@littlebearapps/platform-admin-sdk 1.4.2 → 2.0.0

package/templates/shared/scripts/ops/verify-account-completeness.ts

@@ -0,0 +1,236 @@
+#!/usr/bin/env npx tsx
+/**
+ * Verify Account Completeness Script
+ *
+ * Queries all Cloudflare GraphQL Analytics endpoints to calculate the true
+ * account-wide bill and compare against D1 records for the current month.
+ *
+ * Services audited:
+ *   - Workers (requests + CPU)
+ *   - D1 (rows read/written)
+ *   - R2 (Class A/B operations)
+ *   - KV (reads/writes)
+ *   - Vectorize (queries)
+ *   - Durable Objects (requests)
+ *   - Workers AI (neurons)
+ *
+ * Usage:
+ *   npx tsx scripts/ops/verify-account-completeness.ts
+ *   npx tsx scripts/ops/verify-account-completeness.ts --start 2026-02-01 --end 2026-02-28
+ *
+ * Environment Variables:
+ *   CLOUDFLARE_API_TOKEN  — API token with Analytics:Read permissions
+ *   CLOUDFLARE_ACCOUNT_ID — Your Cloudflare account ID
+ *   D1_DATABASE_ID        — Your platform-metrics D1 database ID
+ */
+
+const GRAPHQL_ENDPOINT = 'https://api.cloudflare.com/client/v4/graphql';
+const REST_API_BASE = 'https://api.cloudflare.com/client/v4';
+
+// Pricing constants (Workers Paid Plan)
+const PRICING = {
+  workers: { includedRequests: 10_000_000, requestCostPerMillion: 0.3, cpuCostPerMillionMs: 0.02 },
+  d1: { includedReads: 25_000_000_000, includedWrites: 50_000_000, readCostPerMillion: 0.001, writeCostPerMillion: 1.0 },
+  kv: { includedReads: 10_000_000, includedWrites: 1_000_000, readCostPerMillion: 0.5, writeCostPerMillion: 5.0 },
+  r2: { includedClassA: 1_000_000, includedClassB: 10_000_000, classACostPerMillion: 4.5, classBCostPerMillion: 0.36 },
+  vectorize: { includedDimensions: 30_000_000, queryCostPerMillionDimensions: 0.01 },
+  durableObjects: { includedRequests: 1_000_000, requestCostPerMillion: 0.15 },
+  workersAI: { neuronCostPer1000: 0.011 },
+};
+
+interface ServiceUsage {
+  name: string;
+  usage: string;
+  includedAllowance: string;
+  billableUsage: string;
+  estimatedCost: number;
+}
+
+// ---------------------------------------------------------------------------
+// GraphQL helper
+// ---------------------------------------------------------------------------
+
+async function queryGraphQL(query: string, variables: Record<string, unknown>): Promise<unknown> {
+  const apiToken = process.env.CLOUDFLARE_API_TOKEN;
+  if (!apiToken) throw new Error('CLOUDFLARE_API_TOKEN required');
+
+  const response = await fetch(GRAPHQL_ENDPOINT, {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${apiToken}`, 'Content-Type': 'application/json' },
+    body: JSON.stringify({ query, variables }),
+  });
+
+  const result = (await response.json()) as { data?: unknown; errors?: Array<{ message: string }> };
+  if (result.errors?.length) throw new Error(`GraphQL error: ${result.errors[0].message}`);
+  return result.data;
+}
+
+// ---------------------------------------------------------------------------
+// Service queries
+// ---------------------------------------------------------------------------
+
+async function getWorkersUsage(accountId: string, startDate: string, endDate: string): Promise<ServiceUsage> {
+  const query = `query($accountTag:String!,$startDate:Date!,$endDate:Date!){viewer{accounts(filter:{accountTag:$accountTag}){workersInvocationsAdaptive(filter:{date_geq:$startDate,date_leq:$endDate},limit:1000){sum{requests,errors}quantiles{cpuTimeP50}}}}}`;
+  const data = (await queryGraphQL(query, { accountTag: accountId, startDate, endDate })) as Record<string, unknown>;
+  const results = ((data as { viewer: { accounts: Array<{ workersInvocationsAdaptive: Array<{ sum: { requests: number }; quantiles: { cpuTimeP50: number } }> }> } }).viewer.accounts[0]?.workersInvocationsAdaptive) ?? [];
+  let totalRequests = 0;
+  let totalCpuMs = 0;
+  for (const row of results) {
+    totalRequests += row.sum.requests;
+    totalCpuMs += row.sum.requests * row.quantiles.cpuTimeP50;
+  }
+  const billable = Math.max(0, totalRequests - PRICING.workers.includedRequests);
+  const cost = (billable / 1_000_000) * PRICING.workers.requestCostPerMillion + (totalCpuMs / 1_000_000) * PRICING.workers.cpuCostPerMillionMs;
+  return { name: 'Workers', usage: `${(totalRequests / 1_000_000).toFixed(2)}M requests`, includedAllowance: '10M requests', billableUsage: `${(billable / 1_000_000).toFixed(2)}M`, estimatedCost: cost };
+}
+
+async function getD1Usage(accountId: string, startDate: string, endDate: string): Promise<ServiceUsage> {
+  const query = `query($accountTag:String!,$startDate:Date!,$endDate:Date!){viewer{accounts(filter:{accountTag:$accountTag}){d1AnalyticsAdaptiveGroups(filter:{date_geq:$startDate,date_leq:$endDate},limit:1000){sum{rowsRead,rowsWritten}}}}}`;
+  const data = (await queryGraphQL(query, { accountTag: accountId, startDate, endDate })) as Record<string, unknown>;
+  const results = ((data as { viewer: { accounts: Array<{ d1AnalyticsAdaptiveGroups: Array<{ sum: { rowsRead: number; rowsWritten: number } }> }> } }).viewer.accounts[0]?.d1AnalyticsAdaptiveGroups) ?? [];
+  let totalReads = 0, totalWrites = 0;
+  for (const row of results) { totalReads += row.sum.rowsRead; totalWrites += row.sum.rowsWritten; }
+  const billReads = Math.max(0, totalReads - PRICING.d1.includedReads);
+  const billWrites = Math.max(0, totalWrites - PRICING.d1.includedWrites);
+  const cost = (billReads / 1_000_000) * PRICING.d1.readCostPerMillion + (billWrites / 1_000_000) * PRICING.d1.writeCostPerMillion;
+  return { name: 'D1', usage: `${(totalWrites / 1_000_000).toFixed(1)}M writes, ${(totalReads / 1_000_000_000).toFixed(3)}B reads`, includedAllowance: '50M writes, 25B reads', billableUsage: `${(billWrites / 1_000_000).toFixed(1)}M writes`, estimatedCost: cost };
+}
+
+async function getKVUsage(accountId: string, startDate: string, endDate: string): Promise<ServiceUsage> {
+  const query = `query($accountTag:String!,$startDate:Date!,$endDate:Date!){viewer{accounts(filter:{accountTag:$accountTag}){kvOperationsAdaptiveGroups(filter:{date_geq:$startDate,date_leq:$endDate},limit:1000){sum{requests}dimensions{actionType}}}}}`;
+  const data = (await queryGraphQL(query, { accountTag: accountId, startDate, endDate })) as Record<string, unknown>;
+  const results = ((data as { viewer: { accounts: Array<{ kvOperationsAdaptiveGroups: Array<{ sum: { requests: number }; dimensions: { actionType: string } }> }> } }).viewer.accounts[0]?.kvOperationsAdaptiveGroups) ?? [];
+  let reads = 0, writes = 0;
+  for (const row of results) {
+    const action = row.dimensions.actionType.toLowerCase();
+    if (action === 'read' || action === 'get') reads += row.sum.requests;
+    else if (action === 'write' || action === 'put') writes += row.sum.requests;
+  }
+  const billReads = Math.max(0, reads - PRICING.kv.includedReads);
+  const cost = (billReads / 1_000_000) * PRICING.kv.readCostPerMillion + (Math.max(0, writes - PRICING.kv.includedWrites) / 1_000_000) * PRICING.kv.writeCostPerMillion;
+  return { name: 'KV', usage: `${(reads / 1_000_000).toFixed(2)}M reads, ${(writes / 1_000).toFixed(1)}K writes`, includedAllowance: '10M reads, 1M writes', billableUsage: `${(billReads / 1_000_000).toFixed(2)}M reads`, estimatedCost: cost };
+}
+
+async function getR2Usage(accountId: string, startDate: string, endDate: string): Promise<ServiceUsage> {
+  const query = `query($accountTag:String!,$startDate:Date!,$endDate:Date!){viewer{accounts(filter:{accountTag:$accountTag}){r2OperationsAdaptiveGroups(filter:{date_geq:$startDate,date_leq:$endDate},limit:1000){sum{requests}dimensions{actionType}}}}}`;
+  const data = (await queryGraphQL(query, { accountTag: accountId, startDate, endDate })) as Record<string, unknown>;
+  const results = ((data as { viewer: { accounts: Array<{ r2OperationsAdaptiveGroups: Array<{ sum: { requests: number }; dimensions: { actionType: string } }> }> } }).viewer.accounts[0]?.r2OperationsAdaptiveGroups) ?? [];
+  const classBActions = new Set(['GetObject', 'HeadObject', 'HeadBucket']);
+  let classA = 0, classB = 0;
+  for (const row of results) {
+    if (classBActions.has(row.dimensions.actionType)) classB += row.sum.requests;
+    else classA += row.sum.requests;
+  }
+  const billA = Math.max(0, classA - PRICING.r2.includedClassA);
+  const billB = Math.max(0, classB - PRICING.r2.includedClassB);
+  const cost = (billA / 1_000_000) * PRICING.r2.classACostPerMillion + (billB / 1_000_000) * PRICING.r2.classBCostPerMillion;
+  return { name: 'R2', usage: `${(classA / 1_000).toFixed(1)}K A, ${(classB / 1_000).toFixed(1)}K B`, includedAllowance: '1M A, 10M B', billableUsage: `${billA.toLocaleString()} A`, estimatedCost: cost };
+}
+
+// ---------------------------------------------------------------------------
+// D1 comparison
+// ---------------------------------------------------------------------------
+
+async function getD1RecordTotal(
+  accountId: string,
+  apiToken: string,
+  databaseId: string,
+  startDate: string,
+  endDate: string
+): Promise<number> {
+  const sql = `SELECT SUM(total_cost_usd) as total FROM daily_usage_rollups WHERE snapshot_date BETWEEN '${startDate}' AND '${endDate}'`;
+  const url = `${REST_API_BASE}/accounts/${accountId}/d1/database/${databaseId}/query`;
+  const response = await fetch(url, {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${apiToken}`, 'Content-Type': 'application/json' },
+    body: JSON.stringify({ sql }),
+  });
+  if (!response.ok) return 0;
+  const data = (await response.json()) as { result?: Array<{ results?: Array<{ total: number }> }> };
+  return data?.result?.[0]?.results?.[0]?.total ?? 0;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main(): Promise<void> {
+  const apiToken = process.env.CLOUDFLARE_API_TOKEN;
+  const accountId = process.env.CLOUDFLARE_ACCOUNT_ID;
+  const databaseId = process.env.D1_DATABASE_ID;
+
+  if (!apiToken || !accountId || !databaseId) {
+    console.error('Error: Required environment variables: CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID, D1_DATABASE_ID');
+    process.exit(1);
+  }
+
+  // Parse date range
+  const args = process.argv.slice(2);
+  const now = new Date();
+  let startDate = `${now.getUTCFullYear()}-${String(now.getUTCMonth() + 1).padStart(2, '0')}-01`;
+  let endDate = now.toISOString().split('T')[0];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--start' && args[i + 1]) startDate = args[++i];
+    else if (args[i] === '--end' && args[i + 1]) endDate = args[++i];
+  }
+
+  console.log('='.repeat(80));
+  console.log(`ACCOUNT COMPLETENESS AUDIT (${startDate} to ${endDate})`);
+  console.log('='.repeat(80));
+  console.log('');
+
+  const services: ServiceUsage[] = [];
+
+  console.log('Querying Cloudflare GraphQL…');
+  for (const [name, fn] of [
+    ['Workers', () => getWorkersUsage(accountId, startDate, endDate)],
+    ['D1', () => getD1Usage(accountId, startDate, endDate)],
+    ['KV', () => getKVUsage(accountId, startDate, endDate)],
+    ['R2', () => getR2Usage(accountId, startDate, endDate)],
+  ] as const) {
+    console.log(`  ${name}…`);
+    services.push(await fn());
+  }
+
+  console.log('');
+  console.log('Service          | Usage                           | Billable               | Est. Cost');
+  console.log('-'.repeat(80));
+
+  let totalCF = 0;
+  for (const svc of services) {
+    totalCF += svc.estimatedCost;
+    console.log(`${svc.name.padEnd(16)} | ${svc.usage.padEnd(31)} | ${svc.billableUsage.padEnd(22)} | $${svc.estimatedCost.toFixed(2).padStart(8)}`);
+  }
+  console.log('-'.repeat(80));
+  console.log(`${'CF TOTAL'.padEnd(16)} | ${' '.repeat(31)} | ${' '.repeat(22)} | $${totalCF.toFixed(2).padStart(8)}`);
+  console.log('');
+
+  // Compare against D1
+  console.log('Querying D1 records…');
+  const d1Total = await getD1RecordTotal(accountId, apiToken, databaseId, startDate, endDate);
+
+  console.log('');
+  console.log('-'.repeat(80));
+  console.log('COMPARISON');
+  console.log('-'.repeat(80));
+  console.log(`  Cloudflare Calculated: $${totalCF.toFixed(2)}`);
+  console.log(`  Our D1 Records:       $${d1Total.toFixed(2)}`);
+  console.log(`  Variance:             $${(totalCF - d1Total).toFixed(2)}`);
+  console.log('');
+
+  const variance = Math.abs(totalCF - d1Total);
+  const variancePct = (variance / Math.max(totalCF, d1Total, 0.01)) * 100;
+
+  if (variancePct < 5) {
+    console.log(`VERDICT: ACCURATE (${variancePct.toFixed(1)}% variance — within acceptable margin)`);
+  } else if (d1Total > totalCF) {
+    console.log(`VERDICT: OVER-RECORDED (D1 records exceed Cloudflare by $${(d1Total - totalCF).toFixed(2)})`);
+  } else {
+    console.log(`VERDICT: MISSING DATA (Cloudflare exceeds D1 by $${(totalCF - d1Total).toFixed(2)})`);
+  }
+}
+
+main().catch((error) => {
+  console.error('Fatal error:', error);
+  process.exit(1);
+});

