@ecodrix/erix-api 3.1.2 → 3.2.0

package/dist/ts/esm/visitor.d.ts

@@ -0,0 +1,147 @@
+import { V as VisitorMessage, d as VisitorTyping, A as APIError, e as WebchatSettings } from './error-DuNpKP1d.js';
+export { W as WebchatSettingsPatch } from './error-DuNpKP1d.js';
+
+/**
+ * @module visitor
+ * @responsibility `@ecodrix/erix-api/visitor` — the anonymous website-chat
+ * visitor client. No API key and no workspace data: a visitor reads and
+ * writes only their own thread, identified by their session id. Uses `fetch`
+ * for HTTP and loads `socket.io-client` only when `connect()` is called, so a
+ * chat widget doesn't ship the full SDK (no axios on this path).
+ *
+ * Every import here must stay free of axios: the subpath's whole point is a
+ * small bundle (checked by `visitor.test.ts` and `scripts/smoke-dist.mjs`).
+ */
+
+/** The widget's look, as a visitor reads it (no domains, no staff-name switch). */
+type WebchatWidget = Omit<WebchatSettings, "allowedDomains" | "showStaffNames">;
+/**
+ * Why a visitor call failed. Server codes, plus `NETWORK_ERROR` when no
+ * answer came back (offline, timed out): only that one and `INTERNAL_ERROR`
+ * are worth an immediate "Try again".
+ */
+type WebchatErrorCode = "VALIDATION_ERROR" | "NOT_FOUND" | "ORIGIN_NOT_ALLOWED" | "RATE_LIMITED" | "INTERNAL_ERROR" | "MALICIOUS_INPUT" | "NETWORK_ERROR";
+/**
+ * A failed visitor call or a refused live connection. `status` is the HTTP
+ * status (absent for network and socket errors); `field` names the input a
+ * `VALIDATION_ERROR` is about (`text`, `name`, `phone`, `email`, …) and
+ * `message` is copy the visitor can read.
+ */
+declare class WebchatVisitorError extends APIError {
+    code: WebchatErrorCode;
+    field?: string;
+    constructor(message: string, code: WebchatErrorCode, status?: number, field?: string);
+}
+interface WebchatVisitorOptions {
+    /** API host, scheme and domain only. Default `https://api.ecodrix.com`. */
+    apiUrl?: string;
+    /** The workspace's public client code (from the embed snippet). */
+    clientCode: string;
+    /**
+     * The visitor's id and only secret: random, 20–80 characters of
+     * `A-Z a-z 0-9 _ -` (e.g. `crypto.randomUUID()`). Keep it for the visitor's
+     * next visit to continue the same thread.
+     */
+    sessionId: string;
+    /** The origin of the site the chat runs on, checked against the workspace's allowed domains. */
+    parent: string;
+}
+/** The page the visitor is on. Query string and hash are dropped before sending. */
+interface VisitorPage {
+    /** Starts with `/`, up to 200 characters. */
+    path: string;
+    /** Up to 120 characters. */
+    title?: string;
+}
+interface VisitorSendOptions {
+    /**
+     * Your id for this message, 8–64 characters of `A-Z a-z 0-9 _ -`. Resend
+     * with the same id after a failure: it's stored (and answered) once.
+     */
+    messageId?: string;
+    /** The visitor's name, if known. */
+    name?: string;
+    page?: VisitorPage;
+}
+/** The visitor's details (name plus a phone or an email). */
+interface VisitorContact {
+    name: string;
+    phone?: string;
+    email?: string;
+    /** Ticked the consent box (shown only when `messages()` returned `consentNotice`). */
+    consent?: boolean;
+}
+/** `messages()`: the thread, the widget's look, and the consent notice when the workspace has a privacy link. */
+interface VisitorThread {
+    success: boolean;
+    data: VisitorMessage[];
+    widget: WebchatWidget;
+    consentNotice?: string;
+    privacyPolicyUrl?: string;
+}
+/** `send()`: the stored message, or `{ duplicate: true }` when a resent `messageId` was already stored. */
+interface VisitorSendResult {
+    success: boolean;
+    data: VisitorMessage | {
+        duplicate: true;
+    };
+}
+interface VisitorLiveHandlers {
+    /** A new message on the thread (team, AI or system; also the visitor's own). */
+    onMessage?: (message: VisitorMessage) => void;
+    onTyping?: (typing: VisitorTyping) => void;
+    /**
+     * The live connection failed or was refused. Fall back to polling
+     * `messages()` until `onReconnect`. Network drops retry on their own;
+     * `RATE_LIMITED` and `INTERNAL_ERROR` refusals retry after a minute; other
+     * refusals (`ORIGIN_NOT_ALLOWED`, `NOT_FOUND`, `VALIDATION_ERROR`) don't.
+     */
+    onError?: (error: WebchatVisitorError) => void;
+    /**
+     * Live again after a drop or a refusal. Nothing missed in between is
+     * replayed: call `messages()` now.
+     */
+    onReconnect?: () => void;
+}
+/**
+ * One website visitor's chat with a workspace: send, read, leave contact
+ * details, and get replies live.
+ *
+ * @example
+ * ```ts
+ * import { WebchatVisitor } from "@ecodrix/erix-api/visitor";
+ *
+ * const chat = new WebchatVisitor({ clientCode: "ERIX_CLNT_XXXXXX", sessionId, parent: location.origin });
+ * const { data: thread, widget } = await chat.messages();
+ * await chat.send("Do you open on Sunday?", { messageId: crypto.randomUUID() });
+ * chat.connect({ onMessage: (m) => render(m), onReconnect: () => chat.messages().then(redraw) });
+ * ```
+ */
+declare class WebchatVisitor {
+    private readonly options;
+    private readonly host;
+    private readonly base;
+    private socket;
+    private opening;
+    private retry;
+    constructor(options: WebchatVisitorOptions);
+    /** Send the visitor's message. */
+    send(text: string, opts?: VisitorSendOptions): Promise<VisitorSendResult>;
+    /** The visitor's thread, oldest first, with the widget's look. */
+    messages(): Promise<VisitorThread>;
+    /** Save the visitor's details and link the thread to a contact. */
+    contact(details: VisitorContact): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Get replies and typing live over the `/visitor` socket. Only works inside
+     * the ERIX widget frame: the server refuses sockets opened from other
+     * origins, so a chat UI on your own page polls `messages()` instead.
+     */
+    connect(handlers: VisitorLiveHandlers): Promise<void>;
+    /** Close the live connection. `connect()` again to reopen. */
+    disconnect(): void;
+    private call;
+}
+
+export { type VisitorContact, type VisitorLiveHandlers, VisitorMessage, type VisitorPage, type VisitorSendOptions, type VisitorSendResult, type VisitorThread, VisitorTyping, type WebchatErrorCode, WebchatSettings, WebchatVisitor, WebchatVisitorError, type WebchatVisitorOptions, type WebchatWidget };

