@obbyx/sdk 0.0.0-stage → 0.1.1

package/dist/seller/consumed-proofs.js

@@ -0,0 +1,150 @@
+import { DatabaseSync } from 'node:sqlite';
+export class ConsumedProofsStore {
+    now;
+    db;
+    constructor(path, now = () => Math.floor(Date.now() / 1000)) {
+        this.now = now;
+        this.db = new DatabaseSync(path);
+        this.db.exec(`
+      PRAGMA journal_mode = WAL;
+      PRAGMA synchronous = FULL;
+      PRAGMA busy_timeout = 5000;
+      CREATE TABLE IF NOT EXISTS consumed_proofs (
+        key TEXT PRIMARY KEY,
+        binding TEXT NOT NULL,
+        state TEXT NOT NULL,
+        payment_response TEXT,
+        response_status INTEGER,
+        response_headers TEXT,
+        response_body BLOB,
+        created_at INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL
+      ) STRICT;
+      CREATE TABLE IF NOT EXISTS payment_ids (
+        scope_id TEXT PRIMARY KEY,
+        fingerprint TEXT NOT NULL,
+        proof_key TEXT NOT NULL,
+        created_at INTEGER NOT NULL
+      ) STRICT;
+    `);
+    }
+    /**
+     * x402 `payment-identifier`: remembers which proof served a client-chosen id
+     * for one operation fingerprint. Returns the stored mapping (existing or new).
+     */
+    bindPaymentId(scopeId, fingerprint, proofKey) {
+        const res = this.db
+            .prepare('INSERT INTO payment_ids (scope_id, fingerprint, proof_key, created_at) VALUES (?, ?, ?, ?) ON CONFLICT(scope_id) DO NOTHING')
+            .run(scopeId, fingerprint, proofKey, this.now());
+        const row = this.db
+            .prepare('SELECT fingerprint, proof_key FROM payment_ids WHERE scope_id = ?')
+            .get(scopeId);
+        return {
+            fingerprint: row.fingerprint,
+            proofKey: row.proof_key,
+            created: Number(res.changes) === 1,
+        };
+    }
+    /** Compare-and-set: moves the id only if it still points at `previous` (one winner). */
+    rebindPaymentId(scopeId, previous, proofKey) {
+        const res = this.db
+            .prepare('UPDATE payment_ids SET proof_key = ? WHERE scope_id = ? AND proof_key = ?')
+            .run(proofKey, scopeId, previous);
+        return Number(res.changes) === 1;
+    }
+    close() {
+        this.db.close();
+    }
+    get(key) {
+        const row = this.db.prepare('SELECT * FROM consumed_proofs WHERE key = ?').get(key);
+        return row === undefined ? undefined : toRecord(row);
+    }
+    /** Inserts the proof in `settling` unless it exists; returns the stored record. */
+    begin(key, binding) {
+        const ts = this.now();
+        const res = this.db
+            .prepare(`INSERT INTO consumed_proofs (key, binding, state, created_at, updated_at)
+         VALUES (?, ?, 'settling', ?, ?) ON CONFLICT(key) DO NOTHING`)
+            .run(key, binding, ts, ts);
+        const record = this.get(key);
+        if (record === undefined)
+            throw new Error(`consumed proof ${key} vanished`);
+        return { created: Number(res.changes) === 1, record };
+    }
+    /** Compare-and-set; returns false if the proof is not in `from`. */
+    transition(key, from, to, patch = {}) {
+        const res = this.db
+            .prepare(`UPDATE consumed_proofs
+            SET state = ?, updated_at = ?,
+                payment_response = COALESCE(?, payment_response),
+                response_status = COALESCE(?, response_status),
+                response_headers = COALESCE(?, response_headers),
+                response_body = COALESCE(?, response_body)
+          WHERE key = ? AND state = ?`)
+            .run(to, this.now(), patch.paymentResponse ?? null, patch.response?.status ?? null, patch.response === undefined ? null : JSON.stringify(patch.response.headers), patch.response?.body ?? null, key, from);
+        return Number(res.changes) === 1;
+    }
+    /**
+     * Records a SETTLED payment as paid (`settling → paid_not_served`), also when
+     * a concurrent request removed or moved its row meanwhile: the payment did
+     * settle, so it must stay servable once. Atomic; returns the stored state.
+     */
+    markSettled(key, binding, paymentResponse) {
+        const ts = this.now();
+        this.db.exec('BEGIN IMMEDIATE');
+        try {
+            this.db
+                .prepare(`INSERT INTO consumed_proofs (key, binding, state, payment_response, created_at, updated_at)
+           VALUES (?, ?, 'paid_not_served', ?, ?, ?)
+           ON CONFLICT(key) DO UPDATE SET state = 'paid_not_served', payment_response = excluded.payment_response,
+             updated_at = excluded.updated_at
+           WHERE consumed_proofs.state = 'settling'`)
+                .run(key, binding, paymentResponse, ts, ts);
+            this.db.exec('COMMIT');
+        }
+        catch (err) {
+            this.db.exec('ROLLBACK');
+            throw err;
+        }
+        const record = this.get(key);
+        if (record === undefined)
+            throw new Error(`consumed proof ${key} vanished`);
+        return record.state;
+    }
+    /**
+     * Recovers a proof stuck in `serving` (the process died while the handler
+     * ran): after `leaseSeconds` it goes back to `paid_not_served` (already
+     * settled) or `settling` (authorization flow, not settled yet), so the SAME
+     * payment can complete the operation. Compare-and-set: one winner.
+     */
+    reclaimStale(key, leaseSeconds) {
+        const res = this.db
+            .prepare(`UPDATE consumed_proofs
+            SET state = CASE WHEN payment_response IS NULL THEN 'settling' ELSE 'paid_not_served' END,
+                updated_at = ?
+          WHERE key = ? AND state = 'serving' AND updated_at <= ?`)
+            .run(this.now(), key, this.now() - leaseSeconds);
+        return Number(res.changes) === 1;
+    }
+    /** Removes a proof that never reached the network (e.g. rejected at verification). */
+    forget(key, state) {
+        this.db.prepare('DELETE FROM consumed_proofs WHERE key = ? AND state = ?').run(key, state);
+    }
+}
+function toRecord(row) {
+    return {
+        key: row.key,
+        binding: row.binding,
+        state: row.state,
+        paymentResponse: row.payment_response,
+        response: row.response_status === null
+            ? null
+            : {
+                status: row.response_status,
+                headers: JSON.parse(row.response_headers ?? '{}'),
+                body: row.response_body ?? new Uint8Array(),
+            },
+        updatedAt: row.updated_at,
+    };
+}
+//# sourceMappingURL=consumed-proofs.js.map

