@nistrix/chat 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nistrix Ltda
+
+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,72 @@
-# Temporary Holding Version
+# @nistrix/chat
 
-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.
+The Nistrix chat for your own site or app: your visitors talk to your Nistrix agents and team, in a screen you design. It runs in browsers and in React Native, with no other dependency.
+
+It uses a **publishable key** (`nx_pk_live_...`, or `nx_pk_test_...` in your test environment). It is not a secret: it can only open visitor chats on one chat channel, from the sites and apps you listed on it. Never put a secret key (`nx_sk_`, `nx_rk_`) in a site or app.
+
+## Get a key
+
+In Nistrix, **Integrations → API and MCP → Nistrix in your apps → Publishable keys**: choose the chat channel, list your sites (`https://shop.example`) and apps (`com.shop.app`), and copy the key.
+
+## Use it
+
+```ts
+import { NistrixChat } from "@nistrix/chat";
+
+const chat = new NistrixChat({
+  publishableKey: "nx_pk_live_...",
+  storage: window.localStorage, // keeps the visitor between visits
+});
+
+const history = await chat.messages();
+await chat.send("Hi, can I book a time?", { name: "Bia" });
+
+const stop = chat.subscribe((messages) => render(messages)); // the agent or team wrote
+// later: stop();
+```
+
+### React Native
+
+Native apps have no origin, so they name themselves with `appId` (the bundle id or package name listed on the key):
+
+```ts
+import AsyncStorage from "@react-native-async-storage/async-storage";
+
+const chat = new NistrixChat({
+  publishableKey: "nx_pk_live_...",
+  appId: "com.shop.app",
+  storage: AsyncStorage,
+});
+```
+
+## Errors
+
+Calls throw `ChatError` with the HTTP `status` and the API's `code`, for example `origin-not-allowed` (add the site or app to the key) or `rate-limited`.
+
+## Booking pages and lead forms
+
+`NistrixIntents` uses the same key to show free times, ask for appointments, send leads, and turn sensitive values into data tokens. A booking or a lead is an intent (`nx_int_`, ten minutes) that your backend confirms with a secret key, unless the key confirms it on its own.
+
+```ts
+import { NistrixIntents } from "@nistrix/chat";
+
+const nistrix = new NistrixIntents({ publishableKey: "nx_pk_live_..." });
+
+const [slot] = await nistrix.slots({ service: "Cleaning", from: "2026-12-08" });
+const booking = await nistrix.book({ start: slot.localStart, name: "Bia", phone: "92991234567" });
+
+const cpf = await nistrix.tokenize("cpf", "529.982.247-25"); // nx_tok_..., never the value
+const lead = await nistrix.submitLead({ phone: "92991234567", fields: { cpf: cpf.token } });
+```
+
+## Test environment
+
+A `nx_pk_test_` key from your sandbox works the same way; conversations, bookings, and leads land in the sandbox, and `test` is `true`.
+
+## Develop
+
+```bash
+pnpm install
+pnpm test
+pnpm build
+```

