spaps-sdk 1.12.0 → 1.13.0

package/CHANGELOG.md

@@ -8,6 +8,18 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
 
 ### Added
 
+- Added `whitelist`, `users`, and `supportTelemetry` namespaces so the TypeScript SDK matches consumer-facing Python client domain coverage.
+
+## [1.13.0] - 2026-06-13
+
+### Added
+
+- Added `auth.oidc`, `auth.webauthn`, `auth.mfa`, and `auth.sms` helpers for the backend login-method families, with MFA-required challenge results preserved as typed responses.
+
+## [1.12.0] - 2026-06-12
+
+### Added
+
 - Added browser-safe `entitlements.listCurrentUserProjects()` and `entitlements.checkCurrentUserProjectAccess(...)` helpers for project grant reads.
 
 ## [1.11.0] - 2026-06-08

package/README.md

@@ -23,7 +23,7 @@ This package targets `Node.js >=14`.
 
 | Need | Package gives you |
 | --- | --- |
-| One client for many SPAPS surfaces | `auth`, `payments`, `sessions`, `secureMessages`, `issueReporting`, `appLinks`, `marketing`, `email`, `entitlements`, `usage`, `skillEvals`, `dayrate`, `admin`, and `cfo` namespaces |
+| One client for many SPAPS surfaces | `auth`, `payments`, `sessions`, `secureMessages`, `issueReporting`, `appLinks`, `whitelist`, `users`, `supportTelemetry`, `marketing`, `email`, `entitlements`, `usage`, `access`, `graph`, `contract`, `skillEvals`, `dayrate`, `admin`, and `cfo` namespaces |
 | Local development without extra config | Localhost URLs automatically enable local mode |
 | Browser and server usage | `publishableKey`, `secretKey`, or legacy `apiKey` support |
 | Shared contracts | Re-exports a large slice of `spaps-types` |
@@ -43,14 +43,16 @@ const auth = await spaps.auth.signInWithPassword({
   password: "correct-horse-battery-staple",
 });
 
-const me = await spaps.getUser();
+// Accounts with activated TOTP receive an MFA challenge from /api/auth/login;
+// complete /api/auth/mfa/verify before using token-backed helpers.
+const session = await spaps.getSessionContext();
 const issues = await spaps.issueReporting.list({
   status: "open",
   scope: "mine",
   limit: 20,
 });
 
-console.log(auth.user.id, me.data.email, issues.total);
+console.log(auth.user.id, session.user.email, session.entitlements.length, issues.total);
 ```
 
 Issue-reporting reads are user-scoped in the stock SPAPS API. The SDK accepts `scope: "mine"`
@@ -80,16 +82,22 @@ Relevant environment variables:
 
 | Namespace | Covers |
 | --- | --- |
-| `auth` | Password, wallet, magic-link, refresh, logout, and password-management flows |
+| `auth` | Password, wallet, OIDC, WebAuthn, MFA, SMS, magic-link, refresh, logout, and password-management flows |
 | `payments` | Checkout sessions, products, prices, subscriptions, and crypto helpers |
 | `sessions` | Session lookup, validation, and lifecycle helpers |
 | `secureMessages` | Secure-message create/list helpers |
 | `issueReporting` | Status, history, create, update, reply, voice-token, and private screenshot attachment flows |
 | `appLinks` | Authenticated create and public resolve helpers for application-scoped short links |
+| `whitelist` | Email whitelist checks and admin mutations |
+| `users` | Batch user/email lookups and app membership administration |
+| `supportTelemetry` | Trusted-service support event ingest and case inspection |
 | `marketing` | Browser-safe attribution/experiment event emission and server-side experiment results |
 | `email` | Template lookup, preview, and send helpers |
 | `entitlements` | User/resource entitlement queries and browser-safe current-user project access reads |
 | `usage` | Secret-key usage authorization and immutable usage recording |
+| `access` | Agent-oriented access decisions, action preparation, and persisted decision traces |
+| `graph` | Secret-key capability graph node, path, impact, explain, and refresh helpers |
+| `contract` | Machine-readable capability graph contract discovery |
 | `skillEvals` | Paid blind skill-eval cases, review rooms, reviewer marks, insight inboxes, and controlled reveal |
 | `dayrate` | Availability, Stripe booking, x402 booking-hold, and checkout-status helpers |
 | `admin` | Product and pricing admin helpers |
@@ -97,6 +105,68 @@ Relevant environment variables:
 
 ## Common Patterns
 
+### Agent Access Decisions
+
+`access.check` returns a typed decision even when access is denied. Treat
+`allowed: false` as a normal outcome and use `next_actions` to route the user
+or agent to the next step.
+
+```ts
+const spaps = new SPAPSClient({
+  apiUrl: "https://api.example.test",
+  secretKey: process.env.SPAPS_API_KEY,
+});
+spaps.setAccessToken(process.env.SPAPS_ADMIN_ACCESS_TOKEN!);
+
+const decision = await spaps.access.check({
+  actor: { actor_type: "user", actor_ref: "user_123" },
+  action: "checkout.create",
+  resource: { resource_type: "product", resource_ref: "dayrate" },
+  controls: { entitlement_key: "bookme_paid" },
+});
+
+if (!decision.allowed) {
+  console.log(decision.outcome, decision.next_actions);
+}
+
+const prepared = await spaps.access.prepareAction({
+  access: {
+    actor: { actor_ref: "admin_123" },
+    action: "admin.delete_user",
+    resource: { resource_type: "user", resource_ref: "user_123" },
+  },
+  include_command_templates: true,
+  environment: "production",
+});
+
+console.log(prepared.status, prepared.execution.operator_gate_required);
+```
+
+`operator-gated` is descriptive compatibility input when supplied by a client;
+it does not authorize mutation command templates. The server returns mutation
+command templates only for a non-publishable key plus an authenticated
+admin/operator user context. Publishable callers cannot self-attest the gate.
+
+Use the graph and contract namespaces from trusted server code:
+
+```ts
+const contract = await spaps.contract.get();
+const refresh = await spaps.graph.refresh("local-refresh");
+const nodes = await spaps.graph.listNodes({ node_type: "x402_resource", q: "dayrate" });
+const explanation = await spaps.access.explain(decision.decision_trace_id);
+
+console.log(contract.version, refresh.status, refresh.diagnostics.phase2_gate?.recommendation);
+console.log(nodes.projection?.projection_status, explanation.graph_node_keys);
+```
+
+`contract.get()` also returns `graph_node_types`, `graph_edge_types`,
+`graph_source_domains`, and `source_domain_notes` so agents can discover
+stable graph vocabulary such as `wallet`, `api_key`, `role`, and `approver`.
+
+Capability API failures throw `SPAPSSDKError`. The error preserves `code`,
+`status`/`statusCode`, `requestId`/`request_id`, `details`, `diagnostics`, and
+`remediations`, including fields returned by the server error envelope.
+
 ### Browser-Safe Project Access Reads
 
 Use a publishable key and an authenticated user JWT in browser code. These
@@ -124,6 +194,58 @@ const access = await spaps.entitlements.checkCurrentUserProjectAccess({
 console.log(projects.count, access.has_access);
 ```
 
