@mohamedtebo/convai-platform

Multi-provider AI SDK — OpenAI Responses + Conversations (recommended), OpenAI Assistants (legacy), Anthropic Claude. Explicit tool loops, pluggable ConversationStore + ToolHandler, SdkResult safe API.

Install

npm install @mohamedtebo/convai-platform openai
# optional
npm install @anthropic-ai/sdk

Quick start

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',
  userQuestion: 'Book a ticket for tomorrow',
  instructions: 'You are a helpful booking assistant.',
});

if (result.success) {
  if (result.data.kind === 'text') {
    console.log(result.data.outputText);
  } else {
    console.log(result.data.toolCallResult);
  }
} else {
  console.error(result.error.code, result.error.hint);
}

Documentation (included in npm package)

| Doc | Description | |-----|-------------| | docs/API_INTEGRATION.md | Full api integration: migration, lifecycle, WhatsApp, Facebook | | ../api/docs/COMPLETE_CONVAI_SDK_INTEGRATION_GUIDE.md | Master guide (api monorepo) — all channels + migration | | README.md | This file — SDK API reference |

After install: node_modules/@mohamedtebo/convai-platform/docs/API_INTEGRATION.md

api monorepo copies:

• api/docs/CONVAI_SDK_INTEGRATION.md — integration guide
• api/docs/reports/CONVAI_SDK_INTEGRATION_REPORT.md — formal rollout report

Providers

| provider value | API | |------------------|-----| | openai-responses | OpenAI Responses + Conversations (recommended) | | openai-assistants | OpenAI Assistants beta (legacy) | | anthropic | Claude |

Core interfaces

ConversationStore

Persist conversationId and lastResponseId per app thread key.

interface ConversationStore {
  load(threadKey: string): Promise<ConversationState | null>;
  save(threadKey: string, state: ConversationState): Promise<void>;
  create(threadKey: string, conversationId: string): Promise<ConversationState>;
}

api implements this as MongoConversationStore (Thread.openai_conversation_id).

ToolHandler

Execute business tools when the model returns function_call.

interface ToolHandler {
  buildOutput(call: RawToolCall, ctx: ToolHandlerContext): Promise<ToolOutput | undefined>;
  extractResult(calls: RawToolCall[], outputs: ToolOutput[], ctx: ToolHandlerContext): Promise<unknown>;
}

api implements this as ApiToolHandler in api/src/core/convai-adapters/telbany-tool.handler.ts.

api integration (production)

import { getAIPlatformClient } from './core/convai-adapters';

const client = getAIPlatformClient({ backend: 'openai-responses', model: 'gpt-4o-mini' });

await client.safe.askWithTools({
  threadKey: threadId,
  chatbotId,
  organizationId,
  userQuestion: enrichedQuestion,
  instructions: params.instructions,
  tools: params.tools,
  model: params.model,
  mediaUrl,
});

Enable: AI_USE_CONVAI_SDK=true in api .env (after migration steps 01–06).

Package layout

src/
├── composed/platform-client.ts
├── factory/provider.factory.ts
├── safe/safe-platform.client.ts
├── types/
├── errors/
├── adapters/memory-conversation.store.ts
└── providers/openai/
    ├── openai-responses.provider.ts
    ├── operations/create-response.operation.ts
    ├── operations/submit-tool-outputs.operation.ts
    └── loops/responses-tool.loop.ts
docs/
└── API_INTEGRATION.md    ← full api rollout guide

Build & publish

npm run build
npm test
npm publish --access public

License

MIT © mohamedtebo