@mohamedtebo/convai-platform 1.0.0

package/README.md

@@ -0,0 +1,155 @@
+# @mohamedtebo/convai-platform
+
+> Multi-provider AI conversation SDK — OpenAI Responses/Conversations API, OpenAI Assistants (legacy), and Anthropic Claude — with explicit tool loops, pluggable persistence, and strict Single Responsibility architecture.
+
+---
+
+## Install
+
+```bash
+npm install @mohamedtebo/convai-platform openai
+# optional: add Anthropic support
+npm install @anthropic-ai/sdk
+```
+
+---
+
+## Quick start
+
+```typescript
+import { createPlatformClient, MemoryConversationStore } from '@mohamedtebo/convai-platform';
+
+const client = createPlatformClient({
+  provider: 'openai-responses',
+  apiKey: process.env.OPENAI_API_KEY!,
+  model: 'gpt-4o',
+  conversationStore: new MemoryConversationStore(),
+});
+
+const result = await client.safe.askWithTools({
+  threadKey: 'thread_abc123',
+  chatbotId: 'bot_001',
+  userQuestion: 'Hello, how can I book a ticket?',
+  instructions: 'You are a helpful booking assistant.',
+});
+
+if (result.success) {
+  console.log(result.data.outputText);
+} else {
+  console.error(result.error.hint);
+}
+```
+
+---
+
+## Architecture
+
+```
+src/
+├── index.ts                        ← Public API (exports)
+├── composed/
+│   └── platform-client.ts          ← createPlatformClient() — composed entry point
+├── factory/
+│   └── provider.factory.ts         ← Maps ClientConfig → AIProvider
+├── safe/
+│   └── safe-platform.client.ts     ← SdkResult<T> wrapper (never throws)
+├── types/                          ← Shared interfaces (all ≤ 60 lines)
+│   ├── ask-with-tools.types.ts
+│   ├── client-config.interface.ts
+│   ├── conversation-store.interface.ts
+│   ├── provider.interface.ts
+│   ├── sdk-result.interface.ts
+│   └── tool-handler.interface.ts
+├── errors/                         ← Typed error hierarchy
+│   ├── sdk.error.ts
+│   ├── provider.error.ts
+│   └── tool-loop.error.ts
+├── adapters/
+│   └── memory-conversation.store.ts ← In-memory ConversationStore (for tests)
+└── providers/
+    ├── openai/
+    │   ├── openai-responses.provider.ts  ← NEW API: Responses + Conversations
+    │   ├── openai-assistants.provider.ts ← LEGACY API: beta.threads (deprecated)
+    │   ├── operations/                   ← Single-operation files (createResponse, etc.)
+    │   ├── loops/                        ← Tool loop implementations
+    │   ├── builders/                     ← State builders (resolveConversationId)
+    │   └── utils/                        ← error-mapper, usage-mapper
+    └── anthropic/
+        ├── anthropic.provider.ts
+        ├── loops/claude-tool.loop.ts
+        └── utils/error-mapper.ts
+```
+
+---
+
+## Providers
+
+| Provider | Config `provider` value | Notes |
+|---|---|---|
+| OpenAI Responses + Conversations | `openai-responses` | **Recommended** |
+| OpenAI Assistants (legacy) | `openai-assistants` | Deprecated — use during migration |
+| Anthropic Claude | `anthropic` | Requires `@anthropic-ai/sdk` peer dep |
+
+---
+
+## Pluggable Persistence — ConversationStore
+
+```typescript
+export interface ConversationStore {
+  load(threadKey: string): Promise<ConversationState | null>;
+  save(threadKey: string, state: ConversationState): Promise<void>;
+  create(threadKey: string, conversationId: string): Promise<ConversationState>;
+}
+```
+
+Telbany ships a `MongoConversationStore` inside `api/src/core/convai-adapters/` that reads/writes `Thread.openai_conversation_id` and `Thread.last_response_id`.
+
+---
+
+## Pluggable Tool Handling — ToolHandler
+
+```typescript
+export interface ToolHandler {
+  buildOutput(call: RawToolCall, ctx: ToolHandlerContext): Promise<ToolOutput | undefined>;
+  extractResult(calls: RawToolCall[], outputs: ToolOutput[], ctx: ToolHandlerContext): Promise<unknown>;
+}
+```
+
+Telbany ships a `TelbanyToolHandler` that delegates to existing run-completion services so all business logic stays in `telbany`, not in the SDK.
+
+---
+
+## Result type
+
+```typescript
+const result = await client.safe.askWithTools(params);
+
+if (result.success) {
+  if (result.data.kind === 'text') {
+    console.log(result.data.outputText); // plain AI reply
+  } else {
+    console.log(result.data.toolCallResult); // ticket, product, etc.
+  }
+} else {
+  console.error(result.error.code, result.error.hint);
+}
+```
+
+---
+
+## Build & Publish
+
+```bash
+# inside convai-platform/
+npm install
+npm run build
+npm publish --access public
+```
+
+Requires npm login under `mohamedtebo` account, or `npm login --registry https://registry.npmjs.org`.
+
+---
+
+## License
+
+MIT © mohamedtebo

