@recombine-ai/platform 0.2.5 → 0.2.6-test.10

package/build/analytics.d.ts

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+export type AnalyticsScalar = boolean | number | string;
+export type AnalyticsFieldType = 'boolean' | 'number' | 'string';
+declare const analyticsFieldDefinitionBrand: unique symbol;
+export interface AnalyticsFieldDefinition<T> {
+    readonly type: AnalyticsFieldType;
+    readonly schema: z.ZodType<T>;
+    readonly [analyticsFieldDefinitionBrand]: true;
+}
+export type AnalyticsFieldDefinitions = Readonly<Record<string, AnalyticsFieldDefinition<unknown>>>;
+export type AnalyticsValue<TField extends AnalyticsFieldDefinition<unknown>> = TField extends AnalyticsFieldDefinition<infer TValue> ? TValue : never;
+type AnalyticsFieldName<TFields extends AnalyticsFieldDefinitions> = Extract<keyof TFields, string>;
+export interface ConversationAnalyticsSummary {
+    conversationId: string;
+    agentId: string;
+    channel: string;
+    startedAt: Date;
+}
+export interface AnalyticsStore {
+    set(conversationId: string, agentId: string, fieldName: string, value: AnalyticsScalar): Promise<void>;
+    clear(conversationId: string, agentId: string, fieldName: string): Promise<void>;
+    get(conversationId: string, agentId: string, fieldName: string): Promise<unknown | undefined>;
+    getSummary(conversationId: string, agentId: string): Promise<ConversationAnalyticsSummary | undefined>;
+}
+export interface AgentAnalytics<TFields extends AnalyticsFieldDefinitions> {
+    set<TName extends AnalyticsFieldName<TFields>>(conversationId: string, fieldName: TName, value: AnalyticsValue<TFields[TName]>): Promise<void>;
+    clear<TName extends AnalyticsFieldName<TFields>>(conversationId: string, fieldName: TName): Promise<void>;
+    get<TName extends AnalyticsFieldName<TFields>>(conversationId: string, fieldName: TName): Promise<AnalyticsValue<TFields[TName]> | undefined>;
+    getSummary(conversationId: string): Promise<ConversationAnalyticsSummary | undefined>;
+}
+export declare const analyticsField: {
+    boolean(): AnalyticsFieldDefinition<boolean>;
+    number(): AnalyticsFieldDefinition<number>;
+    string(): AnalyticsFieldDefinition<string>;
+    enum<const TValues extends readonly [string, ...string[]]>(values: TValues): AnalyticsFieldDefinition<TValues[number]>;
+};
+export declare function validateAgentAnalytics(agentId: string, fields: AnalyticsFieldDefinitions): void;
+export declare function createAgentAnalytics<TFields extends AnalyticsFieldDefinitions>(store: AnalyticsStore, agentId: string, fields: TFields): AgentAnalytics<TFields>;
+export declare function createInMemoryAnalytics(summaries?: ConversationAnalyticsSummary[]): AnalyticsStore;
+export declare function assertAnalyticsScalar(value: unknown): asserts value is AnalyticsScalar;
+export {};
+//# sourceMappingURL=analytics.d.ts.map

package/build/analytics.d.ts.map

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

package/build/analytics.js

@@ -0,0 +1,129 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.analyticsField = void 0;
+exports.validateAgentAnalytics = validateAgentAnalytics;
+exports.createAgentAnalytics = createAgentAnalytics;
+exports.createInMemoryAnalytics = createInMemoryAnalytics;
+exports.assertAnalyticsScalar = assertAnalyticsScalar;
+const zod_1 = require("zod");
+const analyticsFieldDefinitionBrand = Symbol('AnalyticsFieldDefinition');
+const analyticsFieldDefinitions = new WeakSet();
+function defineField(type, schema) {
+    const definition = {
+        type,
+        schema,
+        [analyticsFieldDefinitionBrand]: true,
+    };
+    analyticsFieldDefinitions.add(definition);
+    return Object.freeze(definition);
+}
+exports.analyticsField = {
+    boolean() {
+        return defineField('boolean', zod_1.z.boolean());
+    },
+    number() {
+        return defineField('number', zod_1.z.number().finite());
+    },
+    string() {
+        return defineField('string', zod_1.z.string());
+    },
+    enum(values) {
+        return defineField('string', zod_1.z.enum(values));
+    },
+};
+function validateAgentAnalytics(agentId, fields) {
+    if (agentId.trim() === '') {
+        throw new Error('Analytics agent ID must not be empty');
+    }
+    for (const [fieldName, value] of Object.entries(fields)) {
+        if (!/^[A-Za-z0-9_.:-]{1,128}$/.test(fieldName)) {
+            throw new Error('Analytics field name contains unsupported characters');
+        }
+        if (!isAnalyticsFieldDefinition(value)) {
+            throw new Error(`Analytics field '${fieldName}' must be declared with analyticsField`);
+        }
+        const definition = value;
+        if (!['boolean', 'number', 'string'].includes(definition.type)) {
+            throw new Error(`Analytics field '${fieldName}' has an unsupported type`);
+        }
+    }
+}
+function isAnalyticsFieldDefinition(value) {
+    return typeof value === 'object' && value !== null && analyticsFieldDefinitions.has(value);
+}
+function createAgentAnalytics(store, agentId, fields) {
+    validateAgentAnalytics(agentId, fields);
+    const getDefinition = (fieldName) => {
+        const definition = fields[fieldName];
+        if (!definition) {
+            throw new Error(`Analytics field '${fieldName}' is not declared for agent '${agentId}'`);
+        }
+        return definition;
+    };
+    const parseValue = (fieldName, value) => getDefinition(fieldName).schema.parse(value);
+    return {
+        async set(conversationId, fieldName, value) {
+            const parsed = parseValue(fieldName, value);
+            assertAnalyticsScalar(parsed);
+            await store.set(conversationId, agentId, fieldName, parsed);
+        },
+        async clear(conversationId, fieldName) {
+            getDefinition(fieldName);
+            await store.clear(conversationId, agentId, fieldName);
+        },
+        async get(conversationId, fieldName) {
+            getDefinition(fieldName);
+            const value = await store.get(conversationId, agentId, fieldName);
+            return value === undefined ? undefined : parseValue(fieldName, value);
+        },
+        getSummary(conversationId) {
+            return store.getSummary(conversationId, agentId);
+        },
+    };
+}
+function createInMemoryAnalytics(summaries = []) {
+    const conversations = new Map();
+    const conversationAgents = new Map(summaries.map((summary) => [summary.conversationId, summary.agentId]));
+    const summariesById = new Map(summaries.map((summary) => [summary.conversationId, structuredClone(summary)]));
+    return {
+        async set(conversationId, agentId, fieldName, value) {
+            const existingAgentId = conversationAgents.get(conversationId);
+            if (existingAgentId !== undefined && existingAgentId !== agentId) {
+                throw new Error(`Conversation '${conversationId}' belongs to another agent`);
+            }
+            assertAnalyticsScalar(value);
+            const values = conversations.get(conversationId) ?? new Map();
+            values.set(fieldName, value);
+            conversations.set(conversationId, values);
+            conversationAgents.set(conversationId, agentId);
+        },
+        async clear(conversationId, agentId, fieldName) {
+            if (conversationAgents.get(conversationId) !== agentId) {
+                return;
+            }
+            const values = conversations.get(conversationId);
+            values?.delete(fieldName);
+            if (values?.size === 0) {
+                conversations.delete(conversationId);
+            }
+        },
+        async get(conversationId, agentId, fieldName) {
+            if (conversationAgents.get(conversationId) !== agentId) {
+                return undefined;
+            }
+            return conversations.get(conversationId)?.get(fieldName);
+        },
+        async getSummary(conversationId, agentId) {
+            const summary = summariesById.get(conversationId);
+            return summary?.agentId === agentId ? structuredClone(summary) : undefined;
+        },
+    };
+}
+function assertAnalyticsScalar(value) {
+    if (typeof value === 'boolean' ||
+        typeof value === 'string' ||
+        (typeof value === 'number' && Number.isFinite(value))) {
+        return;
+    }
+    throw new Error('Analytics value must be a boolean, finite number, or string');
+}

