@kortex-ai/hub-client 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kortex
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,342 @@
+# @kortex-ai/hub-client
+
+Official TypeScript/JavaScript client for the Kortex Hub API. This package provides a type-safe, easy-to-use interface for interacting with Kortex's conversation management, messaging, and notification systems.
+
+## Features
+
+- 🔒 **Type-safe** - Full TypeScript support with comprehensive type definitions
+- ✅ **Validated** - Built-in request validation using Zod schemas
+- 🚀 **Modern** - Works in Node.js, Deno, Bun, and browsers
+- 📦 **Tree-shakeable** - ESM and CommonJS support
+- 🎯 **Simple API** - Clean, intuitive methods for all endpoints
+- 🛡️ **Never throws** - All methods return Result types for safe error handling
+
+## Installation
+
+```bash
+# Using pnpm
+pnpm add @kortex-ai/hub-client
+
+# Using npm
+npm install @kortex-ai/hub-client
+
+# Using yarn
+yarn add @kortex-ai/hub-client
+```
+
+## Quick Start
+
+```typescript
+import { KortexClient } from '@kortex-ai/hub-client'
+
+// Initialize the client
+const client = new KortexClient({
+  apiToken: 'your-api-token',
+  baseUrl: 'https://kortex-dashboard.vercel.app', // Optional, this is the default
+})
+
+// Use the client with Result pattern (never throws)
+const result = await client.sendMessage({
+  waId: '1234567890',
+  message: {
+    type: 'text',
+    content: {
+      text: 'Hello from the API!',
+    },
+  },
+})
+
+if (result.error) {
+  console.error('Error:', result.error.message)
+} else {
+  console.log('Success:', result.data.message)
+}
+```
+
+## API Reference
+
+### Client Configuration
+
+```typescript
+interface KortexClientConfig {
+  /**
+   * API token for authentication (required)
+   */
+  apiToken: string
+
+  /**
+   * Base URL of the Kortex Hub API
+   * @default 'https://kortex-dashboard.vercel.app'
+   */
+  baseUrl?: string
+
+  /**
+   * Optional custom fetch implementation
+   */
+  fetch?: typeof fetch
+
+  /**
+   * Optional request timeout in milliseconds
+   * @default 30000 (30 seconds)
+   */
+  timeout?: number
+}
+```
+
+### Methods
+
+#### `assignTags(payload)`
+
+Assign tags to a conversation.
+
+```typescript
+await client.assignTags({
+  waId: '1234567890',
+  tags: ['important', 'customer-support'],
+})
+```
+
+**Parameters:**
+
+- `waId` (string, required) - WhatsApp ID of the conversation
+- `tags` (string[], required) - Array of tag names to assign
+
+**Returns:** `Promise<Result<AssignTagsResponse, KortexAPIError>>`
+
+---
+
+#### `sendNotification(payload)`
+
+Send notifications through specified channels.
+
+```typescript
+await client.sendNotification({
+  sendOptions: ['dashboard', 'email'],
+  notification: {
+    category: 'general',
+    title: 'New Update Available',
+    message: 'Version 2.0 is now available!',
+    link: 'https://example.com/updates',
+  },
+})
+```
+
+**Parameters:**
+
+- `sendOptions` (Array<'dashboard' | 'email' | 'push'>, required) - Delivery channels
+- `notification` (BareNotification, required) - Notification details
+
+**Notification Types:**
+
+- `general` - General notification with optional link
+- `chat` - Chat-related notification with conversationId
+- `spaces` - Spaces notification with spaceUrlPath
+
+**Returns:** `Promise<Result<SendNotificationResponse, KortexAPIError>>`
+
+---
+
+#### `sendMessage(payload)`
+
+Send a message (text, note, or template) to a WhatsApp conversation.
+
+```typescript
+// Send a text message
+await client.sendMessage({
+  waId: '1234567890',
+  message: {
+    type: 'text',
+    content: {
+      text: 'Hello!',
+    },
+  },
+  clientName: 'John Doe', // Optional
+})
+
+// Send a template message
+await client.sendMessage({
+  waId: '1234567890',
+  message: {
+    type: 'template',
+    content: {
+      name: 'welcome_message',
+      language: 'en',
+      body_variables: ['John', 'Acme Corp'],
+    },
+  },
+})
+```
+
+**Parameters:**
+
+- `waId` (string, required) - WhatsApp ID
+- `message` (object, required) - Message object with type and content
+  - `type`: `'text'` | `'note'` | `'template'`
+  - `content`: Varies by message type
+- `clientName` (string, optional) - Client name for context
+
+**Returns:** `Promise<Result<SendMessageResponse, KortexAPIError>>`
+
+---
+
+#### `stopConversationAi(payload)`
+
+Stop or start AI for a conversation.
+
+```typescript
+// Stop AI
+await client.stopConversationAi({
+  waId: '1234567890',
+  stopAi: true,
+})
+
+// Start AI
+await client.stopConversationAi({
+  waId: '1234567890',
+  stopAi: false,
+})
+```
+
+**Parameters:**
+
+- `waId` (string, required) - WhatsApp ID
+- `stopAi` (boolean, required) - Whether to stop or start AI
+
+**Returns:** `Promise<Result<StopConversationAiResponse, KortexAPIError>>`
+
+---
+
+#### `upsertConversation(payload)`
+
+Create or update a conversation.
+
+```typescript
+const response = await client.upsertConversation({
+  waId: '1234567890',
+  clientName: 'John Doe',
+})
+
+console.log(response.data) // ConversationWithTags
+```
+
+**Parameters:**
+
+- `waId` (string, required) - WhatsApp ID
+- `clientName` (string, required) - Client name
+
+**Returns:** `Promise<Result<UpsertConversationResponse, KortexAPIError>>`
+
+## Error Handling
+
+All client methods return a `Result` type that never throws. This provides safe, explicit error handling:
+
+```typescript
+import { KortexClient } from '@kortex-ai/hub-client'
+
+const client = new KortexClient({ apiToken: 'your-token' })
+
+// Result pattern - check if operation succeeded
+const result = await client.sendMessage({
+  waId: '1234567890',
+  message: {
+    type: 'text',
+    content: { text: 'Hello!' },
+  },
+})
+
+if (result.error) {
+  // Error - access error details
+  console.error('Failed:', result.error.message)
+  console.error('Status:', result.error.statusCode)
+  console.error('Response:', result.error.response)
+} else {
+  // Success - access data
+  console.log('Message sent:', result.data.message)
+}
+
+// Or destructure for cleaner code
+const { data, error } = await client.sendMessage({
+  /* ... */
+})
+
+if (error) {
+  console.error('Error:', error)
+  return
+}
+
+console.log('Success:', data)
+```
+
+## Advanced Usage
+
+### Custom Fetch Implementation
+
+```typescript
+import { KortexClient } from '@kortex-ai/hub-client'
+import fetch from 'node-fetch'
+
+const client = new KortexClient({
+  apiToken: 'your-token',
+  fetch: fetch as any, // Use node-fetch in Node.js < 18
+})
+```
+
+### Custom Timeout
+
+```typescript
+const client = new KortexClient({
+  apiToken: 'your-token',
+  timeout: 60000, // 60 seconds
+})
+```
+
+### Using with Different Environments
+
+The package works seamlessly across different JavaScript environments:
+
+```typescript
+// Node.js (18+)
+import { KortexClient } from '@kortex-ai/hub-client'
+
+// Node.js (< 18) - install node-fetch
+import fetch from 'node-fetch'
+const client = new KortexClient({
+  apiToken: 'token',
+  fetch: fetch as any,
+})
+
+// Deno
+import { KortexClient } from 'npm:@kortex-ai/hub-client'
+
+// Browser
+import { KortexClient } from '@kortex-ai/hub-client'
+```
+
+## Type Exports
+
+All TypeScript types and schemas are exported for your convenience:
+
+```typescript
+import type {
+  AssignTagsPayload,
+  SendMessagePayload,
+  SendNotificationPayload,
+  ConversationWithTags,
+  BareNotification,
+  // ... and more
+} from '@kortex-ai/hub-client'
+
+import {
+  AssignTagsSchema,
+  SendMessageSchema,
+  // ... Zod schemas for validation
+} from '@kortex-ai/hub-client'
+```
+
+## License
+
+MIT
+
+## Support
+
+For issues and questions, please visit [GitHub Issues](https://github.com/kortex/kortex-dashboard/issues) or contact support.

package/dist/index.d.mts

@@ -0,0 +1,173 @@
+import * as convex_helpers_server_zod4 from 'convex-helpers/server/zod4';
+import { z } from 'zod';
+
+type Success<T> = {
+    data: T;
+    error: null;
+};
+type Failure<E> = {
+    data: null;
+    error: E;
+};
+type Result<T, E = Error> = Success<T> | Failure<E>;
+
+declare const ConversationSchema: z.ZodObject<{
+    _id: convex_helpers_server_zod4.Zid<"conversations">;
+    _creationTime: z.ZodNumber;
+    organizationId: convex_helpers_server_zod4.Zid<"organizations">;
+    waId: z.ZodString;
+    name: z.ZodString;
+    assignedUserId: z.ZodNullable<convex_helpers_server_zod4.Zid<"users">>;
+    stopAi: z.ZodBoolean;
+    status: z.ZodEnum<{
+        open: "open";
+        closed: "closed";
+    }>;
+    messageWindowStart: z.ZodNullable<z.ZodNumber>;
+    lastMessageText: z.ZodNullable<z.ZodString>;
+    lastMessageTimestamp: z.ZodNullable<z.ZodNumber>;
+    unreadCount: z.ZodNumber;
+}, z.core.$strip>;
+type Conversation = z.infer<typeof ConversationSchema>;
+type ConversationWithTags = Conversation & {
+    tags: string[];
+};
+
+declare const AssignTagsSchema: z.ZodObject<{
+    waId: z.ZodString;
+    tags: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+type AssignTagsPayload = z.infer<typeof AssignTagsSchema>;
+type AssignTagsResponse = {
+    message: string;
+};
+declare const SendNotificationSchema: z.ZodObject<{
+    sendOptions: z.ZodArray<z.ZodEnum<{
+        push: "push";
+        email: "email";
+        dashboard: "dashboard";
+    }>>;
+    notification: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        link: z.ZodNullable<z.ZodURL>;
+        message: z.ZodString;
+        title: z.ZodString;
+        category: z.ZodLiteral<"general">;
+    }, z.core.$strip>, z.ZodObject<{
+        message: z.ZodString;
+        title: z.ZodString;
+        category: z.ZodLiteral<"chat">;
+        conversationId: convex_helpers_server_zod4.Zid<"conversations">;
+    }, z.core.$strip>, z.ZodObject<{
+        message: z.ZodString;
+        title: z.ZodString;
+        category: z.ZodLiteral<"spaces">;
+        spaceUrlPath: z.ZodString;
+    }, z.core.$strip>], "category">;
+}, z.core.$strip>;
+type SendNotificationPayload = z.infer<typeof SendNotificationSchema>;
+type SendNotificationResponse = {
+    message: string;
+};
+declare const SendMessageSchema: z.ZodObject<{
+    waId: z.ZodString;
+    message: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"text">;
+        content: z.ZodObject<{
+            text: z.ZodString;
+        }, z.core.$strip>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"note">;
+        content: z.ZodObject<{
+            text: z.ZodString;
+        }, z.core.$strip>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"template">;
+        content: z.ZodObject<{
+            name: z.ZodString;
+            language: z.ZodString;
+            header_variable: z.ZodOptional<z.ZodString>;
+            body_variables: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            button_variables: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>;
+    }, z.core.$strip>], "type">;
+    clientName: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type SendMessagePayload = z.infer<typeof SendMessageSchema>;
+type SendMessageResponse = {
+    message: string;
+};
+declare const StopConversationAiSchema: z.ZodObject<{
+    waId: z.ZodString;
+    stopAi: z.ZodBoolean;
+}, z.core.$strip>;
+type StopConversationAiPayload = z.infer<typeof StopConversationAiSchema>;
+type StopConversationAiResponse = {
+    message: string;
+};
+declare const UpsertConversationSchema: z.ZodObject<{
+    waId: z.ZodString;
+    clientName: z.ZodString;
+}, z.core.$strip>;
+type UpsertConversationPayload = z.infer<typeof UpsertConversationSchema>;
+type UpsertConversationResponse = {
+    message: string;
+    data: ConversationWithTags;
+};
+
+interface KortexClientConfig {
+    /**
+     * Base URL of the Kortex Hub API
+     * @default 'https://kortex-dashboard.vercel.app'
+     */
+    baseUrl?: string;
+    /**
+     * API token for authentication
+     */
+    apiToken: string;
+}
+type KortexAPIError = {
+    message: string;
+    statusCode?: number;
+    response?: unknown;
+};
+declare class KortexClient {
+    private readonly baseUrl;
+    private readonly apiToken;
+    constructor(config: KortexClientConfig);
+    /**
+     * Internal method to make API requests
+     */
+    private request;
+    /**
+     * Assign tags to a conversation
+     * @param payload - The waId and tags to assign
+     * @returns Result with the success message or error
+     */
+    assignTags(payload: AssignTagsPayload): Promise<Result<AssignTagsResponse, KortexAPIError>>;
+    /**
+     * Send a notification through specified channels
+     * @param payload - The notification and send options
+     * @returns Result with the success message or error
+     */
+    sendNotification(payload: SendNotificationPayload): Promise<Result<SendNotificationResponse, KortexAPIError>>;
+    /**
+     * Send a message (text, note, or template) to a WhatsApp conversation
+     * @param payload - The message details (waId, message type and content)
+     * @returns Result with the success message or error
+     */
+    sendMessage(payload: SendMessagePayload): Promise<Result<SendMessageResponse, KortexAPIError>>;
+    /**
+     * Stop or start AI for a conversation
+     * @param payload - The waId and stopAi boolean
+     * @returns Result with the success message or error
+     */
+    stopConversationAi(payload: StopConversationAiPayload): Promise<Result<StopConversationAiResponse, KortexAPIError>>;
+    /**
+     * Create or update a conversation
+     * @param payload - The waId and client name
+     * @returns Result with the conversation data or error
+     */
+    upsertConversation(payload: UpsertConversationPayload): Promise<Result<UpsertConversationResponse, KortexAPIError>>;
+}
+
+export { type AssignTagsPayload, type AssignTagsResponse, AssignTagsSchema, type KortexAPIError, KortexClient, type KortexClientConfig, type SendMessagePayload, type SendMessageResponse, SendMessageSchema, type SendNotificationPayload, type SendNotificationResponse, SendNotificationSchema, type StopConversationAiPayload, type StopConversationAiResponse, StopConversationAiSchema, type UpsertConversationPayload, type UpsertConversationResponse, UpsertConversationSchema };