package/dist/adapters/index.d.ts

@@ -0,0 +1,2 @@
+export { MemoryConversationStore } from './memory-conversation.store';
+//# sourceMappingURL=index.d.ts.map

package/dist/adapters/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAC"}

package/dist/adapters/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryConversationStore = void 0;
+var memory_conversation_store_1 = require("./memory-conversation.store");
+Object.defineProperty(exports, "MemoryConversationStore", { enumerable: true, get: function () { return memory_conversation_store_1.MemoryConversationStore; } });
+//# sourceMappingURL=index.js.map

package/dist/adapters/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":";;;AAAA,yEAAsE;AAA7D,oIAAA,uBAAuB,OAAA"}

package/dist/adapters/memory-conversation.store.d.ts

@@ -0,0 +1,12 @@
+import type { ConversationState, ConversationStore } from '../types/conversation-store.interface';
+/**
+ * In-memory ConversationStore — useful for tests and lightweight apps.
+ * State is lost when the process restarts. Use MongoConversationStore in production.
+ */
+export declare class MemoryConversationStore implements ConversationStore {
+    private readonly map;
+    load(threadKey: string): Promise<ConversationState | null>;
+    save(threadKey: string, state: ConversationState): Promise<void>;
+    create(threadKey: string, conversationId: string): Promise<ConversationState>;
+}
+//# sourceMappingURL=memory-conversation.store.d.ts.map

package/dist/adapters/memory-conversation.store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-conversation.store.d.ts","sourceRoot":"","sources":["../../src/adapters/memory-conversation.store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,uCAAuC,CAAC;AAElG;;;GAGG;AACH,qBAAa,uBAAwB,YAAW,iBAAiB;IAC/D,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAwC;IAEtD,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAI1D,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAIhE,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;CAKpF"}

package/dist/adapters/memory-conversation.store.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryConversationStore = void 0;
+/**
+ * In-memory ConversationStore — useful for tests and lightweight apps.
+ * State is lost when the process restarts. Use MongoConversationStore in production.
+ */
+class MemoryConversationStore {
+    constructor() {
+        this.map = new Map();
+    }
+    async load(threadKey) {
+        return this.map.get(threadKey) ?? null;
+    }
+    async save(threadKey, state) {
+        this.map.set(threadKey, state);
+    }
+    async create(threadKey, conversationId) {
+        const state = { conversationId };
+        this.map.set(threadKey, state);
+        return state;
+    }
+}
+exports.MemoryConversationStore = MemoryConversationStore;
+//# sourceMappingURL=memory-conversation.store.js.map

package/dist/adapters/memory-conversation.store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-conversation.store.js","sourceRoot":"","sources":["../../src/adapters/memory-conversation.store.ts"],"names":[],"mappings":";;;AAEA;;;GAGG;AACH,MAAa,uBAAuB;IAApC;QACmB,QAAG,GAAG,IAAI,GAAG,EAA6B,CAAC;IAe9D,CAAC;IAbC,KAAK,CAAC,IAAI,CAAC,SAAiB;QAC1B,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,IAAI,CAAC;IACzC,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,SAAiB,EAAE,KAAwB;QACpD,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;IACjC,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,SAAiB,EAAE,cAAsB;QACpD,MAAM,KAAK,GAAsB,EAAE,cAAc,EAAE,CAAC;QACpD,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;QAC/B,OAAO,KAAK,CAAC;IACf,CAAC;CACF;AAhBD,0DAgBC"}

package/dist/composed/platform-client.d.ts