package/templates/shared/scripts/validate-schemas.js

@@ -0,0 +1,61 @@
+/**
+ * JSON Schema Validation Script
+ *
+ * Validates all JSON schemas in contracts/schemas/ are syntactically correct
+ * using the Ajv JSON Schema validator.
+ *
+ * Usage:
+ *   node scripts/validate-schemas.js
+ *   npm run validate:schemas
+ *
+ * Prerequisites:
+ *   npm install ajv ajv-formats --save-dev
+ */
+
+import Ajv from 'ajv';
+import addFormats from 'ajv-formats';
+import { readFileSync, readdirSync } from 'fs';
+import { join } from 'path';
+
+const ajv = new Ajv({ allErrors: true, strict: true });
+addFormats(ajv);
+
+const schemasDir = join(process.cwd(), 'contracts', 'schemas');
+
+let schemaFiles;
+try {
+  schemaFiles = readdirSync(schemasDir).filter((file) => file.endsWith('.schema.json'));
+} catch {
+  console.error(`No schemas directory found at ${schemasDir}`);
+  console.error('Create contracts/schemas/ with your JSON schema files.');
+  process.exit(1);
+}
+
+if (schemaFiles.length === 0) {
+  console.log('No schema files found in contracts/schemas/');
+  process.exit(0);
+}
+
+let allValid = true;
+
+for (const file of schemaFiles) {
+  const path = join(schemasDir, file);
+  const schema = JSON.parse(readFileSync(path, 'utf-8'));
+
+  try {
+    ajv.compile(schema);
+    console.log(`  PASS  ${file}`);
+  } catch (error) {
+    console.error(`  FAIL  ${file}: ${error.message}`);
+    allValid = false;
+  }
+}
+
+console.log('');
+if (allValid) {
+  console.log(`All ${schemaFiles.length} schemas are valid.`);
+  process.exit(0);
+}
+
+console.error('Some schemas are invalid.');
+process.exit(1);

