@conquext/pg 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Rasheed Alabi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,51 @@
+import { StorageBackend, UsageEvent, UsageQuery } from '@conquext/core';
+
+interface PgConfig {
+    connectionString: string;
+    schema?: string;
+}
+interface PgRow {
+    id: string;
+    timestamp: Date;
+    model: string;
+    provider: string;
+    requested_model: string | null;
+    input_tokens: number;
+    output_tokens: number;
+    total_tokens: number;
+    cost: number;
+    latency_ms: number;
+    status: string;
+    error: string | null;
+    streaming: boolean | null;
+    time_to_first_token_ms: number | null;
+    cache_read_tokens: number | null;
+    cache_write_tokens: number | null;
+    pricing_miss: boolean | null;
+    user_id: string | null;
+    user_name: string | null;
+    user_email: string | null;
+    user_team: string | null;
+    user_plan: string | null;
+    task_id: string | null;
+    task_title: string | null;
+    task_type: string | null;
+    task_priority: string | null;
+    session_id: string | null;
+    conversation_id: string | null;
+    parent_call_id: string | null;
+    labels: Record<string, string>;
+}
+declare class PgBackend implements StorageBackend {
+    private sql;
+    private readonly schema;
+    private readonly connectionString;
+    constructor(config: PgConfig);
+    private initSql;
+    static eventToRow(event: UsageEvent): PgRow;
+    write(events: UsageEvent[]): Promise<void>;
+    query(query: UsageQuery): Promise<UsageEvent[]>;
+    close(): Promise<void>;
+}
+
+export { PgBackend, type PgConfig };

package/dist/index.js

