tapimo 0.0.2 → 0.2.0

package/src/internal/Cursor.test.ts

@@ -90,11 +90,12 @@ describe('Cursor', () => {
   })
 
   test('falls back to an OR expansion for a mixed-direction keyset', () => {
+    const holder = `'0x${'ab'.repeat(20)}'`
     expect(
       Cursor.keyset([
         { literal: '1000', name: 'balance', order: 'desc' },
-        { literal: "'0xabc'", name: 'holder', order: 'asc' },
+        { literal: holder, name: 'holder', order: 'asc' },
       ]),
-    ).toBe("(balance <= 1000 AND ((balance < 1000) OR (balance = 1000 AND holder > '0xabc')))")
+    ).toBe(`(balance <= 1000 AND ((balance < 1000) OR (balance = 1000 AND holder > ${holder})))`)
   })
 })

package/src/internal/Log.test.ts

@@ -92,7 +92,7 @@ describe('middleware', () => {
     api.use('*', async (c, next) => {
       c.set('principal', {
         id: 'ip:203.0.113.7',
-        payment: { payer: '0xpayer', reason: 'public_over_quota', type: 'mpp' },
+        payment: { payer: `0x${'aa'.repeat(20)}`, reason: 'public_over_quota', type: 'mpp' },
         type: 'public',
       })
       await next()

package/src/internal/Log.ts

@@ -42,17 +42,21 @@ export type Entry = {
   path: string
   /** MPP payment reason when the request was paid per call. */
   payment?: Auth.Payment['reason'] | undefined
-  /** Caller identity. Raw API-key tokens are never logged. */
+  /** Caller identity. Raw API-key tokens and the super admin secret are never logged. */
   principal?:
     | {
+        /** Attributed super admin identity for super admin callers. */
+        actor?: string | undefined
         /** Key environment for API-key callers. */
         environment?: ApiKey.ApiKey['environment'] | undefined
-        /** Principal id: the API key id, or the public quota identity. */
+        /** Principal id: the API key id, the public quota identity, the user id, or `super_admin`. */
         id: string
         /** Owning organization id for API-key callers. */
         orgId?: string | undefined
+        /** Owning project id for project-attributed API-key callers. */
+        projectId?: string | undefined
         /** Principal kind. */
-        type: 'api_key' | 'public'
+        type: 'api_key' | 'public' | 'session' | 'super_admin'
       }
     | undefined
   /** Raw query string (no leading `?`) with API-key tokens redacted, when present. */
@@ -146,9 +150,13 @@ export function middleware<environment extends Environment = Environment>(
         ? {}
         : {
             principal: {
+              ...(principal.type === 'super_admin' ? { actor: principal.actor } : {}),
               ...(principal.type === 'api_key' ? { environment: principal.environment } : {}),
               id: principal.id,
               ...(principal.type === 'api_key' ? { orgId: principal.orgId } : {}),
+              ...(principal.type === 'api_key' && principal.projectId !== undefined
+                ? { projectId: principal.projectId }
+                : {}),
               type: principal.type,
             },
           }),

package/src/internal/MetricSink.ts

@@ -60,7 +60,7 @@ type RouteTags = {
   cache: 'hit' | 'miss'
   method: string
   principal_environment: 'none' | 'production' | 'sandbox'
-  principal_type: 'api_key' | 'public' | 'unknown'
+  principal_type: 'api_key' | 'public' | 'session' | 'super_admin' | 'unknown'
   route: string
 }
 

package/src/internal/OpenApi.ts

@@ -2,7 +2,6 @@ import type { Context, Env, MiddlewareHandler, ValidationTargets } from 'hono'
 import type { HasRequiredKeys } from 'hono/utils/types'
 import { resolver, type ResponsesWithResolver, validator } from 'hono-openapi'
 import * as z from 'zod/mini'
-import { pilatFontFaces } from './OpenApi.fonts.js'
 import * as Response from './Response.js'
 import * as Schema from './Schema.js'
 
@@ -50,64 +49,6 @@ export {
   validator,
 } from 'hono-openapi'
 
-// Theme-aware Tempo API wordmark for the docs header (`vocs.logoUrl`), inlined
-// as SVG data URIs. See {@link file://./OpenApi.logo.ts}.
-export { logoUrl } from './OpenApi.logo.js'
-
-/**
- * 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}).
- */
-export 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;
-}`
-
 /**
  * Standard machine-readable `error.code` values per status, shared API-wide.
  * The reference enumerates `error.code` to these so generated clients narrow it

package/src/internal/RateLimit.test.ts

@@ -1,4 +1,4 @@
-import { RateLimit, Store } from 'cadent'
+import { RateLimit, Store } from 'tapimo'
 
 describe('memory', () => {
   test('tracks fixed-window quota in a store', async () => {

package/src/internal/RpcSchema.ts

@@ -0,0 +1,10 @@
+import type { RpcSchema } from 'ox'
+
+/**
+ * Ox-compatible JSON-RPC schema union used to type the relay handler's incoming
+ * requests (`RpcRequest.RpcRequest<Ox>`). The relay switches on `request.method`
+ * string literals and casts params per method, so a permissive schema whose
+ * `params` is an array is sufficient — the full method-by-method schema union
+ * from the accounts SDK is not needed here.
+ */
+export type Ox = RpcSchema.Generic<string, readonly unknown[]>

package/src/internal/Store.test.ts

@@ -1,4 +1,4 @@
-import { Store } from 'cadent'
+import { Store } from 'tapimo'
 
 describe('from', () => {
   const ops = {
@@ -68,7 +68,89 @@ describe('increment', () => {
   })
 })
 
+describe('update', () => {
+  test('falls back to a get + put read-modify-write without a native swap', async () => {
+    const cells = new Map<string, string>()
+    const store = Store.from({
+      async delete(key) {
+        cells.delete(key)
+      },
+      async get(key) {
+        return cells.get(key) ?? null
+      },
+      async list() {
+        return { keys: [] }
+      },
+      async put(key, value) {
+        cells.set(key, value)
+      },
+    })
+
+    expect(await Store.update(store, 'value', (current) => `${current ?? 'start'}+`)).toMatchInlineSnapshot(`"start+"`) // prettier-ignore
+    expect(await Store.update(store, 'value', (current) => `${current}+`)).toMatchInlineSnapshot(`"start++"`) // prettier-ignore
+  })
+
+  test('retries the transform when the compare-and-swap loses', async () => {
+    const store = Store.memory()
+    await store.put('value', 'a')
+
+    // Interleave a competing write between the read and the swap once.
+    let raced = false
+    const get = store.get.bind(store)
+    store.get = async (key) => {
+      const current = await get(key)
+      if (!raced) {
+        raced = true
+        await store.put('value', 'b')
+      }
+      return current
+    }
+
+    const transforms: (null | string)[] = []
+    const written = await Store.update(store, 'value', (current) => {
+      transforms.push(current)
+      return `${current}c`
+    })
+
+    expect(written).toMatchInlineSnapshot(`"bc"`)
+    expect(transforms).toMatchInlineSnapshot(`
+      [
+        "a",
+        "b",
+      ]
+    `)
+  })
+
+  test('fails after exhausting compare-and-swap attempts', async () => {
+    const store = Store.memory()
+    await store.put('value', 'a')
+
+    // Every read is immediately invalidated by a competing write.
+    const get = store.get.bind(store)
+    store.get = async (key) => {
+      const current = await get(key)
+      await store.put('value', `${current}!`)
+      return current
+    }
+
+    await expect(
+      Store.update(store, 'value', (current) => `${current}c`, { attempts: 2 }),
+    ).rejects.toThrowErrorMatchingInlineSnapshot(
+      `[Store.UpdateContentionError: Store update on "value" lost 2 compare-and-swap attempts.]`,
+    )
+  })
+})
+
 describe('memory', () => {
+  test('swaps atomically against the expected value', async () => {
+    const store = Store.memory()
+
+    expect(await store.swap!('value', null, 'first')).toMatchInlineSnapshot(`true`)
+    expect(await store.swap!('value', null, 'clobber')).toMatchInlineSnapshot(`false`)
+    expect(await store.swap!('value', 'first', 'second')).toMatchInlineSnapshot(`true`)
+    expect(await store.get('value')).toMatchInlineSnapshot(`"second"`)
+  })
+
   test('treats expired entries as absent', async () => {
     const store = Store.memory()
 
@@ -148,6 +230,8 @@ describe('cloudflareKv', () => {
             .filter((key) => !options.prefix || key.startsWith(options.prefix))
             .sort()
             .map((name) => ({ name })),
+          list_complete: true,
+          cursor: '',
         }
       },
       async put(key, value, options) {
@@ -190,9 +274,69 @@ describe('cloudflareKv', () => {
       `[RangeError: Cloudflare KV expirationTtl must be at least 60 seconds]`,
     )
   })
+
+  test('lists every Cloudflare Workers KV page', async () => {
+    const calls: unknown[] = []
+    const namespace = {
+      async delete() {},
+      async get() {
+        return null
+      },
+      async list(options = {}) {
+        calls.push(options)
+        if (options.cursor === 'page-2')
+          return {
+            keys: [{ name: 'secret:2' }],
+            list_complete: true,
+            cursor: '',
+          }
+        return {
+          keys: [{ name: 'secret:1' }],
+          list_complete: false,
+          cursor: 'page-2',
+        }
+      },
+      async put() {},
+    } satisfies Store.cloudflareKv.Namespace
+    const store = Store.cloudflareKv(namespace)
+
+    expect(await store.list({ prefix: 'secret:' })).toMatchInlineSnapshot(`
+      {
+        "keys": [
+          {
+            "name": "secret:1",
+          },
+          {
+            "name": "secret:2",
+          },
+        ],
+      }
+    `)
+    expect(calls).toMatchInlineSnapshot(`
+      [
+        {
+          "prefix": "secret:",
+        },
+        {
+          "cursor": "page-2",
+          "prefix": "secret:",
+        },
+      ]
+    `)
+  })
 })
 
 describe('durableObject', () => {
+  // The stub contract requires native `increment` and `swap` (our DO class
+  // implements them); derive them for the in-memory fakes.
+  function stubFor(backing: Store.State): Store.durableObject.Stub {
+    return {
+      ...backing,
+      increment: (key, options) => Store.increment(backing, key, options),
+      swap: (key, expected, next, options) => backing.swap!(key, expected, next, options),
+    }
+  }
+
   test('adapts a Durable Object namespace without caching stubs', async () => {
     const calls: string[] = []
     const backing = Store.memory({
@@ -201,12 +345,7 @@ describe('durableObject', () => {
     const namespace = {
       getByName(name) {
         calls.push(name)
-        // The stub contract requires a native `increment` (our DO class
-        // implements it); derive one for the in-memory fake.
-        return {
-          ...backing,
-          increment: (key, options) => Store.increment(backing, key, options),
-        }
+        return stubFor(backing)
       },
     } satisfies Store.durableObject.Namespace
     const store = Store.durableObject(namespace, { name: 'tempo-api' })
@@ -250,6 +389,7 @@ describe('durableObject', () => {
           increment: (key, options) => Store.increment(backing, key, options),
           list: (options) => backing.list(options),
           put: (key, value, options) => backing.put(key, value, options),
+          swap: (key, expected, next, options) => backing.swap!(key, expected, next, options),
         } satisfies Store.durableObject.Stub
         return new Proxy(stub, {
           get(target, method: string) {
@@ -294,7 +434,7 @@ describe('durableObject', () => {
       getByName() {
         stubs += 1
         return {
-          ...backing,
+          ...stubFor(backing),
           increment: (key, options) => {
             if (failures > 0) {
               failures -= 1
@@ -317,7 +457,7 @@ describe('durableObject', () => {
     const namespace = {
       getByName() {
         return {
-          ...Store.memory(),
+          ...stubFor(Store.memory()),
           increment: () => {
             attempts += 1
             throw Object.assign(new Error('Network connection lost.'), { retryable: true })
@@ -339,7 +479,7 @@ describe('durableObject', () => {
       ({
         getByName() {
           return {
-            ...Store.memory(),
+            ...stubFor(Store.memory()),
             increment: () => {
               attempts += 1
               throw error

package/src/internal/Store.ts

@@ -1,3 +1,5 @@
+import { Json } from 'ox'
+
 /** Minimal string store contract used by Tempo API internals. */
 export type Store = {
   /** Deletes a key. */
@@ -26,6 +28,22 @@ export type Store = {
   }>
   /** Writes a string value, optionally with a time-to-live. */
   put(key: string, value: string, options?: Store.PutOptions): Promise<void>
+  /**
+   * Optional atomic compare-and-swap: writes `next` only when the current
+   * value equals `expected` (`null` = only-if-absent) and reports whether the
+   * write happened. Implement when the backend can execute the compare and
+   * write in one place (in-memory, inside a Durable Object); consumers go
+   * through the {@link update} helper, which falls back to a get + put when
+   * this is absent.
+   */
+  swap?:
+    | ((
+        key: string,
+        expected: null | string,
+        next: string,
+        options?: Store.PutOptions,
+      ) => Promise<boolean>)
+    | undefined
   /**
    * Store kind discriminant. `'state'` marks an authoritative, enumerable
    * store ({@link State}); `'cache'` marks a cache (e.g. the Web Cache,
@@ -102,6 +120,50 @@ export async function increment(
   return count
 }
 
+/**
+ * Atomically transforms a value on a store: reads the current value, applies
+ * `fn`, and writes the result, returning the written value.
+ *
+ * Uses the store's native {@link Store.swap} compare-and-swap when implemented,
+ * re-running `fn` on contention (optimistic concurrency, bounded by
+ * `attempts`). Otherwise falls back to a get + put read-modify-write, which
+ * can lose concurrent writes — fine for dev/in-process backends, not for
+ * contended distributed state.
+ */
+export async function update(
+  store: Store,
+  key: string,
+  fn: (current: null | string) => string,
+  options: update.Options = {},
+): Promise<string> {
+  const { attempts = 8, ...put } = options
+
+  if (!store.swap) {
+    const next = fn(await store.get(key))
+    await store.put(key, next, put)
+    return next
+  }
+
+  for (let attempt = 0; attempt < attempts; attempt++) {
+    const current = await store.get(key)
+    const next = fn(current)
+    if (await store.swap(key, current, next, put)) return next
+  }
+  throw new UpdateContentionError(key, attempts)
+}
+
+export declare namespace update {
+  /** Options for {@link update}. */
+  type Options = Store.PutOptions & {
+    /**
+     * Maximum compare-and-swap attempts before failing with
+     * {@link UpdateContentionError}.
+     * @default 8
+     */
+    attempts?: number | undefined
+  }
+}
+
 /** Creates an in-memory store with TTL support. */
 export function memory(options: memory.Options = {}): State {
   // Track value + optional expiration in one cell so `get` can lazily evict
@@ -148,6 +210,14 @@ export function memory(options: memory.Options = {}): State {
       const expiresAt = options.ttl === undefined ? undefined : Date.now() + options.ttl
       cells.set(key, { expiresAt, value })
     },
+    // Native swap: the compare and write are synchronous, so concurrent
+    // consumers cannot interleave between them.
+    async swap(key, expected, next, options = {}) {
+      if ((read(key)?.value ?? null) !== expected) return false
+      const expiresAt = options.ttl === undefined ? undefined : Date.now() + options.ttl
+      cells.set(key, { expiresAt, value: next })
+      return true
+    },
   })
 }
 
@@ -211,10 +281,23 @@ export function cloudflareKv(namespace: cloudflareKv.Namespace): State {
       return namespace.get(key)
     },
     async list(options = {}) {
-      const result = await namespace.list(
-        options.prefix === undefined ? undefined : { prefix: options.prefix },
-      )
-      return { keys: result.keys.map(({ name }) => ({ name })) }
+      const keys: { name: string }[] = []
+      let cursor: string | undefined
+
+      for (;;) {
+        const result = await namespace.list(
+          options.prefix === undefined && cursor === undefined
+            ? undefined
+            : {
+                ...(options.prefix === undefined ? {} : { prefix: options.prefix }),
+                ...(cursor === undefined ? {} : { cursor }),
+              },
+        )
+        keys.push(...result.keys.map(({ name }) => ({ name })))
+        if (result.list_complete) return { keys }
+        if (result.cursor === undefined) throw new Error('Cloudflare KV list is missing a cursor.')
+        cursor = result.cursor
+      }
     },
     async put(key, value, options = {}) {
       const expirationTtl = cloudflareKvExpirationTtl(options.ttl)
@@ -238,13 +321,19 @@ export declare namespace cloudflareKv {
     /** Lists keys. */
     list(options?: {
       /** Restrict results to keys with this prefix. */
-      prefix?: string | null | undefined
+      prefix?: string | undefined
+      /** Continue from a previous page. */
+      cursor?: string | undefined
     }): Promise<{
       /** Matching keys. */
       keys: readonly {
         /** Key name. */
         name: string
       }[]
+      /** Whether every matching key was returned. */
+      list_complete: boolean
+      /** Cursor for the next page. */
+      cursor?: string | undefined
     }>
     /** Writes a text value. */
     put(
@@ -302,6 +391,19 @@ function durableObjectStorage(storage: durableObject.Storage): State {
 
       await storage.put(key, durableObjectValue(value, options))
     },
+    // Native swap: the object is single-threaded and its input gate holds
+    // other events while storage operations are in flight, so the compare and
+    // write cannot interleave with another request.
+    async swap(key, expected, next, options = {}) {
+      const current = (await durableObjectRead(storage, key, await storage.get(key)))?.value ?? null
+      if (current !== expected) return false
+      if (options.ttl !== undefined && options.ttl <= 0) {
+        await storage.delete(key)
+        return true
+      }
+      await storage.put(key, durableObjectValue(next, options))
+      return true
+    },
   })
 }
 
@@ -341,12 +443,20 @@ export declare namespace durableObject {
   /**
    * Minimal Durable Object RPC stub shape used by this adapter — just the store
    * operations (no `type` discriminant, which an RPC stub doesn't carry).
-   * `increment` is required: the stub mirrors the `tapimo/cloudflare`
-   * `DurableObject` class, whose RPC surface implements it.
+   * `increment` and `swap` are required: the stub mirrors the
+   * `tapimo/cloudflare` `DurableObject` class, whose RPC surface implements
+   * them.
    */
-  type Stub = Omit<Store, 'increment' | 'type'> & {
+  type Stub = Omit<Store, 'increment' | 'swap' | 'type'> & {
     /** Atomically increments an integer counter inside the object. */
     increment(key: string, options?: Store.PutOptions): Promise<number>
+    /** Atomically compares-and-swaps a value inside the object. */
+    swap(
+      key: string,
+      expected: null | string,
+      next: string,
+      options?: Store.PutOptions,
+    ): Promise<boolean>
   }
 }
 
@@ -364,7 +474,7 @@ export async function memoize<value>(
   const raw = await store.get(key)
   if (raw) {
     try {
-      return JSON.parse(raw) as value
+      return Json.parse(raw) as value
     } catch {
       // Corrupt entries are treated as misses so the next call refreshes.
     }
@@ -379,7 +489,7 @@ export async function memoize<value>(
   // fetch is still in flight.
   const flight = (async () => {
     const value = await fetch()
-    await store.put(key, JSON.stringify(value), { ttl })
+    await store.put(key, Json.stringify(value), { ttl })
     return value
   })()
   flights.set(key, flight)
@@ -450,6 +560,12 @@ function durableObjectStub(
     async put(key, value, options) {
       await durableObjectRetry(() => stub(key).put(key, value, options))
     },
+    // Native RPC swap: the compare-and-write runs inside the object. A lost
+    // response retried after a successful write compares stale and returns
+    // false, which optimistic callers already handle as contention.
+    async swap(key, expected, next, options) {
+      return durableObjectRetry(() => stub(key).swap(key, expected, next, options))
+    },
   })
 }
 
@@ -482,7 +598,7 @@ function cloudflareKvExpirationTtl(ttl: number | undefined) {
   return seconds
 }
 
-const durableObjectValueType = 'cadent:store:v1'
+const durableObjectValueType = 'tempo-api:store:v1'
 
 type DurableObjectValue = {
   expiresAt?: number | undefined
@@ -524,3 +640,12 @@ function isDurableObjectValue(value: unknown): value is DurableObjectValue {
       typeof value.expiresAt === 'number')
   )
 }
+
+/** Thrown when {@link update} exhausts its compare-and-swap attempts. */
+export class UpdateContentionError extends Error {
+  override name = 'Store.UpdateContentionError'
+
+  constructor(key: string, attempts: number) {
+    super(`Store update on "${key}" lost ${attempts} compare-and-swap attempts.`)
+  }
+}

package/src/internal/Tidx.local.test.ts

@@ -1,6 +1,6 @@
 import * as TestApp from '../../test/App.js'
 import * as Runtime from '../../test/runtime.js'
-import * as Indexer from '../apps/indexer.js'
+import * as Indexer from '../apps/data/routes/indexer.js'
 
 describe('local TIDX runtime', () => {
   test.runIf(Runtime.get().mode === 'localnet')(