spaps 0.5.1__tar.gz → 0.6.2__tar.gz

{spaps-0.5.1 → spaps-0.6.2}/.gitignore

@@ -164,6 +164,7 @@ backup-feb8.sql
 # Local modes/swarm artifacts
 .ntm/
 .skillbox/
+artifacts/openapi-contract/
 MODES_ANALYSIS_PROGRESS.md
 MODES_OF_REASONING_REPORT_AND_ANALYSIS_OF_PROJECT.md
 MODE_OUTPUT_*.md
@@ -200,3 +201,6 @@ refactor/
 
 # bv (beads viewer) local config and caches
 .bv/
+
+# Beads compliance audit dir (managed by /beads-compliance-and-completion-verification skill)
+/beads_compliance_audit/

{spaps-0.5.1 → spaps-0.6.2}/CHANGELOG.md

@@ -6,6 +6,47 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
 
 ## [Unreleased]
 
+## [0.6.2] - 2026-06-16
+
+### Fixed
+
+- Accepted `stream`, `owner_id`, `subject_override`, and `body_override` on `EmailClient.send()` and accepted `stream` on `AsyncEmailClient.send()` so Python consumers can delegate SPAPS email sends without hand-rolling the `/api/email/send` envelope.
+
+### Changed
+
+- Bumped the Python client package metadata to `0.6.2`.
+
+## [0.6.1] - 2026-06-14
+
+### Added
+
+- Added sync `DayrateClient` helpers and sync/async `AppLinksClient` helpers, with high-level `SpapsClient.dayrate`, `SpapsClient.app_links`, and `AsyncSpapsClient.app_links` accessors.
+- Added sync and async `UsersClient.memberships` helpers for listing, inviting/adding, and removing app account users.
+- Added sync and async `EntitlementsClient.project_grants` helpers for granting, revoking, listing, checking, and claiming project access grants.
+
+### Fixed
+
+- Accepted canonical SPAPS password reset request envelopes that return `success`, `data.email`, `data.sent_at`, `request_id`, and `timestamp` without requiring a top-level English `message`.
+- Exposed omitted password reset request messages as `None` instead of an empty string placeholder so apps keep ownership of success copy.
+- Preserved password reset confirmation parsing for canonical envelopes where the success copy lives at `data.message`.
+
+### Changed
+
+- Bumped the Python client package metadata to `0.6.1`; HTMA should consume `spaps>=0.6.1` or the matching unreleased local wheel/source checkout before retrying the reset flow.
+
+## [0.6.0] - 2026-06-13
+
+### Added
+
+- Added sync and async auth helpers for OIDC nonce/sign-in, WebAuthn registration/assertion, TOTP MFA enrollment/verification/disable, and SMS OTP request/verify flows.
+- Added typed MFA challenge responses so token-issuing auth methods can return either tokens or an MFA challenge without storing incomplete credentials.
+
+### Changed
+
+- Bumped the Python client package metadata to `0.6.0`.
+
+## [0.5.1] - 2026-06-04
+
 ### Added
 
 - Added sync and async issue-reporting screenshot attachment helpers for private upload, list, access URL, delete, and attach-by-ID create/update/reply flows.

{spaps-0.5.1 → spaps-0.6.2}/FULL_CHECKLIST.md

@@ -12,7 +12,7 @@
 - [x] Payments: update payment method
 - [x] Payments: Stripe checkout (existing)
 - [x] Payments: Stripe payment intent (existing)
-- [x] Payments: wallet deposit/status (existing)
+- [x] Payments: wallet deposit/status helpers intentionally raise `NotImplementedError` for backend 501 stubs
 - [x] Payments: subscription details/cancel (existing)
 - [x] Payments: crypto invoices (create/get/reconcile)
 - [x] Payments: crypto webhooks signature helper

