tapimo 0.1.0 → 0.3.0

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

@@ -0,0 +1,87 @@
+import { nanoid } from 'nanoid'
+
+import { postgresUrl } from '../../../test/containers.js'
+import * as Db from '../Db.js'
+import * as BillingSettings from './billingSettings.js'
+
+const create = () => Db.postgres({ connectionString: postgresUrl, schema: `t_${nanoid()}` })
+
+/** Redacts nondeterministic row fields (timestamps). */
+function redact(record: BillingSettings.Record) {
+  return { ...record, createdAt: '<timestamp>', updatedAt: '<timestamp>' }
+}
+
+describe('upsert', () => {
+  test('behavior: inserts defaults for fields not provided', async () => {
+    const db = create()
+    await db.migrate()
+    const record = await BillingSettings.upsert(db, { orgId: 'org_1', spendLimit: '250' })
+    expect(redact(record)).toMatchInlineSnapshot(`
+      {
+        "createdAt": "<timestamp>",
+        "currency": "usd",
+        "environment": "production",
+        "orgId": "org_1",
+        "period": "month",
+        "spendLimit": "250",
+        "txFeeLimit": null,
+        "updatedAt": "<timestamp>",
+      }
+    `)
+    await db.close()
+  })
+
+  test('behavior: absent fields keep their stored value', async () => {
+    const db = create()
+    await db.migrate()
+    await BillingSettings.upsert(db, { orgId: 'org_1', spendLimit: '250' })
+    const record = await BillingSettings.upsert(db, { orgId: 'org_1', txFeeLimit: '0.50' })
+    expect(record.spendLimit).toBe('250')
+    expect(record.txFeeLimit).toBe('0.50')
+    await db.close()
+  })
+
+  test('behavior: null clears a limit without touching the other', async () => {
+    const db = create()
+    await db.migrate()
+    await BillingSettings.upsert(db, { orgId: 'org_1', spendLimit: '250', txFeeLimit: '0.50' }) // prettier-ignore
+    const record = await BillingSettings.upsert(db, { orgId: 'org_1', spendLimit: null })
+    expect(record.spendLimit).toBeNull()
+    expect(record.txFeeLimit).toBe('0.50')
+    await db.close()
+  })
+})
+
+describe('get', () => {
+  test('behavior: returns the stored row, undefined for orgs without settings', async () => {
+    const db = create()
+    await db.migrate()
+    expect(await BillingSettings.get(db, 'org_1')).toBeUndefined()
+    const record = await BillingSettings.upsert(db, { orgId: 'org_1', txFeeLimit: '1' })
+    expect(await BillingSettings.get(db, 'org_1')).toStrictEqual(record)
+    await db.close()
+  })
+
+  test('behavior: production and sandbox settings coexist per org and read disjointly', async () => {
+    const db = create()
+    await db.migrate()
+    const production = await BillingSettings.upsert(db, { orgId: 'org_1', spendLimit: '250' })
+    const sandbox = await BillingSettings.upsert(db, { environment: 'sandbox', orgId: 'org_1', spendLimit: '10' }) // prettier-ignore
+    expect(sandbox.environment).toBe('sandbox')
+    expect(await BillingSettings.get(db, 'org_1')).toStrictEqual(production)
+    expect(await BillingSettings.get(db, 'org_1', 'sandbox')).toStrictEqual(sandbox)
+    await db.close()
+  })
+})
+
+describe('deleteByOrg', () => {
+  test('behavior: deletes the row and reports absence', async () => {
+    const db = create()
+    await db.migrate()
+    await BillingSettings.upsert(db, { orgId: 'org_1', spendLimit: '250' })
+    expect(await BillingSettings.deleteByOrg(db, 'org_1')).toBe(true)
+    expect(await BillingSettings.deleteByOrg(db, 'org_1')).toBe(false)
+    expect(await BillingSettings.get(db, 'org_1')).toBeUndefined()
+    await db.close()
+  })
+})

package/src/db/tables/billingSettings.ts