package/build/index.d.ts

@@ -1,5 +1,8 @@
 export * from './interfaces/platform';
 export * from './interfaces/rc-voice';
 export * from './context-cache';
+export * from './analytics';
+export * from './postgres-analytics';
+export * from './postgres-analytics-query';
 export * from './timeouts-manager';
 //# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAA;AACrC,cAAc,uBAAuB,CAAA;AACrC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,oBAAoB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAA;AACrC,cAAc,uBAAuB,CAAA;AACrC,cAAc,iBAAiB,CAAA;AAG/B,cAAc,aAAa,CAAA;AAC3B,cAAc,sBAAsB,CAAA;AACpC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,oBAAoB,CAAA"}

package/build/index.js

@@ -17,4 +17,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./interfaces/platform"), exports);
 __exportStar(require("./interfaces/rc-voice"), exports);
 __exportStar(require("./context-cache"), exports);
+__exportStar(require("./analytics"), exports);
+__exportStar(require("./postgres-analytics"), exports);
+__exportStar(require("./postgres-analytics-query"), exports);
 __exportStar(require("./timeouts-manager"), exports);

package/build/interfaces/platform.d.ts

@@ -1,5 +1,6 @@
 import { ReadableStream } from 'node:stream/web';
 import { AIEngine, AIStreamEngine, LlmAdapter, LlmStreamAdapter, Logger, Message, PromptFS, ResponseChunk } from '@recombine-ai/engine';
+import { AgentAnalytics, AnalyticsFieldDefinitions, AnalyticsStore } from '../analytics';
 import { ContextCache } from '../context-cache';
 import { TimeoutManager } from '../timeouts-manager';
 import { IRcVoice } from './rc-voice';
@@ -7,33 +8,53 @@ export interface IModels {
     models: Record<string, LlmAdapter>;
     streamingModels: Record<string, LlmStreamAdapter>;
 }