package/templates/shared/tests/contract/validate-schemas.test.ts

@@ -0,0 +1,130 @@
+/**
+ * Contract Tests for JSON Schemas
+ *
+ * Validates telemetry envelope + error report schemas against fixtures.
+ * Ensures contracts remain valid as schemas evolve.
+ */
+
+import { describe, expect, it } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+function loadJson(relativePath: string): unknown {
+  const fullPath = resolve(__dirname, '..', '..', relativePath);
+  return JSON.parse(readFileSync(fullPath, 'utf-8'));
+}
+
+// ===========================================================================
+// Envelope Schema
+// ===========================================================================
+
+describe('telemetry envelope schema', () => {
+  const schema = loadJson('contracts/schemas/envelope.v1.schema.json') as {
+    required?: string[];
+    properties?: Record<string, unknown>;
+  };
+
+  it('has required version 1 schema structure', () => {
+    expect(schema).toBeDefined();
+    expect(schema.required).toBeDefined();
+    expect(Array.isArray(schema.required)).toBe(true);
+  });
+
+  it('requires core fields', () => {
+    const required = schema.required ?? [];
+    expect(required).toContain('version');
+    expect(required).toContain('project');
+    expect(required).toContain('feature');
+  });
+
+  it('defines resource_usage properties', () => {
+    const props = schema.properties ?? {};
+    expect(props.resource_usage).toBeDefined();
+  });
+});
+
+// ===========================================================================
+// Valid Fixture
+// ===========================================================================
+
+describe('valid telemetry envelope fixture', () => {
+  const fixture = loadJson('tests/fixtures/telemetry-envelope-valid.json') as Record<string, unknown>;
+
+  it('has version 1', () => {
+    expect(fixture.version).toBe(1);
+  });
+
+  it('has valid project and feature format', () => {
+    expect(typeof fixture.project).toBe('string');
+    expect(typeof fixture.feature).toBe('string');
+    const feature = fixture.feature as string;
+    expect(feature.split(':').length).toBeGreaterThanOrEqual(3);
+  });
+
+  it('has resource_usage with numeric values', () => {
+    const usage = fixture.resource_usage as Record<string, unknown>;
+    expect(usage).toBeDefined();
+    expect(typeof usage.d1_reads).toBe('number');
+    expect(typeof usage.d1_writes).toBe('number');
+    expect(usage.d1_reads).toBeGreaterThanOrEqual(0);
+    expect(usage.d1_writes).toBeGreaterThanOrEqual(0);
+  });
+
+  it('has valid handler_type', () => {
+    expect(['fetch', 'scheduled', 'queue', 'alarm', 'tail']).toContain(fixture.handler_type);
+  });
+
+  it('has valid outcome', () => {
+    expect(['ok', 'error', 'exception', 'canceled']).toContain(fixture.outcome);
+  });
+});
+
+// ===========================================================================
+// Invalid Fixture
+// ===========================================================================
+
+describe('invalid telemetry envelope fixture', () => {
+  const fixture = loadJson('tests/fixtures/telemetry-envelope-invalid.json') as Record<string, unknown>;
+
+  it('has wrong version', () => {
+    expect(fixture.version).not.toBe(1);
+  });
+
+  it('has empty project', () => {
+    expect(fixture.project).toBe('');
+  });
+
+  it('has malformed feature ID (missing colons)', () => {
+    const feature = fixture.feature as string;
+    expect(feature.split(':').length).toBeLessThan(3);
+  });
+
+  it('has invalid resource_usage values', () => {
+    const usage = fixture.resource_usage as Record<string, unknown>;
+    const hasInvalid = Object.values(usage).some(
+      (v) => typeof v !== 'number' || v < 0
+    );
+    expect(hasInvalid).toBe(true);
+  });
+});
+
+// ===========================================================================
+// Error Report Schema
+// ===========================================================================
+
+describe('error report schema', () => {
+  const schema = loadJson('contracts/schemas/error_report.v1.schema.json') as {
+    required?: string[];
+    properties?: Record<string, unknown>;
+  };
+
+  it('has required schema structure', () => {
+    expect(schema).toBeDefined();
+    expect(schema.required).toBeDefined();
+  });
+
+  it('requires error identification fields', () => {
+    const required = schema.required ?? [];
+    expect(required.length).toBeGreaterThan(0);
+  });
+});

