@mohamedtebo/convai-platform 1.0.0 → 1.0.4

package/dist/providers/openai/operations/create-response.operation.js

@@ -7,12 +7,21 @@ async function createResponse(openai, params) {
     const { conversationId, previousResponseId, model, instructions, userQuestion, tools, vectorStoreIds, } = params;
     const body = {
         model,
-        conversation_id: conversationId,
         instructions,
-        input: userQuestion,
-        ...(previousResponseId ? { previous_response_id: previousResponseId } : {}),
-        ...(tools?.length ? { tools } : {}),
+        // Responses API requires an array of message objects, not a plain string
+        input: [{ role: 'user', content: userQuestion }],
+        store: true,
     };
+    // Pass existing conversation or chain via previous_response_id — never both
+    if (conversationId) {
+        body['conversation'] = conversationId;
+    }
+    else if (previousResponseId) {
+        body['previous_response_id'] = previousResponseId;
+    }
+    if (tools?.length) {
+        body['tools'] = tools;
+    }
     if (vectorStoreIds?.length) {
         body['tool_resources'] = { file_search: { vector_store_ids: vectorStoreIds } };
     }

package/dist/providers/openai/operations/create-response.operation.js.map

@@ -1 +1 @@
-{"version":3,"file":"create-response.operation.js","sourceRoot":"","sources":["../../../../src/providers/openai/operations/create-response.operation.ts"],"names":[],"mappings":";;AAcA,wCAiCC;AA9CD,wDAAuD;AAYvD,mFAAmF;AAC5E,KAAK,UAAU,cAAc,CAClC,MAAc,EACd,MAA4B;IAE5B,MAAM,EACJ,cAAc,EACd,kBAAkB,EAClB,KAAK,EACL,YAAY,EACZ,YAAY,EACZ,KAAK,EACL,cAAc,GACf,GAAG,MAAM,CAAC;IAEX,MAAM,IAAI,GAA4B;QACpC,KAAK;QACL,eAAe,EAAE,cAAc;QAC/B,YAAY;QACZ,KAAK,EAAE,YAAY;QACnB,GAAG,CAAC,kBAAkB,CAAC,CAAC,CAAC,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3E,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACpC,CAAC;IAEF,IAAI,cAAc,EAAE,MAAM,EAAE,CAAC;QAC3B,IAAI,CAAC,gBAAgB,CAAC,GAAG,EAAE,WAAW,EAAE,EAAE,gBAAgB,EAAE,cAAc,EAAE,EAAE,CAAC;IACjF,CAAC;IAED,IAAI,CAAC;QACH,8DAA8D;QAC9D,OAAO,MAAO,MAAc,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACtD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAA,6BAAc,EAAC,GAAG,CAAC,CAAC;IAC5B,CAAC;AACH,CAAC"}
+{"version":3,"file":"create-response.operation.js","sourceRoot":"","sources":["../../../../src/providers/openai/operations/create-response.operation.ts"],"names":[],"mappings":";;AAeA,wCA2CC;AAzDD,wDAAuD;AAavD,mFAAmF;AAC5E,KAAK,UAAU,cAAc,CAClC,MAAc,EACd,MAA4B;IAE5B,MAAM,EACJ,cAAc,EACd,kBAAkB,EAClB,KAAK,EACL,YAAY,EACZ,YAAY,EACZ,KAAK,EACL,cAAc,GACf,GAAG,MAAM,CAAC;IAEX,MAAM,IAAI,GAA4B;QACpC,KAAK;QACL,YAAY;QACZ,yEAAyE;QACzE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE,CAAC;QAChD,KAAK,EAAE,IAAI;KACZ,CAAC;IAEF,4EAA4E;IAC5E,IAAI,cAAc,EAAE,CAAC;QACnB,IAAI,CAAC,cAAc,CAAC,GAAG,cAAc,CAAC;IACxC,CAAC;SAAM,IAAI,kBAAkB,EAAE,CAAC;QAC9B,IAAI,CAAC,sBAAsB,CAAC,GAAG,kBAAkB,CAAC;IACpD,CAAC;IAED,IAAI,KAAK,EAAE,MAAM,EAAE,CAAC;QAClB,IAAI,CAAC,OAAO,CAAC,GAAG,KAAK,CAAC;IACxB,CAAC;IAED,IAAI,cAAc,EAAE,MAAM,EAAE,CAAC;QAC3B,IAAI,CAAC,gBAAgB,CAAC,GAAG,EAAE,WAAW,EAAE,EAAE,gBAAgB,EAAE,cAAc,EAAE,EAAE,CAAC;IACjF,CAAC;IAED,IAAI,CAAC;QACH,8DAA8D;QAC9D,OAAO,MAAO,MAAc,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACtD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAA,6BAAc,EAAC,GAAG,CAAC,CAAC;IAC5B,CAAC;AACH,CAAC"}

package/dist/providers/openai/operations/submit-tool-outputs.operation.d.ts

@@ -2,7 +2,8 @@ import type OpenAI from 'openai';
 import type { ToolOutput } from '../../../types/tool-handler.interface';
 export interface SubmitToolOutputsParams {
     previousResponseId: string;
-    conversationId: string;
+    /** Used only when previous_response_id is not set — never send both. */
+    conversationId?: string;
     model: string;
     instructions: string;
     toolOutputs: ToolOutput[];
@@ -10,8 +11,8 @@ export interface SubmitToolOutputsParams {
 }
 /**
  * Resumes the AI response by submitting tool call outputs.
- * In the Responses API this is a new responses.create call with the previous_response_id set
- * and the tool results embedded in the input array.
+ * OpenAI accepts either `conversation` OR `previous_response_id`, never both.
+ * Tool continuations chain via previous_response_id (matches telbany legacy when no conversation).
  */
 export declare function submitToolOutputs(openai: OpenAI, params: SubmitToolOutputsParams): Promise<unknown>;
 //# sourceMappingURL=submit-tool-outputs.operation.d.ts.map

package/dist/providers/openai/operations/submit-tool-outputs.operation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"submit-tool-outputs.operation.d.ts","sourceRoot":"","sources":["../../../../src/providers/openai/operations/submit-tool-outputs.operation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AACjC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uCAAuC,CAAC;AAGxE,MAAM,WAAW,uBAAuB;IACtC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,KAAK,CAAC,EAAE,OAAO,EAAE,CAAC;CACnB;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,uBAAuB,GAC9B,OAAO,CAAC,OAAO,CAAC,CAwBlB"}
+{"version":3,"file":"submit-tool-outputs.operation.d.ts","sourceRoot":"","sources":["../../../../src/providers/openai/operations/submit-tool-outputs.operation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AACjC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uCAAuC,CAAC;AAGxE,MAAM,WAAW,uBAAuB;IACtC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,wEAAwE;IACxE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,KAAK,CAAC,EAAE,OAAO,EAAE,CAAC;CACnB;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,uBAAuB,GAC9B,OAAO,CAAC,OAAO,CAAC,CA8BlB"}

package/dist/providers/openai/operations/submit-tool-outputs.operation.js

@@ -4,24 +4,30 @@ exports.submitToolOutputs = submitToolOutputs;
 const error_mapper_1 = require("../utils/error-mapper");
 /**
  * Resumes the AI response by submitting tool call outputs.
- * In the Responses API this is a new responses.create call with the previous_response_id set
- * and the tool results embedded in the input array.
+ * OpenAI accepts either `conversation` OR `previous_response_id`, never both.
+ * Tool continuations chain via previous_response_id (matches telbany legacy when no conversation).
  */
 async function submitToolOutputs(openai, params) {
     const { previousResponseId, conversationId, model, instructions, toolOutputs, tools } = params;
     const toolResultMessages = toolOutputs.map((o) => ({
-        type: 'tool_result',
-        tool_use_id: o.call_id,
-        content: o.output,
+        type: 'function_call_output',
+        call_id: o.call_id,
+        output: o.output,
     }));
     const body = {
         model,
-        conversation_id: conversationId,
         instructions,
-        previous_response_id: previousResponseId,
         input: toolResultMessages,
+        store: true,
         ...(tools?.length ? { tools } : {}),
     };
+    // Mutually exclusive — prefer chaining from the function-call response
+    if (previousResponseId) {
+        body['previous_response_id'] = previousResponseId;
+    }
+    else if (conversationId) {
+        body['conversation'] = conversationId;
+    }
     try {
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         return await openai.responses.create(body);

package/dist/providers/openai/operations/submit-tool-outputs.operation.js.map

@@ -1 +1 @@
-{"version":3,"file":"submit-tool-outputs.operation.js","sourceRoot":"","sources":["../../../../src/providers/openai/operations/submit-tool-outputs.operation.ts"],"names":[],"mappings":";;AAkBA,8CA2BC;AA3CD,wDAAuD;AAWvD;;;;GAIG;AACI,KAAK,UAAU,iBAAiB,CACrC,MAAc,EACd,MAA+B;IAE/B,MAAM,EAAE,kBAAkB,EAAE,cAAc,EAAE,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,KAAK,EAAE,GAAG,MAAM,CAAC;IAE/F,MAAM,kBAAkB,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACjD,IAAI,EAAE,aAAa;QACnB,WAAW,EAAE,CAAC,CAAC,OAAO;QACtB,OAAO,EAAE,CAAC,CAAC,MAAM;KAClB,CAAC,CAAC,CAAC;IAEJ,MAAM,IAAI,GAA4B;QACpC,KAAK;QACL,eAAe,EAAE,cAAc;QAC/B,YAAY;QACZ,oBAAoB,EAAE,kBAAkB;QACxC,KAAK,EAAE,kBAAkB;QACzB,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACpC,CAAC;IAEF,IAAI,CAAC;QACH,8DAA8D;QAC9D,OAAO,MAAO,MAAc,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACtD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAA,6BAAc,EAAC,GAAG,CAAC,CAAC;IAC5B,CAAC;AACH,CAAC"}
+{"version":3,"file":"submit-tool-outputs.operation.js","sourceRoot":"","sources":["../../../../src/providers/openai/operations/submit-tool-outputs.operation.ts"],"names":[],"mappings":";;AAmBA,8CAiCC;AAlDD,wDAAuD;AAYvD;;;;GAIG;AACI,KAAK,UAAU,iBAAiB,CACrC,MAAc,EACd,MAA+B;IAE/B,MAAM,EAAE,kBAAkB,EAAE,cAAc,EAAE,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,KAAK,EAAE,GAAG,MAAM,CAAC;IAE/F,MAAM,kBAAkB,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACjD,IAAI,EAAE,sBAAsB;QAC5B,OAAO,EAAE,CAAC,CAAC,OAAO;QAClB,MAAM,EAAE,CAAC,CAAC,MAAM;KACjB,CAAC,CAAC,CAAC;IAEJ,MAAM,IAAI,GAA4B;QACpC,KAAK;QACL,YAAY;QACZ,KAAK,EAAE,kBAAkB;QACzB,KAAK,EAAE,IAAI;QACX,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACpC,CAAC;IAEF,uEAAuE;IACvE,IAAI,kBAAkB,EAAE,CAAC;QACvB,IAAI,CAAC,sBAAsB,CAAC,GAAG,kBAAkB,CAAC;IACpD,CAAC;SAAM,IAAI,cAAc,EAAE,CAAC;QAC1B,IAAI,CAAC,cAAc,CAAC,GAAG,cAAc,CAAC;IACxC,CAAC;IAED,IAAI,CAAC;QACH,8DAA8D;QAC9D,OAAO,MAAO,MAAc,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACtD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAA,6BAAc,EAAC,GAAG,CAAC,CAAC;IAC5B,CAAC;AACH,CAAC"}

package/docs/API_INTEGRATION.md

@@ -0,0 +1,385 @@
+# @mohamedtebo/convai-platform — API Integration Guide
+
+Integration of this SDK into the **api** service for OpenAI **Responses + Conversations**, with MongoDB persistence and custom function tools.
+
+> **Package:** `@mohamedtebo/convai-platform`  
+> **Consumer adapters:** `api/src/core/convai-adapters/` (in the api monorepo)
+
+---
+
+## Table of contents
+
+1. [Architecture](#architecture)
+2. [Environment variables](#environment-variables)
+3. [Setup examples](#setup-examples)
+4. [Production rollout & migration scripts](#production-rollout--migration-scripts)
+5. [User message → AI reply lifecycle](#user-message--ai-reply-lifecycle)
+6. [WhatsApp integration cycle](#whatsapp-integration-cycle)
+7. [Facebook Messenger integration cycle](#facebook-messenger-integration-cycle)
+8. [Tool loop lifecycle](#tool-loop-lifecycle)
+9. [Vision (images)](#vision-images)
+10. [Troubleshooting](#troubleshooting)
+11. [Publish this package](#publish-this-package)
+
+---
+
+## Architecture
+
+```
+Widget / Channel
+       │
+       ▼
+api (Socket: ask-question)
+       │
+       ▼
+ThreadRunQueue ──► getBotMessageForResponses()
+       │
+       ├── AI_USE_CONVAI_SDK=false  → legacy response-tool-loop (deprecated)
+       │
+       └── AI_USE_CONVAI_SDK=true   → getBotMessageForResponsesViaSdk()
+                │
+                ├── buildResponseConfig()        ← instructions, tools, model
+                ├── enrichResponsesUserQuestion() ← vision when enabled
+                ├── getAIPlatformClient()        ← cached SDK client
+                └── sdkClient.safe.askWithTools()
+                         │
+                         ├── MongoConversationStore
+                         ├── ApiToolHandler       ← tickets, calendar, custom functions
+                         └── OpenAI Responses API tool loop (this SDK)
+                │
+                ▼
+AssistantResponseService / handleFinalResponseForResponses
+       │
+       ▼
+Socket BOT_REPLIED → widget
+```
+
+### api adapter files
+
+| File | Role |
+|------|------|
+| `api/src/core/convai-adapters/ai-platform.factory.ts` | Cached `PlatformClient` |
+| `api/src/core/convai-adapters/mongo-conversation.store.ts` | `Thread.openai_conversation_id` / `last_response_id` |
+| `api/src/core/convai-adapters/telbany-tool.handler.ts` | **ApiToolHandler** → `run-completion.service` |
+| `api/src/core/convai-adapters/tool-loop-context.loader.ts` | Chatbot functions + org context |
+| `api/src/core/services/ai/providers/openai/response-config.builder.ts` | Instructions, tools, model |
+| `api/src/api/v1/routes/openai/helpers.ts` | `getBotMessageForResponses()` |
+
+### SDK files (this package)
+
+| File | Role |
+|------|------|
+| `src/composed/platform-client.ts` | `createPlatformClient()` |
+| `src/providers/openai/openai-responses.provider.ts` | Responses provider |
+| `src/providers/openai/loops/responses-tool.loop.ts` | Tool loop (max 10 turns) |
+| `src/providers/openai/operations/create-response.operation.ts` | `responses.create` |
+| `src/providers/openai/operations/submit-tool-outputs.operation.ts` | Tool output submit |
+| `src/types/conversation-store.interface.ts` | `ConversationStore` contract |
+| `src/types/tool-handler.interface.ts` | `ToolHandler` contract |
+
+---
+
+## Environment variables
+
+In **api** `.env`:
+
+```env
+AI_BACKEND_DEFAULT=assistants
+AI_RESPONSES_MODEL_DEFAULT=gpt-4o-mini
+AI_USE_CONVAI_SDK=false
+OPENAI_API_KEY=sk-...
+```
+
+| Variable | Values | When to change |
+|----------|--------|----------------|
+| `AI_BACKEND_DEFAULT` | `assistants` \| `responses` | After migration steps 01–04 |
+| `AI_USE_CONVAI_SDK` | `true` \| `false` | After parity test (step 06) on staging |
+| `AI_RESPONSES_MODEL_DEFAULT` | e.g. `gpt-4o-mini` | Optional default model |
+
+MongoDB per chatbot:
+
+| Field | Purpose |
+|-------|---------|
+| `chatbots.ai_backend` | `assistants` or `responses` |
+| `generalsettings.openai_vision_enabled` | Image analysis before model call |
+
+---
+
+## Setup examples
+
+### Install
+
+```bash
+npm install @mohamedtebo/convai-platform openai
+```
+
+### Standalone SDK
+
+```typescript
+import { createPlatformClient, MemoryConversationStore } from '@mohamedtebo/convai-platform';
+
+const client = createPlatformClient({
+  provider: 'openai-responses',
+  apiKey: process.env.OPENAI_API_KEY!,
+  model: 'gpt-4o-mini',
+  conversationStore: new MemoryConversationStore(),
+});
+
+const result = await client.safe.askWithTools({
+  threadKey: 'resp_conv_abc123',
+  chatbotId: '507f1f77bcf86cd799439011',
+  organizationId: 'org_001',
+  userQuestion: 'I want to book a ticket for tomorrow',
+  instructions: 'You are a helpful assistant.',
+  tools: [],
+});
+
+if (result.success && result.data.kind === 'text') {
+  console.log(result.data.outputText);
+}
+```
+
+### With api adapters (production)
+
+```typescript
+import { getAIPlatformClient } from './core/convai-adapters';
+
+const client = getAIPlatformClient({ backend: 'openai-responses', model: 'gpt-4o-mini' });
+
+const result = await client.safe.askWithTools({
+  threadKey: threadId,
+  chatbotId,
+  organizationId,
+  userQuestion: enrichedQuestion,
+  instructions: params.instructions,
+  tools: params.tools,
+  vectorStoreIds: vectorStoreId ? [vectorStoreId] : undefined,
+  model: params.model,
+  mediaUrl,
+});
+```
+
+### Custom ConversationStore + ToolHandler
+
+```typescript
+import { createPlatformClient } from '@mohamedtebo/convai-platform';
+import type { ConversationStore, ToolHandler } from '@mohamedtebo/convai-platform';
+
+const client = createPlatformClient({
+  provider: 'openai-responses',
+  apiKey: process.env.OPENAI_API_KEY!,
+  model: 'gpt-4o',
+  conversationStore: myStore as ConversationStore,
+  toolHandler: myHandler as ToolHandler,
+});
+```
+
+---
+
+## Production rollout & migration scripts
+
+Run from the **api** service root (`MONGO_URI`, `OPENAI_API_KEY` required).
+
+### Steps (must run before production Responses + SDK)
+
+| Step | Purpose | Changes DB? |
+|------|---------|-------------|
+| **01** | Audit chatbots, assistant IDs, vector stores | No |
+| **02** | Verify `General.system_prompt` for all chatbots | Conditionally |
+| **03** | Backfill `openai_conversation_id` from Assistants threads | Yes |
+| **04** | Verify threads missing conversation ID | No |
+| **05** | Set `ai_backend=responses` on pilot chatbots | Yes |
+| **06** | Golden-path parity Q&A test | API calls only |
+
+### Commands
+
+```bash
+cd api
+
+# Audit
+AI_MIGRATION_DRY_RUN=true MIGRATION_STEPS=01,02 \
+  ts-node -r tsconfig-paths/register migrations/openai-responses/run-openai-responses-migration.ts
+
+# Backfill (active threads, 90 days)
+AI_MIGRATION_DRY_RUN=false MIGRATION_STEPS=03 \
+  ts-node -r tsconfig-paths/register migrations/openai-responses/run-openai-responses-migration.ts
+
+# Verify
+AI_MIGRATION_DRY_RUN=false MIGRATION_STEPS=04 \
+  ts-node -r tsconfig-paths/register migrations/openai-responses/run-openai-responses-migration.ts
+
+# Enable Responses on pilot chatbots
+AI_MIGRATION_DRY_RUN=false MIGRATION_STEPS=05 \
+  MIGRATION_CHATBOT_IDS=CHATBOT_ID_1,CHATBOT_ID_2 \
+  ts-node -r tsconfig-paths/register migrations/openai-responses/run-openai-responses-migration.ts
+
+# Parity test
+AI_MIGRATION_DRY_RUN=false MIGRATION_STEPS=06 \
+  PARITY_CHATBOT_ID=CHATBOT_ID_1 \
+  ts-node -r tsconfig-paths/register migrations/openai-responses/run-openai-responses-migration.ts
+
+# Deploy api: AI_USE_CONVAI_SDK=true
+```
+
+### Production checklist
+
+| Order | Action |
+|-------|--------|
+| 1 | Deploy api code (SDK adapters + fixes) with `AI_USE_CONVAI_SDK=false` |
+| 2 | Run migration steps **01–04** on production Mongo |
+| 3 | Run step **05** on 2–3 internal chatbots |
+| 4 | Run step **06** parity on staging, then prod sample |
+| 5 | Set `AI_USE_CONVAI_SDK=true` on staging → soak → production |
+| 6 | Expand step **05** (5% → 25% → 100% chatbots) |
+
+### Rollback
+
+```bash
+AI_MIGRATION_DRY_RUN=false ROLLBACK_CHATBOT_IDS=CHATBOT_ID \
+  ts-node -r tsconfig-paths/register migrations/openai-responses/repair/reset-ai-backend.step.ts
+```
+
+Set `AI_USE_CONVAI_SDK=false` and redeploy.
+
+---
+
+## User message → AI reply lifecycle
+
+When `ai_backend=responses` and `AI_USE_CONVAI_SDK=true`:
+
+| # | Step | Location | What happens |
+|---|------|----------|--------------|
+| 1 | User sends message | Widget → Socket `ask-question` | `userQuestion`, optional `mediaUrl` |
+| 2 | Save message | `api/.../bot-thread-active.handler.ts` | `userQuestionMessage()` → Mongo `Message` |
+| 3 | Enqueue job | `thread-run-queue.service.ts` | One run per `threadId` (batch or sequential) |
+| 4 | Resolve backend | `resolve-job-backend.helper.ts` | `resp_*` or `ai_backend=responses` |
+| 5 | Batch path | `batch-run-processor.ts` | `getBotMessageForResponses()` (not Assistants API) |
+| 6 | Vision | `helpers.ts` → `enrichResponsesUserQuestion()` | `buildVisionMessageContent()` if enabled |
+| 7 | Config | `response-config.builder.ts` | `system_prompt`, context, function tools |
+| 8 | SDK | `getBotMessageForResponsesViaSdk()` | `askWithTools()` |
+| 9 | Load state | `mongo-conversation.store.ts` | `Thread.openai_conversation_id` |
+| 10 | OpenAI | SDK `create-response.operation.ts` | `responses.create` |
+| 11 | Tools? | SDK `responses-tool.loop.ts` | See tool loop section |
+| 12 | Post-process | `handleFinalResponseForResponses()` | Tickets, markers, widget shape |
+| 13 | Reply | Socket `onResult` | `BOT_REPLIED` event |
+
+**Thread IDs**
+
+| Backend | Format | Created in |
+|---------|--------|------------|
+| Assistants | `thread_…` | OpenAI Threads API |
+| Responses | `resp_conv_…` | OpenAI Conversations API |
+
+> **Full guide (Widget + WhatsApp + Facebook + migration):**  
+> api monorepo: `api/docs/COMPLETE_CONVAI_SDK_INTEGRATION_GUIDE.md`
+
+---
+
+## WhatsApp integration cycle
+
+```
+WhatsApp user → Meta webhook → handle-event.ts → handle-incoming-message.ts
+  → BullMQ queue_worker (addTextJob / addMediaJob)
+  → handleChannelAskQuestion('whatsapp')
+  → userQuestionMessage() + ThreadRunQueue.enqueueJob()
+  → getBotMessageForResponses() [SDK when AI_USE_CONVAI_SDK=true]
+  → dispatchBotReply() → WhatsAppAdapter.sendMessage() → user
+```
+
+| # | Step | File |
+|---|------|------|
+| 1 | Meta webhook POST | `whatsapp/webhook/handle-event.ts` |
+| 2 | Parse text/media/button | `handle-incoming-message.ts` |
+| 3 | Redis queue | `queue_worker.ts` |
+| 4 | Channel routing | `channel-ask-question.handler.ts` |
+| 5 | Save + enqueue AI | `existing-lead-bot-text.handler.ts` |
+| 6 | AI pipeline | Shared (see above) |
+| 7 | Outbound | `channel-bot-reply.handler.ts` → `WhatsAppAdapter` |
+
+WhatsApp-specific: typing indicator, interactive calendar lists, media upload to Wasabi.
+
+---
+
+## Facebook Messenger integration cycle
+
+```
+Facebook user → Meta webhook → FacebookAdapter.handleEvent()
+  → fetchMessengerMedia() (attachments) → BullMQ queue_worker
+  → handleChannelAskQuestion('facebook')
+  → userQuestionMessage() + ThreadRunQueue.enqueueJob()
+  → getBotMessageForResponses() [SDK when AI_USE_CONVAI_SDK=true]
+  → dispatchBotReply() → FacebookAdapter.sendMessage() → user
+```
+
+| # | Step | File |
+|---|------|------|
+| 1 | Meta webhook POST | `FacebookAdapter.ts` |
+| 2 | Skip echo, resolve page | `handleEvent()` |
+| 3 | Media / audio transcript | `fetchMessengerMedia()`, `transcribeAudioToText()` |
+| 4 | Redis queue | `queue_worker.ts` |
+| 5 | Channel routing | `channel-ask-question.handler.ts` |
+| 6 | Save + enqueue AI | `existing-lead-bot-text.handler.ts` |
+| 7 | Outbound | `channel-bot-reply.handler.ts` → `FacebookAdapter` |
+
+---
+
+## Tool loop lifecycle
+
+Triggered when `response.output[]` contains `type: function_call`.
+
+| # | Step | Location | Description |
+|---|------|----------|-------------|
+| 1 | Detect calls | SDK `responses-tool.loop.ts` | Scan output for `function_call` |
+| 2 | Build output | api `run-completion.service.ts` | Route by function name |
+| 3 | Missing params | api `query-function.context.ts` | JSON + `MANDATORY_RESPONSE_FORMAT` |
+| 4 | Submit | SDK `submit-tool-outputs.operation.ts` | Chain via `conversation` or `previous_response_id` |
+| 5 | Cap | `MAX_TURNS = 10` | Prevent infinite loops |
+| 6 | Extract | api `ApiToolHandler.extractResult()` | Ticket / API when complete |
+| 7 | Short-circuit | SDK `kind: 'toolResult'` | `AssistantResponseService.run()` |
+| 8 | Continue | `extractResult` returns `null` | Model asks user for missing fields |
+
+**Tool sources**
+
+| Source | Examples |
+|--------|----------|
+| Platform tools | `notifyAgent`, calendar, `get_current_date` |
+| Custom (Mongo) | `create_ticket_for_booking`, `job_application` |
+| File search | When chatbot has vector store |
+
+---
+
+## Vision (images)
+
+When `openai_vision_enabled=true`:
+
+1. api `enrichResponsesUserQuestion()` → `buildVisionMessageContent()`
+2. `VisionFactory.analyzeImages()` → `Image analysis: …` in text
+3. Enriched text sent as `userQuestion` to SDK
+
+---
+
+## Troubleshooting
+
+| Symptom | Cause | Fix area |
+|---------|-------|----------|
+| `Invalid thread_id resp_conv_…` | Assistants API on Responses thread | api batch processor |
+| `Invalid schema … image` | Raw param type to OpenAI | api `function-param-schema.helper.ts` |
+| Ignores images | Vision not enriched | api `enrichResponsesUserQuestion` |
+| Empty reply | SDK error | Check `[getBotMessageForResponses] SDK error` logs |
+| Stale SDK in Docker | Old dist | Rebuild package + restart api |
+
+---
+
+## Publish this package
+
+```bash
+cd convai-platform
+npm run build
+npm publish --access public
+```
+
+If publish returns **404 / no permission**, run `npm login` with the account that owns the `@mohamedtebo` scope on npmjs.com. Until then, mount `./convai-platform/dist` in Docker.
+
+---
+
+MIT © mohamedtebo

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@mohamedtebo/convai-platform",
-  "version": "1.0.0",
+  "version": "1.0.4",
   "description": "Multi-provider AI platform SDK — OpenAI Responses/Conversations + Anthropic Claude with explicit tool loops, pluggable persistence, and SRP architecture",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
-  "files": ["dist", "README.md"],
+  "files": ["dist", "README.md", "docs"],
   "scripts": {
-    "build": "tsc",
+    "build": "rm -rf dist && tsc",
     "dev": "tsc --watch",
     "test": "npm run build && node --test dist/tests/safe-client.test.js",
     "prepublishOnly": "npm run build"

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

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

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

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

package/dist/src/adapters/index.js

@@ -1,6 +0,0 @@
-"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/src/adapters/index.js.map

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

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

@@ -1,12 +0,0 @@
-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/src/adapters/memory-conversation.store.d.ts.map

@@ -1 +0,0 @@
-{"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/src/adapters/memory-conversation.store.js

@@ -1,25 +0,0 @@
-"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/src/adapters/memory-conversation.store.js.map

@@ -1 +0,0 @@
-{"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/src/composed/platform-client.d.ts

@@ -1,29 +0,0 @@
-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/src/composed/platform-client.d.ts.map

@@ -1 +0,0 @@
-{"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/src/composed/platform-client.js

@@ -1,16 +0,0 @@
-"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/src/composed/platform-client.js.map

@@ -1 +0,0 @@
-{"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/src/errors/index.d.ts

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

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

@@ -1 +0,0 @@
-{"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/src/errors/index.js

@@ -1,11 +0,0 @@
-"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