package/dist/seller/consumed-proofs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consumed-proofs.js","sourceRoot":"","sources":["../../src/seller/consumed-proofs.ts"],"names":[],"mappings":"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"}

package/dist/seller/defaults.d.ts

@@ -0,0 +1,7 @@
+/** Seller-side defaults shared by ObytePaywall and ObyteExactServer (seconds). */
+export declare const DEFAULT_QUOTE_TTL_SECONDS = 300;
+/** Freshness window of the payment unit's timestamp offered in `maxTimeoutSeconds`. */
+export declare const DEFAULT_MAX_TIMEOUT_SECONDS = 300;
+/** How long a request may hold a payment in `serving` before a retry takes it over. */
+export declare const DEFAULT_SERVING_LEASE_SECONDS = 300;
+//# sourceMappingURL=defaults.d.ts.map

package/dist/seller/defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../../src/seller/defaults.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAClF,eAAO,MAAM,yBAAyB,MAAM,CAAC;AAC7C,uFAAuF;AACvF,eAAO,MAAM,2BAA2B,MAAM,CAAC;AAC/C,uFAAuF;AACvF,eAAO,MAAM,6BAA6B,MAAM,CAAC"}

package/dist/seller/defaults.js

@@ -0,0 +1,7 @@
+/** Seller-side defaults shared by ObytePaywall and ObyteExactServer (seconds). */
+export const DEFAULT_QUOTE_TTL_SECONDS = 300;
+/** Freshness window of the payment unit's timestamp offered in `maxTimeoutSeconds`. */
+export const DEFAULT_MAX_TIMEOUT_SECONDS = 300;
+/** How long a request may hold a payment in `serving` before a retry takes it over. */
+export const DEFAULT_SERVING_LEASE_SECONDS = 300;
+//# sourceMappingURL=defaults.js.map

