@build-astron-co/nimbus 0.2.0

package/src/state/artifacts.ts

@@ -0,0 +1,147 @@
+/**
+ * Artifact CRUD helpers.
+ *
+ * Refactored from SQLiteAdapter.saveArtifact, getArtifact, listArtifacts,
+ * and deleteArtifact.
+ */
+
+import type { Database } from '../compat/sqlite';
+import { getDb } from './db';
+
+/** Shape returned by artifact query helpers. */
+export interface ArtifactRecord {
+  id: string;
+  conversationId: string | null;
+  name: string;
+  type: string;
+  content: string;
+  language: string | null;
+  createdAt: string;
+  updatedAt: string;
+  metadata: any | null;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Persist or update an artifact.  Uses INSERT ... ON CONFLICT to upsert.
+ */
+export function saveArtifact(
+  id: string,
+  conversationId: string | null,
+  name: string,
+  type: string,
+  content: string,
+  language?: string,
+  metadata?: any,
+  db?: Database
+): void {
+  const d = db || getDb();
+  const stmt = d.prepare(`
+    INSERT INTO artifacts (id, conversation_id, name, type, content, language, created_at, updated_at, metadata)
+    VALUES (?, ?, ?, ?, ?, ?, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP, ?)
+    ON CONFLICT(id) DO UPDATE SET
+      conversation_id = excluded.conversation_id,
+      name = excluded.name,
+      type = excluded.type,
+      content = excluded.content,
+      language = excluded.language,
+      updated_at = CURRENT_TIMESTAMP,
+      metadata = excluded.metadata
+  `);
+
+  stmt.run(
+    id,
+    conversationId || null,
+    name,
+    type,
+    content,
+    language || null,
+    metadata ? JSON.stringify(metadata) : null
+  );
+}
+
+/**
+ * Retrieve a single artifact by id.
+ */
+export function getArtifact(id: string, db?: Database): ArtifactRecord | null {
+  const d = db || getDb();
+  const stmt = d.prepare('SELECT * FROM artifacts WHERE id = ?');
+  const row: any = stmt.get(id);
+
+  if (!row) {
+    return null;
+  }
+
+  return {
+    id: row.id,
+    conversationId: row.conversation_id,
+    name: row.name,
+    type: row.type,
+    content: row.content,
+    language: row.language,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+    metadata: row.metadata ? JSON.parse(row.metadata) : null,
+  };
+}
+
+/**
+ * List artifacts with optional type and conversation filters.
+ */
+export function listArtifacts(
+  type?: string,
+  conversationId?: string,
+  limit: number = 50,
+  offset: number = 0,
+  db?: Database
+): ArtifactRecord[] {
+  const d = db || getDb();
+
+  let query = 'SELECT * FROM artifacts';
+  const params: any[] = [];
+  const conditions: string[] = [];
+
+  if (type) {
+    conditions.push('type = ?');
+    params.push(type);
+  }
+
+  if (conversationId) {
+    conditions.push('conversation_id = ?');
+    params.push(conversationId);
+  }
+
+  if (conditions.length > 0) {
+    query += ` WHERE ${conditions.join(' AND ')}`;
+  }
+
+  query += ' ORDER BY created_at DESC LIMIT ? OFFSET ?';
+  params.push(limit, offset);
+
+  const stmt = d.prepare(query);
+  const rows: any[] = stmt.all(...params) as any[];
+
+  return rows.map(row => ({
+    id: row.id,
+    conversationId: row.conversation_id,
+    name: row.name,
+    type: row.type,
+    content: row.content,
+    language: row.language,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+    metadata: row.metadata ? JSON.parse(row.metadata) : null,
+  }));
+}
+
+/**
+ * Delete an artifact by id.
+ */
+export function deleteArtifact(id: string, db?: Database): void {
+  const d = db || getDb();
+  const stmt = d.prepare('DELETE FROM artifacts WHERE id = ?');
+  stmt.run(id);
+}

package/src/state/audit.ts

@@ -0,0 +1,137 @@
+/**
+ * Audit log helpers.
+ *
+ * Refactored from SQLiteAdapter.logAuditEvent and getAuditLogs.
+ */
+
+import type { Database } from '../compat/sqlite';
+import { getDb } from './db';
+
+/** Shape accepted when writing an audit event. */
+export interface AuditEventInput {
+  id: string;
+  userId?: string;
+  action: string;
+  resourceType?: string;
+  resourceId?: string;
+  input?: any;
+  output?: any;
+  status: string;
+  durationMs?: number;
+  metadata?: any;
+}
+
+/** Shape returned by audit log queries. */
+export interface AuditLogRecord {
+  id: string;
+  timestamp: string;
+  userId: string | null;
+  action: string;
+  resourceType: string | null;
+  resourceId: string | null;
+  input: any | null;
+  output: any | null;
+  status: string;
+  durationMs: number | null;
+  metadata: any | null;
+}
+
+/** Filter criteria for querying audit logs. */
+export interface AuditLogFilter {
+  userId?: string;
+  action?: string;
+  resourceType?: string;
+  status?: string;
+  startDate?: Date;
+  endDate?: Date;
+  limit?: number;
+  offset?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Persist an audit event.
+ */
+export function logAuditEvent(event: AuditEventInput, db?: Database): void {
+  const d = db || getDb();
+  const stmt = d.prepare(`
+    INSERT INTO audit_logs (id, timestamp, user_id, action, resource_type, resource_id, input, output, status, duration_ms, metadata)
+    VALUES (?, CURRENT_TIMESTAMP, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `);
+
+  stmt.run(
+    event.id,
+    event.userId || null,
+    event.action,
+    event.resourceType || null,
+    event.resourceId || null,
+    event.input ? JSON.stringify(event.input) : null,
+    event.output ? JSON.stringify(event.output) : null,
+    event.status,
+    event.durationMs || null,
+    event.metadata ? JSON.stringify(event.metadata) : null
+  );
+}
+
+/**
+ * Query audit logs with optional filters.
+ */
+export function getAuditLogs(filter?: AuditLogFilter, db?: Database): AuditLogRecord[] {
+  const d = db || getDb();
+
+  let query = 'SELECT * FROM audit_logs';
+  const params: any[] = [];
+  const conditions: string[] = [];
+
+  if (filter?.userId) {
+    conditions.push('user_id = ?');
+    params.push(filter.userId);
+  }
+  if (filter?.action) {
+    conditions.push('action = ?');
+    params.push(filter.action);
+  }
+  if (filter?.resourceType) {
+    conditions.push('resource_type = ?');
+    params.push(filter.resourceType);
+  }
+  if (filter?.status) {
+    conditions.push('status = ?');
+    params.push(filter.status);
+  }
+  if (filter?.startDate) {
+    conditions.push('timestamp >= ?');
+    params.push(filter.startDate.toISOString());
+  }
+  if (filter?.endDate) {
+    conditions.push('timestamp <= ?');
+    params.push(filter.endDate.toISOString());
+  }
+
+  if (conditions.length > 0) {
+    query += ` WHERE ${conditions.join(' AND ')}`;
+  }
+
+  query += ' ORDER BY timestamp DESC LIMIT ? OFFSET ?';
+  params.push(filter?.limit || 100, filter?.offset || 0);
+
+  const stmt = d.prepare(query);
+  const rows: any[] = stmt.all(...params) as any[];
+
+  return rows.map(row => ({
+    id: row.id,
+    timestamp: row.timestamp,
+    userId: row.user_id,
+    action: row.action,
+    resourceType: row.resource_type,
+    resourceId: row.resource_id,
+    input: row.input ? JSON.parse(row.input) : null,
+    output: row.output ? JSON.parse(row.output) : null,
+    status: row.status,
+    durationMs: row.duration_ms,
+    metadata: row.metadata ? JSON.parse(row.metadata) : null,
+  }));
+}

package/src/state/billing.ts

@@ -0,0 +1,240 @@
+/**
+ * Billing / usage tracking helpers.
+ *
+ * Refactored from the billing-service database adapter
+ * (services/billing-service/src/db/adapter.ts) into standalone functions
+ * that operate against the unified Nimbus database.
+ */
+
+import type { Database } from '../compat/sqlite';
+import { getDb } from './db';
+
+/** Shape returned by subscription queries. */
+export interface SubscriptionRecord {
+  id: string;
+  teamId: string;
+  plan: string;
+  status: string;
+  currentPeriodStart: string | null;
+  currentPeriodEnd: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+/** Shape returned by usage queries. */
+export interface UsageRecord {
+  id: string;
+  teamId: string | null;
+  userId: string | null;
+  type: string;
+  quantity: number;
+  unit: string;
+  costUsd: number | null;
+  metadata: any | null;
+  createdAt: string;
+}
+
+/** Aggregated usage summary row. */
+export interface UsageSummary {
+  type: string;
+  totalQuantity: number;
+  totalCost: number;
+  count: number;
+}
+
+// ---------------------------------------------------------------------------
+// Subscription helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a new subscription.
+ */
+export function createSubscription(
+  id: string,
+  teamId: string,
+  plan: string = 'free',
+  status: string = 'active',
+  currentPeriodStart?: string,
+  currentPeriodEnd?: string,
+  db?: Database
+): void {
+  const d = db || getDb();
+  const stmt = d.prepare(`
+    INSERT INTO subscriptions (id, team_id, plan, status, current_period_start, current_period_end, created_at, updated_at)
+    VALUES (?, ?, ?, ?, ?, ?, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP)
+  `);
+
+  stmt.run(id, teamId, plan, status, currentPeriodStart || null, currentPeriodEnd || null);
+}
+
+/**
+ * Retrieve a subscription by team id.
+ */
+export function getSubscription(teamId: string, db?: Database): SubscriptionRecord | null {
+  const d = db || getDb();
+  const stmt = d.prepare('SELECT * FROM subscriptions WHERE team_id = ?');
+  const row: any = stmt.get(teamId);
+
+  if (!row) {
+    return null;
+  }
+
+  return {
+    id: row.id,
+    teamId: row.team_id,
+    plan: row.plan,
+    status: row.status,
+    currentPeriodStart: row.current_period_start,
+    currentPeriodEnd: row.current_period_end,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+  };
+}
+
+/**
+ * Update plan, status, or period boundaries of an existing subscription.
+ */
+export function updateSubscription(
+  teamId: string,
+  updates: {
+    plan?: string;
+    status?: string;
+    currentPeriodStart?: string;
+    currentPeriodEnd?: string;
+  },
+  db?: Database
+): void {
+  const d = db || getDb();
+  const stmt = d.prepare(`
+    UPDATE subscriptions
+    SET plan = COALESCE(?, plan),
+        status = COALESCE(?, status),
+        current_period_start = COALESCE(?, current_period_start),
+        current_period_end = COALESCE(?, current_period_end),
+        updated_at = CURRENT_TIMESTAMP
+    WHERE team_id = ?
+  `);
+
+  stmt.run(
+    updates.plan || null,
+    updates.status || null,
+    updates.currentPeriodStart || null,
+    updates.currentPeriodEnd || null,
+    teamId
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Usage helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Record a single usage event.
+ */
+export function recordUsage(
+  id: string,
+  type: string,
+  quantity: number,
+  unit: string = 'tokens',
+  costUsd?: number,
+  teamId?: string,
+  userId?: string,
+  metadata?: any,
+  db?: Database
+): void {
+  const d = db || getDb();
+  const stmt = d.prepare(`
+    INSERT INTO usage (id, team_id, user_id, type, quantity, unit, cost_usd, metadata, created_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, CURRENT_TIMESTAMP)
+  `);
+
+  stmt.run(
+    id,
+    teamId || null,
+    userId || null,
+    type,
+    quantity,
+    unit,
+    costUsd ?? 0,
+    metadata ? JSON.stringify(metadata) : null
+  );
+}
+
+/**
+ * Retrieve usage records for a team within a date range.
+ */
+export function getUsage(
+  teamId: string,
+  since: Date,
+  until?: Date,
+  limit: number = 100,
+  offset: number = 0,
+  db?: Database
+): UsageRecord[] {
+  const d = db || getDb();
+  const untilDate = until || new Date();
+
+  const stmt = d.prepare(`
+    SELECT * FROM usage
+    WHERE team_id = ?
+      AND created_at >= ?
+      AND created_at <= ?
+    ORDER BY created_at DESC
+    LIMIT ? OFFSET ?
+  `);
+
+  const rows: any[] = stmt.all(
+    teamId,
+    since.toISOString(),
+    untilDate.toISOString(),
+    limit,
+    offset
+  ) as any[];
+
+  return rows.map(row => ({
+    id: row.id,
+    teamId: row.team_id,
+    userId: row.user_id,
+    type: row.type,
+    quantity: row.quantity,
+    unit: row.unit,
+    costUsd: row.cost_usd,
+    metadata: row.metadata ? JSON.parse(row.metadata) : null,
+    createdAt: row.created_at,
+  }));
+}
+
+/**
+ * Aggregate usage by type for a team within a date range.
+ */
+export function getUsageSummary(
+  teamId: string,
+  since: Date,
+  until?: Date,
+  db?: Database
+): UsageSummary[] {
+  const d = db || getDb();
+  const untilDate = until || new Date();
+
+  const stmt = d.prepare(`
+    SELECT
+      type,
+      SUM(quantity) as total_quantity,
+      SUM(cost_usd) as total_cost,
+      COUNT(*) as count
+    FROM usage
+    WHERE team_id = ?
+      AND created_at >= ?
+      AND created_at <= ?
+    GROUP BY type
+  `);
+
+  const rows: any[] = stmt.all(teamId, since.toISOString(), untilDate.toISOString()) as any[];
+
+  return rows.map(row => ({
+    type: row.type,
+    totalQuantity: row.total_quantity,
+    totalCost: row.total_cost,
+    count: row.count,
+  }));
+}

package/src/state/checkpoints.ts

@@ -0,0 +1,117 @@
+/**
+ * Checkpoint save / restore helpers for resumable operations.
+ *
+ * Refactored from SQLiteAdapter.saveCheckpoint, getCheckpoint,
+ * getLatestCheckpoint, listCheckpoints, and deleteCheckpoints.
+ */
+
+import type { Database } from '../compat/sqlite';
+import { getDb } from './db';
+
+/** Shape returned by checkpoint queries. */
+export interface CheckpointRecord {
+  id: string;
+  operationId: string;
+  step: number;
+  state: Record<string, unknown>;
+  createdAt: string;
+}
+
+/** Abbreviated shape used by listCheckpoints. */
+export interface CheckpointListItem {
+  id: string;
+  step: number;
+  createdAt: string;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Persist or overwrite a checkpoint for a given operation and step.
+ */
+export function saveCheckpoint(
+  id: string,
+  operationId: string,
+  step: number,
+  state: Record<string, unknown>,
+  db?: Database
+): void {
+  const d = db || getDb();
+  const stmt = d.prepare(`
+    INSERT OR REPLACE INTO checkpoints (id, operation_id, step, state, created_at)
+    VALUES (?, ?, ?, ?, CURRENT_TIMESTAMP)
+  `);
+
+  stmt.run(id, operationId, step, JSON.stringify(state));
+}
+
+/**
+ * Retrieve a single checkpoint by its id.
+ */
+export function getCheckpoint(id: string, db?: Database): CheckpointRecord | null {
+  const d = db || getDb();
+  const stmt = d.prepare('SELECT * FROM checkpoints WHERE id = ?');
+  const row: any = stmt.get(id);
+
+  if (!row) {
+    return null;
+  }
+
+  return {
+    id: row.id,
+    operationId: row.operation_id,
+    step: row.step,
+    state: JSON.parse(row.state),
+    createdAt: row.created_at,
+  };
+}
+
+/**
+ * Retrieve the most recent checkpoint (highest step) for an operation.
+ */
+export function getLatestCheckpoint(operationId: string, db?: Database): CheckpointRecord | null {
+  const d = db || getDb();
+  const stmt = d.prepare(`
+    SELECT * FROM checkpoints WHERE operation_id = ? ORDER BY step DESC LIMIT 1
+  `);
+  const row: any = stmt.get(operationId);
+
+  if (!row) {
+    return null;
+  }
+
+  return {
+    id: row.id,
+    operationId: row.operation_id,
+    step: row.step,
+    state: JSON.parse(row.state),
+    createdAt: row.created_at,
+  };
+}
+
+/**
+ * List all checkpoints for an operation ordered by step ascending.
+ */
+export function listCheckpoints(operationId: string, db?: Database): CheckpointListItem[] {
+  const d = db || getDb();
+  const stmt = d.prepare(`
+    SELECT id, step, created_at FROM checkpoints WHERE operation_id = ? ORDER BY step ASC
+  `);
+
+  return (stmt.all(operationId) as any[]).map(row => ({
+    id: row.id,
+    step: row.step,
+    createdAt: row.created_at,
+  }));
+}
+
+/**
+ * Delete all checkpoints associated with an operation.
+ */
+export function deleteCheckpoints(operationId: string, db?: Database): void {
+  const d = db || getDb();
+  const stmt = d.prepare('DELETE FROM checkpoints WHERE operation_id = ?');
+  stmt.run(operationId);
+}

package/src/state/config.ts

@@ -0,0 +1,67 @@
+/**
+ * Config key-value store helpers.
+ *
+ * Refactored from SQLiteAdapter.setConfig, getConfig, and getAllConfig.
+ */
+
+import type { Database } from '../compat/sqlite';
+import { getDb } from './db';
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Set (insert or replace) a configuration value.
+ * The value is JSON-serialised before storage.
+ */
+export function setConfig(key: string, value: any, db?: Database): void {
+  const d = db || getDb();
+  const stmt = d.prepare(`
+    INSERT OR REPLACE INTO config (key, value, updated_at)
+    VALUES (?, ?, CURRENT_TIMESTAMP)
+  `);
+
+  stmt.run(key, JSON.stringify(value));
+}
+
+/**
+ * Retrieve a single configuration value by key.
+ * Returns `null` when the key does not exist.
+ */
+export function getConfig(key: string, db?: Database): any | null {
+  const d = db || getDb();
+  const stmt = d.prepare('SELECT value FROM config WHERE key = ?');
+  const row: any = stmt.get(key);
+
+  if (!row) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(row.value);
+  } catch {
+    // Corrupted config value — treat as missing
+    return null;
+  }
+}
+
+/**
+ * Retrieve every configuration entry as a flat key-value object.
+ */
+export function getAllConfig(db?: Database): Record<string, any> {
+  const d = db || getDb();
+  const stmt = d.prepare('SELECT key, value FROM config');
+  const rows: any[] = stmt.all() as any[];
+
+  const config: Record<string, any> = {};
+  for (const row of rows) {
+    try {
+      config[row.key] = JSON.parse(row.value);
+    } catch {
+      // Skip corrupted config entries
+    }
+  }
+
+  return config;
+}

package/src/state/conversations.ts

@@ -0,0 +1,14 @@
+/**
+ * Re-export conversation helpers from messages.ts for clarity.
+ *
+ * Consumers can import from either `./messages` or `./conversations`
+ * depending on which name reads better at the call-site.
+ */
+
+export {
+  saveConversation,
+  getConversation,
+  listConversations,
+  deleteConversation,
+} from './messages';
+export type { ConversationRecord } from './messages';