package/dist/chat.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The Nistrix chat for customers' sites and apps. A publishable key (nx_pk_) opens visitor
+ * chats on one of the organization's chat channels, from the sites and apps listed on the key:
+ * browsers are recognized by their origin, native apps by `appId` (their bundle id or package
+ * name). The key is not a secret and can do nothing else.
+ */
+export declare const DEFAULT_API_URL = "https://api.nistrix.com.br";
+export interface ChatAttachment {
+    /** Opens the file for a few minutes; a new link comes with every refresh. */
+    url: string;
+    fileName: string;
+    mimeType: string;
+    size: number;
+}
+export interface ChatMessage {
+    id: string;
+    /** INBOUND: written by the visitor; OUTBOUND: by the agent or the team. */
+    direction: "INBOUND" | "OUTBOUND";
+    kind: string;
+    body: string | null;
+    status: string;
+    sentAt: string;
+    attachment?: ChatAttachment | null;
+}
+/** Where the visitor's session is kept between visits (localStorage, AsyncStorage, ...). */
+export interface VisitorStorage {
+    getItem(key: string): string | null | Promise<string | null>;
+    setItem(key: string, value: string): void | Promise<void>;
+}
+export interface NistrixChatOptions {
+    /** The organization's publishable key: nx_pk_live_... or, in its sandbox, nx_pk_test_.... */
+    publishableKey: string;
+    apiUrl?: string;
+    /** Native apps only: the bundle id or package name listed on the key. */
+    appId?: string;
+    /** Keeps the visitor's session; in memory when left out (a new visitor every launch). */
+    storage?: VisitorStorage;
+    fetch?: typeof fetch;
+    /** The WebSocket class; React Native's accepts headers, which native apps need. */
+    WebSocket?: WebSocketFactory;
+}
+export type WebSocketFactory = new (url: string, protocols?: string | string[], options?: {
+    headers?: Record<string, string>;
+}) => WebSocket;
+export declare class ChatError extends Error {
+    readonly status: number;
+    readonly code: string | null;
+    constructor(status: number, code: string | null);
+}
+export declare class NistrixChat {
+    #private;
+    constructor(options: NistrixChatOptions);
+    /** True for a sandbox key: nothing here reaches real customers. */
+    get test(): boolean;
+    /** The chat's name and greeting, and whether the organization is available. */
+    config(): Promise<{
+        name: string;
+        greeting: string | null;
+        available: boolean;
+    }>;
+    /** The visitor's conversation so far, oldest first. */
+    messages(): Promise<ChatMessage[]>;
+    /** Sends what the visitor wrote; `name` tells the team who is writing. Returns the chat. */
+    send(body: string, options?: {
+        name?: string;
+    }): Promise<ChatMessage[]>;
+    /** Calls `listener` with the whole chat whenever the agent or the team writes. */
+    subscribe(listener: (messages: ChatMessage[]) => void): () => void;
+    /** Stops listening; the visitor's session stays for the next visit. */
+    close(): void;
+}

package/dist/chat.js

