tapimo 0.7.1 → 0.8.0

package/src/db/tables/fundingIdempotency.ts

@@ -0,0 +1,180 @@
+import type { Selectable } from 'kysely'
+
+import type * as Db from '../Db.js'
+import type * as db_Schema from '../Schema.js'
+
+/** Columns of the `funding_idempotency_requests` table. */
+export type Table = db_Schema.FundingIdempotencyRequest
+/** A stored idempotency claim. */
+export type Record = Selectable<Table>
+
+/**
+ * Claims `(apiKeyId, keyHash)` for one creation attempt. A live claim rejects
+ * mismatches, blocks pending work, resumes checkpoints, or replays completion.
+ */
+export async function claim(db: Db.Db, input: claim.Input): Promise<claim.Result> {
+  const now = new Date()
+  const record: Record = {
+    apiKeyId: input.apiKeyId,
+    createdAt: now.toISOString(),
+    expiresAt: new Date(now.getTime() + input.ttlMs).toISOString(),
+    keyHash: input.keyHash,
+    requestHash: input.requestHash,
+    response: null,
+    status: 'pending',
+    transferId: null,
+  }
+  const inserted = await db.kysely
+    .insertInto('funding_idempotency_requests')
+    .values(record)
+    .onConflict((oc) => oc.columns(['apiKeyId', 'keyHash']).doNothing())
+    .returningAll()
+    .executeTakeFirst()
+  if (inserted) return { createdAt: inserted.createdAt, type: 'claimed' }
+
+  // Reclaim an expired row in place; the guard keeps two callers from both
+  // reclaiming (only one UPDATE matches the still-expired predicate).
+  const reclaimed = await db.kysely
+    .updateTable('funding_idempotency_requests')
+    .set(record)
+    .where('apiKeyId', '=', input.apiKeyId)
+    .where('keyHash', '=', input.keyHash)
+    .where('expiresAt', '<=', now.toISOString())
+    .returningAll()
+    .executeTakeFirst()
+  if (reclaimed) return { createdAt: reclaimed.createdAt, type: 'claimed' }
+
+  const existing = await db.kysely
+    .selectFrom('funding_idempotency_requests')
+    .selectAll()
+    .where('apiKeyId', '=', input.apiKeyId)
+    .where('keyHash', '=', input.keyHash)
+    .executeTakeFirst()
+  // The row vanished between the insert and the read (released claim); retry.
+  if (!existing) return claim(db, input)
+  if (existing.requestHash !== input.requestHash) return { type: 'mismatch' }
+  if (existing.status === 'pending') return { type: 'pending' }
+  if (existing.status === 'provisioned')
+    return {
+      createdAt: existing.createdAt,
+      response: existing.response ?? '',
+      type: 'resume',
+    }
+  return { response: existing.response ?? '', type: 'replay' }
+}
+
+export declare namespace claim {
+  /** Claim identity and retention. */
+  type Input = {
+    /** API key id (`key_…`) the claim is scoped to. */
+    apiKeyId: string
+    /** SHA-256 of the caller Idempotency-Key. */
+    keyHash: string
+    /** SHA-256 fingerprint of the canonical validated request. */
+    requestHash: string
+    /** Lease duration for the pending execution, in milliseconds. */
+    ttlMs: number
+  }
+
+  /** Outcome of a claim attempt. */
+  type Result =
+    | { createdAt: string; type: 'claimed' }
+    | { type: 'mismatch' }
+    | { type: 'pending' }
+    | { response: string; type: 'replay' }
+    | { createdAt: string; response: string; type: 'resume' }
+}
+
+/** Stores a provider result before committing its API resource and replay response. */
+export function checkpoint(db: Db.Db, input: checkpoint.Input): Promise<Record | undefined> {
+  const now = new Date()
+  return db.kysely
+    .updateTable('funding_idempotency_requests')
+    .set({
+      expiresAt: new Date(now.getTime() + input.replayTtlMs).toISOString(),
+      response: input.response,
+      status: 'provisioned',
+    })
+    .where('apiKeyId', '=', input.apiKeyId)
+    .where('createdAt', '=', input.createdAt)
+    .where('keyHash', '=', input.keyHash)
+    .where('status', '=', 'pending')
+    .returningAll()
+    .executeTakeFirst()
+}
+
+export declare namespace checkpoint {
+  /** Provider result and owned claim required for durable recovery. */
+  type Input = {
+    /** API key id (`key_…`) the claim is scoped to. */
+    apiKeyId: string
+    /** Creation time returned by the successful claim. */
+    createdAt: string
+    /** SHA-256 of the caller Idempotency-Key. */
+    keyHash: string
+    /** Recovery checkpoint retention in milliseconds. */
+    replayTtlMs: number
+    /** Serialized provider result required to resume resource creation. */
+    response: string
+  }
+}
+
+/** Completes an owned pending or provisioned claim with its replay response. */
+export function complete(db: Db.Db, input: complete.Input): Promise<Record | undefined> {
+  const now = new Date()
+  return db.kysely
+    .updateTable('funding_idempotency_requests')
+    .set({
+      expiresAt: new Date(now.getTime() + input.replayTtlMs).toISOString(),
+      response: input.response,
+      status: 'completed',
+      transferId: input.transferId ?? null,
+    })
+    .where('apiKeyId', '=', input.apiKeyId)
+    .where('createdAt', '=', input.createdAt)
+    .where('keyHash', '=', input.keyHash)
+    .where('status', 'in', ['pending', 'provisioned'])
+    .returningAll()
+    .executeTakeFirst()
+}
+
+export declare namespace complete {
+  /** Completion fields. */
+  type Input = {
+    /** API key id (`key_…`) the claim is scoped to. */
+    apiKeyId: string
+    /** Creation time returned by the successful claim. */
+    createdAt: string
+    /** SHA-256 of the caller Idempotency-Key. */
+    keyHash: string
+    /** Successful-response replay retention from completion, in milliseconds. */
+    replayTtlMs: number
+    /** Serialized success response replayed for the retention window. */
+    response: string
+    /** Transfer id (`ftr_…`) when the request created a funding transfer. */
+    transferId?: string | undefined
+  }
+}
+
+/** Releases a pending claim after a retryable failure. */
+export async function release(db: Db.Db, input: release.Input): Promise<void> {
+  await db.kysely
+    .deleteFrom('funding_idempotency_requests')
+    .where('apiKeyId', '=', input.apiKeyId)
+    .where('createdAt', '=', input.createdAt)
+    .where('keyHash', '=', input.keyHash)
+    .where('status', '=', 'pending')
+    .execute()
+}
+
+export declare namespace release {
+  /** Pending claim identity. */
+  type Input = {
+    /** API key id (`key_…`) the claim is scoped to. */
+    apiKeyId: string
+    /** Creation time returned by the successful claim. */
+    createdAt: string
+    /** SHA-256 of the caller Idempotency-Key. */
+    keyHash: string
+  }
+}

