@kavchat/node 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 maxsave
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,94 @@
-# Temporary Holding Version
+# @kavchat/node
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Kavchat server SDK for Node.js 18+. TypeScript types included, ESM and CommonJS builds, no runtime dependencies (uses the global `fetch` and `node:crypto`).
+
+## Install
+
+```sh
+yarn add @kavchat/node
+```
+
+The package name is a placeholder until it is published.
+
+## Setup
+
+```ts
+import { Kavchat } from '@kavchat/node';
+// const { Kavchat } = require('@kavchat/node');
+
+const kavchat = new Kavchat(process.env.KAVCHAT_SECRET_KEY!, {
+  // baseUrl: 'https://api.kavchat.com',
+  // timeoutMs: 30_000,
+  // locale: 'en',            // language of error messages
+});
+```
+
+## Identify your users
+
+```ts
+const token = kavchat.createUserToken({
+  userId: 'user_123',          // required, 1 to 128 characters
+  phone: '+972501234567',      // optional
+  name: 'Dana',                // optional
+  email: 'dana@example.com',   // optional
+  expiresIn: 7 * 24 * 3600,    // seconds, default 7 days, at most 30 days
+});
+// Send the token to your page or app and pass it to the Kavchat widget or SDK.
+```
+
+`createUserToken(secretKey, options)` is also exported as a standalone function.
+
+## Verify webhooks
+
+Use the raw body. A body that was parsed and then serialized again will not match the signature.
+
+```ts
+import express from 'express';
+import { WebhookVerificationError } from '@kavchat/node';
+
+app.post('/kavchat/webhook', express.raw({ type: 'application/json' }), (req, res) => {
+  try {
+    const event = kavchat.verifyWebhook(req.body, req.get('Kavchat-Signature'));
+    if (event.type === 'ticket.created') console.log('New ticket', event.data.number);
+    res.sendStatus(200);
+  } catch (err) {
+    if (err instanceof WebhookVerificationError) return res.status(400).send(err.code);
+    throw err;
+  }
+});
+```
+
+Options: `kavchat.verifyWebhook(body, header, { toleranceSeconds: 300 })`.
+
+## Server API
+
+```ts
+await kavchat.getWorkspace();
+await kavchat.listTickets({ status: 'open', limit: 50, before: 120 });
+await kavchat.getTicket(id);
+await kavchat.setTicketStatus(id, 'closed');
+await kavchat.getReports({ from: new Date('2026-01-01'), to: new Date() });
+await kavchat.getSettings();
+await kavchat.updateSettings({ audience: 'testers', testerPhones: ['+972501234567'] });
+await kavchat.listReleases();
+```
+
+Errors are thrown as `KavchatApiError` with `status`, `code`, `message` and `details`. `status` is 0 when no response arrived (`code` is `timeout` or `network_error`).
+
+```ts
+import { KavchatApiError } from '@kavchat/node';
+try {
+  await kavchat.getTicket('nope');
+} catch (err) {
+  if (err instanceof KavchatApiError && err.code === 'ticket_not_found') { /* ... */ }
+}
+```
+
+## Tests
+
+```sh
+yarn install
+yarn test
+```
+
+The tests cover the shared vectors in `../test-vectors`, the client against a local HTTP server, the CommonJS build, and an end-to-end check against the server's own `verifyIdentityToken` and `signWebhook` (run with `tsx` from the repository; skipped when the server sources are not there).

package/dist/cjs/client.d.ts

@@ -0,0 +1,39 @@
+import { type UserTokenOptions } from './identity.js';
+import { type VerifyWebhookOptions } from './webhook.js';
+import type { ListTicketsParams, ReleaseSummary, Report, ReportParams, Settings, Ticket, TicketStatus, UpdateSettingsParams, WebhookEvent, Workspace } from './types.js';
+export declare const DEFAULT_BASE_URL = "https://api.kavchat.com";
+export declare const VERSION = "0.0.1";
+export interface KavchatOptions {
+    /** Default https://api.kavchat.com */
+    baseUrl?: string;
+    /** Per request, in milliseconds. Default 30000. */
+    timeoutMs?: number;
+    /** Language of error messages (Accept-Language), e.g. "en" or "he". */
+    locale?: string;
+    /** Custom fetch implementation. Defaults to the global fetch. */
+    fetch?: typeof fetch;
+}
+/**
+ * Kavchat server client. Keep the secret key on your backend only.
+ *
+ *   const kavchat = new Kavchat(process.env.KAVCHAT_SECRET_KEY!);
+ */
+export declare class Kavchat {
+    #private;
+    constructor(secretKey: string, options?: KavchatOptions);
+    /** Signs an identity token for one of your users. See createUserToken(). */
+    createUserToken(options: UserTokenOptions): string;
+    /** Verifies a webhook request and returns the event. See verifyWebhook(). */
+    verifyWebhook(rawBody: string | Uint8Array, signatureHeader: string | null | undefined, options?: VerifyWebhookOptions): WebhookEvent;
+    getWorkspace(): Promise<Workspace>;
+    /** Newest first. Page with `before` = the number of the last ticket you have. */
+    listTickets(params?: ListTicketsParams): Promise<Ticket[]>;
+    getTicket(id: string): Promise<Ticket>;
+    setTicketStatus(id: string, status: TicketStatus): Promise<Ticket>;
+    /** Defaults to the last 30 days. */
+    getReports(params?: ReportParams): Promise<Report>;
+    getSettings(): Promise<Settings>;
+    /** Only the audience and the tester phones can be changed from the server. */
+    updateSettings(params: UpdateSettingsParams): Promise<Settings>;
+    listReleases(): Promise<ReleaseSummary[]>;
+}