@@ -0,0 +1,212 @@
+/**
+ * The Nistrix chat for customers' sites and apps. A publishable key (nx_pk_) opens visitor
+ * chats on one of the organization's chat channels, from the sites and apps listed on the key:
+ * browsers are recognized by their origin, native apps by `appId` (their bundle id or package
+ * name). The key is not a secret and can do nothing else.
+ */
+export const DEFAULT_API_URL = "https://api.nistrix.com.br";
+const APP_HEADER = "X-Nistrix-App";
+const FIRST_RETRY_MS = 1000;
+const MAX_RETRY_MS = 30_000;
+export class ChatError extends Error {
+    status;
+    code;
+    constructor(status, code) {
+        super(`Nistrix chat request failed (${String(status)}${code ? `, ${code}` : ""}).`);
+        this.name = "ChatError";
+        this.status = status;
+        this.code = code;
+    }
+}
+class MemoryStorage {
+    #items = new Map();
+    getItem(key) {
+        return this.#items.get(key) ?? null;
+    }
+    setItem(key, value) {
+        this.#items.set(key, value);
+    }
+}
+function newId() {
+    return globalThis.crypto.randomUUID();
+}
+export class NistrixChat {
+    #base;
+    #apiUrl;
+    #key;
+    #appId;
+    #storage;
+    #fetch;
+    #WebSocket;
+    #token = null;
+    #socket = null;
+    #listeners = new Set();
+    #retryMs = FIRST_RETRY_MS;
+    #closed = false;
+    constructor(options) {
+        if (!options.publishableKey.startsWith("nx_pk_")) {
+            throw new Error("Use a publishable key (nx_pk_...); never a secret key in an app.");
+        }
+        this.#apiUrl = (options.apiUrl ?? DEFAULT_API_URL).replace(/\/$/, "");
+        this.#key = options.publishableKey;
+        this.#base = `${this.#apiUrl}/widget/${encodeURIComponent(this.#key)}`;
+        this.#appId = options.appId;
+        this.#storage = options.storage ?? new MemoryStorage();
+        this.#fetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+        this.#WebSocket = options.WebSocket ?? globalThis.WebSocket;
+    }
+    /** True for a sandbox key: nothing here reaches real customers. */
+    get test() {
+        return this.#key.startsWith("nx_pk_test_");
+    }
+    get #storageKey() {
+        return `nistrix-chat:${this.#key}:visitor`;
+    }
+    get #headers() {
+        return this.#appId ? { [APP_HEADER]: this.#appId } : {};
+    }
+    async #request(path, init) {
+        const headers = { ...this.#headers, accept: "application/json" };
+        if (init.body !== undefined) {
+            headers["content-type"] = "application/json";
+        }
+        if (init.auth) {
+            headers.authorization = `Bearer ${await this.#session()}`;
+        }
+        const response = await this.#fetch(`${this.#base}${path}`, {
+            method: init.method ?? "GET",
+            headers,
+            ...(init.body === undefined ? {} : { body: JSON.stringify(init.body) }),
+        });
+        if (!response.ok) {
+            let code = null;
+            try {
+                const problem = (await response.json());
+                code = problem.type?.split(":").pop() ?? null;
+            }
+            catch {
+                // Not a problem document.
+            }
+            throw new ChatError(response.status, code);
+        }
+        return (await response.json());
+    }
+    async #session(forceNew = false) {
+        if (this.#token && !forceNew) {
+            return this.#token;
+        }
+        const stored = forceNew ? null : await this.#storage.getItem(this.#storageKey);
+        const { visitorToken } = await this.#request("/visitors", {
+            method: "POST",
+            body: { visitorToken: stored },
+        });
+        this.#token = visitorToken;
+        await this.#storage.setItem(this.#storageKey, visitorToken);
+        return visitorToken;
+    }
+    /** Runs a call as the visitor, starting a new session once if the old one expired. */
+    async #asVisitor(path, init = {}) {
+        try {
+            return await this.#request(path, { ...init, auth: true });
+        }
+        catch (error) {
+            if (!(error instanceof ChatError) || error.status !== 401) {
+                throw error;
+            }
+            await this.#session(true);
+            return this.#request(path, { ...init, auth: true });
+        }
+    }
+    /** The chat's name and greeting, and whether the organization is available. */
+    async config() {
+        return this.#request("", {});
+    }
+    /** The visitor's conversation so far, oldest first. */
+    async messages() {
+        const { items } = await this.#asVisitor("/messages");
+        return items;
+    }
+    /** Sends what the visitor wrote; `name` tells the team who is writing. Returns the chat. */
+    async send(body, options = {}) {
+        const { items } = await this.#asVisitor("/messages", {
+            method: "POST",
+            body: { body, clientMessageId: newId(), name: options.name ?? null },
+        });
+        this.#emit(items);
+        return items;
+    }
+    /** Calls `listener` with the whole chat whenever the agent or the team writes. */
+    subscribe(listener) {
+        this.#listeners.add(listener);
+        this.#closed = false;
+        if (!this.#socket) {
+            void this.#connect();
+        }
+        return () => {
+            this.#listeners.delete(listener);
+            if (this.#listeners.size === 0) {
+                this.close();
+            }
+        };
+    }
+    /** Stops listening; the visitor's session stays for the next visit. */
+    close() {
+        this.#closed = true;
+        this.#socket?.close();
+        this.#socket = null;
+    }
+    #emit(messages) {
+        for (const listener of this.#listeners) {
+            listener(messages);
+        }
+    }
+    async #connect() {
+        if (!this.#WebSocket || this.#closed) {
+            return;
+        }
+        try {
+            const { ticket } = await this.#asVisitor("/tickets", { method: "POST" });
+            const url = new URL("/widget/realtime", this.#apiUrl);
+            url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+            url.searchParams.set("ticket", ticket);
+            url.searchParams.set("key", this.#key);
+            if (this.#appId) {
+                // Not every WebSocket can send headers (browsers', Node's): the app is named here too.
+                url.searchParams.set("app", this.#appId);
+            }
+            // Browsers send their origin themselves; native apps name themselves in a header.
+            const socket = this.#appId
+                ? new this.#WebSocket(url.toString(), undefined, { headers: this.#headers })
+                : new this.#WebSocket(url.toString());
+            this.#socket = socket;
+            socket.onopen = () => {
+                this.#retryMs = FIRST_RETRY_MS;
+            };
+            socket.onmessage = (event) => {
+                const data = JSON.parse(String(event.data));
+                if (data.type !== "ping") {
+                    void this.messages().then((items) => {
+                        this.#emit(items);
+                    });
+                }
+            };
+            socket.onclose = () => {
+                this.#socket = null;
+                this.#reconnect();
+            };
+        }
+        catch {
+            this.#reconnect();
+        }
+    }
+    #reconnect() {
+        if (this.#closed || this.#listeners.size === 0) {
+            return;
+        }
+        const wait = this.#retryMs;
+        this.#retryMs = Math.min(this.#retryMs * 2, MAX_RETRY_MS);
+        setTimeout(() => {
+            void this.#connect();
+        }, wait);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { ChatError, DEFAULT_API_URL, NistrixChat, type ChatAttachment, type ChatMessage, type NistrixChatOptions, type VisitorStorage, type WebSocketFactory, } from "./chat.js";
+export { NistrixIntents, type BookingOptions, type BookingRequest, type DataKind, type DataToken, type FieldValue, type Intent, type IntentStatus, type IntentType, type LeadRequest, type NistrixIntentsOptions, type Slot, type TicketRequest, } from "./intents.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { ChatError, DEFAULT_API_URL, NistrixChat, } from "./chat.js";
+export { NistrixIntents, } from "./intents.js";

package/dist/intents.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Booking pages and lead forms in customers' sites and apps, with the same publishable key as
+ * the chat. Free times are public; a booking, a lead, or a ticket is an intent (nx_int_, ten minutes) that
+ * the organization's backend confirms with a secret key, unless the key confirms it on its own.
+ * Sensitive values (a CPF, a health note) become data tokens (nx_tok_) sent in their place.
+ */
+export interface NistrixIntentsOptions {
+    /** The organization's publishable key: nx_pk_live_... or, in its sandbox, nx_pk_test_.... */
+    publishableKey: string;
+    apiUrl?: string;
+    /** Native apps only: the bundle id or package name listed on the key. */
+    appId?: string;
+    fetch?: typeof fetch;
+}
+export interface BookingOptions {
+    schedules: {
+        id: string;
+        name: string;
+        timezone: string;
+    }[];
+    services: {
+        name: string;
+        durationMinutes: number | null;
+        price: string | null;
+    }[];
+}
+export interface Slot {
+    scheduleId: string;
+    scheduleName: string;
+    startsAt: string;
+    /** YYYY-MM-DD HH:MM in the schedule's zone: send it back as `start`. */
+    localStart: string;
+    timezone: string;
+}
+export type IntentType = "book_appointment" | "submit_lead" | "open_ticket";
+export type IntentStatus = "pending" | "confirmed" | "failed" | "expired";
+export interface Intent {
+    /** nx_int_...: hand it to your backend, which confirms it. */
+    id: string;
+    type: IntentType;
+    status: IntentStatus;
+    /** True for a sandbox key: nothing here reaches real customers. */
+    test: boolean;
+    expiresAt: string;
+    /** For a booking: scheduleName, serviceName, localStart, timezone; for a ticket: number. */
+    result: Record<string, unknown> | null;
+    error: string | null;
+}
+export interface BookingRequest {
+    scheduleId?: string;
+    service?: string;
+    /** YYYY-MM-DD HH:MM in the schedule's zone (a slot's `localStart`). */
+    start: string;
+    name: string;
+    phone: string;
+    email?: string;
+    notes?: string;
+}
+export type FieldValue = string | number | boolean | null;
+export interface LeadRequest {
+    name?: string;
+    phone: string;
+    email?: string;
+    message?: string;
+    /** Customer fields by key; a sensitive value goes as its data token. */
+    fields?: Record<string, FieldValue>;
+}
+export interface TicketRequest {
+    subject: string;
+    description?: string;
+    category?: string;
+    name?: string;
+    phone: string;
+    email?: string;
+}
+export type DataKind = "cpf" | "cnpj" | "text";
+export interface DataToken {
+    /** nx_tok_...: send it in place of the value. */
+    token: string;
+    kind: DataKind;
+    /** The last digits of a document; empty for text. */
+    hint: string;
+    expiresAt: string;
+}
+export declare class NistrixIntents {
+    #private;
+    constructor(options: NistrixIntentsOptions);
+    /** True for a sandbox key: nothing here reaches real customers. */
+    get test(): boolean;
+    /** The schedules open for booking and the services they offer. */
+    bookingOptions(): Promise<BookingOptions>;
+    /** Free times, a week from `from` (YYYY-MM-DD) by default. */
+    slots(query?: {
+        scheduleId?: string;
+        service?: string;
+        from?: string;
+        to?: string;
+    }): Promise<Slot[]>;
+    /** Asks for an appointment. Refused (ChatError 409, intent-refused) when the key confirms
+     * bookings on its own and the time was just taken. */
+    book(booking: BookingRequest): Promise<Intent>;
+    /** Sends a lead from a form. */
+    submitLead(lead: LeadRequest): Promise<Intent>;
+    /** Opens a support ticket (the customer is found or created by phone). */
+    openTicket(ticket: TicketRequest): Promise<Intent>;
+    /** Where an intent stands: pending, confirmed, failed (with the reason), or expired. */
+    intent(id: string): Promise<Intent>;
+    /** Keeps a sensitive value and returns a token for it (valid for a day, used once). */
+    tokenize(kind: DataKind, value: string): Promise<DataToken>;
+}

package/dist/intents.js

@@ -0,0 +1,91 @@
+/**
+ * Booking pages and lead forms in customers' sites and apps, with the same publishable key as
+ * the chat. Free times are public; a booking, a lead, or a ticket is an intent (nx_int_, ten minutes) that
+ * the organization's backend confirms with a secret key, unless the key confirms it on its own.
+ * Sensitive values (a CPF, a health note) become data tokens (nx_tok_) sent in their place.
+ */
+import { ChatError, DEFAULT_API_URL } from "./chat.js";
+const APP_HEADER = "X-Nistrix-App";
+export class NistrixIntents {
+    #base;
+    #key;
+    #appId;
+    #fetch;
+    constructor(options) {
+        if (!options.publishableKey.startsWith("nx_pk_")) {
+            throw new Error("Use a publishable key (nx_pk_...); never a secret key in an app.");
+        }
+        const apiUrl = (options.apiUrl ?? DEFAULT_API_URL).replace(/\/$/, "");
+        this.#key = options.publishableKey;
+        this.#base = `${apiUrl}/widget/${encodeURIComponent(this.#key)}`;
+        this.#appId = options.appId;
+        this.#fetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+    }
+    /** True for a sandbox key: nothing here reaches real customers. */
+    get test() {
+        return this.#key.startsWith("nx_pk_test_");
+    }
+    async #request(path, body) {
+        const headers = { accept: "application/json" };
+        if (this.#appId) {
+            headers[APP_HEADER] = this.#appId;
+        }
+        if (body !== undefined) {
+            headers["content-type"] = "application/json";
+        }
+        const response = await this.#fetch(`${this.#base}${path}`, {
+            method: body === undefined ? "GET" : "POST",
+            headers,
+            ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+        });
+        if (!response.ok) {
+            let code = null;
+            try {
+                const problem = (await response.json());
+                code = problem.type?.split(":").pop() ?? null;
+            }
+            catch {
+                // Not a problem document.
+            }
+            throw new ChatError(response.status, code);
+        }
+        return (await response.json());
+    }
+    /** The schedules open for booking and the services they offer. */
+    async bookingOptions() {
+        return this.#request("/booking");
+    }
+    /** Free times, a week from `from` (YYYY-MM-DD) by default. */
+    async slots(query = {}) {
+        const params = new URLSearchParams();
+        for (const [name, value] of Object.entries(query)) {
+            if (value) {
+                params.set(name, value);
+            }
+        }
+        const search = params.size ? `?${params.toString()}` : "";
+        const { items } = await this.#request(`/slots${search}`);
+        return items;
+    }
+    /** Asks for an appointment. Refused (ChatError 409, intent-refused) when the key confirms
+     * bookings on its own and the time was just taken. */
+    async book(booking) {
+        return this.#request("/intents", { type: "book_appointment", ...booking });
+    }
+    /** Sends a lead from a form. */
+    async submitLead(lead) {
+        return this.#request("/intents", { type: "submit_lead", ...lead });
+    }
+    /** Opens a support ticket (the customer is found or created by phone). */
+    async openTicket(ticket) {
+        return this.#request("/intents", { type: "open_ticket", ...ticket });
+    }
+    /** Where an intent stands: pending, confirmed, failed (with the reason), or expired. */
+    async intent(id) {
+        return this.#request(`/intents/${encodeURIComponent(id)}`);
+    }
+    /** Keeps a sensitive value and returns a token for it (valid for a day, used once). */
+    async tokenize(kind, value) {
+        return this.#request("/tokens", { kind, value });
+    }
+}

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "@nistrix/chat",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Nistrix chat for customers' sites and apps: visitors talk to the organization's agents and team with a publishable key (nx_pk_). Runs in browsers and React Native.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nistrix-ltda/nistrix-chat-sdk.git"
+  },
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "pnpm test && pnpm build"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "devDependencies": {
+    "typescript": "~5.9.3",
+    "vitest": "^3.2.4"
+  }
+}