package/templates/shared/tests/fixtures/telemetry-envelope-invalid.json

@@ -0,0 +1,9 @@
+{
+  "version": 99,
+  "project": "",
+  "feature": "missing-colon-format",
+  "resource_usage": {
+    "d1_reads": -1,
+    "d1_writes": "not-a-number"
+  }
+}

package/templates/shared/tests/fixtures/telemetry-envelope-valid.json

@@ -0,0 +1,27 @@
+{
+  "version": 1,
+  "timestamp": "2026-03-05T00:00:00Z",
+  "sdk_version": "1.4.0",
+  "project": "test-project",
+  "feature": "test-project:api:endpoint",
+  "handler_type": "fetch",
+  "outcome": "ok",
+  "duration_ms": 42,
+  "resource_usage": {
+    "d1_reads": 10,
+    "d1_writes": 2,
+    "kv_reads": 5,
+    "kv_writes": 1,
+    "r2_reads": 0,
+    "r2_writes": 0,
+    "ai_requests": 0,
+    "vectorize_reads": 0,
+    "queue_messages": 0,
+    "do_requests": 0,
+    "worker_subrequests": 0
+  },
+  "metadata": {
+    "worker_name": "test-worker",
+    "environment": "production"
+  }
+}

package/templates/shared/tests/helpers/mock-d1.ts