package/dist/cjs/client.js

@@ -0,0 +1,116 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Kavchat = exports.VERSION = exports.DEFAULT_BASE_URL = void 0;
+const errors_js_1 = require("./errors.js");
+const identity_js_1 = require("./identity.js");
+const webhook_js_1 = require("./webhook.js");
+exports.DEFAULT_BASE_URL = 'https://api.kavchat.com';
+exports.VERSION = '0.0.1';
+/**
+ * Kavchat server client. Keep the secret key on your backend only.
+ *
+ *   const kavchat = new Kavchat(process.env.KAVCHAT_SECRET_KEY!);
+ */
+class Kavchat {
+    #secretKey;
+    #baseUrl;
+    #timeoutMs;
+    #locale;
+    #fetch;
+    constructor(secretKey, options = {}) {
+        if (typeof secretKey !== 'string' || !secretKey)
+            throw new TypeError('secretKey is required');
+        this.#secretKey = secretKey;
+        this.#baseUrl = (options.baseUrl ?? exports.DEFAULT_BASE_URL).replace(/\/+$/, '');
+        this.#timeoutMs = options.timeoutMs ?? 30_000;
+        this.#locale = options.locale;
+        const impl = options.fetch ?? globalThis.fetch;
+        if (typeof impl !== 'function')
+            throw new TypeError('No fetch implementation found (Node 18+ required)');
+        this.#fetch = impl;
+    }
+    /** Signs an identity token for one of your users. See createUserToken(). */
+    createUserToken(options) {
+        return (0, identity_js_1.createUserToken)(this.#secretKey, options);
+    }
+    /** Verifies a webhook request and returns the event. See verifyWebhook(). */
+    verifyWebhook(rawBody, signatureHeader, options) {
+        return (0, webhook_js_1.verifyWebhook)(this.#secretKey, rawBody, signatureHeader, options);
+    }
+    getWorkspace() {
+        return this.#request('GET', '/workspace');
+    }
+    /** Newest first. Page with `before` = the number of the last ticket you have. */
+    listTickets(params = {}) {
+        return this.#request('GET', '/tickets', { query: { ...params } });
+    }
+    getTicket(id) {
+        return this.#request('GET', `/tickets/${encodeURIComponent(id)}`);
+    }
+    setTicketStatus(id, status) {
+        return this.#request('PUT', `/tickets/${encodeURIComponent(id)}/status`, { body: { status } });
+    }
+    /** Defaults to the last 30 days. */
+    getReports(params = {}) {
+        const iso = (d) => (d instanceof Date ? d.toISOString() : d);
+        return this.#request('GET', '/reports', { query: { from: iso(params.from), to: iso(params.to) } });
+    }
+    getSettings() {
+        return this.#request('GET', '/settings');
+    }
+    /** Only the audience and the tester phones can be changed from the server. */
+    updateSettings(params) {
+        return this.#request('PUT', '/settings', { body: params });
+    }
+    listReleases() {
+        return this.#request('GET', '/releases');
+    }
+    async #request(method, path, opts = {}) {
+        const url = new URL(`${this.#baseUrl}/v1/server${path}`);
+        for (const [key, value] of Object.entries(opts.query ?? {})) {
+            if (value !== undefined && value !== null && value !== '')
+                url.searchParams.set(key, String(value));
+        }
+        const headers = {
+            Authorization: `Bearer ${this.#secretKey}`,
+            Accept: 'application/json',
+            'User-Agent': `kavchat-node/${exports.VERSION}`,
+        };
+        if (this.#locale)
+            headers['Accept-Language'] = this.#locale;
+        if (opts.body !== undefined)
+            headers['Content-Type'] = 'application/json';
+        let res;
+        try {
+            res = await this.#fetch(url, {
+                method,
+                headers,
+                body: opts.body === undefined ? undefined : JSON.stringify(opts.body),
+                signal: AbortSignal.timeout(this.#timeoutMs),
+            });
+        }
+        catch (err) {
+            const name = err?.name;
+            if (name === 'TimeoutError' || name === 'AbortError') {
+                throw new errors_js_1.KavchatApiError(0, 'timeout', `Request timed out after ${this.#timeoutMs} ms`);
+            }
+            throw new errors_js_1.KavchatApiError(0, 'network_error', `Could not reach Kavchat: ${err?.message ?? err}`);
+        }
+        const text = await res.text();
+        let json;
+        try {
+            json = text ? JSON.parse(text) : undefined;
+        }
+        catch {
+            json = undefined;
+        }
+        if (!res.ok || !json || json.success !== true) {
+            if (json && typeof json.code === 'string') {
+                throw new errors_js_1.KavchatApiError(res.status, json.code, String(json.message ?? json.code), json.details);
+            }
+            throw new errors_js_1.KavchatApiError(res.status, 'invalid_response', `Unexpected response from Kavchat (HTTP ${res.status})`);
+        }
+        return json.data;
+    }
+}
+exports.Kavchat = Kavchat;

package/dist/cjs/errors.d.ts

@@ -0,0 +1,21 @@
+/** Base class of every error thrown by this SDK. */
+export declare class KavchatError extends Error {
+    constructor(message: string);
+}
+/**
+ * The Server API answered with an error, or could not be reached.
+ * `status` is the HTTP status, or 0 when no response arrived (`code` is then
+ * `timeout` or `network_error`).
+ */
+export declare class KavchatApiError extends KavchatError {
+    readonly status: number;
+    readonly code: string;
+    readonly details?: unknown;
+    constructor(status: number, code: string, message: string, details?: unknown);
+}
+export type WebhookErrorCode = 'malformed_header' | 'timestamp_out_of_range' | 'invalid_signature' | 'invalid_payload';
+/** A webhook request failed verification. Answer it with HTTP 400. */
+export declare class WebhookVerificationError extends KavchatError {
+    readonly code: WebhookErrorCode;
+    constructor(code: WebhookErrorCode, message: string);
+}

package/dist/cjs/errors.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebhookVerificationError = exports.KavchatApiError = exports.KavchatError = void 0;
+/** Base class of every error thrown by this SDK. */
+class KavchatError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = new.target.name;
+    }
+}
+exports.KavchatError = KavchatError;
+/**
+ * The Server API answered with an error, or could not be reached.
+ * `status` is the HTTP status, or 0 when no response arrived (`code` is then
+ * `timeout` or `network_error`).
+ */
+class KavchatApiError extends KavchatError {
+    status;
+    code;
+    details;
+    constructor(status, code, message, details) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.details = details;
+    }
+}
+exports.KavchatApiError = KavchatApiError;
+/** A webhook request failed verification. Answer it with HTTP 400. */
+class WebhookVerificationError extends KavchatError {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+exports.WebhookVerificationError = WebhookVerificationError;

package/dist/cjs/identity.d.ts

@@ -0,0 +1,19 @@
+export interface UserTokenOptions {
+    /** Your own user id. Becomes the `sub` claim. 1 to 128 characters. */
+    userId: string;
+    phone?: string;
+    name?: string;
+    email?: string;
+    /** Lifetime in seconds. Default 7 days, at most 30 days. */
+    expiresIn?: number;
+    /** Issue time as unix seconds. Defaults to now; useful in tests. */
+    issuedAt?: number;
+}
+export declare const DEFAULT_TOKEN_TTL_SECONDS: number;
+export declare const MAX_TOKEN_TTL_SECONDS: number;
+/**
+ * Signs an identity token (HS256 JWT) for one of your users.
+ * Pass it to the widget or the mobile SDK; Kavchat then tags sessions and
+ * tickets with `userId` and can show the bot only to testers.
+ */
+export declare function createUserToken(secretKey: string, options: UserTokenOptions): string;

package/dist/cjs/identity.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_TOKEN_TTL_SECONDS = exports.DEFAULT_TOKEN_TTL_SECONDS = void 0;
+exports.createUserToken = createUserToken;
+const node_crypto_1 = require("node:crypto");
+exports.DEFAULT_TOKEN_TTL_SECONDS = 7 * 24 * 60 * 60;
+exports.MAX_TOKEN_TTL_SECONDS = 30 * 24 * 60 * 60;
+/** base64url of {"alg":"HS256","typ":"JWT"} */
+const HEADER = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9';
+/**
+ * Signs an identity token (HS256 JWT) for one of your users.
+ * Pass it to the widget or the mobile SDK; Kavchat then tags sessions and
+ * tickets with `userId` and can show the bot only to testers.
+ */
+function createUserToken(secretKey, options) {
+    if (typeof secretKey !== 'string' || !secretKey)
+        throw new TypeError('secretKey is required');
+    const { userId, phone, name, email } = options;
+    if (typeof userId !== 'string' || userId.length === 0 || userId.length > 128) {
+        throw new RangeError('userId must be a string of 1 to 128 characters');
+    }
+    const expiresIn = options.expiresIn ?? exports.DEFAULT_TOKEN_TTL_SECONDS;
+    if (!Number.isInteger(expiresIn) || expiresIn <= 0 || expiresIn > exports.MAX_TOKEN_TTL_SECONDS) {
+        throw new RangeError(`expiresIn must be a whole number of seconds between 1 and ${exports.MAX_TOKEN_TTL_SECONDS}`);
+    }
+    const iat = options.issuedAt ?? Math.floor(Date.now() / 1000);
+    // Claim order is fixed (sub, phone, name, email, iat, exp) so every SDK signs the same bytes.
+    const claims = { sub: userId };
+    if (phone)
+        claims.phone = phone;
+    if (name)
+        claims.name = name;
+    if (email)
+        claims.email = email;
+    claims.iat = iat;
+    claims.exp = iat + expiresIn;
+    const payload = Buffer.from(JSON.stringify(claims), 'utf8').toString('base64url');
+    const signature = (0, node_crypto_1.createHmac)('sha256', secretKey).update(`${HEADER}.${payload}`).digest('base64url');
+    return `${HEADER}.${payload}.${signature}`;
+}

package/dist/cjs/index.d.ts

@@ -0,0 +1,5 @@
+export { Kavchat, DEFAULT_BASE_URL, VERSION, type KavchatOptions } from './client.js';
+export { createUserToken, DEFAULT_TOKEN_TTL_SECONDS, MAX_TOKEN_TTL_SECONDS, type UserTokenOptions, } from './identity.js';
+export { verifyWebhook, SIGNATURE_HEADER, type VerifyWebhookOptions } from './webhook.js';
+export { KavchatError, KavchatApiError, WebhookVerificationError, type WebhookErrorCode } from './errors.js';
+export type * from './types.js';

package/dist/cjs/index.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebhookVerificationError = exports.KavchatApiError = exports.KavchatError = exports.SIGNATURE_HEADER = exports.verifyWebhook = exports.MAX_TOKEN_TTL_SECONDS = exports.DEFAULT_TOKEN_TTL_SECONDS = exports.createUserToken = exports.VERSION = exports.DEFAULT_BASE_URL = exports.Kavchat = void 0;
+var client_js_1 = require("./client.js");
+Object.defineProperty(exports, "Kavchat", { enumerable: true, get: function () { return client_js_1.Kavchat; } });
+Object.defineProperty(exports, "DEFAULT_BASE_URL", { enumerable: true, get: function () { return client_js_1.DEFAULT_BASE_URL; } });
+Object.defineProperty(exports, "VERSION", { enumerable: true, get: function () { return client_js_1.VERSION; } });
+var identity_js_1 = require("./identity.js");
+Object.defineProperty(exports, "createUserToken", { enumerable: true, get: function () { return identity_js_1.createUserToken; } });
+Object.defineProperty(exports, "DEFAULT_TOKEN_TTL_SECONDS", { enumerable: true, get: function () { return identity_js_1.DEFAULT_TOKEN_TTL_SECONDS; } });
+Object.defineProperty(exports, "MAX_TOKEN_TTL_SECONDS", { enumerable: true, get: function () { return identity_js_1.MAX_TOKEN_TTL_SECONDS; } });
+var webhook_js_1 = require("./webhook.js");
+Object.defineProperty(exports, "verifyWebhook", { enumerable: true, get: function () { return webhook_js_1.verifyWebhook; } });
+Object.defineProperty(exports, "SIGNATURE_HEADER", { enumerable: true, get: function () { return webhook_js_1.SIGNATURE_HEADER; } });
+var errors_js_1 = require("./errors.js");
+Object.defineProperty(exports, "KavchatError", { enumerable: true, get: function () { return errors_js_1.KavchatError; } });
+Object.defineProperty(exports, "KavchatApiError", { enumerable: true, get: function () { return errors_js_1.KavchatApiError; } });
+Object.defineProperty(exports, "WebhookVerificationError", { enumerable: true, get: function () { return errors_js_1.WebhookVerificationError; } });

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{ "type": "commonjs" }

package/dist/cjs/types.d.ts

@@ -0,0 +1,105 @@
+export type TicketStatus = 'open' | 'closed';
+export type Audience = 'off' | 'testers' | 'all';
+export type Locale = 'he' | 'en' | 'ar' | 'ru' | 'es' | 'fr' | 'de' | 'pt' | 'it' | 'tr';
+export interface TranscriptEntry {
+    from: 'bot' | 'user';
+    text: string;
+    stepId?: string;
+    at?: string;
+}
+export interface Ticket {
+    id: string;
+    number: number;
+    status: TicketStatus;
+    name: string | null;
+    email: string | null;
+    /** E.164 */
+    phone: string | null;
+    /** The `sub` claim of the identity token, when the user was identified. */
+    userId: string | null;
+    topicId: string | null;
+    topicName: string | null;
+    scriptId: string | null;
+    sessionId: string | null;
+    message: string;
+    transcript: TranscriptEntry[];
+    createdAt: string;
+    updatedAt: string;
+}
+export interface ContactTopic {
+    id: string;
+    name: string;
+}
+export interface Settings {
+    enabled: boolean;
+    audience: Audience;
+    testerPhones: string[];
+    botName: string;
+    avatarText: string;
+    avatarImageUrl: string | null;
+    subtitle: string;
+    primaryColor: string;
+    position: 'start' | 'end';
+    contactTopics: ContactTopic[];
+}
+export interface Workspace {
+    id: string;
+    name: string;
+    locale: Locale;
+    defaultCountry: string;
+    plan: string;
+    publicKey: string;
+    secretKeyHint: string;
+    webhookUrl: string | null;
+}
+export interface ReleaseSummary {
+    version: number;
+    note?: string;
+    restoredFrom?: number;
+    publishedAt: string;
+    scripts: {
+        id: string;
+        kind: string;
+        name: string;
+    }[];
+}
+export interface ReportTotals {
+    sessions: number;
+    open: number;
+    answered: number;
+    contact: number;
+    abandoned: number;
+}
+export interface UnmatchedQuestion {
+    groupKey: string;
+    sample: string;
+    count: number;
+    lastAt: string;
+}
+export interface Report {
+    from: string;
+    to: string;
+    totals: ReportTotals;
+    byScript: Record<string, unknown>[];
+    dropOff: Record<string, unknown>[];
+    unmatched: UnmatchedQuestion[];
+}
+export interface WebhookEvent {
+    type: 'ticket.created';
+    data: Ticket;
+}
+export interface ListTicketsParams {
+    status?: TicketStatus;
+    /** 1 to 200, default 50 */
+    limit?: number;
+    /** Return tickets with a number lower than this one (paging). */
+    before?: number;
+}
+export interface ReportParams {
+    from?: Date | string;
+    to?: Date | string;
+}
+export interface UpdateSettingsParams {
+    audience?: Audience;
+    testerPhones?: string[];
+}

package/dist/cjs/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/webhook.d.ts

@@ -0,0 +1,14 @@
+import type { WebhookEvent } from './types.js';
+export interface VerifyWebhookOptions {
+    /** Maximum age (and clock skew) of the signature, in seconds. Default 300. */
+    toleranceSeconds?: number;
+    /** Current time as unix seconds. Defaults to now; useful in tests. */
+    now?: number;
+}
+export declare const SIGNATURE_HEADER = "Kavchat-Signature";
+/**
+ * Checks the `Kavchat-Signature` header of a webhook request and returns the parsed event.
+ * `rawBody` must be the exact bytes received, before any JSON parsing.
+ * Throws WebhookVerificationError when the request is not authentic or too old.
+ */
+export declare function verifyWebhook(secretKey: string, rawBody: string | Uint8Array, signatureHeader: string | null | undefined, options?: VerifyWebhookOptions): WebhookEvent;

package/dist/cjs/webhook.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SIGNATURE_HEADER = void 0;
+exports.verifyWebhook = verifyWebhook;
+const node_crypto_1 = require("node:crypto");
+const errors_js_1 = require("./errors.js");
+exports.SIGNATURE_HEADER = 'Kavchat-Signature';
+/**
+ * Checks the `Kavchat-Signature` header of a webhook request and returns the parsed event.
+ * `rawBody` must be the exact bytes received, before any JSON parsing.
+ * Throws WebhookVerificationError when the request is not authentic or too old.
+ */
+function verifyWebhook(secretKey, rawBody, signatureHeader, options = {}) {
+    const tolerance = options.toleranceSeconds ?? 300;
+    const now = options.now ?? Math.floor(Date.now() / 1000);
+    let timestamp;
+    const signatures = [];
+    for (const part of String(signatureHeader ?? '').split(',')) {
+        const eq = part.indexOf('=');
+        if (eq < 0)
+            continue;
+        const key = part.slice(0, eq).trim();
+        const value = part.slice(eq + 1).trim();
+        if (key === 't')
+            timestamp = /^\d+$/.test(value) ? Number(value) : NaN;
+        else if (key === 'v1' && value)
+            signatures.push(value);
+    }
+    if (timestamp === undefined || Number.isNaN(timestamp) || signatures.length === 0) {
+        throw new errors_js_1.WebhookVerificationError('malformed_header', 'Kavchat-Signature header is missing or malformed');
+    }
+    if (Math.abs(now - timestamp) > tolerance) {
+        throw new errors_js_1.WebhookVerificationError('timestamp_out_of_range', 'Webhook timestamp is outside the tolerance');
+    }
+    const body = typeof rawBody === 'string' ? Buffer.from(rawBody, 'utf8') : Buffer.from(rawBody);
+    const expected = Buffer.from((0, node_crypto_1.createHmac)('sha256', secretKey).update(`${timestamp}.`).update(body).digest('hex'), 'utf8');
+    const matches = signatures.some((sig) => {
+        const given = Buffer.from(sig, 'utf8');
+        return given.length === expected.length && (0, node_crypto_1.timingSafeEqual)(given, expected);
+    });
+    if (!matches)
+        throw new errors_js_1.WebhookVerificationError('invalid_signature', 'Webhook signature does not match');
+    try {
+        return JSON.parse(body.toString('utf8'));
+    }
+    catch {
+        throw new errors_js_1.WebhookVerificationError('invalid_payload', 'Webhook body is not valid JSON');
+    }
+}

package/dist/esm/client.d.ts

@@ -0,0 +1,39 @@
+import { type UserTokenOptions } from './identity.js';
+import { type VerifyWebhookOptions } from './webhook.js';
+import type { ListTicketsParams, ReleaseSummary, Report, ReportParams, Settings, Ticket, TicketStatus, UpdateSettingsParams, WebhookEvent, Workspace } from './types.js';
+export declare const DEFAULT_BASE_URL = "https://api.kavchat.com";
+export declare const VERSION = "0.0.1";
+export interface KavchatOptions {
+    /** Default https://api.kavchat.com */
+    baseUrl?: string;
+    /** Per request, in milliseconds. Default 30000. */
+    timeoutMs?: number;
+    /** Language of error messages (Accept-Language), e.g. "en" or "he". */
+    locale?: string;
+    /** Custom fetch implementation. Defaults to the global fetch. */
+    fetch?: typeof fetch;
+}
+/**
+ * Kavchat server client. Keep the secret key on your backend only.
+ *
+ *   const kavchat = new Kavchat(process.env.KAVCHAT_SECRET_KEY!);
+ */
+export declare class Kavchat {
+    #private;
+    constructor(secretKey: string, options?: KavchatOptions);
+    /** Signs an identity token for one of your users. See createUserToken(). */
+    createUserToken(options: UserTokenOptions): string;
+    /** Verifies a webhook request and returns the event. See verifyWebhook(). */
+    verifyWebhook(rawBody: string | Uint8Array, signatureHeader: string | null | undefined, options?: VerifyWebhookOptions): WebhookEvent;
+    getWorkspace(): Promise<Workspace>;
+    /** Newest first. Page with `before` = the number of the last ticket you have. */
+    listTickets(params?: ListTicketsParams): Promise<Ticket[]>;
+    getTicket(id: string): Promise<Ticket>;
+    setTicketStatus(id: string, status: TicketStatus): Promise<Ticket>;
+    /** Defaults to the last 30 days. */
+    getReports(params?: ReportParams): Promise<Report>;
+    getSettings(): Promise<Settings>;
+    /** Only the audience and the tester phones can be changed from the server. */
+    updateSettings(params: UpdateSettingsParams): Promise<Settings>;
+    listReleases(): Promise<ReleaseSummary[]>;
+}

package/dist/esm/client.js

@@ -0,0 +1,112 @@
+import { KavchatApiError } from './errors.js';
+import { createUserToken } from './identity.js';
+import { verifyWebhook } from './webhook.js';
+export const DEFAULT_BASE_URL = 'https://api.kavchat.com';
+export const VERSION = '0.0.1';
+/**
+ * Kavchat server client. Keep the secret key on your backend only.
+ *
+ *   const kavchat = new Kavchat(process.env.KAVCHAT_SECRET_KEY!);
+ */
+export class Kavchat {
+    #secretKey;
+    #baseUrl;
+    #timeoutMs;
+    #locale;
+    #fetch;
+    constructor(secretKey, options = {}) {
+        if (typeof secretKey !== 'string' || !secretKey)
+            throw new TypeError('secretKey is required');
+        this.#secretKey = secretKey;
+        this.#baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
+        this.#timeoutMs = options.timeoutMs ?? 30_000;
+        this.#locale = options.locale;
+        const impl = options.fetch ?? globalThis.fetch;
+        if (typeof impl !== 'function')
+            throw new TypeError('No fetch implementation found (Node 18+ required)');
+        this.#fetch = impl;
+    }
+    /** Signs an identity token for one of your users. See createUserToken(). */
+    createUserToken(options) {
+        return createUserToken(this.#secretKey, options);
+    }
+    /** Verifies a webhook request and returns the event. See verifyWebhook(). */
+    verifyWebhook(rawBody, signatureHeader, options) {
+        return verifyWebhook(this.#secretKey, rawBody, signatureHeader, options);
+    }
+    getWorkspace() {
+        return this.#request('GET', '/workspace');
+    }
+    /** Newest first. Page with `before` = the number of the last ticket you have. */
+    listTickets(params = {}) {
+        return this.#request('GET', '/tickets', { query: { ...params } });
+    }
+    getTicket(id) {
+        return this.#request('GET', `/tickets/${encodeURIComponent(id)}`);
+    }
+    setTicketStatus(id, status) {
+        return this.#request('PUT', `/tickets/${encodeURIComponent(id)}/status`, { body: { status } });
+    }
+    /** Defaults to the last 30 days. */
+    getReports(params = {}) {
+        const iso = (d) => (d instanceof Date ? d.toISOString() : d);
+        return this.#request('GET', '/reports', { query: { from: iso(params.from), to: iso(params.to) } });
+    }
+    getSettings() {
+        return this.#request('GET', '/settings');
+    }
+    /** Only the audience and the tester phones can be changed from the server. */
+    updateSettings(params) {
+        return this.#request('PUT', '/settings', { body: params });
+    }
+    listReleases() {
+        return this.#request('GET', '/releases');
+    }
+    async #request(method, path, opts = {}) {
+        const url = new URL(`${this.#baseUrl}/v1/server${path}`);
+        for (const [key, value] of Object.entries(opts.query ?? {})) {
+            if (value !== undefined && value !== null && value !== '')
+                url.searchParams.set(key, String(value));
+        }
+        const headers = {
+            Authorization: `Bearer ${this.#secretKey}`,
+            Accept: 'application/json',
+            'User-Agent': `kavchat-node/${VERSION}`,
+        };
+        if (this.#locale)
+            headers['Accept-Language'] = this.#locale;
+        if (opts.body !== undefined)
+            headers['Content-Type'] = 'application/json';
+        let res;
+        try {
+            res = await this.#fetch(url, {
+                method,
+                headers,
+                body: opts.body === undefined ? undefined : JSON.stringify(opts.body),
+                signal: AbortSignal.timeout(this.#timeoutMs),
+            });
+        }
+        catch (err) {
+            const name = err?.name;
+            if (name === 'TimeoutError' || name === 'AbortError') {
+                throw new KavchatApiError(0, 'timeout', `Request timed out after ${this.#timeoutMs} ms`);
+            }
+            throw new KavchatApiError(0, 'network_error', `Could not reach Kavchat: ${err?.message ?? err}`);
+        }
+        const text = await res.text();
+        let json;
+        try {
+            json = text ? JSON.parse(text) : undefined;
+        }
+        catch {
+            json = undefined;
+        }
+        if (!res.ok || !json || json.success !== true) {
+            if (json && typeof json.code === 'string') {
+                throw new KavchatApiError(res.status, json.code, String(json.message ?? json.code), json.details);
+            }
+            throw new KavchatApiError(res.status, 'invalid_response', `Unexpected response from Kavchat (HTTP ${res.status})`);
+        }
+        return json.data;
+    }
+}

package/dist/esm/errors.d.ts

@@ -0,0 +1,21 @@
+/** Base class of every error thrown by this SDK. */
+export declare class KavchatError extends Error {
+    constructor(message: string);
+}
+/**
+ * The Server API answered with an error, or could not be reached.
+ * `status` is the HTTP status, or 0 when no response arrived (`code` is then
+ * `timeout` or `network_error`).
+ */
+export declare class KavchatApiError extends KavchatError {
+    readonly status: number;
+    readonly code: string;
+    readonly details?: unknown;
+    constructor(status: number, code: string, message: string, details?: unknown);
+}
+export type WebhookErrorCode = 'malformed_header' | 'timestamp_out_of_range' | 'invalid_signature' | 'invalid_payload';
+/** A webhook request failed verification. Answer it with HTTP 400. */
+export declare class WebhookVerificationError extends KavchatError {
+    readonly code: WebhookErrorCode;
+    constructor(code: WebhookErrorCode, message: string);
+}

package/dist/esm/errors.js

@@ -0,0 +1,31 @@
+/** Base class of every error thrown by this SDK. */
+export class KavchatError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = new.target.name;
+    }
+}
+/**
+ * The Server API answered with an error, or could not be reached.
+ * `status` is the HTTP status, or 0 when no response arrived (`code` is then
+ * `timeout` or `network_error`).
+ */
+export class KavchatApiError extends KavchatError {
+    status;
+    code;
+    details;
+    constructor(status, code, message, details) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.details = details;
+    }
+}
+/** A webhook request failed verification. Answer it with HTTP 400. */
+export class WebhookVerificationError extends KavchatError {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}

