@kindgi/api 0.0.0-bootstrap.0 → 0.1.1

package/dist/routes/conversations.js

@@ -0,0 +1,295 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+import { Hono } from 'hono';
+import { statusFor, toWireError } from '../errors.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, runBinding) {
+    const r = new Hono();
+    // ---------- GET / (list, cursor-paginated) ----------
+    r.get('/', async (c) => {
+        const requestId = c.get('requestId');
+        const tenantId = c.get('tenantId');
+        const limit = clampLimit(c.req.query('limit'));
+        const statusRaw = c.req.query('status');
+        let statusFilter;
+        if (statusRaw !== undefined && statusRaw.length > 0) {
+            if (statusRaw !== 'open' && statusRaw !== 'closed') {
+                c.status(statusFor('bad-input'));
+                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;
+        const rawCursor = c.req.query('cursor');
+        if (rawCursor !== undefined && rawCursor.length > 0) {
+            const decoded = decodeCursor(rawCursor);
+            if (decoded === null) {
+                c.status(statusFor('bad-input'));
+                return c.json(toWireError({ code: 'bad-input', message: '`cursor` is malformed' }, requestId));
+            }
+            before = { openedAt: decoded.createdAt, id: decoded.id };
+        }
+        const listResult = await conversationBinding.listConversationsPage({
+            tenantId,
+            ...(agentIdRaw !== undefined && agentIdRaw.length > 0 && { agentId: agentIdRaw }),
+            ...(statusFilter !== undefined && { status: statusFilter }),
+            ...(before !== undefined && { before }),
+            limit,
+        });
+        if (listResult.kind === 'err') {
+            c.status(statusFor(listResult.error.code));
+            return c.json(toWireError(listResult.error, requestId));
+        }
+        const { data, hasMore } = listResult.value;
+        const last = data[data.length - 1];
+        const nextCursor = hasMore && last !== undefined
+            ? encodeCursor({
+                createdAt: last.openedAt,
+                id: last.id,
+            })
+            : 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');
+        const conversationId = c.req.param('conversationId');
+        const got = await conversationBinding.getConversation(tenantId, conversationId);
+        if (got.kind === 'err') {
+            c.status(statusFor(got.error.code));
+            return c.json(toWireError(got.error, requestId));
+        }
+        return c.json(serializeConversation(got.value));
+    });
+    // ---------- POST / (open) ----------
+    r.post('/', async (c) => {
+        const requestId = c.get('requestId');
+        const tenantId = c.get('tenantId');
+        let body;
+        try {
+            body = await c.req.json();
+        }
+        catch {
+            c.status(statusFor('bad-input'));
+            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));
+            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));
+            return c.json(toWireError(opened.error, 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');
+        const conversationId = c.req.param('conversationId');
+        const existing = await conversationBinding.getConversation(tenantId, conversationId);
+        if (existing.kind === 'err') {
+            c.status(statusFor(existing.error.code));
+            return c.json(toWireError(existing.error, 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));
+            return c.json(toWireError(closed.error, 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');
+        const conversationId = c.req.param('conversationId');
+        const limit = clampLimit(c.req.query('limit'));
+        const rawCursor = c.req.query('cursor');
+        let sinceSequence;
+        if (rawCursor !== undefined && rawCursor.length > 0) {
+            const decoded = decodeMessageCursor(rawCursor);
+            if (decoded === null) {
+                c.status(statusFor('bad-input'));
+                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));
+            return c.json(toWireError(result.error, 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) {
+    return {
+        id: c.id,
+        tenantId: c.tenantId,
+        agentId: c.agentId,
+        agentVersion: c.agentVersion,
+        title: c.title,
+        ...(c.participantId !== undefined && { participantId: c.participantId }),
+        scope: c.scope,
+        status: (c.closedAt === undefined ? 'open' : 'closed'),
+        openedAt: c.openedAt,
+        ...(c.closedAt !== undefined && { closedAt: c.closedAt }),
+        turnCount: c.turnCount,
+        ...(c.lastMessageAt !== undefined && { lastMessageAt: c.lastMessageAt }),
+        ...(c.metadata !== undefined && { metadata: c.metadata }),
+    };
+}
+function serializeMessage(m) {
+    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,
+    };
+}
+// ============ cursor helpers ============
+function encodeMessageCursor(sequence) {
+    return Buffer.from(JSON.stringify({ sequence }), 'utf8').toString('base64url');
+}
+function decodeMessageCursor(raw) {
+    try {
+        const json = Buffer.from(raw, 'base64url').toString('utf8');
+        const parsed = JSON.parse(json);
+        if (parsed === null ||
+            typeof parsed !== 'object' ||
+            typeof parsed.sequence !== 'number') {
+            return null;
+        }
+        return parsed.sequence;
+    }
+    catch {
+        return null;
+    }
+}
+function parseOpenBody(body) {
+    if (body === null || typeof body !== 'object') {
+        return { kind: 'err', error: { code: 'bad-input', message: 'Request body must be an object' } };
+    }
+    const b = body;
+    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;
+    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;
+    }
+    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;
+    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;
+    }
+    return {
+        kind: 'ok',
+        value: {
+            agentId: agentId,
+            agentVersion: agentVersion,
+            title,
+            scope,
+            ...(participantIdRaw !== undefined && { participantId: participantIdRaw }),
+            ...(metadata !== undefined && { metadata }),
+        },
+    };
+}
+//# sourceMappingURL=conversations.js.map

package/dist/routes/conversations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversations.js","sourceRoot":"","sources":["../../src/routes/conversations.ts"],"names":[],"mappings":"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"}

package/dist/routes/cost.d.ts

@@ -0,0 +1,24 @@
+import { Hono } from 'hono';
+import type { Timestamp } from '@kindgi/types';
+import { type CostBinding } from '../cost-binding.js';
+import type { AppEnv } from '../types.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 declare function costRouter(binding: CostBinding): Hono<AppEnv>;
+export type { Timestamp };
+//# sourceMappingURL=cost.d.ts.map

package/dist/routes/cost.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost.d.ts","sourceRoot":"","sources":["../../src/routes/cost.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAE5B,OAAO,KAAK,EAAoB,SAAS,EAAE,MAAM,eAAe,CAAC;AAEjE,OAAO,EAGL,KAAK,WAAW,EAIjB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAI1C;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,CAAC,MAAM,CAAC,CA4M7D;AAqFD,YAAY,EAAE,SAAS,EAAE,CAAC"}

package/dist/routes/cost.js

@@ -0,0 +1,243 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+import { Hono } from 'hono';
+import { COST_GROUP_DIMENSIONS, } from '../cost-binding.js';
+import { statusFor, toWireError } from '../errors.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) {
+    const r = new Hono();
+    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');
+        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'));
+            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'));
+            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 }),
+            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 }),
+        });
+    });
+    // ---------- GET /records/:recordId ----------
+    r.get('/records/:recordId', async (c) => {
+        const requestId = c.get('requestId');
+        const tenantId = c.get('tenantId');
+        const recordId = c.req.param('recordId');
+        const record = await binding.getRecord({ tenantId, recordId });
+        if (record === null) {
+            c.status(statusFor('cost-record-not-found'));
+            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');
+        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'));
+            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'));
+            return c.json(toWireError({ code: 'bad-input', message: '`groupBy` must contain at least one dimension' }, requestId));
+        }
+        const groupBy = [];
+        for (const raw of rawDims) {
+            if (!COST_GROUP_DIMENSIONS.includes(raw)) {
+                c.status(statusFor('bad-input'));
+                return c.json(toWireError({
+                    code: 'bad-input',
+                    message: `\`groupBy\` value "${raw}" is not a known dimension (one of: ${COST_GROUP_DIMENSIONS.join(', ')})`,
+                }, requestId));
+            }
+            if (!groupBy.includes(raw)) {
+                groupBy.push(raw);
+            }
+        }
+        // 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;
+        let to;
+        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'));
+            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'));
+                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'));
+                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'));
+            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'));
+            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, opts = {}) {
+    const out = {};
+    const strKeys = [
+        ['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) {
+    const t = Date.parse(raw);
+    if (!Number.isFinite(t))
+        return null;
+    return new Date(t);
+}
+function serializeRecord(rec) {
+    return {
+        id: rec.id,
+        tenantId: rec.tenantId,
+        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,
+        ...(rec.metrics !== undefined && { metrics: rec.metrics }),
+        ...(rec.attributes !== undefined && { attributes: rec.attributes }),
+    };
+}
+function serializeGroup(g) {
+    return {
+        key: g.key,
+        count: g.count,
+        totalUsd: g.totalUsd,
+    };
+}
+//# sourceMappingURL=cost.js.map

package/dist/routes/cost.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost.js","sourceRoot":"","sources":["../../src/routes/cost.ts"],"names":[],"mappings":"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"}