package/src/db/tables/fundingTransferEvents.ts

@@ -0,0 +1,28 @@
+import type { Selectable } from 'kysely'
+
+import type * as Db from '../Db.js'
+import type * as db_Schema from '../Schema.js'
+
+/** Columns of the `funding_transfer_events` table. */
+export type Table = db_Schema.FundingTransferEvent
+/** One immutable public snapshot at a material version. */
+export type Record = Selectable<Table>
+
+/** Inserts an event row. Callers commit it with its transfer row in one transaction. */
+export function insert(db: Db.Db, record: Record): Promise<Record> {
+  return db.kysely
+    .insertInto('funding_transfer_events')
+    .values(record)
+    .returningAll()
+    .executeTakeFirstOrThrow()
+}
+
+/** Lists a transfer's events, oldest version first. */
+export function listByTransfer(db: Db.Db, transferId: string): Promise<Record[]> {
+  return db.kysely
+    .selectFrom('funding_transfer_events')
+    .selectAll()
+    .where('transferId', '=', transferId)
+    .orderBy('version', 'asc')
+    .execute()
+}

package/src/db/tables/fundingTransferTransactions.test.ts

@@ -0,0 +1,69 @@
+import * as TestApp from '../../../test/App.js'
+import * as TestFunding from '../../../test/Funding.js'
+import * as Transfer from '../../internal/funding/Transfer.js'
+import * as FundingTransferTransactions from './fundingTransferTransactions.js'
+
+const db = TestApp.database()
+
+function createTransfer(id: string) {
+  return Transfer.create(db, {
+    apiKeyId: 'key_test',
+    environment: 'production',
+    id,
+    orgId: 'org_test',
+    snapshot: TestFunding.transferSnapshot(),
+  })
+}
+
+describe('insert', () => {
+  test('canonicalizes EVM hashes before enforcing source uniqueness', async () => {
+    const first = await createTransfer('ftr_evm_first')
+    const second = await createTransfer('ftr_evm_second')
+    const transactionRef = `0x${'aB'.repeat(32)}`
+
+    const inserted = await FundingTransferTransactions.insert(db, {
+      chainId: 'eip155:8453',
+      createdAt: '2026-01-01T00:00:01.000Z',
+      role: 'source',
+      transactionRef,
+      transferId: first.id,
+    })
+    expect(inserted?.transactionRef).toBe(transactionRef.toLowerCase())
+
+    await expect(
+      FundingTransferTransactions.insert(db, {
+        chainId: 'eip155:8453',
+        createdAt: '2026-01-01T00:00:02.000Z',
+        role: 'source',
+        transactionRef: transactionRef.toUpperCase(),
+        transferId: second.id,
+      }),
+    ).rejects.toMatchObject({ constraint: 'funding_transfer_transactions_source_unique' })
+  })
+
+  test('preserves case-sensitive non-EVM transaction references', async () => {
+    const first = await createTransfer('ftr_solana_first')
+    const second = await createTransfer('ftr_solana_second')
+    const transactionRef = 'A'.repeat(87)
+
+    const uppercase = await FundingTransferTransactions.insert(db, {
+      chainId: 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp',
+      createdAt: '2026-01-01T00:00:01.000Z',
+      role: 'source',
+      transactionRef,
+      transferId: first.id,
+    })
+    const lowercase = await FundingTransferTransactions.insert(db, {
+      chainId: 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp',
+      createdAt: '2026-01-01T00:00:02.000Z',
+      role: 'source',
+      transactionRef: transactionRef.toLowerCase(),
+      transferId: second.id,
+    })
+
+    expect([uppercase?.transactionRef, lowercase?.transactionRef]).toEqual([
+      transactionRef,
+      transactionRef.toLowerCase(),
+    ])
+  })
+})

