tapimo 0.2.0 → 0.3.0

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

@@ -0,0 +1,109 @@
+import { nanoid } from 'nanoid'
+
+import { postgresUrl } from '../../../test/containers.js'
+import * as Db from '../Db.js'
+import * as StripeCustomers from './stripeCustomers.js'
+
+const create = () => Db.postgres({ connectionString: postgresUrl, schema: `t_${nanoid()}` })
+
+/** Redacts nondeterministic row fields (timestamps). */
+function redact(record: StripeCustomers.Record) {
+  return { ...record, createdAt: '<timestamp>', updatedAt: '<timestamp>' }
+}
+
+describe('create', () => {
+  test('behavior: inserts with status none', async () => {
+    const db = create()
+    await db.migrate()
+    const record = await StripeCustomers.create(db, {
+      orgId: 'org_1',
+      stripeCustomerId: 'cus_a',
+    })
+    expect(redact(record)).toMatchInlineSnapshot(`
+      {
+        "createdAt": "<timestamp>",
+        "environment": "production",
+        "orgId": "org_1",
+        "status": "none",
+        "stripeCustomerId": "cus_a",
+        "updatedAt": "<timestamp>",
+      }
+    `)
+    await db.close()
+  })
+
+  test('behavior: a concurrent duplicate resolves to the winning row', async () => {
+    const db = create()
+    await db.migrate()
+    const winner = await StripeCustomers.create(db, { orgId: 'org_1', stripeCustomerId: 'cus_a' })
+    // Loser of the first-checkout race: same org, its own Stripe customer.
+    const resolved = await StripeCustomers.create(db, { orgId: 'org_1', stripeCustomerId: 'cus_b' }) // prettier-ignore
+    expect(resolved).toStrictEqual(winner)
+    expect(await StripeCustomers.getByCustomer(db, 'cus_b')).toBeUndefined()
+    await db.close()
+  })
+})
+
+describe('get', () => {
+  test('behavior: reads by org; undefined when absent', async () => {
+    const db = create()
+    await db.migrate()
+    const record = await StripeCustomers.create(db, { orgId: 'org_1', stripeCustomerId: 'cus_a' })
+    expect(await StripeCustomers.get(db, 'org_1')).toStrictEqual(record)
+    expect(await StripeCustomers.get(db, 'org_missing')).toBeUndefined()
+    await db.close()
+  })
+
+  test('behavior: production and sandbox rows coexist per org and read disjointly', async () => {
+    const db = create()
+    await db.migrate()
+    const production = await StripeCustomers.create(db, { orgId: 'org_1', stripeCustomerId: 'cus_live' }) // prettier-ignore
+    const sandbox = await StripeCustomers.create(db, { environment: 'sandbox', orgId: 'org_1', stripeCustomerId: 'cus_test' }) // prettier-ignore
+    expect(sandbox.environment).toBe('sandbox')
+    expect(await StripeCustomers.get(db, 'org_1')).toStrictEqual(production)
+    expect(await StripeCustomers.get(db, 'org_1', 'sandbox')).toStrictEqual(sandbox)
+    await db.close()
+  })
+})
+
+describe('getByCustomer', () => {
+  test('behavior: reads by Stripe customer id; undefined for unknown customers', async () => {
+    const db = create()
+    await db.migrate()
+    const record = await StripeCustomers.create(db, { orgId: 'org_1', stripeCustomerId: 'cus_a' })
+    expect(await StripeCustomers.getByCustomer(db, 'cus_a')).toStrictEqual(record)
+    expect(await StripeCustomers.getByCustomer(db, 'cus_unknown')).toBeUndefined()
+    await db.close()
+  })
+})
+
+describe('setStatus', () => {
+  test('behavior: persists the status and bumps updatedAt', async () => {
+    const db = create()
+    await db.migrate()
+    const record = await StripeCustomers.create(db, { orgId: 'org_1', stripeCustomerId: 'cus_a' })
+    const updated = await StripeCustomers.setStatus(db, 'org_1', 'active')
+    expect(updated?.status).toMatchInlineSnapshot(`"active"`)
+    expect(updated?.createdAt).toBe(record.createdAt)
+    await db.close()
+  })
+
+  test('behavior: undefined when the org has no billing account', async () => {
+    const db = create()
+    await db.migrate()
+    expect(await StripeCustomers.setStatus(db, 'org_missing', 'active')).toBeUndefined()
+    await db.close()
+  })
+})
+
+describe('deleteByOrg', () => {
+  test('behavior: deletes the row; false when absent', async () => {
+    const db = create()
+    await db.migrate()
+    await StripeCustomers.create(db, { orgId: 'org_1', stripeCustomerId: 'cus_a' })
+    expect(await StripeCustomers.deleteByOrg(db, 'org_1')).toBe(true)
+    expect(await StripeCustomers.get(db, 'org_1')).toBeUndefined()
+    expect(await StripeCustomers.deleteByOrg(db, 'org_1')).toBe(false)
+    await db.close()
+  })
+})

