tapimo 0.0.2 → 0.2.0

package/dist/apps/relay/Sponsorships.js

@@ -0,0 +1,193 @@
+import { TxEnvelopeTempo } from 'ox/tempo';
+import { TransactionReceiptNotFoundError, } from 'viem';
+import { getTransactionReceipt } from 'viem/actions';
+import * as Db from '../../db/Db.js';
+import * as SponsoredTransactions from '../../db/tables/sponsoredTransactions.js';
+import * as Tidx from '../../internal/Tidx.js';
+import * as Viem from '../../internal/Viem.js';
+/**
+ * Runs one finalization pass over pending sponsored transactions: rows with a
+ * receipt finalize with the actual fee (`gasUsed × effectiveGasPrice`, in
+ * fee-token base units); rows still unmined past the pending TTL fail, as do
+ * hash-less fill intents the TTL outlives. Rows whose receipt lookup errors
+ * persist past the error TTL fail so they cannot monopolize every batch.
+ *
+ * @param db - The database holding `sponsored_transactions`.
+ * @param options - Finalization options.
+ * @returns Counters for the pass.
+ */
+export async function finalize(db, options) {
+    const { batchSize = 100, getClient, now = () => new Date(), pendingTtlMs = 3_600_000, receiptErrorTtlMs = 86_400_000, } = options;
+    const rows = await SponsoredTransactions.listPending(db, { limit: batchSize });
+    const result = { failed: 0, finalized: 0, pending: 0 };
+    for (const row of rows) {
+        // Fill intents carry no hash until reconciliation matches them on-chain;
+        // here only the TTL can settle them.
+        if (row.transactionHash === null) {
+            if (Date.parse(row.createdAt) + pendingTtlMs <= now().getTime()) {
+                await SponsoredTransactions.fail(db, row.id, now().toISOString());
+                result.failed++;
+            }
+            else
+                result.pending++;
+            continue;
+        }
+        let receipt;
+        try {
+            receipt = await getTransactionReceipt(getClient(row.chainId), {
+                hash: row.transactionHash,
+            });
+        }
+        catch (error) {
+            // Unmined transactions surface as a typed not-found; let the TTL decide.
+            if (error instanceof TransactionReceiptNotFoundError)
+                receipt = null;
+            else {
+                if (Date.parse(row.createdAt) + receiptErrorTtlMs <= now().getTime()) {
+                    await SponsoredTransactions.fail(db, row.id, now().toISOString());
+                    result.failed++;
+                }
+                else
+                    result.pending++;
+                continue;
+            }
+        }
+        if (receipt) {
+            // A reverted transaction still finalizes: the fee payer paid its fees.
+            const feeAmount = receipt.gasUsed * receipt.effectiveGasPrice;
+            await SponsoredTransactions.finalize(db, row.id, {
+                feeAmount: feeAmount.toString(),
+                finalizedAt: now().toISOString(),
+            });
+            result.finalized++;
+        }
+        else if (Date.parse(row.createdAt) + pendingTtlMs <= now().getTime()) {
+            await SponsoredTransactions.fail(db, row.id, now().toISOString());
+            result.failed++;
+        }
+        else
+            result.pending++;
+    }
+    return result;
+}
+/**
+ * Runs one reconciliation pass over pending fill intents (rows with no
+ * transaction hash): fetches the fee payer's recent on-chain transactions
+ * from TIDX, recomputes each candidate's fee-payer sign payload, and fills
+ * matching intents' hashes so the receipt pass can finalize them. Query or
+ * candidate errors leave intents for the next pass.
+ *
+ * @param db - The database holding `sponsored_transactions`.
+ * @param options - Reconciliation options.
+ * @returns Counters for the pass.
+ */
+export async function reconcile(db, options) {
+    const { batchSize = 100, candidateCap = 500, failedIntentTtlMs = 86_400_000, feePayer, getClient, getTidx, skewMs = 120_000, } = options;
+    const intents = await SponsoredTransactions.listIntents(db, {
+        failedSince: new Date(Date.now() - failedIntentTtlMs).toISOString(),
+        limit: batchSize,
+    });
+    const result = { matched: 0, scanned: 0 };
+    if (intents.length === 0)
+        return result;
+    const chains = new Map();
+    for (const intent of intents)
+        chains.set(intent.chainId, [...(chains.get(intent.chainId) ?? []), intent]); // prettier-ignore
+    for (const [chainId, rows] of chains) {
+        const bySignPayload = new Map(rows.map((row) => [row.signPayload, row]));
+        // The intent set bounds the scan window: no cursor state to persist.
+        const since = new Date(Math.min(...rows.map((row) => Date.parse(row.createdAt))) - skewMs).toISOString();
+        let candidates;
+        try {
+            // Dynamic filter values; the tidx client's query type wants literals.
+            const fetched = await getTidx(chainId).fetch({
+                chainId,
+                query: `SELECT hash, "from" FROM txs WHERE fee_payer = '${feePayer.toLowerCase()}' AND block_timestamp >= '${since}' ORDER BY block_timestamp ASC LIMIT ${candidateCap}`,
+            });
+            candidates = fetched.rows;
+        }
+        catch {
+            // Indexer outage must not fail intents; retry on the next pass.
+            continue;
+        }
+        for (const candidate of candidates) {
+            if (bySignPayload.size === 0)
+                break;
+            const hash = candidate['hash'];
+            const sender = candidate['from'];
+            if (!hash || !sender)
+                continue;
+            result.scanned++;
+            try {
+                const serialized = await getRawTransaction(getClient(chainId), hash);
+                if (!serialized?.startsWith(TxEnvelopeTempo.serializedType))
+                    continue;
+                const signPayload = TxEnvelopeTempo.getFeePayerSignPayload(TxEnvelopeTempo.deserialize(serialized), { sender });
+                const intent = bySignPayload.get(signPayload);
+                if (!intent)
+                    continue;
+                await SponsoredTransactions.assignTransactionHash(db, intent.id, hash);
+                bySignPayload.delete(signPayload);
+                result.matched++;
+            }
+            catch {
+                // Unresolvable candidate (lookup error, malformed envelope): skip it.
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Fetches a mined transaction's canonical envelope bytes.
+ * `eth_getRawTransactionByHash` is a node extension absent from viem's typed
+ * RPC schema, hence the request-fn narrowing.
+ */
+function getRawTransaction(client, hash) {
+    return client.request({ method: 'eth_getRawTransactionByHash', params: [hash] });
+}
+/**
+ * Builds a scheduled sponsorship finalizer bound to a database and RPC config.
+ * A host runtime drives {@link createFinalizer.Finalizer.tick} on a timer (a
+ * Cloudflare `scheduled` cron handler, a self-host `setInterval`, …); each
+ * tick reconciles fill intents (when `feePayer` + `tidx` are configured) and
+ * runs one {@link finalize} pass, with memoized per-chain clients.
+ */
+export function createFinalizer(options) {
+    const clients = new Map();
+    const getClient = (chainId) => {
+        let client = clients.get(chainId);
+        if (!client) {
+            client = Viem.getClient({ chainId: chainId, rpc: options.rpc });
+            clients.set(chainId, client);
+        }
+        return client;
+    };
+    const getTidx = options.tidx
+        ? Tidx.createGetClient({ defaultChainId: options.defaultChainId, tidx: options.tidx })
+        : undefined;
+    const feePayer = options.feePayer;
+    return {
+        async tick() {
+            // Resolve per tick so Workers factories build a fresh Hyperdrive-pooled
+            // connection each run.
+            const db = Db.get(options.db);
+            // Reconcile first so freshly matched intents finalize in the same tick.
+            const reconciled = feePayer && getTidx
+                ? await reconcile(db, {
+                    batchSize: options.batchSize,
+                    feePayer,
+                    getClient,
+                    getTidx: (chainId) => getTidx(chainId),
+                })
+                : { matched: 0, scanned: 0 };
+            const finalized = await finalize(db, {
+                batchSize: options.batchSize,
+                getClient,
+                now: options.now,
+                pendingTtlMs: options.pendingTtlMs,
+            });
+            return { ...finalized, ...reconciled };
+        },
+    };
+}
+//# sourceMappingURL=Sponsorships.js.map

package/dist/apps/relay/Sponsorships.js.map

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

package/dist/apps/relay/index.d.ts

@@ -0,0 +1,3 @@
+export { relay } from './App.js';
+export * as Sponsorships from './Sponsorships.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/apps/relay/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/apps/relay/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,UAAU,CAAA;AAChC,OAAO,KAAK,YAAY,MAAM,mBAAmB,CAAA"}

package/dist/apps/relay/index.js

@@ -0,0 +1,3 @@
+export { relay } from './App.js';
+export * as Sponsorships from './Sponsorships.js';
+//# sourceMappingURL=index.js.map

package/dist/apps/relay/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/apps/relay/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,UAAU,CAAA;AAChC,OAAO,KAAK,YAAY,MAAM,mBAAmB,CAAA"}

package/dist/{Cli.d.ts → cli/Cli.d.ts}

@@ -1,6 +1,17 @@
 import { Cli as incur_Cli, Fetch, type Openapi } from 'incur';
-/** Creates an incur CLI backed by a hosted Tempo API. */
-export declare function from(url: string | URL, options?: from.Options): incur_Cli.Cli<{}, undefined, undefined, undefined>;
+/**
+ * Creates an incur CLI backed by a hosted Tempo API, plus the super admin
+ * commands (`<cli> admin …`).
+ */
+export declare function from(url: string | URL, options?: from.Options): incur_Cli.Cli<{
+    [x: `${string} ${string} ${string}`]: {
+        args: {};
+        options: {
+            databaseUrl?: string | undefined;
+            dbSchema?: string | undefined;
+        };
+    };
+}, undefined, undefined, undefined>;
 export declare namespace from {
     /** Options for creating a Tempo API CLI from a hosted API. */
     type Options = {

package/dist/cli/Cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Cli.d.ts","sourceRoot":"","sources":["../../src/cli/Cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,IAAI,SAAS,EAAE,KAAK,EAAE,KAAK,OAAO,EAAE,MAAM,OAAO,CAAA;AAI7D;;;GAGG;AACH,wBAAgB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,EAAE,OAAO,GAAE,IAAI,CAAC,OAAY;;;;;;;;oCAkBjE;AAED,MAAM,CAAC,OAAO,WAAW,IAAI,CAAC;IAC5B,8DAA8D;IAC9D,KAAK,OAAO,GAAG;QACb,uBAAuB;QACvB,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;QAChC,gBAAgB;QAChB,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;QACzB,wEAAwE;QACxE,OAAO,CAAC,EAAE,OAAO,CAAC,aAAa,GAAG,SAAS,CAAA;QAC3C,4EAA4E;QAC5E,aAAa,CAAC,EAAE,OAAO,CAAC,MAAM,GAAG,SAAS,CAAA;QAC1C,4CAA4C;QAC5C,OAAO,CAAC,EAAE,KAAK,CAAC,WAAW,CAAC,OAAO,GAAG,SAAS,CAAA;QAC/C,mBAAmB;QACnB,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;KAC7B,CAAA;CACF"}

package/dist/cli/Cli.js

@@ -0,0 +1,19 @@
+import { Cli as incur_Cli, Fetch } from 'incur';
+import * as Admin from './commands/admin.js';
+/**
+ * Creates an incur CLI backed by a hosted Tempo API, plus the super admin
+ * commands (`<cli> admin …`).
+ */
+export function from(url, options = {}) {
+    const { description = 'Tempo API CLI', name = 'tapimo', openapi = 'openapi.json', request, version = '0.0.0', } = options;
+    return incur_Cli
+        .create(name, {
+        description,
+        fetch: Fetch.fromRequest(url, request),
+        openapi,
+        openapiConfig: options.openapiConfig ?? { mode: 'namespace' },
+        version,
+    })
+        .command(Admin.admin);
+}
+//# sourceMappingURL=Cli.js.map

package/dist/cli/Cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Cli.js","sourceRoot":"","sources":["../../src/cli/Cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,IAAI,SAAS,EAAE,KAAK,EAAgB,MAAM,OAAO,CAAA;AAE7D,OAAO,KAAK,KAAK,MAAM,qBAAqB,CAAA;AAE5C;;;GAGG;AACH,MAAM,UAAU,IAAI,CAAC,GAAiB,EAAE,OAAO,GAAiB,EAAE;IAChE,MAAM,EACJ,WAAW,GAAG,eAAe,EAC7B,IAAI,GAAG,QAAQ,EACf,OAAO,GAAG,cAAc,EACxB,OAAO,EACP,OAAO,GAAG,OAAO,GAClB,GAAG,OAAO,CAAA;IAEX,OAAO,SAAS;SACb,MAAM,CAAC,IAAI,EAAE;QACZ,WAAW;QACX,KAAK,EAAE,KAAK,CAAC,WAAW,CAAC,GAAG,EAAE,OAAO,CAAC;QACtC,OAAO;QACP,aAAa,EAAE,OAAO,CAAC,aAAa,IAAI,EAAE,IAAI,EAAE,WAAW,EAAE;QAC7D,OAAO;KACR,CAAC;SACD,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;AACzB,CAAC"}

package/dist/cli/bin.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/dist/cli/bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../../src/cli/bin.ts"],"names":[],"mappings":""}

package/dist/cli/bin.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import * as Cli from './Cli.js';
+await Cli.from('https://api.tempo.xyz').serve();
+//# sourceMappingURL=bin.js.map

package/dist/cli/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../../src/cli/bin.ts"],"names":[],"mappings":";AACA,OAAO,KAAK,GAAG,MAAM,UAAU,CAAA;AAE/B,MAAM,GAAG,CAAC,IAAI,CAAC,uBAAuB,CAAC,CAAC,KAAK,EAAE,CAAA"}

package/dist/cli/commands/admin.d.ts

@@ -0,0 +1,15 @@
+import { Cli as incur_Cli } from 'incur';
+/**
+ * Super admin commands that run against a deployment's infrastructure rather
+ * than the hosted API (database migrations, …).
+ */
+export declare const admin: incur_Cli.Cli<{
+    [x: `${string} ${string}`]: {
+        args: {};
+        options: {
+            databaseUrl?: string | undefined;
+            dbSchema?: string | undefined;
+        };
+    };
+}, undefined, undefined, undefined>;
+//# sourceMappingURL=admin.d.ts.map

package/dist/cli/commands/admin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/admin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,IAAI,SAAS,EAAK,MAAM,OAAO,CAAA;AAmD3C;;;GAGG;AACH,eAAO,MAAM,KAAK;;;;;;;;mCAIC,CAAA"}

package/dist/cli/commands/admin.js

@@ -0,0 +1,60 @@
+import { Cli as incur_Cli, z } from 'incur';
+import * as Db from '../../db/Db.js';
+/**
+ * Applies pending Postgres migrations, connecting directly via
+ * `--database-url` or `DATABASE_URL` (never through Hyperdrive — the migrate
+ * advisory lock needs session semantics); `--db-schema` scopes the session.
+ */
+const migrate = incur_Cli.create('migrate', {
+    description: 'Apply pending database migrations.',
+    env: z.object({
+        DATABASE_URL: z
+            .string()
+            .optional()
+            .describe('Postgres connection string. Used when --database-url is omitted.'),
+    }),
+    options: z.object({
+        databaseUrl: z
+            .string()
+            .optional()
+            .describe('Postgres connection string. Overrides DATABASE_URL.'),
+        dbSchema: z.string().optional().describe('Postgres schema to create and scope the session to.'),
+    }),
+    async run(c) {
+        const connectionString = c.options.databaseUrl ?? c.env.DATABASE_URL;
+        if (!connectionString)
+            return c.error({
+                code: 'missing_database_url',
+                message: 'Set --database-url or DATABASE_URL to the Postgres connection string.',
+            });
+        const db = Db.postgres({
+            connectionString,
+            ...(c.options.dbSchema ? { schema: c.options.dbSchema } : {}),
+        });
+        try {
+            await db.migrate();
+            return { migrated: true };
+        }
+        catch (error) {
+            /* v8 ignore next */
+            const message = error instanceof Error ? error.message : 'Migration failed.';
+            return c.error({
+                code: 'migrate_failed',
+                message,
+            });
+        }
+        finally {
+            await db.close();
+        }
+    },
+});
+/**
+ * Super admin commands that run against a deployment's infrastructure rather
+ * than the hosted API (database migrations, …).
+ */
+export const admin = incur_Cli
+    .create('admin', {
+    description: 'Super admin commands for a Tempo API deployment.',
+})
+    .command(migrate);
+//# sourceMappingURL=admin.js.map

package/dist/cli/commands/admin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin.js","sourceRoot":"","sources":["../../../src/cli/commands/admin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,IAAI,SAAS,EAAE,CAAC,EAAE,MAAM,OAAO,CAAA;AAE3C,OAAO,KAAK,EAAE,MAAM,gBAAgB,CAAA;AAEpC;;;;GAIG;AACH,MAAM,OAAO,GAAG,SAAS,CAAC,MAAM,CAAC,SAAS,EAAE;IAC1C,WAAW,EAAE,oCAAoC;IACjD,GAAG,EAAE,CAAC,CAAC,MAAM,CAAC;QACZ,YAAY,EAAE,CAAC;aACZ,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CAAC,kEAAkE,CAAC;KAChF,CAAC;IACF,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC;QAChB,WAAW,EAAE,CAAC;aACX,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CAAC,qDAAqD,CAAC;QAClE,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,qDAAqD,CAAC;KAChG,CAAC;IACF,KAAK,CAAC,GAAG,CAAC,CAAC;QACT,MAAM,gBAAgB,GAAG,CAAC,CAAC,OAAO,CAAC,WAAW,IAAI,CAAC,CAAC,GAAG,CAAC,YAAY,CAAA;QACpE,IAAI,CAAC,gBAAgB;YACnB,OAAO,CAAC,CAAC,KAAK,CAAC;gBACb,IAAI,EAAE,sBAAsB;gBAC5B,OAAO,EAAE,uEAAuE;aACjF,CAAC,CAAA;QACJ,MAAM,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC;YACrB,gBAAgB;YAChB,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC9D,CAAC,CAAA;QACF,IAAI,CAAC;YACH,MAAM,EAAE,CAAC,OAAO,EAAE,CAAA;YAClB,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAA;QAC3B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,oBAAoB;YACpB,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,mBAAmB,CAAA;YAC5E,OAAO,CAAC,CAAC,KAAK,CAAC;gBACb,IAAI,EAAE,gBAAgB;gBACtB,OAAO;aACR,CAAC,CAAA;QACJ,CAAC;gBAAS,CAAC;YACT,MAAM,EAAE,CAAC,KAAK,EAAE,CAAA;QAClB,CAAC;IACH,CAAC;CACF,CAAC,CAAA;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,SAAS;KAC3B,MAAM,CAAC,OAAO,EAAE;IACf,WAAW,EAAE,kDAAkD;CAChE,CAAC;KACD,OAAO,CAAC,OAAO,CAAC,CAAA"}

package/dist/cloudflare.d.ts

@@ -27,6 +27,13 @@ export declare class DurableObject extends CloudflareDurableObject {
     }>;
     /** Writes a string value, optionally with a time-to-live. */
     put(key: string, value: string, options?: Store.Store.PutOptions): Promise<void>;
+    /**
+     * Atomically compares-and-swaps a value.
+     *
+     * The compare and write run on the object's single thread behind its input
+     * gate, so concurrent callers cannot interleave between them.
+     */
+    swap(key: string, expected: null | string, next: string, options?: Store.Store.PutOptions): Promise<boolean>;
 }
 export {};
 //# sourceMappingURL=cloudflare.d.ts.map

package/dist/cloudflare.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cloudflare.d.ts","sourceRoot":"","sources":["../src/cloudflare.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,aAAa,IAAI,uBAAuB,EAAE,MAAM,oBAAoB,CAAA;AAE7E,OAAO,KAAK,KAAK,MAAM,qBAAqB,CAAA;AAE5C,KAAK,KAAK,GAAG,qBAAqB,CAAC,OAAO,uBAAuB,CAAC,CAAC,CAAC,CAAC,CAAA;AACrE,KAAK,WAAW,GAAG,qBAAqB,CAAC,OAAO,uBAAuB,CAAC,CAAC,CAAC,CAAC,CAAA;AAE3E,+EAA+E;AAC/E,qBAAa,aAAc,SAAQ,uBAAuB;;IAGxD,YAAY,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,WAAW,EAMvC;IAED,qBAAqB;IACf,MAAM,CAAC,GAAG,EAAE,MAAM,iBAEvB;IAED,uEAAuE;IACjE,GAAG,CAAC,GAAG,EAAE,MAAM,0BAEpB;IAED;;;;;;;OAOG;IACG,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,UAAU,mBAE5D;IAED,kBAAkB;IACZ,IAAI,CAAC,OAAO,CAAC,EAAE,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;;;;OAEtD;IAED,6DAA6D;IACvD,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,UAAU,iBAErE;CACF"}
+{"version":3,"file":"cloudflare.d.ts","sourceRoot":"","sources":["../src/cloudflare.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,aAAa,IAAI,uBAAuB,EAAE,MAAM,oBAAoB,CAAA;AAE7E,OAAO,KAAK,KAAK,MAAM,qBAAqB,CAAA;AAE5C,KAAK,KAAK,GAAG,qBAAqB,CAAC,OAAO,uBAAuB,CAAC,CAAC,CAAC,CAAC,CAAA;AACrE,KAAK,WAAW,GAAG,qBAAqB,CAAC,OAAO,uBAAuB,CAAC,CAAC,CAAC,CAAC,CAAA;AAE3E,+EAA+E;AAC/E,qBAAa,aAAc,SAAQ,uBAAuB;;IAGxD,YAAY,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,WAAW,EAMvC;IAED,qBAAqB;IACf,MAAM,CAAC,GAAG,EAAE,MAAM,iBAEvB;IAED,uEAAuE;IACjE,GAAG,CAAC,GAAG,EAAE,MAAM,0BAEpB;IAED;;;;;;;OAOG;IACG,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,UAAU,mBAE5D;IAED,kBAAkB;IACZ,IAAI,CAAC,OAAO,CAAC,EAAE,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;;;;OAEtD;IAED,6DAA6D;IACvD,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,UAAU,iBAErE;IAED;;;;;OAKG;IACG,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,GAAG,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,UAAU,oBAE9F;CACF"}

package/dist/cloudflare.js

@@ -41,5 +41,14 @@ export class DurableObject extends CloudflareDurableObject {
     async put(key, value, options) {
         await this.#store.put(key, value, options);
     }
+    /**
+     * Atomically compares-and-swaps a value.
+     *
+     * The compare and write run on the object's single thread behind its input
+     * gate, so concurrent callers cannot interleave between them.
+     */
+    async swap(key, expected, next, options) {
+        return this.#store.swap(key, expected, next, options);
+    }
 }
 //# sourceMappingURL=cloudflare.js.map

package/dist/cloudflare.js.map

@@ -1 +1 @@
-{"version":3,"file":"cloudflare.js","sourceRoot":"","sources":["../src/cloudflare.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,4EAA4E;AAC5E,kCAAkC;AAClC,aAAa;AACb,OAAO,EAAE,aAAa,IAAI,uBAAuB,EAAE,MAAM,oBAAoB,CAAA;AAE7E,OAAO,KAAK,KAAK,MAAM,qBAAqB,CAAA;AAK5C,+EAA+E;AAC/E,MAAM,OAAO,aAAc,SAAQ,uBAAuB;IACxD,MAAM,CAAa;IAEnB,YAAY,GAAU,EAAE,GAAgB;QACtC,uEAAuE;QACvE,6EAA6E;QAC7E,KAAK,CAAC,GAAG,EAAE,GAAY,CAAC,CAAA;QACxB,MAAM,EAAE,OAAO,EAAE,GAAG,GAA+C,CAAA;QACnE,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,aAAa,CAAC,OAAO,CAAC,CAAA;IAC5C,CAAC;IAED,qBAAqB;IACrB,KAAK,CAAC,MAAM,CAAC,GAAW;QACtB,MAAM,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;IAC/B,CAAC;IAED,uEAAuE;IACvE,KAAK,CAAC,GAAG,CAAC,GAAW;QACnB,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IAC7B,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,SAAS,CAAC,GAAW,EAAE,OAAgC;QAC3D,OAAO,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,OAAO,CAAC,CAAA;IACnD,CAAC;IAED,kBAAkB;IAClB,KAAK,CAAC,IAAI,CAAC,OAA4C;QACrD,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;IAClC,CAAC;IAED,6DAA6D;IAC7D,KAAK,CAAC,GAAG,CAAC,GAAW,EAAE,KAAa,EAAE,OAAgC;QACpE,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,EAAE,OAAO,CAAC,CAAA;IAC5C,CAAC;CACF"}
+{"version":3,"file":"cloudflare.js","sourceRoot":"","sources":["../src/cloudflare.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,4EAA4E;AAC5E,kCAAkC;AAClC,aAAa;AACb,OAAO,EAAE,aAAa,IAAI,uBAAuB,EAAE,MAAM,oBAAoB,CAAA;AAE7E,OAAO,KAAK,KAAK,MAAM,qBAAqB,CAAA;AAK5C,+EAA+E;AAC/E,MAAM,OAAO,aAAc,SAAQ,uBAAuB;IACxD,MAAM,CAAa;IAEnB,YAAY,GAAU,EAAE,GAAgB;QACtC,uEAAuE;QACvE,6EAA6E;QAC7E,KAAK,CAAC,GAAG,EAAE,GAAY,CAAC,CAAA;QACxB,MAAM,EAAE,OAAO,EAAE,GAAG,GAA+C,CAAA;QACnE,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,aAAa,CAAC,OAAO,CAAC,CAAA;IAC5C,CAAC;IAED,qBAAqB;IACrB,KAAK,CAAC,MAAM,CAAC,GAAW;QACtB,MAAM,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;IAC/B,CAAC;IAED,uEAAuE;IACvE,KAAK,CAAC,GAAG,CAAC,GAAW;QACnB,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IAC7B,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,SAAS,CAAC,GAAW,EAAE,OAAgC;QAC3D,OAAO,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,OAAO,CAAC,CAAA;IACnD,CAAC;IAED,kBAAkB;IAClB,KAAK,CAAC,IAAI,CAAC,OAA4C;QACrD,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;IAClC,CAAC;IAED,6DAA6D;IAC7D,KAAK,CAAC,GAAG,CAAC,GAAW,EAAE,KAAa,EAAE,OAAgC;QACpE,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,EAAE,OAAO,CAAC,CAAA;IAC5C,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,IAAI,CAAC,GAAW,EAAE,QAAuB,EAAE,IAAY,EAAE,OAAgC;QAC7F,OAAO,IAAI,CAAC,MAAM,CAAC,IAAK,CAAC,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,CAAC,CAAA;IACxD,CAAC;CACF"}

package/dist/db/Db.d.ts

@@ -0,0 +1,113 @@
+import { type Compilable, type Dialect, Kysely } from 'kysely';
+import type * as Invitations from './tables/invitations.js';
+import type * as Memberships from './tables/memberships.js';
+import type * as Organizations from './tables/organizations.js';
+import type * as Projects from './tables/projects.js';
+import type * as SponsoredTransactions from './tables/sponsoredTransactions.js';
+import type * as Users from './tables/users.js';
+import type * as VerifiedTokens from './tables/verifiedTokens.js';
+import type * as WebhookDeliveries from './tables/webhookDeliveries.js';
+import type * as WebhookSubscriptions from './tables/webhookSubscriptions.js';
+/**
+ * Kysely schema with camelCase columns. {@link CamelCasePlugin} maps table
+ * records, queries, and {@link migrations} DDL to snake_case storage columns.
+ */
+export type Database = {
+    migrations: {
+        appliedAt: string;
+        checksum: string;
+        name: string;
+        /** SQL as applied; null on rows written before the column existed. */
+        sql: string | null;
+    };
+    invitations: Invitations.Table;
+    memberships: Memberships.Table;
+    organizations: Organizations.Table;
+    projects: Projects.Table;
+    sponsored_transactions: SponsoredTransactions.Table;
+    users: Users.Table;
+    verified_token_lists: VerifiedTokens.ListTable;
+    verified_tokens: VerifiedTokens.Table;
+    webhook_deliveries: WebhookDeliveries.Table;
+    webhook_subscriptions: WebhookSubscriptions.Table;
+};
+/**
+ * A SQL-backed authoritative store: the underlying Kysely handle (table
+ * repository modules query through it), schema migrations, and transactions.
+ */
+export type Db = {
+    /** Closes the underlying connection/pool. */
+    close(): Promise<void>;
+    /**
+     * Underlying Kysely handle. Transaction-scoped {@link Db} values carry the
+     * transaction handle, so repositories called with `tx` run inside it. */
+    kysely: Kysely<Database>;
+    /** Applies any pending schema migrations; safe to call repeatedly and concurrently. */
+    migrate(): Promise<void>;
+    /**
+     * Runs `fn` in a transaction — commits on return, rolls back on throw. `fn`
+     * receives a transaction-scoped {@link Db}; pass it (not the outer `Db`) to
+     * repositories so every query inside runs in the transaction.
+     */
+    transaction<value>(fn: (tx: Db) => Promise<value>): Promise<value>;
+};
+/**
+ * A {@link Db}, or a factory for per-request Workers/Hyperdrive connections.
+ * Node can pass a long-lived singleton. Resolve at the leaf with {@link get}.
+ */
+export type Source = Db | (() => Db);
+/**
+ * Resolves a {@link Source} to a {@link Db}. Call at the request leaf so
+ * factories create per-request instances; singletons resolve to themselves.
+ *
+ * @param source - The database or factory.
+ * @returns The resolved {@link Db}.
+ */
+export declare function get(source: Source): Db;
+/**
+ * One schema migration. `up` builds a single idempotent Kysely DDL statement;
+ * {@link Db.migrate} compiles it for the checksum, then applies it.
+ */
+type Migration = {
+    /** Unique, ordered migration name (e.g. `0001_organizations`). */
+    name: string;
+    /**
+     * Builds the migration's DDL against `db`. Use `.ifNotExists()` so the
+     * statement is safe to re-run without a wrapping transaction. */
+    up: (db: Kysely<Database>) => Compilable & {
+        execute(): Promise<unknown>;
+    };
+};
+/**
+ * Ordered schema migrations for {@link Db.migrate}. Each `up` is one
+ * idempotent statement; compiled-SQL FNV-1a checksums reject edited applied
+ * migrations.
+ */
+export declare const migrations: readonly Migration[];
+/**
+ * Builds a {@link Db} for any Kysely {@link Dialect}. All backends share
+ * migrations, repositories, and the required {@link CamelCasePlugin} mapping.
+ *
+ * @param dialect - The Kysely dialect for the target backend.
+ * @returns The database.
+ */
+export declare function from(dialect: Dialect): Db;
+/**
+ * Creates a Postgres-backed {@link Db} via Kysely's `PostgresDialect`. Optional
+ * `schema` scopes every pooled connection and caps the pool for test isolation.
+ *
+ * @param options - Postgres options.
+ * @returns The database.
+ */
+export declare function postgres(options: postgres.Options): Db;
+export declare namespace postgres {
+    /** Options for {@link postgres}. */
+    type Options = {
+        /** Postgres connection string (`postgresql://…`). */
+        connectionString: string;
+        /** Schema to create and scope the session to (isolates concurrent tests). */
+        schema?: string | undefined;
+    };
+}
+export {};
+//# sourceMappingURL=Db.d.ts.map

package/dist/db/Db.d.ts.map

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