tapimo 0.0.2 → 0.2.0

package/src/db/Schema.ts

@@ -0,0 +1,301 @@
+import * as z from 'zod/mini'
+
+import type * as Webhooks from '../internal/Webhooks.js'
+
+// Row schemas for database tables (`zod/mini`), the source of truth each
+// `tables/` module derives its `Table` type from. Nullable fields map to
+// nullable columns; the domain layer converts `null` back to absent fields.
+// 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).')),
+  createdBy: z
+    .nullable(z.string())
+    .check(z.describe('Identity that created the organization (e.g. admin email), or null.')),
+  id: z
+    .string()
+    .check(
+      z.describe('Opaque organization id (`org_…`).'),
+      z.meta({ examples: ['org_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
+    ),
+  name: z
+    .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;
+ * case-insensitive symbol uniqueness is enforced by a functional index on
+ * `lower(symbol)`.
+ */
+export const VerifiedToken = z.object({
+  address: z.string().check(z.describe('Verified TIP-20 token contract address (lowercase).')),
+  chainId: z.number().check(z.int(), z.describe('Chain the token belongs to.')),
+  currency: z.string().check(z.describe('Display currency, e.g. `USD`.')),
+  decimals: z.number().check(z.int(), z.describe('Decimal precision.')),
+  logoUri: z.nullable(z.string()).check(z.describe('Curated HTTPS logo URL, or null.')),
+  name: z.string().check(z.describe('Display name.')),
+  position: z
+    .number()
+    .check(z.int(), z.describe("Zero-based position in the chain's canonical list order.")),
+  symbol: z.string().check(z.describe('Ticker symbol.'), z.meta({ examples: ['USDC'] })),
+})
+
+/** Columns of the `verified_tokens` table. */
+export type VerifiedToken = z.output<typeof VerifiedToken>
+
+/**
+ * A chain's verified-token list metadata — the opaque `version` that drives
+ * the soft-refresh cache and `If-Match` preconditions, bumped on every publish.
+ */
+export const VerifiedTokenList = z.object({
+  chainId: z.number().check(z.int(), z.describe('Chain the list belongs to.')),
+  updatedAt: z.string().check(z.describe('ISO timestamp of the last publish.')),
+  version: z
+    .string()
+    .check(z.describe('Opaque list version (`<epoch-ms>_<hex>`); changes on every publish.')),
+})
+
+/** Columns of the `verified_token_lists` table. */
+export type VerifiedTokenList = z.output<typeof VerifiedTokenList>
+
+/**
+ * A webhook subscription. The `Webhooks.Owner` union maps to (`ownerType`,
+ * `ownerId`); jsonb object columns round-trip as parsed values. `pollerCursor`
+ * replaces the old per-subscription cursor key.
+ */
+export const WebhookSubscription = z.object({
+  chainId: z.number().check(z.int(), z.describe('Chain the subscription listens on.')),
+  context: z
+    .nullable(z.custom<Webhooks.Context>())
+    .check(z.describe('Human context (`jsonb`), or null.')),
+  createdAt: z.string().check(z.describe('ISO timestamp of creation.')),
+  destination: z
+    .custom<Webhooks.Destination>()
+    .check(z.describe('Delivery destination (`jsonb`).')),
+  eventType: z
+    .custom<Webhooks.EventType>()
+    .check(z.describe('Event type the subscription listens to.')),
+  expiresAt: z
+    .nullable(z.string())
+    .check(z.describe('ISO expiry timestamp (MPP-owned subscriptions), or null.')),
+  failureCount: z
+    .number()
+    .check(z.int(), z.describe('Consecutive delivery failures; drives auto-disable.')),
+  filters: z
+    .custom<Webhooks.Subscription['filters']>()
+    .check(z.describe('Event-type-specific filter predicates (`jsonb`).')),
+  id: z
+    .string()
+    .check(
+      z.describe('Subscription id (`wh_…`, lexically time-ordered).'),
+      z.meta({ examples: ['wh_0000019c1a2b3c4d5e6f7g8h'] }),
+    ),
+  lastDeliveryAt: z
+    .nullable(z.string())
+    .check(z.describe('ISO timestamp of the last successful delivery, or null.')),
+  ownerId: z
+    .string()
+    .check(z.describe('Owner identifier: `orgId` for `api_key` owners, `payer` for `mpp`.')),
+  ownerType: z.custom<Webhooks.Owner['type']>().check(z.describe('Owner kind.')),
+  pollerCursor: z
+    .nullable(z.string())
+    .check(z.describe('Poller keyset cursor, or null before the first tick.')),
+  secret: z.string().check(z.describe('HMAC signing secret.')),
+  status: z.custom<Webhooks.Status>().check(z.describe('Lifecycle status.')),
+  updatedAt: z
+    .string()
+    .check(z.describe('ISO timestamp of the last mutation (`pollerCursor` writes excluded).')),
+})
+
+/** Columns of the `webhook_subscriptions` table. */
+export type WebhookSubscription = z.output<typeof WebhookSubscription>
+
+/**
+ * A webhook delivery attempt. Rows are invisible past `expiresAt` (the
+ * retention deadline that replaces the old store TTL) and pruned by the
+ * poller; deleting a subscription cascades to its rows.
+ */
+export const WebhookDelivery = z.object({
+  attempt: z
+    .number()
+    .check(
+      z.int(),
+      z.describe('Consecutive attempt number (1-based) at the time of the delivery.'),
+    ),
+  createdAt: z.string().check(z.describe('ISO timestamp the attempt was recorded.')),
+  envelope: z
+    .custom<Webhooks.Envelope>()
+    .check(z.describe('The exact envelope that was sent (`jsonb`), for verbatim replay.')),
+  error: z
+    .nullable(z.string())
+    .check(z.describe('Failure reason when `status` is `failed`, or null.')),
+  eventId: z.string().check(z.describe('Idempotent event id the delivery carried (`evt_…`).')),
+  expiresAt: z
+    .string()
+    .check(z.describe('ISO retention deadline; rows past it are invisible and pruned.')),
+  id: z
+    .string()
+    .check(
+      z.describe('Delivery id (`whd_…`, lexically time-ordered).'),
+      z.meta({ examples: ['whd_0000019c1a2b3c4d5e6f7g8h'] }),
+    ),
+  requestUrl: z.string().check(z.describe('Subscriber callback URL the attempt targeted.')),
+  responseMs: z
+    .nullable(z.number())
+    .check(z.describe('Wall-clock duration of the attempt in ms, or null.')),
+  responseStatus: z
+    .nullable(z.number())
+    .check(z.describe('HTTP response status, or null when no response was received.')),
+  status: z.custom<Webhooks.DeliveryStatus>().check(z.describe('Outcome status.')),
+  subscriptionId: z
+    .string()
+    .check(z.describe('Owning subscription id (`wh_…`); FK with `ON DELETE CASCADE`.')),
+})
+
+/** Columns of the `webhook_deliveries` table. */
+export type WebhookDelivery = z.output<typeof WebhookDelivery>

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())
+}