-export interface Platform<TContext extends {}, TModels extends IModels> {
+export interface Platform<TContext extends {}, TModels extends IModels, TRcVoice = IRcVoice, TTimeoutManager = TimeoutManager, TContextCache = ContextCache<TContext>> {
     streamAi: AIStreamEngine<TContext>;
     ai: AIEngine<TContext>;
     fs: PromptFS;
-    rcVoice: IRcVoice;
+    rcVoice: TRcVoice;
     logger: Logger;
-    timeoutManager: TimeoutManager;
+    timeoutManager: TTimeoutManager;
     models: TModels['models'];
     streamingModels: TModels['streamingModels'];
-    contextCache: ContextCache<TContext>;
+    contextCache: TContextCache;
+    analytics: AnalyticsStore;
 }
 export interface CallInfo {
     callId: string;
     phoneNumber?: string;
     headers: Record<string, unknown>;
 }
+export type VoiceSettings = Record<string, string | number | boolean | number[]>;
 export interface VoiceAgent {
     onCallStart: (call: CallInfo) => Promise<{
         initialMessage: string;
-        initialSettings?: Record<string, string | number>;
+        initialSettings?: VoiceSettings;
     }>;
     onCallReady: (call: CallInfo) => Promise<void>;
     streamResponse: (messages: Message[], call: CallInfo) => Promise<ReadableStream<ResponseChunk>>;
-    onCallEnd: (call: CallInfo) => Promise<void>;
+    onCallEnd: (call: CallInfo, completedConversation?: Message[]) => Promise<void>;
     onAgentSpeechDone: (messages: Message[], call: CallInfo) => Promise<void>;
     onServiceStartup: () => Promise<void>;
     onFatalError: (callId: string, err: any) => Promise<void>;
 }
-export declare function createAgent<TContext extends {}, TServices, TModels extends IModels>(creator: (platform: Platform<TContext, TModels>, services: TServices) => VoiceAgent): (platform: Platform<TContext, TModels>, services: TServices) => VoiceAgent;
+export type AgentPlatform<TPlatform extends {
+    analytics: AnalyticsStore;
+}, TFields extends AnalyticsFieldDefinitions> = Omit<TPlatform, 'analytics'> & {
+    analytics: AgentAnalytics<TFields>;
+};
+type ComposedPlatform<TContext extends object, TModels extends IModels> = Platform<TContext, TModels, unknown, unknown, unknown>;
+export interface AgentDefinition<TFields extends AnalyticsFieldDefinitions> {
+    readonly agentId: string;
+    readonly analytics: Readonly<TFields>;
+}
+export interface AgentDeclaration<TContext extends object, TServices, TModels extends IModels, TFields extends AnalyticsFieldDefinitions, TPlatform extends ComposedPlatform<TContext, TModels> = Platform<TContext, TModels>> extends AgentDefinition<TFields> {
+    create: (platform: AgentPlatform<TPlatform, TFields>, services: TServices) => VoiceAgent;
+}
+export interface AgentCreator<TContext extends object, TServices, TModels extends IModels, TFields extends AnalyticsFieldDefinitions, TPlatform extends ComposedPlatform<TContext, TModels> = Platform<TContext, TModels>> {
+    (platform: TPlatform, services: TServices): VoiceAgent;
+    readonly definition: AgentDefinition<TFields>;
+}
+export declare function createAgent<TContext extends object, TServices, TModels extends IModels, const TFields extends AnalyticsFieldDefinitions, TPlatform extends ComposedPlatform<TContext, TModels> = Platform<TContext, TModels>>(declaration: AgentDeclaration<TContext, TServices, TModels, TFields, TPlatform>): AgentCreator<TContext, TServices, TModels, TFields, TPlatform>;
+export {};
 //# sourceMappingURL=platform.d.ts.map

package/build/interfaces/platform.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"platform.d.ts","sourceRoot":"","sources":["../../src/interfaces/platform.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAEhD,OAAO,EACH,QAAQ,EACR,cAAc,EACd,UAAU,EACV,gBAAgB,EAChB,MAAM,EACN,OAAO,EACP,QAAQ,EACR,aAAa,EAChB,MAAM,sBAAsB,CAAA;AAE7B,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAC/C,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAErC,MAAM,WAAW,OAAO;IACpB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;IAClC,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAA;CACpD;AAED,MAAM,WAAW,QAAQ,CAAC,QAAQ,SAAS,EAAE,EAAE,OAAO,SAAS,OAAO;IAElE,QAAQ,EAAE,cAAc,CAAC,QAAQ,CAAC,CAAA;IAElC,EAAE,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAAA;IAEtB,EAAE,EAAE,QAAQ,CAAA;IAEZ,OAAO,EAAE,QAAQ,CAAA;IACjB,MAAM,EAAE,MAAM,CAAA;IACd,cAAc,EAAE,cAAc,CAAA;IAE9B,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAA;IACzB,eAAe,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAA;IAE3C,YAAY,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAA;CACvC;AAED,MAAM,WAAW,QAAQ;IACrB,MAAM,EAAE,MAAM,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,CAAA;IAEpB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACnC;AAED,MAAM,WAAW,UAAU;IACvB,WAAW,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,OAAO,CAAC;QACrC,cAAc,EAAE,MAAM,CAAA;QACtB,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAA;KACpD,CAAC,CAAA;IACF,WAAW,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAC9C,cAAc,EAAE,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,KAAK,OAAO,CAAC,cAAc,CAAC,aAAa,CAAC,CAAC,CAAA;IAC/F,SAAS,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAC5C,iBAAiB,EAAE,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACzE,gBAAgB,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IACrC,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CAC5D;AAED,wBAAgB,WAAW,CAAC,QAAQ,SAAS,EAAE,EAAE,SAAS,EAAE,OAAO,SAAS,OAAO,EAC/E,OAAO,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,EAAE,QAAQ,EAAE,SAAS,KAAK,UAAU,cAA/D,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,YAAY,SAAS,KAAK,UAAU,CAGtF"}
+{"version":3,"file":"platform.d.ts","sourceRoot":"","sources":["../../src/interfaces/platform.ts"],"names":[],"mappings":"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"}

package/build/interfaces/platform.js

@@ -1,6 +1,21 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createAgent = createAgent;
-function createAgent(creator) {
-    return creator;
+const analytics_1 = require("../analytics");
+function createAgent(declaration) {
+    const { agentId, create } = declaration;
+    const analytics = Object.freeze({ ...declaration.analytics });
+    (0, analytics_1.validateAgentAnalytics)(agentId, analytics);
+    const creator = (platform, services) => {
+        const agentPlatform = {
+            ...platform,
+            analytics: (0, analytics_1.createAgentAnalytics)(platform.analytics, agentId, analytics),
+        };
+        return create(agentPlatform, services);
+    };
+    const definition = Object.freeze({ agentId, analytics });
+    return Object.defineProperty(creator, 'definition', {
+        enumerable: true,
+        value: definition,
+    });
 }

package/build/postgres-analytics-query.d.ts

@@ -0,0 +1,87 @@
+import { PoolConfig, QueryResult } from 'pg';
+import { AnalyticsScalar } from './analytics';
+export type AnalyticsFilterScalar = boolean | number | string;
+export type AnalyticsFilterValueType = 'boolean' | 'number' | 'string';
+export type AnalyticsFilterOperator = 'eq' | 'exists' | 'gt' | 'gte' | 'in' | 'lt' | 'lte';
+export interface AnalyticsFilter {
+    key: string;
+    type: AnalyticsFilterValueType;
+    operator: AnalyticsFilterOperator;
+    value?: AnalyticsFilterScalar;
+    values?: AnalyticsFilterScalar[];
+}
+export type AnalyticsMetric = {
+    operation: 'count';
+} | {
+    operation: 'rate';
+    filter: AnalyticsFilter;
+} | {
+    operation: 'average' | 'sum';
+    key: string;
+};
+export type AnalyticsTimeGranularity = 'hour' | 'day' | 'week' | 'month';
+export type AnalyticsQueryParameters = Readonly<Record<string, unknown>>;
+export interface TelescopeConversation {
+    conversationId: string;
+    medium: string;
+    agentId: string;
+    region?: string;
+    phoneNumber?: string;
+    duration?: number;
+    audioUrl?: string;
+    createdAt: number;
+    endedAt?: number;
+    analytics: Record<string, AnalyticsScalar>;
+}
+export interface TelescopeConversationPage {
+    limit: number;
+    items: TelescopeConversation[];
+    lastConversationId?: string;
+}
+export interface AnalyticsFieldValue {
+    value: AnalyticsFilterScalar;
+    count: number;
+}
+export interface AnalyticsFieldMetadata {
+    key: string;
+    type: AnalyticsFilterValueType;
+    variantCount: number;
+    values: AnalyticsFieldValue[];
+}
+export interface AnalyticsFields {
+    items: AnalyticsFieldMetadata[];
+}
+export interface AnalyticsTimeSeriesItem {
+    startAt: string;
+    value: number | null;
+    numerator?: number;
+    denominator?: number;
+}
+export interface AnalyticsTimeSeries {
+    metric: AnalyticsMetric;
+    granularity: AnalyticsTimeGranularity;
+    from: string;
+    to: string;
+    items: AnalyticsTimeSeriesItem[];
+}
+interface Queryable {
+    query<TResult extends Record<string, unknown> = Record<string, unknown>>(text: string, values?: unknown[]): Promise<QueryResult<TResult>>;
+}
+export declare class AnalyticsQueryError extends Error {
+    name: string;
+}
+export declare class PostgresAnalyticsQueryService {
+    private readonly database;
+    constructor(database: Queryable);
+    getConversation(conversationId: string): Promise<TelescopeConversation | undefined>;
+    getConversations(query: AnalyticsQueryParameters): Promise<TelescopeConversationPage>;
+    getAnalyticsFields(query: AnalyticsQueryParameters): Promise<AnalyticsFields>;
+    getTimeSeries(query: AnalyticsQueryParameters): Promise<AnalyticsTimeSeries>;
+}
+export interface PostgresAnalyticsQueryServices {
+    queries: PostgresAnalyticsQueryService;
+    close(): Promise<void>;
+}
+export declare function createPostgresAnalyticsQueryServices(config: PoolConfig): PostgresAnalyticsQueryServices;
+export {};
+//# sourceMappingURL=postgres-analytics-query.d.ts.map

package/build/postgres-analytics-query.d.ts.map

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

package/build/postgres-analytics-query.js

@@ -0,0 +1,392 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PostgresAnalyticsQueryService = exports.AnalyticsQueryError = void 0;
+exports.createPostgresAnalyticsQueryServices = createPostgresAnalyticsQueryServices;
+const pg_1 = require("pg");
+class AnalyticsQueryError extends Error {
+    name = 'AnalyticsQueryError';
+}
+exports.AnalyticsQueryError = AnalyticsQueryError;
+class PostgresAnalyticsQueryService {
+    database;
+    constructor(database) {
+        this.database = database;
+    }
+    async getConversation(conversationId) {
+        const result = await this.database.query(`SELECT c.conversation_id, c.agent_id, c.channel, c.region, c.started_at,
+                    c.ended_at, c.analytics,
+                    p.phone_number, p.recording_url, p.duration_seconds
+             FROM conversations c
+             LEFT JOIN phone_calls p ON p.conversation_id = c.conversation_id
+             WHERE c.conversation_id = $1`, [conversationId]);
+        const row = result.rows[0];
+        return row?.agent_id ? conversationRowToJson(row) : undefined;
+    }
+    async getConversations(query) {
+        const parsedLimit = Number.parseInt(optionalString(query.limit, 'limit') ?? '10', 10);
+        const requestedLimit = Number.isFinite(parsedLimit)
+            ? Math.min(100, Math.max(1, parsedLimit))
+            : 10;
+        const cursor = parseConversationCursor(optionalString(query.lastConversationId, 'lastConversationId'));
+        const { bind, conditions, values } = buildConversationConditions(query);
+        if (cursor) {
+            conditions.push(`(c.started_at, c.conversation_id) < (${bind(cursor.startedAt)}, ${bind(cursor.conversationId)})`);
+        }
+        const where = conditions.length ? `WHERE ${conditions.join(' AND ')}` : '';
+        const limitParameter = bind(requestedLimit + 1);
+        const result = await this.database.query(`SELECT c.conversation_id, c.agent_id, c.channel, c.region, c.started_at,
+                    c.ended_at, c.analytics,
+                    p.phone_number, p.recording_url, p.duration_seconds
+             FROM conversations c
+             LEFT JOIN phone_calls p ON p.conversation_id = c.conversation_id
+             ${where}
+             ORDER BY c.started_at DESC, c.conversation_id DESC
+             LIMIT ${limitParameter}`, values);
+        const hasNextPage = result.rows.length > requestedLimit;
+        const rows = result.rows.slice(0, requestedLimit);
+        return {
+            limit: requestedLimit,
+            items: rows.map(conversationRowToJson),
+            lastConversationId: hasNextPage && rows.length > 0 ? makeConversationCursor(rows.at(-1)) : undefined,
+        };
+    }
+    async getAnalyticsFields(query) {
+        const agentId = requiredString(query.agentId, 'agentId');
+        const values = [agentId];
+        const where = "WHERE jsonb_typeof(entry.value) IN ('boolean', 'number', 'string')" +
+            ' AND c.agent_id = $1';
+        const result = await this.database.query(`WITH value_counts AS (
+                 SELECT entry.key,
+                        jsonb_typeof(entry.value) AS type,
+                        entry.value AS value,
+                        COUNT(*)::bigint AS occurrence_count
+                 FROM conversations c
+                 CROSS JOIN LATERAL jsonb_each(c.analytics) AS entry(key, value)
+                 ${where}
+                 GROUP BY entry.key, type, entry.value
+             ),
+             ranked AS (
+                 SELECT key,
+                        type,
+                        value,
+                        occurrence_count,
+                        COUNT(*) OVER (PARTITION BY key, type)::integer AS variant_count,
+                        ROW_NUMBER() OVER (
+                            PARTITION BY key, type
+                            ORDER BY occurrence_count DESC, value::text ASC
+                        ) AS rank
+                 FROM value_counts
+             )
+             SELECT key, type, value, occurrence_count, variant_count
+             FROM ranked
+             WHERE rank <= 50
+             ORDER BY key ASC, type ASC, rank ASC`, values);
+        return analyticsFieldRowsToJson(result.rows);
+    }
+    async getTimeSeries(query) {
+        const metric = parseMetric(requiredString(query.metric, 'metric'));
+        const granularity = (optionalString(query.granularity, 'granularity') ??
+            'day');
+        if (!['hour', 'day', 'week', 'month'].includes(granularity)) {
+            throw new AnalyticsQueryError('granularity must be hour, day, week, or month');
+        }
+        const { bind, conditions, from, to, values } = buildConversationConditions(query);
+        if (!from || !to) {
+            throw new AnalyticsQueryError('from and to are required for a time series');
+        }
+        const bucketExpression = `date_trunc(${bind(granularity)}::text, c.started_at, 'UTC')`;
+        let valueExpression;
+        let numeratorExpression = 'NULL::bigint';
+        if (metric.operation === 'count') {
+            valueExpression = 'COUNT(*)::double precision';
+        }
+        else if (metric.operation === 'rate') {
+            const predicate = makeAnalyticsPredicate(metric.filter, bind);
+            numeratorExpression = `COUNT(*) FILTER (WHERE ${predicate})::bigint`;
+            valueExpression =
+                `COUNT(*) FILTER (WHERE ${predicate})::double precision / ` + 'NULLIF(COUNT(*), 0)';
+        }
+        else {
+            const key = bind(metric.key);
+            const numericValue = `CASE WHEN jsonb_typeof(c.analytics -> (${key}::text)) = 'number' ` +
+                `THEN (c.analytics ->> (${key}::text))::double precision END`;
+            valueExpression =
+                metric.operation === 'average' ? `AVG(${numericValue})` : `SUM(${numericValue})`;
+        }
+        const where = conditions.length ? `WHERE ${conditions.join(' AND ')}` : '';
+        const result = await this.database.query(`SELECT ${bucketExpression} AS bucket_start,
+                    ${valueExpression} AS metric_value,
+                    ${numeratorExpression} AS numerator,
+                    COUNT(*)::bigint AS denominator
+             FROM conversations c
+             LEFT JOIN phone_calls p ON p.conversation_id = c.conversation_id
+             ${where}
+             GROUP BY bucket_start
+             ORDER BY bucket_start ASC`, values);
+        return {
+            metric,
+            granularity,
+            from: from.toISOString(),
+            to: to.toISOString(),
+            items: result.rows.map((row) => ({
+                startAt: new Date(row.bucket_start).toISOString(),
+                value: row.metric_value === null ? null : Number(row.metric_value),
+                ...(metric.operation === 'rate'
+                    ? {
+                        numerator: Number(row.numerator),
+                        denominator: Number(row.denominator),
+                    }
+                    : {}),
+            })),
+        };
+    }
+}
+exports.PostgresAnalyticsQueryService = PostgresAnalyticsQueryService;
+function createPostgresAnalyticsQueryServices(config) {
+    const pool = new pg_1.Pool(config);
+    return {
+        queries: new PostgresAnalyticsQueryService(pool),
+        close: () => pool.end(),
+    };
+}
+function optionalString(value, name) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string') {
+        throw new AnalyticsQueryError(`${name} must be a string`);
+    }
+    return value;
+}
+function requiredString(value, name) {
+    const result = optionalString(value, name);
+    if (!result) {
+        throw new AnalyticsQueryError(`${name} is required`);
+    }
+    return result;
+}
+function parseDateFilter(value, name) {
+    const stringValue = optionalString(value, name);
+    if (stringValue === undefined)
+        return undefined;
+    const date = /^\d+$/.test(stringValue) ? new Date(Number(stringValue)) : new Date(stringValue);
+    if (Number.isNaN(date.getTime())) {
+        throw new AnalyticsQueryError(`${name} must be a valid date`);
+    }
+    return date;
+}
+function parseDurationFilter(value, name) {
+    const stringValue = optionalString(value, name);
+    if (stringValue === undefined)
+        return undefined;
+    const duration = Number(stringValue);
+    if (!Number.isFinite(duration) || duration < 0) {
+        throw new AnalyticsQueryError(`${name} must be a non-negative number`);
+    }
+    return duration;
+}
+function parseAnalyticsFilters(value) {
+    const stringValue = optionalString(value, 'filters');
+    if (!stringValue)
+        return [];
+    let filters;
+    try {
+        filters = JSON.parse(stringValue);
+    }
+    catch {
+        throw new AnalyticsQueryError('filters must be valid JSON');
+    }
+    if (!Array.isArray(filters) || filters.length > 20) {
+        throw new AnalyticsQueryError('filters must be an array with at most 20 entries');
+    }
+    return filters.map(validateAnalyticsFilter);
+}
+function validateAnalyticsFilter(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new AnalyticsQueryError('Each filter must be an object');
+    }
+    const filter = value;
+    if (typeof filter.key !== 'string' || !/^[A-Za-z0-9_.:-]{1,128}$/.test(filter.key)) {
+        throw new AnalyticsQueryError('Filter key is invalid');
+    }
+    if (!['boolean', 'number', 'string'].includes(String(filter.type))) {
+        throw new AnalyticsQueryError(`Filter '${filter.key}' has an invalid type`);
+    }
+    const type = filter.type;
+    const allowedOperators = type === 'number'
+        ? ['eq', 'in', 'gt', 'gte', 'lt', 'lte', 'exists']
+        : ['eq', 'in', 'exists'];
+    if (!allowedOperators.includes(String(filter.operator))) {
+        throw new AnalyticsQueryError(`Filter '${filter.key}' has an invalid operator`);
+    }
+    const operator = filter.operator;
+    if (operator === 'in') {
+        if (!Array.isArray(filter.values) ||
+            filter.values.length === 0 ||
+            filter.values.length > 50 ||
+            filter.values.some((item) => typeof item !== type || (type === 'number' && !Number.isFinite(item)))) {
+            throw new AnalyticsQueryError(`Filter '${filter.key}' has invalid values`);
+        }
+        return { key: filter.key, type, operator, values: filter.values };
+    }
+    if (operator !== 'exists' && typeof filter.value !== type) {
+        throw new AnalyticsQueryError(`Filter '${filter.key}' has an invalid value`);
+    }
+    if (type === 'number' && !Number.isFinite(filter.value)) {
+        throw new AnalyticsQueryError(`Filter '${filter.key}' has an invalid value`);
+    }
+    return {
+        key: filter.key,
+        type,
+        operator,
+        ...(operator === 'exists' ? {} : { value: filter.value }),
+    };
+}
+function parseMetric(value) {
+    let metric;
+    try {
+        metric = JSON.parse(value);
+    }
+    catch {
+        throw new AnalyticsQueryError('metric must be valid JSON');
+    }
+    if (!metric || typeof metric !== 'object' || Array.isArray(metric)) {
+        throw new AnalyticsQueryError('metric must be an object');
+    }
+    const record = metric;
+    if (!['count', 'rate', 'average', 'sum'].includes(String(record.operation))) {
+        throw new AnalyticsQueryError('metric operation is invalid');
+    }
+    if (record.operation === 'rate') {
+        return { operation: 'rate', filter: validateAnalyticsFilter(record.filter) };
+    }
+    if (record.operation === 'average' || record.operation === 'sum') {
+        if (typeof record.key !== 'string' || !/^[A-Za-z0-9_.:-]{1,128}$/.test(record.key)) {
+            throw new AnalyticsQueryError('Metric key is invalid');
+        }
+        return { operation: record.operation, key: record.key };
+    }
+    return { operation: 'count' };
+}
+function parseConversationCursor(value) {
+    if (!value)
+        return undefined;
+    try {
+        const cursor = JSON.parse(Buffer.from(value, 'base64url').toString('utf8'));
+        const startedAt = new Date(String(cursor.startedAt));
+        if (Number.isNaN(startedAt.getTime()) ||
+            typeof cursor.conversationId !== 'string' ||
+            cursor.conversationId === '') {
+            throw new Error('invalid cursor');
+        }
+        return { startedAt, conversationId: cursor.conversationId };
+    }
+    catch {
+        throw new AnalyticsQueryError('lastConversationId is invalid');
+    }
+}
+function makeConversationCursor(row) {
+    return Buffer.from(JSON.stringify({
+        startedAt: new Date(row.started_at).toISOString(),
+        conversationId: row.conversation_id,
+    })).toString('base64url');
+}
+function conversationRowToJson(row) {
+    return {
+        conversationId: row.conversation_id,
+        medium: row.channel,
+        agentId: row.agent_id,
+        region: row.region || undefined,
+        phoneNumber: row.phone_number || undefined,
+        duration: row.duration_seconds ?? undefined,
+        audioUrl: row.recording_url || undefined,
+        createdAt: new Date(row.started_at).getTime(),
+        endedAt: row.ended_at ? new Date(row.ended_at).getTime() : undefined,
+        analytics: analyticsScalars(row.analytics),
+    };
+}
+function analyticsScalars(values) {
+    return Object.fromEntries(Object.entries(values ?? {}).filter((entry) => {
+        const value = entry[1];
+        return (typeof value === 'boolean' ||
+            typeof value === 'string' ||
+            (typeof value === 'number' && Number.isFinite(value)));
+    }));
+}
+function analyticsFieldRowsToJson(rows) {
+    const fields = new Map();
+    for (const row of rows) {
+        const id = `${row.key}\u0000${row.type}`;
+        let field = fields.get(id);
+        if (!field) {
+            field = {
+                key: row.key,
+                type: row.type,
+                variantCount: Number(row.variant_count),
+                values: [],
+            };
+            fields.set(id, field);
+        }
+        if (field.variantCount <= 50) {
+            field.values.push({ value: row.value, count: Number(row.occurrence_count) });
+        }
+    }
+    return { items: [...fields.values()] };
+}
+function buildConversationConditions(query) {
+    const values = [];
+    const bind = (value) => {
+        values.push(value);
+        return `$${values.length}`;
+    };
+    const conditions = [];
+    const from = parseDateFilter(query.from, 'from');
+    const to = parseDateFilter(query.to, 'to');
+    if (from && to && from >= to) {
+        throw new AnalyticsQueryError('from must be earlier than to');
+    }
+    const agentId = requiredString(query.agentId, 'agentId');
+    const region = optionalString(query.region, 'region');
+    const channel = optionalString(query.channel, 'channel');
+    const phoneNumber = optionalString(query.phoneNumber, 'phoneNumber');
+    conditions.push(`c.agent_id = ${bind(agentId)}`);
+    if (region)
+        conditions.push(`c.region = ${bind(region)}`);
+    if (channel)
+        conditions.push(`c.channel = ${bind(channel)}`);
+    if (phoneNumber)
+        conditions.push(`p.phone_number = ${bind(phoneNumber)}`);
+    if (from)
+        conditions.push(`c.started_at >= ${bind(from)}`);
+    if (to)
+        conditions.push(`c.started_at < ${bind(to)}`);
+    const minDuration = parseDurationFilter(query.minDurationSeconds, 'minDurationSeconds');
+    const maxDuration = parseDurationFilter(query.maxDurationSeconds, 'maxDurationSeconds');
+    if (minDuration !== undefined)
+        conditions.push(`p.duration_seconds >= ${bind(minDuration)}`);
+    if (maxDuration !== undefined)
+        conditions.push(`p.duration_seconds <= ${bind(maxDuration)}`);
+    if (minDuration !== undefined && maxDuration !== undefined && minDuration > maxDuration) {
+        throw new AnalyticsQueryError('minDurationSeconds must not exceed maxDurationSeconds');
+    }
+    for (const filter of parseAnalyticsFilters(query.filters)) {
+        conditions.push(makeAnalyticsPredicate(filter, bind));
+    }
+    return { bind, conditions, from, to, values };
+}
+function makeAnalyticsPredicate(filter, bind) {
+    const key = bind(filter.key);
+    if (filter.operator === 'exists') {
+        return `c.analytics ? (${key}::text)`;
+    }
+    if (filter.operator === 'eq') {
+        return `c.analytics @> jsonb_build_object(${key}::text, ${bind(JSON.stringify(filter.value))}::jsonb)`;
+    }
+    if (filter.operator === 'in') {
+        const predicates = filter.values.map((value) => `c.analytics @> jsonb_build_object(${key}::text, ${bind(JSON.stringify(value))}::jsonb)`);
+        return `(${predicates.join(' OR ')})`;
+    }
+    const operator = { gt: '>', gte: '>=', lt: '<', lte: '<=' }[filter.operator];
+    return (`(CASE WHEN jsonb_typeof(c.analytics -> (${key}::text)) = 'number' THEN ` +
+        `(c.analytics ->> (${key}::text))::double precision ${operator} ${bind(filter.value)} ` +
+        'ELSE false END)');
+}