package/dist/esm/identity.d.ts

@@ -0,0 +1,19 @@
+export interface UserTokenOptions {
+    /** Your own user id. Becomes the `sub` claim. 1 to 128 characters. */
+    userId: string;
+    phone?: string;
+    name?: string;
+    email?: string;
+    /** Lifetime in seconds. Default 7 days, at most 30 days. */
+    expiresIn?: number;
+    /** Issue time as unix seconds. Defaults to now; useful in tests. */
+    issuedAt?: number;
+}
+export declare const DEFAULT_TOKEN_TTL_SECONDS: number;
+export declare const MAX_TOKEN_TTL_SECONDS: number;
+/**
+ * Signs an identity token (HS256 JWT) for one of your users.
+ * Pass it to the widget or the mobile SDK; Kavchat then tags sessions and
+ * tickets with `userId` and can show the bot only to testers.
+ */
+export declare function createUserToken(secretKey: string, options: UserTokenOptions): string;

package/dist/esm/identity.js

@@ -0,0 +1,36 @@
+import { createHmac } from 'node:crypto';
+export const DEFAULT_TOKEN_TTL_SECONDS = 7 * 24 * 60 * 60;
+export const MAX_TOKEN_TTL_SECONDS = 30 * 24 * 60 * 60;
+/** base64url of {"alg":"HS256","typ":"JWT"} */
+const HEADER = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9';
+/**
+ * Signs an identity token (HS256 JWT) for one of your users.
+ * Pass it to the widget or the mobile SDK; Kavchat then tags sessions and
+ * tickets with `userId` and can show the bot only to testers.
+ */
+export function createUserToken(secretKey, options) {
+    if (typeof secretKey !== 'string' || !secretKey)
+        throw new TypeError('secretKey is required');
+    const { userId, phone, name, email } = options;
+    if (typeof userId !== 'string' || userId.length === 0 || userId.length > 128) {
+        throw new RangeError('userId must be a string of 1 to 128 characters');
+    }
+    const expiresIn = options.expiresIn ?? DEFAULT_TOKEN_TTL_SECONDS;
+    if (!Number.isInteger(expiresIn) || expiresIn <= 0 || expiresIn > MAX_TOKEN_TTL_SECONDS) {
+        throw new RangeError(`expiresIn must be a whole number of seconds between 1 and ${MAX_TOKEN_TTL_SECONDS}`);
+    }
+    const iat = options.issuedAt ?? Math.floor(Date.now() / 1000);
+    // Claim order is fixed (sub, phone, name, email, iat, exp) so every SDK signs the same bytes.
+    const claims = { sub: userId };
+    if (phone)
+        claims.phone = phone;
+    if (name)
+        claims.name = name;
+    if (email)
+        claims.email = email;
+    claims.iat = iat;
+    claims.exp = iat + expiresIn;
+    const payload = Buffer.from(JSON.stringify(claims), 'utf8').toString('base64url');
+    const signature = createHmac('sha256', secretKey).update(`${HEADER}.${payload}`).digest('base64url');
+    return `${HEADER}.${payload}.${signature}`;
+}