package/dist/seller/defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../../src/seller/defaults.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAClF,MAAM,CAAC,MAAM,yBAAyB,GAAG,GAAG,CAAC;AAC7C,uFAAuF;AACvF,MAAM,CAAC,MAAM,2BAA2B,GAAG,GAAG,CAAC;AAC/C,uFAAuF;AACvF,MAAM,CAAC,MAAM,6BAA6B,GAAG,GAAG,CAAC"}

package/dist/seller/payment-identifier.d.ts

@@ -0,0 +1,73 @@
+import type { PaymentPayload } from '@x402/core/types';
+import { z } from 'zod';
+/**
+ * x402 `payment-identifier` extension (seller side): a client-chosen id makes
+ * a repeated operation return the stored response instead of charging again.
+ */
+export declare const PAYMENT_IDENTIFIER = "payment-identifier";
+/** Same constraints as @x402/extensions (16–128 chars of [A-Za-z0-9_-]). */
+export declare const paymentIdSchema: z.ZodString;
+/** Same declaration as @x402/extensions `declarePaymentIdentifierExtension`. */
+export declare function paymentIdentifierDeclaration(required: boolean): {
+    info: {
+        required: boolean;
+    };
+    schema: {
+        $schema: string;
+        type: string;
+        properties: {
+            required: {
+                type: string;
+            };
+            id: {
+                type: string;
+                minLength: number;
+                maxLength: number;
+                pattern: string;
+            };
+        };
+        required: string[];
+    };
+};
+/** The client's id: `undefined` when absent, `'invalid'` when malformed. */
+export declare function paymentIdOf(payload: PaymentPayload): string | undefined | 'invalid';
+/** What the store needs for payment-identifier decisions. */
+export interface PaymentIdStore {
+    bindPaymentId(scopeId: string, fingerprint: string, proofKey: string): {
+        fingerprint: string;
+        proofKey: string;
+        created: boolean;
+    };
+    /** Compare-and-set: moves the id to `proofKey` only if it still points at `previous`. */
+    rebindPaymentId(scopeId: string, previous: string, proofKey: string): boolean;
+    get(key: string): {
+        state: string;
+        response: unknown;
+        paymentResponse: string | null;
+    } | undefined;
+}
+export type PaymentIdDecision = {
+    kind: 'proceed';
+} | {
+    kind: 'replay';
+    proofKey: string;
+} | {
+    kind: 'reject';
+    status: 400 | 409;
+    error: string;
+};
+/**
+ * One client id = one operation. Contract: the caller has already created the
+ * proof row for `proofKey` (so other requests see it as in progress).
+ * Concurrent retries with DIFFERENT payments
+ * for the same id: exactly one wins the compare-and-set; the others get 409,
+ * so an id can never be charged twice.
+ */
+export declare function decidePaymentId(store: PaymentIdStore, input: {
+    paymentId: string | undefined | 'invalid';
+    required: boolean;
+    scopeId: (id: string) => string;
+    fingerprint: string;
+    proofKey: string;
+}): PaymentIdDecision;
+//# sourceMappingURL=payment-identifier.d.ts.map

package/dist/seller/payment-identifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payment-identifier.d.ts","sourceRoot":"","sources":["../../src/seller/payment-identifier.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;GAGG;AACH,eAAO,MAAM,kBAAkB,uBAAuB,CAAC;AAEvD,4EAA4E;AAC5E,eAAO,MAAM,eAAe,aAA8C,CAAC;AAM3E,gFAAgF;AAChF,wBAAgB,4BAA4B,CAAC,QAAQ,EAAE,OAAO;;;;;;;;;;;;;;;;;;;;EAa7D;AAED,4EAA4E;AAC5E,wBAAgB,WAAW,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,CASnF;AAED,6DAA6D;AAC7D,MAAM,WAAW,cAAc;IAC7B,aAAa,CACX,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,GACf;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;IAC/D,yFAAyF;IACzF,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IAC9E,GAAG,CACD,GAAG,EAAE,MAAM,GACV;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAC;QAAC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,SAAS,CAAC;CACrF;AAED,MAAM,MAAM,iBAAiB,GACzB;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GACnB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACpC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,GAAG,GAAG,GAAG,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,cAAc,EACrB,KAAK,EAAE;IACL,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAAC;IAC1C,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,CAAC;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;CAClB,GACA,iBAAiB,CAwBnB"}