@@ -0,0 +1,108 @@
+import type { Selectable } from 'kysely'
+
+import type * as Db from '../Db.js'
+import type * as db_Schema from '../Schema.js'
+
+/** Columns of the `billing_settings` table, derived from `Schema.BillingSettings`. */
+export type Table = db_Schema.BillingSettings
+
+/** A stored billing-settings row. */
+export type Record = Selectable<Table>
+
+/** Currencies limits may be denominated in; single-member today, widens without schema changes. */
+export const currencies = ['usd'] as const satisfies readonly Record['currency'][]
+
+/** Spend-limit windows; single-member today, widens without schema changes. */
+export const periods = ['month'] as const satisfies readonly Record['period'][]
+
+/**
+ * Reads an organization's billing settings.
+ *
+ * @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('billing_settings')
+    .selectAll()
+    .where('orgId', '=', orgId)
+    .where('environment', '=', environment)
+    .executeTakeFirst()
+}
+
+/**
+ * Upserts an organization's billing settings with PATCH semantics: absent
+ * fields keep their stored value, `null` clears the limit.
+ *
+ * @param db - The database.
+ * @param input - The settings to apply.
+ * @returns The stored record.
+ */
+export async function upsert(db: Db.Db, input: upsert.Input): Promise<Record> {
+  const now = new Date().toISOString()
+  const environment = input.environment ?? 'production'
+  return await db.kysely
+    .insertInto('billing_settings')
+    .values({
+      createdAt: now,
+      currency: input.currency ?? 'usd',
+      environment,
+      orgId: input.orgId,
+      period: input.period ?? 'month',
+      spendLimit: input.spendLimit ?? null,
+      txFeeLimit: input.txFeeLimit ?? null,
+      updatedAt: now,
+    })
+    // Targets the `(org_id, environment)` unique index, which exists both
+    // before and after the org pkey drop release.
+    .onConflict((oc) =>
+      oc.columns(['orgId', 'environment']).doUpdateSet({
+        ...(input.currency !== undefined ? { currency: input.currency } : {}),
+        ...(input.period !== undefined ? { period: input.period } : {}),
+        ...(input.spendLimit !== undefined ? { spendLimit: input.spendLimit } : {}),
+        ...(input.txFeeLimit !== undefined ? { txFeeLimit: input.txFeeLimit } : {}),
+        updatedAt: now,
+      }),
+    )
+    .returningAll()
+    .executeTakeFirstOrThrow()
+}
+
+export declare namespace upsert {
+  /** Fields accepted when upserting billing settings; absent = unchanged, null = cleared. */
+  type Input = {
+    /** Currency both limits are denominated in. */
+    currency?: Record['currency'] | undefined
+    /** Environment these settings apply to; defaults to `production`. */
+    environment?: Record['environment'] | undefined
+    /** Organization id (`org_…`) the settings belong to. */
+    orgId: string
+    /** Spend-limit window. */
+    period?: Record['period'] | undefined
+    /** Spend limit per period (decimal string in `currency` units), or null to clear. */
+    spendLimit?: string | null | undefined
+    /** Per-transaction fee cap (decimal string in `currency` units), or null to clear. */
+    txFeeLimit?: string | null | undefined
+  }
+}
+
+/**
+ * Deletes an organization's billing settings.
+ *
+ * @param db - The database.
+ * @param orgId - The organization id (`org_…`).
+ * @returns Whether a settings row existed and was deleted.
+ */
+export async function deleteByOrg(db: Db.Db, orgId: string): Promise<boolean> {
+  const result = await db.kysely
+    .deleteFrom('billing_settings')
+    .where('orgId', '=', orgId)
+    .executeTakeFirst()
+  return result.numDeletedRows > 0n
+}

package/src/db/tables/invitations.ts

