@channlize/core 0.1.0 → 0.4.0

package/dist/index.d.ts

@@ -1,8 +1,74 @@
+/**
+ * Helpers shared by `@channlize/core`, `@channlize/react` and
+ * `@channlize/mcp`: defaults, key detection, environment variables, event
+ * keys and the API's error shape. Core is the single source for these.
+ */
+/** Default API base URL. */
+declare const DEFAULT_BASE_URL = "https://api.channlize.com";
+/** Default request timeout, in milliseconds. */
+declare const DEFAULT_TIMEOUT = 10000;
+/** Log tracking severities, lowest first. */
+declare const EVENT_SEVERITIES: readonly ["info", "warning", "error"];
+/**
+ * Valid Events key (same rule as the API): lowercase letters, digits,
+ * dots, underscores and dashes, e.g. `user.subscribed`. At most 100
+ * characters.
+ */
+declare const EVENT_KEY_PATTERN: RegExp;
+/** Whether `event` is a valid Events key for `notify`. */
+declare function isValidEventKey(event: unknown): event is string;
+type KeyKind = 'widget' | 'server';
+/**
+ * `wk_…` is the public widget key (browser: contact form, chat, browser
+ * log tracking); anything else is a server API key (`ch_live_…`).
+ */
+declare function keyKind(key: string): KeyKind;
+/** The `CHANNLIZE_*` environment variables, trimmed (empty → undefined). */
+interface ChannlizeEnv {
+    /** `CHANNLIZE_SERVER_API_KEY` */
+    serverApiKey?: string;
+    /** `CHANNLIZE_WIDGET_KEY` */
+    widgetKey?: string;
+    /** `CHANNLIZE_API_KEY` (either kind of key) */
+    apiKey?: string;
+    /** `CHANNLIZE_PROJECT_ID` */
+    projectId?: string;
+    /** `CHANNLIZE_BASE_URL` */
+    baseUrl?: string;
+    /** `CHANNLIZE_TIMEOUT` (milliseconds, unparsed) */
+    timeout?: string;
+}
+/**
+ * Reads the `CHANNLIZE_*` environment variables. Safe in browsers and edge
+ * runtimes without `process` (everything is undefined there).
+ */
+declare function readChannlizeEnv(env?: Record<string, string | undefined> | undefined): ChannlizeEnv;
+/** A failed API response, parsed from its JSON body. */
+interface ApiErrorInfo {
+    status: number;
+    /** Human-readable text (field messages joined with `, `). */
+    message: string;
+    /** Machine-readable code: the body's `code`, else its `error` (e.g. `NOT_FOUND`). */
+    code?: string;
+    /** `requestId` from the body, to quote to support. */
+    requestId?: string;
+    /** The parsed body (e.g. `limit`, `used`, `resetAt` on a plan-limit 429). */
+    body: Record<string, unknown>;
+}
+/**
+ * Parses the API's error shape (`api/lib/api/error.ts`):
+ * `{ statusCode, error: "NOT_FOUND", message: string | string[], requestId? }`.
+ * A few legacy routes put the human text in `error`.
+ */
+declare function parseApiError(status: number, body: unknown, statusText?: string): ApiErrorInfo;
+
 /**
  * Core types for Channlize SDK
  */
