tapimo 0.15.1 → 0.18.0

package/src/db/Schema.ts

@@ -8,10 +8,27 @@ import type * as routes_Catalog from '../internal/routes/Catalog.js'
 import type * as routes_Deposit from '../internal/routes/Deposit.js'
 import type * as routes_DepositAddress from '../internal/routes/DepositAddress.js'
 import type * as routes_Provider from '../internal/routes/Provider.js'
+import type * as routes_Policy from '../internal/routes/Policy.js'
 import type * as routes_Transfer from '../internal/routes/Transfer.js'
 import type * as routes_TransferSubsidy from '../internal/routes/TransferSubsidy.js'
 import type * as internal_Schema from '../internal/Schema.js'
 import type * as Webhooks from '../internal/Webhooks.js'
+import type * as Scope from '../Scope.js'
+
+/** Route policy overrides stored as jsonb. */
+export const RoutesPolicyOverrides = z.custom<routes_Policy.Overrides>()
+/** Columns of the `routes_policies` table. */
+export const RoutesPolicy = z.object({
+  apiKeyId: z.string(),
+  createdAt: z.string(),
+  environment: z.enum(['production', 'sandbox']),
+  orgId: z.string(),
+  policy: RoutesPolicyOverrides,
+  projectId: z.string(),
+  updatedAt: z.string(),
+  version: z.number().check(z.int(), z.nonnegative()),
+})
+export type RoutesPolicy = z.output<typeof RoutesPolicy>
 
 /** One authenticated administrator access to a protected admin API route. */
 export const AdminAuditLog = z.object({
@@ -56,6 +73,7 @@ export const ApiKeyAdmission = z.object({
   expiresAt: z.nullable(z.string()),
   id: z.string(),
   orgId: z.string(),
+  pendingScopes: z.nullable(z.custom<readonly Scope.Id[]>()),
   projectId: z.nullable(z.string()),
 })
 
@@ -185,6 +203,11 @@ export const EarnVault = z
     description: z
       .nullable(z.string())
       .check(z.describe('Curated vault description, or null when absent.')),
+    earnings: z
+      .custom<z.output<typeof EarnVaults.schema.Earnings> | null>()
+      .check(
+        z.describe('Additional reward distributors beyond campaign history, or null for none.'),
+      ),
     label: z.string().check(z.describe('Curated vault label.')),
     privateInputTokens: z
       .custom<readonly Address[]>()
@@ -410,7 +433,12 @@ export const RequestUsageMeterEvent = z.object({
   environment: z
     .enum(['production', 'sandbox'])
     .check(z.describe('Environment the requests were served under; `production` or `sandbox`.')),
-  error: z.nullable(z.string()).check(z.describe('Last failure detail while `pending`, or null.')),
+  error: z
+    .nullable(z.string())
+    .check(z.describe('Last failure or reconciliation detail, or null.')),
+  eventTimestamp: z
+    .optional(z.string())
+    .check(z.describe('Timestamp sent with this frozen Stripe meter event (ISO 8601).')),
   firstAttemptedAt: z.string().check(z.describe('When this event was first claimed (ISO 8601).')),
   identifier: z
     .string()
@@ -694,6 +722,14 @@ export const SponsoredTransaction = z.object({
       z.describe('Opaque sponsored-transaction id (`stx_…`).'),
       z.meta({ examples: ['stx_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
     ),
+  meterEventFirstAttemptedAt: z
+    .nullable(z.string())
+    .check(
+      z.describe('When this sponsorship first reached Stripe submission (ISO 8601), or null.'),
+    ),
+  meterReportAttemptedAt: z
+    .nullable(z.string())
+    .check(z.describe('When billing last claimed this row for reporting (ISO 8601), or null.')),
   meterReportedAt: z
     .nullable(z.string())
     .check(z.describe('When the row was reported to the billing meter (ISO 8601), or null; exactly-once marker.')), // prettier-ignore
@@ -713,6 +749,9 @@ export const SponsoredTransaction = z.object({
   transactionHash: z
     .nullable(z.string())
     .check(z.describe('Transaction hash, or null for fill intents until reconciled.')),
+  transactionHashReconciled: z
+    .boolean()
+    .check(z.describe('Whether reconciliation confirmed the transaction hash by sign payload.')),
 })
 
 /** Columns of the `sponsored_transactions` table. */
@@ -805,6 +844,13 @@ export const User = z.object({
     ),
   image: z.nullable(z.string()).check(z.describe('Profile image URL, or null.')),
   name: z.string().check(z.describe('Display name.')),
+  termsSharedAt: z
+    .nullable(z.string())
+    .check(
+      z.describe(
+        'When terms links were first included in a successful sign-in response for this user, or null otherwise.',
+      ),
+    ),
   updatedAt: z.string().check(z.describe('When the user was last updated (ISO 8601).')),
 })
 
@@ -1160,13 +1206,20 @@ export const RoutesTransferSubsidy = z.object({
   destinationChainId: z
     .string()
     .check(z.describe('Destination CAIP-2 chain receiving the subsidy.')),
-  recipient: z.string().check(z.describe('Lowercase destination recipient address.')),
+  recipient: z
+    .string()
+    .check(z.describe('Destination recipient address, preserving Tron Base58Check case.')),
   sourceChainId: z
     .string()
     .check(z.describe('Source CAIP-2 chain containing the verified payment.')),
-  tokenAddress: z.string().check(z.describe('Lowercase destination token address.')),
+  status: z
+    .union([z.literal('active'), z.literal('expired')])
+    .check(z.describe('Whether the signed subsidy remains eligible for broadcast.')),
+  tokenAddress: z
+    .string()
+    .check(z.describe('Destination token address, preserving Tron Base58Check case.')),
   transaction: z
-    .custom<routes_TransferSubsidy.Transaction>()
+    .custom<routes_TransferSubsidy.Transaction | string>()
     .check(z.describe('Signed subsidy retained for replay, including after transfer deletion.')),
   transactionRef: z.string().check(z.describe('Canonical source execution transaction reference.')),
   transferId: z
@@ -1177,6 +1230,24 @@ export const RoutesTransferSubsidy = z.object({
 /** Columns of the `routes_transfer_subsidies` table. */
 export type RoutesTransferSubsidy = z.output<typeof RoutesTransferSubsidy>
 
+/** An expired Solana subsidy retained as immutable settlement evidence. */
+export const RoutesTransferSubsidyExpiredAttempt = z.object({
+  createdAt: z.string().check(z.describe('When the signed subsidy was first persisted.')),
+  expiredAt: z.string().check(z.describe('When finality proved the blockhash expired.')),
+  sourceChainId: z.string().check(z.describe('Source CAIP-2 chain.')),
+  transaction: z
+    .custom<routes_TransferSubsidy.Transaction | string>()
+    .check(z.describe('Expired signed transaction retained for audit.')),
+  transactionHash: z.string().check(z.describe('Expired Solana signature.')),
+  transactionRef: z.string().check(z.describe('Canonical source transaction reference.')),
+  transferId: z.string().check(z.describe('Original subsidy billing owner.')),
+})
+
+/** Columns of the `routes_transfer_subsidy_expired_attempts` table. */
+export type RoutesTransferSubsidyExpiredAttempt = z.output<
+  typeof RoutesTransferSubsidyExpiredAttempt
+>
+
 /** One durable next nonce for a destination subsidy signer on an EVM chain. */
 export const RoutesTransferSubsidyNonce = z.object({
   account: z.string().check(z.describe('Lowercase destination subsidy signer address.')),

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

@@ -0,0 +1,57 @@
+import { nanoid } from 'nanoid'
+
+import * as Runtime from '../../../test/runtime.js'
+import * as Db from '../Db.js'
+import * as ApiKeyAdmissions from './apiKeyAdmissions.js'
+
+describe('ledger', () => {
+  test('reads every fact in one query', async () => {
+    const db = Db.postgres({ connectionString: Runtime.postgresUrl, schema: `t_${nanoid()}` })
+    await db.migrate()
+    try {
+      const queries: number[] = []
+      const observed = Db.observe(db, { onQuery: (ms) => queries.push(ms) })
+      const ledger = await ApiKeyAdmissions.ledger(observed, {
+        id: 'key_missing',
+        orgId: 'org_missing',
+      })
+
+      expect(queries).toHaveLength(1)
+      expect(ledger).toMatchInlineSnapshot(`
+        {
+          "admitted": undefined,
+          "bootstrapped": false,
+          "revoked": false,
+          "tombstoned": false,
+        }
+      `)
+    } finally {
+      await db.close()
+    }
+  })
+})
+
+describe('admits', () => {
+  const owner = { id: 'key_1', orgId: 'org_1', projectId: 'proj_1' }
+  const base = { bootstrapped: true, revoked: false, tombstoned: false }
+
+  test('accepts a matching admission', () => {
+    const admitted = { orgId: 'org_1', projectId: 'proj_1' }
+    expect(ApiKeyAdmissions.admits({ ...base, admitted }, owner)).toBe(true)
+  })
+
+  test('rejects a revoked key regardless of admission', () => {
+    const admitted = { orgId: 'org_1', projectId: 'proj_1' }
+    expect(ApiKeyAdmissions.admits({ ...base, admitted, revoked: true }, owner)).toBe(false)
+  })
+
+  test('rejects an admission attributed elsewhere', () => {
+    const admitted = { orgId: 'org_1', projectId: null }
+    expect(ApiKeyAdmissions.admits({ ...base, admitted }, owner)).toBe(false)
+  })
+
+  test('accepts a legacy key only until its organization is imported', () => {
+    expect(ApiKeyAdmissions.admits({ ...base, bootstrapped: false }, owner)).toBe(true)
+    expect(ApiKeyAdmissions.admits(base, owner)).toBe(false)
+  })
+})

package/src/db/tables/apiKeyAdmissions.ts

@@ -1,11 +1,18 @@
-import { sql } from 'kysely'
+import { sql, type JSONColumnType, type Selectable } from 'kysely'
 
 import type * as Db from '../Db.js'
 import type * as db_Schema from '../Schema.js'
+import * as ApiKeyOwnerTombstones from './apiKeyOwnerTombstones.js'
 import * as ApiKeyRevocations from './apiKeyRevocations.js'
 
 /** Columns of the `api_key_admissions` table. */
-export type Table = db_Schema.ApiKeyAdmission
+export type Table = Omit<db_Schema.ApiKeyAdmission, 'pendingScopes'> & {
+  pendingScopes: JSONColumnType<
+    db_Schema.ApiKeyAdmission['pendingScopes'],
+    string | null | undefined,
+    string | null
+  >
+}
 
 /** Returns whether an organization completed its bounded legacy-key import. */
 export async function isBootstrapped(db: Db.Db, orgId: string): Promise<boolean> {
@@ -23,7 +30,7 @@ export async function exists(db: Db.Db, id: string): Promise<boolean> {
 }
 
 /** Reads one authoritative admission row. */
-export async function get(db: Db.Db, id: string): Promise<Table | undefined> {
+export async function get(db: Db.Db, id: string): Promise<Selectable<Table> | undefined> {
   return db.kysely
     .selectFrom('api_key_admissions')
     .selectAll()
@@ -31,6 +38,19 @@ export async function get(db: Db.Db, id: string): Promise<Table | undefined> {
     .executeTakeFirst()
 }
 
+/** Replaces or clears the scope publication intent while holding the key lock. */
+export async function setPendingScopes(
+  db: Db.Db,
+  id: string,
+  scopes: db_Schema.ApiKeyAdmission['pendingScopes'],
+): Promise<void> {
+  await db.kysely
+    .updateTable('api_key_admissions')
+    .set({ pendingScopes: scopes === null ? null : JSON.stringify(scopes) })
+    .where('id', '=', id)
+    .execute()
+}
+
 /** Atomically admits a new key or moves an existing key into an organization. */
 export async function admit(db: Db.Db, options: admit.Options): Promise<boolean> {
   await lockOrganization(db, options.orgId)
@@ -150,14 +170,84 @@ export declare namespace admit {
 
 /** Returns whether a ledger-managed key has the supplied attribution. */
 export async function matches(db: Db.Db, owner: matches.Owner): Promise<boolean> {
-  if (await ApiKeyRevocations.exists(db, owner.id)) return false
-  const record = await db.kysely
-    .selectFrom('api_key_admissions')
-    .select(['orgId', 'projectId'])
-    .where('id', '=', owner.id)
-    .executeTakeFirst()
-  if (!record) return !(await isBootstrapped(db, owner.orgId))
-  return record.orgId === owner.orgId && record.projectId === (owner.projectId ?? null)
+  return admits(await ledger(db, owner), owner)
+}
+
+/** Reads one key's admission, revocation, and owner-deletion state in a single round trip for lifecycle checks. */
+export async function ledger(db: Db.Db, owner: matches.Owner): Promise<Ledger> {
+  const now = new Date().toISOString()
+  const row = await db.kysely
+    .selectNoFrom((eb) => [
+      eb
+        .selectFrom('api_key_admissions')
+        .select('orgId')
+        .where('id', '=', owner.id)
+        .as('admittedOrgId'),
+      eb
+        .selectFrom('api_key_admissions')
+        .select('projectId')
+        .where('id', '=', owner.id)
+        .as('admittedProjectId'),
+      eb
+        .exists(
+          eb
+            .selectFrom('api_key_admission_bootstraps')
+            .select('orgId')
+            .where('orgId', '=', owner.orgId),
+        )
+        .as('bootstrapped'),
+      eb
+        .exists(
+          eb
+            .selectFrom('api_key_revocations')
+            .select('id')
+            .where('id', '=', owner.id)
+            .where('expiresAt', '>', now),
+        )
+        .as('revoked'),
+      eb
+        .exists(
+          eb
+            .selectFrom('api_key_owner_tombstones')
+            .select('id')
+            .where('id', 'in', ApiKeyOwnerTombstones.ownerKeys(owner)),
+        )
+        .as('tombstoned'),
+    ])
+    .executeTakeFirstOrThrow()
+  return {
+    admitted:
+      row.admittedOrgId === null || row.admittedOrgId === undefined
+        ? undefined
+        : { orgId: row.admittedOrgId, projectId: row.admittedProjectId ?? null },
+    bootstrapped: Boolean(row.bootstrapped),
+    revoked: Boolean(row.revoked),
+    tombstoned: Boolean(row.tombstoned),
+  }
+}
+
+/** Ledger facts about one key and its owner, read together by {@link ledger}. */
+export type Ledger = {
+  /** Attribution recorded for the key, when it has an admission row. */
+  admitted?: { orgId: string; projectId: string | null } | undefined
+  /** Whether the owning organization completed its legacy-key import. */
+  bootstrapped: boolean
+  /** Whether an unexpired revocation fence exists for the key. */
+  revoked: boolean
+  /** Whether the organization or project carries a deletion tombstone. */
+  tombstoned: boolean
+}
+
+/**
+ * Applies the admission rule: an unrevoked key whose admission row carries the
+ * supplied attribution, or a legacy key of an organization not yet imported.
+ */
+export function admits(ledger: Ledger, owner: matches.Owner): boolean {
+  if (ledger.revoked) return false
+  if (!ledger.admitted) return !ledger.bootstrapped
+  return (
+    ledger.admitted.orgId === owner.orgId && ledger.admitted.projectId === (owner.projectId ?? null)
+  )
 }
 
 export declare namespace matches {

package/src/db/tables/apiKeyOwnerTombstones.ts

@@ -63,8 +63,8 @@ function key(owner: Owner) {
     : `project:${owner.orgId}:${owner.projectId}`
 }
 
-/** Builds the hierarchical lock keys for an owner. */
-function ownerKeys(owner: Owner) {
+/** Builds the hierarchical fence keys for an owner: the organization, then its project. */
+export function ownerKeys(owner: Owner) {
   const keys = [key({ orgId: owner.orgId })]
   if (owner.projectId !== undefined) keys.push(key(owner))
   return keys

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

@@ -0,0 +1,30 @@
+import * as TestApp from '../../../test/App.js'
+import * as AuthAccounts from './authAccounts.js'
+import * as Users from './users.js'
+
+describe('getWalletAddress', () => {
+  test('returns the oldest wallet linked to a user', async () => {
+    const db = TestApp.database()
+    try {
+      const user = await Users.upsertByAddress(db, { address: `0x${'aa'.repeat(20)}` })
+      const newer = `0x${'bb'.repeat(20)}`
+      const older = `0x${'cc'.repeat(20)}`
+      await AuthAccounts.setWalletUser(db, { address: newer, userId: user.id })
+      await AuthAccounts.setWalletUser(db, { address: older, userId: user.id })
+      await db.kysely
+        .updateTable('auth_accounts')
+        .set({ createdAt: '2026-01-02T00:00:00.000Z' })
+        .where('accountId', '=', newer)
+        .execute()
+      await db.kysely
+        .updateTable('auth_accounts')
+        .set({ createdAt: '2026-01-01T00:00:00.000Z' })
+        .where('accountId', '=', older)
+        .execute()
+
+      await expect(AuthAccounts.getWalletAddress(db, user.id)).resolves.toBe(older)
+    } finally {
+      await db.close()
+    }
+  })
+})

package/src/db/tables/authAccounts.ts

@@ -51,6 +51,7 @@ export async function getWalletAddress(db: Db.Db, userId: string): Promise<strin
     .where('issuer', '=', walletIssuer)
     .where('userId', '=', userId)
     .orderBy('createdAt', 'asc')
+    .limit(1)
     .executeTakeFirst()
   return account?.accountId
 }

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

@@ -21,6 +21,39 @@ const input = {
 } as const satisfies EarnVaults.upsert.Options
 
 describe('upsert', () => {
+  test('scopes earnings counterparties by vault and chain, preserving omitted settings', async () => {
+    const db = TestApp.database()
+    const earnings = {
+      rewardDistributors: [
+        input.vaultAddress,
+        input.vaultAddress.toLowerCase() as typeof input.vaultAddress,
+      ],
+    }
+    const stored = await EarnVaults.upsert(db, { ...input, earnings })
+    expect(stored.earnings).toMatchInlineSnapshot(`
+      {
+        "rewardDistributors": [
+          "0x2f05f4d3625b2effb383efbedafd2d8f04371636",
+        ],
+      }
+    `)
+    expect((await EarnVaults.upsert(db, input)).earnings).toEqual(stored.earnings)
+    expect((await EarnVaults.upsert(db, { ...input, chainId: 4217 })).earnings).toBeNull()
+    expect(
+      (await EarnVaults.upsert(db, { ...input, vaultAddress: input.privateInputTokens[0] }))
+        .earnings,
+    ).toBeNull()
+    expect(
+      (
+        await EarnVaults.upsert(db, {
+          ...input,
+          earnings: { rewardDistributors: [] },
+        })
+      ).earnings,
+    ).toEqual({ rewardDistributors: [] })
+    expect((await EarnVaults.upsert(db, { ...input, earnings: null })).earnings).toBeNull()
+  })
+
   test('inserts flattened curated fields and generates a stable slug', async () => {
     vi.useFakeTimers()
     try {
@@ -33,6 +66,7 @@ describe('upsert', () => {
           "chainId": 42431,
           "createdAt": "2026-01-01T00:00:00.000Z",
           "description": "Bridge test PATHUSD deposited into Tempo Earn.",
+          "earnings": null,
           "label": "btPATHUSD Earn",
           "privateInputTokens": [
             "0x20c00000000000000000000057F242B21a53ae4D",

package/src/db/tables/earnVaults.ts

@@ -10,10 +10,12 @@ const slugSuffix = customAlphabet('0123456789abcdefghijklmnopqrstuvwxyz', 8)
 /** Columns of the `earn_vaults` table. */
 export type Table = Omit<
   db_Schema.EarnVault,
-  'chainId' | 'privateInputTokens' | 'privateOutputTokens' | 'zones'
+  'chainId' | 'earnings' | 'privateInputTokens' | 'privateOutputTokens' | 'zones'
 > & {
   /** Bigint chain id, read as a string from pg and written as a number. */
   chainId: ColumnType<string, number, number>
+  /** Additional reward distributors beyond campaign history, or null for none. */
+  earnings: JSONColumnType<db_Schema.EarnVault['earnings']>
   /** Tokens accepted for private deposits. */
   privateInputTokens: JSONColumnType<db_Schema.EarnVault['privateInputTokens'], string, string>
   /** Tokens supported for private redemptions. */
@@ -72,6 +74,7 @@ export async function upsert(db: Db.Db, options: upsert.Options): Promise<Record
       chainId: options.chainId,
       createdAt: now,
       description: options.description,
+      earnings: JSON.stringify(normalizeEarnings(options.earnings ?? null)),
       label: options.label,
       privateInputTokens: JSON.stringify(options.privateInputTokens),
       privateOutputTokens: JSON.stringify(options.privateOutputTokens),
@@ -83,6 +86,9 @@ export async function upsert(db: Db.Db, options: upsert.Options): Promise<Record
     .onConflict((oc) =>
       oc.columns(['chainId', 'vaultAddress']).doUpdateSet({
         description: options.description,
+        ...(options.earnings !== undefined
+          ? { earnings: JSON.stringify(normalizeEarnings(options.earnings)) }
+          : {}),
         label: options.label,
         privateInputTokens: JSON.stringify(options.privateInputTokens),
         privateOutputTokens: JSON.stringify(options.privateOutputTokens),
@@ -103,6 +109,8 @@ export declare namespace upsert {
     chainId: number
     /** Curated vault description. */
     description: string | null
+    /** Omitted preserves additional distributors; null clears them without changing campaign history. */
+    earnings?: db_Schema.EarnVault['earnings'] | undefined
     /** Curated vault label. */
     label: string
     /** Tokens accepted for private deposits. */
@@ -149,7 +157,7 @@ function kebab(label: string): string {
 }
 
 function toRecord(row: Selectable<Table>): Record {
-  return { ...row, chainId: Number(row.chainId) }
+  return { ...row, chainId: Number(row.chainId), earnings: normalizeEarnings(row.earnings) }
 }
 
 function normalize(address: string): Address {
@@ -159,3 +167,10 @@ function normalize(address: string): Address {
 function normalizeZones(zones: db_Schema.EarnVault['zones']): db_Schema.EarnVault['zones'] {
   return zones.map((zone) => ({ ...zone, earnRouter: normalize(zone.earnRouter) }))
 }
+
+function normalizeEarnings(earnings: db_Schema.EarnVault['earnings']) {
+  if (!earnings) return null
+  return {
+    rewardDistributors: [...new Set(earnings.rewardDistributors.map(normalize))].sort(),
+  }
+}