@@ -0,0 +1,29 @@
+import type { ClientConfig } from '../types/client-config.interface';
+import type { AskWithToolsParams, AskWithToolsResult } from '../types/ask-with-tools.types';
+import type { SdkResult } from '../types/sdk-result.interface';
+/**
+ * Fully composed SDK client.
+ * Exposes both a raw API (throws on error) and a safe API (returns SdkResult).
+ *
+ * @example
+ * const client = createPlatformClient({
+ *   provider: 'openai-responses',
+ *   apiKey: process.env.OPENAI_API_KEY!,
+ *   model: 'gpt-4o',
+ *   conversationStore: new MongoConversationStore(),
+ *   toolHandler: new TelbanyToolHandler(),
+ * });
+ *
+ * const result = await client.safe.askWithTools({ ... });
+ * if (result.success) console.log(result.data.outputText);
+ */
+export interface PlatformClient {
+    /** Call askWithTools directly — throws SdkError on failure. */
+    askWithTools(params: AskWithToolsParams): Promise<AskWithToolsResult>;
+    /** Safe version — never throws, returns SdkResult<T>. */
+    safe: {
+        askWithTools(params: AskWithToolsParams): Promise<SdkResult<AskWithToolsResult>>;
+    };
+}
+export declare function createPlatformClient(config: ClientConfig): PlatformClient;
+//# sourceMappingURL=platform-client.d.ts.map

package/dist/composed/platform-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-client.d.ts","sourceRoot":"","sources":["../../src/composed/platform-client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAC;AACrE,OAAO,KAAK,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AAC5F,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAI/D;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,cAAc;IAC7B,+DAA+D;IAC/D,YAAY,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IACtE,yDAAyD;IACzD,IAAI,EAAE;QACJ,YAAY,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,SAAS,CAAC,kBAAkB,CAAC,CAAC,CAAC;KAClF,CAAC;CACH;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,YAAY,GAAG,cAAc,CAUzE"}

package/dist/composed/platform-client.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPlatformClient = createPlatformClient;
+const provider_factory_1 = require("../factory/provider.factory");
+const safe_platform_client_1 = require("../safe/safe-platform.client");
+function createPlatformClient(config) {
+    const provider = (0, provider_factory_1.buildProvider)(config);
+    const safeClient = new safe_platform_client_1.SafePlatformClient(provider);
+    return {
+        askWithTools: (params) => provider.askWithTools(params),
+        safe: {
+            askWithTools: (params) => safeClient.askWithTools(params),
+        },
+    };
+}
+//# sourceMappingURL=platform-client.js.map

package/dist/composed/platform-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-client.js","sourceRoot":"","sources":["../../src/composed/platform-client.ts"],"names":[],"mappings":";;AA+BA,oDAUC;AAtCD,kEAA4D;AAC5D,uEAAkE;AA2BlE,SAAgB,oBAAoB,CAAC,MAAoB;IACvD,MAAM,QAAQ,GAAG,IAAA,gCAAa,EAAC,MAAM,CAAC,CAAC;IACvC,MAAM,UAAU,GAAG,IAAI,yCAAkB,CAAC,QAAQ,CAAC,CAAC;IAEpD,OAAO;QACL,YAAY,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,QAAQ,CAAC,YAAY,CAAC,MAAM,CAAC;QACvD,IAAI,EAAE;YACJ,YAAY,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,UAAU,CAAC,YAAY,CAAC,MAAM,CAAC;SAC1D;KACF,CAAC;AACJ,CAAC"}

package/dist/errors/index.d.ts

@@ -0,0 +1,4 @@
+export { SdkError } from './sdk.error';
+export { ProviderError } from './provider.error';
+export { ToolLoopError, NoToolHandlerError } from './tool-loop.error';
+//# sourceMappingURL=index.d.ts.map

package/dist/errors/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/errors/index.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NoToolHandlerError = exports.ToolLoopError = exports.ProviderError = exports.SdkError = void 0;
+var sdk_error_1 = require("./sdk.error");
+Object.defineProperty(exports, "SdkError", { enumerable: true, get: function () { return sdk_error_1.SdkError; } });
+var provider_error_1 = require("./provider.error");
+Object.defineProperty(exports, "ProviderError", { enumerable: true, get: function () { return provider_error_1.ProviderError; } });
+var tool_loop_error_1 = require("./tool-loop.error");
+Object.defineProperty(exports, "ToolLoopError", { enumerable: true, get: function () { return tool_loop_error_1.ToolLoopError; } });
+Object.defineProperty(exports, "NoToolHandlerError", { enumerable: true, get: function () { return tool_loop_error_1.NoToolHandlerError; } });
+//# sourceMappingURL=index.js.map