package/src/db/tables/fundingTransferTransactions.ts

@@ -0,0 +1,37 @@
+import type { Selectable } from 'kysely'
+
+import type * as Db from '../Db.js'
+import type * as db_Schema from '../Schema.js'
+
+/** Columns of the `funding_transfer_transactions` table. */
+export type Table = db_Schema.FundingTransferTransaction
+/** One verified transaction reference on a transfer. */
+export type Record = Selectable<Table>
+
+/**
+ * Inserts a transaction reference, lowercasing EVM hashes while preserving
+ * other references. Repeats return `undefined`; conflicting source ownership throws.
+ */
+export function insert(db: Db.Db, record: Record): Promise<Record | undefined> {
+  return db.kysely
+    .insertInto('funding_transfer_transactions')
+    .values({
+      ...record,
+      transactionRef: record.chainId.startsWith('eip155:')
+        ? record.transactionRef.toLowerCase()
+        : record.transactionRef,
+    })
+    .onConflict((oc) => oc.columns(['transferId', 'role', 'transactionRef']).doNothing())
+    .returningAll()
+    .executeTakeFirst()
+}
+
+/** Lists a transfer's transaction references, oldest first. */
+export function listByTransfer(db: Db.Db, transferId: string): Promise<Record[]> {
+  return db.kysely
+    .selectFrom('funding_transfer_transactions')
+    .selectAll()
+    .where('transferId', '=', transferId)
+    .orderBy('createdAt', 'asc')
+    .execute()
+}

package/src/db/tables/fundingTransfers.test.ts