@@ -0,0 +1,125 @@
+// src/pg-backend.ts
+var PgBackend = class _PgBackend {
+  sql;
+  schema;
+  connectionString;
+  constructor(config) {
+    this.schema = config.schema ?? "observatory";
+    this.connectionString = config.connectionString;
+    this.sql = null;
+  }
+  async initSql() {
+    if (this.sql) return;
+    const { default: postgres } = await import("postgres");
+    this.sql = postgres(this.connectionString);
+  }
+  static eventToRow(event) {
+    return {
+      id: event.id,
+      timestamp: event.timestamp,
+      model: event.model,
+      provider: event.provider,
+      requested_model: event.requested_model ?? null,
+      input_tokens: event.input_tokens,
+      output_tokens: event.output_tokens,
+      total_tokens: event.total_tokens,
+      cost: event.cost,
+      latency_ms: event.latency_ms,
+      status: event.status,
+      error: event.error ?? null,
+      streaming: event.streaming ?? null,
+      time_to_first_token_ms: event.time_to_first_token_ms ?? null,
+      cache_read_tokens: event.cache_read_tokens ?? null,
+      cache_write_tokens: event.cache_write_tokens ?? null,
+      pricing_miss: event.pricing_miss ?? null,
+      user_id: event.context?.user?.id ?? null,
+      user_name: event.context?.user?.name ?? null,
+      user_email: event.context?.user?.email ?? null,
+      user_team: event.context?.user?.team ?? null,
+      user_plan: event.context?.user?.plan ?? null,
+      task_id: event.context?.task?.id ?? null,
+      task_title: event.context?.task?.title ?? null,
+      task_type: event.context?.task?.type ?? null,
+      task_priority: event.context?.task?.priority ?? null,
+      session_id: event.context?.session?.id ?? null,
+      conversation_id: event.context?.session?.conversationId ?? null,
+      parent_call_id: event.context?.session?.parentCallId ?? null,
+      labels: event.context?.labels ?? {}
+    };
+  }
+  async write(events) {
+    await this.initSql();
+    const sql = this.sql;
+    const rows = events.map(_PgBackend.eventToRow);
+    await sql`
+      INSERT INTO ${sql(this.schema)}.usage_events ${sql(rows)}
+    `;
+  }
+  async query(query) {
+    await this.initSql();
+    const sql = this.sql;
+    const rows = await sql`
+      SELECT * FROM ${sql(this.schema)}.usage_events
+      WHERE timestamp >= ${query.from} AND timestamp <= ${query.to}
+      ${query.user ? sql`AND user_id = ${query.user}` : sql``}
+      ${query.model ? sql`AND model = ${query.model}` : sql``}
+      ${query.provider ? sql`AND provider = ${query.provider}` : sql``}
+      ${query.task ? sql`AND task_id = ${query.task}` : sql``}
+      ${query.session ? sql`AND session_id = ${query.session}` : sql``}
+      ORDER BY timestamp DESC
+      LIMIT 1000
+    `;
+    return rows.map(rowToEvent);
+  }
+  async close() {
+    if (!this.sql) return;
+    const sql = this.sql;
+    await sql.end();
+  }
+};
+function rowToEvent(row) {
+  return {
+    id: row.id,
+    timestamp: row.timestamp,
+    model: row.model,
+    provider: row.provider,
+    requested_model: row.requested_model || void 0,
+    input_tokens: row.input_tokens,
+    output_tokens: row.output_tokens,
+    total_tokens: row.total_tokens,
+    cost: Number(row.cost),
+    latency_ms: Number(row.latency_ms),
+    status: row.status,
+    error: row.error || void 0,
+    streaming: row.streaming || void 0,
+    time_to_first_token_ms: row.time_to_first_token_ms ? Number(row.time_to_first_token_ms) : void 0,
+    cache_read_tokens: row.cache_read_tokens || void 0,
+    cache_write_tokens: row.cache_write_tokens || void 0,
+    pricing_miss: row.pricing_miss || void 0,
+    context: {
+      user: row.user_id ? {
+        id: row.user_id,
+        name: row.user_name || void 0,
+        email: row.user_email || void 0,
+        team: row.user_team || void 0,
+        plan: row.user_plan || void 0
+      } : void 0,
+      task: row.task_id ? {
+        id: row.task_id,
+        title: row.task_title || void 0,
+        type: row.task_type || void 0,
+        priority: row.task_priority || void 0
+      } : void 0,
+      session: row.session_id ? {
+        id: row.session_id,
+        conversationId: row.conversation_id || void 0,
+        parentCallId: row.parent_call_id || void 0
+      } : void 0,
+      labels: row.labels || void 0
+    }
+  };
+}
+export {
+  PgBackend
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/pg-backend.ts"],"sourcesContent":["import type { StorageBackend, UsageEvent, UsageQuery } from '@conquext/core';\n\nexport interface PgConfig {\n  connectionString: string;\n  schema?: string;\n}\n\ninterface PgRow {\n  id: string;\n  timestamp: Date;\n  model: string;\n  provider: string;\n  requested_model: string | null;\n  input_tokens: number;\n  output_tokens: number;\n  total_tokens: number;\n  cost: number;\n  latency_ms: number;\n  status: string;\n  error: string | null;\n  streaming: boolean | null;\n  time_to_first_token_ms: number | null;\n  cache_read_tokens: number | null;\n  cache_write_tokens: number | null;\n  pricing_miss: boolean | null;\n  user_id: string | null;\n  user_name: string | null;\n  user_email: string | null;\n  user_team: string | null;\n  user_plan: string | null;\n  task_id: string | null;\n  task_title: string | null;\n  task_type: string | null;\n  task_priority: string | null;\n  session_id: string | null;\n  conversation_id: string | null;\n  parent_call_id: string | null;\n  labels: Record<string, string>;\n}\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\ntype Sql = any;\n\nexport class PgBackend implements StorageBackend {\n  private sql: Sql | null;\n  private readonly schema: string;\n  private readonly connectionString: string;\n\n  constructor(config: PgConfig) {\n    this.schema = config.schema ?? 'observatory';\n    this.connectionString = config.connectionString;\n    this.sql = null;\n  }\n\n  private async initSql(): Promise<void> {\n    if (this.sql) return;\n    const { default: postgres } = await import('postgres');\n    this.sql = postgres(this.connectionString);\n  }\n\n  static eventToRow(event: UsageEvent): PgRow {\n    return {\n      id: event.id,\n      timestamp: event.timestamp,\n      model: event.model,\n      provider: event.provider,\n      requested_model: event.requested_model ?? null,\n      input_tokens: event.input_tokens,\n      output_tokens: event.output_tokens,\n      total_tokens: event.total_tokens,\n      cost: event.cost,\n      latency_ms: event.latency_ms,\n      status: event.status,\n      error: event.error ?? null,\n      streaming: event.streaming ?? null,\n      time_to_first_token_ms: event.time_to_first_token_ms ?? null,\n      cache_read_tokens: event.cache_read_tokens ?? null,\n      cache_write_tokens: event.cache_write_tokens ?? null,\n      pricing_miss: event.pricing_miss ?? null,\n      user_id: event.context?.user?.id ?? null,\n      user_name: event.context?.user?.name ?? null,\n      user_email: event.context?.user?.email ?? null,\n      user_team: event.context?.user?.team ?? null,\n      user_plan: event.context?.user?.plan ?? null,\n      task_id: event.context?.task?.id ?? null,\n      task_title: event.context?.task?.title ?? null,\n      task_type: event.context?.task?.type ?? null,\n      task_priority: event.context?.task?.priority ?? null,\n      session_id: event.context?.session?.id ?? null,\n      conversation_id: event.context?.session?.conversationId ?? null,\n      parent_call_id: event.context?.session?.parentCallId ?? null,\n      labels: event.context?.labels ?? {},\n    };\n  }\n\n  async write(events: UsageEvent[]): Promise<void> {\n    await this.initSql();\n    const sql = this.sql!;\n    const rows = events.map(PgBackend.eventToRow);\n\n    await sql`\n      INSERT INTO ${sql(this.schema)}.usage_events ${sql(rows)}\n    `;\n  }\n\n  async query(query: UsageQuery): Promise<UsageEvent[]> {\n    await this.initSql();\n    const sql = this.sql!;\n\n    const rows = await sql`\n      SELECT * FROM ${sql(this.schema)}.usage_events\n      WHERE timestamp >= ${query.from} AND timestamp <= ${query.to}\n      ${query.user ? sql`AND user_id = ${query.user}` : sql``}\n      ${query.model ? sql`AND model = ${query.model}` : sql``}\n      ${query.provider ? sql`AND provider = ${query.provider}` : sql``}\n      ${query.task ? sql`AND task_id = ${query.task}` : sql``}\n      ${query.session ? sql`AND session_id = ${query.session}` : sql``}\n      ORDER BY timestamp DESC\n      LIMIT 1000\n    `;\n\n    return rows.map(rowToEvent);\n  }\n\n  async close(): Promise<void> {\n    if (!this.sql) return;\n    const sql = this.sql;\n    await sql.end();\n  }\n}\n\nfunction rowToEvent(row: Record<string, unknown>): UsageEvent {\n  return {\n    id: row.id as string,\n    timestamp: row.timestamp as Date,\n    model: row.model as string,\n    provider: row.provider as string,\n    requested_model: (row.requested_model as string) || undefined,\n    input_tokens: row.input_tokens as number,\n    output_tokens: row.output_tokens as number,\n    total_tokens: row.total_tokens as number,\n    cost: Number(row.cost),\n    latency_ms: Number(row.latency_ms),\n    status: row.status as 'success' | 'error',\n    error: (row.error as string) || undefined,\n    streaming: (row.streaming as boolean) || undefined,\n    time_to_first_token_ms: row.time_to_first_token_ms ? Number(row.time_to_first_token_ms) : undefined,\n    cache_read_tokens: (row.cache_read_tokens as number) || undefined,\n    cache_write_tokens: (row.cache_write_tokens as number) || undefined,\n    pricing_miss: (row.pricing_miss as boolean) || undefined,\n    context: {\n      user: row.user_id ? {\n        id: row.user_id as string,\n        name: (row.user_name as string) || undefined,\n        email: (row.user_email as string) || undefined,\n        team: (row.user_team as string) || undefined,\n        plan: (row.user_plan as string) || undefined,\n      } : undefined,\n      task: row.task_id ? {\n        id: row.task_id as string,\n        title: (row.task_title as string) || undefined,\n        type: (row.task_type as string) || undefined,\n        priority: (row.task_priority as 'low' | 'medium' | 'high' | 'critical') || undefined,\n      } : undefined,\n      session: row.session_id ? {\n        id: row.session_id as string,\n        conversationId: (row.conversation_id as string) || undefined,\n        parentCallId: (row.parent_call_id as string) || undefined,\n      } : undefined,\n      labels: (row.labels as Record<string, string>) || undefined,\n    },\n  };\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@conquext/pg",
+  "version": "0.1.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/migrations"
+  ],
+  "dependencies": {
+    "@conquext/core": "0.1.0"
+  },
+  "peerDependencies": {
+    "postgres": ">=3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "postgres": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}

package/src/migrations/001_create_usage_events.sql

@@ -0,0 +1,57 @@
+CREATE SCHEMA IF NOT EXISTS observatory;
+
+CREATE TABLE IF NOT EXISTS observatory.usage_events (
+  id TEXT PRIMARY KEY,
+  timestamp TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  model TEXT NOT NULL,
+  provider TEXT NOT NULL,
+  requested_model TEXT,
+  input_tokens INTEGER NOT NULL,
+  output_tokens INTEGER NOT NULL,
+  total_tokens INTEGER NOT NULL,
+  cost NUMERIC(12, 6) NOT NULL DEFAULT 0,
+  latency_ms NUMERIC(10, 2) NOT NULL,
+  status TEXT NOT NULL CHECK (status IN ('success', 'error')),
+  error TEXT,
+  streaming BOOLEAN,
+  time_to_first_token_ms NUMERIC(10, 2),
+  cache_read_tokens INTEGER,
+  cache_write_tokens INTEGER,
+  pricing_miss BOOLEAN,
+  user_id TEXT,
+  user_name TEXT,
+  user_email TEXT,
+  user_team TEXT,
+  user_plan TEXT,
+  task_id TEXT,
+  task_title TEXT,
+  task_type TEXT,
+  task_priority TEXT,
+  session_id TEXT,
+  conversation_id TEXT,
+  parent_call_id TEXT,
+  labels JSONB DEFAULT '{}'::jsonb,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+) PARTITION BY RANGE (timestamp);
+
+-- Create initial monthly partitions (3 months)
+DO $$
+DECLARE
+  start_date DATE := DATE_TRUNC('month', CURRENT_DATE);
+BEGIN
+  FOR i IN 0..2 LOOP
+    EXECUTE format(
+      'CREATE TABLE IF NOT EXISTS observatory.usage_events_%s PARTITION OF observatory.usage_events FOR VALUES FROM (%L) TO (%L)',
+      TO_CHAR(start_date + (i || ' months')::INTERVAL, 'YYYY_MM'),
+      start_date + (i || ' months')::INTERVAL,
+      start_date + ((i + 1) || ' months')::INTERVAL
+    );
+  END LOOP;
+END $$;
+
+-- Indexes for common queries
+CREATE INDEX IF NOT EXISTS idx_usage_events_user_id ON observatory.usage_events (user_id, timestamp);
+CREATE INDEX IF NOT EXISTS idx_usage_events_model ON observatory.usage_events (model, timestamp);
+CREATE INDEX IF NOT EXISTS idx_usage_events_provider ON observatory.usage_events (provider, timestamp);
+CREATE INDEX IF NOT EXISTS idx_usage_events_task_id ON observatory.usage_events (task_id, timestamp);
+CREATE INDEX IF NOT EXISTS idx_usage_events_team ON observatory.usage_events (user_team, timestamp);