package/dist/index.d.ts

@@ -0,0 +1,173 @@
+import * as convex_helpers_server_zod4 from 'convex-helpers/server/zod4';
+import { z } from 'zod';
+
+type Success<T> = {
+    data: T;
+    error: null;
+};
+type Failure<E> = {
+    data: null;
+    error: E;
+};
+type Result<T, E = Error> = Success<T> | Failure<E>;
+
+declare const ConversationSchema: z.ZodObject<{
+    _id: convex_helpers_server_zod4.Zid<"conversations">;
+    _creationTime: z.ZodNumber;
+    organizationId: convex_helpers_server_zod4.Zid<"organizations">;
+    waId: z.ZodString;
+    name: z.ZodString;
+    assignedUserId: z.ZodNullable<convex_helpers_server_zod4.Zid<"users">>;
+    stopAi: z.ZodBoolean;
+    status: z.ZodEnum<{
+        open: "open";
+        closed: "closed";
+    }>;
+    messageWindowStart: z.ZodNullable<z.ZodNumber>;
+    lastMessageText: z.ZodNullable<z.ZodString>;
+    lastMessageTimestamp: z.ZodNullable<z.ZodNumber>;
+    unreadCount: z.ZodNumber;
+}, z.core.$strip>;
+type Conversation = z.infer<typeof ConversationSchema>;
+type ConversationWithTags = Conversation & {
+    tags: string[];
+};
+
+declare const AssignTagsSchema: z.ZodObject<{
+    waId: z.ZodString;
+    tags: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+type AssignTagsPayload = z.infer<typeof AssignTagsSchema>;
+type AssignTagsResponse = {
+    message: string;
+};
+declare const SendNotificationSchema: z.ZodObject<{
+    sendOptions: z.ZodArray<z.ZodEnum<{
+        push: "push";
+        email: "email";
+        dashboard: "dashboard";
+    }>>;
+    notification: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        link: z.ZodNullable<z.ZodURL>;
+        message: z.ZodString;
+        title: z.ZodString;
+        category: z.ZodLiteral<"general">;
+    }, z.core.$strip>, z.ZodObject<{
+        message: z.ZodString;
+        title: z.ZodString;
+        category: z.ZodLiteral<"chat">;
+        conversationId: convex_helpers_server_zod4.Zid<"conversations">;
+    }, z.core.$strip>, z.ZodObject<{
+        message: z.ZodString;
+        title: z.ZodString;
+        category: z.ZodLiteral<"spaces">;
+        spaceUrlPath: z.ZodString;
+    }, z.core.$strip>], "category">;
+}, z.core.$strip>;
+type SendNotificationPayload = z.infer<typeof SendNotificationSchema>;
+type SendNotificationResponse = {
+    message: string;
+};
+declare const SendMessageSchema: z.ZodObject<{
+    waId: z.ZodString;
+    message: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"text">;
+        content: z.ZodObject<{
+            text: z.ZodString;
+        }, z.core.$strip>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"note">;
+        content: z.ZodObject<{
+            text: z.ZodString;
+        }, z.core.$strip>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"template">;
+        content: z.ZodObject<{
+            name: z.ZodString;
+            language: z.ZodString;
+            header_variable: z.ZodOptional<z.ZodString>;
+            body_variables: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            button_variables: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>;
+    }, z.core.$strip>], "type">;
+    clientName: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type SendMessagePayload = z.infer<typeof SendMessageSchema>;
+type SendMessageResponse = {
+    message: string;
+};
+declare const StopConversationAiSchema: z.ZodObject<{
+    waId: z.ZodString;
+    stopAi: z.ZodBoolean;
+}, z.core.$strip>;
+type StopConversationAiPayload = z.infer<typeof StopConversationAiSchema>;
+type StopConversationAiResponse = {
+    message: string;
+};
+declare const UpsertConversationSchema: z.ZodObject<{
+    waId: z.ZodString;
+    clientName: z.ZodString;
+}, z.core.$strip>;
+type UpsertConversationPayload = z.infer<typeof UpsertConversationSchema>;
+type UpsertConversationResponse = {
+    message: string;
+    data: ConversationWithTags;
+};
+
+interface KortexClientConfig {
+    /**
+     * Base URL of the Kortex Hub API
+     * @default 'https://kortex-dashboard.vercel.app'
+     */
+    baseUrl?: string;
+    /**
+     * API token for authentication
+     */
+    apiToken: string;
+}
+type KortexAPIError = {
+    message: string;
+    statusCode?: number;
+    response?: unknown;
+};
+declare class KortexClient {
+    private readonly baseUrl;
+    private readonly apiToken;
+    constructor(config: KortexClientConfig);
+    /**
+     * Internal method to make API requests
+     */
+    private request;
+    /**
+     * Assign tags to a conversation
+     * @param payload - The waId and tags to assign
+     * @returns Result with the success message or error
+     */
+    assignTags(payload: AssignTagsPayload): Promise<Result<AssignTagsResponse, KortexAPIError>>;
+    /**
+     * Send a notification through specified channels
+     * @param payload - The notification and send options
+     * @returns Result with the success message or error
+     */
+    sendNotification(payload: SendNotificationPayload): Promise<Result<SendNotificationResponse, KortexAPIError>>;
+    /**
+     * Send a message (text, note, or template) to a WhatsApp conversation
+     * @param payload - The message details (waId, message type and content)
+     * @returns Result with the success message or error
+     */
+    sendMessage(payload: SendMessagePayload): Promise<Result<SendMessageResponse, KortexAPIError>>;
+    /**
+     * Stop or start AI for a conversation
+     * @param payload - The waId and stopAi boolean
+     * @returns Result with the success message or error
+     */
+    stopConversationAi(payload: StopConversationAiPayload): Promise<Result<StopConversationAiResponse, KortexAPIError>>;
+    /**
+     * Create or update a conversation
+     * @param payload - The waId and client name
+     * @returns Result with the conversation data or error
+     */
+    upsertConversation(payload: UpsertConversationPayload): Promise<Result<UpsertConversationResponse, KortexAPIError>>;
+}
+
+export { type AssignTagsPayload, type AssignTagsResponse, AssignTagsSchema, type KortexAPIError, KortexClient, type KortexClientConfig, type SendMessagePayload, type SendMessageResponse, SendMessageSchema, type SendNotificationPayload, type SendNotificationResponse, SendNotificationSchema, type StopConversationAiPayload, type StopConversationAiResponse, StopConversationAiSchema, type UpsertConversationPayload, type UpsertConversationResponse, UpsertConversationSchema };