@@ -0,0 +1,198 @@
+import 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 Memberships from './memberships.js'
+
+/** Columns of the `invitations` table, derived from `Schema.Invitation`. */
+export type Table = db_Schema.Invitation
+
+/** A stored invitation row. */
+export type Record = Selectable<Table>
+
+/**
+ * Inserts an invitation and returns the stored record. Emails are stored
+ * lowercase so matching against verified emails is case-insensitive. Re-inviting
+ * a live (pending) (org, email) refreshes that row — role, inviter, expiry —
+ * rather than accumulating duplicates, matching the `invitations_pending_unique`
+ * partial index.
+ *
+ * @param db - The database.
+ * @param input - The invitation to insert.
+ * @returns The stored record.
+ */
+export function create(db: Db.Db, input: create.Input): Promise<Record> {
+  const now = new Date().toISOString()
+  return db.kysely
+    .insertInto('invitations')
+    .values({
+      acceptedAt: null,
+      createdAt: now,
+      email: input.email.toLowerCase(),
+      expiresAt: input.expiresAt,
+      id: Id.generate('inv'),
+      invitedBy: input.invitedBy,
+      orgId: input.orgId,
+      revokedAt: null,
+      role: input.role,
+    })
+    .onConflict((oc) =>
+      oc
+        .columns(['orgId', 'email'])
+        .where('acceptedAt', 'is', null)
+        .where('revokedAt', 'is', null)
+        .doUpdateSet({
+          createdAt: now,
+          expiresAt: input.expiresAt,
+          invitedBy: input.invitedBy,
+          role: input.role,
+        }),
+    )
+    .returningAll()
+    .executeTakeFirstOrThrow()
+}
+
+export declare namespace create {
+  /** Fields accepted when inserting an invitation. */
+  type Input = {
+    /** Invitee email. */
+    email: string
+    /** When the invitation expires (ISO 8601). */
+    expiresAt: string
+    /** User id (`usr_…`) creating the invitation. */
+    invitedBy: string
+    /** Organization id (`org_…`) the invitation joins. */
+    orgId: string
+    /** Role granted on accept. */
+    role: Memberships.Role
+  }
+}
+
+/**
+ * Reads an invitation by id.
+ *
+ * @param db - The database.
+ * @param id - The invitation id (`inv_…`).
+ * @returns The record, or `undefined` when absent.
+ */
+export function get(db: Db.Db, id: string): Promise<Record | undefined> {
+  return db.kysely.selectFrom('invitations').selectAll().where('id', '=', id).executeTakeFirst()
+}
+
+/**
+ * Lists an organization's pending invitations (unaccepted, unrevoked,
+ * unexpired), newest first.
+ *
+ * @param db - The database.
+ * @param orgId - The organization id (`org_…`).
+ * @returns The records.
+ */
+export function listByOrg(db: Db.Db, orgId: string): Promise<Record[]> {
+  return pending(db).where('orgId', '=', orgId).orderBy('createdAt', 'desc').execute()
+}
+
+/**
+ * Lists pending invitations addressed to an email, joined with the inviting
+ * organization's name, newest first.
+ *
+ * @param db - The database.
+ * @param email - The invitee email (matched lowercase).
+ * @returns The records with `orgName` from the organization row.
+ */
+export function listByEmail(db: Db.Db, email: string): Promise<(Record & { orgName: string })[]> {
+  return db.kysely
+    .selectFrom('invitations')
+    .innerJoin('organizations', 'organizations.id', 'invitations.orgId')
+    .where('invitations.acceptedAt', 'is', null)
+    .where('invitations.revokedAt', 'is', null)
+    .where('invitations.expiresAt', '>', new Date().toISOString())
+    .where('invitations.email', '=', email.toLowerCase())
+    .selectAll('invitations')
+    .select('organizations.name as orgName')
+    .orderBy('invitations.createdAt', 'desc')
+    .execute()
+}
+
+/**
+ * Revokes a pending invitation.
+ *
+ * @param db - The database.
+ * @param id - The invitation id (`inv_…`).
+ * @returns The revoked record, or `undefined` when absent or already settled.
+ */
+export function revoke(db: Db.Db, id: string): Promise<Record | undefined> {
+  const now = new Date().toISOString()
+  return db.kysely
+    .updateTable('invitations')
+    .set({ revokedAt: now })
+    .where('id', '=', id)
+    .where('acceptedAt', 'is', null)
+    .where('revokedAt', 'is', null)
+    .returningAll()
+    .executeTakeFirst()
+}
+
+/**
+ * Accepts a pending invitation into a membership, atomically: the conditional
+ * update settles the invitation exactly once (double accepts lose the race).
+ * A new member is inserted at the invited role; an existing member is only ever
+ * elevated to it — accepting never demotes (which could strip the last owner).
+ *
+ * @param db - The database.
+ * @param id - The invitation id (`inv_…`).
+ * @param userId - The accepting user id (`usr_…`).
+ * @returns The accepted record, or `undefined` when absent, settled, or expired.
+ */
+export function accept(db: Db.Db, id: string, userId: string): Promise<Record | undefined> {
+  const now = new Date().toISOString()
+  return db.kysely.transaction().execute(async (trx) => {
+    const invitation = await trx
+      .updateTable('invitations')
+      .set({ acceptedAt: now })
+      .where('id', '=', id)
+      .where('acceptedAt', 'is', null)
+      .where('revokedAt', 'is', null)
+      .where('expiresAt', '>', now)
+      .returningAll()
+      .executeTakeFirst()
+    if (!invitation) return undefined
+    const existing = await trx
+      .selectFrom('memberships')
+      .selectAll()
+      .where('orgId', '=', invitation.orgId)
+      .where('userId', '=', userId)
+      .executeTakeFirst()
+    if (!existing)
+      await trx
+        .insertInto('memberships')
+        .values({
+          createdAt: now,
+          orgId: invitation.orgId,
+          role: invitation.role,
+          updatedAt: now,
+          userId,
+        })
+        // A concurrent accept/join could insert first; keep that membership.
+        .onConflict((oc) => oc.columns(['orgId', 'userId']).doNothing())
+        .execute()
+    else if (Memberships.rank[invitation.role] > Memberships.rank[existing.role])
+      await trx
+        .updateTable('memberships')
+        .set({ role: invitation.role, updatedAt: now })
+        .where('orgId', '=', invitation.orgId)
+        .where('userId', '=', userId)
+        .execute()
+    return invitation
+  })
+}
+
+/** Base query selecting pending invitations (unaccepted, unrevoked, unexpired). */
+function pending(db: Db.Db) {
+  return db.kysely
+    .selectFrom('invitations')
+    .selectAll()
+    .where('acceptedAt', 'is', null)
+    .where('revokedAt', 'is', null)
+    .where('expiresAt', '>', new Date().toISOString())
+}

