tapimo 0.2.0 → 0.3.0

package/src/internal/OpenApi.ts

@@ -89,9 +89,11 @@ export const errorCodes = {
     'webhook_not_found',
     'delivery_not_found',
     'webhooks_not_enabled',
+    'billing_not_found',
   ],
   429: ['rate_limit_exceeded', 'payment_required'],
   500: ['internal_error'],
+  501: ['billing_unconfigured'],
   502: ['upstream_error'],
 } as const satisfies Record<number, readonly [string, ...string[]]>
 
@@ -259,7 +261,11 @@ export function responses<schema extends z.ZodMiniType>(
       content: {
         'application/json': {
           schema: resolver(success.schema, schemaOptions),
-          ...(success.example === undefined ? {} : { example: success.example }),
+          ...(success.examples === undefined
+            ? success.example === undefined
+              ? {}
+              : { example: success.example }
+            : { examples: success.examples }),
         },
       },
       description: success.description,
@@ -275,6 +281,7 @@ export function responses<schema extends z.ZodMiniType>(
     ...(errors?.[415] && { 415: error(415, 'Unsupported media type.') }),
     429: responseRef('RateLimited'),
     500: responseRef('InternalError'),
+    ...(errors?.[501] && { 501: error(501, 'Not implemented.') }),
     502: error(502, 'Upstream data failure.'),
   }
 }
@@ -318,6 +325,8 @@ export declare namespace responses {
           413?: ErrorOverride | undefined
           /** Override for the 415 response. Setting this includes 415 in the map. */
           415?: ErrorOverride | undefined
+          /** Override for the 501 response. Setting this includes 501 in the map. */
+          501?: ErrorOverride | undefined
           /** Override for the 502 response. */
           502?: ErrorOverride | undefined
         }
@@ -328,6 +337,8 @@ export declare namespace responses {
       description: string
       /** Optional full example body rendered for the 200 response. */
       example?: unknown
+      /** Optional named example bodies rendered for the 200 response. */
+      examples?: Record<string, { description?: string; summary?: string; value: unknown }>
       /** Zod schema describing the 200 response body. */
       schema: schema
     }

package/src/internal/RateLimit.test.ts

