@channlize/core 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @channlize/core
 
+## 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 +23,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
@@ -69,10 +78,74 @@ 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' });
 ```
 
@@ -111,8 +184,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,6 +200,13 @@ 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)` — log tracking (browser)
+- `trackServerEvent(name: string, options?)` — log tracking (server)
+
+### createNotifier
+
+`createNotifier<TEvents>(config?: NotifierConfig): (event, data?, options?) => Promise<NotifyResponse>` — standalone server-side Events sender (see above).
 
 ### Types
 

package/dist/index.d.mts

@@ -1,8 +1,9 @@
 /**
  * Core types for Channlize SDK
  */
-/** Severity for tracked events (Slack routing uses project settings). */
+/** Severity for log tracking (`trackEvent` / `trackServerEvent`); Slack alerts use project settings. */
 type EventSeverity = 'info' | 'warning' | 'error';
+/** Options for log tracking (`trackEvent` / `trackServerEvent`). */
 interface TrackEventOptions {
     properties?: Record<string, unknown>;
     severity?: EventSeverity;
@@ -11,20 +12,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;
@@ -143,14 +202,16 @@ declare class RateLimitError extends ChannlizeError {
 
 /**
  * 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,14 +239,16 @@ 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;
     }>;
     /**
-     * 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>;
@@ -194,7 +257,32 @@ declare class ChannlizeClient {
         success: boolean;
         id: string;
     }>;
+    /**
+     * 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, RateLimitError, ValidationError, createNotifier, ChannlizeClient as default };
+export type { ApiResponse, ChannlizeConfig, ChannlizeEvents, ChatMessage, ChatSession, ContactFormData, CreateChatSessionResponse, CreateContactResponse, EventSeverity, FileAttachment, Notifier, NotifierConfig, NotifyEventData, NotifyEventName, NotifyOptions, NotifyResponse, SendMessageResponse, TrackEventOptions };

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 /**
  * Core types for Channlize SDK
  */
-/** Severity for tracked events (Slack routing uses project settings). */
+/** Severity for log tracking (`trackEvent` / `trackServerEvent`); Slack alerts use project settings. */
 type EventSeverity = 'info' | 'warning' | 'error';
+/** Options for log tracking (`trackEvent` / `trackServerEvent`). */
 interface TrackEventOptions {
     properties?: Record<string, unknown>;
     severity?: EventSeverity;
@@ -11,20 +12,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;
@@ -143,14 +202,16 @@ declare class RateLimitError extends ChannlizeError {
 
 /**
  * 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,14 +239,16 @@ 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;
     }>;
     /**
-     * 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>;
@@ -194,7 +257,32 @@ declare class ChannlizeClient {
         success: boolean;
         id: string;
     }>;
+    /**
+     * 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, RateLimitError, ValidationError, createNotifier, ChannlizeClient as default };
+export type { ApiResponse, ChannlizeConfig, ChannlizeEvents, ChatMessage, ChatSession, ContactFormData, CreateChatSessionResponse, CreateContactResponse, EventSeverity, FileAttachment, Notifier, NotifierConfig, NotifyEventData, NotifyEventName, NotifyOptions, NotifyResponse, SendMessageResponse, TrackEventOptions };