@conquext/observa-clickhouse 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,23 @@
+import { StorageBackend, UsageEvent, UsageQuery } from '@conquext/observa-core';
+
+interface ClickHouseConfig {
+    url: string;
+    database?: string;
+    username?: string;
+    password?: string;
+}
+declare class ClickHouseBackend implements StorageBackend {
+    private client;
+    private clientPromise;
+    private readonly database;
+    private readonly config;
+    constructor(config: ClickHouseConfig);
+    private ensureClient;
+    private initClient;
+    static eventToRow(event: UsageEvent): Record<string, unknown>;
+    write(events: UsageEvent[]): Promise<void>;
+    query(_query: UsageQuery): Promise<UsageEvent[]>;
+    close(): Promise<void>;
+}
+
+export { ClickHouseBackend, type ClickHouseConfig };

package/dist/index.js

@@ -0,0 +1,77 @@
+// src/clickhouse-backend.ts
+var ClickHouseBackend = class _ClickHouseBackend {
+  client;
+  clientPromise = null;
+  database;
+  config;
+  constructor(config) {
+    this.database = config.database ?? "observatory";
+    this.config = config;
+  }
+  async ensureClient() {
+    if (this.client) return;
+    if (!this.clientPromise) {
+      this.clientPromise = this.initClient(this.config);
+    }
+    await this.clientPromise;
+  }
+  async initClient(config) {
+    const { createClient } = await import("@clickhouse/client");
+    this.client = createClient({
+      url: config.url,
+      database: this.database,
+      username: config.username,
+      password: config.password
+    });
+  }
+  static eventToRow(event) {
+    return {
+      id: event.id,
+      timestamp: event.timestamp.toISOString(),
+      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 ? 1 : 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 ? 1 : null,
+      user_id: event.context?.user?.id ?? null,
+      user_team: event.context?.user?.team ?? null,
+      task_id: event.context?.task?.id ?? null,
+      task_type: event.context?.task?.type ?? null,
+      session_id: event.context?.session?.id ?? null,
+      labels: event.context?.labels ?? {}
+    };
+  }
+  async write(events) {
+    await this.ensureClient();
+    const client = this.client;
+    const rows = events.map(_ClickHouseBackend.eventToRow);
+    await client.insert({
+      table: "usage_events",
+      values: rows,
+      format: "JSONEachRow"
+    });
+  }
+  async query(_query) {
+    await this.ensureClient();
+    throw new Error("query() is not yet implemented for ClickHouseBackend");
+  }
+  async close() {
+    await this.ensureClient();
+    const client = this.client;
+    if (client) await client.close();
+  }
+};
+export {
+  ClickHouseBackend
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/clickhouse-backend.ts"],"sourcesContent":["import type { StorageBackend, UsageEvent, UsageQuery } from '@conquext/observa-core';\n\nexport interface ClickHouseConfig {\n  url: string;\n  database?: string;\n  username?: string;\n  password?: string;\n}\n\nexport class ClickHouseBackend implements StorageBackend {\n  private client: unknown;\n  private clientPromise: Promise<void> | null = null;\n  private readonly database: string;\n  private readonly config: ClickHouseConfig;\n\n  constructor(config: ClickHouseConfig) {\n    this.database = config.database ?? 'observatory';\n    this.config = config;\n  }\n\n  private async ensureClient(): Promise<void> {\n    if (this.client) return;\n    if (!this.clientPromise) {\n      this.clientPromise = this.initClient(this.config);\n    }\n    await this.clientPromise;\n  }\n\n  private async initClient(config: ClickHouseConfig): Promise<void> {\n    const { createClient } = await import('@clickhouse/client');\n    this.client = createClient({\n      url: config.url,\n      database: this.database,\n      username: config.username,\n      password: config.password,\n    });\n  }\n\n  static eventToRow(event: UsageEvent): Record<string, unknown> {\n    return {\n      id: event.id,\n      timestamp: event.timestamp.toISOString(),\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 ? 1 : 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 ? 1 : null,\n      user_id: event.context?.user?.id ?? null,\n      user_team: event.context?.user?.team ?? null,\n      task_id: event.context?.task?.id ?? null,\n      task_type: event.context?.task?.type ?? null,\n      session_id: event.context?.session?.id ?? null,\n      labels: event.context?.labels ?? {},\n    };\n  }\n\n  async write(events: UsageEvent[]): Promise<void> {\n    await this.ensureClient();\n    const client = this.client as { insert: (params: unknown) => Promise<void> };\n    const rows = events.map(ClickHouseBackend.eventToRow);\n\n    await client.insert({\n      table: 'usage_events',\n      values: rows,\n      format: 'JSONEachRow',\n    });\n  }\n\n  async query(_query: UsageQuery): Promise<UsageEvent[]> {\n    await this.ensureClient();\n    throw new Error('query() is not yet implemented for ClickHouseBackend');\n  }\n\n  async close(): Promise<void> {\n    await this.ensureClient();\n    const client = this.client as { close: () => Promise<void> };\n    if (client) await client.close();\n  }\n}\n"],"mappings":";AASO,IAAM,oBAAN,MAAM,mBAA4C;AAAA,EAC/C;AAAA,EACA,gBAAsC;AAAA,EAC7B;AAAA,EACA;AAAA,EAEjB,YAAY,QAA0B;AACpC,SAAK,WAAW,OAAO,YAAY;AACnC,SAAK,SAAS;AAAA,EAChB;AAAA,EAEA,MAAc,eAA8B;AAC1C,QAAI,KAAK,OAAQ;AACjB,QAAI,CAAC,KAAK,eAAe;AACvB,WAAK,gBAAgB,KAAK,WAAW,KAAK,MAAM;AAAA,IAClD;AACA,UAAM,KAAK;AAAA,EACb;AAAA,EAEA,MAAc,WAAW,QAAyC;AAChE,UAAM,EAAE,aAAa,IAAI,MAAM,OAAO,oBAAoB;AAC1D,SAAK,SAAS,aAAa;AAAA,MACzB,KAAK,OAAO;AAAA,MACZ,UAAU,KAAK;AAAA,MACf,UAAU,OAAO;AAAA,MACjB,UAAU,OAAO;AAAA,IACnB,CAAC;AAAA,EACH;AAAA,EAEA,OAAO,WAAW,OAA4C;AAC5D,WAAO;AAAA,MACL,IAAI,MAAM;AAAA,MACV,WAAW,MAAM,UAAU,YAAY;AAAA,MACvC,OAAO,MAAM;AAAA,MACb,UAAU,MAAM;AAAA,MAChB,iBAAiB,MAAM,mBAAmB;AAAA,MAC1C,cAAc,MAAM;AAAA,MACpB,eAAe,MAAM;AAAA,MACrB,cAAc,MAAM;AAAA,MACpB,MAAM,MAAM;AAAA,MACZ,YAAY,MAAM;AAAA,MAClB,QAAQ,MAAM;AAAA,MACd,OAAO,MAAM,SAAS;AAAA,MACtB,WAAW,MAAM,YAAY,IAAI;AAAA,MACjC,wBAAwB,MAAM,0BAA0B;AAAA,MACxD,mBAAmB,MAAM,qBAAqB;AAAA,MAC9C,oBAAoB,MAAM,sBAAsB;AAAA,MAChD,cAAc,MAAM,eAAe,IAAI;AAAA,MACvC,SAAS,MAAM,SAAS,MAAM,MAAM;AAAA,MACpC,WAAW,MAAM,SAAS,MAAM,QAAQ;AAAA,MACxC,SAAS,MAAM,SAAS,MAAM,MAAM;AAAA,MACpC,WAAW,MAAM,SAAS,MAAM,QAAQ;AAAA,MACxC,YAAY,MAAM,SAAS,SAAS,MAAM;AAAA,MAC1C,QAAQ,MAAM,SAAS,UAAU,CAAC;AAAA,IACpC;AAAA,EACF;AAAA,EAEA,MAAM,MAAM,QAAqC;AAC/C,UAAM,KAAK,aAAa;AACxB,UAAM,SAAS,KAAK;AACpB,UAAM,OAAO,OAAO,IAAI,mBAAkB,UAAU;AAEpD,UAAM,OAAO,OAAO;AAAA,MAClB,OAAO;AAAA,MACP,QAAQ;AAAA,MACR,QAAQ;AAAA,IACV,CAAC;AAAA,EACH;AAAA,EAEA,MAAM,MAAM,QAA2C;AACrD,UAAM,KAAK,aAAa;AACxB,UAAM,IAAI,MAAM,sDAAsD;AAAA,EACxE;AAAA,EAEA,MAAM,QAAuB;AAC3B,UAAM,KAAK,aAAa;AACxB,UAAM,SAAS,KAAK;AACpB,QAAI,OAAQ,OAAM,OAAO,MAAM;AAAA,EACjC;AACF;","names":[]}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@conquext/observa-clickhouse",
+  "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/observa-core": "0.1.0"
+  },
+  "peerDependencies": {
+    "@clickhouse/client": ">=1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@clickhouse/client": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}

package/src/migrations/001_create_usage_events.sql

@@ -0,0 +1,28 @@
+CREATE TABLE IF NOT EXISTS observatory.usage_events (
+  id String,
+  timestamp DateTime64(3, 'UTC'),
+  model LowCardinality(String),
+  provider LowCardinality(String),
+  requested_model Nullable(String),
+  input_tokens UInt32,
+  output_tokens UInt32,
+  total_tokens UInt32,
+  cost Decimal64(6),
+  latency_ms Float32,
+  status LowCardinality(String),
+  error Nullable(String),
+  streaming Nullable(UInt8),
+  time_to_first_token_ms Nullable(Float32),
+  cache_read_tokens Nullable(UInt32),
+  cache_write_tokens Nullable(UInt32),
+  pricing_miss Nullable(UInt8),
+  user_id Nullable(String),
+  user_team Nullable(LowCardinality(String)),
+  task_id Nullable(String),
+  task_type Nullable(LowCardinality(String)),
+  session_id Nullable(String),
+  labels Map(String, String)
+) ENGINE = MergeTree()
+PARTITION BY toYYYYMM(timestamp)
+ORDER BY (timestamp, provider, model)
+TTL timestamp + INTERVAL 1 YEAR;