package/src/db/tables/memberships.ts

@@ -0,0 +1,208 @@
+import type { Selectable } from 'kysely'
+
+import type * as Db from '../Db.js'
+import type * as db_Schema from '../Schema.js'
+
+/** Columns of the `memberships` table, derived from `Schema.Membership`. */
+export type Table = db_Schema.Membership
+
+/** A stored membership row. */
+export type Record = Selectable<Table>
+
+/** A membership role. */
+export type Role = Record['role']
+
+/** Fixed membership roles, least to most privileged. */
+export const roles = ['member', 'admin', 'owner'] as const satisfies readonly Role[]
+
+/** Privilege rank per role; higher ranks satisfy lower minimums. */
+export const rank = { admin: 1, member: 0, owner: 2 } as const satisfies { [role in Role]: number }
+
+/**
+ * Inserts a membership and returns the stored record.
+ *
+ * @param db - The database.
+ * @param input - The membership to insert.
+ * @returns The stored record.
+ */
+export function create(db: Db.Db, input: create.Input): Promise<Record> {
+  const now = new Date().toISOString()
+  return db.kysely
+    .insertInto('memberships')
+    .values({
+      createdAt: now,
+      orgId: input.orgId,
+      role: input.role,
+      updatedAt: now,
+      userId: input.userId,
+    })
+    .returningAll()
+    .executeTakeFirstOrThrow()
+}
+
+export declare namespace create {
+  /** Fields accepted when inserting a membership. */
+  type Input = {
+    /** Organization id (`org_…`). */
+    orgId: string
+    /** Granted role. */
+    role: Role
+    /** Member user id (`usr_…`). */
+    userId: string
+  }
+}
+
+/**
+ * Reads one user's membership in an organization.
+ *
+ * @param db - The database.
+ * @param orgId - The organization id (`org_…`).
+ * @param userId - The member user id (`usr_…`).
+ * @returns The record, or `undefined` when absent.
+ */
+export function get(db: Db.Db, orgId: string, userId: string): Promise<Record | undefined> {
+  return db.kysely
+    .selectFrom('memberships')
+    .selectAll()
+    .where('orgId', '=', orgId)
+    .where('userId', '=', userId)
+    .executeTakeFirst()
+}
+
+/**
+ * Lists an organization's memberships, oldest first (stable member ordering).
+ *
+ * @param db - The database.
+ * @param orgId - The organization id (`org_…`).
+ * @returns The records.
+ */
+export function listByOrg(db: Db.Db, orgId: string): Promise<Record[]> {
+  return db.kysely
+    .selectFrom('memberships')
+    .selectAll()
+    .where('orgId', '=', orgId)
+    .orderBy('createdAt', 'asc')
+    .execute()
+}
+
+/**
+ * Lists an organization's memberships joined with member identity (address,
+ * email), oldest first.
+ *
+ * @param db - The database.
+ * @param orgId - The organization id (`org_…`).
+ * @returns The records with `address`/`email` from the member's user row.
+ */
+export function listByOrgDetailed(
+  db: Db.Db,
+  orgId: string,
+): Promise<(Record & { address: string | null; email: string | null })[]> {
+  return db.kysely
+    .selectFrom('memberships')
+    .innerJoin('users', 'users.id', 'memberships.userId')
+    .where('memberships.orgId', '=', orgId)
+    .selectAll('memberships')
+    .select(['users.address', 'users.email'])
+    .orderBy('memberships.createdAt', 'asc')
+    .execute()
+}
+
+/**
+ * Changes a member's role atomically, refusing to demote the last owner. The
+ * org's owner rows are locked for the transaction, so a concurrent demotion or
+ * removal cannot race two guards into leaving the organization ownerless.
+ *
+ * @param db - The database.
+ * @param orgId - The organization id (`org_…`).
+ * @param userId - The member user id (`usr_…`).
+ * @param input - The fields to update.
+ * @returns The updated record, or an `error` when absent or the last owner.
+ */
+export function update(
+  db: Db.Db,
+  orgId: string,
+  userId: string,
+  input: update.Input,
+): Promise<update.Result> {
+  const now = new Date().toISOString()
+  return db.kysely.transaction().execute(async (trx) => {
+    const owners = await trx
+      .selectFrom('memberships')
+      .select('userId')
+      .where('orgId', '=', orgId)
+      .where('role', '=', 'owner')
+      .forUpdate()
+      .execute()
+    const current = await trx
+      .selectFrom('memberships')
+      .selectAll()
+      .where('orgId', '=', orgId)
+      .where('userId', '=', userId)
+      .executeTakeFirst()
+    if (!current) return { error: 'not_found' as const }
+    if (current.role === 'owner' && input.role !== 'owner' && owners.length <= 1)
+      return { error: 'last_owner' as const }
+    const record = await trx
+      .updateTable('memberships')
+      .set({ role: input.role, updatedAt: now })
+      .where('orgId', '=', orgId)
+      .where('userId', '=', userId)
+      .returningAll()
+      .executeTakeFirstOrThrow()
+    return { record }
+  })
+}
+
+export declare namespace update {
+  /** Mutable membership fields. */
+  type Input = {
+    /** New role. */
+    role: Role
+  }
+
+  /** Outcome of a guarded role change. */
+  type Result =
+    | { error: 'last_owner' | 'not_found'; record?: undefined }
+    | { error?: undefined; record: Record }
+}
+
+/**
+ * Deletes a membership atomically, refusing to remove the last owner. Locks
+ * the org's owner rows for the transaction (see {@link update}) so concurrent
+ * removals cannot race the organization ownerless.
+ *
+ * @param db - The database.
+ * @param orgId - The organization id (`org_…`).
+ * @param userId - The member user id (`usr_…`).
+ * @returns `removed` on success, otherwise why the removal was refused.
+ */
+export function remove(db: Db.Db, orgId: string, userId: string): Promise<remove.Result> {
+  return db.kysely.transaction().execute(async (trx) => {
+    const owners = await trx
+      .selectFrom('memberships')
+      .select('userId')
+      .where('orgId', '=', orgId)
+      .where('role', '=', 'owner')
+      .forUpdate()
+      .execute()
+    const current = await trx
+      .selectFrom('memberships')
+      .selectAll()
+      .where('orgId', '=', orgId)
+      .where('userId', '=', userId)
+      .executeTakeFirst()
+    if (!current) return 'not_found'
+    if (current.role === 'owner' && owners.length <= 1) return 'last_owner'
+    await trx
+      .deleteFrom('memberships')
+      .where('orgId', '=', orgId)
+      .where('userId', '=', userId)
+      .execute()
+    return 'removed'
+  })
+}
+
+export declare namespace remove {
+  /** Outcome of a guarded removal. */
+  type Result = 'last_owner' | 'not_found' | 'removed'
+}

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

