@xkova/sdk 0.1.0-alpha.2 → 0.1.0-alpha.4

package/README.md

@@ -6,7 +6,7 @@ holders, wallets, payments, tokenization, and other customer resources.
 ## Install
 
 ```bash
-npm install @xkova/sdk@0.1.0-alpha.2
+npm install @xkova/sdk@alpha
 ```
 
 Requires Node.js 22 or newer. Keep this package and your API keys on the server.
@@ -197,26 +197,17 @@ For your own OIDC provider, use `beginAuthorization` and
 code unless your integration explicitly assigns that exchange to XKOVA. Both
 sign-in paths use the same XKOVA session and store contracts.
 
-### Sandbox demo sign-in
-
-For a sandbox application explicitly enabled for demo sign-in, call
-`completeSandboxDemoAuthorization({ state: start.state, transactionStore })`
-after `beginHostedAuthorization`. The SDK obtains the capability and exact
-callback from the server-held transaction, validates the returned callback and
-expiry, and returns `{ callbackUrl, expiresAt }`. Complete that callback through
-`completeHostedAuthorization` with the original browser flow cookie. The API
-reserves a demo account for the session. This operation is not
-available to ordinary tenant applications or production workspaces, and it
-accepts no member, email, wallet, or callback selector.
-
-Keep the same pending reservation and transaction after an ambiguous admission
-failure. Repeating the method uses the same idempotency key and recovers the
-same demo account reservation. The method never retries automatically.
-`isDefinitiveXKOVASandboxDemoAdmissionFailure(error)` identifies confirmed
-rejection before an account was reserved; network, malformed-response, and
-unknown server failures can leave the reservation outcome uncertain.
-API errors retain their status, correlation ID, and Retry-After. Both admission
-and session requests reject HTTP redirects.
+### Local development
+
+The SDK accepts HTTP API URLs, browser origins, callbacks, and storage URLs on
+`localhost` and `127.0.0.1`. Remote hosts require HTTPS. Register each origin
+and callback with its exact scheme, host, port, and path. These two local hosts
+are distinct origins; cookies and browser storage are not shared between them.
+
+For local passkeys, serve the authentication page on `localhost` and use
+`localhost` as its relying-party ID. An IP address cannot be a passkey
+relying-party ID. Keep API keys and member sessions in your BFF, including
+during local development.
 
 ### Stores and callback recovery
 
@@ -344,6 +335,10 @@ Business requests use `no-store` and reject redirects so credentials cannot
 follow a redirect. Network failures preserve the application session. Reuse the
 original idempotency key when reconciling an uncertain write.
 
+`resolved.resources.self.profile()` returns the current member's profile,
+including email and name. These fields are display metadata, not authentication
+proof. Read the profile when displaying it instead of caching it in the session.
+
 `resolved.resources.self.verification()` returns the member's verification
 requirements and sessions through the public self-verification operation.
 `resolved.resources.self.uploadAvatar(image)` performs presign, object upload,
@@ -351,7 +346,7 @@ confirmation, and refreshed avatar lookup. Pass a nonempty PNG, JPEG, WebP, or G
 `Blob` of at most 5 MiB. Storage receives only the image bytes and their content
 headers, never bearer credentials, request signatures, member context, or cookies.
 The helper rejects redirects, expired capabilities, URL credentials, and non-HTTPS
-storage URLs (localhost HTTP is permitted for local development). It does not
+storage URLs (HTTP on `localhost` or `127.0.0.1` is permitted for local development). It does not
 retry an upload. `XKOVAUploadError` identifies the object-storage stage without
 exposing the signed URL; API failures retain `XKOVAApiError` metadata.
 
