@xkova/sdk 0.1.0-alpha.5 → 0.1.0-alpha.7

package/dist/resources/payment-requests.d.ts

@@ -11,6 +11,7 @@ export declare class PaymentRequestsResource extends Resource {
         has_more: boolean;
     }>;
     create(body: ReqBody<'createPaymentRequest'>, opts?: XKOVAMutationOptions): Promise<{
+        notification_status?: "queued" | "sent" | "failed" | "cancelled";
         id?: import("../generated/types.js").components["schemas"]["PaymentRequestId"];
         requester_id?: import("../generated/types.js").components["schemas"]["AccountHolderId"];
         payer_id?: import("../generated/types.js").components["schemas"]["AccountHolderId"] | null;
@@ -26,6 +27,7 @@ export declare class PaymentRequestsResource extends Resource {
         updated_at?: import("../generated/types.js").components["schemas"]["TimestampUtc"];
     }>;
     retrieve(id: string): Promise<{
+        notification_status?: "queued" | "sent" | "failed" | "cancelled";
         id?: import("../generated/types.js").components["schemas"]["PaymentRequestId"];
         requester_id?: import("../generated/types.js").components["schemas"]["AccountHolderId"];
         payer_id?: import("../generated/types.js").components["schemas"]["AccountHolderId"] | null;
@@ -82,6 +84,7 @@ export declare class PaymentRequestsResource extends Resource {
         finalized_at: import("../generated/types.js").components["schemas"]["TimestampUtc"] | null;
     }>;
     cancel(id: string, opts?: XKOVAMutationOptions): Promise<{
+        notification_status?: "queued" | "sent" | "failed" | "cancelled";
         id?: import("../generated/types.js").components["schemas"]["PaymentRequestId"];
         requester_id?: import("../generated/types.js").components["schemas"]["AccountHolderId"];
         payer_id?: import("../generated/types.js").components["schemas"]["AccountHolderId"] | null;
@@ -97,6 +100,7 @@ export declare class PaymentRequestsResource extends Resource {
         updated_at?: import("../generated/types.js").components["schemas"]["TimestampUtc"];
     }>;
     decline(id: string, body?: ReqBody<'declinePaymentRequest'>, opts?: XKOVAMutationOptions): Promise<{
+        notification_status?: "queued" | "sent" | "failed" | "cancelled";
         id?: import("../generated/types.js").components["schemas"]["PaymentRequestId"];
         requester_id?: import("../generated/types.js").components["schemas"]["AccountHolderId"];
         payer_id?: import("../generated/types.js").components["schemas"]["AccountHolderId"] | null;

package/dist/resources/tenant.d.ts

@@ -47,6 +47,12 @@ export declare class TenantResource extends Resource {
         publishable_key: string;
         name: string;
         provider_kind: "xkova_hosted" | "oidc" | "signed_launch";
+        provider_namespace: string;
+        issuer: string | null;
+        audience: string | null;
+        jwks_uri: string | null;
+        allowed_jwt_algorithms: ("RS256" | "PS256" | "ES256" | "EdDSA")[];
+        proof_binding_mode: "authorization_nonce" | "server_assertion_jti";
         enrollment_mode: import("../generated/types.js").components["schemas"]["MemberAuthEnrollmentMode"];
         is_default: boolean;
         status: "active" | "principal_disabled";
@@ -73,6 +79,12 @@ export declare class TenantResource extends Resource {
         publishable_key: string;
         name: string;
         provider_kind: "xkova_hosted" | "oidc" | "signed_launch";
+        provider_namespace: string;
+        issuer: string | null;
+        audience: string | null;
+        jwks_uri: string | null;
+        allowed_jwt_algorithms: ("RS256" | "PS256" | "ES256" | "EdDSA")[];
+        proof_binding_mode: "authorization_nonce" | "server_assertion_jti";
         enrollment_mode: import("../generated/types.js").components["schemas"]["MemberAuthEnrollmentMode"];
         is_default: boolean;
         status: "active" | "principal_disabled";
@@ -90,6 +102,9 @@ export declare class TenantResource extends Resource {
         created_at: import("../generated/types.js").components["schemas"]["TimestampUtc"];
         updated_at: import("../generated/types.js").components["schemas"]["TimestampUtc"];
     }>;
+    /** Disables the exact Hosted Auth or OIDC member application. */
+    disableMemberAuthApplication(id: string, opts?: XKOVAMutationOptions): Promise<void>;
+    /** Existing Hosted Auth convenience name. */
     disableHostedApplication(id: string, opts?: XKOVAMutationOptions): Promise<void>;
     configureOidcApplication(body: ReqBody<'configureMemberAuthOidcApplication'>, opts?: XKOVAMutationOptions): Promise<{
         id: string;

package/dist/resources/tenant.js

@@ -15,9 +15,14 @@ export class TenantResource extends Resource {
     updateHostedApplication(id, body, opts) {
         return this.patchJson(`/tenant/member-auth/applications/${this.enc(id)}`, body, opts);
     }
-    disableHostedApplication(id, opts) {
+    /** Disables the exact Hosted Auth or OIDC member application. */
+    disableMemberAuthApplication(id, opts) {
         return this.deleteJson(`/tenant/member-auth/applications/${this.enc(id)}`, opts);
     }
+    /** Existing Hosted Auth convenience name. */
+    disableHostedApplication(id, opts) {
+        return this.disableMemberAuthApplication(id, opts);
+    }
     configureOidcApplication(body, opts) {
         return this.putJson('/tenant/member-auth/application', body, opts);
     }

package/dist/resources/tokenization.d.ts

@@ -186,6 +186,9 @@ export declare class TokenizationResource extends Resource {
         raw_contract: string | null;
         raw_function: string | null;
         raw_args: string[] | null;
+        failure_reason_code: string | null;
+        failure_reason_detail: string | null;
+        failure_retryable: boolean;
         created_at: string;
         updated_at: string;
     }>;
@@ -222,6 +225,9 @@ export declare class TokenizationResource extends Resource {
         raw_contract: string | null;
         raw_function: string | null;
         raw_args: string[] | null;
+        failure_reason_code: string | null;
+        failure_reason_detail: string | null;
+        failure_retryable: boolean;
         created_at: string;
         updated_at: string;
     }>;
@@ -261,6 +267,9 @@ export declare class TokenizationResource extends Resource {
         raw_contract: string | null;
         raw_function: string | null;
         raw_args: string[] | null;
+        failure_reason_code: string | null;
+        failure_reason_detail: string | null;
+        failure_retryable: boolean;
         created_at: string;
         updated_at: string;
     }>;
@@ -292,6 +301,9 @@ export declare class TokenizationResource extends Resource {
         raw_contract: string | null;
         raw_function: string | null;
         raw_args: string[] | null;
+        failure_reason_code: string | null;
+        failure_reason_detail: string | null;
+        failure_retryable: boolean;
         created_at: string;
         updated_at: string;
     }>;
@@ -323,6 +335,9 @@ export declare class TokenizationResource extends Resource {
         raw_contract: string | null;
         raw_function: string | null;
         raw_args: string[] | null;
+        failure_reason_code: string | null;
+        failure_reason_detail: string | null;
+        failure_retryable: boolean;
         created_at: string;
         updated_at: string;
     }>;

package/dist/resources/wallets.d.ts

@@ -16,6 +16,7 @@ export declare class WalletsResource extends Resource {
         updated_at: import("../generated/types.js").components["schemas"]["TimestampUtc"];
     }>;
     balance(id: string, query: Query<'getWalletBalance'>): Promise<{
+        data_freshness: import("../generated/types.js").components["schemas"]["DataFreshness"][];
         chain_id: number;
         wallet: string;
         token: string;
@@ -34,6 +35,7 @@ export declare class WalletsResource extends Resource {
         has_more: boolean;
     } & {
         data?: import("../generated/types.js").components["schemas"]["LedgerEntry"][];
+        data_freshness: import("../generated/types.js").components["schemas"]["DataFreshness"][];
     }>;
     decommission(id: string, opts?: XKOVAMutationOptions): Promise<{
         id: import("../generated/types.js").components["schemas"]["WalletId"];

package/examples/postgres-checkpoint-store.mjs

@@ -0,0 +1,116 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto';
+
+/** Install pg separately. The application owns the pool, schema, retention and key rotation. */
+export class PostgresCheckpointStore {
+  #context = new AsyncLocalStorage();
+  #key;
+
+  constructor(pool, namespace, encryptionKey) {
+    if (!/^[a-z][a-z0-9_-]{0,63}$/.test(namespace)) throw new Error('Invalid store namespace');
+    if (!Buffer.isBuffer(encryptionKey) || encryptionKey.length !== 32)
+      throw new Error('A 32-byte application encryption key is required');
+    this.pool = pool;
+    this.namespace = namespace;
+    this.#key = Buffer.from(encryptionKey);
+  }
+
+  #binding(reference) {
+    return JSON.stringify([this.namespace, reference]);
+  }
+
+  #encrypt(reference, record) {
+    const iv = randomBytes(12);
+    const cipher = createCipheriv('aes-256-gcm', this.#key, iv);
+    cipher.setAAD(Buffer.from(this.#binding(reference)));
+    const bytes = Buffer.concat([cipher.update(JSON.stringify(record), 'utf8'), cipher.final()]);
+    return Buffer.concat([iv, cipher.getAuthTag(), bytes]);
+  }
+
+  #decrypt(reference, bytes) {
+    if (!Buffer.isBuffer(bytes) || bytes.length < 29) throw new Error('Invalid stored envelope');
+    const decipher = createDecipheriv('aes-256-gcm', this.#key, bytes.subarray(0, 12));
+    decipher.setAAD(Buffer.from(this.#binding(reference)));
+    decipher.setAuthTag(bytes.subarray(12, 28));
+    return JSON.parse(
+      Buffer.concat([decipher.update(bytes.subarray(28)), decipher.final()]).toString('utf8'),
+    );
+  }
+
+  #db() {
+    return this.#context.getStore()?.client ?? this.pool;
+  }
+
+  async put(reference, record) {
+    await this.#db().query(
+      'INSERT INTO xkova_helper_checkpoints(namespace, reference, envelope, expires_at) VALUES ($1,$2,$3,$4)',
+      [this.namespace, reference, this.#encrypt(reference, record), this.#expiry(record)],
+    );
+  }
+
+  async get(reference) {
+    const result = await this.#db().query(
+      'SELECT envelope FROM xkova_helper_checkpoints WHERE namespace=$1 AND reference=$2 AND expires_at > now()',
+      [this.namespace, reference],
+    );
+    return result.rowCount ? this.#decrypt(reference, result.rows[0].envelope) : null;
+  }
+
+  async replace(reference, record) {
+    const result = await this.#db().query(
+      'UPDATE xkova_helper_checkpoints SET envelope=$3, expires_at=$4 WHERE namespace=$1 AND reference=$2',
+      [this.namespace, reference, this.#encrypt(reference, record), this.#expiry(record)],
+    );
+    if (result.rowCount !== 1) throw new Error('Cannot replace a missing checkpoint');
+  }
+
+  async delete(reference) {
+    await this.#db().query(
+      'DELETE FROM xkova_helper_checkpoints WHERE namespace=$1 AND reference=$2',
+      [this.namespace, reference],
+    );
+  }
+
+  #expiry(record) {
+    const value = record.applicationExpiresAt ?? record.expiresAt;
+    if (!Number.isSafeInteger(value)) throw new Error('Invalid checkpoint expiry');
+    return new Date(value);
+  }
+
+  /** A session lock, with separate autocommit checkpoints, never an outer SQL transaction. */
+  async runExclusive(reference, work) {
+    const existing = this.#context.getStore();
+    if (existing) {
+      if (existing.reference !== reference) throw new Error('Nested references are unsupported');
+      return work();
+    }
+    const client = await this.pool.connect();
+    let locked = false;
+    let discard = false;
+    try {
+      await client.query("SET lock_timeout = '5s'");
+      await client.query("SET statement_timeout = '10s'");
+      await client.query('SELECT pg_advisory_lock(hashtextextended($1, 0))', [
+        this.#binding(reference),
+      ]);
+      locked = true;
+      return await this.#context.run({ client, reference }, work);
+    } finally {
+      try {
+        if (locked) {
+          const result = await client.query(
+            'SELECT pg_advisory_unlock(hashtextextended($1, 0)) AS released',
+            [this.#binding(reference)],
+          );
+          if (result.rows[0]?.released !== true) throw new Error('Checkpoint lock was lost');
+        }
+        await client.query('RESET lock_timeout');
+        await client.query('RESET statement_timeout');
+      } catch {
+        // A connection with an uncertain lock must never return to the pool.
+        discard = true;
+      }
+      client.release(discard);
+    }
+  }
+}

package/examples/postgres-checkpoints.sql

@@ -0,0 +1,9 @@
+-- Apply through your application's normal migration process, to its own database.
+CREATE TABLE xkova_helper_checkpoints (
+  namespace text NOT NULL,
+  reference text NOT NULL,
+  envelope bytea NOT NULL,
+  expires_at timestamptz NOT NULL,
+  PRIMARY KEY (namespace, reference)
+);
+CREATE INDEX xkova_helper_checkpoints_expiry ON xkova_helper_checkpoints (expires_at);

package/llms.txt

@@ -10,7 +10,7 @@ Use this package on a Node.js 22+ server. Read the installed declarations before
 - `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.
 - [Quickstart](https://docs.xkova.com/getting-started.html): sandbox access and first authenticated call.
-- [Customer OpenAPI](https://github.com/XKOVA/typescript-sdk/blob/main/schema/customer-api.json): customer contract in this source repository. Installed declarations determine your release’s exact request and response types.
+- [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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xkova/sdk",
-  "version": "0.1.0-alpha.5",
+  "version": "0.1.0-alpha.7",
   "description": "TypeScript SDK for the XKOVA API.",
   "homepage": "https://docs.xkova.com",
   "repository": {
@@ -46,7 +46,8 @@
   },
   "files": [
     "dist",
-    "llms.txt"
+    "llms.txt",
+    "examples"
   ],
   "dependencies": {
     "viem": "^2.21.0"