@@ -0,0 +1,61 @@
+import { vi } from 'vitest';
+
+interface D1RunResult {
+  success: boolean;
+  results?: unknown[];
+  meta?: Record<string, unknown>;
+}
+
+export class MockD1Database {
+  private runResults: D1RunResult[] = [];
+  private allResults: Array<{ results: unknown[] }> = [];
+  private firstResults: Array<unknown | null> = [];
+  statements: string[] = [];
+  bindings: unknown[][] = [];
+
+  queueRunResult(result: D1RunResult): void {
+    this.runResults.push(result);
+  }
+
+  queueAllResult(results: unknown[]): void {
+    this.allResults.push({ results });
+  }
+
+  queueFirstResult(result: unknown | null): void {
+    this.firstResults.push(result);
+  }
+
+  prepare(sql: string) {
+    this.statements.push(sql);
+    const self = this;
+    let boundValues: unknown[] = [];
+
+    const stmt = {
+      bind(...args: unknown[]) {
+        boundValues = args;
+        self.bindings.push(args);
+        return stmt;
+      },
+      run: vi.fn(async () => {
+        return self.runResults.shift() ?? { success: true, results: [] };
+      }),
+      all: vi.fn(async () => {
+        return self.allResults.shift() ?? { results: [] };
+      }),
+      first: vi.fn(async () => {
+        return self.firstResults.shift() ?? null;
+      }),
+    };
+
+    return stmt;
+  }
+
+  async batch(statements: unknown[]): Promise<D1RunResult[]> {
+    return statements.map(() => this.runResults.shift() ?? { success: true, results: [] });
+  }
+
+  async exec(sql: string): Promise<D1RunResult> {
+    this.statements.push(sql);
+    return { success: true };
+  }
+}