package/dist/esm/index.d.ts

@@ -0,0 +1,5 @@
+export { Kavchat, DEFAULT_BASE_URL, VERSION, type KavchatOptions } from './client.js';
+export { createUserToken, DEFAULT_TOKEN_TTL_SECONDS, MAX_TOKEN_TTL_SECONDS, type UserTokenOptions, } from './identity.js';
+export { verifyWebhook, SIGNATURE_HEADER, type VerifyWebhookOptions } from './webhook.js';
+export { KavchatError, KavchatApiError, WebhookVerificationError, type WebhookErrorCode } from './errors.js';
+export type * from './types.js';

package/dist/esm/index.js

@@ -0,0 +1,4 @@
+export { Kavchat, DEFAULT_BASE_URL, VERSION } from './client.js';
+export { createUserToken, DEFAULT_TOKEN_TTL_SECONDS, MAX_TOKEN_TTL_SECONDS, } from './identity.js';
+export { verifyWebhook, SIGNATURE_HEADER } from './webhook.js';
+export { KavchatError, KavchatApiError, WebhookVerificationError } from './errors.js';

package/dist/esm/types.d.ts

@@ -0,0 +1,105 @@
+export type TicketStatus = 'open' | 'closed';
+export type Audience = 'off' | 'testers' | 'all';
+export type Locale = 'he' | 'en' | 'ar' | 'ru' | 'es' | 'fr' | 'de' | 'pt' | 'it' | 'tr';
+export interface TranscriptEntry {
+    from: 'bot' | 'user';
+    text: string;
+    stepId?: string;
+    at?: string;
+}
+export interface Ticket {
+    id: string;
+    number: number;
+    status: TicketStatus;
+    name: string | null;
+    email: string | null;
+    /** E.164 */
+    phone: string | null;
+    /** The `sub` claim of the identity token, when the user was identified. */
+    userId: string | null;
+    topicId: string | null;
+    topicName: string | null;
+    scriptId: string | null;
+    sessionId: string | null;
+    message: string;
+    transcript: TranscriptEntry[];
+    createdAt: string;
+    updatedAt: string;
+}
+export interface ContactTopic {
+    id: string;
+    name: string;
+}
+export interface Settings {
+    enabled: boolean;
+    audience: Audience;
+    testerPhones: string[];
+    botName: string;
+    avatarText: string;
+    avatarImageUrl: string | null;
+    subtitle: string;
+    primaryColor: string;
+    position: 'start' | 'end';
+    contactTopics: ContactTopic[];
+}
+export interface Workspace {
+    id: string;
+    name: string;
+    locale: Locale;
+    defaultCountry: string;
+    plan: string;
+    publicKey: string;
+    secretKeyHint: string;
+    webhookUrl: string | null;
+}
+export interface ReleaseSummary {
+    version: number;
+    note?: string;
+    restoredFrom?: number;
+    publishedAt: string;
+    scripts: {
+        id: string;
+        kind: string;
+        name: string;
+    }[];
+}
+export interface ReportTotals {
+    sessions: number;
+    open: number;
+    answered: number;
+    contact: number;
+    abandoned: number;
+}
+export interface UnmatchedQuestion {
+    groupKey: string;
+    sample: string;
+    count: number;
+    lastAt: string;
+}
+export interface Report {
+    from: string;
+    to: string;
+    totals: ReportTotals;
+    byScript: Record<string, unknown>[];
+    dropOff: Record<string, unknown>[];
+    unmatched: UnmatchedQuestion[];
+}
+export interface WebhookEvent {
+    type: 'ticket.created';
+    data: Ticket;
+}
+export interface ListTicketsParams {
+    status?: TicketStatus;
+    /** 1 to 200, default 50 */
+    limit?: number;
+    /** Return tickets with a number lower than this one (paging). */
+    before?: number;
+}
+export interface ReportParams {
+    from?: Date | string;
+    to?: Date | string;
+}
+export interface UpdateSettingsParams {
+    audience?: Audience;
+    testerPhones?: string[];
+}

