tapimo 0.2.0 → 0.3.0

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

@@ -0,0 +1,121 @@
+import { type ColumnType } from 'kysely';
+import type * as Db from '../Db.js';
+import type * as db_Schema from '../Schema.js';
+/** A `bigint` count column: read as a string from pg, written as a number. */
+type Count = ColumnType<string, number, number>;
+/** Environment a request-usage row attributes to. */
+export type Environment = db_Schema.RequestUsageBucket['environment'];
+/** Exactly-once state of a meter event. */
+export type State = db_Schema.RequestUsageMeterEvent['state'];
+/** Columns of the `request_usage_buckets` table (pg representation). */
+export type BucketTable = {
+    bucketStart: string;
+    environment: Environment;
+    orgId: string;
+    reportedCount: Count;
+    updatedAt: string;
+};
+/** Columns of the `request_usage_meter_events` table (pg representation). */
+export type MeterEventTable = {
+    bucketStart: string;
+    deltaCount: Count;
+    environment: Environment;
+    error: string | null;
+    firstAttemptedAt: string;
+    identifier: string;
+    orgId: string;
+    reason: string | null;
+    reportedAt: string | null;
+    sequence: number;
+    state: State;
+    stripeCustomerId: string;
+};
+/** A stored per-hour request-count watermark. */
+export type Bucket = db_Schema.RequestUsageBucket;
+/** A stored request-count meter event. */
+export type MeterEvent = db_Schema.RequestUsageMeterEvent;
+/** Identifies one hourly bucket for an org in an environment. */
+export type BucketKey = {
+    /** UTC hour start (ISO 8601). */
+    bucketStart: string;
+    /** Environment the requests were served under. */
+    environment: Environment;
+    /** Organization id (`org_…`). */
+    orgId: string;
+};
+/**
+ * Reads a bucket watermark.
+ *
+ * @param db - The database.
+ * @param key - The bucket key.
+ * @returns The watermark, or `undefined` when none has been reported yet.
+ */
+export declare function getBucket(db: Db.Db, key: BucketKey): Promise<Bucket | undefined>;
+/**
+ * Lists the meter events still awaiting a Stripe acknowledgement in an
+ * environment, oldest first — the reporter's crash-recovery drive.
+ *
+ * @param db - The database.
+ * @param environment - The environment to scan.
+ * @returns The pending meter events.
+ */
+export declare function listPending(db: Db.Db, environment: Environment): Promise<MeterEvent[]>;
+/**
+ * Counts the meter events already reported for a bucket — the next delta's
+ * `sequence`, so a new seal never collides with a settled one.
+ *
+ * @param db - The database.
+ * @param key - The bucket key.
+ * @returns The count of reported events for the bucket.
+ */
+export declare function countReported(db: Db.Db, key: BucketKey): Promise<number>;
+/**
+ * Inserts a frozen `pending` meter event, claiming a delta. Idempotent on the
+ * deterministic `identifier`: a re-seal after a crash resolves to the existing
+ * row rather than duplicating the delta.
+ *
+ * @param db - The database.
+ * @param input - The event to insert.
+ * @returns Whether this call inserted the row.
+ */
+export declare function insertPending(db: Db.Db, input: insertPending.Input): Promise<boolean>;
+export declare namespace insertPending {
+    /** Fields accepted when sealing a pending meter event. */
+    type Input = {
+        /** UTC hour start the delta bills for (ISO 8601). */
+        bucketStart: string;
+        /** Frozen request count this event bills (positive). */
+        deltaCount: number;
+        /** Environment the requests were served under. */
+        environment: Environment;
+        /** Deterministic id; also the Stripe identifier and idempotency key. */
+        identifier: string;
+        /** Organization id (`org_…`). */
+        orgId: string;
+        /** Delta sequence within the bucket. */
+        sequence: number;
+        /** Stripe customer id the event bills against. */
+        stripeCustomerId: string;
+    };
+}
+/**
+ * Marks a pending event reported and advances its bucket watermark by the
+ * event's frozen delta, atomically. A no-op once reported, so a retry after a
+ * crash between the Stripe ack and this write never double-advances.
+ *
+ * @param db - The database.
+ * @param identifier - The event identifier.
+ * @param at - When Stripe acknowledged the event (ISO 8601).
+ * @returns Whether this call settled the event (false when already reported).
+ */
+export declare function settle(db: Db.Db, identifier: string, at: string): Promise<boolean>;
+/**
+ * Records a transient failure on a pending event; it stays pending for retry.
+ *
+ * @param db - The database.
+ * @param identifier - The event identifier.
+ * @param error - The failure detail.
+ */
+export declare function markError(db: Db.Db, identifier: string, error: string): Promise<void>;
+export {};
+//# sourceMappingURL=requestUsage.d.ts.map

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

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

package/dist/db/tables/requestUsage.js

