Metadata-Version: 2.5
Name: royal-vendor-sdk
Version: 0.1.0
Summary: Royal Python clients for curated Encompass, PanTerra, and Paylocity APIs
License-Expression: Apache-2.0
Requires-Python: >=3.11
Requires-Dist: attrs>=22.2.0
Requires-Dist: httpx<0.29.0,>=0.27.0
Description-Content-Type: text/markdown

# Royal Vendor SDK for Python

Typed sync and async access to Royal's curated Encompass, PanTerra, and
Paylocity API surfaces. Import the vendor you need directly:

```python
from royal_vendor_sdk.encompass import EncompassClient, LoanPipelineQueryRequest

with EncompassClient(access_token) as client:
    result = client.query_pipeline(
        LoanPipelineQueryRequest(fields=["Loan.LoanNumber"]),
        limit=100,
    )
```

All calls return `ApiResult[T]` (`royal_vendor_sdk.core`), and matching
operations are available on each vendor's `*AsyncClient`. Generated transport
code remains internal under each vendor's `_generated` subpackage;
applications should use the stable clients.

## royal_vendor_sdk.encompass

The stable facades cover every operation exposed by the Royal .NET Encompass
client: loans, pipeline and reports, fields and locks, milestones and free
roles, schemas, organizations, company settings, users, custom data objects,
eFolder, Encompass Docs, and administrative batch updates.

### Authentication

Three token helpers cover Encompass's supported grants, each returning
`ApiResult[OAuthAccessToken]` (sync + `_async` variants of each):

- `request_service_token` -- `grant_type=client_credentials`. Restricted to
  ISV partners registered as Encompass API Users.
- `request_user_service_token` -- `grant_type=password` (resource owner
  password credentials). Lenders must use this grant instead of
  `client_credentials`; pass a plain Encompass user name and the SDK
  qualifies it as `{username}@encompass:{instance_id}`.
- `request_impersonation_token` -- exchanges an already-issued access token
  for one acting as another Encompass user (`urn:ietf:params:oauth:grant-
  type:token-exchange`). Super Administrators may impersonate any user; API
  Users authenticated with the password grant may impersonate users at or
  below their own level.

```python
from royal_vendor_sdk.encompass import (
    request_user_service_token,
    request_impersonation_token,
)

token = request_user_service_token(
    client_id=client_id,
    client_secret=client_secret,
    instance_id=instance_id,
    username="service.user",
    password=password,
)

impersonated = request_impersonation_token(
    client_id=client_id,
    client_secret=client_secret,
    actor_token=token.value.access_token,
    subject_user_id="target-encompass-user-id",
)
```

## royal_vendor_sdk.panterra

Typed sync and async access to the curated PanTerra Streams API. The
specification prefers v2 operations and retains v1 operations only where the
current vendor surface has no equivalent.

```python
from royal_vendor_sdk.panterra import PanTerraClient

with PanTerraClient(access_token) as client:
    result = client.list_call_detail_records(account_id=12345)
```

The facade includes account and user CDRs, agents, groups, and recordings,
with a matching `PanTerraAsyncClient`. The complete curated surface is
available through `client.generated_client` and
`royal_vendor_sdk.panterra._generated.api`.

## royal_vendor_sdk.paylocity

Typed sync and async access to the employee and custom-field operations
already supported by the stable Royal .NET Paylocity SDK.

```python
from royal_vendor_sdk.paylocity import PaylocityClient

with PaylocityClient(access_token) as client:
    result = client.list_employees(company_id="company-id", page_size=100)
```

The facade supports listing, reading, creating, and updating employees plus
both custom-field reads. `PaylocityAsyncClient` provides the same surface
asynchronously.
