@ecodrix/erix-api 3.1.1 → 3.2.0

package/dist/ts/esm/error-DuNpKP1d.d.ts

@@ -0,0 +1,158 @@
+/**
+ * Website chat (webchat) shapes shared by the visitor client
+ * (`@ecodrix/erix-api/visitor`) and the workspace client. Types only: this
+ * file must never import runtime code, so the visitor bundle stays small.
+ */
+/**
+ * A message as a website visitor sees it (`messages()`, the live
+ * `webchat.message` event). Nothing else from the stored row is exposed.
+ */
+interface VisitorMessage {
+    id: string;
+    direction: "inbound" | "outbound";
+    text: string;
+    /** ISO timestamp. */
+    createdAt: string;
+    /** Who wrote it: the visitor, the AI assistant, a team member, or a system notice. */
+    from: "visitor" | "ai" | "team" | "system";
+    /** Team replies only, and only when the workspace shows staff names. */
+    senderFirstName?: string;
+}
+/**
+ * The live `webchat.typing` event. `waiting: true` (with `on: false`) means
+ * the AI left the reply to the team: show "The team will reply here".
+ */
+interface VisitorTyping {
+    on: boolean;
+    waiting?: boolean;
+}
+/** The website chat widget's settings (`service_config.webchat`). */
+interface WebchatSettings {
+    /**
+     * Sites the widget may run on. Read-only here: add one with `domain`,
+     * remove one with `connections.removeWebchatDomain`.
+     */
+    allowedDomains: string[];
+    /** Up to 60 characters. */
+    name?: string;
+    /** Up to 200 characters. */
+    greeting?: string;
+    /** `#rrggbb`. */
+    color?: string;
+    /** Default `right`. */
+    position?: "left" | "right";
+    /** `https://` only. */
+    logoUrl?: string;
+    /** When the widget asks for name and phone/email. Default `when_needed`. */
+    detailsMode?: "before" | "when_needed" | "off";
+    /** Up to 80 characters, e.g. "We reply 10 am to 7 pm". */
+    hoursText?: string;
+    /** Show a team member's first name on their replies. Default true. */
+    showStaffNames?: boolean;
+}
+/**
+ * The website chat as its owner edits it (`connections.webchatSettings()`):
+ * the sites it may run on in plain text, the plan's cap on them, and the
+ * saved settings (a setting left at its default is absent).
+ */
+interface WebchatOwnerSettings {
+    allowedDomains: string[];
+    /** How many sites the plan allows. */
+    maxDomains: number;
+    settings: Omit<WebchatSettings, "allowedDomains">;
+}
+/**
+ * A settings save: send only what changes; `null` clears a setting back to
+ * its default. `domain` adds a site to the allowed domains (plan-capped).
+ */
+type WebchatSettingsPatch = {
+    [K in Exclude<keyof WebchatSettings, "allowedDomains">]?: WebchatSettings[K] | null;
+} & {
+    /** A site to add to the allowed domains, e.g. `example.com`. */
+    domain?: string;
+};
+
+/**
+ * Typed error hierarchy for the @ecodrix/erix-api SDK.
+ *
+ * All errors thrown by the SDK extend `EcodrixError`, so a single
+ * `catch` block can handle them all, while still allowing granular
+ * differentiation between auth failures, rate limits, and generic API errors.
+ *
+ * @example
+ * ```typescript
+ * import { APIError, AuthenticationError, RateLimitError } from "@ecodrix/erix-api";
+ *
+ * try {
+ *   await ecod.product.erix.leads.retrieve("invalid_id");
+ * } catch (err) {
+ *   if (err instanceof AuthenticationError) {
+ *     console.error("Invalid API key or client code.");
+ *   } else if (err instanceof RateLimitError) {
+ *     console.warn("Slow down — rate limit hit.");
+ *   } else if (err instanceof APIError) {
+ *     console.error(`API error ${err.status}: ${err.message}`);
+ *   }
+ * }
+ * ```
+ */
+/** Base class for all ECODrIx SDK errors. */
+declare class EcodrixError extends Error {
+    constructor(message: string);
+}
+/** One value the server refused, from a `VALIDATION_ERROR`'s `issues`. */
+interface APIErrorIssue {
+    /** Where in the request body, e.g. `["color"]`. */
+    path: (string | number)[];
+    message: string;
+    /** The check that failed, e.g. `"too_big"`. */
+    code?: string;
+}
+/**
+ * Represents an error returned by the ECODrIx API.
+ * Carries the HTTP `status` code and an optional `code` string.
+ */
+declare class APIError extends EcodrixError {
+    /** HTTP status code returned by the API (e.g. 400, 404, 500). */
+    status?: number;
+    /** Machine-readable error code (e.g. `"NOT_FOUND"`, `"VALIDATION_ERROR"`). */
+    code?: string;
+    /** Each refused value, when the server lists them (`VALIDATION_ERROR`). */
+    issues?: APIErrorIssue[];
+    /** The one field the server names, when it sends `field`. */
+    field?: string;
+    constructor(message: string, status?: number, code?: string);
+}
+/**
+ * Thrown when the API key or client code is missing, invalid, or expired.
+ * HTTP 401. `code` is the server's (e.g. `INVALID_KEY`) when it sends one.
+ */
+declare class AuthenticationError extends APIError {
+    constructor(message?: string, code?: string, status?: number);
+}
+/**
+ * Thrown when the caller is signed in but not allowed: role, plan, or no
+ * longer a member (`code` `FORBIDDEN`, `NOT_A_MEMBER`, …). HTTP 403. Extends
+ * AuthenticationError so existing 401/403 handling keeps working; check
+ * `status` or `code` to tell a dead key from a missing permission.
+ */
+declare class PermissionError extends AuthenticationError {
+    constructor(message?: string, code?: string);
+}
+/**
+ * Thrown when the rate limit for the API key has been exceeded.
+ * HTTP 429. Implement exponential backoff before retrying.
+ */
+declare class RateLimitError extends APIError {
+    constructor(message?: string);
+}
+/**
+ * Turn an HTTP client error into the typed SDK error: 401 → AuthenticationError,
+ * 403 → PermissionError, 429 → RateLimitError, else APIError. Keeps the
+ * server's status and code (sent in `code`, or in `error` as UPPER_SNAKE),
+ * and an APIError keeps the body's `issues` and `field` so a form can show
+ * each refused value under its own field.
+ */
+declare function toAPIError(error: any): APIError;
+
+export { APIError as A, EcodrixError as E, PermissionError as P, RateLimitError as R, type VisitorMessage as V, type WebchatSettingsPatch as W, type WebchatOwnerSettings as a, AuthenticationError as b, type APIErrorIssue as c, type VisitorTyping as d, type WebchatSettings as e, toAPIError as t };