@@ -0,0 +1,89 @@
+import * as Transfer from '../../internal/funding/Transfer.js'
+import * as TestApp from '../../../test/App.js'
+import * as TestFunding from '../../../test/Funding.js'
+import * as FundingTransfers from './fundingTransfers.js'
+
+const db = TestApp.database()
+
+const owner = { environment: 'production', orgId: 'org_list' } as const
+
+let counter = 0
+function seed(input: Partial<Transfer.create.Input> = {}) {
+  // Distinct create times keep ids strictly ordered for paging assertions.
+  return Transfer.create(db, {
+    apiKeyId: 'key_test',
+    environment: 'production',
+    id: Transfer.generateId(new Date(Date.UTC(2026, 0, 1, 0, 0, counter++))),
+    orgId: owner.orgId,
+    snapshot: TestFunding.transferSnapshot(),
+    ...input,
+  })
+}
+
+describe('list', () => {
+  test('pages newest-first by id with owner isolation', async () => {
+    const first = await seed()
+    const second = await seed({ projectId: 'prj_a' })
+    const third = await seed()
+    await seed({ orgId: 'org_other' })
+    await seed({ environment: 'sandbox' })
+
+    const page = await FundingTransfers.list(db, owner, { limit: 3 })
+    expect(page.map((row) => row.id)).toEqual([third.id, second.id, first.id])
+
+    const rest = await FundingTransfers.list(db, owner, { cursor: third.id, limit: 3 })
+    expect(rest.map((row) => row.id)).toEqual([second.id, first.id])
+  })
+
+  test('narrows project-attributed owners to their project', async () => {
+    const rows = await FundingTransfers.list(db, { ...owner, projectId: 'prj_a' }, { limit: 10 })
+    expect(rows.every((row) => row.projectId === 'prj_a')).toBe(true)
+    expect(rows.length).toBeGreaterThan(0)
+  })
+
+  test('filters by status', async () => {
+    const record = await seed()
+    await Transfer.transition(db, { expectedVersion: 1, id: record.id, status: 'expired' })
+    const rows = await FundingTransfers.list(db, owner, { limit: 10, status: 'expired' })
+    expect(rows.map((row) => row.id)).toEqual([record.id])
+  })
+})
+
+describe('count', () => {
+  test('shares the list filter and stops at the cap', async () => {
+    const total = await FundingTransfers.count(db, owner, { cap: 100 })
+    expect(total).toBeGreaterThanOrEqual(3)
+    expect(await FundingTransfers.count(db, owner, { cap: 2 })).toBe(3)
+    expect(await FundingTransfers.count(db, { ...owner, orgId: 'org_none' }, { cap: 100 })).toBe(0)
+  })
+})
+
+describe('getOwned', () => {
+  test('returns owned rows and hides foreign ones', async () => {
+    const record = await seed()
+    expect((await FundingTransfers.getOwned(db, owner, record.id))?.id).toBe(record.id)
+    expect(
+      await FundingTransfers.getOwned(db, { ...owner, orgId: 'org_other' }, record.id),
+    ).toBeUndefined()
+    expect(
+      await FundingTransfers.getOwned(db, { ...owner, projectId: 'prj_a' }, record.id),
+    ).toBeUndefined()
+  })
+})
+
+describe('update', () => {
+  test('applies only against the expected version', async () => {
+    const record = await seed()
+    const options = {
+      expectedVersion: 1,
+      id: record.id,
+      snapshot: record.snapshot,
+      status: 'processing',
+      statusReason: null,
+      updatedAt: '2026-01-01T00:10:00.000Z',
+      version: 2,
+    } as const
+    expect((await FundingTransfers.update(db, options))?.version).toBe(2)
+    expect(await FundingTransfers.update(db, options)).toBeUndefined()
+  })
+})

package/src/db/tables/fundingTransfers.ts