+### Modern Auth Methods
+
+Login methods that may require MFA return either token data or an MFA challenge
+with `mfa_required: true`. Complete the challenge with `auth.mfa.verify()`
+before calling token-backed helpers.
+
+```ts
+const methods = await spaps.auth.getMethods();
+console.log(methods.methods.filter((item) => item.enabled).map((item) => item.method));
+
+const login = await spaps.auth.signInWithPassword({
+  email: "user@example.com",
+  password: "correct-horse-battery-staple",
+});
+
+if ("mfa_required" in login) {
+  const verified = await spaps.auth.mfa.verify({
+    challenge_id: login.challenge_id,
+    challenge: login.challenge,
+    code: "123456",
+  });
+  console.log(verified.user.id);
+} else {
+  console.log(login.user.id);
+}
+```
+
+OIDC, WebAuthn, and SMS helpers mirror the backend route families without
+reimplementing browser or provider SDKs:
+
+```ts
+const oidc = await spaps.auth.oidc.getNonce();
+await spaps.auth.oidc.signIn({
+  provider: "google",
+  id_token: providerIdToken,
+  challenge_id: oidc.challenge_id,
+});
+
+const createOptions = await spaps.auth.webauthn.registerOptions();
+await spaps.auth.webauthn.registerVerify({
+  challenge_id: createOptions.challenge_id,
+  credential: serializedPublicKeyCredential,
+});
+
+const sms = await spaps.auth.sms.request({ phone_number: "+15555550100" });
+await spaps.auth.sms.verify({
+  phone_number: "+15555550100",
+  challenge_id: sms.challenge_id,
+  code: "123456",
+});
+```
+
 ### Typed Secure Messages
 
 ```ts
@@ -231,6 +353,7 @@ publishing `spaps-sdk` or `spaps-issue-reporting-react` remains operator-gated.
 ### Application Short Links
 
 Use `appLinks` when a browser app needs a stable public URL for large local state, such as compressed diagram state.
+Treat `link.username` as an opaque public owner segment returned by SPAPS.
 
 ```ts
 const spaps = new SPAPSClient({
@@ -246,7 +369,7 @@ const link = await spaps.appLinks.create({
   metadata: { diagram_state: "pako:..." },
 });
 
-console.log(`/${link.app_slug}/${link.username}/${link.slug}`);
+console.log(`/api/v1/app-links/${link.username}/${link.slug}`);
 
 await spaps.appLinks.update(link.username, link.slug, {
   metadata: { diagram_state: "pako:new-state" },
@@ -556,7 +679,7 @@ npm run test:readme
 ## Metadata
 
 - `package_name`: `spaps-sdk`
-- `latest_version`: `1.11.0`
+- `latest_version`: `1.13.0`
 - `minimum_runtime`: `Node.js >=14.0.0`
 - `api_base_url`: `https://api.sweetpotato.dev`