tapimo 0.1.0 → 0.2.0

package/src/cli/commands/admin.ts

@@ -50,11 +50,11 @@ const migrate = incur_Cli.create('migrate', {
 })
 
 /**
- * Operator commands that run against a deployment's infrastructure rather
+ * Super admin commands that run against a deployment's infrastructure rather
  * than the hosted API (database migrations, …).
  */
 export const admin = incur_Cli
   .create('admin', {
-    description: 'Operator commands for a Tempo API deployment.',
+    description: 'Super admin commands for a Tempo API deployment.',
   })
   .command(migrate)

package/src/db/Db.ts

@@ -5,11 +5,17 @@ import {
   type Dialect,
   Kysely,
   PostgresDialect,
+  type RawBuilder,
   sql,
 } from 'kysely'
 import * as pg from 'pg'
 
+import type * as Invitations from './tables/invitations.js'
+import type * as Memberships from './tables/memberships.js'
 import type * as Organizations from './tables/organizations.js'
+import type * as Projects from './tables/projects.js'
+import type * as SponsoredTransactions from './tables/sponsoredTransactions.js'
+import type * as Users from './tables/users.js'
 import type * as VerifiedTokens from './tables/verifiedTokens.js'
 import type * as WebhookDeliveries from './tables/webhookDeliveries.js'
 import type * as WebhookSubscriptions from './tables/webhookSubscriptions.js'
@@ -26,7 +32,12 @@ export type Database = {
     /** SQL as applied; null on rows written before the column existed. */
     sql: string | null
   }
+  invitations: Invitations.Table
+  memberships: Memberships.Table
   organizations: Organizations.Table
+  projects: Projects.Table
+  sponsored_transactions: SponsoredTransactions.Table
+  users: Users.Table
   verified_token_lists: VerifiedTokens.ListTable
   verified_tokens: VerifiedTokens.Table
   webhook_deliveries: WebhookDeliveries.Table
@@ -235,8 +246,156 @@ export const migrations: readonly Migration[] = [
         .on('webhookDeliveries')
         .column('expiresAt'),
   },
