spaps-sdk 1.11.0 → 1.13.0

package/CHANGELOG.md

@@ -8,8 +8,28 @@ 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
+
+### Added
+
+- Exported the canonical issue-report screenshot attachment constraints: `ISSUE_REPORT_ATTACHMENT_ALLOWED_MIME_TYPES`, `ISSUE_REPORT_ATTACHMENT_MAX_BYTES`, and `ISSUE_REPORT_ATTACHMENT_MAX_RETAINED`.
+- Added SDK-side preflight validation to `issueReporting.uploadAttachment(file, options)`, rejecting unsupported MIME types and files larger than 10 MiB before opening the multipart request. SPAPS remains the authoritative backend validator.
+- Documented the operator-gated automatic screenshot-capture handoff: React consumers should lazy-load capture through `spaps-issue-reporting-react@0.6.0`, pass captured files to SDK `uploadAttachment`, and keep publishing/deployment approval outside worker nodes. The local proof tarball for this SDK line was `/tmp/spaps-sdk-1.11.0.tgz`; `spaps-sdk@1.11.0` is now published on npm.
+
 ## [1.10.2] - 2026-06-04
 
 ### Added

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
@@ -154,14 +276,34 @@ console.log(voiceToken.provider, voiceToken.model_id);
 
 ### Issue Reporting Screenshot Attachments
 
-Screenshots are uploaded as private pending hosted assets first. Create, update, or reply calls then send only attachment IDs; do not put raw image bytes, data URLs, or base64 payloads in issue notes or target metadata.
+Use `spaps.issueReporting.uploadAttachment(file)` as the canonical screenshot
+upload path. Consumers should not carry raw `POST /api/v1/issue-reports/attachments`
+adapters when their installed `spaps-sdk` exposes this method.
+
+Screenshots are uploaded as private pending hosted assets first. Create, update,
+or reply calls then send only attachment IDs; do not put raw image bytes, data
+URLs, or base64 payloads in issue notes or target metadata.
 
 ```ts
+import {
+  ISSUE_REPORT_ATTACHMENT_ALLOWED_MIME_TYPES,
+  ISSUE_REPORT_ATTACHMENT_MAX_BYTES,
+  ISSUE_REPORT_ATTACHMENT_MAX_RETAINED,
+} from "spaps-sdk";
+
 spaps.setAccessToken(accessToken);
 
 const file = new File([pngBytes], "protocol-save-failure.png", {
   type: "image/png",
 });
+
+const supportedType = ISSUE_REPORT_ATTACHMENT_ALLOWED_MIME_TYPES.some(
+  (mimeType) => mimeType === file.type,
+);
+if (!supportedType || file.size > ISSUE_REPORT_ATTACHMENT_MAX_BYTES) {
+  throw new Error("Screenshot is not a supported SPAPS issue-report attachment");
+}
+
 const attachment = await spaps.issueReporting.uploadAttachment(file);
 
 const issue = await spaps.issueReporting.create({
@@ -178,14 +320,40 @@ const issue = await spaps.issueReporting.create({
 });
 
 const access = await spaps.issueReporting.getAttachmentAccess(attachment.id);
-console.log(issue.id, access.expires_in_seconds);
+console.log(issue.id, access.expires_in_seconds, ISSUE_REPORT_ATTACHMENT_MAX_RETAINED);
 ```
 
-SPAPS accepts PNG, JPEG, and WebP screenshots up to 10 MiB each, with at most 5 retained screenshots per report. The hosted object remains private; callers fetch a short-lived access URL after normal issue-reporting authorization succeeds. SPAPS does not redact screenshot contents, so host apps should warn users when a capture may include sensitive data.
+The SDK rejects unsupported screenshot MIME types and files over 10 MiB before
+opening the multipart request. SPAPS still performs authoritative validation,
+stores the hosted object privately, and retains at most 5 screenshots per report
+or reply. Callers fetch a short-lived access URL after normal issue-reporting
+authorization succeeds. SPAPS does not redact screenshot contents, so host apps
+should warn users when a capture may include sensitive data.
+
+Browser capture is intentionally outside this SDK. The shared
+`spaps-issue-reporting-react` automatic DOM capture contract is a React-package
+concern: it should lazy-load `html2canvas` only after the host app opts in with
+the React `screenshotCapture` config, convert the visible same-origin DOM result
+to a PNG, JPEG, or WebP `Blob`/`File`, then pass that file to
+`uploadAttachment`. Apps that do not opt in must not download `html2canvas`.
+If capture or upload fails, submit the issue with metadata and any manual
+attachments instead of blocking issue submission.
+
+Version note: `uploadAttachment` was added in `spaps-sdk@1.10.1`, and
+`getAttachmentAccess` became the canonical access helper in `spaps-sdk@1.10.2`.
+The exported limit constants shown above are part of this source package line;
+wait for the operator-approved npm release before removing local shims from
+consumers pinned to older packages.
+
+No new SDK method or backend screenshot endpoint is part of the automatic
+capture contract unless the existing private attachment upload proves
+insufficient. Worker nodes may validate with local packs or workspace links, but
+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({
@@ -201,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" },
@@ -511,7 +679,7 @@ npm run test:readme
 ## Metadata
 
 - `package_name`: `spaps-sdk`
-- `latest_version`: `1.10.2`
+- `latest_version`: `1.13.0`
 - `minimum_runtime`: `Node.js >=14.0.0`
 - `api_base_url`: `https://api.sweetpotato.dev`