@@ -0,0 +1,153 @@
+import type { Selectable } from 'kysely'
+
+import type * as Db from '../Db.js'
+import type * as db_Schema from '../Schema.js'
+
+/** Columns of the `funding_transfers` table. */
+export type Table = db_Schema.FundingTransfer
+/** A stored funding transfer. */
+export type Record = Selectable<Table>
+
+/**
+ * Ownership filter derived from the API-key principal, never from the
+ * request. A `projectId` narrows reads to that project; organization-attributed
+ * keys omit it and see every project in their organization and environment.
+ */
+export type Owner = {
+  /** Key environment. */
+  environment: Record['environment']
+  /** Owning organization id (`org_…`). */
+  orgId: string
+  /** Attributed project id, for project-attributed keys. */
+  projectId?: string | undefined
+}
+
+/** Inserts a transfer row. Callers commit the matching event in the same transaction. */
+export function insert(db: Db.Db, record: Record): Promise<Record> {
+  return db.kysely
+    .insertInto('funding_transfers')
+    .values(record)
+    .returningAll()
+    .executeTakeFirstOrThrow()
+}
+
+/** Gets a transfer by id without ownership scoping (domain and reconciler use). */
+export function get(db: Db.Db, id: string): Promise<Record | undefined> {
+  return db.kysely
+    .selectFrom('funding_transfers')
+    .selectAll()
+    .where('id', '=', id)
+    .executeTakeFirst()
+}
+
+/** Gets an owner-visible transfer by id; `undefined` for absent or foreign rows. */
+export function getOwned(db: Db.Db, owner: Owner, id: string): Promise<Record | undefined> {
+  let query = db.kysely
+    .selectFrom('funding_transfers')
+    .selectAll()
+    .where('id', '=', id)
+    .where('orgId', '=', owner.orgId)
+    .where('environment', '=', owner.environment)
+  if (owner.projectId !== undefined) query = query.where('projectId', '=', owner.projectId)
+  return query.executeTakeFirst()
+}
+
+/**
+ * Lists an owner's transfers newest-first. Ids embed a timestamp, so lexical
+ * key order is chronological and the cursor is the last returned id.
+ */
+export function list(db: Db.Db, owner: Owner, options: list.Options): Promise<Record[]> {
+  let query = db.kysely
+    .selectFrom('funding_transfers')
+    .selectAll()
+    .where('orgId', '=', owner.orgId)
+    .where('environment', '=', owner.environment)
+  if (owner.projectId !== undefined) query = query.where('projectId', '=', owner.projectId)
+  if (options.status !== undefined) query = query.where('status', '=', options.status)
+  if (options.cursor !== undefined) query = query.where('id', '<', options.cursor)
+  return query.orderBy('id', 'desc').limit(options.limit).execute()
+}
+
+export declare namespace list {
+  /** Paging and filter options. */
+  type Options = {
+    /** Exclusive lower bound: the last id of the previous page. */
+    cursor?: string | undefined
+    /** Maximum rows to return (fetch one extra to detect a further page). */
+    limit: number
+    /** Restricts to one lifecycle status. */
+    status?: Record['status'] | undefined
+  }
+}
+
+/**
+ * Counts an owner's transfers through a capped subquery sharing the list
+ * filter, so the count cannot scan unboundedly. A result above `cap` means
+ * the true count was truncated.
+ */
+export async function count(db: Db.Db, owner: Owner, options: count.Options): Promise<number> {
+  const row = await db.kysely
+    .selectFrom((eb) => {
+      let query = eb
+        .selectFrom('funding_transfers')
+        .select('id')
+        .where('orgId', '=', owner.orgId)
+        .where('environment', '=', owner.environment)
+      if (owner.projectId !== undefined) query = query.where('projectId', '=', owner.projectId)
+      if (options.status !== undefined) query = query.where('status', '=', options.status)
+      return query.limit(options.cap + 1).as('page')
+    })
+    .select(({ fn }) => fn.countAll<string>().as('count'))
+    .executeTakeFirstOrThrow()
+  return Number(row.count)
+}
+
+export declare namespace count {
+  /** Count options sharing the list filter. */
+  type Options = {
+    /** Row ceiling; a result above it signals a truncated count. */
+    cap: number
+    /** Restricts to one lifecycle status. */
+    status?: Record['status'] | undefined
+  }
+}
+
+/**
+ * Applies a version-guarded update; `undefined` when the row moved past
+ * `expectedVersion` (or vanished) so the caller retries against fresh state.
+ */
+export function update(db: Db.Db, options: update.Options): Promise<Record | undefined> {
+  return db.kysely
+    .updateTable('funding_transfers')
+    .set({
+      snapshot: options.snapshot,
+      status: options.status,
+      statusReason: options.statusReason,
+      updatedAt: options.updatedAt,
+      version: options.version,
+    })
+    .where('id', '=', options.id)
+    .where('version', '=', options.expectedVersion)
+    .returningAll()
+    .executeTakeFirst()
+}
+
+export declare namespace update {
+  /** Guarded update fields. */
+  type Options = {
+    /** The version the update was computed against. */
+    expectedVersion: number
+    /** Transfer id (`ftr_…`). */
+    id: string
+    /** Replacement public snapshot. */
+    snapshot: Record['snapshot']
+    /** New lifecycle status. */
+    status: Record['status']
+    /** Customer-safe reason, or null to clear. */
+    statusReason: Record['statusReason']
+    /** Mutation timestamp (ISO 8601). */
+    updatedAt: string
+    /** The incremented version. */
+    version: number
+  }
+}

package/src/db/tables/organizations.ts

@@ -186,6 +186,22 @@ export function get(db: Db.Db, id: string): Promise<Record | undefined> {
   return db.kysely.selectFrom('organizations').selectAll().where('id', '=', id).executeTakeFirst()
 }
 
