@kindgi/api 0.0.0-bootstrap.0 → 0.1.0

package/src/routes/conversations.ts

@@ -0,0 +1,369 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import { Hono } from 'hono';
+
+import type {
+  Conversation,
+  ConversationBinding,
+  ConversationId,
+  ConversationMessage,
+  ConversationPageCursor,
+} from '@kindgi/agents';
+import type { RunBinding } from '@kindgi/runtime';
+import type { AgentId, Semver, TenantId } from '@kindgi/types';
+
+import { statusFor, toWireError } from '../errors.js';
+import type { AppEnv } from '../types.js';
+import { clampLimit, decodeCursor, encodeCursor } from './pagination.js';
+
+/**
+ * Conversations resource routes. All storage access goes through the
+ * `ConversationBinding` — the router never touches storage directly.
+ * Messages sort is `sequence asc` (natural conversation reading
+ * order); conversation list sort is `openedAt DESC, id DESC`
+ * (most-recently-opened first).
+ */
+export function conversationsRouter(
+  conversationBinding: ConversationBinding,
+  runBinding: RunBinding,
+): Hono<AppEnv> {
+  const r = new Hono<AppEnv>();
+
+  // ---------- GET / (list, cursor-paginated) ----------
+  r.get('/', async (c) => {
+    const requestId = c.get('requestId');
+    const tenantId = c.get('tenantId') as TenantId;
+    const limit = clampLimit(c.req.query('limit'));
+
+    const statusRaw = c.req.query('status');
+    let statusFilter: 'open' | 'closed' | undefined;
+    if (statusRaw !== undefined && statusRaw.length > 0) {
+      if (statusRaw !== 'open' && statusRaw !== 'closed') {
+        c.status(statusFor('bad-input') as never);
+        return c.json(
+          toWireError(
+            { code: 'bad-input', message: '`status` must be one of: open, closed' },
+            requestId,
+          ),
+        );
+      }
+      statusFilter = statusRaw;
+    }
+
+    const agentIdRaw = c.req.query('agentId');
+
+    let before: ConversationPageCursor | undefined;
+    const rawCursor = c.req.query('cursor');
+    if (rawCursor !== undefined && rawCursor.length > 0) {
+      const decoded = decodeCursor(rawCursor);
+      if (decoded === null) {
+        c.status(statusFor('bad-input') as never);
+        return c.json(
+          toWireError({ code: 'bad-input', message: '`cursor` is malformed' }, requestId),
+        );
+      }
+      before = { openedAt: decoded.createdAt, id: decoded.id as unknown as ConversationId };
+    }
+
+    const listResult = await conversationBinding.listConversationsPage({
+      tenantId,
+      ...(agentIdRaw !== undefined && agentIdRaw.length > 0 && { agentId: agentIdRaw as AgentId }),
+      ...(statusFilter !== undefined && { status: statusFilter }),
+      ...(before !== undefined && { before }),
+      limit,
+    });
+    if (listResult.kind === 'err') {
+      c.status(statusFor(listResult.error.code) as never);
+      return c.json(toWireError(listResult.error as never, requestId));
+    }
+    const { data, hasMore } = listResult.value;
+    const last = data[data.length - 1];
+    const nextCursor =
+      hasMore && last !== undefined
+        ? encodeCursor({
+            createdAt: last.openedAt as unknown as string,
+            id: last.id as unknown as string,
+          })
+        : undefined;
+    return c.json({
+      data: data.map(serializeConversation),
+      hasMore,
+      ...(nextCursor !== undefined && { nextCursor }),
+    });
+  });
+
+  // ---------- GET /:conversationId ----------
+  r.get('/:conversationId', async (c) => {
+    const requestId = c.get('requestId');
+    const tenantId = c.get('tenantId') as TenantId;
+    const conversationId = c.req.param('conversationId') as ConversationId;
+
+    const got = await conversationBinding.getConversation(tenantId, conversationId);
+    if (got.kind === 'err') {
+      c.status(statusFor(got.error.code) as never);
+      return c.json(toWireError(got.error as never, requestId));
+    }
+    return c.json(serializeConversation(got.value));
+  });
+
+  // ---------- POST / (open) ----------
+  r.post('/', async (c) => {
+    const requestId = c.get('requestId');
+    const tenantId = c.get('tenantId') as TenantId;
+
+    let body: unknown;
+    try {
+      body = await c.req.json();
+    } catch {
+      c.status(statusFor('bad-input') as never);
+      return c.json(
+        toWireError({ code: 'bad-input', message: 'Request body must be valid JSON' }, requestId),
+      );
+    }
+    const parsed = parseOpenBody(body);
+    if (parsed.kind === 'err') {
+      c.status(statusFor(parsed.error.code) as never);
+      return c.json(toWireError(parsed.error, requestId));
+    }
+
+    const opened = await conversationBinding.openConversation({
+      tenantId,
+      agentId: parsed.value.agentId,
+      agentVersion: parsed.value.agentVersion,
+      title: parsed.value.title,
+      scope: parsed.value.scope,
+      ...(parsed.value.participantId !== undefined && {
+        participantId: parsed.value.participantId,
+      }),
+      ...(parsed.value.metadata !== undefined && { metadata: parsed.value.metadata }),
+    });
+    if (opened.kind === 'err') {
+      c.status(statusFor(opened.error.code) as never);
+      return c.json(toWireError(opened.error as never, requestId));
+    }
+    c.status(201);
+    return c.json(serializeConversation(opened.value));
+  });
+
+  // ---------- POST /:conversationId/close (idempotent) ----------
+  r.post('/:conversationId/close', async (c) => {
+    const requestId = c.get('requestId');
+    const tenantId = c.get('tenantId') as TenantId;
+    const conversationId = c.req.param('conversationId') as ConversationId;
+
+    const existing = await conversationBinding.getConversation(tenantId, conversationId);
+    if (existing.kind === 'err') {
+      c.status(statusFor(existing.error.code) as never);
+      return c.json(toWireError(existing.error as never, requestId));
+    }
+    // Close is idempotent — closing an already-closed conversation
+    // returns 200 with the current row, no error and no timestamp bump.
+    if (existing.value.closedAt !== undefined) {
+      return c.json(serializeConversation(existing.value));
+    }
+    const closed = await conversationBinding.closeConversation(
+      tenantId,
+      conversationId,
+      runBinding,
+    );
+    if (closed.kind === 'err') {
+      c.status(statusFor(closed.error.code) as never);
+      return c.json(toWireError(closed.error as never, requestId));
+    }
+    return c.json(serializeConversation(closed.value));
+  });
+
+  // ---------- GET /:conversationId/messages (cursor-paginated, sequence asc) ----------
+  r.get('/:conversationId/messages', async (c) => {
+    const requestId = c.get('requestId');
+    const tenantId = c.get('tenantId') as TenantId;
+    const conversationId = c.req.param('conversationId') as ConversationId;
+    const limit = clampLimit(c.req.query('limit'));
+
+    const rawCursor = c.req.query('cursor');
+    let sinceSequence: number | undefined;
+    if (rawCursor !== undefined && rawCursor.length > 0) {
+      const decoded = decodeMessageCursor(rawCursor);
+      if (decoded === null) {
+        c.status(statusFor('bad-input') as never);
+        return c.json(
+          toWireError({ code: 'bad-input', message: '`cursor` is malformed' }, requestId),
+        );
+      }
+      // Advance past the last-seen sequence. `readMessages`' sinceSequence
+      // is inclusive (`>= n`), so bump by one for exclusive resume.
+      sinceSequence = decoded + 1;
+    }
+
+    const result = await conversationBinding.readMessages({
+      tenantId,
+      conversationId,
+      ...(sinceSequence !== undefined && { sinceSequence }),
+      limit: limit + 1,
+    });
+    if (result.kind === 'err') {
+      c.status(statusFor(result.error.code) as never);
+      return c.json(toWireError(result.error as never, requestId));
+    }
+    const all = result.value;
+    const hasMore = all.length > limit;
+    const page = hasMore ? all.slice(0, limit) : all;
+    const last = page[page.length - 1];
+    const nextCursor =
+      hasMore && last !== undefined ? encodeMessageCursor(last.sequence) : undefined;
+    return c.json({
+      data: page.map(serializeMessage),
+      hasMore,
+      ...(nextCursor !== undefined && { nextCursor }),
+    });
+  });
+
+  return r;
+}
+
+// ============ serializers ============
+
+function serializeConversation(c: Conversation): Record<string, unknown> {
+  return {
+    id: c.id as unknown as string,
+    tenantId: c.tenantId as unknown as string,
+    agentId: c.agentId as unknown as string,
+    agentVersion: c.agentVersion as unknown as string,
+    title: c.title,
+    ...(c.participantId !== undefined && { participantId: c.participantId }),
+    scope: c.scope,
+    status: (c.closedAt === undefined ? 'open' : 'closed') as 'open' | 'closed',
+    openedAt: c.openedAt as unknown as string,
+    ...(c.closedAt !== undefined && { closedAt: c.closedAt as unknown as string }),
+    turnCount: c.turnCount,
+    ...(c.lastMessageAt !== undefined && { lastMessageAt: c.lastMessageAt as unknown as string }),
+    ...(c.metadata !== undefined && { metadata: c.metadata }),
+  };
+}
+
+function serializeMessage(m: ConversationMessage): Record<string, unknown> {
+  return {
+    sequence: m.sequence,
+    role: m.role,
+    content: m.content,
+    ...(m.toolCall !== undefined && { toolCall: m.toolCall }),
+    ...(m.actor !== undefined && { actor: m.actor }),
+    createdAt: m.createdAt as unknown as string,
+  };
+}
+
+// ============ cursor helpers ============
+
+function encodeMessageCursor(sequence: number): string {
+  return Buffer.from(JSON.stringify({ sequence }), 'utf8').toString('base64url');
+}
+
+function decodeMessageCursor(raw: string): number | null {
+  try {
+    const json = Buffer.from(raw, 'base64url').toString('utf8');
+    const parsed = JSON.parse(json) as unknown;
+    if (
+      parsed === null ||
+      typeof parsed !== 'object' ||
+      typeof (parsed as { sequence?: unknown }).sequence !== 'number'
+    ) {
+      return null;
+    }
+    return (parsed as { sequence: number }).sequence;
+  } catch {
+    return null;
+  }
+}
+
+// ============ body parsers ============
+
+interface ParsedOpenBody {
+  readonly agentId: AgentId;
+  readonly agentVersion: Semver;
+  readonly title: string;
+  readonly scope: Readonly<Record<string, unknown>>;
+  readonly participantId?: string;
+  readonly metadata?: Readonly<Record<string, unknown>>;
+}
+
+function parseOpenBody(
+  body: unknown,
+):
+  | { kind: 'ok'; value: ParsedOpenBody }
+  | { kind: 'err'; error: { code: string; message: string } } {
+  if (body === null || typeof body !== 'object') {
+    return { kind: 'err', error: { code: 'bad-input', message: 'Request body must be an object' } };
+  }
+  const b = body as Record<string, unknown>;
+  const agentId = b.agentId;
+  if (typeof agentId !== 'string' || agentId.length === 0) {
+    return {
+      kind: 'err',
+      error: { code: 'bad-input', message: '`agentId` must be a non-empty string' },
+    };
+  }
+  const agentVersion = b.agentVersion;
+  if (typeof agentVersion !== 'string' || agentVersion.length === 0) {
+    return {
+      kind: 'err',
+      error: { code: 'bad-input', message: '`agentVersion` must be a non-empty string' },
+    };
+  }
+  const titleRaw = b.title;
+  if (titleRaw !== undefined && typeof titleRaw !== 'string') {
+    return {
+      kind: 'err',
+      error: { code: 'bad-input', message: '`title` must be a string when supplied' },
+    };
+  }
+  // Default title when omitted — the underlying runtime rejects blanks.
+  // Callers who want a first-turn auto-title supply that themselves.
+  const title =
+    titleRaw !== undefined && titleRaw.trim().length > 0 ? titleRaw : 'Untitled conversation';
+
+  const scopeRaw = b.scope;
+  let scope: Readonly<Record<string, unknown>>;
+  if (scopeRaw === undefined) {
+    scope = {};
+  } else if (scopeRaw === null || typeof scopeRaw !== 'object' || Array.isArray(scopeRaw)) {
+    return {
+      kind: 'err',
+      error: { code: 'bad-input', message: '`scope` must be an object when supplied' },
+    };
+  } else {
+    scope = scopeRaw as Readonly<Record<string, unknown>>;
+  }
+
+  const participantIdRaw = b.participantId;
+  if (participantIdRaw !== undefined && typeof participantIdRaw !== 'string') {
+    return {
+      kind: 'err',
+      error: { code: 'bad-input', message: '`participantId` must be a string when supplied' },
+    };
+  }
+
+  const metadataRaw = b.metadata;
+  let metadata: Readonly<Record<string, unknown>> | undefined;
+  if (metadataRaw !== undefined) {
+    if (metadataRaw === null || typeof metadataRaw !== 'object' || Array.isArray(metadataRaw)) {
+      return {
+        kind: 'err',
+        error: { code: 'bad-input', message: '`metadata` must be an object when supplied' },
+      };
+    }
+    metadata = metadataRaw as Readonly<Record<string, unknown>>;
+  }
+
+  return {
+    kind: 'ok',
+    value: {
+      agentId: agentId as AgentId,
+      agentVersion: agentVersion as Semver,
+      title,
+      scope,
+      ...(participantIdRaw !== undefined && { participantId: participantIdRaw }),
+      ...(metadata !== undefined && { metadata }),
+    },
+  };
+}