package/src/db/tables/stripeCustomers.ts

@@ -0,0 +1,162 @@
+import type { Selectable } from 'kysely'
+
+import type * as Db from '../Db.js'
+import type * as db_Schema from '../Schema.js'
+
+/** Columns of the `stripe_customers` table, derived from `Schema.StripeCustomer`. */
+export type Table = db_Schema.StripeCustomer
+
+/** A stored Stripe billing-source row. */
+export type Record = Selectable<Table>
+
+/** A billing status. */
+export type Status = Record['status']
+
+/** Billing statuses; `active` alone opens the production sponsorship gate. */
+export const statuses = ['active', 'canceled', 'none', 'past_due'] as const satisfies readonly Status[] // prettier-ignore
+
+/**
+ * Inserts a Stripe billing source (status `none`) and returns the stored record.
+ * Idempotent per organization: a concurrent first-checkout race resolves to
+ * the winner's row — the loser's Stripe customer stays orphaned in Stripe,
+ * which is harmless.
+ *
+ * @param db - The database.
+ * @param input - The Stripe source to insert.
+ * @returns The stored record.
+ */
+export async function create(db: Db.Db, input: create.Input): Promise<Record> {
+  const now = new Date().toISOString()
+  const environment = input.environment ?? 'production'
+  const inserted = await db.kysely
+    .insertInto('stripe_customers')
+    .values({
+      createdAt: now,
+      environment,
+      orgId: input.orgId,
+      status: 'none',
+      stripeCustomerId: input.stripeCustomerId,
+      updatedAt: now,
+    })
+    // Untargeted so it holds against either the org pkey (before the pkey drop
+    // release) or the `(org_id, environment)` unique index (after).
+    .onConflict((oc) => oc.doNothing())
+    .returningAll()
+    .executeTakeFirst()
+  if (inserted) return inserted
+  return await db.kysely
+    .selectFrom('stripe_customers')
+    .selectAll()
+    .where('orgId', '=', input.orgId)
+    .where('environment', '=', environment)
+    .executeTakeFirstOrThrow()
+}
+
+export declare namespace create {
+  /** Fields accepted when inserting a Stripe billing source. */
+  type Input = {
+    /** Environment this source backs; defaults to `production`. */
+    environment?: Record['environment'] | undefined
+    /** Organization id (`org_…`) the Stripe source belongs to. */
+    orgId: string
+    /** Stripe customer id backing this account. */
+    stripeCustomerId: string
+  }
+}
+
+/**
+ * Deletes an organization's Stripe billing source. The Stripe customer is never
+ * deleted; its invoice history stays in Stripe for audit.
+ *
+ * @param db - The database.
+ * @param orgId - The organization id (`org_…`).
+ * @returns Whether a Stripe source existed and was deleted.
+ */
+export async function deleteByOrg(db: Db.Db, orgId: string): Promise<boolean> {
+  const result = await db.kysely
+    .deleteFrom('stripe_customers')
+    .where('orgId', '=', orgId)
+    .executeTakeFirst()
+  return result.numDeletedRows > 0n
+}
+
+/**
+ * Reads an organization's Stripe billing source.
+ *
+ * @param db - The database.
+ * @param orgId - The organization id (`org_…`).
+ * @param environment - The environment to read; defaults to `production`.
+ * @returns The stored record, or `undefined` when the org has none.
+ */
+export function get(
+  db: Db.Db,
+  orgId: string,
+  environment: Record['environment'] = 'production',
+): Promise<Record | undefined> {
+  return db.kysely
+    .selectFrom('stripe_customers')
+    .selectAll()
+    .where('orgId', '=', orgId)
+    .where('environment', '=', environment)
+    .executeTakeFirst()
+}
+
+/**
+ * Lists every billing source in an environment — the driver set for the cron
+ * job that reconciles cached billing snapshots (e.g. API-key records) against
+ * this authoritative table.
+ *
+ * @param db - The database.
+ * @param environment - The environment to enumerate.
+ * @returns The stored records for that environment.
+ */
+export function listByEnvironment(
+  db: Db.Db,
+  environment: Record['environment'],
+): Promise<Record[]> {
+  return db.kysely
+    .selectFrom('stripe_customers')
+    .selectAll()
+    .where('environment', '=', environment)
+    .execute()
+}
+
+/**
+ * Reads a Stripe billing source by its customer id — the webhook handler's
+ * lookup for inbound events.
+ *
+ * @param db - The database.
+ * @param stripeCustomerId - The Stripe customer id.
+ * @returns The stored record, or `undefined` for unknown customers.
+ */
+export function getByCustomer(db: Db.Db, stripeCustomerId: string): Promise<Record | undefined> {
+  return db.kysely
+    .selectFrom('stripe_customers')
+    .selectAll()
+    .where('stripeCustomerId', '=', stripeCustomerId)
+    .executeTakeFirst()
+}
+
+/**
+ * Sets an organization's billing status.
+ *
+ * @param db - The database.
+ * @param orgId - The organization id (`org_…`).
+ * @param status - The derived status to persist.
+ * @param environment - The environment to update; defaults to `production`.
+ * @returns The updated record, or `undefined` when the org has no Stripe source.
+ */
+export function setStatus(
+  db: Db.Db,
+  orgId: string,
+  status: Status,
+  environment: Record['environment'] = 'production',
+): Promise<Record | undefined> {
+  return db.kysely
+    .updateTable('stripe_customers')
+    .set({ status, updatedAt: new Date().toISOString() })
+    .where('orgId', '=', orgId)
+    .where('environment', '=', environment)
+    .returningAll()
+    .executeTakeFirst()
+}

