Metadata-Version: 2.4
Name: actus-connector-sdk
Version: 0.0.1b6
Summary: Build and run Actus connectors with typed declarations, isolated credentials, and trusted clients
License-Expression: Apache-2.0
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic<3,>=2.12.4
Requires-Dist: packaging<27,>=24
Requires-Dist: aiosqlite<0.22,>=0.21
Requires-Dist: cryptography<51,>=50.0.2
Requires-Dist: jsonschema<5,>=4.26
Requires-Dist: httpx<0.29,>=0.28.1
Requires-Dist: PyJWT<3,>=2.10.1
Requires-Dist: fastapi<1,>=0.115
Provides-Extra: build
Requires-Dist: build<2,>=1.2; extra == "build"
Provides-Extra: serve
Requires-Dist: uvicorn<0.42,>=0.41; extra == "serve"
Dynamic: license-file

# Actus Connector SDK

Python SDK for building and running Actus connector applications.

Version `0.0.1b6` is a beta release. Python 3.12 or later is required.
Application versions are independent of SDK versions. During beta, pin the SDK
version explicitly; compatibility across beta releases is not guaranteed.

## Changes in 0.0.1b6

OAuth callback URLs explicitly support HTTP or HTTPS independently of listener and
Runtime transport. Callback URLs retain their exact configured value and transaction
binding. The development callback listener uses the URL's scheme on the configured
port: HTTP does not read TLS files, while HTTPS still validates its certificate and key.
State, PKCE, signed permits, ownership checks and cleanup remain unchanged. Provider
authorization, token and revocation endpoints retain their existing HTTPS requirement.
Platform callbacks can share the Backend API entrypoint without an extra callback port.
Consumer dependency upgrades remain separate and wait for mirror synchronization and
explicit authorization; publishing this SDK does not change installed applications.

## Previous changes in 0.0.1b5

Listeners default to HTTPS and require certificates; explicit HTTP works on configured
IP addresses without TLS files. Client URLs select HTTP/HTTPS without fallback, with
the same signed permits and installation permissions. OAuth endpoint and callback
HTTPS policy remains separate. Set `listen.scheme` explicitly to `http` for cleartext
listeners, including protected loopback listeners; keep `https` for TLS listeners.
Existing application packages must be rebuilt for the new beta SDK requirement.
Platform consumers wait for mirror synchronization and an explicit dependency upgrade.

## Previous changes in 0.0.1b4

- CLI builds default to verified installed SDK material and a project-local `dist/` output.
  Safe rebuilds replace matching packages atomically; `--no-overwrite` preserves them.
  Explicit source directories, actionable errors, `--version`, interactive auth selection
  and generated/default development settings simplify the local workflow.
- `FormAuth` validates flat multi-field inputs and explicitly converts them into
  encrypted credentials through `FormAuthResult`.
- Form authorization reuses connection ownership, transaction handling, restart,
  reauthorization and disconnect; local development supports hidden secret inputs.
- `OAuth2AuthorizationCode` adds initial authorization with state, PKCE S256,
  bounded token exchange, encrypted temporary context and a development HTTPS callback.
- OAuth credentials refresh on invocation when their known expiry is reached, with
  connection locks, durable recovery markers and revision-checked token rotation.
  Ambiguous refreshes require reauthorization.
- OAuth disconnect can attempt configured token revocation once after committing
  local removal. Independent, non-sensitive outcomes remain queryable; failures
  never restore credentials or enqueue retries. Production platform callbacks and
  result presentation belong to the integrating platform.

FormAuth, OAuth and the simplified CLI were introduced in 0.0.1b4. Upgrading an SDK
package does not upgrade existing application packages or platform installations.

## Previous changes in 0.0.1b3

- Consume bounded HTTP status, headers, empty responses and SSE within the owned request.
- Preserve deadlines, response ownership and cleanup for custom protocol consumers.
- Report `OperationRejected` as a definite failure only when the application confirms
  no business effects; ambiguous writes remain uncertain.

## Previous changes in 0.0.1b2

- Preserve the primary client failure when response or client cleanup also fails.
- Report observed cleanup failures through `ClientError.cleanup_failed` and cancellation.
- Keep cleanup ownership through repeated cancellation without retrying uncertain writes.

## Installation

```bash
python -m pip install --index-url https://pypi.org/simple \
  'actus-connector-sdk==0.0.1b6'
```

For application building and serving:

```bash
python -m pip install --index-url https://pypi.org/simple \
  'actus-connector-sdk[build,serve]==0.0.1b6'
```

Use a new isolated environment. Platform consumers using the Tencent mirror must
wait for synchronization and verify artifact digests before upgrading; do not
automatically fall back to another index.
The distribution name is `actus-connector-sdk`; the Python import is `connector_sdk`.

## Capabilities

- Typed application, configuration, operation and resource declarations.
- Static Manifest generation and declaration consistency checks.
- Per-installation SQLite state, encrypted credentials and connection ownership.
- NoAuth, API Key, FormAuth and OAuth authorization, connection maintenance and JSON operations.
- Bounded HTTP requests, deadlines, cancellation and lifecycle cleanup.
- Signed platform permits and a public `ConnectorClient`.
- CLI commands: `init`, `check`, `build`, `serve` and `dev`.

This beta does not provide file streaming. Production platform
routing and permit issuance belong to the integrating platform, not to the SDK.

## Start an application

```bash
connector init --help
connector check --help
connector build --help
connector serve --help
connector dev --help
```

Declare the SDK dependency in your application's `pyproject.toml`:

```toml
[project]
name = "example-connector"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = ["actus-connector-sdk==0.0.1b6"]
```

With the SDK build extra installed, run `connector build` in the application directory.
It writes a checked application package to the project's `dist/` directory without requiring
the application to be installed first. The CLI prepares a temporary verification wheel from the actual
installed SDK after checking its complete RECORD and content. This is not an original release
artifact. Local candidates are not replaced by same-version registry packages; optional
`--sdk-wheel` material must match the running SDK's content, not just its version.
No sibling source checkout or platform environment file is required.
Formal consumer upgrades wait for the
Tencent mirror's wheel and sdist to match the published artifact digests.

Run `connector build --help` for the project and output arguments. Local `dev`
creates its own development identity and HTTPS configuration; these credentials
are for local testing and are not production platform credentials.

The source distribution includes `README.md` with detailed APIs, protocol
contracts, lifecycle semantics and application examples. Internal development
notes there describe the source checkout and may differ from this published
package's distribution status.

## License

Apache License 2.0. See `LICENSE` included in the distribution.
