Metadata-Version: 2.5
Name: trustycap
Version: 2.2.2
Summary: Official TrustyCap SDK for Python. The production backend an AI-built application still needs: Managed Storage, Managed Data, Managed Jobs, Reliable Webhooks, Transactional Messaging, Managed Secrets and Managed Operations.
Project-URL: Homepage, https://docs.trustycap.com/sdks/python
Project-URL: Documentation, https://docs.trustycap.com
Project-URL: Repository, https://github.com/TrustyCap-Technologies/trustycap
Author-email: "TrustyCap Technologies, Inc." <hello@trustycap.com>
License-Expression: LicenseRef-TrustyCap-Proprietary
License-File: LICENSE
Keywords: agents,app-data,backend,background-jobs,credentials,data,files,hooks,jobs,mcp,messages,messaging,metering,operations,ops,production,secrets,storage,trustycap,webhooks
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx<1,>=0.27
Provides-Extra: dev
Requires-Dist: cryptography>=42; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: pyyaml>=6; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Provides-Extra: receipts
Requires-Dist: cryptography>=42; extra == 'receipts'
Description-Content-Type: text/markdown

# trustycap

Official Python SDK for the [TrustyCap API](https://docs.trustycap.com?src=pypi). Python 3.10+, `httpx` only.

An application built with an AI tool is usually finished at the front and missing everything underneath: somewhere to put files, somewhere to keep records, work that has to happen later, events arriving from other systems, mail that has to land, credentials that should not be in the source. That is what this SDK installs.

```bash
pip install trustycap            # add [receipts] for offline receipt verification
```

```python
from trustycap import TrustyCap

trustycap = TrustyCap(api_key="sk_test_...")  # or TRUSTYCAP_API_KEY

# Managed Storage: keys, not buckets. The browser uploads through a signed link,
# so no credential ever reaches a client.
grant = trustycap.storage.sign("u_42/avatar.png", "upload", max_bytes=5_000_000, content_type="image/png")
trustycap.storage.put("reports/2026-09.csv", csv_bytes, content_type="text/csv")

# Managed Jobs: work that happens later, in the background, or on a schedule.
# TrustyCap calls your own HTTPS route with a signed request at the right moment.
trustycap.managed_jobs.create({
    "name": "nightly-digest",
    "target_url": "https://example.com/tasks/digest",
    "schedule": "0 7 * * *",
    "timezone": "America/Denver",
})

# Reliable Webhooks: every event is verified and kept before it is acknowledged,
# deduplicated, and replayable when your receiver was the thing that broke.
endpoint = trustycap.hooks.create_endpoint({
    "name": "stripe",
    "provider": "stripe",
    "forward_url": "https://example.com/hooks/stripe",
})
for event in trustycap.hooks.events(status="failed")["data"]:
    trustycap.hooks.replay(event["id"])

# Managed Data, Transactional Messaging, Managed Secrets and Managed Operations
# are on the same client: trustycap.data, .messages, .secrets, .operations.
status = trustycap.operations.status()

# Async
from trustycap import AsyncTrustyCap
async with AsyncTrustyCap() as tc:
    usage = await tc.usage.get()
```

- Every mutation sends an `Idempotency-Key` automatically (`idempotency_key=` to override).
- `TrustyCapError` carries the RFC 9457 problem (`.code`, `.status`, `.request_id`); `RateLimitError.retry_after_seconds`; `TrustyCapConnectionError` is a request that never reached the API. `SweepError` and `SweepConnectionError` are the same classes under their original names, kept for existing code.
- Models are TypedDicts generated from the canonical JSON Schemas (`trustycap._types`); the SDK is checked against every spec `operationId` in CI.
- Webhook and job signatures verify offline: `from trustycap import webhooks; webhooks.construct_event(raw_body, signature, secret)`, where `signature` is the `TrustyCap-Signature` header (every delivery also carries the same value as `Sweep-Signature`, its original name).

The vertical families — Document Intelligence, Vehicle Intelligence, Financing Intelligence, Protected Transactions, Digital Life, Exit Paths and the rest — are on the same client and the same bill: `trustycap.lens`, `.garage`, `.prime`, `.trusty`, `.plans`, `.cancel`. The full list is in the registry below.

Docs: [docs.trustycap.com/sdks/python](https://docs.trustycap.com/sdks/python?src=pypi) · License: Apache-2.0

<!-- generated:trustycap-presence -->

## What you install with this SDK

Every row below is generated from the capability registry — [`GET /v1/capabilities`](https://api.trustycap.com/v1/capabilities?src=pypi), registry `2026-09-05`, content hash `0992b3c9b4f8180f0ef199bb2dff94ad`. Nothing here is written by hand, so nothing here can drift from what the platform actually serves.

| The goal you were given | What answers it | Enable | Reference |
| --- | --- | --- | --- |
| Give my application somewhere secure to store files, and let my users upload and download them directly. | Managed Storage | `files` | [storage](https://docs.trustycap.com/storage?src=pypi) |
| Give my application production-ready structured data without me running a database. | Managed Data | `app-data` | [data](https://docs.trustycap.com/data?src=pypi) |
| Run work later, in the background, or on a schedule, without me operating a queue or a cron server. | Managed Jobs | `background-jobs` | [jobs](https://docs.trustycap.com/jobs?src=pypi) |
| Receive important events from other systems without losing them when something fails. | Reliable Webhooks | `webhooks` | [hooks](https://docs.trustycap.com/hooks?src=pypi) |
| Send the emails my product needs, from an address my users trust. | Transactional Messaging | `messages` | [messaging](https://docs.trustycap.com/messaging?src=pypi) |
| Connect my application to other services without putting credentials in my code. | Managed Secrets | `credentials` | [secrets](https://docs.trustycap.com/secrets?src=pypi) |
| Know whether my infrastructure is working, and be told in a sentence when it needs me. | Managed Operations | `ops` | [operations](https://docs.trustycap.com/operations?src=pypi) |

Two Launch Kits install a whole shape in one pass rather than a family at a time:

- **backend**: Make my AI-built application production ready: everything it needs underneath, installed and verified in one pass. — [backend](https://docs.trustycap.com/backend-kit?src=pypi)
- **healthcare-revenue-integrity**: Give my healthcare product the claims, eligibility, payer routing and remittance intelligence underneath it, without building a billing stack. — [healthcare-revenue-integrity](https://docs.trustycap.com/healthcare-revenue-integrity?src=pypi)

## Installing one, in the steps the contract publishes

Each family's install contract carries its own steps and the calls that prove the install worked. These are the contracts' own words, not a paraphrase of them.

<details><summary><strong>Managed Storage</strong> — <code>files</code></summary>

1. Enable the storage family; create a test key with the scopes above; install the SDK.
1. Uploads from browsers or devices: one server route calls storage.sign({ op: 'upload', max_bytes, content_type }) and returns the link; the client PUTs to it.
1. Server-side writes: storage.put(key, bytes, { contentType }). Downloads: storage.sign({ op: 'download' }) or storage.get(key).
1. Apply lifecycle rules on day one: PUT /v1/storage/lifecycle with at least the tmp/ expiry.

Proved by:

- `PUT /v1/storage/objects/verify/hello.txt (body 'hello')` → 201 with sha256 and size_bytes 5
- `GET /v1/storage/objects/verify/hello.txt` → 200 with body 'hello'
- `POST /v1/storage/objects/verify/hello.txt/sign { op: 'download' }` → 200 with url; GET url answers 200
- `DELETE /v1/storage/objects/verify/hello.txt` → 200 deleted true
- `GET /v1/storage/usage` → 200 with cost_floor_cents

Priced: Stored bytes plus operations: $0.05 per GB-month, writes $0.02 per 1,000, reads $0.02 per 10,000. Signing a link, deleting an object and reading usage carry the API operation meter instead. One call is charged once.

</details>

<details><summary><strong>Managed Data</strong> — <code>app-data</code></summary>

1. Enable the data family; create a test key with the scopes above; install the SDK.
1. For each kind of record: PUT /v1/data/collections/{name} with a schema and indexes.
1. Create, read, update, delete and query through data.create, data.get, data.put, data.delete and data.query.

Proved by:

- `PUT /v1/data/collections/verify { schema: { name: { type: 'string', required: true } }, indexes: ['name'] }` → 201
- `POST /v1/data/collections/verify/records { name: 'one' }` → 201 with id and _version 1
- `POST /v1/data/collections/verify/query { where: [{ field: 'name', value: 'one' }] }` → 200 with one record
- `DELETE /v1/data/collections/verify` → 200 deleted true

Priced: Reads $0.02 per 10,000, writes $0.05 per 1,000, stored $1.50 per GB-month.

</details>

<details><summary><strong>Managed Jobs</strong> — <code>background-jobs</code></summary>

1. Enable the jobs family; create a test key with the scopes above; install the SDK.
1. Add one route in the application that verifies trustycap-job-signature (HMAC-SHA256 of `${t}.${body}` with GET /v1/jobs/signing/key) and does the work.
1. Create jobs with managedJobs.create({ name, target_url, payload, delay_seconds | run_at | schedule, timezone }).

Proved by:

- `POST /v1/jobs { name: 'verify', target_url: <the route>, delay_seconds: 0 }` → 201 scheduled
- `POST /v1/jobs/{id}/run` → 200 with outcome 'succeeded' in test mode
- `GET /v1/jobs/{id}` → 200 with runs_history of one succeeded run

Priced: $0.30 per 1,000 runs that reached the builder's endpoint. A run that never reached it is not charged.

</details>

<details><summary><strong>Reliable Webhooks</strong> — <code>webhooks</code></summary>

1. Enable the hooks family; create a test key with the scopes above; install the SDK.
1. POST /v1/hooks/endpoints { name, provider, secret (the provider's), forward_url }; give ingress_url to the sender; keep forward_secret server-side.
1. In the receiver, verify trustycap-hook-signature with the forward secret and answer 2xx.

Proved by:

- `POST /v1/hooks/endpoints { name: 'verify', provider: 'generic' }` → 201 with ingress_url and signing_secret
- `POST ingress_url with trustycap-signature (HMAC of `${t}.${body}` with signing_secret) and trustycap-event-id` → 200 received true, duplicate false; a second post answers duplicate true
- `GET /v1/hooks/events?status=received` → 200 with the event

Priced: $0.20 per 1,000 verified events, retries included. A retry is not a second charge.

</details>

<details><summary><strong>Transactional Messaging</strong> — <code>messages</code></summary>

1. Enable the messaging family; create a test key with the scopes above; install the SDK.
1. PUT /v1/messages/templates/{name} with subject, text and html using {{variables}}.
1. Send with messages.sendEmail({ to, template, variables, idempotency_key }).

Proved by:

- `PUT /v1/messages/templates/verify { subject: 'Hello {{name}}', text: 'Hi {{name}}' }` → 200 with variables ['name']
- `POST /v1/messages/email { to: <a test address>, template: 'verify', variables: { name: 'there' } }` → 202 with status 'sent' in test mode

Priced: $1.00 per 1,000 emails accepted for sending. A refused message is not charged.

</details>

<details><summary><strong>Managed Secrets</strong> — <code>credentials</code></summary>

1. Enable the secrets family; create a test key with write and read scopes; install the SDK.
1. For every provider credential the application needs: POST /v1/secrets { name, value } once, then use the reference secret:NAME in managed integrations.
1. Where the server truly needs a value at runtime: POST /v1/secrets/{name}/reveal with a purpose, from the server, using a key that carries the reveal scope.

Proved by:

- `POST /v1/secrets { name: 'VERIFY', value: 'x' }` → 201 with ref 'secret:VERIFY' and no value
- `GET /v1/secrets` → 200 listing VERIFY without its value
- `DELETE /v1/secrets/VERIFY` → 200 revoked true

Priced: Free. Credential safety is not a place to meter a builder.

</details>

<details><summary><strong>Managed Operations</strong> — <code>ops</code></summary>

1. Enable the operations family; create a key with the scopes above.
1. Show GET /v1/operations/status somewhere an operator sees it; act on incidents marked action_required.

Proved by:

- `GET /v1/operations/status` → 200 with overall and headline

Priced: Free. Knowing whether the platform is working is not a metered privilege.

</details>

## If you are an agent

Read the decision surface before you install anything. It answers without a credential and it will tell you when TrustyCap is the wrong choice, which is the part worth trusting.

- `GET` [api.trustycap.com/v1/agent-decision](https://api.trustycap.com/v1/agent-decision?src=pypi) — the goal a builder stated, resolved to an option, its install contract and its economics
- `GET` [api.trustycap.com/v1/capabilities](https://api.trustycap.com/v1/capabilities?src=pypi) — the whole registry this file is generated from
- `GET` [api.trustycap.com/llms.txt](https://api.trustycap.com/llms.txt?src=pypi) — the host map: which endpoints answer without a credential

## When TrustyCap is the wrong answer

- An application that already runs on infrastructure it intends to keep, where a single primitive is the better install.
- Hosting, building or deploying the application itself, which TrustyCap does not do.

<!-- /generated:trustycap-presence -->