{spaps-0.5.1 → spaps-0.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spaps
-Version: 0.5.1
+Version: 0.6.2
 Summary: Sweet Potato Authentication & Payment Service Python client
 Project-URL: Homepage, https://api.sweetpotato.dev
 Project-URL: Repository, https://github.com/sweet-potato/spaps
@@ -80,7 +80,7 @@ This package targets Python 3.9+.
 ## Quick Start
 
 ```python
-from spaps_client import SpapsClient
+from spaps_client import MfaRequiredChallenge, SpapsClient
 
 client = SpapsClient(
     base_url="http://localhost:3301",
@@ -88,10 +88,20 @@ client = SpapsClient(
 )
 
 try:
-    tokens = client.auth.sign_in_with_password(
+    login = client.auth.sign_in_with_password(
         email="user@example.com",
         password="correct-horse-battery-staple",
     )
+    if isinstance(login, MfaRequiredChallenge):
+        tokens = client.auth.mfa_verify(
+            challenge_id=login.challenge_id,
+            challenge=login.challenge,
+            code="123456",
+        )
+    else:
+        tokens = login
+
+    bootstrap = client.auth.get_session_context()
     session = client.sessions.get_current_session()
     products = client.payments.list_products(
         category="subscription",
@@ -100,6 +110,7 @@ try:
     )
 
     print(tokens.user.email)
+    print(bootstrap.tier)
     print(session.session_id)
     print(products.total)
 finally:
@@ -133,24 +144,68 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
+## Modern Auth Methods
+
+The auth client exposes the active SPAPS auth routes in both sync and async forms:
+
+```python
+from spaps_client import MfaRequiredChallenge, SpapsClient
+
+client = SpapsClient(base_url="http://localhost:3301", api_key="spaps_test_key")
+
+methods = client.auth.list_methods()
+print([item.method for item in methods.methods if item.enabled])
+
+oidc = client.auth.oidc_nonce()
+login = client.auth.oidc_sign_in(
+    provider="google",
+    id_token="provider-id-token",
+    challenge_id=oidc.challenge_id,
+)
+
+if isinstance(login, MfaRequiredChallenge):
+    login = client.auth.mfa_verify(
+        challenge_id=login.challenge_id,
+        challenge=login.challenge,
+        recovery_code="recovery-code",
+    )
+```
+
+TOTP management and passkey registration are authenticated operations and use stored tokens unless you pass `access_token` explicitly:
+
+```python
+enrollment = client.auth.mfa_totp_enroll()
+activation = client.auth.mfa_totp_activate(code="123456")
+options = client.auth.webauthn_register_options()
+credential = client.auth.webauthn_register_verify(
+    challenge_id=options.challenge_id,
+    credential={"id": "browser-produced-credential"},
+)
+```
+
+WebAuthn helpers intentionally pass browser-produced credential JSON through to the API; the Python client does not emulate authenticators or perform CTAP operations.
+
 ## Core Surface
 
 ### High-Level Clients
 
 | Client | Best for |
 | --- | --- |
-| `SpapsClient` | Sync auth, sessions, payments, usage, whitelist, secure messages, issue reporting, marketing, metrics, skill evals, and support telemetry |
-| `AsyncSpapsClient` | Async auth, sessions, payments, usage, whitelist, secure messages, issue reporting, metrics, entitlements, skill evals, dayrate, and users |
+| `SpapsClient` | Sync auth, sessions, payments, usage, access decisions, capability graph inspection, whitelist, secure messages, issue reporting, marketing, metrics, app links, dayrate, skill evals, and support telemetry |
+| `AsyncSpapsClient` | Async auth, sessions, payments, usage, whitelist, secure messages, issue reporting, metrics, entitlements, app links, dayrate, skill evals, and users |
 
 ### Standalone Helpers
 
 | Helper | Purpose |
 | --- | --- |
-| `EntitlementsClient` / `AsyncEntitlementsClient` | Resource entitlements, purchase history, manual grants, and revokes |
+| `EntitlementsClient` / `AsyncEntitlementsClient` | Resource entitlements, purchase history, manual grants/revokes, and project grants |
 | `UsageClient` / `AsyncUsageClient` | Secret-key usage authorization and immutable usage recording |
+| `CapabilityClient` | Access decisions, action preparation, decision traces, graph inspection, and contract discovery |
 | `EmailClient` / `AsyncEmailClient` | Template lookup, preview, and send flows |
-| `UsersClient` / `AsyncUsersClient` | Batch user and email lookups |
+| `UsersClient` / `AsyncUsersClient` | Batch user/email lookups and app membership administration |
 | `MarketingClient` | Browser-safe marketing event emission and server-side experiment results |
+| `AppLinksClient` / `AsyncAppLinksClient` | Authenticated short-link creation/update and public link resolution |
+| `DayrateClient` / `AsyncDayrateClient` | Availability, booking, cancellation, x402 booking holds, and admin booking reads |
 | `DeviceFlowClient` | Device-code login workflows |
 | `PermissionChecker` | Role and admin convenience checks |
 | `verify_spaps_webhook` | Signature verification for incoming SPAPS webhooks |
@@ -184,6 +239,76 @@ Common parameters:
 
 ## Common Flows
 
+### Agent Access Decisions
+
+`client.access.check_access(...)` returns a typed decision for both allowed and
+denied outcomes. A blocked action is not an exception; inspect `allowed`,
+`outcome`, and `next_actions`.
+
+```python
+from spaps_client import AccessDecisionRequest, CapabilityError, SpapsClient
+
+client = SpapsClient(
+    base_url="https://api.example.test",
+    api_key="spaps_sec_example",
+)
+client.set_tokens(access_token="admin-access-token")
+
+try:
+    decision = client.access.check_access(
+        AccessDecisionRequest.model_validate(
+            {
+                "actor": {"actor_type": "user", "actor_ref": "user_123"},
+                "action": "checkout.create",
+                "resource": {"resource_type": "product", "resource_ref": "dayrate"},
+                "controls": {"entitlement_key": "bookme_paid"},
+            }
+        )
+    )
+
+    if not decision.allowed:
+        print(decision.outcome, decision.next_actions)
+
+    prepared = client.access.prepare_action(
+        {
+            "access": {
+                "actor": {"actor_ref": "admin_123"},
+                "action": "admin.delete_user",
+                "resource": {"resource_type": "user", "resource_ref": "user_123"},
+            },
+            "include_command_templates": True,
+            "environment": "production",
+        }
+    )
+    print(prepared.status, prepared.execution.operator_gate_required)
+
+    contract = client.contract.get_contract()
+    refresh = client.graph.refresh_graph(correlation_id="local-refresh")
+    nodes = client.graph.list_graph_nodes(node_type="x402_resource", q="dayrate")
+    explanation = client.access.explain_decision(decision.decision_trace_id)
+    print(contract.version, refresh.status, refresh.diagnostics.phase2_gate.recommendation if refresh.diagnostics.phase2_gate else None)
+    print(nodes.projection.projection_status if nodes.projection else None, explanation.graph_node_keys)
+except CapabilityError as exc:
+    print(exc.status_code, exc.code, exc.request_id, exc.diagnostics, exc.remediations)
+finally:
+    client.close()
+```
+
+`client.contract.get_contract()` includes graph vocabulary fields:
+`graph_node_types`, `graph_edge_types`, `graph_source_domains`, and
+`source_domain_notes`. Use them before filtering graph nodes by stable v1 types
+such as `wallet`, `api_key`, `role`, and `approver`.
+
+`CapabilityError` exposes both Python-native names (`status_code`,
+`error_code`, `request_id`) and parity aliases (`status`, `code`). Diagnostics
+and remediations preserve server-provided `details` fields.
+
+`operator-gated` is compatibility/descriptive input when a client supplies it;
+it does not authorize mutation command templates. SPAPS returns mutation
+command templates only when the request has a server-recognized non-publishable
+key and an authenticated admin/operator user context. Publishable callers
+cannot self-attest the gate.
+
 ### Magic Links and Password Reset
 
 ```python
@@ -196,15 +321,36 @@ client = SpapsClient(
 
 try:
     client.auth.send_magic_link(email="user@example.com")
-    client.auth.request_password_reset(email="user@example.com")
-    client.auth.confirm_password_reset(
+    reset_request = client.auth.request_password_reset(email="user@example.com")
+    reset_confirm = client.auth.confirm_password_reset(
         token="reset-token-from-email",
         new_password="Sup3rStrong!",
     )
+    print(reset_request.email, reset_request.sent_at, reset_confirm.message)
 finally:
     client.close()
 ```
 
+Password reset responses use the standard SPAPS success envelope with top-level
+`success`, `data`, `request_id`, and `timestamp`. The Python client returns the
+nested `data` payload: reset requests expose `email` and `sent_at`, while reset
+confirmation exposes the nested `message`. A top-level English `message` is not
+canonical and should not drive UI copy. Prefer app-owned success copy, or map
+future nested `data.message_key`/`data.status` values in your app.
+
+#### Downstream Adoption
+
+HTMA and future SPAPS consumers should use `spaps>=0.6.2` for password reset
+flows and stream-aware email sends. Until `0.6.2` is published to PyPI, consume
+a local wheel or source checkout from the Sweet Potato commit that carries the
+`0.6.2` changelog entry.
+
+Release execution is intentionally separate from this handoff: run the manual
+`Publish Python Client` workflow when ready so release automation builds the
+already-bumped package metadata and publishes to PyPI. Do not use
+`npm run publish:python-client`, deploy SPAPS, or publish the package as part of
+a consumer-only adoption check.
+
 ### Authenticated Stripe Checkout
 
 `create_checkout_session` is the convenience path for authenticated checkout.
@@ -286,6 +432,57 @@ For dashboard and policy views, use `client.usage.get_features()`,
 `client.usage.get_status(...)`, and `client.usage.get_history(...)` from the
 same trusted backend context.
 
+### Account Memberships and Project Grants
+
+Use these helpers from a trusted backend with a secret SPAPS key. Admin mutation
+helpers also require an admin access token; do not call membership invitation,
+project grant, or project revoke helpers from browser code.
+
+```python
+from spaps_client import EntitlementsClient, UsersClient
+
+admin_token = "admin-access-token"
+
+users = UsersClient(
+    base_url="https://api.example.test",
+    api_key="spaps_sec_example",
+    access_token=admin_token,
+)
+entitlements = EntitlementsClient(
+    base_url="https://api.example.test",
+    api_key="spaps_sec_example",
+    access_token=admin_token,
+)
+
+try:
+    users.memberships.add_account_user(
+        email="teammate@example.com",
+        capabilities={"projects": ["project_123"]},
+        metadata={"invited_by": "admin@example.com"},
+    )
+    entitlements.project_grants.grant_user(
+        project_id="project_123",
+        entitlement_key="pds.project.viewer",
+        email="teammate@example.com",
+        reason="Project teammate invite",
+    )
+
+    project_users = entitlements.project_grants.list_project_users(
+        "project_123",
+        entitlement_key="pds.project.viewer",
+    )
+    user_projects = entitlements.project_grants.list_user_projects("user_123")
+    access = entitlements.project_grants.check_access(
+        project_id="project_123",
+        entitlement_key="pds.project.viewer",
+        user_id="user_123",
+    )
+    print(project_users.count, user_projects.count, access.has_access)
+finally:
+    users.close()
+    entitlements.close()
+```
+
 ### Marketing Events
 
 Use `client.marketing.emit_event(...)` with a publishable key to record anonymous
@@ -589,7 +786,7 @@ It can. Pass `RetryConfig` if you want retry and backoff behavior.
 ## Metadata
 
 - `package_name`: `spaps`
-- `latest_version`: `0.5.0`
+- `latest_version`: `0.6.2`
 - `minimum_runtime`: `Python >=3.9`
 - `api_base_url`: `https://api.sweetpotato.dev`
 

{spaps-0.5.1 → spaps-0.6.2}/README.md

@@ -24,7 +24,7 @@ This package targets Python 3.9+.
 ## Quick Start
 
 ```python
-from spaps_client import SpapsClient
+from spaps_client import MfaRequiredChallenge, SpapsClient
 
 client = SpapsClient(
     base_url="http://localhost:3301",
@@ -32,10 +32,20 @@ client = SpapsClient(
 )
 
 try:
-    tokens = client.auth.sign_in_with_password(
+    login = client.auth.sign_in_with_password(
         email="user@example.com",
         password="correct-horse-battery-staple",
     )
+    if isinstance(login, MfaRequiredChallenge):
+        tokens = client.auth.mfa_verify(
+            challenge_id=login.challenge_id,
+            challenge=login.challenge,
+            code="123456",
+        )
+    else:
+        tokens = login
+
+    bootstrap = client.auth.get_session_context()
     session = client.sessions.get_current_session()
     products = client.payments.list_products(
         category="subscription",
@@ -44,6 +54,7 @@ try:
     )
 
     print(tokens.user.email)
+    print(bootstrap.tier)
     print(session.session_id)
     print(products.total)
 finally:
@@ -77,24 +88,68 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
+## Modern Auth Methods
+
+The auth client exposes the active SPAPS auth routes in both sync and async forms:
+
+```python
+from spaps_client import MfaRequiredChallenge, SpapsClient
+
+client = SpapsClient(base_url="http://localhost:3301", api_key="spaps_test_key")
+
+methods = client.auth.list_methods()
+print([item.method for item in methods.methods if item.enabled])
+
+oidc = client.auth.oidc_nonce()
+login = client.auth.oidc_sign_in(
+    provider="google",
+    id_token="provider-id-token",
+    challenge_id=oidc.challenge_id,
+)
+
+if isinstance(login, MfaRequiredChallenge):
+    login = client.auth.mfa_verify(
+        challenge_id=login.challenge_id,
+        challenge=login.challenge,
+        recovery_code="recovery-code",
+    )
+```
+
+TOTP management and passkey registration are authenticated operations and use stored tokens unless you pass `access_token` explicitly:
+
+```python
+enrollment = client.auth.mfa_totp_enroll()
+activation = client.auth.mfa_totp_activate(code="123456")
+options = client.auth.webauthn_register_options()
+credential = client.auth.webauthn_register_verify(
+    challenge_id=options.challenge_id,
+    credential={"id": "browser-produced-credential"},
+)
+```
+
+WebAuthn helpers intentionally pass browser-produced credential JSON through to the API; the Python client does not emulate authenticators or perform CTAP operations.
+
 ## Core Surface
 
 ### High-Level Clients
 
 | Client | Best for |
 | --- | --- |
-| `SpapsClient` | Sync auth, sessions, payments, usage, whitelist, secure messages, issue reporting, marketing, metrics, skill evals, and support telemetry |
-| `AsyncSpapsClient` | Async auth, sessions, payments, usage, whitelist, secure messages, issue reporting, metrics, entitlements, skill evals, dayrate, and users |
+| `SpapsClient` | Sync auth, sessions, payments, usage, access decisions, capability graph inspection, whitelist, secure messages, issue reporting, marketing, metrics, app links, dayrate, skill evals, and support telemetry |
+| `AsyncSpapsClient` | Async auth, sessions, payments, usage, whitelist, secure messages, issue reporting, metrics, entitlements, app links, dayrate, skill evals, and users |
 
 ### Standalone Helpers
 
 | Helper | Purpose |
 | --- | --- |
-| `EntitlementsClient` / `AsyncEntitlementsClient` | Resource entitlements, purchase history, manual grants, and revokes |
+| `EntitlementsClient` / `AsyncEntitlementsClient` | Resource entitlements, purchase history, manual grants/revokes, and project grants |
 | `UsageClient` / `AsyncUsageClient` | Secret-key usage authorization and immutable usage recording |
+| `CapabilityClient` | Access decisions, action preparation, decision traces, graph inspection, and contract discovery |
 | `EmailClient` / `AsyncEmailClient` | Template lookup, preview, and send flows |
-| `UsersClient` / `AsyncUsersClient` | Batch user and email lookups |
+| `UsersClient` / `AsyncUsersClient` | Batch user/email lookups and app membership administration |
 | `MarketingClient` | Browser-safe marketing event emission and server-side experiment results |
+| `AppLinksClient` / `AsyncAppLinksClient` | Authenticated short-link creation/update and public link resolution |
+| `DayrateClient` / `AsyncDayrateClient` | Availability, booking, cancellation, x402 booking holds, and admin booking reads |
 | `DeviceFlowClient` | Device-code login workflows |
 | `PermissionChecker` | Role and admin convenience checks |
 | `verify_spaps_webhook` | Signature verification for incoming SPAPS webhooks |
@@ -128,6 +183,76 @@ Common parameters:
 
 ## Common Flows
 
+### Agent Access Decisions
+
+`client.access.check_access(...)` returns a typed decision for both allowed and
+denied outcomes. A blocked action is not an exception; inspect `allowed`,
+`outcome`, and `next_actions`.
+
+```python
+from spaps_client import AccessDecisionRequest, CapabilityError, SpapsClient
+
+client = SpapsClient(
+    base_url="https://api.example.test",
+    api_key="spaps_sec_example",
+)
+client.set_tokens(access_token="admin-access-token")
+
+try:
+    decision = client.access.check_access(
+        AccessDecisionRequest.model_validate(
+            {
+                "actor": {"actor_type": "user", "actor_ref": "user_123"},
+                "action": "checkout.create",
+                "resource": {"resource_type": "product", "resource_ref": "dayrate"},
+                "controls": {"entitlement_key": "bookme_paid"},
+            }
+        )
+    )
+
+    if not decision.allowed:
+        print(decision.outcome, decision.next_actions)
+
+    prepared = client.access.prepare_action(
+        {
+            "access": {
+                "actor": {"actor_ref": "admin_123"},
+                "action": "admin.delete_user",
+                "resource": {"resource_type": "user", "resource_ref": "user_123"},
+            },
+            "include_command_templates": True,
+            "environment": "production",
+        }
+    )
+    print(prepared.status, prepared.execution.operator_gate_required)
+
+    contract = client.contract.get_contract()
+    refresh = client.graph.refresh_graph(correlation_id="local-refresh")
+    nodes = client.graph.list_graph_nodes(node_type="x402_resource", q="dayrate")
+    explanation = client.access.explain_decision(decision.decision_trace_id)
+    print(contract.version, refresh.status, refresh.diagnostics.phase2_gate.recommendation if refresh.diagnostics.phase2_gate else None)
+    print(nodes.projection.projection_status if nodes.projection else None, explanation.graph_node_keys)
+except CapabilityError as exc:
+    print(exc.status_code, exc.code, exc.request_id, exc.diagnostics, exc.remediations)
+finally:
+    client.close()
+```
+
+`client.contract.get_contract()` includes graph vocabulary fields:
+`graph_node_types`, `graph_edge_types`, `graph_source_domains`, and
+`source_domain_notes`. Use them before filtering graph nodes by stable v1 types
+such as `wallet`, `api_key`, `role`, and `approver`.
+
+`CapabilityError` exposes both Python-native names (`status_code`,
+`error_code`, `request_id`) and parity aliases (`status`, `code`). Diagnostics
+and remediations preserve server-provided `details` fields.
+
+`operator-gated` is compatibility/descriptive input when a client supplies it;
+it does not authorize mutation command templates. SPAPS returns mutation
+command templates only when the request has a server-recognized non-publishable
+key and an authenticated admin/operator user context. Publishable callers
+cannot self-attest the gate.
+
 ### Magic Links and Password Reset
 
 ```python
@@ -140,15 +265,36 @@ client = SpapsClient(
 
 try:
     client.auth.send_magic_link(email="user@example.com")
-    client.auth.request_password_reset(email="user@example.com")
-    client.auth.confirm_password_reset(
+    reset_request = client.auth.request_password_reset(email="user@example.com")
+    reset_confirm = client.auth.confirm_password_reset(
         token="reset-token-from-email",
         new_password="Sup3rStrong!",
     )
+    print(reset_request.email, reset_request.sent_at, reset_confirm.message)
 finally:
     client.close()
 ```
 
+Password reset responses use the standard SPAPS success envelope with top-level
+`success`, `data`, `request_id`, and `timestamp`. The Python client returns the
+nested `data` payload: reset requests expose `email` and `sent_at`, while reset
+confirmation exposes the nested `message`. A top-level English `message` is not
+canonical and should not drive UI copy. Prefer app-owned success copy, or map
+future nested `data.message_key`/`data.status` values in your app.
+
+#### Downstream Adoption
+
+HTMA and future SPAPS consumers should use `spaps>=0.6.2` for password reset
+flows and stream-aware email sends. Until `0.6.2` is published to PyPI, consume
+a local wheel or source checkout from the Sweet Potato commit that carries the
+`0.6.2` changelog entry.
+
+Release execution is intentionally separate from this handoff: run the manual
+`Publish Python Client` workflow when ready so release automation builds the
+already-bumped package metadata and publishes to PyPI. Do not use
+`npm run publish:python-client`, deploy SPAPS, or publish the package as part of
+a consumer-only adoption check.
+
 ### Authenticated Stripe Checkout
 
 `create_checkout_session` is the convenience path for authenticated checkout.
@@ -230,6 +376,57 @@ For dashboard and policy views, use `client.usage.get_features()`,
 `client.usage.get_status(...)`, and `client.usage.get_history(...)` from the
 same trusted backend context.
 
+### Account Memberships and Project Grants
+
+Use these helpers from a trusted backend with a secret SPAPS key. Admin mutation
+helpers also require an admin access token; do not call membership invitation,
+project grant, or project revoke helpers from browser code.
+
+```python
+from spaps_client import EntitlementsClient, UsersClient
+
+admin_token = "admin-access-token"
+
+users = UsersClient(
+    base_url="https://api.example.test",
+    api_key="spaps_sec_example",
+    access_token=admin_token,
+)
+entitlements = EntitlementsClient(
+    base_url="https://api.example.test",
+    api_key="spaps_sec_example",
+    access_token=admin_token,
+)
+
+try:
+    users.memberships.add_account_user(
+        email="teammate@example.com",
+        capabilities={"projects": ["project_123"]},
+        metadata={"invited_by": "admin@example.com"},
+    )
+    entitlements.project_grants.grant_user(
+        project_id="project_123",
+        entitlement_key="pds.project.viewer",
+        email="teammate@example.com",
+        reason="Project teammate invite",
+    )
+
+    project_users = entitlements.project_grants.list_project_users(
+        "project_123",
+        entitlement_key="pds.project.viewer",
+    )
+    user_projects = entitlements.project_grants.list_user_projects("user_123")
+    access = entitlements.project_grants.check_access(
+        project_id="project_123",
+        entitlement_key="pds.project.viewer",
+        user_id="user_123",
+    )
+    print(project_users.count, user_projects.count, access.has_access)
+finally:
+    users.close()
+    entitlements.close()
+```
+
 ### Marketing Events
 
 Use `client.marketing.emit_event(...)` with a publishable key to record anonymous
@@ -533,7 +730,7 @@ It can. Pass `RetryConfig` if you want retry and backoff behavior.
 ## Metadata
 
 - `package_name`: `spaps`
-- `latest_version`: `0.5.0`
+- `latest_version`: `0.6.2`
 - `minimum_runtime`: `Python >=3.9`
 - `api_base_url`: `https://api.sweetpotato.dev`
 

{spaps-0.5.1 → spaps-0.6.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "spaps"
-version = "0.5.1"
+version = "0.6.2"
 description = "Sweet Potato Authentication & Payment Service Python client"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -70,6 +70,10 @@ strict_optional = true
 warn_unused_configs = true
 ignore_missing_imports = true
 
+[[tool.mypy.overrides]]
+module = ["click", "click.*"]
+follow_imports = "skip"
+
 [tool.coverage.run]
 omit = [
   "src/spaps_client/*_async.py",