@voltade/envoy-sdk 1.3.0 → 1.3.1

package/README.md

@@ -11,39 +11,34 @@ npm install @voltade/envoy-sdk
 ## Quick Start
 
 ```typescript
-import { EnvoyClient } from '@voltade/envoy-sdk';
+import { EnvoyClient } from "@voltade/envoy-sdk";
 
-// Initialize the client
 const client = new EnvoyClient({
-  apiKey: 'your-api-key',
-  accountId: 'your-account-id',
-  baseUrl: 'https://envoy-crm.voltade.com', // optional, defaults to this
+  apiKey: "your-api-key",
+  accountId: "your-account-id",
+  baseUrl: "https://envoy-crm.voltade.com", // optional
 });
 
-// Create and send a message to a conversation
+// Send a message
 const message = await client.conversations.createMessage(123, {
-  content: 'Hello, how can I help you?',
-  message_type: 'outgoing',
-  private: false
+  content: "Hello, how can I help you?",
+  message_type: "outgoing",
+  private: false,
 });
 
-// Escalate a conversation to a human agent
+// Escalate to human
 const result = await client.conversations.escalateToHuman(123);
-console.log(`Escalated: ${result.success}`);
 ```
 
 ## Features
 
 - **Type-safe**: Full TypeScript support with comprehensive type definitions
-- **Resource-based**: Organized API methods by resource (conversations, messages, etc.)
+- **Resource-based**: Organized API methods by resource (conversations, contacts, companies, etc.)
 - **Error handling**: Structured error types for different API failures
-- **Easy to use**: Simple, intuitive API design
-
-## API Reference
+- **Zod schemas**: Runtime validation with exported schemas
+- **Webhook support**: Parse and validate incoming webhook events
 
-### EnvoyClient
-
-#### Configuration
+## Configuration
 
 ```typescript
 const client = new EnvoyClient({
@@ -54,24 +49,56 @@ const client = new EnvoyClient({
 });
 ```
 
+---
+
+## API Reference
+
 ### Conversations
 
-#### Create Message
+#### `createMessage(conversationId, params)`
+
+Create and send a message to a conversation. Supports text messages, WhatsApp templates, and file attachments.
 
 ```typescript
-const message = await client.conversations.createMessage(conversationId, {
-  content: 'Your message',
-  message_type: 'outgoing',
+// Simple text message
+const message = await client.conversations.createMessage(123, {
+  content: "Hello, how can I help you?",
+  message_type: "outgoing",
   private: false,
-  content_type: 'text',
-  content_attributes: {}
+});
+
+// WhatsApp template message
+const templateMessage = await client.conversations.createMessage(123, {
+  content: "Template message",
+  template_params: {
+    name: "order_confirmation",
+    category: "MARKETING",
+    language: "en",
+    processed_params: {
+      body: { "1": "121212" },
+      header: {
+        media_url: "https://example.com/image.jpg",
+        media_type: "image",
+      },
+    },
+  },
+});
+
+// Message with file attachments
+const file = new File([blob], "document.pdf", { type: "application/pdf" });
+const messageWithAttachment = await client.conversations.createMessage(123, {
+  content: "Here is your document",
+  message_type: "outgoing",
+  file_attachments: [file],
 });
 ```
 
-#### Escalate to Human
+#### `escalateToHuman(conversationId)`
+
+Escalate a conversation to a human agent.
 
 ```typescript
-const result = await client.conversations.escalateToHuman(conversationId);
+const result = await client.conversations.escalateToHuman(123);
 
 if (result.success) {
   console.log(`Escalated to ${result.escalation_type}`);
@@ -81,6 +108,336 @@ if (result.success) {
 }
 ```
 