package/dist/errors/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":";;;AAAA,yCAAuC;AAA9B,qGAAA,QAAQ,OAAA;AACjB,mDAAiD;AAAxC,+GAAA,aAAa,OAAA;AACtB,qDAAsE;AAA7D,gHAAA,aAAa,OAAA;AAAE,qHAAA,kBAAkB,OAAA"}

package/dist/errors/provider.error.d.ts

@@ -0,0 +1,16 @@
+import { SdkError } from './sdk.error';
+/** Error from the AI provider itself (API error, rate limit, auth failure). */
+export declare class ProviderError extends SdkError {
+    readonly statusCode?: number;
+    readonly provider: string;
+    constructor({ provider, code, message, statusCode, retryable, retryAfterMs, requestId, }: {
+        provider: string;
+        code: string;
+        message: string;
+        statusCode?: number;
+        retryable?: boolean;
+        retryAfterMs?: number;
+        requestId?: string;
+    });
+}
+//# sourceMappingURL=provider.error.d.ts.map

package/dist/errors/provider.error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.error.d.ts","sourceRoot":"","sources":["../../src/errors/provider.error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC,+EAA+E;AAC/E,qBAAa,aAAc,SAAQ,QAAQ;IACzC,SAAgB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpC,SAAgB,QAAQ,EAAE,MAAM,CAAC;gBAErB,EACV,QAAQ,EACR,IAAI,EACJ,OAAO,EACP,UAAU,EACV,SAAiB,EACjB,YAAY,EACZ,SAAS,GACV,EAAE;QACD,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,SAAS,CAAC,EAAE,OAAO,CAAC;QACpB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB;CAMF"}

package/dist/errors/provider.error.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProviderError = void 0;
+const sdk_error_1 = require("./sdk.error");
+/** Error from the AI provider itself (API error, rate limit, auth failure). */
+class ProviderError extends sdk_error_1.SdkError {
+    constructor({ provider, code, message, statusCode, retryable = false, retryAfterMs, requestId, }) {
+        super({ code, message, retryable, retryAfterMs, requestId });
+        this.name = 'ProviderError';
+        this.provider = provider;
+        this.statusCode = statusCode;
+    }
+}
+exports.ProviderError = ProviderError;
+//# sourceMappingURL=provider.error.js.map

package/dist/errors/provider.error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.error.js","sourceRoot":"","sources":["../../src/errors/provider.error.ts"],"names":[],"mappings":";;;AAAA,2CAAuC;AAEvC,+EAA+E;AAC/E,MAAa,aAAc,SAAQ,oBAAQ;IAIzC,YAAY,EACV,QAAQ,EACR,IAAI,EACJ,OAAO,EACP,UAAU,EACV,SAAS,GAAG,KAAK,EACjB,YAAY,EACZ,SAAS,GASV;QACC,KAAK,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,SAAS,EAAE,CAAC,CAAC;QAC7D,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;CACF;AA1BD,sCA0BC"}

package/dist/errors/sdk.error.d.ts

@@ -0,0 +1,15 @@
+/** Base SDK error — all thrown errors extend this. */
+export declare class SdkError extends Error {
+    readonly code: string;
+    readonly retryable: boolean;
+    readonly retryAfterMs?: number;
+    readonly requestId?: string;
+    constructor({ code, message, retryable, retryAfterMs, requestId, }: {
+        code: string;
+        message: string;
+        retryable?: boolean;
+        retryAfterMs?: number;
+        requestId?: string;
+    });
+}
+//# sourceMappingURL=sdk.error.d.ts.map

package/dist/errors/sdk.error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk.error.d.ts","sourceRoot":"","sources":["../../src/errors/sdk.error.ts"],"names":[],"mappings":"AAAA,sDAAsD;AACtD,qBAAa,QAAS,SAAQ,KAAK;IACjC,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,SAAgB,SAAS,EAAE,OAAO,CAAC;IACnC,SAAgB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtC,SAAgB,SAAS,CAAC,EAAE,MAAM,CAAC;gBAEvB,EACV,IAAI,EACJ,OAAO,EACP,SAAiB,EACjB,YAAY,EACZ,SAAS,GACV,EAAE;QACD,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,CAAC,EAAE,OAAO,CAAC;QACpB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB;CAQF"}

package/dist/errors/sdk.error.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SdkError = void 0;
+/** Base SDK error — all thrown errors extend this. */
+class SdkError extends Error {
+    constructor({ code, message, retryable = false, retryAfterMs, requestId, }) {
+        super(message);
+        this.name = 'SdkError';
+        this.code = code;
+        this.retryable = retryable;
+        this.retryAfterMs = retryAfterMs;
+        this.requestId = requestId;
+    }
+}
+exports.SdkError = SdkError;
+//# sourceMappingURL=sdk.error.js.map