@@ -371,7 +366,44 @@ Durable application cookies use the host-only `__Host-` prefix, `Secure`, `HttpO
 
 The publishable key is a non-secret application registration identifier. It grants no member or tenant authority by itself. The registered application pins tenant, workspace, environment, provider kind, issuer, audience, origins, redirects, and session policy, and must also match the authenticated workspace principal.
 
-## Cancellation and deadlines
+### Recover an existing member payment
+
+Read recovery state through the resolved member resources:
+
+```ts
+const recovery = await resolved.resources.payments.recovery(paymentId);
+// Call only after the member confirms cancellation in your app.
+if (recovery.can_cancel) {
+  await resolved.resources.payments.cancelForMember(paymentId);
+}
+```
+
+The API permits reads by the sender or recipient. Only the sender can cancel
+or continue. The API principal needs `payment.read` and `payment.cancel`
+permissions for these operations. Your BFF must validate the session, exact
+Origin, and CSRF token before cancellation. Cancellation does not require a
+passkey because it sends no value.
+
+When `can_continue` is true, use `beginMemberAction()` with
+`resourceType: 'payment'`, the existing `resourceId`, and `action: 'sign'`.
+Complete fresh authorization through the registered provider. Keep the original
+amount, recipient, fees, and deadline. Do not create a second payment or reuse
+an expired signing credential. Recovery uses the payment ID, so a new valid
+session for the same member can recover it without the original form draft.
+
+`approval_expired` means the signing window has closed. It remains cancellable
+until a signature has been accepted. After acceptance, `processing` disables
+both actions. `cancelled`, `completed`, and `failed` are separate outcomes;
+retain all three in history. These actions apply to payments; escrow
+cancellation has its own authorization and settlement rules.
+
+Availability can change between a read and a click. After a conflict or an
+uncertain cancellation response, read recovery state again. Repeating an
+already completed member cancellation returns the cancelled payment. Aborting
+an HTTP request or cancelling an authorization ceremony does not cancel the
+payment.
+
+## Request cancellation and deadlines
 
 Set `timeoutMs` on the client for a default request deadline. Mutation options and workflow polling also accept an `AbortSignal`:
 
@@ -386,6 +418,33 @@ await xkova.payments.cancel('pay_...', {
 
 The SDK does not automatically retry writes. Use `withRetry` with a stable idempotency key when retry behavior is appropriate for your application.
 
+## Product enrollment
+
+After a member accepts your displayed terms, call
+`resources.self.acceptProductEnrollment(product, { terms_version })` from the
+BFF. Select the product and terms version on your server. Read the saved result
+with `resources.self.productEnrollment(product)` when the member returns.
+Acceptance does not require an `Idempotency-Key` header. Repeating the same
+acceptance preserves its timestamp. Changed terms or credit parameters with the
+same product are rejected.
+
+Sandbox applications can include `sandbox_credit: { token_deployment_id,
+amount }` to issue a test-token welcome credit. Use an active dUSDC deployment.
+The credit is issued once per member, workspace, and product, across application
+registrations. The daily workspace budget is 1000 dUSDC. Keep amounts and token
+selection in the BFF, and give each product a stable identifier.
+
+For Hosted Auth, set `require_passkey: true` to hold activation and the credit
+until the member has an active passkey and has acknowledged recovery codes.
+`setup_required` means terms are saved and security setup remains incomplete.
+Open Account Center with the `security` intent, then read the enrollment again
+on return. The setup requirement is fixed when the enrollment is accepted.
+
+Poll the enrollment after acceptance. `opening` means delivery is pending;
+`active` means the credit has a successful receipt and an indexed balance.
+`requires_review` needs operator investigation. Do not create another product
+identifier to retry an uncertain credit. Credits do not debit bank accounts.
+
 ## Errors
 
 `XKOVAApiError.retryAfter` preserves the upstream `Retry-After` header when
@@ -432,11 +491,39 @@ idempotency, and settlement. It links the public customer OpenAPI and expanded
 documentation. Installed declarations determine the methods available in your
 version; live documentation may describe a newer release.
 
-## Contributing
+## Writing checks for contributors
+
+Use plain verbs, concrete examples, and comments that explain non-obvious
+decisions. Vary section length, remove repeated conclusions, and write each
+guide for its reader. Test failure and recovery cases alongside successful
+calls. Keep commits small and omit attribution or co-author trailers.
+
+The local pre-push hook checks both public SDKs before the existing test gates.
+It reads each pushed branch or tag's committed files, plus new commit messages
+that touch either package. Uncommitted edits cannot change that result. No
+build or network access is needed. Use the repository's pinned Node version,
+then install workspace dependencies with `pnpm install` to set up the hook.
+
+To check edits before committing:
+
+```sh
+pnpm --filter @xkova/sdk writing:check
+```
 
-Run `pnpm check` from the source repository root before committing. The
-[contributor guide](https://github.com/XKOVA/typescript-sdk/blob/main/CONTRIBUTING.md)
-covers generated files, local pre-push checks, writing rules, and packaging.
+The check covers package guides, examples, public source and generated types,
+and descriptive package metadata. It rejects stock wording, emoji, em dashes,
+attribution, internal decision narratives, and implementation-provider details.
+Describe installation, supported methods, inputs, results, and the steps an
+application developer needs. Do not turn release planning or maintainer
+conversations into package documentation. Standard license text, rule
+definitions, and negative test fixtures are checked separately.
+
+A pass is a mechanical check, not a judgment of authorship. Before pushing,
+reread the result for sentence rhythm, repeated structures, useful comments,
+accurate examples, and test quality. This gate does not scan historical file
+contents or replace secret scanning. It checks commit messages locally;
+review PR descriptions separately. Run `pnpm --filter @xkova/sdk writing:test`
+when changing the rules or hook.
 
 ## License
 

package/dist/client.js

@@ -1,4 +1,5 @@
 import { XKOVAApiError } from './errors.js';
+import { isAllowedProtocol } from './url.js';
 import { generateIdempotencyKey } from './idempotency.js';
 import { signXKOVARequest, validateXKOVARequestSigner, xkovaContentDigest, } from './request-signing.js';
 import { AccountHoldersResource, } from './resources/account-holders.js';
@@ -240,8 +241,8 @@ function normalizeApiBaseUrl(baseUrl) {
     if (url.username || url.password || url.search || url.hash) {
         throw new TypeError('XKOVA SDK baseUrl must be an API origin or /v1 base URL');
     }
-    if (url.protocol !== 'https:' && !(url.protocol === 'http:' && url.hostname === 'localhost')) {
-        throw new TypeError('XKOVA SDK baseUrl must use HTTPS or localhost HTTP');
+    if (!isAllowedProtocol(url)) {
+        throw new TypeError('XKOVA SDK baseUrl must use HTTPS or loopback HTTP');
     }
     const pathname = url.pathname.replace(/\/+$/, '');
     if (pathname !== '' && pathname !== '/v1') {