package/src/db/tables/users.ts

@@ -1,6 +1,6 @@
 import type { Selectable } from 'kysely'
-import { nanoid } from 'nanoid'
 
+import * as Id from '../../internal/Id.js'
 import type * as Db from '../Db.js'
 import type * as db_Schema from '../Schema.js'
 
@@ -49,7 +49,7 @@ export async function upsertByAddress(db: Db.Db, input: upsertByAddress.Input):
   const now = new Date().toISOString()
   const inserted = await db.kysely
     .insertInto('users')
-    .values({ address, createdAt: now, email: null, id: `usr_${nanoid()}`, updatedAt: now })
+    .values({ address, createdAt: now, email: null, id: Id.generate('usr'), updatedAt: now })
     .onConflict((oc) => oc.column('address').doNothing())
     .returningAll()
     .executeTakeFirst()

package/src/handlers/internal/sponsorship.ts

@@ -9,11 +9,30 @@ import * as Utils from './utils.js'
 /**
  * Sponsorship approval callback. The candidate always carries its `chainId`:
  * raw submissions deserialize it, and fills validate only prepared/filled
- * transactions.
+ * transactions. Anything but `true` refuses; raw submissions surface a named
+ * reason to the caller while fills fall back to an unsponsored fill.
  */
 export type Validate = (
   request: Transaction.TransactionRequest & { chainId?: number | Hex.Hex | undefined },
-) => boolean | Promise<boolean>
+) => Validation | Promise<Validation>
+
+/** A sponsorship verdict: `true` sponsors; `false` or a named reason refuses. */
+export type Validation =
+  | boolean
+  | 'billing_past_due'
+  | 'billing_required'
+  | 'fee_token_unsupported'
+  | 'spend_limit_exceeded'
+  | 'tx_fee_limit_exceeded'
+
+/** Refusal messages keyed by named validation reason. */
+const refusalMessages = {
+  billing_past_due: 'Billing past due.',
+  billing_required: 'Billing required.',
+  fee_token_unsupported: 'Fee token unsupported.',
+  spend_limit_exceeded: 'Spend limit exceeded.',
+  tx_fee_limit_exceeded: 'Transaction fee limit exceeded.',
+} as const satisfies Record<Exclude<Validation, boolean>, string>
 
 /** Returns sponsor metadata for `eth_fillTransaction` responses. */
 export function getSponsor(options: getSponsor.Options): getSponsor.ReturnType {
@@ -49,10 +68,13 @@ export declare namespace getSponsor {
 export async function shouldSponsor(options: shouldSponsor.Options) {
   const { sender, transaction, validate } = options
   if (!validate) return true
-  return await validate({
+  // Named refusal reasons collapse to false: fills fall back to an
+  // unsponsored fill instead of surfacing the reason.
+  const verdict = await validate({
     ...transaction,
     from: sender,
   } as Transaction.TransactionRequest)
+  return verdict === true
 }
 
 export declare namespace shouldSponsor {
@@ -166,10 +188,15 @@ export async function handleRawTransaction(options: handleRawTransaction.Options
     feeToken_chain
   const transaction_sponsored = feeToken ? { ...transaction, feeToken } : transaction
 
-  if (validate && !(await validate(transaction_sponsored as Transaction.TransactionRequest)))
-    throw new RpcResponse.InvalidParamsError({
-      message: 'Sponsorship rejected.',
-    })
+  if (validate) {
+    const verdict = await validate(transaction_sponsored as Transaction.TransactionRequest)
+    if (verdict !== true)
+      throw new RpcResponse.InvalidParamsError(
+        verdict === false
+          ? { message: 'Sponsorship rejected.' }
+          : { data: { code: verdict }, message: refusalMessages[verdict] },
+      )
+  }
 
   const envelope = TxEnvelopeTempo.from(transaction_sponsored as never)
   const signPayload = TxEnvelopeTempo.getFeePayerSignPayload(envelope, { sender })

package/src/handlers/internal/utils.ts

@@ -80,18 +80,30 @@ export function normalizeTempoTransaction(value: Record<string, unknown> | undef
 
 /** Returns a raw JSON-RPC error response object (not wrapped in a `Response`). */
 export function rpcErrorJson(request: RpcRequest.RpcRequest, error: unknown) {
-  if (error instanceof RpcResponse.InvalidParamsError)
-    return RpcResponse.from({ error }, { request })
-
-  if (error instanceof RpcResponse.MethodNotSupportedError)
-    return RpcResponse.from({ error }, { request })
+  // Serialize error instances to plain objects: `Error.message` is
+  // non-enumerable, so instances stringify onto the wire without it.
+  if (
+    error instanceof RpcResponse.InvalidParamsError ||
+    error instanceof RpcResponse.MethodNotSupportedError
+  )
+    return RpcResponse.from(
+      {
+        error: {
+          code: error.code,
+          message: error.message,
+          ...(error.data !== undefined ? { data: error.data } : {}),
+        },
+      },
+      { request },
+    )
 
   if ((error as { name?: string | undefined }).name === 'ZodError')
     return RpcResponse.from(
       {
-        error: new RpcResponse.InvalidParamsError({
+        error: {
+          code: RpcResponse.InvalidParamsError.code,
           message: (error as Error).message,
-        }),
+        },
       },
       { request },
     )

package/src/index.ts

@@ -1,3 +1,4 @@
+export * as Analytics from './analytics/Analytics.js'
 export * as ApiKey from './ApiKey.js'
 export * as ApiKeys from './ApiKeys.js'
 export * as App from './App.js'