package/dist/errors/sdk.error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk.error.js","sourceRoot":"","sources":["../../src/errors/sdk.error.ts"],"names":[],"mappings":";;;AAAA,sDAAsD;AACtD,MAAa,QAAS,SAAQ,KAAK;IAMjC,YAAY,EACV,IAAI,EACJ,OAAO,EACP,SAAS,GAAG,KAAK,EACjB,YAAY,EACZ,SAAS,GAOV;QACC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;QACjC,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;CACF;AA1BD,4BA0BC"}

package/dist/errors/tool-loop.error.d.ts

@@ -0,0 +1,11 @@
+import { SdkError } from './sdk.error';
+/** Error thrown when the AI tool loop exceeds the maximum number of turns. */
+export declare class ToolLoopError extends SdkError {
+    readonly turnsExceeded: number;
+    constructor(turnsExceeded: number);
+}
+/** Error thrown when no tool handler is configured but the AI requests tool calls. */
+export declare class NoToolHandlerError extends SdkError {
+    constructor();
+}
+//# sourceMappingURL=tool-loop.error.d.ts.map

package/dist/errors/tool-loop.error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-loop.error.d.ts","sourceRoot":"","sources":["../../src/errors/tool-loop.error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC,8EAA8E;AAC9E,qBAAa,aAAc,SAAQ,QAAQ;IACzC,SAAgB,aAAa,EAAE,MAAM,CAAC;gBAE1B,aAAa,EAAE,MAAM;CASlC;AAED,sFAAsF;AACtF,qBAAa,kBAAmB,SAAQ,QAAQ;;CAS/C"}

package/dist/errors/tool-loop.error.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NoToolHandlerError = exports.ToolLoopError = void 0;
+const sdk_error_1 = require("./sdk.error");
+/** Error thrown when the AI tool loop exceeds the maximum number of turns. */
+class ToolLoopError extends sdk_error_1.SdkError {
+    constructor(turnsExceeded) {
+        super({
+            code: 'TOOL_LOOP_MAX_TURNS_EXCEEDED',
+            message: `Tool loop exceeded ${turnsExceeded} turns without a final answer`,
+            retryable: false,
+        });
+        this.name = 'ToolLoopError';
+        this.turnsExceeded = turnsExceeded;
+    }
+}
+exports.ToolLoopError = ToolLoopError;
+/** Error thrown when no tool handler is configured but the AI requests tool calls. */
+class NoToolHandlerError extends sdk_error_1.SdkError {
+    constructor() {
+        super({
+            code: 'NO_TOOL_HANDLER_CONFIGURED',
+            message: 'AI requested tool calls but no ToolHandler was configured in ClientConfig',
+            retryable: false,
+        });
+        this.name = 'NoToolHandlerError';
+    }
+}
+exports.NoToolHandlerError = NoToolHandlerError;
+//# sourceMappingURL=tool-loop.error.js.map

package/dist/errors/tool-loop.error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-loop.error.js","sourceRoot":"","sources":["../../src/errors/tool-loop.error.ts"],"names":[],"mappings":";;;AAAA,2CAAuC;AAEvC,8EAA8E;AAC9E,MAAa,aAAc,SAAQ,oBAAQ;IAGzC,YAAY,aAAqB;QAC/B,KAAK,CAAC;YACJ,IAAI,EAAE,8BAA8B;YACpC,OAAO,EAAE,sBAAsB,aAAa,+BAA+B;YAC3E,SAAS,EAAE,KAAK;SACjB,CAAC,CAAC;QACH,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,aAAa,GAAG,aAAa,CAAC;IACrC,CAAC;CACF;AAZD,sCAYC;AAED,sFAAsF;AACtF,MAAa,kBAAmB,SAAQ,oBAAQ;IAC9C;QACE,KAAK,CAAC;YACJ,IAAI,EAAE,4BAA4B;YAClC,OAAO,EAAE,2EAA2E;YACpF,SAAS,EAAE,KAAK;SACjB,CAAC,CAAC;QACH,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AATD,gDASC"}

package/dist/factory/index.d.ts

@@ -0,0 +1,2 @@
+export { buildProvider } from './provider.factory';
+//# sourceMappingURL=index.d.ts.map

package/dist/factory/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/factory/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/factory/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildProvider = void 0;
+var provider_factory_1 = require("./provider.factory");
+Object.defineProperty(exports, "buildProvider", { enumerable: true, get: function () { return provider_factory_1.buildProvider; } });
+//# sourceMappingURL=index.js.map

