Metadata-Version: 2.4
Name: faximus-sdk
Version: 0.1.0rc5
Summary: Candidate typed Faximus customer API SDK with bounded safe transport
License-Expression: MIT
Project-URL: Source, https://github.com/Faximus-LLC/faximus-api
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
License-File: DEPENDENCY-INVENTORY.v1.json
Requires-Dist: pydantic==2.12.5
Requires-Dist: urllib3==2.8.0
Requires-Dist: python-dateutil==2.9.0.post0
Requires-Dist: typing-extensions==4.15.0
Dynamic: license-file

# Faximus SDK candidate

Release owner: Faximus LLC. The rc.4 packages are published under the verified
`@faximus/sdk` npm and `faximus-sdk` PyPI namespaces. Each later source candidate
requires its own qualification and direct archive download verification before
registry publication. Prior qualified rc.4 packages and archives remain available
unchanged; candidate source is not evidence of publication or customer acceptance.

Install an explicitly qualified version, or deliberately select the npm prerelease
channel after checking its current version:

```sh
npm install --save-exact '@faximus/sdk@<qualified-version>'
npm install '@faximus/sdk@next'
python3 -m pip install 'faximus-sdk==<qualified-version>'
```

The `next` channel is mutable; pinned versions provide repeatable installation.
Registry namespace ownership is verified separately from per-version artifact
qualification. The source repository remains private.

TypeScript supports Node 22; Python supports Python 3.11+. Qualified runtime versions are recorded with each candidate.

Default execution fails with `test_mode_unavailable` until an explicit test credential mode and fresh, exact schema106 native readiness input are supplied. This candidate includes generated fixture/scenario helpers; see `docs/product/developer-sdk-native-test.md` in the source repository. Controlled fixtures explicitly select `execution="fixture"` and a loopback receiver. Live customer use explicitly selects `execution="live"`; real fax sends and account usage apply. Historical sandbox/nonprod key labels do not prove test isolation.

Use prepared fax intents for exact idempotency key/body reuse and explicit acceptance reconciliation. Mutations are never automatically retried. Read retries, cursors and polling are bounded; cancellation and timeouts terminate work. Unknown, partial or unconfirmed delivery never triggers a resend. API keys cannot manage keys; session/provider operations fail locally.

Generated models describe the source OpenAPI and are accessible through the models export/subpackage. Generated API mappings are reference material; the thin wrapper is the supported safe transport. OAS 3.1 generator support is beta. Runtime schema validation remains authoritative; generated types alone do not prove endpoint parity.

Verify exact webhook raw bytes before parsing, require the signed payload eventId, compare an optional event-ID header with that signed ID, then atomically deduplicate with your durable event store before effects. A bounded current/retiring secret pair supports rotation; the verifier does not maintain a hidden in-memory production dedupe store.

Release ownership: Faximus LLC. Registry publication requires verified namespace ownership. Publication to the owned archive origin requires qualified artifacts and direct download verification. See the release policy/tooling in `sdk/` for fail-closed publication and readback checks. Consumers should pin this prerelease; additive fields must be tolerated, unknown enums remain unconfirmed and breaking changes require a major version after 1.0. Deprecation must preserve the prior package for migration. Rollback pins the prior qualified package version; public versions are never overwritten or silently deleted.

Webhook timestamp digits are strictly ASCII; the signed eventId is a nonempty valid Unicode scalar string bounded to 128 UTF8 bytes. Native UUID event IDs retain their existing format.

SDK source license: MIT, Copyright (c) 2026 Faximus LLC. Preserve LICENSE and NOTICE when distributing.

Response resource policy: JSON/text SDK responses default to a 4 MiB byte cap, configurable with `maxResponseBytes` (TypeScript) or `max_response_bytes` (Python) from 1 byte through 16 MiB. Both count streamed bytes rather than trusting Content-Length, close/cancel the stream on errors, and retain uncertain acceptance for dispatched mutations. This cap covers metadata and public contract reads; retrieve large fax documents through their qualified short-lived access URLs separately. Node fetch counts decompressed response bytes. Python requests identity encoding and rejects other encodings to avoid unbounded decompression. Python connected header/body/chunk reads are interrupted at the absolute deadline or cancellation; OS DNS resolution and TCP connection establishment before socket registration are outside this interruption guarantee. The pinned urllib3 dialer can make sequential per-address TCP attempts, each using the connect timeout; their cumulative time can exceed max_elapsed. Neither max_elapsed nor cancellation promises a hard total-return deadline during those pre-registration phases. Custom injected transports must honor the supplied deadlines/abort signals; they are test seams, not a bypass of the production resource policy.

Native test candidate: use `createTestDocument`, `completeTestDocument`, `prepareTestFax`, `submitTestFax`, `pollTestFax`, and `cancelTestFax` (Python uses snake_case). The SDK sets `X-Faximus-Mode: test`, binds each idempotent mutation to operation/target/exact body, and denies live-shaped or non-synthetic responses. Readiness is a qualified native configuration input, not proof minted by this SDK. Prior qualified archives remain unchanged.