package/dist/seller/payment-identifier.js

@@ -0,0 +1,75 @@
+import { z } from 'zod';
+/**
+ * x402 `payment-identifier` extension (seller side): a client-chosen id makes
+ * a repeated operation return the stored response instead of charging again.
+ */
+export const PAYMENT_IDENTIFIER = 'payment-identifier';
+/** Same constraints as @x402/extensions (16–128 chars of [A-Za-z0-9_-]). */
+export const paymentIdSchema = z.string().regex(/^[a-zA-Z0-9_-]{16,128}$/);
+const extensionSchema = z
+    .object({ info: z.object({ id: z.unknown().optional() }).loose() })
+    .loose();
+/** Same declaration as @x402/extensions `declarePaymentIdentifierExtension`. */
+export function paymentIdentifierDeclaration(required) {
+    return {
+        info: { required },
+        schema: {
+            $schema: 'https://json-schema.org/draft/2020-12/schema',
+            type: 'object',
+            properties: {
+                required: { type: 'boolean' },
+                id: { type: 'string', minLength: 16, maxLength: 128, pattern: '^[a-zA-Z0-9_-]+$' },
+            },
+            required: ['required'],
+        },
+    };
+}
+/** The client's id: `undefined` when absent, `'invalid'` when malformed. */
+export function paymentIdOf(payload) {
+    const raw = payload.extensions?.[PAYMENT_IDENTIFIER];
+    if (raw === undefined)
+        return undefined;
+    const ext = extensionSchema.safeParse(raw);
+    if (!ext.success)
+        return 'invalid';
+    const id = ext.data.info.id;
+    if (id === undefined)
+        return undefined;
+    const parsed = paymentIdSchema.safeParse(id);
+    return parsed.success ? parsed.data : 'invalid';
+}
+/**
+ * One client id = one operation. Contract: the caller has already created the
+ * proof row for `proofKey` (so other requests see it as in progress).
+ * Concurrent retries with DIFFERENT payments
+ * for the same id: exactly one wins the compare-and-set; the others get 409,
+ * so an id can never be charged twice.
+ */
+export function decidePaymentId(store, input) {
+    const { paymentId } = input;
+    if (paymentId === 'invalid')
+        return { kind: 'reject', status: 400, error: 'invalid_payment_identifier' };
+    if (paymentId === undefined) {
+        return input.required
+            ? { kind: 'reject', status: 400, error: 'payment_identifier_required' }
+            : { kind: 'proceed' };
+    }
+    const scopeId = input.scopeId(paymentId);
+    const mapping = store.bindPaymentId(scopeId, input.fingerprint, input.proofKey);
+    if (mapping.fingerprint !== input.fingerprint) {
+        return { kind: 'reject', status: 409, error: 'payment_identifier_conflict' };
+    }
+    if (mapping.proofKey === input.proofKey)
+        return { kind: 'proceed' };
+    const original = store.get(mapping.proofKey);
+    if (original?.state === 'served')
+        return { kind: 'replay', proofKey: mapping.proofKey };
+    if (original !== undefined && original.state !== 'failed') {
+        return { kind: 'reject', status: 409, error: 'payment_in_progress' };
+    }
+    // The earlier attempt definitely failed (or never consumed its proof): move the id.
+    return store.rebindPaymentId(scopeId, mapping.proofKey, input.proofKey)
+        ? { kind: 'proceed' }
+        : { kind: 'reject', status: 409, error: 'payment_in_progress' };
+}
+//# sourceMappingURL=payment-identifier.js.map

package/dist/seller/payment-identifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"payment-identifier.js","sourceRoot":"","sources":["../../src/seller/payment-identifier.ts"],"names":[],"mappings":"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"}

package/dist/seller/paywall.d.ts

