tapimo 0.1.0 → 0.3.0

package/dist/db/tables/sponsoredTransactions.d.ts

@@ -0,0 +1,239 @@
+import type { Selectable } from 'kysely';
+import type * as Db from '../Db.js';
+import type * as db_Schema from '../Schema.js';
+/** Columns of the `sponsored_transactions` table, derived from `Schema.SponsoredTransaction`. */
+export type Table = db_Schema.SponsoredTransaction;
+/** A stored sponsored-transaction row. */
+export type Record = Selectable<Table>;
+/**
+ * Records one sponsorship commitment as `pending`, keyed by its fee-payer
+ * sign payload. Written after fee-payer signing and before any broadcast, so
+ * no sponsored transaction goes unrecorded; a later recording site for the
+ * same envelope (raw submission after a fill intent) upgrades the row with
+ * its transaction hash, reopening failed rows for finalization.
+ *
+ * @param db - The database.
+ * @param input - Attribution and envelope facts captured at signing time.
+ * @returns The stored record.
+ */
+export declare function upsert(db: Db.Db, input: upsert.Input): Promise<Record>;
+export declare namespace upsert {
+    /** Attribution and envelope facts recorded at sponsorship time. */
+    type Input = {
+        /** API key id (`key_…`) that requested sponsorship. */
+        apiKeyId: string;
+        /** Whether the sponsorship accrues billable spend; false for sandbox. */
+        billable: boolean;
+        /** Chain the sponsored transaction targets. */
+        chainId: number;
+        /** Lowercase fee currency snapshot (`usd`), when resolved. */
+        currency?: string | undefined;
+        /** Key environment the sponsorship was requested under. */
+        environment: Table['environment'];
+        /** Signed fee cap (`gas × maxFeePerGas`) in base units, when known. */
+        feeMax?: string | undefined;
+        /** Fee token the sponsorship resolved, when known. */
+        feeToken?: string | undefined;
+        /** Organization id (`org_…`) the spend attributes to. */
+        orgId: string;
+        /** Project id (`prj_…`) the spend attributes to. */
+        projectId: string;
+        /** Fee-payer sign payload — a stable identity for the sponsored envelope. */
+        signPayload: string;
+        /** Serialized sponsored transaction, kept for observability beyond log retention. */
+        transaction: string;
+        /** Transaction hash; omit for fill intents, whose senders have not signed yet. */
+        transactionHash?: string | undefined;
+    };
+}
+/**
+ * Reads one sponsorship row by id.
+ *
+ * @param db - The database.
+ * @param id - The sponsored-transaction id (`stx_…`).
+ * @returns The record, or `undefined` when absent.
+ */
+export declare function get(db: Db.Db, id: string): Promise<Record | undefined>;
+/**
+ * Lists pending sponsorships, oldest first, for the finalization job.
+ *
+ * @param db - The database.
+ * @param options - Paging options.
+ * @returns The pending records.
+ */
+export declare function listPending(db: Db.Db, options?: listPending.Options): Promise<Record[]>;
+export declare namespace listPending {
+    /** Options for {@link listPending}. */
+    type Options = {
+        /** Maximum rows to return. */
+        limit?: number | undefined;
+    };
+}
+/**
+ * Lists hash-less fill intents, oldest first, for the reconciliation pass.
+ * Failed intents are included only when the caller supplies a recovery floor.
+ *
+ * @param db - The database.
+ * @param options - Paging options.
+ * @returns The pending intents.
+ */
+export declare function listIntents(db: Db.Db, options?: listIntents.Options): Promise<Record[]>;
+export declare namespace listIntents {
+    /** Options for {@link listIntents}. */
+    type Options = listPending.Options & {
+        /** Include failed intents whose terminal timestamp is at or after this ISO timestamp. */
+        failedSince?: string | undefined;
+    };
+}
+/**
+ * Fills a reconciled intent's transaction hash and reopens failed intents.
+ * A no-op once another pass already assigned the hash.
+ *
+ * @param db - The database.
+ * @param id - The sponsored-transaction id (`stx_…`).
+ * @param transactionHash - The matched on-chain transaction hash.
+ */
+export declare function assignTransactionHash(db: Db.Db, id: string, transactionHash: string): Promise<void>;
+/**
+ * Transitions a pending sponsorship to `finalized` with the receipt's actual
+ * fee. A no-op when the row is no longer pending (idempotent re-runs).
+ *
+ * @param db - The database.
+ * @param id - The sponsored-transaction id (`stx_…`).
+ * @param input - The finalized fee facts.
+ */
+export declare function finalize(db: Db.Db, id: string, input: finalize.Input): Promise<void>;
+export declare namespace finalize {
+    /** Fee facts resolved from the transaction receipt. */
+    type Input = {
+        /** Actual fee paid in fee-token base units. */
+        feeAmount: string;
+        /** When the sponsorship finalized (ISO 8601). */
+        finalizedAt: string;
+    };
+}
+/**
+ * Transitions a pending sponsorship to `failed` (never landed within the
+ * pending TTL). A no-op when the row is no longer pending.
+ *
+ * @param db - The database.
+ * @param id - The sponsored-transaction id (`stx_…`).
+ * @param finalizedAt - When the sponsorship was marked failed (ISO 8601).
+ */
+export declare function fail(db: Db.Db, id: string, finalizedAt: string): Promise<void>;
+/**
+ * Records a sponsorship and enforces the period spend limit atomically. A
+ * per-org advisory lock serializes concurrent sponsorships so each one's
+ * signed cap is counted before the limit check; without it a burst reads
+ * pre-burst spend and overshoots. Throws {@link PeriodSpendLimitError} (rolling
+ * back the row) when the limit would be exceeded.
+ *
+ * @param db - The database (primary; never a cached replica).
+ * @param input - The sponsorship to record.
+ * @param limit - The period spend limit to enforce.
+ * @returns The stored record.
+ */
+export declare function reserve(db: Db.Db, input: upsert.Input, limit: reserve.Limit): Promise<Record>;
+export declare namespace reserve {
+    /** The period spend limit enforced by {@link reserve}. */
+    type Limit = {
+        /** Chains whose spend counts (mainnet chain ids). */
+        chainIds: readonly number[];
+        /** Limit in fee-token base units. */
+        max: bigint;
+        /** Window start (ISO 8601). */
+        since: string;
+    };
+}
+/**
+ * Billable spend committed since a cutoff, in fee-token base units: finalized
+ * rows at their actual fee plus pending rows at their signed fee cap, so
+ * in-flight sponsorships consume limit budget until receipts land.
+ *
+ * @param db - The database.
+ * @param options - Aggregation scope.
+ * @returns The committed spend in base units.
+ */
+export declare function spend(db: Db.Db, options: spend.Options): Promise<bigint>;
+export declare namespace spend {
+    /** Options for {@link spend}. */
+    type Options = {
+        /** Chains whose spend counts (mainnet chain ids). */
+        chainIds: readonly number[];
+        /** Environment whose spend counts; production mirrors the billing gate, sandbox is display-only. Defaults to `production`. */
+        environment?: Table['environment'] | undefined;
+        /** Organization id (`org_…`) the spend attributes to. */
+        orgId: string;
+        /** Window start (ISO 8601); rows created earlier are out of scope. */
+        since: string;
+    };
+}
+/**
+ * Sponsorship usage bucketed by time for one organization: row counts and
+ * committed fees per bucket. Fee semantics mirror {@link spend}: finalized
+ * rows at their actual fee, pending rows at their signed cap, failed rows at
+ * zero. Buckets with no rows are omitted.
+ *
+ * @param db - The database.
+ * @param options - Aggregation scope.
+ * @returns Time-ordered usage buckets.
+ */
+export declare function usage(db: Db.Db, options: usage.Options): Promise<usage.Bucket[]>;
+export declare namespace usage {
+    /** One time bucket of sponsorship usage. */
+    type Bucket = {
+        /** Sponsored transactions recorded in the bucket, any status. */
+        count: number;
+        /** Committed fees in fee-token base units: finalized fees plus pending caps. */
+        feeTotal: bigint;
+        /** Bucket start (ISO 8601), aligned to UTC calendar boundaries. */
+        timestamp: string;
+    };
+    /** Options for {@link usage}. */
+    type Options = {
+        /** Key environment to restrict to; omit for all. */
+        environment?: Table['environment'] | undefined;
+        /** Window start (ISO 8601), inclusive. */
+        from: string;
+        /** Bucket width, aligned to UTC calendar boundaries. */
+        interval: 'day' | 'hour' | 'month' | 'week';
+        /** Organization id (`org_…`) the usage attributes to. */
+        orgId: string;
+        /** Project id (`prj_…`) to restrict to; omit for all. */
+        projectId?: string | undefined;
+        /** Window end (ISO 8601), exclusive. */
+        to: string;
+    };
+}
+/**
+ * Lists finalized billable rows not yet reported to the billing meter, oldest
+ * first, for the metering job.
+ *
+ * @param db - The database.
+ * @param options - Reporting scope.
+ * @returns The unreported records.
+ */
+export declare function listUnreported(db: Db.Db, options: listUnreported.Options): Promise<Record[]>;
+export declare namespace listUnreported {
+    /** Options for {@link listUnreported}. */
+    type Options = {
+        /** Chains whose spend is metered (mainnet chain ids). */
+        chainIds: readonly number[];
+        /** Maximum rows to return. */
+        limit?: number | undefined;
+    };
+}
+/**
+ * Marks a row as reported to the billing meter. A no-op once marked — the
+ * durable exactly-once guard for the metering job.
+ *
+ * @param db - The database.
+ * @param id - The sponsored-transaction id (`stx_…`).
+ * @param at - When the report was acknowledged (ISO 8601).
+ */
+export declare function markReported(db: Db.Db, id: string, at: string): Promise<void>;
+/** Thrown by {@link reserve} when recording would exceed the org's period spend limit. */
+export declare class PeriodSpendLimitError extends Error {
+    name: string;
+}
+//# sourceMappingURL=sponsoredTransactions.d.ts.map

