tapimo 0.0.2 → 0.2.0

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

@@ -0,0 +1,160 @@
+import { nanoid } from 'nanoid'
+
+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()}` })
+
+/** Redacts nondeterministic row fields (generated nanoid ids, timestamps). */
+function redact(record: Organizations.Record) {
+  return {
+    ...record,
+    createdAt: '<timestamp>',
+    id: /^org_[\w-]{21}$/.test(record.id) ? 'org_<id>' : record.id,
+    updatedAt: '<timestamp>',
+  }
+}
+
+describe('create', () => {
+  test('behavior: inserts with a generated id and defaults', async () => {
+    const db = create()
+    await db.migrate()
+    const record = await Organizations.create(db, { name: 'Acme, Inc.' })
+    expect(record.id).toMatch(/^org_/)
+    expect(redact(record)).toMatchInlineSnapshot(`
+      {
+        "createdAt": "<timestamp>",
+        "createdBy": null,
+        "id": "org_<id>",
+        "name": "Acme, Inc.",
+        "updatedAt": "<timestamp>",
+        "userId": null,
+      }
+    `)
+    await db.close()
+  })
+
+  test('behavior: preserves an explicit id and createdBy', async () => {
+    const db = create()
+    await db.migrate()
+    const record = await Organizations.create(db, {
+      createdBy: 'admin@tempo.xyz',
+      id: 'org_explicit',
+      name: 'Explicit',
+    })
+    expect(redact(record)).toMatchInlineSnapshot(`
+      {
+        "createdAt": "<timestamp>",
+        "createdBy": "admin@tempo.xyz",
+        "id": "org_explicit",
+        "name": "Explicit",
+        "updatedAt": "<timestamp>",
+        "userId": null,
+      }
+    `)
+    await db.close()
+  })
+})
+
+describe('get', () => {
+  test('behavior: returns undefined when absent', async () => {
+    const db = create()
+    await db.migrate()
+    expect(await Organizations.get(db, 'org_missing')).toBeUndefined()
+    await db.close()
+  })
+})
+
+describe('list', () => {
+  test('behavior: lists newest first', async () => {
+    const db = create()
+    await db.migrate()
+    await Organizations.create(db, { id: 'org_a', name: 'A' })
+    // Distinct createdAt for a deterministic order.
+    await new Promise((resolve) => setTimeout(resolve, 5))
+    await Organizations.create(db, { id: 'org_b', name: 'B' })
+    expect((await Organizations.list(db)).map((record) => record.id)).toMatchInlineSnapshot(`
+      [
+        "org_b",
+        "org_a",
+      ]
+    `)
+    await db.close()
+  })
+})
+
+describe('update', () => {
+  test('behavior: renames and bumps updatedAt', async () => {
+    const db = create()
+    await db.migrate()
+    const created = await Organizations.create(db, { id: 'org_1', name: 'Before' })
+    await new Promise((resolve) => setTimeout(resolve, 5))
+    const updated = await Organizations.update(db, 'org_1', { name: 'After' })
+    expect(updated?.name).toMatchInlineSnapshot(`"After"`)
+    expect(updated && updated.updatedAt > created.updatedAt).toBe(true)
+    await db.close()
+  })
+
+  test('behavior: returns undefined when absent', async () => {
+    const db = create()
+    await db.migrate()
+    expect(await Organizations.update(db, 'org_missing', { name: 'X' })).toBeUndefined()
+    await db.close()
+  })
+})
+
+describe('upsert', () => {
+  test('behavior: inserts when absent, defaulting name to the id', async () => {
+    const db = create()
+    await db.migrate()
+    await Organizations.upsert(db, { id: 'key_fallback' })
+    expect((await Organizations.get(db, 'key_fallback'))?.name).toMatchInlineSnapshot(
+      `"key_fallback"`,
+    )
+    await db.close()
+  })
+
+  test('behavior: leaves an existing row untouched', async () => {
+    const db = create()
+    await db.migrate()
+    await Organizations.create(db, { id: 'org_1', name: 'Original' })
+    await Organizations.upsert(db, { id: 'org_1', name: 'Clobbered' })
+    expect((await Organizations.get(db, 'org_1'))?.name).toMatchInlineSnapshot(`"Original"`)
+    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,
+  }
+}

package/src/db/tables/organizations.ts

@@ -0,0 +1,232 @@
+import type { Selectable } from 'kysely'
+import { nanoid } from 'nanoid'
+
+import type * as Db from '../Db.js'
+import type * as db_Schema from '../Schema.js'
+
+/** Columns of the `organizations` table, derived from `Schema.Organization`. */
+export type Table = db_Schema.Organization
+
+/** A stored organization row. */
+export type Record = Selectable<Table>
+
+/**
+ * Inserts an organization and returns the stored record. The `id` defaults to
+ * a generated `org_…` handle when omitted.
+ *
+ * @param db - The database.
+ * @param input - The organization 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('organizations')
+    .values({
+      createdAt: now,
+      createdBy: input.createdBy ?? null,
+      id: input.id ?? `org_${nanoid()}`,
+      name: input.name,
+      updatedAt: now,
+      userId: input.userId ?? null,
+    })
+    .returningAll()
+    .executeTakeFirstOrThrow()
+}
+
+export declare namespace create {
+  /** Fields accepted when inserting an organization. */
+  type Input = {
+    /** Identity creating the organization (e.g. admin email), recorded for audit. */
+    createdBy?: string | undefined
+    /** Explicit id; a generated `org_…` handle is used when omitted. */
+    id?: string | undefined
+    /** Human-readable organization name. */
+    name: string
+    /** Owning user id (`usr_…`); null for organizations created by the super admin. */
+    userId?: string | undefined
+  }
+}
+
+/**
+ * Inserts an organization owned by `userId` — the org row plus its `owner`
+ * membership, atomically.
+ *
+ * @param db - The database.
+ * @param input - The organization to insert.
+ * @returns The stored record.
+ */
+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
+      .insertInto('organizations')
+      .values({
+        createdAt: now,
+        createdBy: input.userId,
+        id: `org_${nanoid()}`,
+        name: input.name,
+        updatedAt: now,
+        userId: input.userId,
+      })
+      .returningAll()
+      .executeTakeFirstOrThrow()
+    await trx
+      .insertInto('memberships')
+      .values({
+        createdAt: now,
+        orgId: record.id,
+        role: 'owner',
+        updatedAt: now,
+        userId: input.userId,
+      })
+      .execute()
+    return record
+  })
+}
+
+export declare namespace createOwned {
+  /** Fields accepted when inserting a user-owned organization. */
+  type Input = {
+    /** Human-readable organization name. */
+    name: string
+    /** Owning user id (`usr_…`), granted the `owner` membership. */
+    userId: string
+  }
+}
+
+/**
+ * Deletes an organization and its owned rows atomically.
+ *
+ * @param db - The database.
+ * @param id - The organization id (`org_…`).
+ * @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) => {
+    await trx
+      .deleteFrom('webhook_subscriptions')
+      .where('ownerType', '=', 'api_key')
+      .where('ownerId', '=', id)
+      .execute()
+    await trx.deleteFrom('invitations').where('orgId', '=', id).execute()
+    await trx.deleteFrom('memberships').where('orgId', '=', id).execute()
+    await trx.deleteFrom('projects').where('orgId', '=', id).execute()
+    const result = await trx.deleteFrom('organizations').where('id', '=', id).executeTakeFirst()
+    return result.numDeletedRows > 0n
+  })
+}
+
+/**
+ * Reads an organization by id.
+ *
+ * @param db - The database.
+ * @param id - The organization id (`org_…`).
+ * @returns The record, or `undefined` when absent.
+ */
+export function get(db: Db.Db, id: string): Promise<Record | undefined> {
+  return db.kysely.selectFrom('organizations').selectAll().where('id', '=', id).executeTakeFirst()
+}
+
+/**
+ * Lists organizations, newest first.
+ *
+ * @param db - The database.
+ * @returns The records.
+ */
+export function list(db: Db.Db): Promise<Record[]> {
+  return db.kysely.selectFrom('organizations').selectAll().orderBy('createdAt', 'desc').execute()
+}
+
+/**
+ * Lists organizations owned by `userId`, newest first.
+ *
+ * @param db - The database.
+ * @param userId - The owning user id (`usr_…`).
+ * @returns The records.
+ */
+export function listByUser(db: Db.Db, userId: string): Promise<Record[]> {
+  return db.kysely
+    .selectFrom('organizations')
+    .selectAll()
+    .where('userId', '=', userId)
+    .orderBy('createdAt', 'desc')
+    .execute()
+}
+
+/**
+ * Lists organizations `userId` is a member of (any role), newest first.
+ *
+ * @param db - The database.
+ * @param userId - The member user id (`usr_…`).
+ * @returns The records.
+ */
+export function listByMember(db: Db.Db, userId: string): Promise<Record[]> {
+  return db.kysely
+    .selectFrom('organizations')
+    .innerJoin('memberships', 'memberships.orgId', 'organizations.id')
+    .where('memberships.userId', '=', userId)
+    .selectAll('organizations')
+    .orderBy('organizations.createdAt', 'desc')
+    .execute()
+}
+
+/**
+ * Renames an organization, bumping `updatedAt`.
+ *
+ * @param db - The database.
+ * @param id - The organization id (`org_…`).
+ * @param input - The fields to update.
+ * @returns The updated record, or `undefined` when absent.
+ */
+export function update(db: Db.Db, id: string, input: update.Input): Promise<Record | undefined> {
+  return db.kysely
+    .updateTable('organizations')
+    .set({ name: input.name, updatedAt: new Date().toISOString() })
+    .where('id', '=', id)
+    .returningAll()
+    .executeTakeFirst()
+}
+
+export declare namespace update {
+  /** Mutable organization fields. */
+  type Input = {
+    /** New human-readable organization name. */
+    name: string
+  }
+}
+
+/**
+ * Inserts an organization when absent (`ON CONFLICT DO NOTHING`) — the
+ * mint/backfill path, where a key's `orgId` must resolve to a real row. The
+ * `name` defaults to the id for degenerate orgs created by the mint fallback.
+ *
+ * @param db - The database.
+ * @param input - The organization to ensure.
+ */
+export async function upsert(db: Db.Db, input: upsert.Input): Promise<void> {
+  const now = new Date().toISOString()
+  await db.kysely
+    .insertInto('organizations')
+    .values({
+      createdAt: now,
+      createdBy: input.createdBy ?? null,
+      id: input.id,
+      name: input.name ?? input.id,
+      updatedAt: now,
+    })
+    .onConflict((oc) => oc.column('id').doNothing())
+    .execute()
+}
+
+export declare namespace upsert {
+  /** Fields accepted when ensuring an organization exists. */
+  type Input = {
+    /** Identity creating the organization, recorded for audit. */
+    createdBy?: string | undefined
+    /** The organization id (`org_…`, or a mint-fallback key id). */
+    id: string
+    /** Human-readable organization name; defaults to the id. */
+    name?: string | undefined
+  }
+}

package/src/db/tables/projects.ts

@@ -0,0 +1,107 @@
+import type { Selectable } from 'kysely'
+import { nanoid } from 'nanoid'
+
+import type * as Db from '../Db.js'
+import type * as db_Schema from '../Schema.js'
+
+/** Columns of the `projects` table, derived from `Schema.Project`. */
+export type Table = db_Schema.Project
+
+/** A stored project row. */
+export type Record = Selectable<Table>
+
+/**
+ * Inserts a project and returns the stored record.
+ *
+ * @param db - The database.
+ * @param input - The project 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('projects')
+    .values({
+      createdAt: now,
+      id: `prj_${nanoid()}`,
+      name: input.name,
+      orgId: input.orgId,
+      updatedAt: now,
+    })
+    .returningAll()
+    .executeTakeFirstOrThrow()
+}
+
+export declare namespace create {
+  /** Fields accepted when inserting a project. */
+  type Input = {
+    /** Human-readable project name. */
+    name: string
+    /** Owning organization id (`org_…`). */
+    orgId: string
+  }
+}
+
+/**
+ * Deletes a project.
+ *
+ * @param db - The database.
+ * @param id - The project id (`prj_…`).
+ * @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
+}
+
+/**
+ * Reads a project by id.
+ *
+ * @param db - The database.
+ * @param id - The project id (`prj_…`).
+ * @returns The record, or `undefined` when absent.
+ */
+export function get(db: Db.Db, id: string): Promise<Record | undefined> {
+  return db.kysely.selectFrom('projects').selectAll().where('id', '=', id).executeTakeFirst()
+}
+
+/**
+ * Lists an organization's projects, newest first.
+ *
+ * @param db - The database.
+ * @param orgId - The owning organization id (`org_…`).
+ * @returns The records.
+ */
+export function listByOrg(db: Db.Db, orgId: string): Promise<Record[]> {
+  return db.kysely
+    .selectFrom('projects')
+    .selectAll()
+    .where('orgId', '=', orgId)
+    .orderBy('createdAt', 'desc')
+    .execute()
+}
+
+/**
+ * Renames a project, bumping `updatedAt`.
+ *
+ * @param db - The database.
+ * @param id - The project id (`prj_…`).
+ * @param input - The fields to update.
+ * @returns The updated record, or `undefined` when absent.
+ */
+export function update(db: Db.Db, id: string, input: update.Input): Promise<Record | undefined> {
+  return db.kysely
+    .updateTable('projects')
+    .set({ name: input.name, updatedAt: new Date().toISOString() })
+    .where('id', '=', id)
+    .returningAll()
+    .executeTakeFirst()
+}
+
+export declare namespace update {
+  /** Mutable project fields. */
+  type Input = {
+    /** New human-readable project name. */
+    name: string
+  }
+}