@@ -1,8 +1,9 @@
 import { nanoid } from 'nanoid'
 
-import { postgresUrl } from '../../../test/containers.js'
+import * as Webhooks from '../../internal/Webhooks.js'
 import * as Db from '../Db.js'
 import * as Organizations from './organizations.js'
+import { postgresUrl } from '../../../test/containers.js'
 
 const create = () => Db.postgres({ connectionString: postgresUrl, schema: `t_${nanoid()}` })
 
@@ -11,7 +12,7 @@ function redact(record: Organizations.Record) {
   return {
     ...record,
     createdAt: '<timestamp>',
-    id: /^org_[\w-]{21}$/.test(record.id) ? 'org_<id>' : record.id,
+    id: /^org_[0-9A-Za-z]{24}$/.test(record.id) ? 'org_<id>' : record.id,
     updatedAt: '<timestamp>',
   }
 }
@@ -29,6 +30,7 @@ describe('create', () => {
         "id": "org_<id>",
         "name": "Acme, Inc.",
         "updatedAt": "<timestamp>",
+        "userId": null,
       }
     `)
     await db.close()
@@ -49,6 +51,7 @@ describe('create', () => {
         "id": "org_explicit",
         "name": "Explicit",
         "updatedAt": "<timestamp>",
+        "userId": null,
       }
     `)
     await db.close()