package/dist/ts/esm/visitor.js

@@ -0,0 +1 @@
+import{a as l,b as h,c as m,d as a,g as d,h as O,j as f}from"./chunk-XPXDFZWU.js";var R=class extends f{constructor(i,n,p,o){super(i,p,n);a(this,"field");this.name="WebchatVisitorError",this.field=o}},_=3e4,N=6e4,V=new Set(["RATE_LIMITED","INTERNAL_ERROR"]),S={400:"VALIDATION_ERROR",403:"ORIGIN_NOT_ALLOWED",404:"NOT_FOUND",429:"RATE_LIMITED"},I=class{constructor(e){a(this,"options",e);a(this,"host");a(this,"base");a(this,"socket",null);a(this,"opening",null);a(this,"retry");var i;this.host=((i=e.apiUrl)!=null?i:d).replace(/\/+$/,""),this.base=`${O("v1",this.host)}/infra/connect/webhooks/webchat/${encodeURIComponent(e.clientCode)}`}send(e,i={}){let{sessionId:n,parent:p}=this.options,t=i,{page:o}=t,c=m(t,["page"]);return this.call("/message",l(l({sessionId:n,text:e,parent:p},c),o&&{page:h(l({},o),{path:o.path.split(/[?#]/)[0]})}))}messages(){let{sessionId:e,parent:i}=this.options;return this.call(`/messages?${new URLSearchParams({sessionId:e,parent:i})}`)}contact(e){let{sessionId:i,parent:n}=this.options;return this.call("/contact",l({sessionId:i,parent:n},e))}connect(e){if(this.opening)return this.opening;let{clientCode:i,sessionId:n,parent:p}=this.options,o=import("socket.io-client").then(({io:c})=>{if(this.opening!==o)return;let t=c(`${this.host}/visitor`,{auth:{clientCode:i,sessionId:n,parent:p}});this.socket=t;let g=!1;t.on("connect",()=>{var r;g&&((r=e.onReconnect)==null||r.call(e)),g=!1}),t.on("disconnect",()=>{g=!0}),t.on("connect_error",r=>{var u,E,T;g=!0;let s=(E=(u=r.data)==null?void 0:u.code)!=null?E:"NETWORK_ERROR";(T=e.onError)==null||T.call(e,new R(r.message,s)),!t.active&&V.has(s)&&(clearTimeout(this.retry),this.retry=setTimeout(()=>{this.socket===t&&t.connect()},N))}),t.on("webchat.message",r=>{var s;return(s=e.onMessage)==null?void 0:s.call(e,r)}),t.on("webchat.typing",r=>{var s;return(s=e.onTyping)==null?void 0:s.call(e,r)})},c=>{var t;this.opening===o&&(this.opening=null,(t=e.onError)==null||t.call(e,new R((c==null?void 0:c.message)||"Network error","NETWORK_ERROR")))});return this.opening=o,o}disconnect(){var e;clearTimeout(this.retry),(e=this.socket)==null||e.disconnect(),this.socket=null,this.opening=null}async call(e,i){var g,r;let n=new AbortController,p=setTimeout(()=>n.abort(),_),o,c;try{o=await fetch(`${this.base}${e}`,{method:i?"POST":"GET",headers:i?{"content-type":"application/json"}:void 0,body:i?JSON.stringify(i):void 0,signal:n.signal}),c=await o.text()}catch(s){throw new R((s==null?void 0:s.message)||"Network error","NETWORK_ERROR")}finally{clearTimeout(p)}let t=null;try{t=JSON.parse(c)}catch(s){}if(o.ok&&(t!=null&&t.success))return t;throw new R((t==null?void 0:t.message)||(t==null?void 0:t.error)||`Request failed (${o.status})`,(r=(g=t==null?void 0:t.code)!=null?g:S[o.status])!=null?r:"INTERNAL_ERROR",o.status,t==null?void 0:t.field)}};export{I as WebchatVisitor,R as WebchatVisitorError};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecodrix/erix-api",
-  "version": "3.1.2",
+  "version": "3.2.0",
   "author": "ECODrIx Team <contact@ecodrix.com>",
   "license": "MIT",
   "description": "Official TypeScript SDK for the ERIX API by ECODrIx: CRM, Flow automations, one inbox across WhatsApp, Instagram and email, GST invoices and payments. Node and browser (proxy mode).",
@@ -33,6 +33,11 @@
       "types": "./dist/ts/esm/index.d.ts",
       "import": "./dist/ts/esm/index.js",
       "require": "./dist/ts/cjs/index.cjs"
+    },
+    "./visitor": {
+      "types": "./dist/ts/esm/visitor.d.ts",
+      "import": "./dist/ts/esm/visitor.js",
+      "require": "./dist/ts/cjs/visitor.cjs"
     }
   },
   "files": [