tapimo 0.2.0 → 0.3.0

package/src/App.ts

@@ -6,6 +6,7 @@ import { HTTPException } from 'hono/http-exception'
 import { requestId, type RequestIdVariables } from 'hono/request-id'
 import { generateSpecs } from 'hono-openapi'
 
+import type * as Analytics from './analytics/Analytics.js'
 import * as ApiKey from './ApiKey.js'
 import * as Assets from './Assets.js'
 import * as Auth from './internal/Auth.js'
@@ -40,6 +41,8 @@ export type PlatformApp = ReturnType<typeof platform>
 export type Environment = {
   Variables: Auth.Variables &
     RequestIdVariables & {
+      /** ClickHouse-backed analytics store, or a per-request factory; undefined when usage analytics is unconfigured. Resolve at the leaf with `Analytics.get`. */
+      analytics: Analytics.Source | undefined
       /** Base path for this API app. */
       basePath: string
       /** Default Tempo chain id for this API app. */
@@ -93,6 +96,9 @@ export type Listener = (incoming: unknown, outgoing: unknown) => Promise<void>
 /** HTTP endpoints owned by Tempo API handlers, used for typed auth overrides. */
 export type Endpoint = Auth.Endpoint<App>
 
+/** Stripe billing capability for platform billing routes; owned by {@link platform}. */
+export type Billing = Platform.Billing
+
 /** Transactional email sender for platform emails; owned by {@link platform}. */
 export type Email = Platform.Email
 
@@ -194,12 +200,22 @@ export function create<const path extends string = '/'>(options: create.Options<
   // side; `cached` falls back to `source` so consumers never branch.
   const db = 'source' in options.db ? options.db : { source: options.db }
 
+  // Normalize the `analytics` option: accept the bare source or `{ source }`,
+  // mirroring `db`. Undefined leaves usage analytics unconfigured (501).
+  const analytics =
+    options.analytics === undefined
+      ? undefined
+      : 'source' in options.analytics
+        ? options.analytics.source
+        : options.analytics
+
   // Built-in auth: the session surface (mounted last) plus the enforcement
   // middleware (installed below), wired together in `Auth.install`.
   const auth = Auth.install({ auth: options.auth, db: db.source, kv: options.kv })
 
   base.use('*', Timing.middleware())
   base.use('*', async (c, next) => {
+    c.set('analytics', analytics)
     c.set('basePath', basePath)
     c.set('db', db.source)
     c.set('dbCached', db.cached ?? db.source)
@@ -403,6 +419,8 @@ export declare namespace create {
    * configuration belongs to {@link data}; email to {@link platform}.
    */
   type Options<path extends string = '/'> = {
+    /** Analytics store for usage reads (e.g. `Analytics.clickhouse(...)`), or a per-request factory. Accepts `{ source }` to mirror `db`. Omit to leave usage analytics unconfigured — usage routes answer 501. Ingest happens outside this app (queue consumer via `Analytics.handleQueue`). */
+    analytics?: Analytics.Source | { source: Analytics.Source } | undefined
     /** Authentication: lane defaults, quotas, and credentials for the built-in enforcement middleware, plus the `session` sign-in surface. Omit for default-closed policies with in-memory rate limiting; pass false to leave policies unenforced (tests only). */
     auth?: Auth.install.Options['auth'] | false | undefined
     /** Caching configuration: the cache store plus the edge response cache toggle. */

package/src/Client.test-d.ts

@@ -3,14 +3,17 @@ import type * as z from 'zod/mini'
 
 import * as Activities from './apps/data/routes/activities.js'
 import * as Balances from './apps/data/routes/balances.js'
+import * as Billing from './apps/platform/routes/billing.js'
 import * as Blocks from './apps/data/routes/blocks.js'
 import * as Exchanges from './apps/data/routes/exchanges.js'
 import * as FeeAmm from './apps/data/routes/fee-amm.js'
+import * as Funding from './apps/data/routes/funding.js'
 import * as Indexer from './apps/data/routes/indexer.js'
 import * as Me from './apps/platform/routes/me.js'
 import * as Orgs from './apps/platform/routes/orgs.js'
 import * as Receipts from './apps/data/routes/receipts.js'
 import * as Rpc from './apps/data/routes/rpc.js'
+import * as Scopes from './apps/platform/routes/scopes.js'
 import * as Tokens from './apps/data/routes/tokens.js'
 import * as Transactions from './apps/data/routes/transactions.js'
 import * as Transfers from './apps/data/routes/transfers.js'
@@ -127,6 +130,30 @@ describe('narrows responses by status', () => {
     }
   })
 
+  test('GET /v1/scopes', async () => {
+    const client = Client.create()
+    const res = await client.v1.scopes.$get()
+
+    expectTypeOf(res.status).toEqualTypeOf<200 | PublicAccessStatus>()
+
+    switch (res.status) {
+      case 200: {
+        const json = await res.json()
+        expectTypeOf(json.data[0]!.scope).toEqualTypeOf<
+          z.output<typeof Scopes.schema.getScopes.Response>['data'][number]['scope']
+        >()
+        void json
+        return
+      }
+      case 400: {
+        const json = await res.json()
+        expectTypeOf(json.error.code).toEqualTypeOf<'api_key_malformed'>()
+        void json
+        return
+      }
+    }
+  })
+
   test('POST /v1/orgs', async () => {
     const client = Client.create()
     const res = await client.v1.orgs.$post({ json: { name: 'Acme' } })
@@ -173,6 +200,164 @@ describe('narrows responses by status', () => {
     }
   })
 
+  test('GET /v1/orgs/:orgId/billing', async () => {
+    const client = Client.create()
+    const res = await client.v1.orgs[':orgId{org_[A-Za-z0-9_-]+}'].billing.$get({
+      param: { orgId: 'org_test' },
+    })
+
+    expectTypeOf(res.status).toEqualTypeOf<200 | 400 | 401 | 403 | 404 | 501 | 502>()
+
+    switch (res.status) {
+      case 200: {
+        const json = await res.json()
+        expectTypeOf(json.status).toEqualTypeOf<z.output<typeof Billing.schema.Billing>['status']>()
+        void json
+        return
+      }
+      case 501: {
+        const json = await res.json()
+        expectTypeOf(json.error.code).toEqualTypeOf<'billing_unconfigured'>()
+        void json
+        return
+      }
+    }
+  })
+
+  test('GET /v1/orgs/:orgId/usage/sponsorships', async () => {
+    const client = Client.create()
+    const res = await client.v1.orgs[':orgId{org_[A-Za-z0-9_-]+}'].usage.sponsorships.$get({
+      param: { orgId: 'org_test' },
+    })
+
+    expectTypeOf(res.status).toEqualTypeOf<200 | 400 | 401 | 403 | 404 | 502>()
+
+    switch (res.status) {
+      case 200: {
+        const json = await res.json()
+        expectTypeOf(json.data[0]!.count).toEqualTypeOf<number>()
+        expectTypeOf(json.data[0]!.feeTotal).toEqualTypeOf<{ amount: string; currency: 'usd' }>()
+        expectTypeOf(json.data[0]!.timestamp).toEqualTypeOf<string>()
+        void json
+        return
+      }
+      case 400: {
+        const json = await res.json()
+        expectTypeOf(json.error.code).toEqualTypeOf<Access400<'param_invalid' | 'query_invalid'>>()
+        void json
+        return
+      }
+    }
+  })
+
+  test('PATCH /v1/orgs/:orgId/billing', async () => {
+    const client = Client.create()
+    const res = await client.v1.orgs[':orgId{org_[A-Za-z0-9_-]+}'].billing.$patch({
+      json: { spendLimit: { amount: '250' }, txFeeLimit: null },
+      param: { orgId: 'org_test' },
+    })
+
+    expectTypeOf(res.status).toEqualTypeOf<200 | 400 | 401 | 403 | 404 | 501 | 502>()
+
+    switch (res.status) {
+      case 200: {
+        const json = await res.json()
+        expectTypeOf(json.spendLimit).toEqualTypeOf<
+          z.output<typeof Billing.schema.SpendLimit> | undefined
+        >()
+        expectTypeOf(json.spend).toEqualTypeOf<z.output<typeof Billing.schema.Billing>['spend']>()
+        void json
+        return
+      }
+      case 501: {
+        const json = await res.json()
+        expectTypeOf(json.error.code).toEqualTypeOf<'billing_unconfigured'>()
+        void json
+        return
+      }
+    }
+  })
+
+  test('POST /v1/orgs/:orgId/billing/stripe/manage', async () => {
+    const client = Client.create()
+    const res = await client.v1.orgs[':orgId{org_[A-Za-z0-9_-]+}'].billing.stripe.manage.$post({
+      param: { orgId: 'org_test' },
+    })
+
+    expectTypeOf(res.status).toEqualTypeOf<200 | 400 | 401 | 403 | 404 | 501 | 502>()
+
+    switch (res.status) {
+      case 200: {
+        const json = await res.json()
+        expectTypeOf(json.url).toEqualTypeOf<string>()
+        void json
+        return
+      }
+      case 404: {
+        const json = await res.json()
+        expectTypeOf(json.error.code).toEqualTypeOf<
+          'billing_not_found' | 'organization_not_found'
+        >()
+        void json
+        return
+      }
+    }
+  })
+
+  test('GET /v1/orgs/:orgId/billing/payment-methods', async () => {
+    const client = Client.create()
+    const res = await client.v1.orgs[':orgId{org_[A-Za-z0-9_-]+}'].billing['payment-methods'].$get({
+      param: { orgId: 'org_test' },
+    })
+
+    expectTypeOf(res.status).toEqualTypeOf<200 | 400 | 401 | 403 | 404 | 501 | 502>()
+
+    switch (res.status) {
+      case 200: {
+        const json = await res.json()
+        expectTypeOf(json.data[0]!.provider).toEqualTypeOf<'stripe'>()
+        expectTypeOf(json.data[0]!.default).toEqualTypeOf<boolean>()
+        expectTypeOf(json.data[0]!.card).toEqualTypeOf<
+          { brand: string; expMonth: number; expYear: number; last4: string } | undefined
+        >()
+        void json
+        return
+      }
+      case 501: {
+        const json = await res.json()
+        expectTypeOf(json.error.code).toEqualTypeOf<'billing_unconfigured'>()
+        void json
+        return
+      }
+    }
+  })
+
+  test('DELETE /v1/orgs/:orgId/billing/payment-methods/:methodId', async () => {
+    const client = Client.create()
+    const res = await client.v1.orgs[':orgId{org_[A-Za-z0-9_-]+}'].billing['payment-methods'][
+      ':methodId{pm_[A-Za-z0-9_-]+}'
+    ].$delete({ param: { methodId: 'pm_test', orgId: 'org_test' } })
+
+    expectTypeOf(res.status).toEqualTypeOf<200 | 400 | 401 | 403 | 404 | 501 | 502>()
+
+    switch (res.status) {
+      case 200: {
+        const json = await res.json()
+        expectTypeOf(json.status).toEqualTypeOf<'active' | 'canceled' | 'none' | 'past_due'>()
+        void json
+        return
+      }
+      case 404: {
+        const json = await res.json()
+        expectTypeOf(json.error.code).toEqualTypeOf<
+          'billing_not_found' | 'organization_not_found' | 'payment_method_not_found'
+        >()
+        void json
+        return
+      }
+    }
+  })
+
   test('DELETE /v1/orgs/:orgId', async () => {
     const client = Client.create()
     const res = await client.v1.orgs[':orgId{org_[A-Za-z0-9_-]+}'].$delete({
@@ -271,6 +456,29 @@ describe('narrows responses by status', () => {
     }
   })
 
+  test('GET /v1/orgs/:orgId/api-keys', async () => {
+    const client = Client.create()
+    const res = await client.v1.orgs[':orgId{org_[A-Za-z0-9_-]+}']['api-keys'].$get({
+      // The environment filter is optional (defaults to production server-side).
+      query: { environment: 'sandbox' },
+      param: { orgId: 'org_test' },
+    })
+
+    expectTypeOf(res.status).toEqualTypeOf<200 | 400 | 401 | 403 | 404 | 502>()
+
+    switch (res.status) {
+      case 200: {
+        const json = await res.json()
+        expectTypeOf(json.data[0]!.id).toEqualTypeOf<string>()
+        expectTypeOf(json.data[0]!.environment).toEqualTypeOf<'production' | 'sandbox'>()
+        // Absent on org-wide keys minted without project attribution.
+        expectTypeOf(json.data[0]!.projectId).toEqualTypeOf<string | undefined>()
+        void json
+        return
+      }
+    }
+  })
+
   test('DELETE /v1/orgs/:orgId/projects/:projectId/api-keys/:keyId', async () => {
     const client = Client.create()
     const res = await client.v1.orgs[':orgId{org_[A-Za-z0-9_-]+}'].projects[
@@ -296,6 +504,41 @@ describe('narrows responses by status', () => {
     }
   })
 
+  test('GET /v1/orgs/:orgId/usage/requests', async () => {
+    const client = Client.create()
+    const res = await client.v1.orgs[':orgId{org_[A-Za-z0-9_-]+}'].usage.requests.$get({
+      param: { orgId: 'org_test' },
+      query: { projectId: 'prj_test' },
+    })
+
+    expectTypeOf(res.status).toEqualTypeOf<200 | 400 | 401 | 403 | 404 | 501 | 502>()
+
+    switch (res.status) {
+      case 200: {
+        const json = await res.json()
+        expectTypeOf(json.from).toEqualTypeOf<string>()
+        expectTypeOf(json.interval).toEqualTypeOf<'day' | 'hour'>()
+        expectTypeOf(json.to).toEqualTypeOf<string>()
+        expectTypeOf(json.totals.requests).toEqualTypeOf<number>()
+        expectTypeOf(json.byKey[0]?.apiKeyId).toEqualTypeOf<string | undefined>()
+        void json
+        return
+      }
+      case 404: {
+        const json = await res.json()
+        expectTypeOf(json.error.code).toEqualTypeOf<'organization_not_found'>()
+        void json
+        return
+      }
+      case 501: {
+        const json = await res.json()
+        expectTypeOf(json.error.code).toEqualTypeOf<'analytics_unconfigured'>()
+        void json
+        return
+      }
+    }
+  })
+
   test('GET /v1/orgs/:orgId/members', async () => {
     const client = Client.create()
     const res = await client.v1.orgs[':orgId{org_[A-Za-z0-9_-]+}'].members.$get({
@@ -356,6 +599,30 @@ describe('narrows responses by status', () => {
     }
   })
 
+  test('POST /v1/invitations/:invitationId/decline', async () => {
+    const client = Client.create()
+    const res = await client.v1.invitations[':invitationId{inv_[A-Za-z0-9_-]+}'].decline.$post({
+      param: { invitationId: 'inv_test' },
+    })
+
+    expectTypeOf(res.status).toEqualTypeOf<200 | 400 | 401 | 403 | 404 | 502>()
+
+    switch (res.status) {
+      case 200: {
+        const json = await res.json()
+        expectTypeOf(json.id).toEqualTypeOf<string>()
+        void json
+        return
+      }
+      case 404: {
+        const json = await res.json()
+        expectTypeOf(json.error.code).toEqualTypeOf<'invitation_not_found'>()
+        void json
+        return
+      }
+    }
+  })
+
   test('GET /v1/orgs', async () => {
     const client = Client.create()
     const res = await client.v1.orgs.$get()
@@ -922,6 +1189,90 @@ describe('narrows responses by status', () => {
     }
   })
 
+  test('GET /v1/funding/routes', async () => {
+    const client = Client.create()
+    const res = await client.v1.funding.routes.$get({
+      query: {
+        sourceAmount: '1000000',
+        sourceChain: 'base',
+        sourceToken: 'USDC',
+      },
+    })
+
+    expectTypeOf(res.status).toEqualTypeOf<200 | 400 | PaidAccessStatus>()
+
+    switch (res.status) {
+      case 200: {
+        const json = await res.json()
+        expectTypeOf(json.data[0]!.sourceAmount).toEqualTypeOf<
+          z.output<typeof Funding.schema.listFundingRoutes.Response>['data'][number]['sourceAmount']
+        >()
+        expectTypeOf(json.data[0]!.provider.id).toEqualTypeOf<string>()
+        void json
+        return
+      }
+      case 400: {
+        const json = await res.json()
+        expectTypeOf(json.error.code).toEqualTypeOf<Access400<'query_invalid'>>()
+        expectTypeOf(json.error.message).toEqualTypeOf<string>()
+        void json
+        return
+      }
+    }
+  })
+
+  test('GET /v1/funding/chains', async () => {
+    const client = Client.create()
+    const res = await client.v1.funding.chains.$get()
+
+    expectTypeOf(res.status).toEqualTypeOf<200 | PaidAccessStatus>()
+
+    switch (res.status) {
+      case 200: {
+        const json = await res.json()
+        expectTypeOf(json.data[0]!.tokens[0]!.symbol).toEqualTypeOf<
+          z.output<
+            typeof Funding.schema.listFundingChains.Response
+          >['data'][number]['tokens'][number]['symbol']
+        >()
+        void json
+        return
+      }
+      case 400: {
+        const json = await res.json()
+        expectTypeOf(json.error.code).toEqualTypeOf<'api_key_malformed'>()
+        expectTypeOf(json.error.message).toEqualTypeOf<string>()
+        void json
+        return
+      }
+    }
+  })
+
+  test('GET /v1/providers', async () => {
+    const client = Client.create()
+    const res = await client.v1.providers.$get({ query: { capability: 'fundingRoutes' } })
+
+    expectTypeOf(res.status).toEqualTypeOf<200 | 400 | PaidAccessStatus>()
+
+    switch (res.status) {
+      case 200: {
+        const json = await res.json()
+        expectTypeOf(json.data[0]!.capabilities).toEqualTypeOf<
+          z.output<typeof Funding.schema.listProviders.Response>['data'][number]['capabilities']
+        >()
+        void json
+        return
+      }
+      case 400: {
+        const json = await res.json()
+        expectTypeOf(json.error.code).toEqualTypeOf<Access400<'query_invalid'>>()
+        expectTypeOf(json.error.message).toEqualTypeOf<string>()
+        void json
+        return
+      }
+    }
+  })
+
   test('GET /v1/exchange/swaps', async () => {
     const client = Client.create()
     const res = await client.v1.exchange.swaps.$get()

package/src/Scope.ts

@@ -18,6 +18,8 @@ type Entry = {
   description: string
   /** Scope identifier used in a key's `scopes` and in route policies. */
   scope: string
+  /** Whether a session may self-mint this scope (else super-admin-only). */
+  selfServe: boolean
 }
 
 /**
@@ -30,26 +32,32 @@ export const catalog = [
   {
     description: 'Read public chain data: tokens, transactions, transfers, blocks, and receipts.',
     scope: 'data:read',
+    selfServe: true,
   },
   {
     description: 'Run ad-hoc queries against the raw indexer passthrough.',
     scope: 'indexer:query',
+    selfServe: true,
   },
   {
     description: 'Fill and submit transactions through the relay.',
     scope: 'rpc-relay:read',
+    selfServe: true,
   },
   {
     description: 'Sponsor transaction fees through the relay as the managed fee payer.',
     scope: 'rpc-relay:sponsor',
+    selfServe: true,
   },
   {
     description: 'Read webhook subscriptions.',
     scope: 'webhooks:read',
+    selfServe: false,
   },
   {
     description: 'Create, update, and delete webhook subscriptions.',
     scope: 'webhooks:write',
+    selfServe: false,
   },
 ] as const satisfies readonly Entry[]
 
@@ -57,7 +65,12 @@ export const catalog = [
 export type Id = (typeof catalog)[number]['scope']
 
 /**
- * Scopes a session may self-mint through the developer platform. Empty: every
- * scope requires super admin issuance.
+ * Scopes a session may self-mint through the developer platform, derived from
+ * the catalog's `selfServe` flag. Paid usage (mainnet sponsorship) is gated by
+ * an active billing source at request time, so self-serve users cannot consume
+ * paid APIs for free. Webhooks stay super-admin-only, as does {@link wildcard}
+ * (intentionally absent from the catalog).
  */
-export const selfServe: readonly Id[] = []
+export const selfServe: readonly Id[] = catalog
+  .filter((entry) => entry.selfServe)
+  .map((entry) => entry.scope)

package/src/admin/apps/scopes.test.ts

@@ -17,26 +17,32 @@ describe('GET /scopes', () => {
           {
             "description": "Read public chain data: tokens, transactions, transfers, blocks, and receipts.",
             "scope": "data:read",
+            "selfServe": true,
           },
           {
             "description": "Run ad-hoc queries against the raw indexer passthrough.",
             "scope": "indexer:query",
+            "selfServe": true,
           },
           {
             "description": "Fill and submit transactions through the relay.",
             "scope": "rpc-relay:read",
+            "selfServe": true,
           },
           {
             "description": "Sponsor transaction fees through the relay as the managed fee payer.",
             "scope": "rpc-relay:sponsor",
+            "selfServe": true,
           },
           {
             "description": "Read webhook subscriptions.",
             "scope": "webhooks:read",
+            "selfServe": false,
           },
           {
             "description": "Create, update, and delete webhook subscriptions.",
             "scope": "webhooks:write",
+            "selfServe": false,
           },
         ],
       }

package/src/admin/apps/scopes.ts

@@ -18,6 +18,9 @@ export namespace schema {
         scope: z
           .string()
           .check(z.describe('Scope identifier used in API-key grants and route policies.')),
+        selfServe: z
+          .boolean()
+          .check(z.describe('Whether a session may self-mint this scope (else super-admin-only).')),
       })
       .check(z.describe('A single issuable API-key scope.'))
 

package/src/admin/ui/src/components/Page.tsx

@@ -1,4 +1,5 @@
 import type { ReactNode } from 'react'
+import { cx } from 'regen-ui'
 
 import { MobileProfile } from './MobileProfile'
 
@@ -37,9 +38,7 @@ export function Page(props: {
 /** Bordered surface container used for lists and forms. */
 export function Card(props: { children: ReactNode; className?: string }) {
   return (
-    <div className={`border border-border bg-surface ${props.className ?? ''}`}>
-      {props.children}
-    </div>
+    <div className={cx('border border-border bg-surface', props.className)}>{props.children}</div>
   )
 }
 

package/src/admin/ui/src/routes/__root.tsx

@@ -207,12 +207,12 @@ function MobileNav() {
 
 function SignInRequired({ loginUrl }: { loginUrl?: string }) {
   return (
-    <div className="flex min-h-screen flex-col items-center justify-center gap-3 bg-background text-foreground">
+    <div className="flex min-h-dvh flex-col items-center justify-center gap-3 bg-background text-foreground">
       <p className="font-medium">Sign in required</p>
       {loginUrl ? (
         <Button render={<a href={loginUrl} />}>Sign in</Button>
       ) : (
-        <p className="text-sm text-foreground-secondary">Your session has expired.</p>
+        <p className="text-copy-14 text-foreground-secondary">Your session has expired.</p>
       )}
     </div>
   )

package/src/admin/ui/src/routes/api-keys.tsx

@@ -1,6 +1,6 @@
 import { createFileRoute } from '@tanstack/react-router'
 import { type ReactNode, useState } from 'react'
-import { Button, Fields, Input, Rows, Select, useCopy } from 'regen-ui'
+import { Button, cx, Fields, Input, Rows, Select, useCopy } from 'regen-ui'
 import { Check, ChevronRight, Copy as CopyIcon, Plus, Trash2, X } from 'lucide-react'
 
 import { Card, Notice, Page } from '../components/Page'
@@ -313,7 +313,7 @@ function KeyRow(props: { record: ApiKeys.ApiKey }) {
 
 function Detail(props: { children: ReactNode; className?: string; label: ReactNode }) {
   return (
-    <div className={`flex min-w-0 flex-col gap-1 ${props.className ?? ''}`}>
+    <div className={cx('flex min-w-0 flex-col gap-1', props.className)}>
       <dt className="text-label-12 text-foreground-secondary">{props.label}</dt>
       <dd className="min-w-0 text-label-13 text-foreground">{props.children}</dd>
     </div>