package/dist/db/tables/sponsoredTransactions.d.ts.map

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

package/dist/db/tables/sponsoredTransactions.js

@@ -0,0 +1,314 @@
+import { sql } from 'kysely';
+import * as Id from '../../internal/Id.js';
+/**
+ * Records one sponsorship commitment as `pending`, keyed by its fee-payer
+ * sign payload. Written after fee-payer signing and before any broadcast, so
+ * no sponsored transaction goes unrecorded; a later recording site for the
+ * same envelope (raw submission after a fill intent) upgrades the row with
+ * its transaction hash, reopening failed rows for finalization.
+ *
+ * @param db - The database.
+ * @param input - Attribution and envelope facts captured at signing time.
+ * @returns The stored record.
+ */
+export async function upsert(db, input) {
+    const record = {
+        apiKeyId: input.apiKeyId,
+        billable: input.billable,
+        chainId: input.chainId,
+        createdAt: new Date().toISOString(),
+        currency: input.currency ?? null,
+        environment: input.environment,
+        feeAmount: null,
+        feeMax: input.feeMax ?? null,
+        feeToken: input.feeToken ?? null,
+        finalizedAt: null,
+        id: Id.generate('stx'),
+        meterReportedAt: null,
+        orgId: input.orgId,
+        projectId: input.projectId,
+        signPayload: input.signPayload,
+        status: 'pending',
+        transaction: input.transaction,
+        transactionHash: input.transactionHash ?? null,
+    };
+    return await db.kysely
+        .insertInto('sponsored_transactions')
+        .values(record)
+        .onConflict((oc) => oc.column('signPayload').doUpdateSet((eb) => ({
+        // Same sign payload = same envelope = same cap; only fills older nulls.
+        currency: eb.fn.coalesce(eb.ref('sponsored_transactions.currency'), eb.ref('excluded.currency')), // prettier-ignore
+        feeMax: eb.fn.coalesce(eb.ref('sponsored_transactions.feeMax'), eb.ref('excluded.feeMax')),
+        // A raw submission fills the intent's hash; a duplicate intent never
+        // clears an already-known hash.
+        transactionHash: eb.fn.coalesce(eb.ref('excluded.transactionHash'), eb.ref('sponsored_transactions.transactionHash')),
+        createdAt: sql `CASE WHEN ${eb.ref('sponsored_transactions.status')} = 'failed' THEN ${eb.ref('excluded.createdAt')} ELSE ${eb.ref('sponsored_transactions.createdAt')} END`,
+        finalizedAt: sql `CASE WHEN ${eb.ref('sponsored_transactions.status')} = 'failed' THEN NULL ELSE ${eb.ref('sponsored_transactions.finalizedAt')} END`,
+        status: sql `CASE WHEN ${eb.ref('sponsored_transactions.status')} = 'failed' THEN 'pending' ELSE ${eb.ref('sponsored_transactions.status')} END`,
+    })))
+        .returningAll()
+        .executeTakeFirstOrThrow();
+}
+/**
+ * Reads one sponsorship row by id.
+ *
+ * @param db - The database.
+ * @param id - The sponsored-transaction id (`stx_…`).
+ * @returns The record, or `undefined` when absent.
+ */
+export function get(db, id) {
+    return db.kysely
+        .selectFrom('sponsored_transactions')
+        .selectAll()
+        .where('id', '=', id)
+        .executeTakeFirst();
+}
+/**
+ * Lists pending sponsorships, oldest first, for the finalization job.
+ *
+ * @param db - The database.
+ * @param options - Paging options.
+ * @returns The pending records.
+ */
+export function listPending(db, options = {}) {
+    let query = db.kysely
+        .selectFrom('sponsored_transactions')
+        .selectAll()
+        .where('status', '=', 'pending')
+        // `id` breaks same-millisecond `createdAt` ties for a deterministic scan.
+        .orderBy('createdAt', 'asc')
+        .orderBy('id', 'asc');
+    if (options.limit !== undefined)
+        query = query.limit(options.limit);
+    return query.execute();
+}
+/**
+ * Lists hash-less fill intents, oldest first, for the reconciliation pass.
+ * Failed intents are included only when the caller supplies a recovery floor.
+ *
+ * @param db - The database.
+ * @param options - Paging options.
+ * @returns The pending intents.
+ */
+export function listIntents(db, options = {}) {
+    let query = db.kysely
+        .selectFrom('sponsored_transactions')
+        .selectAll()
+        .where(intentStatus(options.failedSince))
+        .where('transactionHash', 'is', null)
+        // `pending` sorts after `failed`; descending keeps active intents first.
+        .orderBy('status', 'desc')
+        .orderBy('createdAt', 'asc')
+        .orderBy('id', 'asc');
+    if (options.limit !== undefined)
+        query = query.limit(options.limit);
+    return query.execute();
+}
+/**
+ * Fills a reconciled intent's transaction hash and reopens failed intents.
+ * A no-op once another pass already assigned the hash.
+ *
+ * @param db - The database.
+ * @param id - The sponsored-transaction id (`stx_…`).
+ * @param transactionHash - The matched on-chain transaction hash.
+ */
+export async function assignTransactionHash(db, id, transactionHash) {
+    await db.kysely
+        .updateTable('sponsored_transactions')
+        .set({ finalizedAt: null, status: 'pending', transactionHash })
+        .where('id', '=', id)
+        .where('status', 'in', ['failed', 'pending'])
+        .where('transactionHash', 'is', null)
+        .execute();
+}
+/**
+ * Transitions a pending sponsorship to `finalized` with the receipt's actual
+ * fee. A no-op when the row is no longer pending (idempotent re-runs).
+ *
+ * @param db - The database.
+ * @param id - The sponsored-transaction id (`stx_…`).
+ * @param input - The finalized fee facts.
+ */
+export async function finalize(db, id, input) {
+    await db.kysely
+        .updateTable('sponsored_transactions')
+        .set({ feeAmount: input.feeAmount, finalizedAt: input.finalizedAt, status: 'finalized' })
+        .where('id', '=', id)
+        .where('status', '=', 'pending')
+        .execute();
+}
+/**
+ * Transitions a pending sponsorship to `failed` (never landed within the
+ * pending TTL). A no-op when the row is no longer pending.
+ *
+ * @param db - The database.
+ * @param id - The sponsored-transaction id (`stx_…`).
+ * @param finalizedAt - When the sponsorship was marked failed (ISO 8601).
+ */
+export async function fail(db, id, finalizedAt) {
+    await db.kysely
+        .updateTable('sponsored_transactions')
+        .set({ finalizedAt, status: 'failed' })
+        .where('id', '=', id)
+        .where('status', '=', 'pending')
+        .execute();
+}
+/**
+ * Records a sponsorship and enforces the period spend limit atomically. A
+ * per-org advisory lock serializes concurrent sponsorships so each one's
+ * signed cap is counted before the limit check; without it a burst reads
+ * pre-burst spend and overshoots. Throws {@link PeriodSpendLimitError} (rolling
+ * back the row) when the limit would be exceeded.
+ *
+ * @param db - The database (primary; never a cached replica).
+ * @param input - The sponsorship to record.
+ * @param limit - The period spend limit to enforce.
+ * @returns The stored record.
+ */
+export async function reserve(db, input, limit) {
+    return db.transaction(async (tx) => {
+        // `hashtext` maps the org id into the advisory-lock keyspace; the class
+        // namespaces it against other advisory-lock users. Released at tx end.
+        await sql `select pg_advisory_xact_lock(${billingLockClass}, hashtext(${input.orgId}))`.execute(tx.kysely); // prettier-ignore
+        const record = await upsert(tx, input);
+        if (record.billable) {
+            const committed = await spend(tx, {
+                chainIds: limit.chainIds,
+                orgId: input.orgId,
+                since: limit.since,
+            });
+            if (committed > limit.max)
+                throw new PeriodSpendLimitError();
+        }
+        return record;
+    });
+}
+/** Advisory-lock class namespacing per-org sponsorship serialization. */
+const billingLockClass = 1112294220;
+/**
+ * Billable spend committed since a cutoff, in fee-token base units: finalized
+ * rows at their actual fee plus pending rows at their signed fee cap, so
+ * in-flight sponsorships consume limit budget until receipts land.
+ *
+ * @param db - The database.
+ * @param options - Aggregation scope.
+ * @returns The committed spend in base units.
+ */
+export async function spend(db, options) {
+    const { chainIds, environment = 'production', orgId, since } = options;
+    const query = db.kysely
+        .selectFrom('sponsored_transactions')
+        .select([
+        sql `coalesce(sum(case when status = 'finalized' then fee_amount::numeric else 0 end), 0)`.as('finalized'), // prettier-ignore
+        sql `coalesce(sum(case when status = 'pending' then fee_max::numeric else 0 end), 0)`.as('pending'), // prettier-ignore
+    ])
+        .where('orgId', '=', orgId)
+        .where('environment', '=', environment)
+        // Redundant with the CASE arms, but lets the billing index's
+        // (org_id, status, created_at) shape serve the range scan.
+        .where('status', 'in', ['finalized', 'pending'])
+        .where('chainId', 'in', [...chainIds])
+        .where('createdAt', '>=', since);
+    // Production mirrors the sponsorship gate — only billable rows count. Sandbox
+    // rows are non-billable by construction, so the figure is display-only.
+    const row = await (environment === 'production' ? query.where('billable', '=', true) : query) //
+        .executeTakeFirstOrThrow();
+    return BigInt(row.finalized) + BigInt(row.pending);
+}
+/**
+ * Sponsorship usage bucketed by time for one organization: row counts and
+ * committed fees per bucket. Fee semantics mirror {@link spend}: finalized
+ * rows at their actual fee, pending rows at their signed cap, failed rows at
+ * zero. Buckets with no rows are omitted.
+ *
+ * @param db - The database.
+ * @param options - Aggregation scope.
+ * @returns Time-ordered usage buckets.
+ */
+export async function usage(db, options) {
+    // TODO: convert to an OLAP-friendly approach (rollup table or columnar store)
+    // when per-org range scans grow slow.
+    const { environment, from, interval, orgId, projectId, to } = options;
+    // `sql.lit` inlines the enum-validated interval so the GROUP BY expression
+    // matches the SELECT expression textually; truncation happens in UTC wall
+    // time regardless of the session time zone.
+    const bucket = sql `date_trunc(${sql.lit(interval)}, (created_at::timestamptz) at time zone 'UTC')`;
+    let query = db.kysely
+        .selectFrom('sponsored_transactions')
+        .select([
+        sql `to_char(${bucket}, 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"')`.as('timestamp'),
+        sql `count(*)`.as('count'),
+        sql `coalesce(sum(case when status = 'finalized' then fee_amount::numeric when status = 'pending' then fee_max::numeric else 0 end), 0)`.as('feeTotal'), // prettier-ignore
+    ])
+        .where('orgId', '=', orgId)
+        // Text-range bounds keep the (org_id, created_at) index serving the scan.
+        .where('createdAt', '>=', from)
+        .where('createdAt', '<', to)
+        .groupBy(bucket)
+        .orderBy(bucket);
+    if (environment !== undefined)
+        query = query.where('environment', '=', environment);
+    if (projectId !== undefined)
+        query = query.where('projectId', '=', projectId);
+    const rows = await query.execute();
+    return rows.map((row) => ({
+        count: Number(row.count),
+        feeTotal: BigInt(row.feeTotal),
+        timestamp: row.timestamp,
+    }));
+}
+/**
+ * Lists finalized billable rows not yet reported to the billing meter, oldest
+ * first, for the metering job.
+ *
+ * @param db - The database.
+ * @param options - Reporting scope.
+ * @returns The unreported records.
+ */
+export function listUnreported(db, options) {
+    let query = db.kysely
+        .selectFrom('sponsored_transactions')
+        .selectAll()
+        .where('status', '=', 'finalized')
+        .where('billable', '=', true)
+        .where('chainId', 'in', [...options.chainIds])
+        .where('meterReportedAt', 'is', null)
+        // `id` breaks same-millisecond `finalizedAt` ties for a deterministic scan.
+        .orderBy('finalizedAt', 'asc')
+        .orderBy('id', 'asc');
+    if (options.limit !== undefined)
+        query = query.limit(options.limit);
+    return query.execute();
+}
+/**
+ * Marks a row as reported to the billing meter. A no-op once marked — the
+ * durable exactly-once guard for the metering job.
+ *
+ * @param db - The database.
+ * @param id - The sponsored-transaction id (`stx_…`).
+ * @param at - When the report was acknowledged (ISO 8601).
+ */
+export async function markReported(db, id, at) {
+    await db.kysely
+        .updateTable('sponsored_transactions')
+        .set({ meterReportedAt: at })
+        .where('id', '=', id)
+        .where('meterReportedAt', 'is', null)
+        .execute();
+}
+/** Intent status predicate; failed rows are recovery candidates only briefly. */
+function intentStatus(failedSince) {
+    return (eb) => {
+        if (failedSince === undefined)
+            return eb('status', '=', 'pending');
+        return eb.or([
+            eb('status', '=', 'pending'),
+            eb.and([eb('status', '=', 'failed'), eb('finalizedAt', '>=', failedSince)]),
+        ]);
+    };
+}
+/** Thrown by {@link reserve} when recording would exceed the org's period spend limit. */
+export class PeriodSpendLimitError extends Error {
+    name = 'SponsoredTransactions.PeriodSpendLimitError';
+}
+//# sourceMappingURL=sponsoredTransactions.js.map