package/build/postgres-analytics.d.ts

@@ -0,0 +1,45 @@
+import { Pool, PoolConfig, QueryResult } from 'pg';
+import { AnalyticsScalar, AnalyticsStore, ConversationAnalyticsSummary } from './analytics';
+import { PostgresAnalyticsQueryService } from './postgres-analytics-query';
+export interface ConversationRecord {
+    conversationId: string;
+    agentId: string;
+    channel: string;
+    region?: string;
+    startedAt: Date;
+    endedAt?: Date;
+}
+export interface PhoneCallRecord {
+    phoneNumber?: string;
+    recordingUrl?: string;
+    endedReason?: string;
+    durationSeconds?: number;
+}
+interface Queryable {
+    query<TResult extends Record<string, unknown> = Record<string, unknown>>(text: string, values?: unknown[]): Promise<QueryResult<TResult>>;
+}
+export declare class PostgresAnalytics implements AnalyticsStore {
+    private readonly database;
+    constructor(database: Queryable);
+    set(conversationId: string, agentId: string, fieldName: string, value: AnalyticsScalar): Promise<void>;
+    clear(conversationId: string, agentId: string, fieldName: string): Promise<void>;
+    get(conversationId: string, agentId: string, fieldName: string): Promise<unknown | undefined>;
+    getSummary(conversationId: string, agentId: string): Promise<ConversationAnalyticsSummary | undefined>;
+}
+export declare class PostgresConversationRepository {
+    private readonly pool;
+    constructor(pool: Pool);
+    saveConversation(conversation: ConversationRecord, phoneCall?: PhoneCallRecord): Promise<void>;
+    private upsertConversation;
+    private upsertPhoneCall;
+}
+export declare function migrateAnalyticsDatabase(pool: Pool): Promise<void>;
+export interface PostgresAnalyticsServices {
+    analytics: PostgresAnalytics;
+    conversations: PostgresConversationRepository;
+    queries: PostgresAnalyticsQueryService;
+    close(): Promise<void>;
+}
+export declare function createPostgresAnalyticsServices(config: PoolConfig): Promise<PostgresAnalyticsServices>;
+export {};
+//# sourceMappingURL=postgres-analytics.d.ts.map

