@digisglobal/omnivox-sdk 0.3.0 → 0.4.1

package/README.md

@@ -0,0 +1,208 @@
+# @digisglobal/omnivox-sdk
+
+TypeScript SDK for integrating your backend product with the Omnivox API.
+
+Use this package from server-side application code to authenticate with an Omnivox tenant, work with contacts and conversations, and send or list messages through the tenant's configured channels.
+
+## Installation
+
+```bash
+pnpm add @digisglobal/omnivox-sdk
+```
+
+Other package managers work too:
+
+```bash
+npm install @digisglobal/omnivox-sdk
+yarn add @digisglobal/omnivox-sdk
+```
+
+## Prerequisites
+
+Before writing code, get these values from your Omnivox tenant admin, Omnivox Console, or Omnivox support contact:
+
+- Your Omnivox API base URL
+- An Omnivox API key for your tenant
+
+Use placeholders like this in local development:
+
+```bash
+OMNIVOX_BASE_URL=https://api.example.com
+OMNIVOX_API_KEY=ovx_live_xxxxxx
+```
+
+Keep the API key on your server. Do not expose it in browser bundles, mobile apps, logs, or client-side configuration.
+
+## Create a Client
+
+```ts
+import {
+  createApiKeyTokenProvider,
+  createOmnivoxClient,
+} from '@digisglobal/omnivox-sdk'
+
+const baseUrl = process.env.OMNIVOX_BASE_URL
+const apiKey = process.env.OMNIVOX_API_KEY
+
+if (!baseUrl || !apiKey) {
+  throw new Error('OMNIVOX_BASE_URL and OMNIVOX_API_KEY are required')
+}
+
+export const omnivox = createOmnivoxClient({
+  baseUrl,
+  tokenProvider: createApiKeyTokenProvider(apiKey),
+})
+```
+
+## Verify Access
+
+Start with `auth.me()` to confirm that the base URL and API key are valid:
+
+```ts
+const me = await omnivox.auth.me()
+
+console.log(`Connected to Omnivox tenant: ${me.tenant.name}`)
+```
+
+For API-key authentication, `me.agent` is `null` because the request is made as a tenant API key rather than a logged-in Console agent.
+
+## Available Modules
+
+The composed client exposes these modules:
+
+- `auth` - current tenant and actor context
+- `tenants` - tenant-scoped channels and API keys
+- `agents` - tenant agents
+- `channels` - WhatsApp and Email channel configuration
+- `contacts` - contacts, identities, tags, and custom fields
+- `conversations` - conversation lifecycle, assignment, and lobby pickup
+- `messages` - send, list, fetch, and soft-delete messages
+
+## Common Workflows
+
+### Search Contacts
+
+```ts
+const contacts = await omnivox.contacts.search({
+  page: 1,
+  pageSize: 20,
+  q: 'alex',
+})
+
+for (const contact of contacts.data) {
+  console.log(contact.displayName)
+}
+```
+
+### Create a Contact
+
+```ts
+const contact = await omnivox.contacts.create({
+  displayName: 'Alex Rivera',
+  identities: [
+    {
+      channel: 'EMAIL',
+      value: 'alex@example.com',
+    },
+  ],
+})
+
+console.log(contact)
+```
+
+### Create or Reopen a Conversation
+
+Use `reopenOrCreate()` when your product needs an active conversation for a known contact identity. If an active conversation already exists for the contact identity and channel, Omnivox returns it; otherwise Omnivox creates a new one.
+
+```ts
+const conversation = await omnivox.conversations.reopenOrCreate({
+  contactIdentityId: 'contact_identity_id',
+  channelId: 'channel_id',
+})
+
+console.log(conversation)
+```
+
+### Send a Message
+
+```ts
+const message = await omnivox.messages.send({
+  conversationId: 'conversation_id',
+  body: 'Hello from your product.',
+})
+
+console.log(message)
+```
+
+### Iterate Through Paginated Results
+
+List endpoints return `{ data, meta }`. Use `iteratePages()` when you need to collect every page.
+
+```ts
+import { iteratePages } from '@digisglobal/omnivox-sdk'
+
+const allContacts = await iteratePages(
+  (params) => omnivox.contacts.search(params),
+  { page: 1, pageSize: 100 },
+)
+
+console.log(`Loaded ${allContacts.length} contacts`)
+```
+
+The SDK clamps `pageSize` to the API maximum of `100`.
+
+## Error Handling
+
+SDK methods throw `OmnivoxRequestError` for non-2xx API responses. The error includes the HTTP status and parsed response body.
+
+```ts
+import { OmnivoxRequestError } from '@digisglobal/omnivox-sdk'
+
+try {
+  await omnivox.auth.me()
+} catch (error) {
+  if (error instanceof OmnivoxRequestError) {
+    console.error('Omnivox request failed', {
+      status: error.status,
+      body: error.body,
+    })
+  }
+
+  throw error
+}
+```
+
+Common statuses during onboarding:
+
+- `401` - missing, invalid, or revoked API key
+- `400` - request body or query parameter failed validation
+- `404` - the requested resource does not exist in your tenant
+- `422` - the requested operation is not allowed by the channel or conversation state
+
+## Security Notes
+
+- Treat Omnivox API keys as server-side secrets.
+- Do not put API keys in frontend code, mobile apps, or public repositories.
+- Store API keys in your backend secret manager or deployment environment variables.
+- Rotate or revoke API keys through your Omnivox admin flow when they are no longer needed.
+
+## Runtime Notes
+
+- Node.js `>=22` is supported.
+- The SDK uses the platform `fetch` API. Node.js 22 includes `fetch` globally.
+- The package ships ESM, CommonJS, and TypeScript declarations.
+- Browser session-cookie authentication exists for Omnivox Console-style applications, but backend API-key authentication is the recommended path for tenant product integrations.
+
+## API Reference
+
+For complete request and response schemas, open the API reference for your Omnivox environment:
+
+```text
+<OMNIVOX_BASE_URL>/docs
+```
+
+For example, if your base URL is `https://api.example.com`, the API reference is available at `https://api.example.com/docs`.
+
+## Support
+
+If you do not have a base URL, tenant, or API key, contact your Omnivox tenant admin, Omnivox account team, or Omnivox support contact.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@digisglobal/omnivox-sdk",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "type": "module",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -12,10 +12,12 @@
     "./package.json": "./package.json"
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
   },
   "engines": {
     "node": ">=22"