package/dist/db/tables/sponsoredTransactions.js.map

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

package/dist/db/tables/stripeCustomers.d.ts

@@ -0,0 +1,81 @@
+import type { Selectable } from 'kysely';
+import type * as Db from '../Db.js';
+import type * as db_Schema from '../Schema.js';
+/** Columns of the `stripe_customers` table, derived from `Schema.StripeCustomer`. */
+export type Table = db_Schema.StripeCustomer;
+/** A stored Stripe billing-source row. */
+export type Record = Selectable<Table>;
+/** A billing status. */
+export type Status = Record['status'];
+/** Billing statuses; `active` alone opens the production sponsorship gate. */
+export declare const statuses: readonly ["active", "canceled", "none", "past_due"];
+/**
+ * Inserts a Stripe billing source (status `none`) and returns the stored record.
+ * Idempotent per organization: a concurrent first-checkout race resolves to
+ * the winner's row — the loser's Stripe customer stays orphaned in Stripe,
+ * which is harmless.
+ *
+ * @param db - The database.
+ * @param input - The Stripe source to insert.
+ * @returns The stored record.
+ */
+export declare function create(db: Db.Db, input: create.Input): Promise<Record>;
+export declare namespace create {
+    /** Fields accepted when inserting a Stripe billing source. */
+    type Input = {
+        /** Environment this source backs; defaults to `production`. */
+        environment?: Record['environment'] | undefined;
+        /** Organization id (`org_…`) the Stripe source belongs to. */
+        orgId: string;
+        /** Stripe customer id backing this account. */
+        stripeCustomerId: string;
+    };
+}
+/**
+ * Deletes an organization's Stripe billing source. The Stripe customer is never
+ * deleted; its invoice history stays in Stripe for audit.
+ *
+ * @param db - The database.
+ * @param orgId - The organization id (`org_…`).
+ * @returns Whether a Stripe source existed and was deleted.
+ */
+export declare function deleteByOrg(db: Db.Db, orgId: string): Promise<boolean>;
+/**
+ * Reads an organization's Stripe billing source.
+ *
+ * @param db - The database.
+ * @param orgId - The organization id (`org_…`).
+ * @param environment - The environment to read; defaults to `production`.
+ * @returns The stored record, or `undefined` when the org has none.
+ */
+export declare function get(db: Db.Db, orgId: string, environment?: Record['environment']): Promise<Record | undefined>;
+/**
+ * Lists every billing source in an environment — the driver set for the cron
+ * job that reconciles cached billing snapshots (e.g. API-key records) against
+ * this authoritative table.
+ *
+ * @param db - The database.
+ * @param environment - The environment to enumerate.
+ * @returns The stored records for that environment.
+ */
+export declare function listByEnvironment(db: Db.Db, environment: Record['environment']): Promise<Record[]>;
+/**
+ * Reads a Stripe billing source by its customer id — the webhook handler's
+ * lookup for inbound events.
+ *
+ * @param db - The database.
+ * @param stripeCustomerId - The Stripe customer id.
+ * @returns The stored record, or `undefined` for unknown customers.
+ */
+export declare function getByCustomer(db: Db.Db, stripeCustomerId: string): Promise<Record | undefined>;
+/**
+ * Sets an organization's billing status.
+ *
+ * @param db - The database.
+ * @param orgId - The organization id (`org_…`).
+ * @param status - The derived status to persist.
+ * @param environment - The environment to update; defaults to `production`.
+ * @returns The updated record, or `undefined` when the org has no Stripe source.
+ */
+export declare function setStatus(db: Db.Db, orgId: string, status: Status, environment?: Record['environment']): Promise<Record | undefined>;
+//# sourceMappingURL=stripeCustomers.d.ts.map

