Metadata-Version: 2.4
Name: viio-sync-api-sdk
Version: 0.2.0
Summary: Async Python SDK for the Viio Sync API
Project-URL: Documentation, https://developers.viio.io/sync-api
Project-URL: Changelog, https://developers.viio.io/sync-api
Author: Viio
License-Expression: MIT
License-File: LICENSE
Keywords: grpc,sdk,sync,viio
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: grpcio<2,>=1.83
Requires-Dist: protobuf<8,>=7.35.1
Description-Content-Type: text/markdown

# Viio Sync API SDK for Python

`viio-sync-api-sdk` contains the generated `viio.sync.v1` protobuf contract and an AsyncIO client for authentication and
explicit sync-batch lifecycle management.

## Install

```shell
python -m pip install viio-sync-api-sdk
```

Python 3.11 and later are supported without an artificial upper minor-version cap. CI validates the minimum version and
the latest stable Python release, so the upper tested version advances automatically.

## Send a batch

```python
from viio_sync_api import SyncApiAuthentication, SyncApiClient, SyncApiClientOptions
from viio_sync_api.v1 import Account, AccountRecords, GenericAccountDetails, SyncRecordsRequest


async def sync_accounts() -> None:
    options = SyncApiClientOptions(
        endpoint="https://sync.example.com",
        authentication=SyncApiAuthentication.api_key("your-api-key"),
    )

    async with SyncApiClient(options) as client:
        batch = await client.start_batch("installation-id")
        try:
            await batch.write(
                SyncRecordsRequest(
                    accounts=AccountRecords(
                        records=[
                            Account(
                                generic=GenericAccountDetails(
                                    id="account-1",
                                    email="person@example.com",
                                )
                            )
                        ]
                    )
                )
            )
            await batch.complete()
        except BaseException:
            await batch.abort()
            raise
```

Each write accepts exactly one typed records wrapper. A present empty wrapper represents an intentional empty snapshot:

```python
await batch.write(SyncRecordsRequest(accounts=AccountRecords()))
```

`SyncApiBatchAlreadyInProgressError` distinguishes an existing sync. Protocol failures raise
`SyncApiProtocolError`. Native `grpc.aio.AioRpcError`, cancellation, and timeout errors remain available for retry
decisions.

The authenticated generated stub is available as `client.grpc_client`. Calls through it bypass batch validation.

`max_receive_message_size` caps individual responses received by this client, while `max_send_message_size` caps
individual requests it sends. The receive limit defaults to 16 MiB to match the .NET SDK; setting either value to
`None` leaves that direction at gRPC's default.

## AWS Lambda

The [Viio developer portal](https://developers.viio.io/sync-api) provides a complete Lambda handler and AWS SAM
template. The handler acquires an application token from Microsoft Entra ID, pages through Microsoft Graph users, maps
each user to `MicrosoftEmployeeDetails`, writes a complete employee snapshot, and completes or aborts the Sync API
batch. The template configures Amazon EventBridge Scheduler to invoke it every night with `cron(0 2 * * ? *)`.

Grant the Entra application the Microsoft Graph `User.Read.All` application permission and supply these Lambda
environment variables from your secret-management system:

- `MICROSOFT_TENANT_ID`
- `MICROSOFT_CLIENT_ID`
- `MICROSOFT_CLIENT_SECRET`
- `VIIO_SYNC_API_ENDPOINT`
- `VIIO_SYNC_API_KEY`
- `VIIO_DIRECT_INTEGRATION_INSTALLATION_ID`

The example creates and closes the client inside each invocation's event loop. This avoids retaining a gRPC AsyncIO
channel across event loops when Lambda reuses a warm execution environment.

`grpcio` contains native code. When creating a Lambda ZIP or layer on another operating system, ask pip for the
matching Linux wheel:

```shell
# x86_64
python -m pip install \
  --platform manylinux2014_x86_64 \
  --implementation cp \
  --python-version 3.11 \
  --only-binary=:all: \
  --target package \
  viio-sync-api-sdk

# arm64
python -m pip install \
  --platform manylinux2014_aarch64 \
  --implementation cp \
  --python-version 3.11 \
  --only-binary=:all: \
  --target package \
  viio-sync-api-sdk
```

Replace `3.11` with the Python version of the target Lambda runtime. The same package can be installed normally in AWS
Lambda Python container images. Full API documentation is available at <https://developers.viio.io/sync-api>.

## Authentication and transport security

External integrations use API keys. Viio-managed callers can supply an asynchronous bearer-token provider.

Sync API endpoints must use HTTPS. HTTP is accepted only for loopback endpoints during development. SDK exception
messages and representations do not include keys or bearer tokens.

## License

MIT
