tapimo 0.1.0 → 0.2.0

package/src/apps/{transactions.ts → data/routes/transactions.ts}

@@ -2,19 +2,19 @@ import { Hono, type Context } from 'hono'
 import { Hex } from 'ox'
 import * as z from 'zod/mini'
 
-import type * as App from '../App.js'
-import * as Auth from '../internal/Auth.js'
-import * as Cache from '../internal/Cache.js'
-import * as Cursor from '../internal/Cursor.js'
-import * as OpenApi from '../internal/OpenApi.js'
-import * as Response from '../internal/Response.js'
-import * as Schema from '../internal/Schema.js'
-import * as Store from '../internal/Store.js'
-import type * as Tidx from '../internal/Tidx.js'
-import * as Timing from '../internal/Timing.js'
-import * as Ttl from '../internal/Ttl.js'
-import * as Value from '../internal/Value.js'
-import * as VerifiedTokens from '../internal/VerifiedTokens.js'
+import type * as App from '../../../App.js'
+import * as Auth from '../../../internal/Auth.js'
+import * as Cache from '../../../internal/Cache.js'
+import * as Cursor from '../../../internal/Cursor.js'
+import * as OpenApi from '../../../internal/OpenApi.js'
+import * as Response from '../../../internal/Response.js'
+import * as Schema from '../../../internal/Schema.js'
+import * as Store from '../../../internal/Store.js'
+import type * as Tidx from '../../../internal/Tidx.js'
+import * as Timing from '../../../internal/Timing.js'
+import * as Ttl from '../../../internal/Ttl.js'
+import * as Value from '../../../internal/Value.js'
+import * as VerifiedTokens from '../../../internal/VerifiedTokens.js'
 import * as Receipts from './receipts.js'
 import * as Tokens from './tokens.js'
 