@@ -122,3 +125,36 @@ describe('upsert', () => {
     await db.close()
   })
 })
+
+describe('deleteOrganization', () => {
+  test('behavior: deletes api-key-owned webhook subscriptions', async () => {
+    const db = create()
+    await db.migrate()
+    await Organizations.create(db, { id: 'org_1', name: 'One' })
+    await Organizations.create(db, { id: 'org_2', name: 'Two' })
+    const deletedOrg = { orgId: 'org_1', type: 'api_key' } as const
+    const keptOrg = { orgId: 'org_2', type: 'api_key' } as const
+    const keptMpp = { payer: 'did:pkh:eip155:1:0xabc', type: 'mpp' } as const
+    await Webhooks.createSubscription(db, subscription(deletedOrg))
+    const keptApiKey = await Webhooks.createSubscription(db, subscription(keptOrg))
+    const keptMppSubscription = await Webhooks.createSubscription(db, subscription(keptMpp))
+
+    expect(await Organizations.deleteOrganization(db, 'org_1')).toBe(true)
+
+    expect(await Webhooks.listSubscriptions(db, deletedOrg)).toEqual([])
+    const active = await Webhooks.listActive(db, 4217, 'token:transfer')
+    expect(active.map(({ id }) => id).sort()).toEqual(
+      [keptApiKey.id, keptMppSubscription.id].sort(),
+    )
+    await db.close()
+  })
+})
+
+function subscription(owner: Webhooks.Owner): Webhooks.CreateInput {
+  return {
+    chainId: 4217,
+    destination: { type: 'url', url: 'https://hooks.example.com/endpoint' },
+    eventType: 'token:transfer',
+    owner,
+  }
+}