package/dist/factory/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/factory/index.ts"],"names":[],"mappings":";;;AAAA,uDAAmD;AAA1C,iHAAA,aAAa,OAAA"}

package/dist/factory/provider.factory.d.ts

@@ -0,0 +1,8 @@
+import type { ClientConfig } from '../types/client-config.interface';
+import type { AIProvider } from '../types/provider.interface';
+/**
+ * Build the correct AIProvider implementation from a ClientConfig.
+ * Add new providers here without touching any other file.
+ */
+export declare function buildProvider(config: ClientConfig): AIProvider;
+//# sourceMappingURL=provider.factory.d.ts.map

package/dist/factory/provider.factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.factory.d.ts","sourceRoot":"","sources":["../../src/factory/provider.factory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAC;AACrE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAM9D;;;GAGG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,YAAY,GAAG,UAAU,CAoC9D"}

package/dist/factory/provider.factory.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildProvider = buildProvider;
+const openai_responses_provider_1 = require("../providers/openai/openai-responses.provider");
+const openai_assistants_provider_1 = require("../providers/openai/openai-assistants.provider");
+const anthropic_provider_1 = require("../providers/anthropic/anthropic.provider");
+const memory_conversation_store_1 = require("../adapters/memory-conversation.store");
+/**
+ * Build the correct AIProvider implementation from a ClientConfig.
+ * Add new providers here without touching any other file.
+ */
+function buildProvider(config) {
+    switch (config.provider) {
+        case 'openai-responses': {
+            const store = config.conversationStore ?? new memory_conversation_store_1.MemoryConversationStore();
+            return new openai_responses_provider_1.OpenAIResponsesProvider({
+                apiKey: config.apiKey,
+                model: config.model ?? 'gpt-4o',
+                conversationStore: store,
+                toolHandler: config.toolHandler,
+                maxRetries: config.maxRetries,
+                timeoutMs: config.timeoutMs,
+            });
+        }
+        case 'openai-assistants': {
+            return new openai_assistants_provider_1.OpenAIAssistantsProvider({
+                apiKey: config.apiKey,
+                assistantId: config.model ?? '',
+                model: 'gpt-4o',
+                toolHandler: config.toolHandler,
+                maxRetries: config.maxRetries,
+                timeoutMs: config.timeoutMs,
+            });
+        }
+        case 'anthropic': {
+            return new anthropic_provider_1.AnthropicProvider({
+                apiKey: config.apiKey,
+                model: config.model ?? 'claude-opus-4-5',
+                toolHandler: config.toolHandler,
+                maxRetries: config.maxRetries,
+            });
+        }
+        default: {
+            const exhaustive = config.provider;
+            throw new Error(`Unknown provider: ${String(exhaustive)}`);
+        }
+    }
+}
+//# sourceMappingURL=provider.factory.js.map