package/build/postgres-analytics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres-analytics.d.ts","sourceRoot":"","sources":["../src/postgres-analytics.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAc,UAAU,EAAE,WAAW,EAAE,MAAM,IAAI,CAAA;AAE9D,OAAO,EACH,eAAe,EACf,cAAc,EACd,4BAA4B,EAE/B,MAAM,aAAa,CAAA;AACpB,OAAO,EAAE,6BAA6B,EAAE,MAAM,4BAA4B,CAAA;AAI1E,MAAM,WAAW,kBAAkB;IAC/B,cAAc,EAAE,MAAM,CAAA;IACtB,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,IAAI,CAAA;IACf,OAAO,CAAC,EAAE,IAAI,CAAA;CACjB;AAID,MAAM,WAAW,eAAe;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,eAAe,CAAC,EAAE,MAAM,CAAA;CAC3B;AAID,UAAU,SAAS;IACf,KAAK,CAAC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnE,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,OAAO,EAAE,GACnB,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAA;CACnC;AAaD,qBAAa,iBAAkB,YAAW,cAAc;IACxC,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAAR,QAAQ,EAAE,SAAS;IAE1C,GAAG,CACL,cAAc,EAAE,MAAM,EACtB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,eAAe,GACvB,OAAO,CAAC,IAAI,CAAC;IAeV,KAAK,CAAC,cAAc,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAchF,GAAG,CACL,cAAc,EAAE,MAAM,EACtB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,GAClB,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC;IAezB,UAAU,CACZ,cAAc,EAAE,MAAM,EACtB,OAAO,EAAE,MAAM,GAChB,OAAO,CAAC,4BAA4B,GAAG,SAAS,CAAC;CAqBvD;AAgBD,qBAAa,8BAA8B;IAC3B,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,IAAI;IAEjC,gBAAgB,CAClB,YAAY,EAAE,kBAAkB,EAChC,SAAS,CAAC,EAAE,eAAe,GAC5B,OAAO,CAAC,IAAI,CAAC;YAmBF,kBAAkB;YAsClB,eAAe;CAgChC;AA2FD,wBAAsB,wBAAwB,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAgDxE;AA6BD,MAAM,WAAW,yBAAyB;IACtC,SAAS,EAAE,iBAAiB,CAAA;IAC5B,aAAa,EAAE,8BAA8B,CAAA;IAC7C,OAAO,EAAE,6BAA6B,CAAA;IACtC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACzB;AAID,wBAAsB,+BAA+B,CACjD,MAAM,EAAE,UAAU,GACnB,OAAO,CAAC,yBAAyB,CAAC,CAgBpC"}