+  {
+    name: '0012_users',
+    up: (db) =>
+      db.schema
+        .createTable('users')
+        .ifNotExists()
+        .addColumn('id', 'text', (c) => c.primaryKey())
+        .addColumn('address', 'text', (c) => c.notNull().unique())
+        .addColumn('email', 'text')
+        .addColumn('createdAt', 'text', (c) => c.notNull())
+        .addColumn('updatedAt', 'text', (c) => c.notNull()),
+  },
+  {
+    name: '0013_organizations_user_id',
+    // The schema builder cannot express `ADD COLUMN IF NOT EXISTS`; raw SQL
+    // (snake_case: the CamelCase plugin does not map raw statements).
+    up: (db) => raw(db, sql`ALTER TABLE organizations ADD COLUMN IF NOT EXISTS user_id text`),
+  },
+  {
+    name: '0014_projects',
+    up: (db) =>
+      db.schema
+        .createTable('projects')
+        .ifNotExists()
+        .addColumn('id', 'text', (c) => c.primaryKey())
+        .addColumn('orgId', 'text', (c) => c.notNull())
+        .addColumn('name', 'text', (c) => c.notNull())
+        .addColumn('createdAt', 'text', (c) => c.notNull())
+        .addColumn('updatedAt', 'text', (c) => c.notNull()),
+  },
+  {
+    name: '0015_projects_org_index',
+    up: (db) =>
+      db.schema.createIndex('projects_org_idx').ifNotExists().on('projects').column('orgId'),
+  },
+  {
+    name: '0016_memberships',
+    up: (db) =>
+      db.schema
+        .createTable('memberships')
+        .ifNotExists()
+        .addColumn('orgId', 'text', (c) => c.notNull())
+        .addColumn('userId', 'text', (c) => c.notNull())
+        .addColumn('role', 'text', (c) => c.notNull())
+        .addColumn('createdAt', 'text', (c) => c.notNull())
+        .addColumn('updatedAt', 'text', (c) => c.notNull())
+        .addPrimaryKeyConstraint('memberships_pk', ['orgId', 'userId']),
+  },
+  {
+    name: '0017_memberships_user_index',
+    up: (db) =>
+      db.schema.createIndex('memberships_user_idx').ifNotExists().on('memberships').column('userId'), // prettier-ignore
+  },
+  {
+    name: '0018_memberships_owner_backfill',
+    // Raw SQL (snake_case: the CamelCase plugin does not map raw statements).
+    up: (db) =>
+      raw(
+        db,
+        sql`INSERT INTO memberships (org_id, user_id, role, created_at, updated_at) SELECT id, user_id, 'owner', created_at, updated_at FROM organizations WHERE user_id IS NOT NULL ON CONFLICT DO NOTHING`,
+      ),
+  },
+  {
+    name: '0019_invitations',
+    up: (db) =>
+      db.schema
+        .createTable('invitations')
+        .ifNotExists()
+        .addColumn('id', 'text', (c) => c.primaryKey())
+        .addColumn('orgId', 'text', (c) => c.notNull())
+        .addColumn('email', 'text', (c) => c.notNull())
+        .addColumn('role', 'text', (c) => c.notNull())
+        .addColumn('invitedBy', 'text', (c) => c.notNull())
+        .addColumn('createdAt', 'text', (c) => c.notNull())
+        .addColumn('expiresAt', 'text', (c) => c.notNull())
+        .addColumn('acceptedAt', 'text')
+        .addColumn('revokedAt', 'text'),
+  },
+  {
+    name: '0020_invitations_org_index',
+    up: (db) =>
+      db.schema.createIndex('invitations_org_idx').ifNotExists().on('invitations').column('orgId'),
+  },
+  {
+    name: '0021_invitations_email_index',
+    up: (db) =>
+      db.schema.createIndex('invitations_email_idx').ifNotExists().on('invitations').column('email'), // prettier-ignore
+  },
+  {
+    name: '0022_users_address_nullable',
+    // Raw SQL; a no-op when the column is already nullable.
+    up: (db) => raw(db, sql`ALTER TABLE users ALTER COLUMN address DROP NOT NULL`),
+  },
+  {
+    name: '0023_invitations_pending_unique',
+    // Raw SQL: a partial unique index (snake_case; the CamelCase plugin does
+    // not map raw statements). At most one live (unaccepted, unrevoked)
+    // invitation per (org, email); a re-invite upserts the existing row.
+    up: (db) =>
+      raw(
+        db,
+        sql`CREATE UNIQUE INDEX IF NOT EXISTS invitations_pending_unique ON invitations (org_id, email) WHERE accepted_at IS NULL AND revoked_at IS NULL`,
+      ),
+  },
+  {
+    name: '0024_sponsored_transactions',
+    up: (db) =>
+      db.schema
+        .createTable('sponsoredTransactions')
+        .ifNotExists()
+        .addColumn('id', 'text', (c) => c.primaryKey())
+        .addColumn('orgId', 'text', (c) => c.notNull())
+        .addColumn('projectId', 'text', (c) => c.notNull())
+        .addColumn('apiKeyId', 'text', (c) => c.notNull())
+        .addColumn('environment', 'text', (c) => c.notNull())
+        .addColumn('chainId', 'integer', (c) => c.notNull())
+        .addColumn('transactionHash', 'text')
+        .addColumn('signPayload', 'text', (c) => c.notNull())
+        .addColumn('transaction', 'text', (c) => c.notNull())
+        .addColumn('status', 'text', (c) => c.notNull())
+        .addColumn('feeAmount', 'text')
+        .addColumn('feeToken', 'text')
+        .addColumn('billable', 'boolean', (c) => c.notNull())
+        .addColumn('createdAt', 'text', (c) => c.notNull())
+        .addColumn('finalizedAt', 'text')
+        .addUniqueConstraint('sponsored_transactions_sign_payload_key', ['signPayload']),
+  },
+  {
+    name: '0025_sponsored_transactions_status_index',
+    up: (db) =>
+      db.schema.createIndex('sponsored_transactions_status_idx').ifNotExists().on('sponsoredTransactions').columns(['status', 'createdAt']), // prettier-ignore
+  },
+  {
+    name: '0026_sponsored_transactions_org_index',
+    up: (db) =>
+      db.schema.createIndex('sponsored_transactions_org_idx').ifNotExists().on('sponsoredTransactions').columns(['orgId', 'createdAt']), // prettier-ignore
+  },
 ]
 
