tapimo 0.4.0 → 0.4.3

package/src/apps/relay/App.test.ts

@@ -29,14 +29,14 @@ const senderAccount = Tempo.accounts[9]!
 /** Super admin secret configured on the end-to-end billing app. */
 const superAdminSecret = 'tempo:sk:a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1'
 
-/** Keys covering the sponsorship policy matrix; all hold the base relay scope. */
+/** Keys covering the sponsorship policy matrix. */
 const keys = [
   {
     id: 'key_sponsor',
     orgId: 'org_1',
     projectId: 'prj_1',
     environment: 'sandbox',
-    scopes: ['rpc-relay:read', 'rpc-relay:sponsor'],
+    scopes: ['rpc-relay:sponsor'],
     token: 'secret_sponsor',
   },
   {
@@ -44,7 +44,7 @@ const keys = [
     orgId: 'org_1',
     projectId: 'prj_1',
     environment: 'production',
-    scopes: ['rpc-relay:read', 'rpc-relay:sponsor'],
+    scopes: ['rpc-relay:sponsor'],
     token: 'secret_sponsor_prod',
   },
   {
@@ -75,7 +75,7 @@ const keys = [
     id: 'key_unattributed',
     orgId: 'org_1',
     environment: 'sandbox',
-    scopes: ['rpc-relay:read', 'rpc-relay:sponsor'],
+    scopes: ['rpc-relay:sponsor'],
     token: 'secret_unattributed',
   },
 ] as const satisfies readonly TestApp.kvStore.Key[]
@@ -169,7 +169,7 @@ describe.skipIf(runtime.mode !== 'localnet')('behavior: sponsorship', () => {
     expect(row?.orgId).toMatchInlineSnapshot(`"org_2"`)
   })
 
-  test('behavior: keys without the sponsor scope are refused', async () => {
+  test('behavior: read-only keys cannot access the sponsor route', async () => {
     const db = TestApp.database()
     const app = TestApp.create({
       auth: { keys },
@@ -177,14 +177,15 @@ describe.skipIf(runtime.mode !== 'localnet')('behavior: sponsorship', () => {
       relay: { feePayer: { account: feePayerAccount } },
     })
 
-    const body = await relayRequest(app, {
-      method: 'eth_signRawTransaction',
-      params: [await signSponsorable()],
-      token: 'secret_unscoped',
-    })
-    // "Sponsorship rejected." surfaces as invalid params (-32602).
-    expect(body.result).toBeUndefined()
-    expect(body.error?.code).toBe(-32602)
+    const response = await app.fetch(
+      new Request('http://tempo-api.test/rpc/sponsor', {
+        body: JSON.stringify({ id: 1, jsonrpc: '2.0', method: 'eth_chainId' }),
+        headers: { 'content-type': 'application/json', 'tempo-api-key': 'secret_unscoped' },
+        method: 'POST',
+      }),
+    )
+    expect(response.status).toBe(403)
+    expect(await response.json()).toMatchObject({ error: { code: 'api_key_forbidden' } })
     expect(await SponsoredTransactions.listPending(db)).toHaveLength(0)
   })
 
@@ -288,12 +289,16 @@ describe.skipIf(runtime.mode !== 'localnet')('behavior: sponsorship', () => {
           nonce: '0x0',
         },
       ],
-      token: 'secret_unscoped',
+      token: 'secret_sponsor',
     })
     const result = body.result as unknown as
-      | { capabilities?: { sponsored?: boolean }; tx?: { feePayerSignature?: string | null } }
+      | {
+          capabilities?: { balanceDiffs?: unknown; sponsored?: boolean }
+          tx?: { feePayerSignature?: string | null }
+        }
       | undefined
     expect(result?.tx?.feePayerSignature ?? null).toBeNull()
+    expect(result?.capabilities?.balanceDiffs).toBeUndefined()
     expect(result?.capabilities?.sponsored).toBe(false)
     expect(await SponsoredTransactions.listPending(db)).toHaveLength(0)
   })
@@ -629,7 +634,7 @@ describe.skipIf(runtime.mode !== 'localnet')('behavior: sponsorship (viem)', ()
       chain: Tempo.chain,
       transport: withRelay(
         Relay.http(),
-        http(`${server.url}/rpc/relay`, {
+        http(`${server.url}/rpc/sponsor`, {
           fetchOptions: { headers: { 'tempo-api-key': 'secret_sponsor' } },
         }),
         policy ? { policy } : {},
@@ -785,13 +790,13 @@ async function signSponsorable(
   })
 }
 
-/** Posts one JSON-RPC request to the composed app's relay mount. */
+/** Posts one JSON-RPC request to the composed app's sponsor mount. */
 async function relayRequest(
   app: ReturnType<typeof TestApp.create>,
   options: { method: string; params: readonly unknown[]; token?: string | undefined },
 ) {
   const response = await app.fetch(
-    new Request('http://tempo-api.test/rpc/relay', {
+    new Request('http://tempo-api.test/rpc/sponsor', {
       body: JSON.stringify({ id: 1, jsonrpc: '2.0', method: options.method, params: options.params }), // prettier-ignore
       headers: {
         'content-type': 'application/json',

package/src/apps/relay/App.ts

@@ -18,16 +18,17 @@ import * as Viem from '../../internal/Viem.js'
 import * as Scope from '../../Scope.js'
 
 /**
- * The relay route group: the wallet relay at `/rpc/relay`. Mount
- * after `data()`, whose published chain clients and supported-chain set the
- * middleware reads from request context.
+ * The relay route group exposes wallet features at `/rpc/relay` and fee
+ * sponsorship at `/rpc/sponsor`. Mount it after `data()`, which publishes
+ * chain clients and supported chains.
  *
  * ```ts
  * App.create(options).route('/', data()).route('/', relay())
  * ```
  */
 export function relay(options: relay.Options = {}) {
-  const handler = middleware(options)
+  const handler_relay = middleware({ ...options, features: 'all', path: 'rpc/relay' })
+  const handler_sponsor = middleware({ ...options, path: 'rpc/sponsor' })
   return new Hono<App.Environment>()
     .use(
       '/rpc/relay',
@@ -39,8 +40,20 @@ export function relay(options: relay.Options = {}) {
       Auth.policy({ apiKey: { scopes: ['rpc-relay:read'] }, mpp: false, public: false }),
       OpenApi.describeRoute({ hide: true, summary: 'Relay RPC' }),
     )
-    .all('/rpc/relay', handler)
-    .all('/rpc/relay/:chainId', handler)
+    .all('/rpc/relay', handler_relay)
+    .all('/rpc/relay/:chainId', handler_relay)
+    .use(
+      '/rpc/sponsor',
+      Auth.policy({ apiKey: { scopes: ['rpc-relay:sponsor'] }, mpp: false, public: false }),
+      OpenApi.describeRoute({ hide: true, summary: 'Sponsor RPC' }),
+    )
+    .use(
+      '/rpc/sponsor/*',
+      Auth.policy({ apiKey: { scopes: ['rpc-relay:sponsor'] }, mpp: false, public: false }),
+      OpenApi.describeRoute({ hide: true, summary: 'Sponsor RPC' }),
+    )
+    .all('/rpc/sponsor', handler_sponsor)
+    .all('/rpc/sponsor/:chainId', handler_sponsor)
 }
 
 export declare namespace relay {
@@ -58,11 +71,9 @@ export declare namespace relay {
   }
 }
 
-// The wallet relay middleware: proxies wallet JSON-RPC (fills, sponsored
-// sends) with wallet-aware enrichment. Built per request from context rather
-// than closed over group locals; relay traffic is low-QPS and the viem
-// clients are memoized upstream, so per-request handler construction is cheap.
-function middleware(options: relay.Options = {}) {
+// Builds request-aware RPC middleware. Viem clients are memoized upstream, so
+// constructing `Handler.relay` per request stays cheap.
+function middleware(options: middleware.Options) {
   // Platform-wide per-transaction cap; org settings tighten it, never loosen.
   const txFeeLimit = options.feePayer
     ? Billing.toBaseUnits(options.feePayer.txFeeLimit ?? '1.00')
@@ -215,12 +226,12 @@ function middleware(options: relay.Options = {}) {
 
     // Dispatching a standalone Hono via `fetch(c.req.raw)` bypasses Hono's
     // mount-path stripping, so its internal routes register at the request's
-    // full external path (`basePath` + `/rpc/relay`).
+    // full external path (`basePath` + the RPC mount).
     const handler = Handler.relay({
       cache: c.get('store'),
-      features: 'all',
+      ...(options.features ? { features: options.features } : {}),
       getClient: (chainId) => c.get('getClient')(chainId as Viem.ChainId | undefined),
-      path: Path.join(c.get('basePath'), 'rpc/relay'),
+      path: Path.join(c.get('basePath'), options.path),
       ...(feePayer ? { feePayer } : {}),
       ...(verifiedTokens
         ? {
@@ -234,3 +245,13 @@ function middleware(options: relay.Options = {}) {
     return handler.fetch(c.req.raw)
   })
 }
+
+declare namespace middleware {
+  /** Internal relay mount configuration. */
+  type Options = relay.Options & {
+    /** Optional wallet feature bundle. */
+    features?: Handler.relay.Options['features']
+    /** RPC mount path. */
+    path: 'rpc/relay' | 'rpc/sponsor'
+  }
+}

package/src/db/Db.ts

@@ -10,6 +10,7 @@ import {
 } from 'kysely'
 import * as pg from 'pg'
 
+import type * as AdminAuditLogs from './tables/adminAuditLogs.js'
 import type * as BillingSettings from './tables/billingSettings.js'
 import type * as Invitations from './tables/invitations.js'
 import type * as Memberships from './tables/memberships.js'
@@ -28,6 +29,10 @@ import type * as WebhookSubscriptions from './tables/webhookSubscriptions.js'
  * records, queries, and {@link migrations} DDL to snake_case storage columns.
  */
 export type Database = {
+  admin_audit_logs: AdminAuditLogs.Table
+  billing_settings: BillingSettings.Table
+  invitations: Invitations.Table
+  memberships: Memberships.Table
   migrations: {
     appliedAt: string
     checksum: string
@@ -35,9 +40,6 @@ export type Database = {
     /** SQL as applied; null on rows written before the column existed. */
     sql: string | null
   }
-  billing_settings: BillingSettings.Table
-  invitations: Invitations.Table
-  memberships: Memberships.Table
   organizations: Organizations.Table
   projects: Projects.Table
   request_usage_buckets: RequestUsage.BucketTable
@@ -520,6 +522,60 @@ export const migrations: readonly Migration[] = [
     // Partial: the reporter scans only unreported (pending) rows.
     up: (db) => raw(db, sql`CREATE INDEX IF NOT EXISTS request_usage_meter_events_pending_idx ON request_usage_meter_events (first_attempted_at, identifier) WHERE state = 'pending'`), // prettier-ignore
   },
+  {
+    // Supports the admin organization's newest-first keyset pagination.
+    name: '0045_organizations_admin_list_index',
+    up: (db) => raw(db, sql`CREATE INDEX IF NOT EXISTS organizations_admin_list_idx ON organizations (created_at DESC, id DESC)`), // prettier-ignore
+  },
+  {
+    // Prefix search keeps organization-name lookup index-backed.
+    name: '0046_organizations_name_prefix_index',
+    up: (db) => raw(db, sql`CREATE INDEX IF NOT EXISTS organizations_name_prefix_idx ON organizations (lower(name) text_pattern_ops)`), // prettier-ignore
+  },
+  {
+    // Prefix search keeps member-email lookup index-backed.
+    name: '0047_users_email_prefix_index',
+    up: (db) => raw(db, sql`CREATE INDEX IF NOT EXISTS users_email_prefix_idx ON users (lower(email) text_pattern_ops) WHERE email IS NOT NULL`), // prettier-ignore
+  },
+  {
+    // Exact owner lookup for organizations created by a user.
+    name: '0048_organizations_user_index',
+    up: (db) => raw(db, sql`CREATE INDEX IF NOT EXISTS organizations_user_idx ON organizations (user_id) WHERE user_id IS NOT NULL`), // prettier-ignore
+  },
+  {
+    // Supports oldest-first admin membership keyset pagination.
+    name: '0049_memberships_admin_list_index',
+    up: (db) => raw(db, sql`CREATE INDEX IF NOT EXISTS memberships_admin_list_idx ON memberships (org_id, created_at, user_id)`), // prettier-ignore
+  },
+  {
+    // Supports newest-first admin project keyset pagination.
+    name: '0050_projects_admin_list_index',
+    up: (db) => raw(db, sql`CREATE INDEX IF NOT EXISTS projects_admin_list_idx ON projects (org_id, created_at DESC, id DESC)`), // prettier-ignore
+  },
+  {
+    name: '0051_admin_audit_logs',
+    up: (db) =>
+      db.schema
+        .createTable('adminAuditLogs')
+        .ifNotExists()
+        .addColumn('id', 'text', (c) => c.primaryKey())
+        .addColumn('actor', 'text', (c) => c.notNull())
+        .addColumn('method', 'text', (c) => c.notNull())
+        .addColumn('path', 'text', (c) => c.notNull())
+        .addColumn('query', 'text')
+        .addColumn('requestId', 'text', (c) => c.notNull())
+        .addColumn('status', 'integer', (c) => c.notNull())
+        .addColumn('createdAt', 'text', (c) => c.notNull()),
+  },
+  {
+    name: '0052_admin_audit_logs_created_index',
+    up: (db) =>
+      db.schema
+        .createIndex('admin_audit_logs_created_idx')
+        .ifNotExists()
+        .on('adminAuditLogs')
+        .columns(['createdAt', 'id']),
+  },
 ]
 
 /**

package/src/db/Schema.ts

@@ -2,6 +2,25 @@ import * as z from 'zod/mini'
 
 import type * as Webhooks from '../internal/Webhooks.js'
 
+/** One authenticated administrator access to a protected admin API route. */
+export const AdminAuditLog = z.object({
+  actor: z.string().check(z.describe('Verified administrator email.')),
+  createdAt: z.string().check(z.describe('When the access completed (ISO 8601).')),
+  id: z.string().check(z.describe('Opaque audit event id (`aud_…`).')),
+  method: z.string().check(z.describe('HTTP method used for the access.')),
+  path: z.string().check(z.describe('Admin API path accessed, without query parameters.')),
+  query: z
+    .nullable(z.string())
+    .check(z.describe('Query string used for the lookup, or null when absent.')),
+  requestId: z.string().check(z.describe('Request id correlating the access with request logs.')),
+  status: z
+    .number()
+    .check(z.int(), z.describe('HTTP response status returned to the administrator.')),
+})
+
+/** Columns of the `admin_audit_logs` table. */
+export type AdminAuditLog = z.output<typeof AdminAuditLog>
+
 // 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.
@@ -49,7 +68,7 @@ export const Invitation = z.object({
       z.describe('Opaque invitation id (`inv_…`).'),
       z.meta({ examples: ['inv_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
     ),
-  invitedBy: z.string().check(z.describe('User id (`usr_…`) that created the invitation.')),
+  invitedBy: z.string().check(z.describe('User or API key id that created the invitation.')),
   orgId: z.string().check(z.describe('Organization id (`org_…`) the invitation joins.')),
   revokedAt: z
     .nullable(z.string())

package/src/db/tables/adminAuditLogs.ts

@@ -0,0 +1,47 @@
+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'
+
+/** Columns of the `admin_audit_logs` table. */
+export type Table = db_Schema.AdminAuditLog
+
+/** One stored administrator access event. */
+export type Record = Selectable<Table>
+
+/** Records an authenticated access to a protected admin API route. */
+export function insert(db: Db.Db, input: insert.Input): Promise<Record> {
+  return db.kysely
+    .insertInto('admin_audit_logs')
+    .values({
+      actor: input.actor,
+      createdAt: new Date().toISOString(),
+      id: Id.generate('aud'),
+      method: input.method,
+      path: input.path,
+      query: input.query ?? null,
+      requestId: input.requestId,
+      status: input.status,
+    })
+    .returningAll()
+    .executeTakeFirstOrThrow()
+}
+
+export declare namespace insert {
+  /** Fields captured for one administrator access. */
+  type Input = {
+    /** Verified administrator email. */
+    actor: string
+    /** HTTP method used for the access. */
+    method: string
+    /** Admin API path accessed, without query parameters. */
+    path: string
+    /** Query string used for the lookup. */
+    query?: string | undefined
+    /** Request id correlating the access with request logs. */
+    requestId: string
+    /** HTTP response status returned to the administrator. */
+    status: number
+  }
+}

package/src/db/tables/invitations.ts

@@ -60,7 +60,7 @@ export declare namespace create {
     email: string
     /** When the invitation expires (ISO 8601). */
     expiresAt: string
-    /** User id (`usr_…`) creating the invitation. */
+    /** User or API key id creating the invitation. */
     invitedBy: string
     /** Organization id (`org_…`) the invitation joins. */
     orgId: string

package/src/db/tables/memberships.ts

@@ -9,6 +9,9 @@ export type Table = db_Schema.Membership
 /** A stored membership row. */
 export type Record = Selectable<Table>
 
+/** A membership with the member's resolved user identity. */
+export type DetailedRecord = Record & { address: string | null; email: string | null }
+
 /** A membership role. */
 export type Role = Record['role']
 
@@ -93,20 +96,73 @@ export function listByOrg(db: Db.Db, orgId: string): Promise<Record[]> {
  * @param orgId - The organization id (`org_…`).
  * @returns The records with `address`/`email` from the member's user row.
  */
-export function listByOrgDetailed(
+export function listByOrgDetailed(db: Db.Db, orgId: string): Promise<DetailedRecord[]> {
+  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()
+}
+
+/**
+ * Lists a bounded page of an organization's memberships with member identity,
+ * oldest first.
+ *
+ * @param db - The database.
+ * @param orgId - The organization id.
+ * @param options - Keyset and page-size options.
+ * @returns At most `limit + 1` rows for next-cursor derivation.
+ */
+export function listByOrgDetailedPage(
   db: Db.Db,
   orgId: string,
-): Promise<(Record & { address: string | null; email: string | null })[]> {
-  return db.kysely
+  options: listByOrgDetailedPage.Options,
+): Promise<DetailedRecord[]> {
+  const cursor = options.cursor
+  let query = db.kysely
     .selectFrom('memberships')
     .innerJoin('users', 'users.id', 'memberships.userId')
     .where('memberships.orgId', '=', orgId)
     .selectAll('memberships')
     .select(['users.address', 'users.email'])
+  if (cursor)
+    query = query.where((eb) =>
+      eb.or([
+        eb('memberships.createdAt', '>', cursor.createdAt),
+        eb.and([
+          eb('memberships.createdAt', '=', cursor.createdAt),
+          eb('memberships.userId', '>', cursor.userId),
+        ]),
+      ]),
+    )
+  return query
     .orderBy('memberships.createdAt', 'asc')
+    .orderBy('memberships.userId', 'asc')
+    .limit(options.limit + 1)
     .execute()
 }
 
+export declare namespace listByOrgDetailedPage {
+  /** Cursor fields for the last membership on the previous page. */
+  type Cursor = {
+    /** Membership creation time. */
+    createdAt: string
+    /** Member user id, used as a deterministic tie-breaker. */
+    userId: string
+  }
+
+  /** Options for {@link listByOrgDetailedPage}. */
+  type Options = {
+    /** Last membership returned by the previous page. */
+    cursor?: Cursor | undefined
+    /** Requested page size. */
+    limit: number
+  }
+}
+
 /**
  * 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

package/src/db/tables/organizations.ts

@@ -1,4 +1,4 @@
-import type { Selectable } from 'kysely'
+import { sql, type Selectable } from 'kysely'
 
 import * as Id from '../../internal/Id.js'
 import type * as Db from '../Db.js'
@@ -133,6 +133,39 @@ export function get(db: Db.Db, id: string): Promise<Record | undefined> {
   return db.kysely.selectFrom('organizations').selectAll().where('id', '=', id).executeTakeFirst()
 }
 
+/**
+ * Reads an organization with current member and project counts.
+ *
+ * @param db - The database.
+ * @param id - The organization id.
+ * @returns The organization summary, or `undefined` when absent.
+ */
+export async function getSummary(db: Db.Db, id: string): Promise<search.Result | undefined> {
+  const record = await db.kysely
+    .selectFrom('organizations')
+    .selectAll('organizations')
+    .select((eb) => [
+      eb
+        .selectFrom('memberships')
+        .select((builder) => builder.fn.countAll<number>().as('count'))
+        .whereRef('memberships.orgId', '=', 'organizations.id')
+        .as('memberCount'),
+      eb
+        .selectFrom('projects')
+        .select((builder) => builder.fn.countAll<number>().as('count'))
+        .whereRef('projects.orgId', '=', 'organizations.id')
+        .as('projectCount'),
+    ])
+    .where('organizations.id', '=', id)
+    .executeTakeFirst()
+  if (!record) return undefined
+  return {
+    ...record,
+    memberCount: Number(record.memberCount),
+    projectCount: Number(record.projectCount),
+  }
+}
+
 /**
  * Lists organizations, newest first.
  *
@@ -143,6 +176,120 @@ export function list(db: Db.Db): Promise<Record[]> {
   return db.kysely.selectFrom('organizations').selectAll().orderBy('createdAt', 'desc').execute()
 }
 
+/**
+ * Searches organizations for the admin lookup surface, newest first. Results
+ * include member and project counts and use a stable `(createdAt, id)` keyset.
+ *
+ * @param db - The database.
+ * @param options - Search, keyset, and page-size options.
+ * @returns At most `limit + 1` rows so the caller can derive a next cursor.
+ */
+export async function search(db: Db.Db, options: search.Options): Promise<search.Result[]> {
+  const { cursor, limit, query: searchQuery } = options
+  let query = db.kysely
+    .selectFrom('organizations')
+    .selectAll('organizations')
+    .select((eb) => [
+      eb
+        .selectFrom('memberships')
+        .select((builder) => builder.fn.countAll<number>().as('count'))
+        .whereRef('memberships.orgId', '=', 'organizations.id')
+        .as('memberCount'),
+      eb
+        .selectFrom('projects')
+        .select((builder) => builder.fn.countAll<number>().as('count'))
+        .whereRef('projects.orgId', '=', 'organizations.id')
+        .as('projectCount'),
+    ])
+
+  if (searchQuery?.startsWith('org_')) query = query.where('organizations.id', '=', searchQuery)
+  else if (searchQuery?.startsWith('usr_'))
+    query = query.where((eb) =>
+      eb.or([
+        eb('organizations.userId', '=', searchQuery),
+        eb(
+          'organizations.id',
+          'in',
+          eb
+            .selectFrom('memberships')
+            .select('memberships.orgId')
+            .where('memberships.userId', '=', searchQuery),
+        ),
+      ]),
+    )
+  else if (searchQuery) {
+    const pattern = `${searchQuery
+      .toLowerCase()
+      .replaceAll('\\', '\\\\')
+      .replaceAll('%', '\\%')
+      .replaceAll('_', '\\_')}%`
+    query = query.where((eb) =>
+      eb.or([
+        sql<boolean>`lower(${sql.ref('organizations.name')}) LIKE ${pattern} ESCAPE '\\'`,
+        eb(
+          'organizations.id',
+          'in',
+          eb
+            .selectFrom('memberships')
+            .innerJoin('users', 'users.id', 'memberships.userId')
+            .select('memberships.orgId')
+            .where(sql<boolean>`lower(${sql.ref('users.email')}) LIKE ${pattern} ESCAPE '\\'`),
+        ),
+      ]),
+    )
+  }
+
+  if (cursor)
+    query = query.where((eb) =>
+      eb.or([
+        eb('organizations.createdAt', '<', cursor.createdAt),
+        eb.and([
+          eb('organizations.createdAt', '=', cursor.createdAt),
+          eb('organizations.id', '<', cursor.id),
+        ]),
+      ]),
+    )
+
+  const records = await query
+    .orderBy('organizations.createdAt', 'desc')
+    .orderBy('organizations.id', 'desc')
+    .limit(limit + 1)
+    .execute()
+  return records.map((record) => ({
+    ...record,
+    memberCount: Number(record.memberCount),
+    projectCount: Number(record.projectCount),
+  }))
+}
+
+export declare namespace search {
+  /** Cursor fields for the last organization returned by the previous page. */
+  type Cursor = {
+    /** Organization creation time. */
+    createdAt: string
+    /** Organization id, used as a deterministic tie-breaker. */
+    id: string
+  }
+
+  /** Options for {@link search}. */
+  type Options = {
+    /** Last organization returned by the previous page. */
+    cursor?: Cursor | undefined
+    /** Requested page size. */
+    limit: number
+    /** Exact resource id or case-insensitive name/email prefix search. */
+    query?: string | undefined
+  }
+
+  /** Organization summary returned by {@link search}. */
+  type Result = Record & {
+    /** Number of current organization members. */
+    memberCount: number
+    /** Number of projects owned by the organization. */
+    projectCount: number
+  }
+}
+
 /**
  * Lists organizations owned by `userId`, newest first.
  *