package/src/routes/cost.ts

@@ -0,0 +1,327 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import { Hono } from 'hono';
+
+import type { Cursor, TenantId, Timestamp } from '@kindgi/types';
+
+import {
+  COST_GROUP_DIMENSIONS,
+  type CostAggregateGroup,
+  type CostBinding,
+  type CostGroupDimension,
+  type CostRecord,
+  type CostRecordFilter,
+} from '../cost-binding.js';
+import { statusFor, toWireError } from '../errors.js';
+import type { AppEnv } from '../types.js';
+import { clampLimit } from './pagination.js';
+import { parseScopeParams } from './scope-params.js';
+
+/**
+ * Cost readback routes — part of the admin control plane. Three
+ * surfaces:
+ *
+ *   - `GET  /v1/cost/records`      — paginated raw records with filters
+ *   - `GET  /v1/cost/records/:id`  — single record
+ *   - `GET  /v1/cost/aggregate`    — multi-dim rollup over a required
+ *                                    time window
+ *
+ * The aggregate endpoint is the primary consumer path (dashboards);
+ * the records list is for drilldown. Aggregate always runs over a
+ * bounded time range — without one, queries would scan unbounded rows.
+ * When the caller gives none, the route applies "last 30 days" and
+ * echoes it in the response `timeRange` field for round-trippability.
+ *
+ * Budgets are not part of this surface.
+ */
+export function costRouter(binding: CostBinding): Hono<AppEnv> {
+  const r = new Hono<AppEnv>();
+
+  const DEFAULT_AGGREGATE_WINDOW_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
+
+  // ---------- GET /records ----------
+  r.get('/records', async (c) => {
+    const requestId = c.get('requestId');
+    const tenantId = c.get('tenantId') as TenantId;
+    const limit = clampLimit(c.req.query('limit'));
+
+    const cursorRaw = c.req.query('cursor');
+    const filter = parseRecordFilter(c.req.query());
+    if (filter.kind === 'err') {
+      c.status(statusFor('bad-input') as never);
+      return c.json(toWireError({ code: 'bad-input', message: filter.error }, requestId));
+    }
+
+    // Thread the ?scopeKind + ?scopeId + ?inherit
+    // triplet as a sibling of `filter` (matches the binding's shape:
+    // `scope` / `inherit` are top-level on `CostListRecordsInput`).
+    const scopeParsed = parseScopeParams(c.req.query(), { tenantId });
+    if (scopeParsed.kind === 'err') {
+      c.status(statusFor('scope-invalid') as never);
+      return c.json(
+        toWireError({ code: 'scope-invalid', message: scopeParsed.message }, requestId),
+      );
+    }
+
+    const page = await binding.listRecords({
+      tenantId,
+      limit,
+      ...(cursorRaw !== undefined && cursorRaw.length > 0 && { cursor: cursorRaw as Cursor }),
+      filter: filter.value,
+      ...(scopeParsed.scope !== undefined && { scope: scopeParsed.scope }),
+      ...(scopeParsed.inherit !== undefined && { inherit: scopeParsed.inherit }),
+    });
+    return c.json({
+      data: page.data.map(serializeRecord),
+      hasMore: page.nextCursor !== undefined,
+      ...(page.nextCursor !== undefined && { nextCursor: page.nextCursor as unknown as string }),
+    });
+  });
+
+  // ---------- GET /records/:recordId ----------
+  r.get('/records/:recordId', async (c) => {
+    const requestId = c.get('requestId');
+    const tenantId = c.get('tenantId') as TenantId;
+    const recordId = c.req.param('recordId');
+
+    const record = await binding.getRecord({ tenantId, recordId });
+    if (record === null) {
+      c.status(statusFor('cost-record-not-found') as never);
+      return c.json(
+        toWireError(
+          {
+            code: 'cost-record-not-found',
+            message: `No cost record with id "${recordId}"`,
+            recordId,
+          },
+          requestId,
+        ),
+      );
+    }
+    return c.json(serializeRecord(record));
+  });
+
+  // ---------- GET /aggregate ----------
+  r.get('/aggregate', async (c) => {
+    const requestId = c.get('requestId');
+    const tenantId = c.get('tenantId') as TenantId;
+    const query = c.req.query();
+
+    // groupBy — required, comma-separated, each value from the closed set.
+    const groupByRaw = query.groupBy;
+    if (groupByRaw === undefined || groupByRaw.length === 0) {
+      c.status(statusFor('bad-input') as never);
+      return c.json(
+        toWireError(
+          { code: 'bad-input', message: '`groupBy` is required (comma-separated dimensions)' },
+          requestId,
+        ),
+      );
+    }
+    const rawDims = groupByRaw
+      .split(',')
+      .map((s) => s.trim())
+      .filter((s) => s.length > 0);
+    if (rawDims.length === 0) {
+      c.status(statusFor('bad-input') as never);
+      return c.json(
+        toWireError(
+          { code: 'bad-input', message: '`groupBy` must contain at least one dimension' },
+          requestId,
+        ),
+      );
+    }
+    const groupBy: CostGroupDimension[] = [];
+    for (const raw of rawDims) {
+      if (!(COST_GROUP_DIMENSIONS as readonly string[]).includes(raw)) {
+        c.status(statusFor('bad-input') as never);
+        return c.json(
+          toWireError(
+            {
+              code: 'bad-input',
+              message: `\`groupBy\` value "${raw}" is not a known dimension (one of: ${(
+                COST_GROUP_DIMENSIONS as readonly string[]
+              ).join(', ')})`,
+            },
+            requestId,
+          ),
+        );
+      }
+      if (!groupBy.includes(raw as CostGroupDimension)) {
+        groupBy.push(raw as CostGroupDimension);
+      }
+    }
+
+    // Time range — required. Default to last 30 days when both absent
+    // (documented in the response `timeRange`). If only one endpoint is
+    // supplied, reject — half-open defaults invite confusion.
+    const fromRaw = query.from;
+    const toRaw = query.to;
+    let from: Date;
+    let to: Date;
+    if (fromRaw === undefined && toRaw === undefined) {
+      to = new Date();
+      from = new Date(to.getTime() - DEFAULT_AGGREGATE_WINDOW_MS);
+    } else if (fromRaw === undefined || toRaw === undefined) {
+      c.status(statusFor('bad-input') as never);
+      return c.json(
+        toWireError(
+          {
+            code: 'bad-input',
+            message: '`from` and `to` must be provided together (or both omitted for the default)',
+          },
+          requestId,
+        ),
+      );
+    } else {
+      const parsedFrom = parseIsoDate(fromRaw);
+      const parsedTo = parseIsoDate(toRaw);
+      if (parsedFrom === null || parsedTo === null) {
+        c.status(statusFor('bad-input') as never);
+        return c.json(
+          toWireError(
+            { code: 'bad-input', message: '`from` / `to` must be ISO-8601 timestamps' },
+            requestId,
+          ),
+        );
+      }
+      if (parsedFrom.getTime() > parsedTo.getTime()) {
+        c.status(statusFor('bad-input') as never);
+        return c.json(
+          toWireError(
+            { code: 'bad-input', message: '`from` must be less than or equal to `to`' },
+            requestId,
+          ),
+        );
+      }
+      from = parsedFrom;
+      to = parsedTo;
+    }
+
+    const filter = parseRecordFilter(query, { skipTime: true });
+    if (filter.kind === 'err') {
+      c.status(statusFor('bad-input') as never);
+      return c.json(toWireError({ code: 'bad-input', message: filter.error }, requestId));
+    }
+
+    // Thread the scope triplet into aggregate so a
+    // scoped `/records` list and a scoped `/aggregate` reconcile to the
+    // same underlying row-set.
+    const scopeParsed = parseScopeParams(query, { tenantId });
+    if (scopeParsed.kind === 'err') {
+      c.status(statusFor('scope-invalid') as never);
+      return c.json(
+        toWireError({ code: 'scope-invalid', message: scopeParsed.message }, requestId),
+      );
+    }
+
+    const result = await binding.aggregate({
+      tenantId,
+      groupBy,
+      from,
+      to,
+      ...(Object.keys(filter.value).length > 0 && { filter: filter.value }),
+      ...(scopeParsed.scope !== undefined && { scope: scopeParsed.scope }),
+      ...(scopeParsed.inherit !== undefined && { inherit: scopeParsed.inherit }),
+    });
+
+    return c.json({
+      groups: result.groups.map(serializeGroup),
+      totalUsd: result.totalUsd,
+      totalRecords: result.totalRecords,
+      timeRange: {
+        from: result.timeRange.from,
+        to: result.timeRange.to,
+      },
+      groupBy,
+    });
+  });
+
+  return r;
+}
+
+// -------- helpers --------
+
+function parseRecordFilter(
+  query: Readonly<Record<string, string | undefined>>,
+  opts: { skipTime?: boolean } = {},
+): { kind: 'ok'; value: CostRecordFilter } | { kind: 'err'; error: string } {
+  const out: {
+    runId?: string;
+    agentId?: string;
+    conversationId?: string;
+    category?: string;
+    providerId?: string;
+    from?: Date;
+    to?: Date;
+  } = {};
+  const strKeys: Array<
+    ['runId' | 'agentId' | 'conversationId' | 'category' | 'providerId', string]
+  > = [
+    ['runId', 'runId'],
+    ['agentId', 'agentId'],
+    ['conversationId', 'conversationId'],
+    ['category', 'category'],
+    ['providerId', 'providerId'],
+  ];
+  for (const [outKey, qKey] of strKeys) {
+    const raw = query[qKey];
+    if (raw !== undefined && raw.length > 0) {
+      out[outKey] = raw;
+    }
+  }
+  if (opts.skipTime !== true) {
+    const fromRaw = query.from;
+    if (fromRaw !== undefined && fromRaw.length > 0) {
+      const parsed = parseIsoDate(fromRaw);
+      if (parsed === null) return { kind: 'err', error: '`from` must be an ISO-8601 timestamp' };
+      out.from = parsed;
+    }
+    const toRaw = query.to;
+    if (toRaw !== undefined && toRaw.length > 0) {
+      const parsed = parseIsoDate(toRaw);
+      if (parsed === null) return { kind: 'err', error: '`to` must be an ISO-8601 timestamp' };
+      out.to = parsed;
+    }
+    if (out.from !== undefined && out.to !== undefined && out.from.getTime() > out.to.getTime()) {
+      return { kind: 'err', error: '`from` must be less than or equal to `to`' };
+    }
+  }
+  return { kind: 'ok', value: out };
+}
+
+function parseIsoDate(raw: string): Date | null {
+  const t = Date.parse(raw);
+  if (!Number.isFinite(t)) return null;
+  return new Date(t);
+}
+
+function serializeRecord(rec: CostRecord): Record<string, unknown> {
+  return {
+    id: rec.id,
+    tenantId: rec.tenantId as unknown as string,
+    category: rec.category,
+    ...(rec.providerId !== undefined && { providerId: rec.providerId }),
+    ...(rec.runId !== undefined && { runId: rec.runId }),
+    ...(rec.agentId !== undefined && { agentId: rec.agentId }),
+    ...(rec.conversationId !== undefined && { conversationId: rec.conversationId }),
+    quantity: rec.quantity,
+    unit: rec.unit,
+    ...(rec.costUsd !== undefined && { costUsd: rec.costUsd }),
+    occurredAt: rec.occurredAt as unknown as string,
+    ...(rec.metrics !== undefined && { metrics: rec.metrics }),
+    ...(rec.attributes !== undefined && { attributes: rec.attributes }),
+  };
+}
+
+function serializeGroup(g: CostAggregateGroup): Record<string, unknown> {
+  return {
+    key: g.key,
+    count: g.count,
+    totalUsd: g.totalUsd,
+  };
+}
+
+// Re-export for typing convenience in tests / callers.
+export type { Timestamp };