@channlize/core 0.1.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # @channlize/core
 
+## 0.4.0
+
+### Minor Changes
+
+- 5663cd2: Make `@channlize/core` the single source for what the packages share.
+
+  - core exports `DEFAULT_BASE_URL`, `DEFAULT_TIMEOUT`, `EVENT_SEVERITIES`, `EVENT_KEY_PATTERN`, `isValidEventKey`, `keyKind` (widget vs. server key), `readChannlizeEnv` (the `CHANNLIZE_*` variables) and `parseApiError` (the API's error shape). `createNotifier`, the client and `@channlize/mcp` use them instead of their own copies.
+  - `ChannlizeError` gains `requestId` and `details` (the API's error body, e.g. `limit`, `used` and `resetAt` on a plan-limit 429). When a legacy route puts its human-readable text in `error`, it becomes the message instead of `HTTP <status>`.
+  - The chat types document where the API differs from them (ISO string timestamps, session summaries without `messages`).
+  - `@channlize/react` and `@channlize/mcp` re-export the error classes as values, so `instanceof` works without importing core.
+  - mcp tool errors no longer end with a doubled period when a core error message ends with one.
+
+- Release every `@channlize/*` package under one shared version. From 0.4.0 on, core, react, mcp and skills always publish together at the same version, so matching versions work together.
+
+## 0.2.2
+
+Not published on its own; these changes ship in 0.4.0.
+
+### Patch Changes
+
+- 097ad44: Log tracking no longer throws when the API refuses an event with a 429: `trackEvent` and `trackServerEvent` resolve with `{ success: false, id: '', dropped: 'plan_limit' | 'rate_limit' }` and log one console warning, so reaching the plan's log tracking limit (`PLAN_LIMIT_REACHED`) or the rate limit never breaks the calling app. `RateLimitError.code` is now `PLAN_LIMIT_REACHED` for plan-limit refusals (for example from `notify()`), and `TrackEventResult` is exported.
+
+## 0.2.1
+
+### Patch Changes
+
+- 69f414f: `submitContactForm` now sends `customFields` (they were silently dropped), so a contact form's topic, company and custom fields reach the API and the Slack post.
+
+## 0.2.0
+
+### Minor Changes
+
+- c113208: Add Events: post a Slack message from your server when something happens.
+
+  - `@channlize/core`: `client.notify(event, data?, { idempotencyKey?, channel? })` and a standalone `createNotifier()` that reads `CHANNLIZE_SERVER_API_KEY` / `CHANNLIZE_API_KEY` and `CHANNLIZE_PROJECT_ID`. Both call `POST /v1/notify` with the server API key (write scope). Event keys and data can be typed with `createNotifier<AppEvents>()` or by augmenting `ChannlizeEvents`. `trackEvent` / `trackServerEvent` are unchanged and now documented as log tracking. Fix: an explicit `baseUrl: undefined` or `timeout: undefined` no longer overrides the defaults.
+  - `@channlize/mcp`: new `notify_event` tool, enabled with `--server-api-key` / `CHANNLIZE_SERVER_API_KEY`.
+  - `@channlize/react`: docs only. `useChannlizeAnalytics().track` is documented as log tracking.
+
 ## 0.1.0
 
 ### Minor Changes
@@ -7,7 +45,7 @@
 - 9ddf630: Errors thrown by the client now carry the API's human-readable `message`
   (field messages joined for validation failures) instead of the error code,
   and `ChannlizeError.code` is set from the API's `error` code.
-  
+
   `CreateContactResponse` gains the fields the API actually returns:
   `success`, `conversationId` and `message`. The old `id`, `status` and
   `slackThreadUrl` fields were never returned and are deprecated. The MCP

package/README.md

@@ -1,6 +1,6 @@
 # @channlize/core
 
-Core TypeScript SDK for the Channlize platform. Provides API client functionality for submitting contact forms and managing chat sessions.
+Core TypeScript SDK for the Channlize platform. Provides API client functionality for submitting contact forms, managing chat sessions, posting Events to Slack from your server, and log tracking.
 
 ## Installation
 
@@ -8,6 +8,15 @@ Core TypeScript SDK for the Channlize platform. Provides API client functionalit
 npm install @channlize/core
 ```
 
+## Quick start: notify Slack from your server (Events)
+
+```typescript
+import { createNotifier } from '@channlize/core';
+
+const notify = createNotifier(); // reads CHANNLIZE_API_KEY (server key) + CHANNLIZE_PROJECT_ID
+await notify('user.subscribed', { username: user.name, plan: 'Pro' });
+```
+
 ## Usage
 
 ### Basic Setup
@@ -16,7 +25,7 @@ npm install @channlize/core
 import { ChannlizeClient } from '@channlize/core';
 
 const client = new ChannlizeClient({
-  apiKey: 'your-api-key',
+  apiKey: 'wk_…', // public widget key
   projectId: 'your-project-id',
   baseUrl: 'https://api.channlize.com', // optional
   timeout: 10000, // optional, default 10s
@@ -38,18 +47,15 @@ const response = await client.submitContactForm({
   },
 });
 
-console.log('Submission ID:', response.id);
-console.log('Slack thread:', response.slackThreadUrl);
+console.log('Conversation:', response.conversationId);
 ```
 
 ### Chat Sessions
 
 ```typescript
 // Create a new chat session
-const sessionResponse = await client.createChatSession({
-  userAgent: navigator.userAgent,
-  pageUrl: window.location.href,
-});
+// Metadata is optional; pageUrl and userAgent are added in the browser.
+const sessionResponse = await client.createChatSession({ plan: 'pro' });
 
 const session = sessionResponse.session;
 
@@ -69,13 +75,81 @@ const messages = await client.getChatMessages(session.id, 50, 0);
 // Close session
 await client.closeChatSession(session.id);
 
-// Event tracking (browser)
+```
+
+### Events: notify Slack from your server
+
+Post a Slack message when something happens in your app. Each event key (`user.subscribed`, `invoice.paid`…) has its own Slack channel and message template, configured under **Events** in the dashboard; `data` fills the template's `{{field}}` placeholders (e.g. `:tada: *{{username}}* subscribed to {{plan}}`).
+
+```typescript
+import { createNotifier } from '@channlize/core';
+
+// Server key from CHANNLIZE_SERVER_API_KEY or CHANNLIZE_API_KEY (ch_live_…, write scope),
+// project from CHANNLIZE_PROJECT_ID, API from CHANNLIZE_BASE_URL (optional).
+// Or pass them: createNotifier({ serverApiKey, projectId, baseUrl }).
+const notify = createNotifier();
+
+const res = await notify('user.subscribed', { username: 'ada', plan: 'Pro' });
+// res.status: 'queued' (posting to Slack) or 'skipped' (see res.reason)
+
+// Retry-safe: the same idempotency key is only posted once.
+await notify('invoice.paid', { amount: '$49' }, { idempotencyKey: invoice.id });
+
+// Post one call to another channel (Slack channel ID).
+await notify('deploy.finished', { version: '1.4.2' }, { channel: 'C0123456' });
+
+// Or on a client configured with serverApiKey + projectId:
+await client.notify('user.subscribed', { username: 'ada', plan: 'Pro' });
+```
+
+- **Server only.** It needs a server API key; never ship it to the browser. Calling with the public widget key (`wk_…`) throws a `ValidationError`.
+- **Ship code before configuring.** An event key the dashboard doesn't know yet is saved as a disabled draft and answered `status: 'skipped'` (no exception), ready to configure and enable.
+- The Channlize bot must be in the Slack channel (`/invite @Channlize`); otherwise the delivery fails, and the dashboard shows why under **Events → Recent deliveries**.
+
+Typed event names and data (optional):
+
+```typescript
+type AppEvents = {
+  'user.subscribed': { username: string; plan: string };
+  'invoice.paid': { amount: string };
+};
+const notify = createNotifier<AppEvents>();
+await notify('user.subscribed', { username: 'ada', plan: 'Pro' }); // autocompleted + type-checked
+
+// Or app-wide, for client.notify too:
+declare module '@channlize/core' {
+  interface ChannlizeEvents {
+    'user.subscribed': { username: string; plan: string };
+  }
+}
+```
+
+Without the SDK:
+
+```bash
+curl -X POST https://api.channlize.com/api/v1/notify \
+  -H "Authorization: Bearer $CHANNLIZE_API_KEY" \
+  -H "Content-Type: application/json" \
+  -H "Idempotency-Key: signup-42" \
+  -d '{"projectId":"<project id>","event":"user.subscribed","data":{"username":"ada","plan":"Pro"}}'
+```
+
+### Log tracking
+
+Record logs that show up under **Log tracking** in the dashboard (Settings → Log tracking can alert Slack on matching logs).
+
+```typescript
+// Browser (widget key)
 await client.trackEvent('page.viewed', { properties: { path: '/pricing' } });
 
-// Event tracking (server; set serverApiKey on the client)
+// Server (set serverApiKey on the client)
 await client.trackServerEvent('webhook.received', { severity: 'warning' });
 ```
 
+Log tracking never breaks your app over limits: when the API answers `429` (the rate limit, or your plan's log tracking limit for the billing period, `PLAN_LIMIT_REACHED`), both calls resolve with `{ success: false, id: '', dropped: 'plan_limit' | 'rate_limit' }` instead of throwing, and the client logs one console warning. Other errors (bad input, network) still throw.
+
+`notify()` is different: a `429` there throws a `RateLimitError` whose `code` is `PLAN_LIMIT_REACHED` when the plan's Events limit is reached, so your server can see that the Slack message was not sent.
+
 ### Error Handling
 
 ```typescript
@@ -111,8 +185,9 @@ try {
 
 ```typescript
 interface ChannlizeConfig {
-  apiKey: string;           // Required: Your API key
+  apiKey: string;           // Required: Your widget key
   projectId: string;        // Required: Your project ID
+  serverApiKey?: string;    // Server-side only: server API key, for notify / trackServerEvent
   baseUrl?: string;         // Optional: API base URL
   timeout?: number;         // Optional: Request timeout in ms
 }
@@ -126,10 +201,17 @@ interface ChannlizeConfig {
 - `getChatSession(sessionId: string): Promise<ChatSession>`
 - `getChatMessages(sessionId: string, limit?: number, offset?: number): Promise<ChatMessage[]>`
 - `closeChatSession(sessionId: string): Promise<ChatSession>`
+- `notify(event: string, data?: Record<string, unknown>, options?: NotifyOptions): Promise<NotifyResponse>` — Events (server)
+- `trackEvent(name: string, options?: TrackEventOptions): Promise<TrackEventResult>` — log tracking (browser); a 429 resolves with `dropped`
+- `trackServerEvent(name: string, options?): Promise<TrackEventResult>` — log tracking (server); a 429 resolves with `dropped`
+
+### createNotifier
+
+`createNotifier<TEvents>(config?: NotifierConfig): (event, data?, options?) => Promise<NotifyResponse>` — standalone server-side Events sender (see above).
 
 ### Types
 
-All TypeScript types are exported from the package:
+All TypeScript types are exported from the package. The error classes (`ChannlizeError`, `ValidationError`, `AuthenticationError`, `RateLimitError`) are values, so import them without `type` for `instanceof` checks (see Error Handling):
 
 ```typescript
 import type {
@@ -141,13 +223,20 @@ import type {
   CreateContactResponse,
   CreateChatSessionResponse,
   SendMessageResponse,
-  ChannlizeError,
-  ValidationError,
-  AuthenticationError,
-  RateLimitError,
+  NotifyResponse,
+  TrackEventResult,
 } from '@channlize/core';
 ```
 
+## Documentation
+
+- Guide: https://channlize.com/docs/core
+- All docs: https://channlize.com/docs (quick start, API keys, troubleshooting)
+
+## Changelog
+
+[CHANGELOG.md](./CHANGELOG.md) lists every release of `@channlize/core`. Product updates: https://channlize.com/docs/changelog
+
 ## License
 
 MIT

package/dist/index.d.mts

@@ -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 };