@@ -0,0 +1,101 @@
+import type { Request, RequestHandler } from 'express';
+import { type FacilitatorClient } from '@x402/core/http';
+import { type Logger } from '@obbyx/obyte/logger';
+import { BATCH_SCHEME, EXACT_SCHEME } from '@obbyx/x402-obyte';
+import type { ConsumedProofsStore } from './consumed-proofs.js';
+/**
+ * Express paywall for x402 `exact` payments on Obyte (seller side).
+ *
+ * Flow `upfront` (phase 3): settle to the facilitator's finality BEFORE the
+ * handler runs; the handler runs at most once per payment proof; a repeat of
+ * the same operation with the same proof returns the stored response.
+ *
+ * Paid handlers return their response instead of writing to `res`, so the
+ * paywall can store it for idempotent replays.
+ */
+export interface PaidResult {
+    readonly status?: number;
+    readonly headers?: Readonly<Record<string, string>>;
+    /** Objects are sent as JSON; strings/bytes as-is. */
+    readonly body: unknown;
+}
+export type PaidHandler = (req: Request) => Promise<PaidResult> | PaidResult;
+export interface RoutePrice {
+    /** Atomic units as a decimal string. */
+    readonly amount: string;
+    /** `'base'` for bytes or an asset id. */
+    readonly asset?: string;
+}
+export interface PaidRouteOptions {
+    readonly price: RoutePrice;
+    readonly description?: string;
+    readonly mimeType?: string;
+    /** What identifies "the same operation". Default: sha256 of the canonical JSON body. */
+    readonly fingerprint?: (req: Request) => string;
+    /** Offered schemes in order of preference. Default: batch-settlement (if enabled), exact. */
+    readonly schemes?: readonly PaywallScheme[];
+    /**
+     * `upfront` (default): settle, then run the handler — for anything expensive
+     * or irreversible. `authorization`: verify, run the handler, settle, then
+     * send — only for cheap, idempotent handlers: if the settlement then fails,
+     * the handler's side effects have happened but its response is withheld.
+     */
+    readonly flow?: 'upfront' | 'authorization';
+}
+export type PaywallScheme = typeof EXACT_SCHEME | typeof BATCH_SCHEME;
+export interface ObytePaywallOptions {
+    readonly facilitator: FacilitatorClient;
+    readonly network: string;
+    readonly payTo: string;
+    /** Stable identifier of this seller/API (part of the binding). */
+    readonly sellerId: string;
+    /** HMAC key for bindings; keep secret, ≥ 32 bytes. */
+    readonly secret: string | Uint8Array;
+    readonly store: ConsumedProofsStore;
+    readonly logger: Logger;
+    readonly quoteTtlSeconds?: number;
+    readonly maxTimeoutSeconds?: number;
+    /** How long one request waits for `settlement_pending` to resolve. */
+    readonly settleWaitMs?: number;
+    readonly settlePollMs?: number;
+    /**
+     * How long a request may hold a payment in `serving` (default 300 s). After
+     * that a retry with the same payment takes over (crash recovery); set it
+     * above the slowest handler.
+     */
+    readonly servingLeaseSeconds?: number;
+    /**
+     * Declares the x402 `payment-identifier` extension: a client-chosen id makes a
+     * repeated operation return the stored response instead of charging again.
+     */
+    readonly paymentIdentifier?: {
+        readonly required: boolean;
+    };
+    /** Enables batch-settlement (AA payment channels) offers; requires a running seller watcher. */
+    readonly batch?: {
+        readonly minChannelTimeoutSeconds: number;
+    };
+    readonly now?: () => number;
+}
+export declare class ObytePaywall {
+    private readonly options;
+    private readonly log;
+    private readonly now;
+    constructor(options: ObytePaywallOptions);
+    /** Wraps a handler so it only runs after a settled payment. */
+    paid(route: PaidRouteOptions, handler: PaidHandler): RequestHandler;
+    private handle;
+    /** authorization flow: verify → handler (response stored) → settle → send. */
+    private authorize;
+    private settleServed;
+    private serve;
+    private send;
+    private paymentRequired;
+    /** PAYMENT-RESPONSE of a payment refused before settlement (not used, nothing charged). */
+    private refusal;
+    private requestFacts;
+    private terms;
+    private schemesFor;
+    private settleWithWait;
+}
+//# sourceMappingURL=paywall.d.ts.map

package/dist/seller/paywall.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paywall.d.ts","sourceRoot":"","sources":["../../src/seller/paywall.ts"],"names":[],"mappings":"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"}