# @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

```bash
npm install @mohamedtebo/convai-platform openai
# optional
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-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](./docs/API_INTEGRATION.md)** | Full **api** integration: migration, lifecycle, WhatsApp, Facebook |
| **[../api/docs/COMPLETE_CONVAI_SDK_INTEGRATION_GUIDE.md](../api/docs/COMPLETE_CONVAI_SDK_INTEGRATION_GUIDE.md)** | Master guide (api monorepo) — all channels + migration |
| [README.md](./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.

```typescript
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`.

```typescript
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)

```typescript
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

```bash
npm run build
npm test
npm publish --access public
```

---

## License

MIT © mohamedtebo