+#### `get(conversationId)`
+
+Get a conversation by ID.
+
+```typescript
+const conversation = await client.conversations.get(123);
+console.log(conversation.status); // 'open' | 'resolved' | 'pending' | 'snoozed'
+```
+
+#### `getMessages(conversationId)`
+
+Get all messages for a conversation.
+
+```typescript
+const response = await client.conversations.getMessages(123);
+console.log(response.payload); // Array of messages
+console.log(response.meta); // Metadata including labels, assignee
+```
+
+---
+
+### Contacts
+
+#### `create(params)`
+
+Create a new contact.
+
+```typescript
+const contact = await client.contacts.create({
+  inbox_id: 1,
+  name: "John Doe",
+  email: "john@example.com",
+  phone_number: "+1234567890",
+  custom_attributes: { plan: "enterprise" },
+});
+```
+
+#### `update(contactId, params)`
+
+Update an existing contact.
+
+```typescript
+const contact = await client.contacts.update(123, {
+  name: "Jane Doe",
+  email: "jane@example.com",
+  custom_attributes: { plan: "pro" },
+});
+```
+
+#### `get(contactId)`
+
+Get a contact by ID.
+
+```typescript
+const contact = await client.contacts.get(123);
+console.log(contact.name, contact.email);
+```
+
+#### `delete(contactId)`
+
+Delete a contact.
+
+```typescript
+await client.contacts.delete(123);
+```
+
+#### `list(params?)`
+
+List all contacts with pagination.
+
+```typescript
+const response = await client.contacts.list({ page: 1 });
+console.log(response.payload); // Array of contacts
+console.log(response.meta); // Pagination metadata
+```
+
+#### `search(params)`
+
+Search contacts by name, identifier, email, or phone number.
+
+```typescript
+const response = await client.contacts.search({
+  q: "john@example.com",
+  page: 1,
+});
+console.log(response.payload);
+```
+
+---
+
+### Companies
+
+#### `list(params?)`
+
+List all companies with pagination.
+
+```typescript
+const companies = await client.companies.list();
+
+// With pagination
+const companies = await client.companies.list({ page: 2, per_page: 50 });
+```
+
+#### `create(params)`
+
+Create a new company.
+
+```typescript
+const company = await client.companies.create({
+  name: "Acme Corp",
+});
+```
+
+#### `get(companyId)`
+
+Get a company by ID.
+
+```typescript
+const company = await client.companies.get(456);
+```
+
+#### `update(companyId, params)`
+
+Update an existing company.
+
+```typescript
+const company = await client.companies.update(456, {
+  name: "Acme Corp Updated",
+});
+```
+
+#### `search(query, params?)`
+
+Search companies by name.
+
+```typescript
+const response = await client.companies.search("Acme");
+
+// With pagination
+const response = await client.companies.search("Acme", {
+  page: 2,
+  per_page: 50,
+});
+console.log(response.payload); // Array of matching companies
+console.log(response.meta); // { count, current_page }
+```
+
+#### `delete(companyId)`
+
+Delete a company.
+
+```typescript
+await client.companies.delete(456);
+```
+
+---
+
+### Company Members
+
+Manage contacts within a company via `client.companies.members`.
+
+#### `list(companyId)`
+
+List all members (contacts) of a company.
+
+```typescript
+const members = await client.companies.members.list(456);
+```
+
+#### `add(companyId, params)`
+
+Add contacts to a company.
+
+```typescript
+const members = await client.companies.members.add(456, {
+  contact_ids: [101, 102, 103],
+});
+```
+
+#### `remove(companyId, params)`
+
+Remove contacts from a company.
+
+```typescript
+await client.companies.members.remove(456, {
+  contact_ids: [101, 102],
+});
+```
+
+---
+
+### Inboxes
+
+#### `searchPortals(inboxId, params)`
+
+Search the knowledge base portals for articles.
+
+```typescript
+const articles = await client.inboxes.searchPortals(1, {
+  queries: ["shipping", "policy"],
+});
+
+articles.forEach((article) => {
+  console.log(article.title, article.content);
+});
+```
+
+#### `uploadWhatsappMedia(inboxId, params)`
+
+Upload media file for WhatsApp messages.
+
+```typescript
+// Upload an image
+const file = new File([imageBlob], "photo.jpg", { type: "image/jpeg" });
+const result = await client.inboxes.uploadWhatsappMedia(123, {
+  file: file,
+  type: "image/jpeg",
+  filename: "photo.jpg",
+  for_template: false,
+});
+console.log("Media ID:", result.media_id);
+
+// Upload a document for template
+const docFile = new File([pdfBlob], "invoice.pdf", { type: "application/pdf" });
+const docResult = await client.inboxes.uploadWhatsappMedia(123, {
+  file: docFile,
+  type: "application/pdf",
+  filename: "invoice.pdf",
+  for_template: true,
+});
+```
+
+---
+
+### Orders
+
+#### `list(params?)`
+
+List all orders with pagination and filtering.
+
+```typescript
+// List with default pagination
+const response = await client.orders.list();
+console.log(response.data); // Array of orders
+console.log(response.meta); // Pagination metadata
+
+// With date filtering
+const response = await client.orders.list({
+  page: 1,
+  per_page: 50,
+  since: "2024-01-01",
+  until: "2024-12-31",
+  sort: "-created_at",
+});
+
+// With advanced filtering
+const response = await client.orders.list({
+  payload: [{ field: "financial_status", operator: "eq", value: "paid" }],
+});
+```
+
+#### `upsert(params)`
+
+Create or update an order based on `source` and `source_id`. If an order with the same source and source_id exists, it will be updated.
+
+```typescript
+const result = await client.orders.upsert({
+  name: "ORD-12345",
+  company_id: 101,
+  total_amount: 150,
+  currency_code: "USD",
+  financial_status: "paid",
+  fulfillment_status: "fulfilled",
+  source: "shopify",
+  source_id: "789456123",
+  order_url: "https://mystore.myshopify.com/admin/orders/789456123",
+  notes: "Customer requested gift wrapping",
+  metadata: {
+    line_items: [
+      {
+        part_number: "SKU-001",
+        quantity: 2,
+        description: "Widget",
+        line_total: 75,
+      },
+    ],
+  },
+});
+console.log(result.payload); // The created/updated order
+```
+
+---
+
+### Webhooks
+
+Parse and validate incoming webhook events using the `webhookEvent` utility.
+
+```typescript
+import { webhookEvent } from "@voltade/envoy-sdk";
+
+// In your webhook handler
+app.post("/webhook", (req, res) => {
+  // Throws ZodError if invalid
+  const event = webhookEvent.parse(req.body);
+
+  if (event.event === "message_created") {
+    console.log("New message:", event.content);
+    console.log("Conversation:", event.conversation.id);
+    console.log("Sender:", event.sender.name);
+  }
+
+  res.sendStatus(200);
+});
+
+// Or use safeParse for graceful handling
+const event = webhookEvent.safeParse(req.body);
+if (event) {
+  // Handle valid event
+} else {
+  // Invalid payload
+}
+```
+
+**Supported webhook events:**
+
+- `message_created` - New message in a conversation
+- `message_updated` - Message was updated
+
+---
+
 ## Error Handling
 
 The SDK provides structured error types:
@@ -93,85 +450,200 @@ import {
   NotFoundError,
   RateLimitError,
   ServerError,
-  NetworkError
-} from '@voltade/envoy-sdk';
+  NetworkError,
+  ValidationError,
+} from "@voltade/envoy-sdk";
 
 try {
-  await client.conversations.createMessage(123, { content: 'Hello' });
+  await client.conversations.createMessage(123, { content: "Hello" });
 } catch (error) {
   if (error instanceof AuthenticationError) {
-    console.error('Invalid API key');
+    console.error("Invalid API key");
   } else if (error instanceof NotFoundError) {
-    console.error('Conversation not found');
+    console.error("Conversation not found");
   } else if (error instanceof RateLimitError) {
-    console.error('Rate limit exceeded');
+    console.error("Rate limit exceeded, retry after:", error.retryAfter);
+  } else if (error instanceof BadRequestError) {
+    console.error("Bad request:", error.response);
+  } else if (error instanceof ValidationError) {
+    console.error("Validation failed:", error.errors);
+  } else if (error instanceof ServerError) {
+    console.error("Server error:", error.statusCode);
+  } else if (error instanceof NetworkError) {
+    console.error("Network error:", error.originalError);
   }
 }
 ```
 
+---
+
 ## Types
 
-All TypeScript types are exported and available for use:
+All TypeScript types are exported:
 
 ```typescript
 import type {
+  // Conversations
   Message,
   Conversation,
+  ConversationStatus,
   CreateMessageParams,
   EscalationResponse,
+  EscalationType,
   MessageType,
   ContentType,
-  ConversationStatus
-} from '@voltade/envoy-sdk';
+  MessagesResponse,
+  MessagesResponseMeta,
+  TemplateParams,
+  Agent,
+  Assignee,
+  Team,
+  Priority,
+  Contact,
+  ContactInbox,
+  ConversationMeta,
+
+  // Contacts
+  ContactCreateParams,
+  ContactUpdateParams,
+  ListContactsParams,
+  ListContactsResponse,
+  SearchContactsParams,
+
+  // Companies
+  Company,
+  CreateCompanyParams,
+  CreateCompanyResponse,
+  GetCompanyResponse,
+  ListCompaniesParams,
+  ListCompaniesResponse,
+  UpdateCompanyParams,
+  UpdateCompanyResponse,
+  SearchCompaniesResponse,
+
+  // Company Members
+  AddCompanyMembersParams,
+  AddCompanyMembersResponse,
+  ListCompanyMembersResponse,
+  RemoveCompanyMembersParams,
+
+  // Inboxes
+  Article,
+  SearchParams,
+  SearchResponse,
+  UploadWhatsappMediaParams,
+  UploadWhatsappMediaResponse,
+
+  // Orders
+  Order,
+  OrdersMeta,
+  ListOrdersParams,
+  ListOrdersResponse,
+  UpsertOrderParams,
+  UpsertOrderRequest,
+  UpsertOrderResponse,
+  UpsertOrderResponsePayload,
+
+  // Webhooks
+  WebhookEvent,
+  MessageCreatedEvent,
+  MessageUpdatedEvent,
+  WebhookConversation,
+  WebhookMessage,
+  WebhookSender,
+
+  // Client
+  EnvoyClientConfig,
+} from "@voltade/envoy-sdk";
 ```
 
+---
+
 ## Zod Schemas
 
 The SDK exposes Zod schemas for runtime validation. All types are derived from these schemas using `z.infer`:
 
 ```typescript
 import {
+  // Conversations
   MessageSchema,
+  ConversationSchema,
+  ConversationStatusSchema,
   CreateMessageParamsSchema,
   EscalationResponseSchema,
-  ConversationSchema
-} from '@voltade/envoy-sdk';
+  EscalationTypeSchema,
+  MessageTypeSchema,
+  ContentTypeSchema,
+  MessagesResponseSchema,
+  MessagesResponseMetaSchema,
+  TemplateParamsSchema,
+  AgentSchema,
+  AssigneeSchema,
+  TeamSchema,
+  PrioritySchema,
+  ContactSchema,
+  ContactInboxSchema,
+  ConversationMetaSchema,
+
+  // Contacts
+  ContactCreateParamsSchema,
+  ContactUpdateParamsSchema,
+  ListContactsParamsSchema,
+  ListContactsResponseSchema,
+  SearchContactsParamsSchema,
+
+  // Companies
+  CompanySchema,
+  CreateCompanyParamsSchema,
+  CreateCompanyResponseSchema,
+  GetCompanyResponseSchema,
+  ListCompaniesParamsSchema,
+  ListCompaniesResponseSchema,
+  UpdateCompanyParamsSchema,
+  UpdateCompanyResponseSchema,
+  SearchCompaniesResponseSchema,
+
+  // Company Members
+  AddCompanyMembersParamsSchema,
+  AddCompanyMembersResponseSchema,
+  ListCompanyMembersResponseSchema,
+  RemoveCompanyMembersParamsSchema,
+
+  // Inboxes
+  ArticleSchema,
+  SearchParamsSchema,
+  SearchResponseSchema,
+  UploadWhatsappMediaParamsSchema,
+  UploadWhatsappMediaResponseSchema,
+
+  // Orders
+  OrderSchema,
+  OrdersMetaSchema,
+  ListOrdersParamsSchema,
+  ListOrdersResponseSchema,
+  UpsertOrderParamsSchema,
+  UpsertOrderRequestSchema,
+  UpsertOrderResponseSchema,
+  UpsertOrderResponsePayloadSchema,
+
+  // Webhooks
+  WebhookEventSchema,
+  MessageCreatedEventSchema,
+  MessageUpdatedEventSchema,
+  WebhookConversationSchema,
+  WebhookMessageSchema,
+  WebhookSenderSchema,
+} from "@voltade/envoy-sdk";
 
 // Validate data at runtime
-const messageData = {
-  id: 123,
-  content: 'Hello',
-  message_type: 'outgoing',
-  // ... other fields
-};
-
 const validatedMessage = MessageSchema.parse(messageData);
 
 // Validate user input
-const userInput = {
-  content: 'Hello, world!',
-  message_type: 'outgoing',
-  private: false
-};
-
 const validatedParams = CreateMessageParamsSchema.parse(userInput);
 await client.conversations.createMessage(123, validatedParams);
 ```
 
-### Available Schemas
-
-All schemas are exported from the SDK:
-- `MessageTypeSchema`
-- `ContentTypeSchema`
-- `CreateMessageParamsSchema`
-- `MessageSchema`
-- `EscalationTypeSchema`
-- `PrioritySchema`
-- `TeamSchema`
-- `AgentSchema`
-- `EscalationResponseSchema`
-- `ConversationStatusSchema`
-- `ConversationSchema`
+---
 
 ## Development
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltade/envoy-sdk",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "type": "module",
   "description": "A comprehensive TypeScript SDK for the Envoy API with built-in error handling and resource-based architecture",
   "main": "./dist/index.js",