@xkova/sdk 0.1.0-alpha.1 → 0.1.0-alpha.10

package/llms.txt

@@ -5,12 +5,13 @@ Use this package on a Node.js 22+ server. Read the installed declarations before
 ## Read first
 
 - [Package guide](README.md): installation, production signing, Hosted Auth, member sessions, durable stores, cancellation, errors, webhooks, and proof verification.
-- [Client declarations](dist/client.d.ts): exact resource properties and client options for this installed release.
-- [Customer API types](dist/generated/types.d.ts): exact request bodies, responses, parameters, and operation IDs. Import types through @xkova/sdk/types.
-- [Member BFF declarations](dist/member-bff.d.ts): authorization, session persistence, refresh, logout, action reviews, and human authorization.
-- [Member resources](dist/member-resources.d.ts): typed resources bound to the exact authenticated member.
+- `dist/client.d.ts`: exact resource properties and client options for this installed release.
+- `dist/generated/types.d.ts`: exact request bodies, responses, parameters, and operation IDs. Import types through @xkova/sdk/types.
+- `dist/member-bff.d.ts`: authorization, session persistence, refresh, logout, action reviews, and human authorization.
+- `dist/member-resources.d.ts`: typed resources bound to the exact authenticated member.
+- `dist/workforce-bff.d.ts`: confidential workforce sessions, durable callback recovery, exact action reviews and fresh provider proof. Use @xkova/sdk/workforce-bff, separately from member login and Console operators.
 - [Quickstart](https://docs.xkova.com/getting-started.html): sandbox access and first authenticated call.
-- [Customer OpenAPI](https://docs.xkova.com/data/openapi-customer.json): machine-readable customer contract for the current published documentation.
+- [Customer OpenAPI](https://github.com/XKOVA/typescript-sdk/blob/main/schema/customer-api.json): machine-readable contract for the public SDK source. For an installed release, use its generated declarations.
 - [SDK guide](https://docs.xkova.com/sdk-overview.html): client and resource examples.
 - [Workflow guide](https://docs.xkova.com/sdk-workflows.html): supported workflow helpers.
 - [Member integration](https://docs.xkova.com/embedded-member.html): browser, BFF, identity, and signing boundaries.
@@ -22,7 +23,7 @@ Use this package on a Node.js 22+ server. Read the installed declarations before
 1. Server business integration: create XKOVAClient.forTenant({ baseUrl, apiKey }). Use https://sandbox-api.xkova.com for sandbox and https://api.xkova.com for production. The API key binds the workspace and mode.
 2. Member application: use XKOVAMemberBffClient from @xkova/sdk/member-bff in your BFF. Resolve confidential sessions to request-scoped resources with resolveResources(). The browser sends only its application cookie and CSRF proof to your BFF.
 3. Browser companion: optionally install @xkova/browser. It calls your same-origin routes; it does not create those routes or install a session store.
-4. Institution staff and management: use the Console and its documented setup flows. Do not invent customer SDK methods for API-key lifecycle, treasury administration, staff governance, or platform management.
+4. Customer staff application: use XKOVAWorkforceBffClient from @xkova/sdk/workforce-bff, an explicitly registered dedicated principal and immutable admitted provider subjects. Resolve each authenticated person per request. API-key attribution, email, groups and member credentials cannot create staff authority.
 
 ## Find a capability
 
@@ -41,6 +42,7 @@ Each namespace below is a property of XKOVAClient. Read its declaration under di
 | Transaction history | transactions |
 | Fee schedules and platform fees | feeSchedules |
 | Customer tokens, deployment, minting, supply, access | tokenization |
+| Tenant treasury vaults, proposals, owner signatures, quorum and transfer status | treasury |
 | Real-world assets, cap tables, distributions, corporate actions, provenance | rwa |
 | Gateway registration and conformance | integrationGateways |
 | Branding and sending-domain configuration | branding |
@@ -49,6 +51,7 @@ Each namespace below is a property of XKOVAClient. Read its declaration under di
 | Webhook subscriptions and delivery operations | webhooks |
 | Token deployment/mint polling and off-ramp initiation | workflows |
 | Session exchange, durable review recovery, fresh human authorization | @xkova/sdk/member-bff |
+| Institution workforce login, scoped sessions and exact action proofs | @xkova/sdk/workforce-bff |
 | Verify webhook signatures over raw body bytes | @xkova/sdk/webhook |
 | Offline RWA transparency proofs | @xkova/sdk/rwa-verify |
 | Customer contract ABIs | @xkova/sdk/abi |
@@ -58,9 +61,10 @@ API availability does not grant permission. Product entitlement, selected API-ke
 ## Requests and results
 
 - Start with the README's sandbox read example. Validate required environment variables on the server; never emit their values into logs, generated files, browser bundles, or prompts.
-- Use exported package entry points and typed resource methods. Do not import dist files as runtime subpaths, use private endpoints, fabricate request fields, or suppress type errors with any.
+- Use exported package entry points and typed resource methods. Do not import dist files as runtime subpaths, fabricate request fields, or suppress type errors with any.
 - Production writes require the bearer key plus an active asymmetric requestSigner credential. Its async callback signs through your key provider. The SDK supplies RFC 9421 signatures and RFC 9530 digests. Production reads use bearer authentication.
 - Generate one idempotency key before a logical mutation and persist it. Reuse it only with the identical request. The SDK does not automatically retry writes. A timeout or disconnect can leave the outcome unknown; reconcile the existing resource before starting another operation.
+- Treasury methods preserve API roles, governance holds, independent owner signatures and Safe quorum. An API key is not an authenticated staff session or a wallet signer. Use isHeldApproval before reading an entity from a governed mutation; approval does not itself produce a signature or prove settlement.
 - Use decimal strings for monetary values according to the request type. Preserve asset and chain identity throughout a flow. Do not perform monetary calculations with JavaScript floating-point numbers.
 - Read pagination and response types. Use paginateCursor or collectCursor where applicable; bound collection sizes and polling. Propagate AbortSignal and request deadlines.
 - Handle XKOVAApiError with its code, status, correlationId, and retryAfter. Handle XKOVAUploadError for the object-storage stage. Do not expose transport headers, provider proofs, or signed URLs in user errors or logs.
@@ -75,10 +79,26 @@ API availability does not grant permission. Product entitlement, selected API-ke
 - Reuse one createMemberActionReference() from @xkova/browser for a durable review. Save the draft before setup detours. Expired or missing reviews require checking activity and an explicit new review.
 - Setup readiness is advisory. beginMemberAction() and completeMemberAction() obtain fresh approval for the exact resource. Browser code must not receive provider wallet credentials or internal signing capabilities. Completion of authorization is distinct from execution and settlement.
 
-## Dependencies
+## Payment recovery
 
-The server SDK uses viem for offline RWA signature verification. The browser companion has no runtime dependencies. Neither imports Thirdweb. You may see Thirdweb in API provider metadata, but these integrations require no Thirdweb SDK or credentials.
+Use resolved.resources.payments.recovery(paymentId) to read the current
+member's payment and available actions. Only the sender can continue or cancel.
+On explicit cancellation, call cancelForMember(paymentId) after BFF session,
+Origin and CSRF checks. The principal needs payment.read and payment.cancel.
+Cancellation sends no value and does not require a passkey.
+
+Continue only when can_continue is true. Begin a fresh member action for the
+same payment resourceId with action sign, then complete the registered proof
+ceremony. Never create another payment, change its fees or deadline, or reuse
+an expired signing credential. A new session for the same member can recover
+the payment without its original draft. Expired approvals remain cancellable;
+accepted signatures close cancellation. Keep cancelled payments in history.
+After a conflict or uncertain cancellation, re-read state before another action.
 
 ## Before handing off code
 
 List the Console setup and stores the application needs. Test denied access, uncertain writes, pagination, cancellation, and terminal outcomes. Report a missing method or setup requirement explicitly. Do not invent methods, suppress type errors, or bypass authorization to make an example run.
+
+## Product opt-in
+
+Use resolveResources().self.productEnrollment(product) to read acceptance and credit status. After explicit consent, call self.acceptProductEnrollment(product, { terms_version, sandbox_credit? }). The BFF chooses the product, terms, amount, and token. Reads do not enroll members. Acceptance needs no Idempotency-Key header; reuse the same product and parameters when retrying. Sandbox credits are dUSDC only and issued once per workspace/member/product; the workspace daily budget is 1000 dUSDC. Poll opening until active. Treat requires_review as unresolved delivery, never as permission to request a second product credit.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@xkova/sdk",
-  "version": "0.1.0-alpha.1",
-  "description": "Server-side TypeScript client for the XKOVA customer API, with customer-only generated types and production request signing.",
+  "version": "0.1.0-alpha.10",
+  "description": "TypeScript SDK for the XKOVA API.",
   "homepage": "https://docs.xkova.com",
   "repository": {
     "type": "git",
@@ -31,6 +31,10 @@
       "types": "./dist/member-bff.d.ts",
       "default": "./dist/member-bff.js"
     },
+    "./workforce-bff": {
+      "types": "./dist/workforce-bff.d.ts",
+      "default": "./dist/workforce-bff.js"
+    },
     "./webhook": {
       "types": "./dist/webhook.d.ts",
       "default": "./dist/webhook.js"
@@ -46,7 +50,8 @@
   },
   "files": [
     "dist",
-    "llms.txt"
+    "llms.txt",
+    "examples"
   ],
   "dependencies": {
     "viem": "^2.21.0"