+/**
+ * Adapts a raw statement to the migration contract (argument-less
+ * `compile`/`execute`) for DDL the schema builders cannot express.
+ */
+function raw(db: Kysely<Database>, statement: RawBuilder<unknown>) {
+  return {
+    compile: () => statement.compile(db),
+    execute: () => statement.execute(db),
+  }
+}
+
 /**
  * Builds a {@link Db} for any Kysely {@link Dialect}. All backends share
  * migrations, repositories, and the required {@link CamelCasePlugin} mapping.

package/src/db/Schema.ts

@@ -8,6 +8,49 @@ import type * as Webhooks from '../internal/Webhooks.js'
 // Domain-owned unions and jsonb values stay typed by their owning module via
 // `z.custom` (type-only imports) so the two cannot drift.
 
+/** A pending, expiring offer of organization membership. */
+export const Invitation = z.object({
+  acceptedAt: z
+    .nullable(z.string())
+    .check(z.describe('When the invitation was accepted (ISO 8601), or null while pending.')),
+  createdAt: z.string().check(z.describe('When the invitation was created (ISO 8601).')),
+  email: z
+    .string()
+    .check(z.describe('Invitee email (stored lowercase); matched against verified emails.')),
+  expiresAt: z.string().check(z.describe('When the invitation expires (ISO 8601).')),
+  id: z
+    .string()
+    .check(
+      z.describe('Opaque invitation id (`inv_…`).'),
+      z.meta({ examples: ['inv_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
+    ),
+  invitedBy: z.string().check(z.describe('User id (`usr_…`) that created the invitation.')),
+  orgId: z.string().check(z.describe('Organization id (`org_…`) the invitation joins.')),
+  revokedAt: z
+    .nullable(z.string())
+    .check(z.describe('When the invitation was revoked (ISO 8601), or null.')),
+  role: z
+    .enum(['admin', 'member', 'owner'])
+    .check(z.describe('Role granted when the invitation is accepted.')),
+})
+
+/** Columns of the `invitations` table. */
+export type Invitation = z.output<typeof Invitation>
+
+/** A user's role within an organization. */
+export const Membership = z.object({
+  createdAt: z.string().check(z.describe('When the membership was created (ISO 8601).')),
+  orgId: z.string().check(z.describe('Organization id (`org_…`).')),
+  role: z
+    .enum(['admin', 'member', 'owner'])
+    .check(z.describe("The member's role within the organization.")),
+  updatedAt: z.string().check(z.describe('When the membership was last updated (ISO 8601).')),
+  userId: z.string().check(z.describe('Member user id (`usr_…`).')),
+})
+
+/** Columns of the `memberships` table. */
+export type Membership = z.output<typeof Membership>
+
 /** An organization, the top-level tenant that owns API keys. */
 export const Organization = z.object({
   createdAt: z.string().check(z.describe('When the organization was created (ISO 8601).')),
@@ -24,11 +67,105 @@ export const Organization = z.object({
     .string()
     .check(z.describe('Human-readable organization name.'), z.meta({ examples: ['Acme, Inc.'] })),
   updatedAt: z.string().check(z.describe('When the organization was last updated (ISO 8601).')),
+  userId: z
+    .nullable(z.string())
+    .check(
+      z.describe('Owning user id (`usr_…`), or null for organizations created by the super admin.'),
+    ),
 })
 
 /** Columns of the `organizations` table. */
 export type Organization = z.output<typeof Organization>
 
+/** A project: an app or integration within an organization. */
+export const Project = z.object({
+  createdAt: z.string().check(z.describe('When the project was created (ISO 8601).')),
+  id: z
+    .string()
+    .check(
+      z.describe('Opaque project id (`prj_…`).'),
+      z.meta({ examples: ['prj_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
+    ),
+  name: z
+    .string()
+    .check(z.describe('Human-readable project name.'), z.meta({ examples: ['Checkout'] })),
+  orgId: z.string().check(z.describe('Owning organization id (`org_…`).')),
+  updatedAt: z.string().check(z.describe('When the project was last updated (ISO 8601).')),
+})
+
+/** Columns of the `projects` table. */
+export type Project = z.output<typeof Project>
+
+/** A transaction sponsored by the managed fee payer — the billable unit of fee payer spend. */
+export const SponsoredTransaction = z.object({
+  apiKeyId: z.string().check(z.describe('API key id (`key_…`) that requested sponsorship.')),
+  billable: z
+    .boolean()
+    .check(z.describe('Whether the sponsorship accrues billable spend; false for sandbox.')),
+  chainId: z.number().check(z.describe('Chain the sponsored transaction targets.')),
+  createdAt: z.string().check(z.describe('When the sponsorship was recorded (ISO 8601).')),
+  environment: z
+    .enum(['production', 'sandbox'])
+    .check(z.describe('Key environment the sponsorship was requested under.')),
+  feeAmount: z
+    .nullable(z.string())
+    .check(z.describe('Actual fee paid in fee-token base units, or null until finalized.')),
+  feeToken: z
+    .nullable(z.string())
+    .check(z.describe('Fee token address, or null when the chain default applied.')),
+  finalizedAt: z
+    .nullable(z.string())
+    .check(z.describe('When the sponsorship reached a terminal status (ISO 8601), or null.')),
+  id: z
+    .string()
+    .check(
+      z.describe('Opaque sponsored-transaction id (`stx_…`).'),
+      z.meta({ examples: ['stx_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
+    ),
+  orgId: z.string().check(z.describe('Organization id (`org_…`) the spend attributes to.')),
+  projectId: z.string().check(z.describe('Project id (`prj_…`) the spend attributes to.')),
+  signPayload: z
+    .string()
+    .check(z.describe('Fee-payer sign payload — a stable identity for the sponsored envelope.')),
+  status: z
+    .enum(['failed', 'finalized', 'pending'])
+    .check(z.describe('Pending until a receipt finalizes it or the pending TTL fails it.')),
+  transaction: z
+    .string()
+    .check(z.describe('Serialized sponsored transaction, kept for durable observability.')),
+  transactionHash: z
+    .nullable(z.string())
+    .check(z.describe('Transaction hash, or null for fill intents until reconciled.')),
+})
+
+/** Columns of the `sponsored_transactions` table. */
+export type SponsoredTransaction = z.output<typeof SponsoredTransaction>
+
+/** A developer identity. */
+export const User = z.object({
+  address: z
+    .nullable(z.string())
+    .check(
+      z.describe(
+        'Wallet address that signs in as this user (stored lowercase), or null for non-wallet identities.',
+      ),
+    ),
+  createdAt: z.string().check(z.describe('When the user was created (ISO 8601).')),
+  email: z
+    .nullable(z.string())
+    .check(z.describe('Verified email from the wallet identity token, or null.')),
+  id: z
+    .string()
+    .check(
+      z.describe('Opaque user id (`usr_…`).'),
+      z.meta({ examples: ['usr_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
+    ),
+  updatedAt: z.string().check(z.describe('When the user was last updated (ISO 8601).')),
+})
+
+/** Columns of the `users` table. */
+export type User = z.output<typeof User>
+
 /**
  * A verified token: one row per curated token, ordered by `position` (list
  * order is canonical and surfaced to clients). Addresses are stored lowercase;

package/src/db/tables/invitations.ts

@@ -0,0 +1,198 @@
+import type { Selectable } from 'kysely'
+import { nanoid } from 'nanoid'
+
+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: `inv_${nanoid()}`,
+      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())
+}