package/dist/factory/provider.factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.factory.js","sourceRoot":"","sources":["../../src/factory/provider.factory.ts"],"names":[],"mappings":";;AAWA,sCAoCC;AA7CD,6FAAwF;AACxF,+FAA0F;AAC1F,kFAA8E;AAC9E,qFAAgF;AAEhF;;;GAGG;AACH,SAAgB,aAAa,CAAC,MAAoB;IAChD,QAAQ,MAAM,CAAC,QAAQ,EAAE,CAAC;QACxB,KAAK,kBAAkB,CAAC,CAAC,CAAC;YACxB,MAAM,KAAK,GAAG,MAAM,CAAC,iBAAiB,IAAI,IAAI,mDAAuB,EAAE,CAAC;YACxE,OAAO,IAAI,mDAAuB,CAAC;gBACjC,MAAM,EAAE,MAAM,CAAC,MAAM;gBACrB,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,QAAQ;gBAC/B,iBAAiB,EAAE,KAAK;gBACxB,WAAW,EAAE,MAAM,CAAC,WAAW;gBAC/B,UAAU,EAAE,MAAM,CAAC,UAAU;gBAC7B,SAAS,EAAE,MAAM,CAAC,SAAS;aAC5B,CAAC,CAAC;QACL,CAAC;QACD,KAAK,mBAAmB,CAAC,CAAC,CAAC;YACzB,OAAO,IAAI,qDAAwB,CAAC;gBAClC,MAAM,EAAE,MAAM,CAAC,MAAM;gBACrB,WAAW,EAAE,MAAM,CAAC,KAAK,IAAI,EAAE;gBAC/B,KAAK,EAAE,QAAQ;gBACf,WAAW,EAAE,MAAM,CAAC,WAAW;gBAC/B,UAAU,EAAE,MAAM,CAAC,UAAU;gBAC7B,SAAS,EAAE,MAAM,CAAC,SAAS;aAC5B,CAAC,CAAC;QACL,CAAC;QACD,KAAK,WAAW,CAAC,CAAC,CAAC;YACjB,OAAO,IAAI,sCAAiB,CAAC;gBAC3B,MAAM,EAAE,MAAM,CAAC,MAAM;gBACrB,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,iBAAiB;gBACxC,WAAW,EAAE,MAAM,CAAC,WAAW;gBAC/B,UAAU,EAAE,MAAM,CAAC,UAAU;aAC9B,CAAC,CAAC;QACL,CAAC;QACD,OAAO,CAAC,CAAC,CAAC;YACR,MAAM,UAAU,GAAU,MAAM,CAAC,QAAQ,CAAC;YAC1C,MAAM,IAAI,KAAK,CAAC,qBAAqB,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;QAC7D,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export { createPlatformClient } from './composed/platform-client';
+export type { PlatformClient } from './composed/platform-client';
+export type { ClientConfig, ProviderType, AIProvider, AskWithToolsParams, AskWithToolsResult, TextResult, ToolResult, UsageMetrics, ConversationState, ConversationStore, RawToolCall, ToolOutput, ToolHandler, ToolHandlerContext, SdkResult, FormattedError, } from './types';
+export { ok, fail } from './types';
+export { SdkError } from './errors/sdk.error';
+export { ProviderError } from './errors/provider.error';
+export { ToolLoopError, NoToolHandlerError } from './errors/tool-loop.error';
+export { MemoryConversationStore } from './adapters/memory-conversation.store';
+export { OpenAIResponsesProvider } from './providers/openai/openai-responses.provider';
+export { OpenAIAssistantsProvider } from './providers/openai/openai-assistants.provider';
+export { AnthropicProvider } from './providers/anthropic/anthropic.provider';
+export { SafePlatformClient } from './safe/safe-platform.client';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAClE,YAAY,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAGjE,YAAY,EACV,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,kBAAkB,EAClB,kBAAkB,EAClB,UAAU,EACV,UAAU,EACV,YAAY,EACZ,iBAAiB,EACjB,iBAAiB,EACjB,WAAW,EACX,UAAU,EACV,WAAW,EACX,kBAAkB,EAClB,SAAS,EACT,cAAc,GACf,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAGnC,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAG7E,OAAO,EAAE,uBAAuB,EAAE,MAAM,sCAAsC,CAAC;AAG/E,OAAO,EAAE,uBAAuB,EAAE,MAAM,8CAA8C,CAAC;AACvF,OAAO,EAAE,wBAAwB,EAAE,MAAM,+CAA+C,CAAC;AACzF,OAAO,EAAE,iBAAiB,EAAE,MAAM,0CAA0C,CAAC;AAG7E,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC"}

package/dist/index.js