@@ -595,7 +595,7 @@ export namespace schema {
 export function transactions() {
   return new Hono<App.Environment>()
     .get(
-      '/',
+      '/v1/transactions',
       Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }),
       OpenApi.validate('query', schema.getTransactions.Query, {
         code: 'query_invalid',
@@ -692,7 +692,7 @@ export function transactions() {
       },
     )
     .get(
-      '/:transactionHash',
+      '/v1/transactions/:transactionHash',
       Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }),
       OpenApi.validate('param', schema.getTransaction.Params, {
         code: 'transaction_invalid',

package/src/apps/{transfers.test.ts → data/routes/transfers.test.ts}

@@ -1,8 +1,8 @@
 import type * as z from 'zod/mini'
 import { Schema } from 'tapimo'
 
-import * as TestApp from '../../test/App.js'
-import * as Runtime from '../../test/runtime.js'
+import * as TestApp from '../../../../test/App.js'
+import * as Runtime from '../../../../test/runtime.js'
 import * as Transfers from './transfers.js'
 
 describe('GET /transfers', () => {

package/src/apps/{transfers.ts → data/routes/transfers.ts}

@@ -3,20 +3,20 @@ import { Address, Hex } from 'ox'
 import { Addresses } from 'viem/tempo'
 import * as z from 'zod/mini'
 
-import type * as App from '../App.js'
-import * as Auth from '../internal/Auth.js'
-import * as Cache from '../internal/Cache.js'
-import * as Cursor from '../internal/Cursor.js'
-import * as Mpp from '../internal/Mpp.js'
-import * as OpenApi from '../internal/OpenApi.js'
-import * as Response from '../internal/Response.js'
-import * as Schema from '../internal/Schema.js'
-import * as Store from '../internal/Store.js'
-import type * as Tidx from '../internal/Tidx.js'
-import * as Timing from '../internal/Timing.js'
-import * as Ttl from '../internal/Ttl.js'
-import * as Value from '../internal/Value.js'
-import * as VerifiedTokens from '../internal/VerifiedTokens.js'
+import type * as App from '../../../App.js'
+import * as Auth from '../../../internal/Auth.js'
+import * as Cache from '../../../internal/Cache.js'
+import * as Cursor from '../../../internal/Cursor.js'
+import * as Mpp from '../../../internal/Mpp.js'
+import * as OpenApi from '../../../internal/OpenApi.js'
+import * as Response from '../../../internal/Response.js'
+import * as Schema from '../../../internal/Schema.js'
+import * as Store from '../../../internal/Store.js'
+import type * as Tidx from '../../../internal/Tidx.js'
+import * as Timing from '../../../internal/Timing.js'
+import * as Ttl from '../../../internal/Ttl.js'
+import * as Value from '../../../internal/Value.js'
+import * as VerifiedTokens from '../../../internal/VerifiedTokens.js'
 import * as Tokens from './tokens.js'
 
 // TIP-20 tokens emit the standard ERC-20 Transfer event. Supplying the
@@ -285,7 +285,7 @@ export namespace schema {
 /** Creates transfer handlers. */
 export function transfers() {
   return new Hono<App.Environment>().get(
-    '/',
+    '/v1/transfers',
     Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }),
     OpenApi.validate('query', schema.getTransfers.Query, {
       code: 'query_invalid',

package/src/apps/{verified-tokens.test.ts → data/routes/verified-tokens.test.ts}

@@ -1,6 +1,6 @@
-import * as TestApp from '../../test/App.js'
-import * as Runtime from '../../test/runtime.js'
-import * as VerifiedTokens from '../internal/VerifiedTokens.js'
+import * as TestApp from '../../../../test/App.js'
+import * as Runtime from '../../../../test/runtime.js'
+import * as VerifiedTokens from '../../../internal/VerifiedTokens.js'
 import * as Verified from './verified-tokens.js'
 
 /** Reader key for the data routes. */

package/src/apps/{verified-tokens.ts → data/routes/verified-tokens.ts}

@@ -1,13 +1,13 @@
 import { type Context, Hono } from 'hono'
 import * as z from 'zod/mini'
 
-import type * as App from '../App.js'
-import * as Auth from '../internal/Auth.js'
-import * as Cache from '../internal/Cache.js'
-import * as OpenApi from '../internal/OpenApi.js'
-import * as Response from '../internal/Response.js'
-import * as Schema from '../internal/Schema.js'
-import * as VerifiedTokens from '../internal/VerifiedTokens.js'
+import type * as App from '../../../App.js'
+import * as Auth from '../../../internal/Auth.js'
+import * as Cache from '../../../internal/Cache.js'
+import * as OpenApi from '../../../internal/OpenApi.js'
+import * as Response from '../../../internal/Response.js'
+import * as Schema from '../../../internal/Schema.js'
+import * as VerifiedTokens from '../../../internal/VerifiedTokens.js'
 
 /** Zod schemas owned by the verified-tokens resource. */
 export namespace schema {
@@ -138,7 +138,7 @@ export namespace schema {
 export function verifiedTokens() {
   return new Hono<App.Environment>()
     .get(
-      '/',
+      '/v1/verified-tokens',
       Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }),
       OpenApi.validate('query', schema.listVerifiedTokens.Query, {
         code: 'query_invalid',
@@ -183,7 +183,7 @@ export function verifiedTokens() {
       },
     )
     .get(
-      '/currencies',
+      '/v1/verified-tokens/currencies',
       Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }),
       OpenApi.validate('query', schema.getVerifiedTokenCurrencies.Query, {
         code: 'query_invalid',
@@ -230,7 +230,7 @@ export function verifiedTokens() {
       },
     )
     .get(
-      '/:address',
+      '/v1/verified-tokens/:address',
       Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }),
       OpenApi.validate('param', schema.Params, {
         code: 'address_invalid',

package/src/apps/{webhooks.test.ts → data/routes/webhooks.test.ts}

@@ -1,11 +1,11 @@
 import { type Db, Webhooks as Core } from 'tapimo'
 
-import * as Tidx from '../internal/Tidx.js'
-import * as Viem from '../internal/Viem.js'
-import * as TestApp from '../../test/App.js'
-import * as Mppx from '../../test/Mppx.js'
-import * as Runtime from '../../test/runtime.js'
-import * as Tempo from '../../test/Tempo.js'
+import * as Tidx from '../../../internal/Tidx.js'
+import * as Viem from '../../../internal/Viem.js'
+import * as TestApp from '../../../../test/App.js'
+import * as Mppx from '../../../../test/Mppx.js'
+import * as Runtime from '../../../../test/runtime.js'
+import * as Tempo from '../../../../test/Tempo.js'
 import * as Webhooks from './webhooks.js'
 
 /** API key with both webhook scopes, owned by `org_test`. */

package/src/apps/{webhooks.ts → data/routes/webhooks.ts}

@@ -2,20 +2,20 @@ import { type Context, Hono } from 'hono'
 import { type AbiEvent, parseAbiItem } from 'viem'
 import * as z from 'zod/mini'
 
-import type * as App from '../App.js'
-import * as Auth from '../internal/Auth.js'
-import * as Cache from '../internal/Cache.js'
-import * as Cursor from '../internal/Cursor.js'
-import * as Db from '../db/Db.js'
-import * as OpenApi from '../internal/OpenApi.js'
-import * as Response from '../internal/Response.js'
-import * as Schema from '../internal/Schema.js'
-import * as Store from '../internal/Store.js'
-import type * as Tidx from '../internal/Tidx.js'
-import * as Ttl from '../internal/Ttl.js'
-import * as Value from '../internal/Value.js'
-import type * as Viem from '../internal/Viem.js'
-import * as Webhooks from '../internal/Webhooks.js'
+import type * as App from '../../../App.js'
+import * as Auth from '../../../internal/Auth.js'
+import * as Cache from '../../../internal/Cache.js'
+import * as Cursor from '../../../internal/Cursor.js'
+import * as Db from '../../../db/Db.js'
+import * as OpenApi from '../../../internal/OpenApi.js'
+import * as Response from '../../../internal/Response.js'
+import * as Schema from '../../../internal/Schema.js'
+import * as Store from '../../../internal/Store.js'
+import type * as Tidx from '../../../internal/Tidx.js'
+import * as Ttl from '../../../internal/Ttl.js'
+import * as Value from '../../../internal/Value.js'
+import type * as Viem from '../../../internal/Viem.js'
+import * as Webhooks from '../../../internal/Webhooks.js'
 import * as Receipts from './receipts.js'
 import * as Transactions from './transactions.js'
 import * as Transfers from './transfers.js'
@@ -378,7 +378,7 @@ export namespace schema {
           .record(z.string(), z.unknown())
           .check(
             z.describe(
-              'Match decoded event arguments by name (indexed or non-indexed). Requires `signature`. Each value is an exact value or an operator object.',
+              'Match decoded event arguments by name (indexed or non-indexed). Requires `signature`. Each value is an exact value or a super admin object.',
             ),
             z.meta({ examples: [{ to: '0x9e39034aae71fb89f66061a2602eb6efec271754' }] }),
           ),
@@ -1225,21 +1225,25 @@ export namespace schema {
  */
 export function webhooks(options: webhooks.Options = {}) {
   const hidden = !options.enabled
-  return (
-    new Hono<App.Environment>()
-      .use('*', async (c, next) => {
-        // Gate the whole resource on a configured state store. Without it the
-        // outbound-HTTP surface is disabled (read-only deployment).
-        if (!c.get('webhook')) return notEnabled(c) as never
+  // Gate the whole resource on a configured state store. Without it the
+  // outbound-HTTP surface is disabled (read-only deployment).
+  const gate = async (c: Context<App.Environment>, next: () => Promise<void>) => {
+    if (!c.get('webhook')) return notEnabled(c) as never
 
-        await next()
+    await next()
 
-        // Subscriptions are principal-scoped, mutating, and stateful: never cache.
-        if (!c.res.headers.has('Cache-Control')) c.res.headers.set('Cache-Control', 'no-store')
-        return
-      })
+    // Subscriptions are principal-scoped, mutating, and stateful: never cache.
+    if (!c.res.headers.has('Cache-Control')) c.res.headers.set('Cache-Control', 'no-store')
+    return
+  }
+  return (
+    new Hono<App.Environment>()
+      // `/v1/webhooks/*` does not match the collection root, so it gets its
+      // own registration.
+      .use('/v1/webhooks', gate)
+      .use('/v1/webhooks/*', gate)
       .get(
-        '/event-types',
+        '/v1/webhooks/event-types',
         Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }),
         OpenApi.describeRoute({
           description: 'See which onchain event types Tempo can POST to your webhook URL.',
@@ -1275,7 +1279,7 @@ export function webhooks(options: webhooks.Options = {}) {
         },
       )
       .post(
-        '/',
+        '/v1/webhooks',
         Auth.policy({ apiKey: { scopes: ['webhooks:write'] } }),
         OpenApi.validate('json', schema.createWebhook.Body, {
           code: 'body_invalid',
@@ -1338,7 +1342,7 @@ export function webhooks(options: webhooks.Options = {}) {
         },
       )
       .get(
-        '/',
+        '/v1/webhooks',
         Auth.policy({ apiKey: { scopes: ['webhooks:read'] } }),
         OpenApi.validate('query', schema.listWebhooks.Query, {
           code: 'query_invalid',
@@ -1412,7 +1416,7 @@ export function webhooks(options: webhooks.Options = {}) {
       // constraint, this API-key-only route's policy would be collected for the
       // event-types request and override its (intentionally public) access.
       .get(
-        '/:id{wh_[A-Za-z0-9_-]+}',
+        '/v1/webhooks/:id{wh_[A-Za-z0-9_-]+}',
         Auth.policy({ apiKey: { scopes: ['webhooks:read'] } }),
         OpenApi.validate('param', schema.getWebhook.Params, {
           code: 'param_invalid',
@@ -1464,7 +1468,7 @@ export function webhooks(options: webhooks.Options = {}) {
         },
       )
       .get(
-        '/:id{wh_[A-Za-z0-9_-]+}/deliveries',
+        '/v1/webhooks/:id{wh_[A-Za-z0-9_-]+}/deliveries',
         Auth.policy({ apiKey: { scopes: ['webhooks:read'] } }),
         OpenApi.validate('param', schema.listWebhookDeliveries.Params, {
           code: 'param_invalid',
@@ -1555,7 +1559,7 @@ export function webhooks(options: webhooks.Options = {}) {
         },
       )
       .post(
-        '/:id{wh_[A-Za-z0-9_-]+}/ping',
+        '/v1/webhooks/:id{wh_[A-Za-z0-9_-]+}/ping',
         Auth.policy({ apiKey: { scopes: ['webhooks:write'] } }),
         OpenApi.validate('param', schema.pingWebhook.Params, {
           code: 'param_invalid',
@@ -1620,7 +1624,7 @@ export function webhooks(options: webhooks.Options = {}) {
         },
       )
       .post(
-        '/:id{wh_[A-Za-z0-9_-]+}/deliveries/:deliveryId/retry',
+        '/v1/webhooks/:id{wh_[A-Za-z0-9_-]+}/deliveries/:deliveryId/retry',
         Auth.policy({ apiKey: { scopes: ['webhooks:write'] } }),
         OpenApi.validate('param', schema.retryWebhookDelivery.Params, {
           code: 'param_invalid',
@@ -1691,7 +1695,7 @@ export function webhooks(options: webhooks.Options = {}) {
         },
       )
       .patch(
-        '/:id{wh_[A-Za-z0-9_-]+}',
+        '/v1/webhooks/:id{wh_[A-Za-z0-9_-]+}',
         Auth.policy({ apiKey: { scopes: ['webhooks:write'] } }),
         OpenApi.validate('param', schema.updateWebhook.Params, {
           code: 'param_invalid',
@@ -1763,7 +1767,7 @@ export function webhooks(options: webhooks.Options = {}) {
         },
       )
       .delete(
-        '/:id{wh_[A-Za-z0-9_-]+}',
+        '/v1/webhooks/:id{wh_[A-Za-z0-9_-]+}',
         Auth.policy({ apiKey: { scopes: ['webhooks:write'] } }),
         OpenApi.validate('param', schema.deleteWebhook.Params, {
           code: 'param_invalid',

package/src/apps/docs/App.ts

@@ -0,0 +1,136 @@
+import { Hono } from 'hono'
+import { Handler as vocs_Handler } from 'vocs/server'
+
+import type * as App from '../../App.js'
+import * as Metadata from '../metadata.js'
+import openrpcSpec from '../../openrpc.json' with { type: 'json' }
+import { pilatFontFaces } from './fonts.js'
+import { logoUrl } from './logo.js'
+
+/**
+ * The docs route group: the Vocs API reference served at the app root.
+ *
+ * ```ts
+ * import { docs } from 'tapimo/docs'
+ * App.create(options).route('/', data()).route('/', platform()).route('/', docs())
+ * ```
+ *
+ * The group registers no routes itself: it carries a reference factory (via
+ * {@link Metadata}) that `App.create` mounts on finalize, after every group and
+ * the OpenAPI/OpenRPC documents — so the reference always renders the full
+ * composed surface and its catch-all stays behind API routes, wherever the
+ * group sits in the composition chain.
+ *
+ * Lives in the `tapimo/docs` subpath (never re-exported from `tapimo/apps`) so
+ * the Vocs renderer and its multi-MB icon/font data are bundled only by
+ * deployments that actually serve docs.
+ */
+export function docs(options: docs.Options = {}) {
+  return Metadata.attach(new Hono<App.Environment>(), {
+    docs: ({ spec }) =>
+      vocs_Handler.openApi(
+        {
+          // Inline the OpenRPC doc so vocs expands it without a self-subrequest
+          // (see `inlineOpenrpc`); the public `/openapi.json` keeps the URL ref.
+          spec: () => spec().then(inlineOpenrpc),
+          sidebar: { collapsed: true },
+          vocs: { logoUrl, title: 'Tempo API Reference', ...options },
+        },
+        { css, fallback: 'next' },
+      ),
+  })
+}
+
+export declare namespace docs {
+  /** Vocs API reference options (theme, top navigation, logo, socials, …). */
+  type Options = NonNullable<Parameters<typeof vocs_Handler.openApi>[0]['vocs']>
+}
+
+/**
+ * Custom CSS injected into the standalone reference's shell `<head>` (via
+ * `Handler.openApi(_, { css })`), after the Vocs design-system styles so it
+ * overrides them:
+ *
+ * - Page/surface backgrounds use Tempo's near-black dark palette and pure-white
+ *   light palette via `light-dark(<light>, <dark>)`.
+ * - The dark border color is darkened (the light theme keeps its default).
+ * - Every corner is squared. The universal `!important` rule beats hard-coded
+ *   `border-radius` values and inline styles (e.g. the Scalar playground), which
+ *   overriding the radius scale variables alone would miss.
+ * - The default sans/body font is Pilat (Vocs reads `--vocs-font-family`); the
+ *   webfont is embedded via {@link pilatFontFaces}. Body stays at the default
+ *   weight (400); headings are pinned to 500, which renders Pilat Demi (the
+ *   family has no 500 cut, so Demi covers the 500-600 range — see
+ *   {@link pilatFontFaces}).
+ */
+const css = `${pilatFontFaces}
+
+:root {
+  --vocs-font-family: "Pilat", Arial, Helvetica, sans-serif;
+  --vocs-background-color-primary: light-dark(#fafafa, #0a0a0a);
+  --vocs-background-color-surface: light-dark(#fff, #121212);
+}
+
+:is(h1, h2, h3, h4, h5, h6)[data-v] {
+  font-weight: 500;
+}
+
+/* Nudge the header logo a touch larger than the default max-h-7 (1.75rem). */
+[data-v-logo-image] {
+  max-height: 2rem;
+}
+
+/* Sidebar leaf items render Regular (the nav's 450 default otherwise resolves to
+ * Demi via the 500-600 range). Group labels ([data-v-sidebar-section-header])
+ * keep their heavier weight. */
+[data-v-sidebar-item] {
+  font-weight: 400;
+}
+
+[data-vocs-theme='dark'] {
+  --vocs-color-gray4: oklch(20% 0 0);
+  --vocs-color-gray5: oklch(0.23 0 0);
+  --vocs-border-color-primary: oklch(0.25 0 0);
+  --vocs-border-color-secondary: oklch(0.25 0 0);
+}
+
+*,
+*::before,
+*::after {
+  border-radius: 0 !important;
+}`
+
+/**
+ * Returns a shallow copy of `spec` with the JSON-RPC passthrough operation's
+ * `x-openrpc` replaced by the inline OpenRPC document, for the docs handler.
+ *
+ * Vocs expands `x-openrpc` at request time. A URL reference (as kept in the
+ * public `/openapi.json` by `App.create`'s `applyOpenrpcLink`) would make the
+ * docs worker fetch its own `/openrpc.json` — a self-subrequest that is
+ * unreliable on Cloudflare Workers and silently falls back to a single,
+ * unexpanded operation. Inlining the committed artifact keeps expansion
+ * deterministic across local and deployed environments, without bloating the
+ * public spec. Only the affected path/op are cloned; the rest of the (large)
+ * document is shared by reference.
+ */
+function inlineOpenrpc<spec extends { paths: Record<string, unknown> }>(spec: spec): spec {
+  const paths: Record<string, unknown> = {}
+  for (const [pathname, item] of Object.entries(spec.paths)) {
+    let next = item
+    if (isRecord(item))
+      for (const [method, op] of Object.entries(item))
+        if (isRpcOperation(op)) next = { ...item, [method]: { ...op, 'x-openrpc': openrpcSpec } }
+    paths[pathname] = next
+  }
+  return { ...spec, paths }
+}
+
+// The JSON-RPC passthrough's operation id, set by its route definition and
+// targeted by `App.create`'s `applyOpenrpcLink`.
+function isRpcOperation(op: unknown): op is Record<string, unknown> {
+  return isRecord(op) && op['operationId'] === 'rpcRequest'
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === 'object' && !Array.isArray(value)
+}

package/src/apps/docs/index.ts

@@ -0,0 +1 @@
+export { docs } from './App.js'

package/src/apps/index.ts

@@ -0,0 +1,3 @@
+export { data } from './data/index.js'
+export { platform } from './platform/index.js'
+export { relay } from './relay/index.js'

package/src/apps/metadata.ts

@@ -0,0 +1,23 @@
+import type { Hono } from 'hono'
+
+import type * as App from '../App.js'
+
+// Hono's `.route()` drops sub-app metadata, so a group's OpenAPI metadata can't
+// ride the instance through it. Each group attaches its metadata here and
+// `App.create` reads it back on mount. The `WeakMap` keeps the association off
+// the app's type, so `testClient`/`hc` inference is untouched.
+const registry = new WeakMap<Hono<any, any>, App.create.Metadata>()
+
+/** Attaches a group's OpenAPI metadata to its app instance for `create` to collect on mount. */
+export function attach<const app extends Hono<any, any>>(
+  app: app,
+  metadata: App.create.Metadata,
+): app {
+  registry.set(app, metadata)
+  return app
+}
+
+/** Reads the OpenAPI metadata attached to an app instance, if any. */
+export function read(app: Hono<any, any>): App.create.Metadata | undefined {
+  return registry.get(app)
+}

package/src/apps/platform/App.ts

@@ -0,0 +1,130 @@
+import { Hono } from 'hono'
+
+import type * as App from '../../App.js'
+import * as Metadata from '../metadata.js'
+
+import { apiKeys } from './routes/api-keys.js'
+import { invitations } from './routes/invitations.js'
+import { me } from './routes/me.js'
+import { members } from './routes/members.js'
+import { orgs } from './routes/orgs.js'
+import { projects } from './routes/projects.js'
+
+/**
+ * Minimal transactional email sender. Cloudflare deployments wrap the Email
+ * Service binding (`{ from, send: (m) => env.EMAIL.send(m) }`); other hosts
+ * pass any compatible sender. Dispatch is always best-effort.
+ */
+export type Email = {
+  /** Console URL embedded in email links (e.g. sign-in URLs). Defaults to the hosted console; self-hosts point it at their own. */
+  consoleUrl?: string | undefined
+  /** Sender address for platform emails (e.g. `noreply@tempo.xyz`). */
+  from: string
+  /** Sends one message. */
+  send: (message: Email.Message) => Promise<unknown>
+}
+
+export declare namespace Email {
+  /** One transactional message. */
+  type Message = {
+    /** Sender address. */
+    from: string
+    /** HTML body. */
+    html?: string | undefined
+    /** Subject line. */
+    subject: string
+    /** Plain-text body. */
+    text: string
+    /** Recipient address. */
+    to: string
+  }
+}
+
+/**
+ * Request environment for platform routes: the shared app environment plus the
+ * `email` sender this group publishes on context. Owned here, not in core
+ * `App.Environment`, since email is a platform concern.
+ */
+export type Environment = {
+  Variables: App.Environment['Variables'] & {
+    /** Transactional email sender for platform emails; undefined when dispatch is disabled. */
+    email: Email | undefined
+  }
+}
+
+/**
+ * The tenant-platform route group: the current user, orgs, projects, members,
+ * invitations, and API-key management. Every route reads its dependencies from
+ * request context set by {@link App.create}.
+ *
+ * The session-auth surface (`/v1/auth/siwe` + `session` capability) is owned by
+ * {@link App.create}, so platform routes gate on a session without owning it.
+ *
+ * ```ts
+ * App.create(options).route('/', platform())
+ * ```
+ */
+export function platform(options: platform.Options = {}) {
+  const app = new Hono<Environment>()
+    // Publish the transactional email sender for this group's handlers
+    // (invitations read it off context); undefined disables dispatch.
+    .use('*', async (c, next) => {
+      c.set('email', options.email)
+      await next()
+    })
+    .route('/', apiKeys({ enabled: options.apiKeys !== false }))
+    .route('/', invitations())
+    .route('/', me())
+    .route('/', members())
+    .route('/', orgs())
+    .route('/', projects())
+  return Metadata.attach(app, openapi)
+}
+
+export declare namespace platform {
+  /** Options for the platform route group. */
+  type Options = {
+    /** Expose the API-key management routes in the OpenAPI document. @default true */
+    apiKeys?: boolean | undefined
+    /** Transactional email sender for platform emails (e.g. invitations); omit to disable dispatch — notified flows still work in-product. */
+    email?: Email | undefined
+  }
+}
+
+/**
+ * The OpenAPI metadata this group owns: platform operation tags and the
+ * `session` security scheme. Tagged onto the {@link platform} instance so
+ * `App.create` collects it.
+ */
+const openapi = {
+  securitySchemes: {
+    session: {
+      description: 'Cookie session established by sign-in (`POST /v1/auth/siwe`). Clients may also send the session token as `Authorization: Bearer <token>`.', // prettier-ignore
+      in: 'cookie',
+      name: 'accounts_auth',
+      type: 'apiKey',
+    },
+  },
+  tags: [
+    { name: 'API Keys', description: 'Credentials for accessing the Tempo API.' },
+    { name: 'Invitations', description: 'Pending organization invitations.' },
+    { name: 'Members', description: 'Organization team membership.' },
+    { name: 'Organizations', description: 'Teams that own application workspaces and members.' },
+    { name: 'Projects', description: 'Application workspaces within an organization.' },
+    { name: 'Users', description: 'Users on the Tempo Platform.' },
+  ],
+  'x-tagGroups': [
+    {
+      name: 'Platform API',
+      tags: [
+        'API Keys',
+        'Authentication',
+        'Invitations',
+        'Members',
+        'Organizations',
+        'Projects',
+        'Users',
+      ],
+    },
+  ],
+} satisfies App.create.Metadata

package/src/apps/platform/index.ts

@@ -0,0 +1 @@
+export { platform } from './App.js'