tapimo 0.14.0 → 0.15.0

package/src/db/tables/organizations.ts

@@ -2,7 +2,15 @@ import { sql, type ExpressionBuilder, type Selectable } from 'kysely'
 
 import * as Id from '../../internal/Id.js'
 import * as Viem from '../../internal/Viem.js'
+import * as ApiKeyAdmissions from './apiKeyAdmissions.js'
+import * as ApiKeyOwnerTombstones from './apiKeyOwnerTombstones.js'
+import * as AuthAccounts from './authAccounts.js'
+import * as RoutesDepositAddresses from './routesDepositAddresses.js'
+import * as RoutesDeposits from './routesDeposits.js'
+import * as RoutesIdempotency from './routesIdempotency.js'
+import * as RoutesTransfers from './routesTransfers.js'
 import * as SponsoredTransactions from './sponsoredTransactions.js'
+import * as Users from './users.js'
 import type * as Db from '../Db.js'
 import type * as db_Schema from '../Schema.js'
 import type * as EnabledBillingSources from './enabledBillingSources.js'
@@ -64,38 +72,45 @@ export declare namespace create {
  */
 export function createOwned(db: Db.Db, input: createOwned.Input): Promise<Record> {
   const now = new Date().toISOString()
-  return db.kysely.transaction().execute(async (trx) => {
-    const record = await trx
+  return db.kysely.transaction().execute(async (kysely) => {
+    const tx = { ...db, kysely }
+    const userId = await (async () => {
+      if (!input.walletAddress) return input.userId
+      const addressUser = await Users.getByAddressForUpdate(tx, input.walletAddress)
+      if (!addressUser) return input.userId
+      return (await AuthAccounts.getWalletUserId(tx, input.walletAddress)) ?? input.userId
+    })()
+    const record = await tx.kysely
       .insertInto('organizations')
       .values({
         createdAt: now,
-        createdBy: input.userId,
+        createdBy: userId,
         id: Id.generate('org'),
         name: input.name,
         sponsorshipSubsidyDurationDays: null,
         sponsorshipSubsidyProjectSpendLimit: null,
         updatedAt: now,
-        userId: input.userId,
+        userId,
       })
       .returningAll()
       .executeTakeFirstOrThrow()
-    await trx
+    await tx.kysely
       .insertInto('memberships')
       .values({
         createdAt: now,
         orgId: record.id,
         role: 'owner',
         updatedAt: now,
-        userId: input.userId,
+        userId,
       })
       .execute()
     if (input.enabledBillingSources?.length)
-      await trx
+      await tx.kysely
         .insertInto('enabled_billing_sources')
         .values(
           input.enabledBillingSources.map((source) => ({
             createdAt: now,
-            createdBy: input.userId,
+            createdBy: userId,
             orgId: record.id,
             source,
           })),
@@ -114,6 +129,8 @@ export declare namespace createOwned {
     name: string
     /** Owning user id (`usr_…`), granted the `owner` membership. */
     userId: string
+    /** Current signing wallet address, used to serialize identity ownership. */
+    walletAddress?: string | undefined
   }
 }
 
@@ -122,51 +139,108 @@ export declare namespace createOwned {
  *
  * @param db - The database.
  * @param id - The organization id (`org_…`).
+ * @param options - Post-commit lifecycle hooks.
  * @returns Whether the organization existed and was deleted.
  */
-export function deleteOrganization(db: Db.Db, id: string): Promise<boolean> {
-  return db.kysely.transaction().execute(async (trx) => {
-    const failedSince = new Date(
-      Date.now() - SponsoredTransactions.failedIntentRecoveryTtlMs,
-    ).toISOString()
-    const unreported = await trx
-      .selectFrom('sponsored_transactions')
-      .select('id')
-      .where('orgId', '=', id)
-      .where('billable', '=', true)
-      .where('chainId', '=', Viem.chainId.mainnet)
-      .where('meterReportedAt', 'is', null)
-      .where(unreportedSponsorshipStatus(failedSince))
-      .limit(1)
-      .executeTakeFirst()
-    if (unreported) throw new UnreportedSponsorshipsError()
-
-    await trx
-      .deleteFrom('webhook_subscriptions')
-      .where('ownerType', '=', 'api_key')
-      .where('ownerId', '=', id)
-      .execute()
-    await trx.deleteFrom('billing_settings').where('orgId', '=', id).execute()
-    await trx.deleteFrom('enabled_billing_sources').where('orgId', '=', id).execute()
-    await trx.deleteFrom('invitations').where('orgId', '=', id).execute()
-    await trx.deleteFrom('invite_link_redemptions').where('orgId', '=', id).execute()
-    await trx.deleteFrom('invite_links').where('orgId', '=', id).execute()
-    await trx.deleteFrom('memberships').where('orgId', '=', id).execute()
-    await trx.deleteFrom('projects').where('orgId', '=', id).execute()
-    await trx.deleteFrom('request_usage_buckets').where('orgId', '=', id).execute()
-    await trx.deleteFrom('request_usage_meter_events').where('orgId', '=', id).execute()
-    await trx.deleteFrom('stripe_customers').where('orgId', '=', id).execute()
-    const result = await trx.deleteFrom('organizations').where('id', '=', id).executeTakeFirst()
-    return result.numDeletedRows > 0n
+export async function deleteOrganization(
+  db: Db.Db,
+  id: string,
+  options: deleteOrganization.Options = {},
+): Promise<boolean> {
+  const result = await RoutesDeposits.withSubsidySettlement(db, {
+    fn: async (tx) => {
+      const failedSince = new Date(
+        Date.now() - SponsoredTransactions.failedIntentRecoveryTtlMs,
+      ).toISOString()
+      const unreportedSponsorship = await tx.kysely
+        .selectFrom('sponsored_transactions')
+        .select('id')
+        .where('orgId', '=', id)
+        .where('billable', '=', true)
+        .where('chainId', '=', Viem.chainId.mainnet)
+        .where('meterReportedAt', 'is', null)
+        .where(unreportedSponsorshipStatus(failedSince))
+        .limit(1)
+        .executeTakeFirst()
+      const [unreportedDepositSubsidy, unreportedTransferSubsidy] = await Promise.all([
+        RoutesDeposits.hasUnreportedSubsidies(tx, { orgId: id }),
+        RoutesTransfers.hasUnreportedSubsidies(tx, id),
+      ])
+      if (unreportedSponsorship || unreportedDepositSubsidy || unreportedTransferSubsidy)
+        throw new UnreportedMeteredUsageError()
+      if (await RoutesIdempotency.hasUnattributedInFlightClaim(tx))
+        throw new IrrevocableDepositAddressError()
+      if (await RoutesIdempotency.hasInFlightDepositAddress(tx, id))
+        throw new IrrevocableDepositAddressError()
+      if (await RoutesDepositAddresses.hasSubsidizedRelayAddress(tx, id))
+        throw new IrrevocableDepositAddressError()
+
+      const previous = await RoutesDepositAddresses.listActiveByOrganization(tx, id)
+      const deactivated = await RoutesDepositAddresses.deactivateByOrganization(tx, {
+        now: new Date().toISOString(),
+        orgId: id,
+      })
+      await ApiKeyOwnerTombstones.markDeleted(tx, { orgId: id })
+      await ApiKeyAdmissions.releaseOwner(tx, { orgId: id })
+      await tx.kysely
+        .deleteFrom('webhook_subscriptions')
+        .where('ownerType', '=', 'api_key')
+        .where('ownerId', '=', id)
+        .execute()
+      await tx.kysely.deleteFrom('billing_settings').where('orgId', '=', id).execute()
+      await tx.kysely.deleteFrom('enabled_billing_sources').where('orgId', '=', id).execute()
+      await tx.kysely.deleteFrom('invitations').where('orgId', '=', id).execute()
+      await tx.kysely.deleteFrom('invite_link_redemptions').where('orgId', '=', id).execute()
+      await tx.kysely.deleteFrom('invite_links').where('orgId', '=', id).execute()
+      await tx.kysely.deleteFrom('memberships').where('orgId', '=', id).execute()
+      await tx.kysely.deleteFrom('projects').where('orgId', '=', id).execute()
+      await tx.kysely.deleteFrom('request_usage_buckets').where('orgId', '=', id).execute()
+      await tx.kysely.deleteFrom('request_usage_meter_events').where('orgId', '=', id).execute()
+      await tx.kysely.deleteFrom('stripe_customers').where('orgId', '=', id).execute()
+      const result = await tx.kysely
+        .deleteFrom('organizations')
+        .where('id', '=', id)
+        .executeTakeFirst()
+      const deactivatedById = new Map(deactivated.map((record) => [record.id, record]))
+      return {
+        deactivated: previous.flatMap((previous) => {
+          const record = deactivatedById.get(previous.id)
+          return record ? [{ previous, record }] : []
+        }),
+        deleted: result.numDeletedRows > 0n,
+      }
+    },
+    orgId: id,
   })
+  if (result.deleted && result.deactivated.length > 0)
+    await options.onDepositAddressesDeactivated?.(result.deactivated)
+  return result.deleted
+}
+
+export declare namespace deleteOrganization {
+  /** Post-commit organization deletion hooks. */
+  type Options = {
+    /** Receives committed deposit-address deactivation transitions. */
+    onDepositAddressesDeactivated?:
+      | ((transitions: readonly DepositAddressDeactivation[]) => Promise<void> | void)
+      | undefined
+  }
+
+  /** One committed deposit-address deactivation. */
+  type DepositAddressDeactivation = {
+    /** Address before organization deletion deactivated it. */
+    previous: RoutesDepositAddresses.Record
+    /** Committed deactivated address. */
+    record: RoutesDepositAddresses.Record
+  }
 }
 
-/** Whether an organization has billable sponsorships awaiting settlement. */
-export async function hasUnreportedSponsorships(db: Db.Db, id: string): Promise<boolean> {
+/** Whether an organization has metered usage awaiting Stripe settlement. */
+export async function hasUnreportedMeteredUsage(db: Db.Db, id: string): Promise<boolean> {
   const failedSince = new Date(
     Date.now() - SponsoredTransactions.failedIntentRecoveryTtlMs,
   ).toISOString()
-  const record = await db.kysely
+  const sponsorship = await db.kysely
     .selectFrom('sponsored_transactions')
     .select('id')
     .where('orgId', '=', id)
@@ -176,7 +250,12 @@ export async function hasUnreportedSponsorships(db: Db.Db, id: string): Promise<
     .where(unreportedSponsorshipStatus(failedSince))
     .limit(1)
     .executeTakeFirst()
-  return record !== undefined
+  if (sponsorship) return true
+  const [deposit, transfer] = await Promise.all([
+    RoutesDeposits.hasUnreportedSubsidies(db, { orgId: id }),
+    RoutesTransfers.hasUnreportedSubsidies(db, id),
+  ])
+  return deposit || transfer
 }
 
 /**
@@ -428,7 +507,7 @@ export declare namespace update {
 
 /**
  * Replaces the organization's sponsorship subsidy policy. A null duration
- * disables the program; an enabled policy may omit its per-project spend cap.
+ * disables the program; an enabled policy may omit its per-attribution spend cap.
  *
  * @param db - The database.
  * @param id - The organization id (`org_…`).
@@ -444,7 +523,7 @@ export function setSponsorshipSubsidy(
     .updateTable('organizations')
     .set({
       sponsorshipSubsidyDurationDays: input.durationDays,
-      sponsorshipSubsidyProjectSpendLimit: input.projectSpendLimit,
+      sponsorshipSubsidyProjectSpendLimit: input.attributionSpendLimit,
       updatedAt: new Date().toISOString(),
     })
     .where('id', '=', id)
@@ -456,16 +535,16 @@ export declare namespace setSponsorshipSubsidy {
   /** Replacement organization subsidy policy. */
   type Input =
     | {
+        /** Optional decimal USD spend cap applied independently to each attribution. */
+        attributionSpendLimit: string | null
         /** Fixed promotion duration in days. */
         durationDays: 90
-        /** Optional decimal USD spend cap applied independently to each project. */
-        projectSpendLimit: string | null
       }
     | {
         /** Null disables the promotion. */
-        durationDays: null
+        attributionSpendLimit: null
         /** Null disables the promotion. */
-        projectSpendLimit: null
+        durationDays: null
       }
 }
 
@@ -519,7 +598,12 @@ function unreportedSponsorshipStatus(failedSince: string) {
     ])
 }
 
-/** Organization deletion is blocked until billable sponsorships settle. */
-export class UnreportedSponsorshipsError extends Error {
-  override name = 'Organizations.UnreportedSponsorshipsError'
+/** Organization deletion is blocked by a provider subsidy that cannot be revoked. */
+export class IrrevocableDepositAddressError extends Error {
+  override name = 'Organizations.IrrevocableDepositAddressError'
+}
+
+/** Organization deletion is blocked until billable metered usage settles. */
+export class UnreportedMeteredUsageError extends Error {
+  override name = 'Organizations.UnreportedMeteredUsageError'
 }

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

@@ -6,6 +6,22 @@ import * as Projects from './projects.js'
 
 const create = () => Db.postgres({ connectionString: Runtime.postgresUrl, schema: `t_${nanoid()}` })
 
+describe('create', () => {
+  test('behavior: accepts a deterministic id', async () => {
+    const db = create()
+    await db.migrate()
+
+    const project = await Projects.create(db, {
+      id: 'prj_000000000000000000000001',
+      name: 'Routes demo',
+      orgId: 'org_1',
+    })
+
+    expect(project.id).toMatchInlineSnapshot(`"prj_000000000000000000000001"`)
+    await db.close()
+  })
+})
+
 describe('activateSponsorship', () => {
   test('behavior: stores the first activation time once', async () => {
     const db = create()

package/src/db/tables/projects.ts

@@ -3,6 +3,8 @@ import { sql, type Selectable } from 'kysely'
 import * as Id from '../../internal/Id.js'
 import type * as Db from '../Db.js'
 import type * as db_Schema from '../Schema.js'
+import * as ApiKeyAdmissions from './apiKeyAdmissions.js'
+import * as ApiKeyOwnerTombstones from './apiKeyOwnerTombstones.js'
 
 /** Columns of the `projects` table, derived from `Schema.Project`. */
 export type Table = db_Schema.Project
@@ -23,7 +25,7 @@ export function create(db: Db.Db, input: create.Input): Promise<Record> {
     .insertInto('projects')
     .values({
       createdAt: now,
-      id: Id.generate('prj'),
+      id: input.id ?? Id.generate('prj'),
       name: input.name,
       orgId: input.orgId,
       sponsorshipSubsidyEndsAt: null,
@@ -38,6 +40,8 @@ export function create(db: Db.Db, input: create.Input): Promise<Record> {
 export declare namespace create {
   /** Fields accepted when inserting a project. */
   type Input = {
+    /** Explicit id; a generated `prj_…` handle is used when omitted. */
+    id?: string | undefined
     /** Human-readable project name. */
     name: string
     /** Owning organization id (`org_…`). */
@@ -53,8 +57,14 @@ export declare namespace create {
  * @returns Whether the project existed and was deleted.
  */
 export async function deleteProject(db: Db.Db, id: string): Promise<boolean> {
-  const result = await db.kysely.deleteFrom('projects').where('id', '=', id).executeTakeFirst()
-  return result.numDeletedRows > 0n
+  return db.transaction(async (tx) => {
+    const project = await get(tx, id)
+    if (!project) return false
+    await ApiKeyOwnerTombstones.markDeleted(tx, { orgId: project.orgId, projectId: id })
+    await ApiKeyAdmissions.releaseOwner(tx, { orgId: project.orgId, projectId: id })
+    const result = await tx.kysely.deleteFrom('projects').where('id', '=', id).executeTakeFirst()
+    return result.numDeletedRows > 0n
+  })
 }
 
 /**

package/src/db/tables/requestUsage.ts

@@ -104,7 +104,10 @@ export async function listPending(db: Db.Db, environment: Environment): Promise<
  * @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> {
+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')])

package/src/db/tables/rewardAccounts.ts

@@ -0,0 +1,178 @@
+import type { ColumnType, JSONColumnType, Selectable } from 'kysely'
+import type { Address } from 'viem'
+
+import type * as Campaigns from '../../internal/rewards/Campaigns.js'
+import type * as Db from '../Db.js'
+import type * as db_Schema from '../Schema.js'
+
+/** Columns of the `reward_accounts` table. */
+export type Table = Omit<db_Schema.RewardAccount, 'chainId' | 'lots'> & {
+  /** Bigint chain id, read as a string from pg and written as a number. */
+  chainId: ColumnType<string, number, number>
+  /** Surviving qualified deposit lots. */
+  lots: JSONColumnType<Campaigns.DepositLot[], string, string>
+}
+
+/** A stored current recipient projection. */
+export type Record = db_Schema.RewardAccount
+
+/** Reads one recipient projection. */
+export async function get(db: Db.Db, options: get.Options): Promise<Record | undefined> {
+  const row = await db.kysely
+    .selectFrom('reward_accounts')
+    .selectAll()
+    .where('chainId', '=', String(options.chainId))
+    .where('vaultAddress', '=', normalize(options.vaultAddress))
+    .where('recipient', '=', normalize(options.recipient))
+    .executeTakeFirst()
+  return row ? toRecord(row) : undefined
+}
+
+export declare namespace get {
+  /** Recipient projection identity. */
+  type Options = {
+    /** Chain containing the vault. */
+    chainId: number
+    /** Registered recipient. */
+    recipient: string
+    /** EarnVault address. */
+    vaultAddress: string
+  }
+}
+
+/** Lists one campaign's current recipient projections. */
+export async function list(db: Db.Db, options: list.Options): Promise<Record[]> {
+  const rows = await db.kysely
+    .selectFrom('reward_accounts')
+    .selectAll()
+    .where('chainId', '=', String(options.chainId))
+    .where('vaultAddress', '=', normalize(options.vaultAddress))
+    .orderBy('recipient', 'asc')
+    .execute()
+  return rows.map(toRecord)
+}
+
+export declare namespace list {
+  /** Campaign identity. */
+  type Options = {
+    /** Chain containing the vault. */
+    chainId: number
+    /** EarnVault address. */
+    vaultAddress: string
+  }
+}
+
+/** Summarizes current unpaid cumulative entitlement for operations. */
+export async function unpaid(db: Db.Db, options: unpaid.Options): Promise<unpaid.Result> {
+  const rows = await db.kysely
+    .selectFrom('reward_accounts')
+    .select(['cumulativeEntitlement', 'cumulativePaid'])
+    .where('chainId', '=', String(options.chainId))
+    .where('vaultAddress', '=', normalize(options.vaultAddress))
+    .whereRef('cumulativeEntitlement', '>', 'cumulativePaid')
+    .execute()
+  return {
+    earnShares: rows
+      .reduce(
+        (sum, row) => sum + BigInt(row.cumulativeEntitlement) - BigInt(row.cumulativePaid),
+        0n,
+      )
+      .toString(),
+    recipients: rows.length,
+  }
+}
+
+export declare namespace unpaid {
+  /** Campaign selector. */
+  type Options = {
+    /** Chain containing the vault. */
+    chainId: number
+    /** EarnVault address. */
+    vaultAddress: string
+  }
+
+  /** Current unpaid totals. */
+  type Result = {
+    /** Unpaid EarnShare units. */
+    earnShares: string
+    /** Recipients with a positive unpaid delta. */
+    recipients: number
+  }
+}
+
+/** Atomically replaces delivered projections for one campaign. */
+export async function replace(db: Db.Db, options: replace.Options): Promise<void> {
+  await db.kysely
+    .deleteFrom('reward_accounts')
+    .where('chainId', '=', String(options.chainId))
+    .where('vaultAddress', '=', normalize(options.vaultAddress))
+    .execute()
+  if (options.accounts.length === 0) return
+  for (let offset = 0; offset < options.accounts.length; offset += 500)
+    await db.kysely
+      .insertInto('reward_accounts')
+      .values(
+        options.accounts.slice(offset, offset + 500).map((account) => ({
+          ...account,
+          chainId: options.chainId,
+          lots: JSON.stringify(account.lots),
+          recipient: normalize(account.recipient),
+          vaultAddress: normalize(options.vaultAddress),
+        })),
+      )
+      .execute()
+}
+
+export declare namespace replace {
+  /** Closing projections for one delivered run. */
+  type Options = {
+    /** Recipient projections without campaign identity. */
+    accounts: readonly Omit<Record, 'chainId' | 'vaultAddress'>[]
+    /** Chain containing the vault. */
+    chainId: number
+    /** EarnVault address. */
+    vaultAddress: Address
+  }
+}
+
+/**
+ * Clears deposit-derived state for the given recipients. A zero-state account
+ * without a registration version is replayed from history by the next run.
+ */
+export async function resetPrincipal(db: Db.Db, options: resetPrincipal.Options): Promise<number> {
+  const recipients = [...new Set(options.recipients.map(normalize))]
+  if (recipients.length === 0) return 0
+  const result = await db.kysely
+    .updateTable('reward_accounts')
+    .set({
+      allocatedPrincipalAssets: '0',
+      eligibilityRegisteredAt: null,
+      lots: JSON.stringify([]),
+      qualifiedEarnShares: '0',
+    })
+    .where('chainId', '=', String(options.chainId))
+    .where('vaultAddress', '=', normalize(options.vaultAddress))
+    .where('recipient', 'in', recipients)
+    .executeTakeFirst()
+  return Number(result.numUpdatedRows)
+}
+
+export declare namespace resetPrincipal {
+  /** Recipients whose deposit-derived state is cleared. */
+  type Options = {
+    /** Chain containing the vault. */
+    chainId: number
+    /** Registered recipients to reset. */
+    recipients: readonly string[]
+    /** EarnVault address. */
+    vaultAddress: string
+  }
+}
+
+function normalize(address: string): Address {
+  return address.toLowerCase() as Address
+}
+
+function toRecord(row: Selectable<Table>): Record {
+  return { ...row, chainId: Number(row.chainId) }
+}

package/src/db/tables/rewardCampaignDistributors.ts

@@ -0,0 +1,68 @@
+import type { ColumnType } from 'kysely'
+import type { Address } from 'viem'
+
+import type * as Db from '../Db.js'
+import type * as db_Schema from '../Schema.js'
+
+/** Columns of the `reward_campaign_distributors` table. */
+export type Table = Omit<db_Schema.RewardCampaignDistributor, 'chainId'> & {
+  /** Bigint chain id, read as a string from pg and written as a number. */
+  chainId: ColumnType<string, number, number>
+}
+
+/** A stored historical reward distributor. */
+export type Record = db_Schema.RewardCampaignDistributor
+
+/** Retains one verified reward distributor for historical payout recognition. */
+export async function add(db: Db.Db, options: add.Options): Promise<void> {
+  await db.kysely
+    .insertInto('reward_campaign_distributors')
+    .values({
+      chainId: options.chainId,
+      createdAt: new Date().toISOString(),
+      distributorAddress: normalize(options.distributorAddress),
+      vaultAddress: normalize(options.vaultAddress),
+    })
+    .onConflict((oc) => oc.doNothing())
+    .execute()
+}
+
+export declare namespace add {
+  /** Verified distributor identity. */
+  type Options = {
+    /** Chain containing the vault. */
+    chainId: number
+    /** Verified reward distributor address. */
+    distributorAddress: Address
+    /** EarnVault address. */
+    vaultAddress: Address
+  }
+}
+
+/** Lists every verified reward distributor for one vault. */
+export async function list(db: Db.Db, options: list.Options): Promise<Record[]> {
+  const rows = await db.kysely
+    .selectFrom('reward_campaign_distributors')
+    .selectAll()
+    .where('chainId', '=', String(options.chainId))
+    .where('vaultAddress', '=', normalize(options.vaultAddress))
+    .orderBy('createdAt')
+    .orderBy('distributorAddress')
+    .execute()
+  return rows.map((row) => ({ ...row, chainId: Number(row.chainId) }))
+}
+
+export declare namespace list {
+  /** Campaign identity. */
+  type Options = {
+    /** Chain containing the vault. */
+    chainId: number
+    /** EarnVault address. */
+    vaultAddress: Address
+  }
+}
+
+/** Canonicalizes persisted addresses. */
+function normalize(address: string): Address {
+  return address.toLowerCase() as Address
+}