-/** Severity for tracked events (Slack routing uses project settings). */
-type EventSeverity = 'info' | 'warning' | 'error';
+
+/** Severity for log tracking (`trackEvent` / `trackServerEvent`); Slack alerts use project settings. */
+type EventSeverity = (typeof EVENT_SEVERITIES)[number];
+/** Options for log tracking (`trackEvent` / `trackServerEvent`). */
 interface TrackEventOptions {
     properties?: Record<string, unknown>;
     severity?: EventSeverity;
@@ -11,20 +77,78 @@ interface TrackEventOptions {
     userAgent?: string;
 }
 interface ChannlizeConfig {
-    /** Widget key used for public SDK endpoints (contact form, chat, browser event tracking) */
+    /** Widget key used for public SDK endpoints (contact form, chat, browser log tracking) */
     apiKey: string;
     /** Base URL for the Channlize API */
     baseUrl?: string;
-    /** Project ID (required for server-side `trackServerEvent`) */
+    /** Project ID (required for server-side `trackServerEvent` and `notify`) */
     projectId: string;
     /** Request timeout in milliseconds */
     timeout?: number;
     /**
-     * Organization API key for server-side `trackServerEvent` (`POST /v1/events`).
-     * Do not expose in browser bundles.
+     * Organization (server) API key, `ch_live_…`, for `trackServerEvent`
+     * (`POST /v1/events`) and `notify` (`POST /v1/notify`, needs the `write`
+     * scope). Do not expose in browser bundles.
      */
     serverApiKey?: string;
 }
+/**
+ * Events (notify Slack from code). Augment this interface to type event
+ * keys and their data across your app:
+ *
+ * ```ts
+ * declare module '@channlize/core' {
+ *   interface ChannlizeEvents {
+ *     'user.subscribed': { username: string; plan: string };
+ *   }
+ * }
+ * ```
+ *
+ * Or pass a map as a type argument: `createNotifier<AppEvents>()`.
+ */
+interface ChannlizeEvents {
+}
+/** A declared event key (autocompleted) or any other key. */
+type NotifyEventName<TEvents extends object = ChannlizeEvents> = (keyof TEvents & string) | (string & {});
+/** The declared data for a key, or any object for undeclared keys. */
+type NotifyEventData<TEvents extends object = ChannlizeEvents, K = string> = K extends keyof TEvents ? TEvents[K] : Record<string, unknown>;
+interface NotifyOptions {
+    /**
+     * Retry-safe sends: a key already used on the project returns the first
+     * delivery (`duplicate: true`) and posts nothing. Sent as `Idempotency-Key`.
+     */
+    idempotencyKey?: string;
+    /** Slack channel ID to post to instead of the event's channel, for this call. */
+    channel?: string;
+}
+interface NotifyResponse {
+    success: boolean;
+    /** Delivery ID (see Events → Recent deliveries in the dashboard). */
+    id: string;
+    event: string;
+    /**
+     * `queued`: will be posted to Slack. `skipped`: not posted (see `reason`):
+     * the event is disabled, is new (saved as a draft to configure), or there
+     * is no Slack workspace / channel. With `duplicate`, the first call's status.
+     */
+    status: 'queued' | 'skipped' | 'sent' | 'failed';
+    reason?: string;
+    duplicate?: boolean;
+}
+/** `createNotifier` options; each falls back to an environment variable. */
+interface NotifierConfig {
+    /**
+     * Server API key (`ch_live_…`, write scope). Default:
+     * `CHANNLIZE_SERVER_API_KEY`, else `CHANNLIZE_API_KEY`.
+     */
+    serverApiKey?: string;
+    /** Project ID. Default: `CHANNLIZE_PROJECT_ID`. */
+    projectId?: string;
+    /** API base URL. Default: `CHANNLIZE_BASE_URL`, else `https://api.channlize.com`. */
+    baseUrl?: string;
+    /** Request timeout in ms (default 10000). */
+    timeout?: number;
+}
 interface ContactFormData {
     /** Contact's name */
     name: string;
@@ -46,11 +170,15 @@ interface ChatMessage {
     id: string;
     /** Message content */
     content: string;
-    /** Message timestamp */
+    /**
+     * Message timestamp. The API sends an ISO 8601 string, which
+     * `ChannlizeClient` passes through as is; `@channlize/react` converts it
+     * to a `Date`. Wrap it in `new Date(...)` before using `Date` methods.
+     */
     timestamp: Date;
     /** Message author (user or agent) */
     author: 'user' | 'agent';
-    /** Author metadata */
+    /** Author metadata (`name` / `email` can be `null` in message history) */
     authorData?: {
         name?: string;
         email?: string;
@@ -74,15 +202,23 @@ interface FileAttachment {
 interface ChatSession {
     /** Session ID */
     id: string;
-    /** Session status */
+    /**
+     * Session status. `createChatSession` answers `active`; `getChatSession`
+     * and `closeChatSession` answer the conversation's status (`open`,
+     * `pending`, `resolved` or `closed`).
+     */
     status: 'active' | 'closed' | 'waiting';
-    /** Messages in the session */
+    /**
+     * Messages in the session. Only `createChatSession` returns it (empty);
+     * `getChatSession`, `closeChatSession` and `sendMessage` return a session
+     * summary without it. Load history with `getChatMessages`.
+     */
     messages: ChatMessage[];
     /** Session metadata */
     metadata?: Record<string, unknown>;
-    /** Created timestamp */
+    /** Created timestamp (an ISO 8601 string on the wire; not sent by `closeChatSession`) */
     createdAt: Date;
-    /** Updated timestamp */
+    /** Updated timestamp (an ISO 8601 string on the wire) */
     updatedAt: Date;
 }
 interface ApiResponse<T = unknown> {
@@ -119,7 +255,7 @@ interface CreateChatSessionResponse {
 interface SendMessageResponse {
     /** The sent message */
     message: ChatMessage;
-    /** Updated session */
+    /** The session (the API sends only `id` and `status`) */
     session: ChatSession;
 }
 /**
@@ -128,6 +264,13 @@ interface SendMessageResponse {
 declare class ChannlizeError extends Error {
     statusCode?: number | undefined;
     code?: string | undefined;
+    /** The API's `requestId` for a failed response, to quote to support. */
+    requestId?: string;
+    /**
+     * The API's JSON error body, e.g. `limit`, `used`, `resetAt` and
+     * `upgradeUrl` on a plan-limit 429. Undefined for network errors.
+     */
+    details?: Record<string, unknown>;
     constructor(message: string, statusCode?: number | undefined, code?: string | undefined);
 }
 declare class ValidationError extends ChannlizeError {
@@ -137,20 +280,39 @@ declare class ValidationError extends ChannlizeError {
 declare class AuthenticationError extends ChannlizeError {
     constructor(message?: string);
 }
+/**
+ * A 429. `code` is `PLAN_LIMIT_REACHED` when the organization is past its
+ * plan's limit for the billing period (the API's 110 % hard cap), else
+ * `RATE_LIMIT_ERROR`.
+ */
 declare class RateLimitError extends ChannlizeError {
-    constructor(message?: string);
+    constructor(message?: string, code?: string);
+}
+/**
+ * What `trackEvent` / `trackServerEvent` resolve with. When the API refuses
+ * the event with a 429 (rate limit or plan limit), the call resolves with
+ * `success: false` and `dropped` instead of throwing: log tracking never
+ * breaks the app that calls it.
+ */
+interface TrackEventResult {
+    success: boolean;
+    id: string;
+    /** Set when the event was refused and not stored. */
+    dropped?: 'plan_limit' | 'rate_limit';
 }
 
 /**
  * Channlize API Client
- * Provides methods to interact with the Channlize platform
+ * Provides methods to interact with the Channlize platform.
+ *
+ * `TEvents` types `notify()` event keys and data (defaults to the
+ * augmentable `ChannlizeEvents` interface; any string key is accepted).
  */
-declare class ChannlizeClient {
+declare class ChannlizeClient<TEvents extends object = ChannlizeEvents> {
     private readonly config;
     constructor(config: ChannlizeConfig);
     private validateConfig;
     private makeRequest;
-    private handleErrorResponse;
     /**
      * Submit a contact form
      */
@@ -178,23 +340,53 @@ declare class ChannlizeClient {
      */
     closeChatSession(sessionId: string): Promise<ChatSession>;
     /**
-     * Track a product or UX event from the browser (uses widget key → POST /public/events).
+     * Log tracking: record a log line from the browser (widget key →
+     * `POST /public/events`). Shown under Log tracking in the dashboard.
      */
-    trackEvent(name: string, options?: TrackEventOptions): Promise<{
-        success: boolean;
-        id: string;
-    }>;
+    trackEvent(name: string, options?: TrackEventOptions): Promise<TrackEventResult>;
+    private sendBrowserEvent;
     /**
-     * Track an event from a trusted server using the organization API key (POST /v1/events).
+     * Log tracking from a trusted server, using the organization API key
+     * (`POST /v1/events`). Shown under Log tracking in the dashboard.
      */
     trackServerEvent(name: string, options?: {
         properties?: Record<string, unknown>;
         severity?: EventSeverity;
-    }): Promise<{
-        success: boolean;
-        id: string;
-    }>;
+    }): Promise<TrackEventResult>;
+    /**
+     * Log tracking must never break the caller: a 429 (rate limit, or the
+     * plan's limit for the billing period) resolves with `success: false`
+     * and `dropped` instead of throwing, with one console warning per client.
+     */
+    private nonFatalTracking;
+    private warnedDropped;
+    private sendServerEvent;
+    /**
+     * Events: post a Slack message from your server when something happens
+     * (`POST /v1/notify`). The event key picks the channel and message
+     * template configured under Events in the dashboard; `data` fills the
+     * template's `{{field}}` placeholders. Needs `serverApiKey` (write scope)
+     * and `projectId` — never call it from browser code.
+     *
+     * An unknown key is saved as a disabled draft and answered with
+     * `status: 'skipped'`, so it never throws for a missing setup.
+     */
+    notify<K extends NotifyEventName<TEvents>>(event: K, data?: NotifyEventData<TEvents, K>, options?: NotifyOptions): Promise<NotifyResponse>;
 }
 
-export { AuthenticationError, ChannlizeClient, ChannlizeError, RateLimitError, ValidationError, ChannlizeClient as default };
-export type { ApiResponse, ChannlizeConfig, ChatMessage, ChatSession, ContactFormData, CreateChatSessionResponse, CreateContactResponse, EventSeverity, FileAttachment, SendMessageResponse, TrackEventOptions };
+type Notifier<TEvents extends object = ChannlizeEvents> = <K extends NotifyEventName<TEvents>>(event: K, data?: NotifyEventData<TEvents, K>, options?: NotifyOptions) => Promise<NotifyResponse>;
+/**
+ * Events: a standalone server-side `notify(event, data)` function. Reads
+ * the server key from `CHANNLIZE_SERVER_API_KEY` or `CHANNLIZE_API_KEY`, and
+ * `CHANNLIZE_PROJECT_ID`, unless given — when it is called, so creating it
+ * at module load never throws.
+ *
+ * ```ts
+ * const notify = createNotifier();
+ * await notify('user.subscribed', { username: 'ada', plan: 'Pro' });
+ * ```
+ */
+declare function createNotifier<TEvents extends object = ChannlizeEvents>(config?: NotifierConfig): Notifier<TEvents>;
+
+export { AuthenticationError, ChannlizeClient, ChannlizeError, DEFAULT_BASE_URL, DEFAULT_TIMEOUT, EVENT_KEY_PATTERN, EVENT_SEVERITIES, RateLimitError, ValidationError, createNotifier, ChannlizeClient as default, isValidEventKey, keyKind, parseApiError, readChannlizeEnv };
+export type { ApiErrorInfo, ApiResponse, ChannlizeConfig, ChannlizeEnv, ChannlizeEvents, ChatMessage, ChatSession, ContactFormData, CreateChatSessionResponse, CreateContactResponse, EventSeverity, FileAttachment, KeyKind, Notifier, NotifierConfig, NotifyEventData, NotifyEventName, NotifyOptions, NotifyResponse, SendMessageResponse, TrackEventOptions, TrackEventResult };