@@ -0,0 +1,34 @@
+"use strict";
+// ──────────────────────────────────────────────────────────────────────
+// @mohamedtebo/convai-platform — public API
+// ──────────────────────────────────────────────────────────────────────
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SafePlatformClient = exports.AnthropicProvider = exports.OpenAIAssistantsProvider = exports.OpenAIResponsesProvider = exports.MemoryConversationStore = exports.NoToolHandlerError = exports.ToolLoopError = exports.ProviderError = exports.SdkError = exports.fail = exports.ok = exports.createPlatformClient = void 0;
+// Primary composed entry point
+var platform_client_1 = require("./composed/platform-client");
+Object.defineProperty(exports, "createPlatformClient", { enumerable: true, get: function () { return platform_client_1.createPlatformClient; } });
+var types_1 = require("./types");
+Object.defineProperty(exports, "ok", { enumerable: true, get: function () { return types_1.ok; } });
+Object.defineProperty(exports, "fail", { enumerable: true, get: function () { return types_1.fail; } });
+// Errors
+var sdk_error_1 = require("./errors/sdk.error");
+Object.defineProperty(exports, "SdkError", { enumerable: true, get: function () { return sdk_error_1.SdkError; } });
+var provider_error_1 = require("./errors/provider.error");
+Object.defineProperty(exports, "ProviderError", { enumerable: true, get: function () { return provider_error_1.ProviderError; } });
+var tool_loop_error_1 = require("./errors/tool-loop.error");
+Object.defineProperty(exports, "ToolLoopError", { enumerable: true, get: function () { return tool_loop_error_1.ToolLoopError; } });
+Object.defineProperty(exports, "NoToolHandlerError", { enumerable: true, get: function () { return tool_loop_error_1.NoToolHandlerError; } });
+// Built-in adapters
+var memory_conversation_store_1 = require("./adapters/memory-conversation.store");
+Object.defineProperty(exports, "MemoryConversationStore", { enumerable: true, get: function () { return memory_conversation_store_1.MemoryConversationStore; } });
+// Individual providers (for consumers who want fine-grained control)
+var openai_responses_provider_1 = require("./providers/openai/openai-responses.provider");
+Object.defineProperty(exports, "OpenAIResponsesProvider", { enumerable: true, get: function () { return openai_responses_provider_1.OpenAIResponsesProvider; } });
+var openai_assistants_provider_1 = require("./providers/openai/openai-assistants.provider");
+Object.defineProperty(exports, "OpenAIAssistantsProvider", { enumerable: true, get: function () { return openai_assistants_provider_1.OpenAIAssistantsProvider; } });
+var anthropic_provider_1 = require("./providers/anthropic/anthropic.provider");
+Object.defineProperty(exports, "AnthropicProvider", { enumerable: true, get: function () { return anthropic_provider_1.AnthropicProvider; } });
+// Safe layer (standalone)
+var safe_platform_client_1 = require("./safe/safe-platform.client");
+Object.defineProperty(exports, "SafePlatformClient", { enumerable: true, get: function () { return safe_platform_client_1.SafePlatformClient; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA,yEAAyE;AACzE,4CAA4C;AAC5C,yEAAyE;;;AAEzE,+BAA+B;AAC/B,8DAAkE;AAAzD,uHAAA,oBAAoB,OAAA;AAsB7B,iCAAmC;AAA1B,2FAAA,EAAE,OAAA;AAAE,6FAAA,IAAI,OAAA;AAEjB,SAAS;AACT,gDAA8C;AAArC,qGAAA,QAAQ,OAAA;AACjB,0DAAwD;AAA/C,+GAAA,aAAa,OAAA;AACtB,4DAA6E;AAApE,gHAAA,aAAa,OAAA;AAAE,qHAAA,kBAAkB,OAAA;AAE1C,oBAAoB;AACpB,kFAA+E;AAAtE,oIAAA,uBAAuB,OAAA;AAEhC,qEAAqE;AACrE,0FAAuF;AAA9E,oIAAA,uBAAuB,OAAA;AAChC,4FAAyF;AAAhF,sIAAA,wBAAwB,OAAA;AACjC,+EAA6E;AAApE,uHAAA,iBAAiB,OAAA;AAE1B,0BAA0B;AAC1B,oEAAiE;AAAxD,0HAAA,kBAAkB,OAAA"}

package/dist/providers/anthropic/anthropic.provider.d.ts

@@ -0,0 +1,22 @@
+import type { AIProvider } from '../../types/provider.interface';
+import type { AskWithToolsParams, AskWithToolsResult } from '../../types/ask-with-tools.types';
+import type { ToolHandler } from '../../types/tool-handler.interface';
+export interface AnthropicProviderConfig {
+    apiKey: string;
+    model: string;
+    toolHandler?: ToolHandler;
+    maxRetries?: number;
+}
+/**
+ * Anthropic Claude provider.
+ * Implements the same AIProvider interface as the OpenAI providers
+ * so telbany can swap providers by changing a single config field.
+ */
+export declare class AnthropicProvider implements AIProvider {
+    private readonly anthropic;
+    private readonly model;
+    private readonly handler?;
+    constructor(config: AnthropicProviderConfig);
+    askWithTools(params: AskWithToolsParams): Promise<AskWithToolsResult>;
+}
+//# sourceMappingURL=anthropic.provider.d.ts.map

package/dist/providers/anthropic/anthropic.provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"anthropic.provider.d.ts","sourceRoot":"","sources":["../../../src/providers/anthropic/anthropic.provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAC;AACjE,OAAO,KAAK,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AAC/F,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oCAAoC,CAAC;AAItE,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,qBAAa,iBAAkB,YAAW,UAAU;IAClD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAU;IACpC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAc;gBAE3B,MAAM,EAAE,uBAAuB;IAYrC,YAAY,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,CAAC;CAU5E"}