package/dist/db/tables/stripeCustomers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stripeCustomers.d.ts","sourceRoot":"","sources":["../../../src/db/tables/stripeCustomers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAA;AAExC,OAAO,KAAK,KAAK,EAAE,MAAM,UAAU,CAAA;AACnC,OAAO,KAAK,KAAK,SAAS,MAAM,cAAc,CAAA;AAE9C,qFAAqF;AACrF,MAAM,MAAM,KAAK,GAAG,SAAS,CAAC,cAAc,CAAA;AAE5C,0CAA0C;AAC1C,MAAM,MAAM,MAAM,GAAG,UAAU,CAAC,KAAK,CAAC,CAAA;AAEtC,wBAAwB;AACxB,MAAM,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAA;AAErC,8EAA8E;AAC9E,eAAO,MAAM,QAAQ,qDAAkF,CAAA;AAEvG;;;;;;;;;GASG;AACH,wBAAsB,MAAM,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAyB5E;AAED,MAAM,CAAC,OAAO,WAAW,MAAM,CAAC;IAC9B,8DAA8D;IAC9D,KAAK,KAAK,GAAG;QACX,+DAA+D;QAC/D,WAAW,CAAC,EAAE,MAAM,CAAC,aAAa,CAAC,GAAG,SAAS,CAAA;QAC/C,8DAA8D;QAC9D,KAAK,EAAE,MAAM,CAAA;QACb,+CAA+C;QAC/C,gBAAgB,EAAE,MAAM,CAAA;KACzB,CAAA;CACF;AAED;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAM5E;AAED;;;;;;;GAOG;AACH,wBAAgB,GAAG,CACjB,EAAE,EAAE,EAAE,CAAC,EAAE,EACT,KAAK,EAAE,MAAM,EACb,WAAW,GAAE,MAAM,CAAC,aAAa,CAAgB,GAChD,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAO7B;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,EAAE,EAAE,EAAE,CAAC,EAAE,EACT,WAAW,EAAE,MAAM,CAAC,aAAa,CAAC,GACjC,OAAO,CAAC,MAAM,EAAE,CAAC,CAMnB;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAM9F;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CACvB,EAAE,EAAE,EAAE,CAAC,EAAE,EACT,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,WAAW,GAAE,MAAM,CAAC,aAAa,CAAgB,GAChD,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAQ7B"}