package/templates/shared/tests/helpers/mock-kv.ts

@@ -0,0 +1,37 @@
+import { vi } from 'vitest';
+
+export interface MockKV {
+  get: ReturnType<typeof vi.fn>;
+  put: ReturnType<typeof vi.fn>;
+  delete: ReturnType<typeof vi.fn>;
+  list: ReturnType<typeof vi.fn>;
+  _store: Map<string, string>;
+}
+
+export function createMockKV(initialData: Record<string, string> = {}): MockKV {
+  const store = new Map<string, string>(Object.entries(initialData));
+  return {
+    get: vi.fn((key: string, type?: string) => {
+      const raw = store.get(key) ?? null;
+      if (raw === null) return Promise.resolve(null);
+      if (type === 'json') return Promise.resolve(JSON.parse(raw));
+      return Promise.resolve(raw);
+    }),
+    put: vi.fn((key: string, value: string, _opts?: unknown) => {
+      store.set(key, typeof value === 'string' ? value : JSON.stringify(value));
+      return Promise.resolve();
+    }),
+    delete: vi.fn((key: string) => {
+      store.delete(key);
+      return Promise.resolve();
+    }),
+    list: vi.fn((opts: { prefix?: string; limit?: number } = {}) => {
+      const keys = [...store.keys()]
+        .filter((k) => !opts.prefix || k.startsWith(opts.prefix))
+        .slice(0, opts.limit ?? 1000)
+        .map((name) => ({ name }));
+      return Promise.resolve({ keys, list_complete: true });
+    }),
+    _store: store,
+  };
+}