chatwoot-router 0.1.0

package/lib/packages/chatwoot-router/src/router.d.ts

@@ -0,0 +1,14 @@
+import { DurableObject } from "cloudflare:workers";
+import type { Env } from "./env.ts";
+export declare const ROUTER_NAME = "global";
+export declare const ROUTE_BUDGET = 15;
+export declare class Router extends DurableObject<Env> {
+    private readonly store;
+    constructor(context: DurableObjectState, env: Env);
+    enqueueConversation(accountId: number, conversationId: number): Promise<void>;
+    requestSweep(): Promise<void>;
+    alarm(): Promise<void>;
+    private sweep;
+    private enqueue;
+    private schedule;
+}

package/lib/packages/chatwoot-router/src/routing.d.ts

@@ -0,0 +1,19 @@
+import { type ChatwootClient, type Fetch } from "../../../shared/chatwoot/api.ts";
+import type { Settings } from "./config.ts";
+/** Jev's answer when no owner fits; also the reserved route name. */
+export declare const UNCLEAR = "unclear";
+export interface RoutingStore {
+    get(key: string): string | undefined;
+    list(start: string, end: string): string[];
+    set(key: string, value: string): void;
+}
+export interface RoutingContext {
+    settings: Settings;
+    store: RoutingStore;
+    chatwoot: ChatwootClient;
+    /** Counts toward the invocation's subrequest budget, like the Chatwoot client's. */
+    fetch: Fetch;
+}
+export declare function routesAccount(settings: Settings, accountId: number): boolean;
+export declare function routeConversation(ctx: RoutingContext, accountId: number, conversationId: number): Promise<"defer" | undefined>;
+export declare function sanitize(text: string, identities: Array<string | null | undefined>): string;

package/lib/packages/chatwoot-router/src/settings.d.ts

@@ -0,0 +1,3 @@
+import { type Settings } from "./config.ts";
+import type { Env } from "./env.ts";
+export declare const loadSettings: (env: Env) => Promise<Settings>;

package/lib/packages/chatwoot-router/src/webhook.d.ts

@@ -0,0 +1,4 @@
+export declare function eventTarget(payload: unknown): {
+    accountId: number;
+    conversationId: number;
+} | undefined;

package/lib/shared/attributes.d.ts

@@ -0,0 +1,6 @@
+export declare const ROUTING_ATTRIBUTES: {
+    readonly seen: "routing_seen";
+    readonly handled: "routing_handled";
+    readonly kind: "routing_kind";
+};
+export declare function messageWatermark(value: unknown): number;

package/lib/shared/budget.d.ts

@@ -0,0 +1,13 @@
+import type { Fetch } from "./chatwoot/api.ts";
+export declare class BudgetExhaustedError extends Error {
+    constructor();
+}
+export declare class Budget {
+    readonly limit: number;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    private used;
+    constructor(limit: number, fetchImpl?: Fetch, timeoutMs?: number);
+    get remaining(): number;
+    readonly fetch: Fetch;
+}

package/lib/shared/chatwoot/api.d.ts