package/build/postgres-analytics.js

@@ -0,0 +1,295 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PostgresConversationRepository = exports.PostgresAnalytics = void 0;
+exports.migrateAnalyticsDatabase = migrateAnalyticsDatabase;
+exports.createPostgresAnalyticsServices = createPostgresAnalyticsServices;
+const pg_1 = require("pg");
+const analytics_1 = require("./analytics");
+const postgres_analytics_query_1 = require("./postgres-analytics-query");
+class PostgresAnalytics {
+    database;
+    constructor(database) {
+        this.database = database;
+    }
+    async set(conversationId, agentId, fieldName, value) {
+        (0, analytics_1.assertAnalyticsScalar)(value);
+        const serialized = JSON.stringify(value);
+        const result = await this.database.query(`UPDATE conversations
+             SET analytics = jsonb_set(analytics, ARRAY[$3::text], $4::jsonb, true),
+                 updated_at = now()
+             WHERE conversation_id = $1
+               AND agent_id = $2`, [conversationId, agentId, fieldName, serialized]);
+        assertConversationBelongsToAgent(result.rowCount, conversationId, agentId);
+    }
+    async clear(conversationId, agentId, fieldName) {
+        const result = await this.database.query(`UPDATE conversations
+             SET analytics = analytics - $3::text,
+                 updated_at = now()
+             WHERE conversation_id = $1
+               AND agent_id = $2`, [conversationId, agentId, fieldName]);
+        assertConversationBelongsToAgent(result.rowCount, conversationId, agentId);
+    }
+    async get(conversationId, agentId, fieldName) {
+        const result = await this.database.query(`SELECT analytics ? $3::text AS present,
+                    analytics -> $3::text AS value
+             FROM conversations
+             WHERE conversation_id = $1
+               AND agent_id = $2`, [conversationId, agentId, fieldName]);
+        if (result.rows.length === 0 || !result.rows[0].present) {
+            return undefined;
+        }
+        return result.rows[0].value;
+    }
+    async getSummary(conversationId, agentId) {
+        const result = await this.database.query(`SELECT conversation_id, agent_id, channel, started_at
+             FROM conversations
+             WHERE conversation_id = $1
+               AND agent_id = $2`, [conversationId, agentId]);
+        const row = result.rows[0];
+        if (!row) {
+            return undefined;
+        }
+        return {
+            conversationId: row.conversation_id,
+            agentId: row.agent_id,
+            channel: row.channel,
+            startedAt: row.started_at,
+        };
+    }
+}
+exports.PostgresAnalytics = PostgresAnalytics;
+function assertConversationBelongsToAgent(rowCount, conversationId, agentId) {
+    if (rowCount !== 1) {
+        throw new Error(`Conversation '${conversationId}' does not belong to agent '${agentId}'`);
+    }
+}
+class PostgresConversationRepository {
+    pool;
+    constructor(pool) {
+        this.pool = pool;
+    }
+    async saveConversation(conversation, phoneCall) {
+        const client = await this.pool.connect();
+        try {
+            await client.query('BEGIN');
+            await this.upsertConversation(client, conversation);
+            if (phoneCall) {
+                await this.upsertPhoneCall(client, conversation.conversationId, phoneCall);
+            }
+            await client.query('COMMIT');
+        }
+        catch (error) {
+            await client.query('ROLLBACK');
+            throw error;
+        }
+        finally {
+            client.release();
+        }
+    }
+    async upsertConversation(client, conversation) {
+        const result = await client.query(`INSERT INTO conversations (
+                 conversation_id,
+                 agent_id,
+                 channel,
+                 region,
+                 started_at,
+                 ended_at
+             ) VALUES ($1, $2, $3, $4, $5, $6)
+             ON CONFLICT (conversation_id) DO UPDATE SET
+                 agent_id = COALESCE(conversations.agent_id, EXCLUDED.agent_id),
+                 region = COALESCE(conversations.region, EXCLUDED.region),
+                 ended_at = COALESCE(conversations.ended_at, EXCLUDED.ended_at),
+                 updated_at = now()
+             WHERE conversations.agent_id IS NULL
+                OR conversations.agent_id = EXCLUDED.agent_id`, [
+            conversation.conversationId,
+            conversation.agentId,
+            conversation.channel,
+            conversation.region ?? null,
+            conversation.startedAt,
+            conversation.endedAt ?? null,
+        ]);
+        assertConversationBelongsToAgent(result.rowCount, conversation.conversationId, conversation.agentId);
+    }
+    async upsertPhoneCall(client, conversationId, phoneCall) {
+        await client.query(`INSERT INTO phone_calls (
+                 conversation_id,
+                 phone_number,
+                 recording_url,
+                 ended_reason,
+                 duration_seconds
+             ) VALUES ($1, $2, $3, $4, $5)
+             ON CONFLICT (conversation_id) DO UPDATE SET
+                 phone_number = COALESCE(phone_calls.phone_number, EXCLUDED.phone_number),
+                 recording_url = COALESCE(phone_calls.recording_url, EXCLUDED.recording_url),
+                 ended_reason = COALESCE(phone_calls.ended_reason, EXCLUDED.ended_reason),
+                 duration_seconds = COALESCE(
+                     phone_calls.duration_seconds,
+                     EXCLUDED.duration_seconds
+                 )`, [
+            conversationId,
+            phoneCall.phoneNumber ?? null,
+            phoneCall.recordingUrl ?? null,
+            phoneCall.endedReason ?? null,
+            phoneCall.durationSeconds ?? null,
+        ]);
+    }
+}
+exports.PostgresConversationRepository = PostgresConversationRepository;
+const migrations = [
+    {
+        version: 1,
+        sql: `
+            -- Analytics rationale: This is the channel-neutral parent row and top-level JSONB map.
+            -- Removing it leaves typed values with no lifecycle or common dimensions to attach to.
+            CREATE TABLE conversations (
+                conversation_id text PRIMARY KEY,
+                agent_id text,
+                channel text NOT NULL,
+                region text,
+                started_at timestamptz NOT NULL,
+                ended_at timestamptz,
+                duration_seconds double precision CHECK (
+                    duration_seconds IS NULL OR duration_seconds >= 0
+                ),
+                analytics jsonb NOT NULL DEFAULT '{}'::jsonb CHECK (
+                    jsonb_typeof(analytics) = 'object'
+                ),
+                created_at timestamptz NOT NULL DEFAULT now(),
+                updated_at timestamptz NOT NULL DEFAULT now()
+            );
+
+            -- Analytics rationale: Phone-only data stays in a one-to-one child so text conversations
+            -- do not acquire call-specific columns or assumptions.
+            CREATE TABLE phone_calls (
+                conversation_id text PRIMARY KEY REFERENCES conversations(conversation_id)
+                    ON DELETE CASCADE,
+                phone_number text,
+                recording_url text,
+                ended_reason text
+            );
+
+            -- Analytics rationale: These indexes cover time-ordered listing and its common equality
+            -- filters; without them dashboards and Telescope lists degrade to full table scans.
+            CREATE INDEX conversations_started_at_idx
+                ON conversations (started_at DESC, conversation_id DESC);
+            CREATE INDEX conversations_agent_started_at_idx
+                ON conversations (agent_id, started_at DESC, conversation_id DESC);
+            CREATE INDEX conversations_region_started_at_idx
+                ON conversations (region, started_at DESC, conversation_id DESC);
+            CREATE INDEX conversations_channel_started_at_idx
+                ON conversations (channel, started_at DESC, conversation_id DESC);
+
+            -- Analytics rationale: GIN accelerates JSONB containment filters while the phone index
+            -- supports exact caller lookups joined through the conversation ID.
+            CREATE INDEX conversations_analytics_idx
+                ON conversations USING gin (analytics);
+            CREATE INDEX phone_calls_phone_number_idx
+                ON phone_calls (phone_number, conversation_id);
+        `,
+    },
+    {
+        version: 2,
+        sql: `
+            -- Analytics rationale: Enforce mandatory agent ownership for new and updated rows
+            -- without making deployment fail on historical conversations that have no agent ID.
+            ALTER TABLE conversations
+                ADD CONSTRAINT conversations_agent_id_required
+                CHECK (agent_id IS NOT NULL AND btrim(agent_id) <> '') NOT VALID;
+        `,
+    },
+    {
+        version: 3,
+        sql: `
+            -- Analytics rationale: Duration describes a phone call, not every conversation. Move
+            -- existing call durations before removing the phone-specific column from the parent.
+            ALTER TABLE phone_calls
+                ADD COLUMN duration_seconds double precision CHECK (
+                    duration_seconds IS NULL OR duration_seconds >= 0
+                );
+
+            UPDATE phone_calls AS p
+            SET duration_seconds = c.duration_seconds
+            FROM conversations AS c
+            WHERE p.conversation_id = c.conversation_id
+              AND p.duration_seconds IS NULL
+              AND c.duration_seconds IS NOT NULL;
+
+            ALTER TABLE conversations
+                DROP COLUMN duration_seconds;
+        `,
+    },
+];
+async function migrateAnalyticsDatabase(pool) {
+    const client = await pool.connect();
+    let lockAcquired = false;
+    let migrationFailed = false;
+    try {
+        await client.query("SELECT pg_advisory_lock(hashtext('recombine_analytics_migrations'))");
+        lockAcquired = true;
+        await client.query(`
+            CREATE TABLE IF NOT EXISTS analytics_schema_migrations (
+                version integer PRIMARY KEY,
+                applied_at timestamptz NOT NULL DEFAULT now()
+            )
+        `);
+        for (const migration of migrations) {
+            const applied = await client.query(`SELECT EXISTS (
+                    SELECT 1 FROM analytics_schema_migrations WHERE version = $1
+                ) AS exists`, [migration.version]);
+            if (applied.rows[0].exists) {
+                continue;
+            }
+            await client.query('BEGIN');
+            try {
+                await client.query(migration.sql);
+                await client.query('INSERT INTO analytics_schema_migrations (version) VALUES ($1)', [migration.version]);
+                await client.query('COMMIT');
+            }
+            catch (error) {
+                await client.query('ROLLBACK');
+                throw error;
+            }
+        }
+    }
+    catch (error) {
+        migrationFailed = true;
+        throw error;
+    }
+    finally {
+        await releaseAnalyticsMigrationClient(client, lockAcquired, migrationFailed);
+    }
+}
+async function releaseAnalyticsMigrationClient(client, lockAcquired, migrationFailed) {
+    let discardClient = false;
+    try {
+        if (lockAcquired) {
+            await client.query("SELECT pg_advisory_unlock(hashtext('recombine_analytics_migrations'))");
+        }
+    }
+    catch (error) {
+        discardClient = true;
+        if (!migrationFailed) {
+            throw error;
+        }
+    }
+    finally {
+        client.release(discardClient);
+    }
+}
+async function createPostgresAnalyticsServices(config) {
+    const pool = new pg_1.Pool(config);
+    try {
+        await migrateAnalyticsDatabase(pool);
+    }
+    catch (error) {
+        await pool.end();
+        throw error;
+    }
+    return {
+        analytics: new PostgresAnalytics(pool),
+        conversations: new PostgresConversationRepository(pool),
+        queries: new postgres_analytics_query_1.PostgresAnalyticsQueryService(pool),
+        close: () => pool.end(),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@recombine-ai/platform",
-  "version": "0.2.5",
+  "version": "0.2.6-test.10",
   "description": "Recombine AI: voice agent platform",
   "license": "EULA",
   "author": "recombine.ai",
@@ -17,6 +17,8 @@
   "dependencies": {
     "@recombine-ai/engine": "1.0.0",
     "@recombine-ai/telescope": "^0.3.0",
+    "@types/pg": "8.15.5",
+    "pg": "8.16.3",
     "redis": "5.11.0",
     "zod": "^4.4.3"
   },