@@ -91,3 +91,87 @@ describe('memory', () => {
     `)
   })
 })
+
+describe('edge', () => {
+  function binding(success = true) {
+    return { limit: vi.fn(async (_: { key: string }) => ({ success })) }
+  }
+
+  function request(options: { asn?: number | undefined; ip?: string | undefined } = {}) {
+    const value = new Request('https://api.tempo.xyz/v1/health', {
+      headers: options.ip ? { 'cf-connecting-ip': options.ip } : {},
+    })
+    if (options.asn) Object.assign(value, { cf: { asn: options.asn } })
+    return value
+  }
+
+  test('allows when every layer is under quota', async () => {
+    const asn = binding()
+    const global = binding()
+    const ip = binding()
+
+    const response = await RateLimit.edge(request({ asn: 64512, ip: '203.0.113.7' }), {
+      asn,
+      global,
+      ip,
+    })
+
+    expect(response).toBeUndefined()
+    expect(ip.limit).toHaveBeenCalledWith({ key: '203.0.113.7' })
+    expect(asn.limit).toHaveBeenCalledWith({ key: 'asn:64512' })
+    expect(global.limit).toHaveBeenCalledWith({ key: 'global' })
+  })
+
+  test('buckets IPv6 clients by /64 prefix', async () => {
+    const ip = binding()
+
+    await RateLimit.edge(request({ ip: '2001:db8:abcd:12::1' }), { ip })
+
+    expect(ip.limit).toHaveBeenCalledWith({ key: '2001:db8:abcd:12' })
+  })
+
+  test('returns 429 when any layer denies', async () => {
+    const response = await RateLimit.edge(request({ asn: 64512, ip: '203.0.113.7' }), {
+      asn: binding(false),
+      global: binding(),
+      ip: binding(),
+    })
+
+    expect(response?.status).toBe(429)
+    expect(response?.headers.get('retry-after')).toBe('10')
+  })
+
+  test('skips the asn layer when the request has no cf metadata', async () => {
+    const asn = binding(false)
+
+    const response = await RateLimit.edge(request({ ip: '203.0.113.7' }), { asn })
+
+    expect(response).toBeUndefined()
+    expect(asn.limit).not.toHaveBeenCalled()
+  })
+
+  test('keys unknown clients together when the ip header is missing', async () => {
+    const ip = binding()
+
+    await RateLimit.edge(request(), { ip })
+
+    expect(ip.limit).toHaveBeenCalledWith({ key: 'unknown' })
+  })
+
+  test('fails open when a binding errors', async () => {
+    const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {})
+    try {
+      const response = await RateLimit.edge(request({ ip: '203.0.113.7' }), {
+        ip: {
+          limit() {
+            return Promise.reject(new Error('binding unavailable'))
+          },
+        },
+      })
+
+      expect(response).toBeUndefined()
+    } finally {
+      consoleError.mockRestore()
+    }
+  })
+})

package/src/internal/RateLimit.ts

@@ -90,4 +90,74 @@ export declare namespace memory {
   }
 }
 
+/** Cloudflare rate-limit binding (per-colo counters). */
+export type Binding = {
+  /** Consumes one request; `success: false` when the key is over quota. */
+  limit(options: { key: string }): Promise<{ success: boolean }>
+}
+
+/**
+ * Layered edge rate limit over Cloudflare rate-limit bindings. Returns a 429
+ * when any configured layer denies; fails open when a binding errors.
+ */
+export async function edge(request: Request, options: edge.Options): Promise<Response | undefined> {
+  try {
+    const checks: Promise<{ success: boolean }>[] = []
+    if (options.ip) checks.push(options.ip.limit({ key: clientKey(request) }))
+    const asn = (request as Request & { cf?: CfProperties }).cf?.asn
+    if (options.asn && asn !== undefined) checks.push(options.asn.limit({ key: `asn:${asn}` }))
+    if (options.global) checks.push(options.global.limit({ key: 'global' }))
+
+    const results = await Promise.all(checks)
+    if (results.some((result) => !result.success))
+      return new Response('Rate limit exceeded', {
+        headers: { 'retry-after': '10' },
+        status: 429,
+      })
+  } catch (error) {
+    console.error('Edge rate limit check failed:', error)
+  }
+  return undefined
+}
+
+export declare namespace edge {
+  /** Layers applied by {@link edge}; omitted layers are skipped. */
+  type Options = {
+    /** Per-network backstop; catches clients rotating addresses within one ASN. */
+    asn?: Binding | undefined
+    /** Fixed-key circuit breaker capping total throughput per colo. */
+    global?: Binding | undefined
+    /** Per-client limit, keyed by IPv4 address or IPv6 /64 prefix. */
+    ip?: Binding | undefined
+  }
+}
+
+/** Cloudflare-enriched request properties; absent outside Workers (tests, service bindings). */
+type CfProperties = { asn?: number | undefined }
+
+/** IPv4 clients key by address; IPv6 clients by /64 prefix so they cannot rotate within their allocation. */
+function clientKey(request: Request): string {
+  const ip = request.headers.get('cf-connecting-ip')
+  if (!ip) return 'unknown'
+  if (ip.includes('.')) return ip
+  return ipv6Prefix(ip)
+}
+
+/** First four hextets of an IPv6 address, with `::` expanded. */
+function ipv6Prefix(ip: string): string {
+  const [address = ''] = ip.split('%')
+  const [head = '', tail = ''] = address.split('::')
+  const left = head ? head.split(':') : []
+  const right = tail ? tail.split(':') : []
+  const groups = [
+    ...left,
+    ...Array.from({ length: Math.max(8 - left.length - right.length, 0) }, () => '0'),
+    ...right,
+  ]
+  return groups
+    .slice(0, 4)
+    .map((group) => Number.parseInt(group || '0', 16).toString(16))
+    .join(':')
+}
+
 export { type RateLimitStore as Store }

package/src/internal/Response.ts

@@ -96,7 +96,7 @@ export declare namespace error {
   }
 
   /** HTTP status code accepted by the public error helper. */
-  type Status = 400 | 401 | 403 | 404 | 409 | 412 | 413 | 415 | 429 | 500 | 502 | 503
+  type Status = 400 | 401 | 403 | 404 | 409 | 412 | 413 | 415 | 429 | 500 | 501 | 502 | 503
 
   /** Options for creating a JSON error response. */
   type Options<status extends Status = Status, code extends string = string> = {

package/src/internal/Schema.ts

@@ -417,6 +417,14 @@ export const TotalCountCapped = z
     z.meta({ examples: [false] }),
   )
 
+/**
+ * Resource environment (`production`/`sandbox`) query parameter shared across
+ * environment-scoped endpoints. Defaults to `production`.
+ */
+export const Environment = z
+  ._default(z.enum(['production', 'sandbox']), 'production')
+  .check(z.describe('Resource environment.'), z.meta({ examples: ['sandbox'] }))
+
 /** Sort-direction (`asc`/`desc`) query parameter shared across list endpoints. */
 export const Order = z
   ._default(z.enum(['asc', 'desc']), 'desc')

package/src/internal/Webhooks.test.ts

@@ -10,7 +10,7 @@ const fixedNow = () => new Date('2026-01-01T00:00:00.000Z')
 /** Asserts the random id/secret shape, then redacts them for a stable snapshot. */
 function redact(subscription: Webhooks.Subscription | null) {
   expect(subscription).not.toBeNull()
-  expect(subscription?.id).toMatch(/^wh_\d{15}_[A-Za-z0-9_-]{21}$/)
+  expect(subscription?.id).toMatch(/^wh_\d{15}_[A-Za-z0-9]{24}$/)
   expect(subscription?.secret).toMatch(/^whsec_[0-9a-f]{64}$/)
   return { ...subscription, id: '<id>', secret: '<secret>' }
 }
@@ -405,8 +405,8 @@ describe('eventId / buildEnvelope', () => {
 describe('delivery log', () => {
   /** Asserts the time-sortable delivery id shape and redacts non-deterministic fields. */
   function redactDelivery(delivery: Webhooks.Delivery) {
-    expect(delivery.id).toMatch(/^whd_\d{15}_[A-Za-z0-9_-]{21}$/)
-    expect(delivery.subscriptionId).toMatch(/^wh_\d{15}_[A-Za-z0-9_-]{21}$/)
+    expect(delivery.id).toMatch(/^whd_\d{15}_[A-Za-z0-9]{24}$/)
+    expect(delivery.subscriptionId).toMatch(/^wh_\d{15}_[A-Za-z0-9]{24}$/)
     return {
       ...delivery,
       envelope: { ...delivery.envelope, subscriptionId: '<subscriptionId>' },

package/src/internal/Webhooks.ts

@@ -1,4 +1,3 @@
-import { nanoid } from 'nanoid'
 import { Hash, Hex } from 'ox'
 
 import type * as app_Webhooks from '../apps/data/routes/webhooks.js'
@@ -6,6 +5,7 @@ import type * as Db from '../db/Db.js'
 import * as WebhookDeliveries from '../db/tables/webhookDeliveries.js'
 import * as WebhookSubscriptions from '../db/tables/webhookSubscriptions.js'
 import type * as Metrics from '../Metrics.js'
+import * as Id from './Id.js'
 import * as MetricSink from './MetricSink.js'
 import * as WebhookDestination from './WebhookDestination.js'
 
@@ -758,14 +758,14 @@ function generateId(now: Date): string {
   // (mirroring delivery ids), letting listSubscriptions page newest-first; 15
   // digits leaves headroom well past the year 5138.
   const timestamp = now.getTime().toString().padStart(15, '0')
-  return `wh_${timestamp}_${nanoid()}`
+  return `wh_${timestamp}_${Id.random()}`
 }
 
 function generateDeliveryId(now: Date): string {
   // Zero-pad the epoch-ms so ids sort chronologically by string comparison; 15
   // digits leaves headroom well past the year 5138.
   const timestamp = now.getTime().toString().padStart(15, '0')
-  return `whd_${timestamp}_${nanoid()}`
+  return `whd_${timestamp}_${Id.random()}`
 }
 
 function generateSecret(): string {