+/**
+ * Reads organizations by id for operational attribution displays.
+ *
+ * @param db - The database.
+ * @param ids - Organization ids to read.
+ * @returns Matching organization records.
+ */
+export function listByIds(db: Db.Db, ids: readonly string[]): Promise<Record[]> {
+  if (ids.length === 0) return Promise.resolve([])
+  return db.kysely
+    .selectFrom('organizations')
+    .selectAll()
+    .where('id', 'in', [...ids])
+    .execute()
+}
+
 /**
  * Reads an organization with current member and project counts.
  *

package/src/db/tables/projects.ts

@@ -65,6 +65,22 @@ export function get(db: Db.Db, id: string): Promise<Record | undefined> {
   return db.kysely.selectFrom('projects').selectAll().where('id', '=', id).executeTakeFirst()
 }
 
+/**
+ * Reads projects by id for operational attribution displays.
+ *
+ * @param db - The database.
+ * @param ids - Project ids to read.
+ * @returns Matching project records.
+ */
+export function listByIds(db: Db.Db, ids: readonly string[]): Promise<Record[]> {
+  if (ids.length === 0) return Promise.resolve([])
+  return db.kysely
+    .selectFrom('projects')
+    .selectAll()
+    .where('id', 'in', [...ids])
+    .execute()
+}
+
 /**
  * Lists an organization's projects, newest first.
  *

package/src/db/tables/requestUsage.ts

@@ -43,6 +43,12 @@ export type Bucket = db_Schema.RequestUsageBucket
 /** A stored request-count meter event. */
 export type MeterEvent = db_Schema.RequestUsageMeterEvent
 
+/** Aggregate state for pending meter events in one billing environment. */
+export type PendingStatus = {
+  count: number
+  oldestAttemptedAt: string | undefined
+}
+
 /** Identifies one hourly bucket for an org in an environment. */
 export type BucketKey = {
   /** UTC hour start (ISO 8601). */
@@ -91,6 +97,23 @@ export async function listPending(db: Db.Db, environment: Environment): Promise<
   return rows.map(toMeterEvent)
 }
 
+/**
+ * Reads the number and age anchor of meter events still awaiting Stripe.
+ *
+ * @param db - The database.
+ * @param environment - The billing environment to inspect.
+ * @returns The pending-event count and oldest first attempt.
+ */
+export async function getPendingStatus(db: Db.Db, environment: Environment): Promise<PendingStatus> {
+  const row = await db.kysely
+    .selectFrom('request_usage_meter_events')
+    .select((eb) => [eb.fn.countAll().as('count'), eb.fn.min('firstAttemptedAt').as('oldest')])
+    .where('environment', '=', environment)
+    .where('state', '=', 'pending')
+    .executeTakeFirstOrThrow()
+  return { count: Number(row.count), oldestAttemptedAt: row.oldest ?? undefined }
+}
+
 /**
  * Inserts a frozen `pending` meter event, claiming a delta. Idempotent on the
  * deterministic `identifier`: a re-seal after a crash resolves to the existing

package/src/db/tables/sponsoredTransactions.test.ts

@@ -62,6 +62,17 @@ describe('upsert', () => {
     await db.close()
   })
 
+  test('behavior: records organization-level sponsorship without a project', async () => {
+    const db = create()
+    await db.migrate()
+    const { projectId: _, ...organization } = input
+    const record = await SponsoredTransactions.upsert(db, organization)
+
+    expect(record.orgId).toMatchInlineSnapshot(`"org_1"`)
+    expect(record.projectId).toBeNull()
+    await db.close()
+  })
+
   test('behavior: preserves an explicit fee token', async () => {
     const db = create()
     await db.migrate()

package/src/db/tables/sponsoredTransactions.ts

@@ -40,7 +40,7 @@ export async function upsert(db: Db.Db, input: upsert.Input): Promise<Record> {
     id: Id.generate('stx'),
     meterReportedAt: null,
     orgId: input.orgId,
-    projectId: input.projectId,
+    projectId: input.projectId ?? null,
     signPayload: input.signPayload,
     status: 'pending',
     transaction: input.transaction,
@@ -95,8 +95,8 @@ export declare namespace upsert {
     feeToken?: string | undefined
     /** Organization id (`org_…`) the spend attributes to. */
     orgId: string
-    /** Project id (`prj_…`) the spend attributes to. */
-    projectId: string
+    /** Project id (`prj_…`) the spend attributes to; omit for organization-level spend. */
+    projectId?: string | undefined
     /** Fee-payer sign payload — a stable identity for the sponsored envelope. */
     signPayload: string
     /** Serialized sponsored transaction, kept for observability beyond log retention. */