@@ -0,0 +1,199 @@
+import { z } from "zod";
+import type { RelayConversation, RelayMessage } from "../types.ts";
+import type { components, operations } from "./schema.ts";
+export type Fetch = (input: Request) => Promise<Response>;
+/** A non-2xx answer from Chatwoot. Only the status is kept: bodies may echo user content. */
+export declare class ChatwootError extends Error {
+    readonly status: number;
+    readonly conversationMissing: boolean;
+    constructor(status: number, operation: string, conversationMissing?: boolean);
+}
+/**
+ * A conversation as returned by GET conversations/{id} and in the conversation list. The spec's
+ * `status` enum omits `snoozed`, which the API does return, so the relay treats it as a string.
+ */
+export type ChatwootConversation = components["schemas"]["conversation_show"];
+declare const messageSchema: z.ZodObject<{
+    id: z.ZodNumber;
+    content: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    message_type: z.ZodNumber;
+    content_type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    status: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    created_at: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    private: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    content_attributes: z.ZodCatch<z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        email: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            subject: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            auto_reply: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+            text_content: z.ZodCatch<z.ZodOptional<z.ZodNullable<z.ZodObject<{
+                quoted: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            }, z.core.$strip>>>>;
+            html_content: z.ZodCatch<z.ZodOptional<z.ZodNullable<z.ZodObject<{
+                quoted: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            }, z.core.$strip>>>>;
+        }, z.core.$strip>>>;
+        deleted: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+        external_error: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        submitted_values: z.ZodOptional<z.ZodUnknown>;
+        submitted_email: z.ZodOptional<z.ZodUnknown>;
+        items: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$strip>>>>;
+    sender: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        id: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        email: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        thumbnail: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        avatar_url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>>>;
+    attachments: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+        file_type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        data_url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        fallback_title: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        coordinates_lat: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        coordinates_long: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        meta: z.ZodCatch<z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            firstName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            lastName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            first_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            last_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        }, z.core.$strip>>>>;
+    }, z.core.$strip>>>>;
+}, z.core.$strip>;
+export type ChatwootMessage = z.infer<typeof messageSchema>;
+/** Conversations per page of the list endpoint (ConversationFinder's CONVERSATION_RESULTS_PER_PAGE default, v4.18.0). */
+export declare const CONVERSATIONS_PER_PAGE = 25;
+/** Chatwoot returns up to 100 messages per `after` page. */
+export declare const MESSAGE_PAGE_SIZE = 100;
+/** The body of POST conversations/{id}/toggle_status. */
+export type StatusChange = operations["toggle-status-of-a-conversation"]["requestBody"]["content"]["application/json"];
+/** A priority for POST conversations/{id}/toggle_priority; null clears it. */
+type ConversationPriority = NonNullable<NonNullable<operations["toggle-priority-of-a-conversation"]["requestBody"]>["content"]["application/json"]["priority"]>;
+interface NewMessage {
+    content: string;
+    private: boolean;
+    files: ReadonlyArray<{
+        blob: Blob;
+        filename: string;
+    }>;
+    /**
+     * Send an email reply from the agent's own mailbox name on the inbox's domain. Phala's Chatwoot
+     * build reads `content_attributes.send_as_agent` (Email::AgentAddressBuilder); upstream ignores it.
+     */
+    sendAsAgent?: boolean;
+}
+export type ChatwootClient = ReturnType<typeof chatwootClient>;
+type MessageQuery = NonNullable<operations["list-all-messages"]["parameters"]["query"]> & {
+    filter_internal_messages?: true;
+};
+export declare function chatwootClient(baseUrl: string, token: string, fetch: Fetch): {
+    /** The conversation, or undefined when it does not exist (it was deleted). */
+    getConversation(accountId: number, conversationId: number): Promise<ChatwootConversation | undefined>;
+    /** Messages with an id above `after`, oldest first; without `after`, the latest page. */
+    listMessages(accountId: number, conversationId: number, query?: MessageQuery): Promise<ChatwootMessage[]>;
+    /**
+     * One message, or undefined if it or its conversation does not exist. Asks for the ids between
+     * `messageId - 1` and `messageId + 1`, which contains it whether `after` is read inclusively
+     * (MessageFinder#messages_between at v4.18.0) or exclusively (as the spec describes it).
+     */
+    getMessage(accountId: number, conversationId: number, messageId: number): Promise<ChatwootMessage | undefined>;
+    inboxName(accountId: number, inboxId: number): Promise<string | undefined>;
+    /**
+     * One page (CONVERSATIONS_PER_PAGE) of conversations of any assignee and the given status
+     * (default: any), most recent activity first (Conversations::SortService's default,
+     * `last_activity_at_desc`, at v4.18.0).
+     */
+    listConversations(accountId: number, page: number, status?: "all" | "open" | "snoozed"): Promise<ChatwootConversation[]>;
+    /** The content of the account's canned response with this short code, if it exists. */
+    cannedResponse(accountId: number, shortCode: string): Promise<string | undefined>;
+    getProfile(): Promise<{
+        id?: number;
+        access_token?: string;
+        account_id?: number;
+        available_name?: string;
+        avatar_url?: string;
+        confirmed?: boolean;
+        display_name?: string | null;
+        message_signature?: string | null;
+        email?: string;
+        hmac_identifier?: string;
+        inviter_id?: number | null;
+        name?: string;
+        provider?: string;
+        pubsub_token?: string;
+        role?: "agent" | "administrator";
+        ui_settings?: {
+            [x: string]: unknown;
+        };
+        uid?: string;
+        type?: string | null;
+        custom_attributes?: {
+            [x: string]: unknown;
+        };
+        accounts?: {
+            id?: number;
+            name?: string;
+            status?: string;
+            active_at?: string | null;
+            role?: "administrator" | "agent";
+            permissions?: string[];
+            availability?: string;
+            availability_status?: string;
+            auto_offline?: boolean;
+            custom_role_id?: number | null;
+            custom_role?: Record<string, unknown> | null;
+        }[];
+    }>;
+    listAgents(accountId: number): Promise<{
+        id?: number;
+        account_id?: number;
+        readonly availability_status?: "online" | "busy" | "offline";
+        auto_offline?: boolean;
+        confirmed?: boolean;
+        email?: string;
+        available_name?: string;
+        name?: string;
+        role?: "agent" | "administrator";
+        thumbnail?: string;
+        custom_role_id?: number | null;
+    }[]>;
+    setStatus(accountId: number, conversationId: number, change: StatusChange): Promise<void>;
+    setPriority(accountId: number, conversationId: number, priority: ConversationPriority | null): Promise<void>;
+    setContactBlocked(accountId: number, contactId: number, blocked: boolean): Promise<void>;
+    assign(accountId: number, conversationId: number, assigneeId: number): Promise<void>;
+    /**
+     * Removes the conversation's assignee the way Chatwoot's dashboard does (ConversationAction.vue
+     * posts `assignee_id: null`, which AssignmentsController#create applies, at v4.18.0). The
+     * spec types `assignee_id` as a number only, so this body is serialized here.
+     */
+    unassign(accountId: number, conversationId: number): Promise<void>;
+    /** The account's label names (Chatwoot saves them in lower case). */
+    listLabels(accountId: number): Promise<string[]>;
+    conversationLabels(accountId: number, conversationId: number): Promise<string[]>;
+    /** Replaces the conversation's labels (the spec's "Add Labels" overwrites the list). */
+    setLabels(accountId: number, conversationId: number, labels: string[]): Promise<void>;
+    setCustomAttributes: (accountId: number, conversationId: number, attributes: Record<string, unknown>) => Promise<void>;
+    /**
+     * Sends an outgoing message (or private note). With files it is sent as the spec's
+     * multipart/form-data body; the generated type renders its `attachments[]` binaries as
+     * strings, so the serializer appends the files itself.
+     */
+    createMessage(accountId: number, conversationId: number, message: NewMessage): Promise<void>;
+};
+export declare function toRelayConversation(conversationId: number, conversation: ChatwootConversation): RelayConversation;
+export declare function toRelayMessage(message: ChatwootMessage, context: {
+    account: {
+        id: number;
+        name: string;
+    };
+    inboxName?: string | null;
+    conversation: RelayConversation;
+    mentionedAgents?: ReadonlyMap<number, string>;
+    discordAvatarUrl?: string;
+}): RelayMessage;
+/**
+ * What Chatwoot itself shows and forwards (Message#ensure_processed_message_content, used by its
+ * Slack integration at v4.18.0): for an email, the reply without its quoted history.
+ */
+export declare function messageContent(message: ChatwootMessage): string;
+export {};