@digisglobal/omnivox-sdk 0.3.0

package/dist/index.d.ts

@@ -0,0 +1,899 @@
+/**
+ * Token-provider abstraction for the Omnivox SDK.
+ *
+ * Two modes:
+ *   - API-key: attaches an `x-api-key` header; sets credentials to 'omit'.
+ *   - Session/cookie: sets credentials to 'include'; attaches no extra headers.
+ *
+ * The transport reads from the provider per request (not once at construction).
+ * Both factories are tree-shakeable — no side effects at module level.
+ */
+/**
+ * fetch `credentials` mode.
+ * Mirrors the browser's `RequestCredentials` without requiring DOM types.
+ */
+type CredentialsMode = 'omit' | 'include' | 'same-origin';
+/** Contract that every token provider must satisfy. */
+interface TokenProvider {
+    /** HTTP headers to attach to every request (e.g. x-api-key). */
+    getHeaders(): Record<string, string>;
+    /** fetch `credentials` mode for this provider. */
+    getCredentials(): CredentialsMode;
+}
+/**
+ * Creates a token provider that authenticates via the `x-api-key` header.
+ * Matches the `@ApiSecurity('x-api-key')` guard on the Omnivox API.
+ * Browser cookies are explicitly excluded (credentials: 'omit').
+ */
+declare function createApiKeyTokenProvider(apiKey: string): TokenProvider;
+/**
+ * Creates a token provider for cookie/session-based authentication (Console use-case).
+ * Sets fetch `credentials` to 'include' so the browser sends the session cookie.
+ * Attaches no explicit headers — the cookie is handled by the browser automatically.
+ */
+declare function createSessionTokenProvider(): TokenProvider;
+
+/**
+ * Messages module — hand-written typed wrapper over the generated client.
+ *
+ * Exposes the Phase-1 messaging surface for the messages resource:
+ *   - send(input)              → POST   /api/v1/messages
+ *   - list(opts)               → GET    /api/v1/messages (pageSize capped at 100)
+ *   - get(id)                  → GET    /api/v1/messages/:id
+ *   - delete(id)               → DELETE /api/v1/messages/:id
+ *
+ * Never re-exports symbols from _generated/.
+ * Contains no business logic — typed transport only.
+ */
+
+/** Options to construct the messages module. */
+interface MessagesModuleOptions extends TokenProvider {
+    /** Base URL of the Omnivox API (e.g. "https://api.omnivox.io"). */
+    baseUrl: string;
+}
+/** Input for sending a message. */
+interface SendMessageInput {
+    conversationId: string;
+    body: string;
+    [key: string]: unknown;
+}
+/** Message resource shape returned by the API. */
+interface MessageItem {
+    id: string;
+    conversationId: string;
+    body: string;
+    [key: string]: unknown;
+}
+/** Paginated list response. */
+interface PagedList$4<T> {
+    data: T[];
+    meta: {
+        page: number;
+        pageSize: number;
+        total: number;
+        hasNextPage: boolean;
+    };
+}
+/** Pagination + filter options for messages.list(). */
+interface MessageListOpts {
+    conversationId: string;
+    page: number;
+    pageSize: number;
+    includeDeleted?: boolean;
+}
+/**
+ * Creates the messages module — a thin typed wrapper over the generated client.
+ */
+declare function createMessagesModule(options: MessagesModuleOptions): {
+    /**
+     * Send a message in a conversation.
+     * Calls POST /api/v1/messages.
+     */
+    send(input: SendMessageInput): Promise<MessageItem>;
+    /**
+     * List messages in a conversation (newest first, paginated).
+     * pageSize is clamped to 100 per the API contract.
+     * Calls GET /api/v1/messages.
+     */
+    list(opts: MessageListOpts): Promise<PagedList$4<MessageItem>>;
+    /**
+     * Fetch a single message by ID.
+     * Calls GET /api/v1/messages/:id.
+     */
+    get(id: string): Promise<MessageItem>;
+    /**
+     * Soft-delete a message (sets deletedAt; row preserved).
+     * Calls DELETE /api/v1/messages/:id.
+     */
+    delete(id: string): Promise<void>;
+};
+/** Return type of createMessagesModule. */
+type MessagesModule = ReturnType<typeof createMessagesModule>;
+
+/**
+ * Conversations module — hand-written typed wrapper over the generated client.
+ *
+ * Exposes the Phase-1 messaging surface for the conversations resource:
+ *   - reopenOrCreate(input)           → POST  /api/v1/conversations/reopen-or-create
+ *   - list(opts)                      → GET   /api/v1/conversations (pageSize capped at 100)
+ *   - updateStatus(id, input)         → PATCH /api/v1/conversations/:id/status
+ *   - assign(id, input)               → PATCH /api/v1/conversations/:id/assign
+ *   - listLobby(opts)                 → GET   /api/v1/conversations/lobby (pageSize capped at 100)
+ *   - pickup(entryId, input)          → POST  /api/v1/conversations/lobby/:entryId/pickup
+ *
+ * Never re-exports symbols from _generated/.
+ * Contains no business logic — typed transport only.
+ */
+
+/** Options to construct the conversations module. */
+interface ConversationsModuleOptions extends TokenProvider {
+    /** Base URL of the Omnivox API (e.g. "https://api.omnivox.io"). */
+    baseUrl: string;
+}
+/** Input for reopen-or-create. */
+interface ReopenOrCreateInput {
+    contactIdentityId: string;
+    /**
+     * The channel to pin the conversation to (channel-as-connection Stage 5).
+     * Optional: when omitted, the API falls back to the tenant's default channel
+     * for the identity's type, or the sole channel of that type, and returns 400
+     * when ambiguous. The single-active-conversation rule is per
+     * (contactIdentity, channel).
+     */
+    channelId?: string;
+    [key: string]: unknown;
+}
+/** Input for updating conversation status. */
+interface UpdateStatusInput {
+    status: string;
+    [key: string]: unknown;
+}
+/** Input for assigning a conversation. */
+interface AssignInput {
+    agentId: string;
+    [key: string]: unknown;
+}
+/** Input for picking up a lobby entry. */
+interface PickupInput {
+    agentId: string;
+    [key: string]: unknown;
+}
+/** Conversation resource shape returned by the API. */
+interface ConversationItem {
+    id: string;
+    status: string;
+    [key: string]: unknown;
+}
+/** Lobby entry resource shape returned by the API. */
+interface LobbyEntry {
+    id: string;
+    [key: string]: unknown;
+}
+/** Paginated list response. */
+interface PagedList$3<T> {
+    data: T[];
+    meta: {
+        page: number;
+        pageSize: number;
+        total: number;
+        hasNextPage: boolean;
+    };
+}
+/** Pagination + filter options for conversations.list(). */
+interface ConversationListOpts {
+    page: number;
+    pageSize: number;
+    contactId?: string;
+    assignedAgentId?: string;
+    channel?: string;
+    status?: string;
+}
+/** Pagination options for conversations.listLobby(). */
+interface LobbyListOpts {
+    page: number;
+    pageSize: number;
+}
+/**
+ * Creates the conversations module — a thin typed wrapper over the generated client.
+ */
+declare function createConversationsModule(options: ConversationsModuleOptions): {
+    /**
+     * Idempotent reopen-or-create for a contact identity.
+     * Returns the existing non-CLOSED conversation (200) or creates a new OPEN one (201).
+     * Calls POST /api/v1/conversations/reopen-or-create.
+     */
+    reopenOrCreate(input: ReopenOrCreateInput): Promise<ConversationItem>;
+    /**
+     * List conversations with optional filters (paginated, sorted deterministically).
+     * pageSize is clamped to 100 per the API contract.
+     * Calls GET /api/v1/conversations.
+     */
+    list(opts?: ConversationListOpts): Promise<PagedList$3<ConversationItem>>;
+    /**
+     * Update a conversation status via the state machine.
+     * Calls PATCH /api/v1/conversations/:id/status.
+     */
+    updateStatus(id: string, input: UpdateStatusInput): Promise<ConversationItem>;
+    /**
+     * Assign a conversation to an agent.
+     * Calls PATCH /api/v1/conversations/:id/assign.
+     */
+    assign(id: string, input: AssignInput): Promise<ConversationItem>;
+    /**
+     * List lobby entries awaiting pickup (paginated, sorted by receivedAt DESC).
+     * pageSize is clamped to 100 per the API contract.
+     * Calls GET /api/v1/conversations/lobby.
+     */
+    listLobby(opts?: LobbyListOpts): Promise<PagedList$3<LobbyEntry>>;
+    /**
+     * Get a single conversation by ID.
+     * Calls GET /api/v1/conversations/:id.
+     */
+    get(id: string): Promise<ConversationItem>;
+    /**
+     * Pick up a lobby entry (atomic 4-step transaction).
+     * Returns the resulting conversation.
+     * Calls POST /api/v1/conversations/lobby/:entryId/pickup.
+     */
+    pickup(entryId: string, input: PickupInput): Promise<{
+        data: ConversationItem;
+    }>;
+};
+/** Return type of createConversationsModule. */
+type ConversationsModule = ReturnType<typeof createConversationsModule>;
+
+/**
+ * Contacts module — hand-written typed wrapper over the generated client.
+ *
+ * Exposes the Phase-1 messaging surface for the contacts resource:
+ *   - create(input)             → POST  /api/v1/contacts
+ *   - search(opts)              → GET   /api/v1/contacts (pageSize capped at 100)
+ *   - detail(id)                → GET   /api/v1/contacts/:id
+ *   - metadata()                → GET   /api/v1/contacts/metadata
+ *   - patch(id, input)          → PATCH /api/v1/contacts/:id
+ *   - addIdentity(id, input)    → POST  /api/v1/contacts/:id/identities
+ *
+ * Never re-exports symbols from _generated/.
+ * Contains no business logic — typed transport only.
+ */
+
+/** Options to construct the contacts module. */
+interface ContactsModuleOptions extends TokenProvider {
+    /** Base URL of the Omnivox API (e.g. "https://api.omnivox.io"). */
+    baseUrl: string;
+}
+/** Identity shape for creating a contact. */
+interface ContactIdentityInput {
+    channel: string;
+    value: string;
+    [key: string]: unknown;
+}
+/** Input for creating a contact. */
+interface CreateContactInput {
+    displayName: string;
+    identities: ContactIdentityInput[];
+    [key: string]: unknown;
+}
+/** Input for patching a contact. */
+interface PatchContactInput {
+    displayName?: string;
+    isActive?: boolean;
+    [key: string]: unknown;
+}
+/** Input for adding an identity to a contact. */
+interface AddIdentityInput {
+    channel: string;
+    value: string;
+    [key: string]: unknown;
+}
+/** Contact identity resource shape. */
+interface ContactIdentity {
+    id: string;
+    channel: string;
+    value: string;
+    [key: string]: unknown;
+}
+/** Contact resource shape returned by the API. */
+interface ContactItem {
+    id: string;
+    displayName: string;
+    identities?: ContactIdentity[];
+    [key: string]: unknown;
+}
+/** Contacts metadata (tag catalog and custom-field definitions). */
+interface ContactsMetadata {
+    tags: unknown[];
+    customFields: unknown[];
+    [key: string]: unknown;
+}
+/** Paginated list response. */
+interface PagedList$2<T> {
+    data: T[];
+    meta: {
+        page: number;
+        pageSize: number;
+        total: number;
+        hasNextPage: boolean;
+    };
+}
+/** Pagination + search options for contacts.search(). */
+interface ContactSearchOpts {
+    page: number;
+    pageSize: number;
+    q?: string;
+    [key: string]: unknown;
+}
+/**
+ * Creates the contacts module — a thin typed wrapper over the generated client.
+ */
+declare function createContactsModule(options: ContactsModuleOptions): {
+    /**
+     * Create a contact with channel identity/identities.
+     * Calls POST /api/v1/contacts.
+     */
+    create(input: CreateContactInput): Promise<ContactItem>;
+    /**
+     * Search contacts by display name or raw identifier.
+     * pageSize is clamped to 100 per the API contract.
+     * Calls GET /api/v1/contacts.
+     */
+    search(opts: ContactSearchOpts): Promise<PagedList$2<ContactItem>>;
+    /**
+     * Get contact detail with identities, tags, field values.
+     * Calls GET /api/v1/contacts/:id.
+     */
+    detail(id: string): Promise<ContactItem>;
+    /**
+     * Return the tenant's tag catalog and custom-field definitions.
+     * Calls GET /api/v1/contacts/metadata.
+     */
+    metadata(): Promise<ContactsMetadata>;
+    /**
+     * Partially update a contact.
+     * Calls PATCH /api/v1/contacts/:id.
+     */
+    patch(id: string, input: PatchContactInput): Promise<ContactItem>;
+    /**
+     * Add a channel identity to an existing contact.
+     * Calls POST /api/v1/contacts/:id/identities.
+     */
+    addIdentity(id: string, input: AddIdentityInput): Promise<ContactIdentity>;
+};
+/** Return type of createContactsModule. */
+type ContactsModule = ReturnType<typeof createContactsModule>;
+
+/**
+ * Agents module — hand-written typed wrapper over the generated client.
+ *
+ * Exposes the Phase-1 config surface for the agents resource:
+ *   - create(input)         → POST /api/v1/agents
+ *   - list(opts)            → GET  /api/v1/agents (pageSize capped at 100)
+ *   - get(id)               → GET  /api/v1/agents/:id
+ *
+ * Never re-exports symbols from _generated/.
+ * Contains no business logic — typed transport only.
+ */
+
+/** Options to construct the agents module. */
+interface AgentsModuleOptions extends TokenProvider {
+    /** Base URL of the Omnivox API (e.g. "https://api.omnivox.io"). */
+    baseUrl: string;
+}
+/** Input for creating an agent. */
+interface CreateAgentInput {
+    displayName: string;
+    email: string;
+    [key: string]: unknown;
+}
+/** Agent resource shape returned by the API. */
+interface AgentItem {
+    id: string;
+    displayName: string;
+    email: string;
+    [key: string]: unknown;
+}
+/** Paginated list response. */
+interface PagedList$1<T> {
+    data: T[];
+    meta: {
+        page: number;
+        pageSize: number;
+        total: number;
+        hasNextPage: boolean;
+    };
+}
+/** Pagination options for list. */
+interface PageOpts {
+    page: number;
+    pageSize: number;
+}
+/**
+ * Creates the agents module — a thin typed wrapper over the generated client.
+ */
+declare function createAgentsModule(options: AgentsModuleOptions): {
+    /**
+     * Create an agent for the authenticated tenant.
+     * Calls POST /api/v1/agents.
+     */
+    create(input: CreateAgentInput): Promise<AgentItem>;
+    /**
+     * List agents for the authenticated tenant (paginated, sorted deterministically).
+     * pageSize is clamped to 100 per the API contract.
+     * Calls GET /api/v1/agents.
+     */
+    list(opts?: PageOpts): Promise<PagedList$1<AgentItem>>;
+    /**
+     * Get an agent by ID.
+     * Calls GET /api/v1/agents/:id.
+     */
+    get(id: string): Promise<AgentItem>;
+};
+/** Return type of createAgentsModule. */
+type AgentsModule = ReturnType<typeof createAgentsModule>;
+
+/**
+ * Tenants module — hand-written typed wrapper over the generated client.
+ *
+ * Exposes the Phase-1 config surface for the tenants resource:
+ *   - channels.list(tenantId)              → GET /api/v1/tenants/:id/channels
+ *   - apiKeys.list(tenantId)               → GET /api/v1/tenants/:id/api-keys
+ *   - apiKeys.create(tenantId, input)      → POST /api/v1/tenants/:id/api-keys
+ *   - apiKeys.revoke(tenantId, keyId)      → DELETE /api/v1/tenants/:id/api-keys/:keyId
+ *
+ * Never re-exports symbols from _generated/.
+ * Contains no business logic — typed transport only.
+ */
+
+/** Options to construct the tenants module. */
+interface TenantsModuleOptions extends TokenProvider {
+    /** Base URL of the Omnivox API (e.g. "https://api.omnivox.io"). */
+    baseUrl: string;
+}
+/** Shape returned by tenants.channels.list(). */
+interface ChannelListItem {
+    id: string;
+    type: string;
+    name: string;
+    status: string;
+    isDefault: boolean;
+    lastVerifiedAt: string | null;
+    [key: string]: unknown;
+}
+/** Shape returned by tenants.apiKeys.list() items. */
+interface ApiKeyItem {
+    id: string;
+    label: string;
+    prefix: string;
+    scopes: string[];
+    status: 'ACTIVE' | 'REVOKED';
+    lastUsedAt: string | null;
+    createdAt: string;
+}
+/** Input for tenants.apiKeys.create(). */
+interface CreateApiKeyInput {
+    /** Human-readable label for the key. */
+    label: string;
+    /** Permission scopes. Defaults to ['*'] (all permissions). */
+    scopes?: string[];
+}
+/** Response from tenants.apiKeys.create() — includes raw key shown once. */
+interface CreateApiKeyResponse {
+    data: {
+        id: string;
+        label: string;
+        prefix: string;
+        scopes: string[];
+        status: 'ACTIVE' | 'REVOKED';
+        lastUsedAt: string | null;
+        createdAt: string;
+        /** Raw key value — shown once and never again. */
+        raw: string;
+    };
+}
+/** Response from tenants.apiKeys.revoke(). */
+interface RevokeApiKeyResponse {
+    data: {
+        id: string;
+        status: 'REVOKED';
+    };
+}
+/** Paginated list response. */
+interface PagedList<T> {
+    data: T[];
+    meta: {
+        page: number;
+        pageSize: number;
+        total: number;
+        hasNextPage: boolean;
+    };
+}
+/**
+ * Creates the tenants module — a thin typed wrapper over the generated client.
+ * The `baseUrl`, `getHeaders`, and `getCredentials` come from the SDK client
+ * instance (typically via a TokenProvider).
+ */
+declare function createTenantsModule(options: TenantsModuleOptions): {
+    /** Channels sub-surface scoped to a tenant. */
+    channels: {
+        /**
+         * List channels for a tenant (non-secret view).
+         * Calls GET /api/v1/tenants/:id/channels.
+         */
+        list(tenantId: string, opts?: {
+            page: number;
+            pageSize: number;
+        }): Promise<PagedList<ChannelListItem>>;
+    };
+    /** API-keys sub-surface scoped to a tenant. */
+    apiKeys: {
+        /**
+         * List API keys for a tenant (metadata only — never exposes secrets).
+         * Calls GET /api/v1/tenants/:id/api-keys.
+         */
+        list(tenantId: string, opts?: {
+            page: number;
+            pageSize: number;
+        }): Promise<PagedList<ApiKeyItem>>;
+        /**
+         * Create a new API key for a tenant. Returns the key metadata plus the
+         * raw key value (shown once — the API will never return it again).
+         * Calls POST /api/v1/tenants/:id/api-keys.
+         */
+        create(tenantId: string, input: CreateApiKeyInput): Promise<CreateApiKeyResponse>;
+        /**
+         * Revoke an existing API key immediately.
+         * Calls DELETE /api/v1/tenants/:id/api-keys/:keyId.
+         */
+        revoke(tenantId: string, keyId: string): Promise<RevokeApiKeyResponse>;
+    };
+};
+/** Return type of createTenantsModule. */
+type TenantsModule = ReturnType<typeof createTenantsModule>;
+
+/** Options for {@link createOmnivoxClient}. */
+interface OmnivoxClientOptions {
+    /** Base URL of the Omnivox API (e.g. "https://api.omnivox.io"). */
+    baseUrl: string;
+    /**
+     * Auth strategy for every request: an API-key provider for host apps or a
+     * session/cookie provider for the Console. Read per request.
+     */
+    tokenProvider: TokenProvider;
+}
+/**
+ * Creates a composed Omnivox client exposing every Phase-1 resource module.
+ * The token provider is read per request (not captured at construction), so
+ * the same client follows a rotating key or refreshed session transparently.
+ */
+declare function createOmnivoxClient(options: OmnivoxClientOptions): {
+    auth: {
+        me(): Promise<AuthMeResponse>;
+    };
+    tenants: {
+        channels: {
+            list(tenantId: string, opts?: {
+                page: number;
+                pageSize: number;
+            }): Promise<PagedList<ChannelListItem>>;
+        };
+        apiKeys: {
+            list(tenantId: string, opts?: {
+                page: number;
+                pageSize: number;
+            }): Promise<PagedList<ApiKeyItem>>;
+            create(tenantId: string, input: CreateApiKeyInput): Promise<CreateApiKeyResponse>;
+            revoke(tenantId: string, keyId: string): Promise<RevokeApiKeyResponse>;
+        };
+    };
+    agents: {
+        create(input: CreateAgentInput): Promise<AgentItem>;
+        list(opts?: PageOpts): Promise<PagedList$1<AgentItem>>;
+        get(id: string): Promise<AgentItem>;
+    };
+    channels: {
+        create(tenantId: string, body: CreateChannelBody): Promise<Channel>;
+        get(tenantId: string, channelId: string): Promise<Channel>;
+        update(tenantId: string, channelId: string, body: UpdateChannelBody): Promise<Channel>;
+        verify(tenantId: string, channelId: string): Promise<void>;
+    };
+    contacts: {
+        create(input: CreateContactInput): Promise<ContactItem>;
+        search(opts: ContactSearchOpts): Promise<PagedList$2<ContactItem>>;
+        detail(id: string): Promise<ContactItem>;
+        metadata(): Promise<ContactsMetadata>;
+        patch(id: string, input: PatchContactInput): Promise<ContactItem>;
+        addIdentity(id: string, input: AddIdentityInput): Promise<ContactIdentity>;
+    };
+    conversations: {
+        reopenOrCreate(input: ReopenOrCreateInput): Promise<ConversationItem>;
+        list(opts?: ConversationListOpts): Promise<PagedList$3<ConversationItem>>;
+        updateStatus(id: string, input: UpdateStatusInput): Promise<ConversationItem>;
+        assign(id: string, input: AssignInput): Promise<ConversationItem>;
+        listLobby(opts?: LobbyListOpts): Promise<PagedList$3<LobbyEntry>>;
+        get(id: string): Promise<ConversationItem>;
+        pickup(entryId: string, input: PickupInput): Promise<{
+            data: ConversationItem;
+        }>;
+    };
+    messages: {
+        send(input: SendMessageInput): Promise<MessageItem>;
+        list(opts: MessageListOpts): Promise<PagedList$4<MessageItem>>;
+        get(id: string): Promise<MessageItem>;
+        delete(id: string): Promise<void>;
+    };
+};
+/** Composed client returned by {@link createOmnivoxClient}. */
+type OmnivoxClient = ReturnType<typeof createOmnivoxClient>;
+
+/**
+ * Auth module — GET /api/v1/auth/me
+ *
+ * Returns the session subject, active tenant, and (for session actors) the
+ * acting Agent. For API-key actors the agent field is null.
+ *
+ * Hand-written typed transport — never imports from _generated/.
+ */
+
+/** The tenant fragment returned by /auth/me */
+interface AuthMeTenant {
+    id: string;
+    slug: string;
+    name: string;
+}
+/** The agent fragment returned by /auth/me (null for API-key actors) */
+interface AuthMeAgent {
+    id: string;
+    displayName: string;
+    role: string;
+}
+/** Full /auth/me response shape (inside the { data } envelope) */
+interface AuthMeResponse {
+    subject: string;
+    tenant: AuthMeTenant;
+    agent: AuthMeAgent | null;
+}
+/** Options to construct the auth-me module. */
+interface AuthMeModuleOptions extends TokenProvider {
+    /** Base URL of the Omnivox API (e.g. "https://api.omnivox.io"). */
+    baseUrl: string;
+}
+/**
+ * Creates the auth-me module — a thin typed wrapper for GET /api/v1/auth/me.
+ */
+declare function createAuthMeModule(options: AuthMeModuleOptions): {
+    /**
+     * Get the identity context for the authenticated actor.
+     * Calls GET /api/v1/auth/me.
+     *
+     * Returns the unwrapped { subject, tenant, agent } object.
+     * Throws an OmnivoxRequestError (carrying `status`) on any non-OK response,
+     * including 401 when unauthenticated.
+     */
+    me(): Promise<AuthMeResponse>;
+};
+/** Return type of createAuthMeModule. */
+type AuthMeModule = ReturnType<typeof createAuthMeModule>;
+
+/**
+ * Shared response helper for the hand-written SDK transport.
+ *
+ * Every resource module performed the same read: skip the body for no-content
+ * statuses, otherwise `JSON.parse` the text and return it — but none checked
+ * `res.ok`, so an API error envelope (`{ error: { code, message } }`) was
+ * happily returned as if it were successful data. Callers (e.g. React Query)
+ * then cached the error shape as a successful result.
+ *
+ * `parseResponse` centralises that read and throws {@link OmnivoxRequestError}
+ * on any non-2xx status, carrying the status code and the parsed error body so
+ * callers can branch on `err.status` or inspect `err.body`.
+ *
+ * Typed transport only — no business logic.
+ */
+/**
+ * Error thrown when an Omnivox API request resolves with a non-2xx status.
+ * Exposes the HTTP `status` and the parsed (or raw) error `body`.
+ */
+declare class OmnivoxRequestError extends Error {
+    /** HTTP status code of the failed response. */
+    readonly status: number;
+    /** Parsed error envelope, or the raw text when the body was not JSON. */
+    readonly body: unknown;
+    constructor(status: number, body: unknown);
+}
+
+/**
+ * Uniform pagination helper for the Omnivox SDK.
+ *
+ * Page-based, caps pageSize at 100 (matching the API contract).
+ * Tree-shakeable — no side effects at module level.
+ * Does not import from apps/api.
+ */
+/** Parameters for a single page request. */
+interface PageParams {
+    page: number;
+    pageSize: number;
+}
+/** Shape returned by list endpoints. */
+interface PagedResponse<T> {
+    data: T[];
+    meta: {
+        page: number;
+        pageSize: number;
+        total: number;
+        hasNextPage: boolean;
+    };
+}
+/**
+ * Normalises caller-supplied pagination options.
+ * Clamps `pageSize` to `MAX_PAGE_SIZE`; passes `page` through unchanged.
+ */
+declare function buildPageParams(opts: PageParams): PageParams;
+/**
+ * Iterates over all pages returned by `fetchPage`, collecting every item.
+ *
+ * - Clamps `pageSize` via `buildPageParams` before the first call.
+ * - Increments `page` after each response that has `hasNextPage: true`.
+ * - Stops as soon as `hasNextPage` is `false`.
+ * - Returns `[]` when the first page contains no items.
+ */
+declare function iteratePages<T>(fetchPage: (params: PageParams) => Promise<PagedResponse<T>>, opts: PageParams): Promise<T[]>;
+
+/**
+ * Channels module — hand-written typed wrapper over the generated client.
+ *
+ * Exposes the id-based channel surface (channel-as-connection Stage 3):
+ *   - create(tenantId, body)            → POST  /api/v1/tenants/:id/channels
+ *   - get(tenantId, channelId)          → GET   /api/v1/tenants/:id/channels/:channelId
+ *   - update(tenantId, channelId, body) → PATCH /api/v1/tenants/:id/channels/:channelId
+ *   - verify(tenantId, channelId)       → POST  /api/v1/tenants/:id/channels/:channelId/verify
+ *
+ * Never re-exports symbols from _generated/.
+ * Contains no business logic — typed transport only.
+ */
+
+/** Channel types supported in Phase 1. */
+type ChannelType = 'WHATSAPP' | 'EMAIL';
+/** Channel lifecycle status. */
+type ChannelStatus = 'ACTIVE' | 'DISABLED';
+/** Options to construct the channels module. */
+interface ChannelsModuleOptions extends TokenProvider {
+    /** Base URL of the Omnivox API (e.g. "https://api.omnivox.io"). */
+    baseUrl: string;
+}
+/** WhatsApp channel config (stored on the row). */
+interface WhatsAppChannelConfig {
+    phoneNumberId: string;
+    wabaId: string;
+}
+/** POST body to create a WhatsApp channel. */
+interface CreateWhatsAppChannelBody {
+    type: 'WHATSAPP';
+    name: string;
+    config: WhatsAppChannelConfig;
+    /** The WABA that owns this channel's secret material (ADR-0030). */
+    whatsAppBusinessAccountId: string;
+    isDefault?: boolean;
+}
+/** SMTP transport config block (shared by basic + oauth2 email). */
+interface EmailSmtpConfig {
+    host: string;
+    port: number;
+    secure: boolean;
+    fromAddress: string;
+    fromName: string;
+}
+/** IMAP transport config block (shared by basic + oauth2 email). */
+interface EmailImapConfig {
+    host: string;
+    port: number;
+    secure: boolean;
+    mailbox: string;
+    pollIntervalSeconds: number;
+}
+/** Basic-auth (SMTP/IMAP password) email config. */
+interface BasicEmailChannelConfig {
+    authMode: 'basic';
+    smtp: EmailSmtpConfig;
+    imap: EmailImapConfig;
+}
+/** Basic-auth email secret. */
+interface BasicEmailChannelSecret {
+    authMode: 'basic';
+    smtpUser: string;
+    smtpPass: string;
+    imapUser: string;
+    imapPass: string;
+}
+/** OAuth2 client-credentials (M365) email config. */
+interface OAuth2EmailChannelConfig {
+    authMode: 'oauth2';
+    provider: 'microsoft365';
+    directoryId: string;
+    clientId: string;
+    credentialType: 'clientSecret' | 'certificate';
+    scope?: string;
+    smtp: EmailSmtpConfig;
+    imap: EmailImapConfig;
+}
+/** OAuth2 secret — Azure app-registration client secret. */
+interface OAuth2ClientSecretEmailChannelSecret {
+    authMode: 'oauth2';
+    credentialType: 'clientSecret';
+    clientSecret: string;
+}
+/** OAuth2 secret — certificate private key + SHA-1 thumbprint. */
+interface OAuth2CertificateEmailChannelSecret {
+    authMode: 'oauth2';
+    credentialType: 'certificate';
+    privateKey: string;
+    thumbprint: string;
+}
+/** OAuth2 email secret — discriminated on `credentialType`. */
+type OAuth2EmailChannelSecret = OAuth2ClientSecretEmailChannelSecret | OAuth2CertificateEmailChannelSecret;
+/** Email channel config — discriminated on `authMode`. */
+type EmailChannelConfig = BasicEmailChannelConfig | OAuth2EmailChannelConfig;
+/** Email channel secret — discriminated on `authMode`. */
+type EmailChannelSecret = BasicEmailChannelSecret | OAuth2EmailChannelSecret;
+/** POST body to create an Email channel. */
+interface CreateEmailChannelBody {
+    type: 'EMAIL';
+    name: string;
+    config: EmailChannelConfig;
+    secret: EmailChannelSecret;
+    isDefault?: boolean;
+}
+/** POST body to create any channel — discriminated on `type`. */
+type CreateChannelBody = CreateWhatsAppChannelBody | CreateEmailChannelBody;
+/** PATCH body to update a channel (all fields optional; `type` is immutable). */
+interface UpdateChannelBody {
+    name?: string;
+    status?: ChannelStatus;
+    isDefault?: boolean;
+    config?: Record<string, unknown>;
+    /** Email only — rotates the stored secret (WhatsApp secret lives on its WABA). */
+    secret?: Record<string, unknown>;
+}
+/** Channel resource shape returned by the API (no secrets exposed). */
+interface Channel {
+    id: string;
+    type: ChannelType;
+    name: string;
+    status: ChannelStatus;
+    isDefault: boolean;
+    lastVerifiedAt: string | null;
+    webhookUrl?: string | null;
+    [key: string]: unknown;
+}
+/**
+ * Creates the channels module — a thin typed wrapper over the generated client.
+ * Covers the id-based channel surface (create/get/update/verify).
+ */
+declare function createChannelsModule(options: ChannelsModuleOptions): {
+    /**
+     * Create a channel. For WhatsApp the secret material lives on the linked
+     * WABA (no inline secret); for Email the `{ config, secret }` envelope is
+     * sent verbatim — secret goes to the SecretsProvider and is never echoed.
+     * Calls POST /api/v1/tenants/:id/channels.
+     */
+    create(tenantId: string, body: CreateChannelBody): Promise<Channel>;
+    /**
+     * Get a single channel by id (config + name/status/isDefault/type +
+     * webhookUrl for WhatsApp; no secrets).
+     * Calls GET /api/v1/tenants/:id/channels/:channelId.
+     */
+    get(tenantId: string, channelId: string): Promise<Channel>;
+    /**
+     * Update a channel (name/status/isDefault/config; Email may rotate secret).
+     * Calls PATCH /api/v1/tenants/:id/channels/:channelId.
+     */
+    update(tenantId: string, channelId: string, body: UpdateChannelBody): Promise<Channel>;
+    /**
+     * Verify a channel through its adapter; on success sets lastVerifiedAt.
+     * Calls POST /api/v1/tenants/:id/channels/:channelId/verify.
+     */
+    verify(tenantId: string, channelId: string): Promise<void>;
+};
+/** Return type of createChannelsModule. */
+type ChannelsModule = ReturnType<typeof createChannelsModule>;
+
+export { type AddIdentityInput, type AgentItem, type AgentsModule, type AgentsModuleOptions, type ApiKeyItem, type AssignInput, type AuthMeAgent, type AuthMeModule, type AuthMeModuleOptions, type AuthMeResponse, type AuthMeTenant, type BasicEmailChannelConfig, type BasicEmailChannelSecret, type Channel, type ChannelListItem, type ChannelStatus, type ChannelType, type ChannelsModule, type ChannelsModuleOptions, type ContactIdentity, type ContactIdentityInput, type ContactItem, type ContactSearchOpts, type ContactsMetadata, type ContactsModule, type ContactsModuleOptions, type ConversationItem, type ConversationListOpts, type ConversationsModule, type ConversationsModuleOptions, type CreateAgentInput, type CreateApiKeyInput, type CreateApiKeyResponse, type CreateChannelBody, type CreateContactInput, type CreateEmailChannelBody, type CreateWhatsAppChannelBody, type CredentialsMode, type EmailChannelConfig, type EmailChannelSecret, type EmailImapConfig, type EmailSmtpConfig, type LobbyEntry, type LobbyListOpts, type MessageItem, type MessageListOpts, type MessagesModule, type MessagesModuleOptions, type OAuth2CertificateEmailChannelSecret, type OAuth2ClientSecretEmailChannelSecret, type OAuth2EmailChannelConfig, type OAuth2EmailChannelSecret, type OmnivoxClient, type OmnivoxClientOptions, OmnivoxRequestError, type PageOpts, type PageParams, type PagedResponse, type PatchContactInput, type PickupInput, type ReopenOrCreateInput, type RevokeApiKeyResponse, type SendMessageInput, type TenantsModule, type TenantsModuleOptions, type TokenProvider, type UpdateChannelBody, type UpdateStatusInput, type WhatsAppChannelConfig, buildPageParams, createAgentsModule, createApiKeyTokenProvider, createAuthMeModule, createChannelsModule, createContactsModule, createConversationsModule, createMessagesModule, createOmnivoxClient, createSessionTokenProvider, createTenantsModule, iteratePages };