@@ -0,0 +1,150 @@
+import { sql } from 'kysely';
+/**
+ * Reads a bucket watermark.
+ *
+ * @param db - The database.
+ * @param key - The bucket key.
+ * @returns The watermark, or `undefined` when none has been reported yet.
+ */
+export async function getBucket(db, key) {
+    const row = await db.kysely
+        .selectFrom('request_usage_buckets')
+        .selectAll()
+        .where('orgId', '=', key.orgId)
+        .where('environment', '=', key.environment)
+        .where('bucketStart', '=', key.bucketStart)
+        .executeTakeFirst();
+    return row ? toBucket(row) : undefined;
+}
+/**
+ * Lists the meter events still awaiting a Stripe acknowledgement in an
+ * environment, oldest first — the reporter's crash-recovery drive.
+ *
+ * @param db - The database.
+ * @param environment - The environment to scan.
+ * @returns The pending meter events.
+ */
+export async function listPending(db, environment) {
+    const rows = await db.kysely
+        .selectFrom('request_usage_meter_events')
+        .selectAll()
+        .where('environment', '=', environment)
+        .where('state', '=', 'pending')
+        .orderBy('firstAttemptedAt', 'asc')
+        .orderBy('identifier', 'asc')
+        .execute();
+    return rows.map(toMeterEvent);
+}
+/**
+ * Counts the meter events already reported for a bucket — the next delta's
+ * `sequence`, so a new seal never collides with a settled one.
+ *
+ * @param db - The database.
+ * @param key - The bucket key.
+ * @returns The count of reported events for the bucket.
+ */
+export async function countReported(db, key) {
+    const row = await db.kysely
+        .selectFrom('request_usage_meter_events')
+        .select((eb) => eb.fn.countAll().as('count'))
+        .where('orgId', '=', key.orgId)
+        .where('environment', '=', key.environment)
+        .where('bucketStart', '=', key.bucketStart)
+        .where('state', '=', 'reported')
+        .executeTakeFirstOrThrow();
+    return Number(row.count);
+}
+/**
+ * Inserts a frozen `pending` meter event, claiming a delta. Idempotent on the
+ * deterministic `identifier`: a re-seal after a crash resolves to the existing
+ * row rather than duplicating the delta.
+ *
+ * @param db - The database.
+ * @param input - The event to insert.
+ * @returns Whether this call inserted the row.
+ */
+export async function insertPending(db, input) {
+    const now = new Date().toISOString();
+    const inserted = await db.kysely
+        .insertInto('request_usage_meter_events')
+        .values({
+        bucketStart: input.bucketStart,
+        deltaCount: input.deltaCount,
+        environment: input.environment,
+        error: null,
+        firstAttemptedAt: now,
+        identifier: input.identifier,
+        orgId: input.orgId,
+        reason: null,
+        reportedAt: null,
+        sequence: input.sequence,
+        state: 'pending',
+        stripeCustomerId: input.stripeCustomerId,
+    })
+        .onConflict((oc) => oc.doNothing())
+        .returning('identifier')
+        .executeTakeFirst();
+    return Boolean(inserted);
+}
+/**
+ * Marks a pending event reported and advances its bucket watermark by the
+ * event's frozen delta, atomically. A no-op once reported, so a retry after a
+ * crash between the Stripe ack and this write never double-advances.
+ *
+ * @param db - The database.
+ * @param identifier - The event identifier.
+ * @param at - When Stripe acknowledged the event (ISO 8601).
+ * @returns Whether this call settled the event (false when already reported).
+ */
+export function settle(db, identifier, at) {
+    return db.transaction(async (tx) => {
+        const updated = await tx.kysely
+            .updateTable('request_usage_meter_events')
+            .set({ error: null, reportedAt: at, state: 'reported' })
+            .where('identifier', '=', identifier)
+            .where('state', '=', 'pending')
+            .returningAll()
+            .executeTakeFirst();
+        if (!updated)
+            return false;
+        await tx.kysely
+            .insertInto('request_usage_buckets')
+            .values({
+            bucketStart: updated.bucketStart,
+            environment: updated.environment,
+            orgId: updated.orgId,
+            reportedCount: Number(updated.deltaCount),
+            updatedAt: at,
+        })
+            .onConflict((oc) => oc.columns(['orgId', 'environment', 'bucketStart']).doUpdateSet({
+            reportedCount: sql `request_usage_buckets.reported_count + ${updated.deltaCount}`,
+            updatedAt: at,
+        }))
+            .execute();
+        return true;
+    });
+}
+/**
+ * Records a transient failure on a pending event; it stays pending for retry.
+ *
+ * @param db - The database.
+ * @param identifier - The event identifier.
+ * @param error - The failure detail.
+ */
+export async function markError(db, identifier, error) {
+    await db.kysely
+        .updateTable('request_usage_meter_events')
+        .set({ error: error.slice(0, 500) })
+        .where('identifier', '=', identifier)
+        .where('state', '=', 'pending')
+        .execute();
+}
+/** Maps a bucket row to its domain record. */
+function toBucket(row) {
+    return { ...row, reportedCount: Number(row.reportedCount) };
+}
+/** Maps a meter-event row to its domain record. */
+function toMeterEvent(row) {
+    return { ...row, deltaCount: Number(row.deltaCount) };
+}
+//# sourceMappingURL=requestUsage.js.map

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

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

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

@@ -26,8 +26,12 @@ export declare namespace upsert {
         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. */
@@ -117,4 +121,119 @@ export declare namespace finalize {
  * @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

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

@@ -1,5 +1,5 @@
 import { sql } from 'kysely';
-import { nanoid } from 'nanoid';
+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
@@ -17,11 +17,14 @@ export async function upsert(db, input) {
         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: `stx_${nanoid()}`,
+        id: Id.generate('stx'),
+        meterReportedAt: null,
         orgId: input.orgId,
         projectId: input.projectId,
         signPayload: input.signPayload,
@@ -33,6 +36,9 @@ export async function upsert(db, input) {
         .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')),
@@ -147,6 +153,149 @@ export async function fail(db, id, finalizedAt) {
         .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) => {
@@ -158,4 +307,8 @@ function intentStatus(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

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