package/dist/esm/types.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/webhook.d.ts

@@ -0,0 +1,14 @@
+import type { WebhookEvent } from './types.js';
+export interface VerifyWebhookOptions {
+    /** Maximum age (and clock skew) of the signature, in seconds. Default 300. */
+    toleranceSeconds?: number;
+    /** Current time as unix seconds. Defaults to now; useful in tests. */
+    now?: number;
+}
+export declare const SIGNATURE_HEADER = "Kavchat-Signature";
+/**
+ * Checks the `Kavchat-Signature` header of a webhook request and returns the parsed event.
+ * `rawBody` must be the exact bytes received, before any JSON parsing.
+ * Throws WebhookVerificationError when the request is not authentic or too old.
+ */
+export declare function verifyWebhook(secretKey: string, rawBody: string | Uint8Array, signatureHeader: string | null | undefined, options?: VerifyWebhookOptions): WebhookEvent;

package/dist/esm/webhook.js

@@ -0,0 +1,45 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import { WebhookVerificationError } from './errors.js';
+export const SIGNATURE_HEADER = 'Kavchat-Signature';
+/**
+ * Checks the `Kavchat-Signature` header of a webhook request and returns the parsed event.
+ * `rawBody` must be the exact bytes received, before any JSON parsing.
+ * Throws WebhookVerificationError when the request is not authentic or too old.
+ */
+export function verifyWebhook(secretKey, rawBody, signatureHeader, options = {}) {
+    const tolerance = options.toleranceSeconds ?? 300;
+    const now = options.now ?? Math.floor(Date.now() / 1000);
+    let timestamp;
+    const signatures = [];
+    for (const part of String(signatureHeader ?? '').split(',')) {
+        const eq = part.indexOf('=');
+        if (eq < 0)
+            continue;
+        const key = part.slice(0, eq).trim();
+        const value = part.slice(eq + 1).trim();
+        if (key === 't')
+            timestamp = /^\d+$/.test(value) ? Number(value) : NaN;
+        else if (key === 'v1' && value)
+            signatures.push(value);
+    }
+    if (timestamp === undefined || Number.isNaN(timestamp) || signatures.length === 0) {
+        throw new WebhookVerificationError('malformed_header', 'Kavchat-Signature header is missing or malformed');
+    }
+    if (Math.abs(now - timestamp) > tolerance) {
+        throw new WebhookVerificationError('timestamp_out_of_range', 'Webhook timestamp is outside the tolerance');
+    }
+    const body = typeof rawBody === 'string' ? Buffer.from(rawBody, 'utf8') : Buffer.from(rawBody);
+    const expected = Buffer.from(createHmac('sha256', secretKey).update(`${timestamp}.`).update(body).digest('hex'), 'utf8');
+    const matches = signatures.some((sig) => {
+        const given = Buffer.from(sig, 'utf8');
+        return given.length === expected.length && timingSafeEqual(given, expected);
+    });
+    if (!matches)
+        throw new WebhookVerificationError('invalid_signature', 'Webhook signature does not match');
+    try {
+        return JSON.parse(body.toString('utf8'));
+    }
+    catch {
+        throw new WebhookVerificationError('invalid_payload', 'Webhook body is not valid JSON');
+    }
+}

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@kavchat/node",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1",
+  "description": "Kavchat server SDK for Node.js: identity tokens, webhook verification and the Server API",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json && tsc -p tsconfig.cjs.json && node scripts/write-cjs-package.mjs",
+    "test": "yarn build && node --test 'test/*.test.mjs' 'test/*.test.cjs'",
+    "prepublishOnly": "yarn build"
+  },
+  "keywords": [
+    "chatbot",
+    "customer-support",
+    "jwt",
+    "kavchat",
+    "rtl",
+    "scripted-bot",
+    "support",
+    "support-chat",
+    "webhook"
+  ],
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.9.3"
+  },
+  "homepage": "https://kavchat.com/docs",
+  "bugs": {
+    "email": "support@kavchat.com"
+  },
+  "author": "maxsave <support@kavchat.com>",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}