chatwoot-router 0.1.0 → 0.3.0

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

@@ -0,0 +1,5 @@
+import { type ChatwootClient, type ChatwootMessage } from "../../../shared/chatwoot/api.ts";
+/** A Chatwoot creation receipt, not a channel delivery receipt. */
+export declare function confirmedReply(message: ChatwootMessage | undefined, botId: number | undefined): boolean;
+/** Read past turn boundaries, including replies made by the former relay's brand bot. */
+export declare function replyHistory(chatwoot: ChatwootClient, accountId: number, conversationId: number, botId: number | undefined, freshPages?: readonly ChatwootMessage[][]): Promise<"found" | "complete-none" | "unknown">;

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

@@ -1,14 +1,11 @@
 import { DurableObject } from "cloudflare:workers";
 import type { Env } from "./env.ts";
-export declare const ROUTER_NAME = "global";
-export declare const ROUTE_BUDGET = 15;
+import type { Transition } from "./webhook.ts";
+export declare function conversationName(accountId: number, conversationId: number): string;
 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>;
+    enqueueConversation(accountId: number, conversationId: number, transition?: Transition): Promise<void>;
     alarm(): Promise<void>;
-    private sweep;
     private enqueue;
-    private schedule;
 }

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

@@ -1,10 +1,7 @@
 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 {
@@ -16,4 +13,3 @@ export interface RoutingContext {
 }
 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/turn.d.ts

@@ -0,0 +1,118 @@
+import { type ChatwootClient } from "../../../shared/chatwoot/api.ts";
+import type { RoutingStore } from "./routing.ts";
+import type { Transition } from "./webhook.ts";
+export declare function expectActivity(store: RoutingStore, accountId: number, conversationId: number, transition: Transition): void;
+/** Preserve an observed pending departure across retries, without using metadata timestamps. */
+export declare function observeStatus(store: RoutingStore, accountId: number, conversationId: number, status: string): void;
+export declare function requestHandoff(store: RoutingStore, accountId: number, conversationId: number): void;
+/** Counts processing failures for this turn, independently of an old queued job's backoff. */
+export declare function recordFailure(store: RoutingStore, accountId: number, conversationId: number): number;
+export declare function clearFailures(store: RoutingStore, accountId: number, conversationId: number): void;
+export declare function readTurn(chatwoot: ChatwootClient, store: RoutingStore, accountId: number, conversationId: number): Promise<{
+    pages: {
+        id: number;
+        conversation_id?: number | undefined;
+        content?: string | null | undefined;
+        message_type: number;
+        content_type?: string | null | undefined;
+        status?: string | null | undefined;
+        created_at?: number | null | undefined;
+        private?: boolean | null | undefined;
+        content_attributes?: {
+            email?: {
+                subject?: string | null | undefined;
+                auto_reply?: boolean | null | undefined;
+                text_content?: {
+                    quoted?: string | null | undefined;
+                } | null | undefined;
+                html_content?: {
+                    quoted?: string | null | undefined;
+                } | null | undefined;
+            } | null | undefined;
+            deleted?: boolean | null | undefined;
+            external_error?: string | null | undefined;
+            activity?: {
+                type?: string | null | undefined;
+                status?: string | null | undefined;
+            } | null | undefined;
+            submitted_values?: unknown;
+            submitted_email?: unknown;
+            items?: unknown;
+        } | null | undefined;
+        sender?: {
+            id?: number | null | undefined;
+            name?: string | null | undefined;
+            email?: string | null | undefined;
+            type?: string | null | undefined;
+            thumbnail?: string | null | undefined;
+            avatar_url?: string | null | undefined;
+        } | null | undefined;
+        attachments?: {
+            file_type?: string | null | undefined;
+            data_url?: string | null | undefined;
+            fallback_title?: string | null | undefined;
+            coordinates_lat?: number | null | undefined;
+            coordinates_long?: number | null | undefined;
+            meta?: {
+                firstName?: string | null | undefined;
+                lastName?: string | null | undefined;
+                first_name?: string | null | undefined;
+                last_name?: string | null | undefined;
+            } | null | undefined;
+        }[] | null | undefined;
+    }[][];
+    messages: {
+        id: number;
+        conversation_id?: number | undefined;
+        content?: string | null | undefined;
+        message_type: number;
+        content_type?: string | null | undefined;
+        status?: string | null | undefined;
+        created_at?: number | null | undefined;
+        private?: boolean | null | undefined;
+        content_attributes?: {
+            email?: {
+                subject?: string | null | undefined;
+                auto_reply?: boolean | null | undefined;
+                text_content?: {
+                    quoted?: string | null | undefined;
+                } | null | undefined;
+                html_content?: {
+                    quoted?: string | null | undefined;
+                } | null | undefined;
+            } | null | undefined;
+            deleted?: boolean | null | undefined;
+            external_error?: string | null | undefined;
+            activity?: {
+                type?: string | null | undefined;
+                status?: string | null | undefined;
+            } | null | undefined;
+            submitted_values?: unknown;
+            submitted_email?: unknown;
+            items?: unknown;
+        } | null | undefined;
+        sender?: {
+            id?: number | null | undefined;
+            name?: string | null | undefined;
+            email?: string | null | undefined;
+            type?: string | null | undefined;
+            thumbnail?: string | null | undefined;
+            avatar_url?: string | null | undefined;
+        } | null | undefined;
+        attachments?: {
+            file_type?: string | null | undefined;
+            data_url?: string | null | undefined;
+            fallback_title?: string | null | undefined;
+            coordinates_lat?: number | null | undefined;
+            coordinates_long?: number | null | undefined;
+            meta?: {
+                firstName?: string | null | undefined;
+                lastName?: string | null | undefined;
+                first_name?: string | null | undefined;
+                last_name?: string | null | undefined;
+            } | null | undefined;
+        }[] | null | undefined;
+    }[];
+    boundary: number;
+    handoff: boolean;
+}>;

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

@@ -1,4 +1,9 @@
+export interface Transition {
+    status: string;
+    at?: number;
+}
 export declare function eventTarget(payload: unknown): {
     accountId: number;
     conversationId: number;
+    transition?: Transition;
 } | undefined;

package/lib/shared/alarm.d.ts

@@ -0,0 +1,2 @@
+/** Set the one Durable Object alarm for the earliest durable wake-up. */
+export declare function scheduleAlarm(state: DurableObjectState, next: number | undefined): Promise<void>;

package/lib/shared/budget.d.ts

@@ -2,12 +2,25 @@ import type { Fetch } from "./chatwoot/api.ts";
 export declare class BudgetExhaustedError extends Error {
     constructor();
 }
+export { JobDeadlineError } from "./deadline.ts";
+export declare const METADATA_TIMEOUT_MS = 1500;
+export declare const TRANSFER_TIMEOUT_MS = 8000;
+export declare const JOB_SLICE_MS = 10000;
 export declare class Budget {
     readonly limit: number;
     private readonly fetchImpl;
-    private readonly timeoutMs;
     private used;
-    constructor(limit: number, fetchImpl?: Fetch, timeoutMs?: number);
+    private slice;
+    private sliceEnds;
+    constructor(limit: number, fetchImpl?: Fetch);
     get remaining(): number;
+    startSlice(ms?: number): void;
+    requireTime(ms: number): void;
+    checkpoint(): void;
+    consume(): void;
+    require(requests: number): void;
+    controlSignal(ms: number): AbortSignal;
+    fetchWith(timeoutMs: number): Fetch;
     readonly fetch: Fetch;
+    private request;
 }

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

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import type { RateLimitStore } from "../rate-limit.ts";
 import type { RelayConversation, RelayMessage } from "../types.ts";
 import type { components, operations } from "./schema.ts";
 export type Fetch = (input: Request) => Promise<Response>;
@@ -6,15 +7,21 @@ export type Fetch = (input: Request) => Promise<Response>;
 export declare class ChatwootError extends Error {
     readonly status: number;
     readonly conversationMissing: boolean;
-    constructor(status: number, operation: string, conversationMissing?: boolean);
+    readonly retryAfterMs: number | undefined;
+    constructor(status: number, operation: string, conversationMissing?: boolean, retryAfterMs?: number);
 }
 /**
  * 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"];
+export type ChatwootConversation = components["schemas"]["conversation_show"] & {
+    meta?: {
+        assignee_type?: string | null;
+    };
+};
 declare const messageSchema: z.ZodObject<{
     id: z.ZodNumber;
+    conversation_id: z.ZodOptional<z.ZodNumber>;
     content: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     message_type: z.ZodNumber;
     content_type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -34,6 +41,10 @@ declare const messageSchema: z.ZodObject<{
         }, z.core.$strip>>>;
         deleted: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
         external_error: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        activity: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            status: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        }, z.core.$strip>>>;
         submitted_values: z.ZodOptional<z.ZodUnknown>;
         submitted_email: z.ZodOptional<z.ZodUnknown>;
         items: z.ZodOptional<z.ZodUnknown>;
@@ -65,6 +76,8 @@ export type ChatwootMessage = z.infer<typeof messageSchema>;
 export declare const CONVERSATIONS_PER_PAGE = 25;
 /** Chatwoot returns up to 100 messages per `after` page. */
 export declare const MESSAGE_PAGE_SIZE = 100;
+/** MessageFinder returns 20 for the latest page and for `before`. */
+export declare const MESSAGE_HISTORY_PAGE_SIZE = 20;
 /** 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. */
@@ -86,7 +99,7 @@ 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): {
+export declare function chatwootClient(baseUrl: string, token: string, fetch: Fetch, limits?: RateLimitStore): {
     /** 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. */
@@ -97,13 +110,16 @@ export declare function chatwootClient(baseUrl: string, token: string, fetch: Fe
      * (MessageFinder#messages_between at v4.18.0) or exclusively (as the spec describes it).
      */
     getMessage(accountId: number, conversationId: number, messageId: number): Promise<ChatwootMessage | undefined>;
+    inboxBot(accountId: number, inboxId: number): Promise<{
+        id: number;
+    } | 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[]>;
+    listConversations(accountId: number, page: number, status?: "all" | "open" | "snoozed" | "pending"): 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<{
@@ -160,7 +176,7 @@ export declare function chatwootClient(baseUrl: string, token: string, fetch: Fe
     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>;
+    assign(accountId: number, conversationId: number, assigneeId: number, assigneeType?: "User" | "AgentBot"): 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
@@ -172,14 +188,51 @@ export declare function chatwootClient(baseUrl: string, token: string, fetch: Fe
     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>;
+    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>;
+    createMessage(accountId: number, conversationId: number, message: NewMessage): Promise<ChatwootMessage | undefined>;
 };
+/** A bot (or another explicit non-user assignee) must never be matched to a numeric user id. */
+export declare function personAssignee(conversation: ChatwootConversation): {
+    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?: Record<string, unknown>;
+    uid?: string;
+    type?: string | null;
+    custom_attributes?: Record<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;
+    }[];
+} | undefined;
+/** An actual public answer; Chatwoot templates include greetings and out-of-office notices. */
+export declare function isAnsweringReply(message: ChatwootMessage): boolean;
 export declare function toRelayConversation(conversationId: number, conversation: ChatwootConversation): RelayConversation;
 export declare function toRelayMessage(message: ChatwootMessage, context: {
     account: {

package/lib/shared/concurrent.d.ts

@@ -0,0 +1,4 @@
+/** Finish or cancel every independent read before the caller can yield to another job. */
+export declare function parallel<T extends readonly unknown[]>(...reads: {
+    [K in keyof T]: Promise<T[K]>;
+}): Promise<T>;

package/lib/shared/deadline.d.ts

@@ -0,0 +1,6 @@
+/** Bounds non-fetch dependencies too, including an RPC whose enqueue outcome can be unknown. */
+export declare function within<T>(pending: Promise<T>, signal: AbortSignal): Promise<T>;
+export declare class JobDeadlineError extends Error {
+    readonly requestStarted: boolean;
+    constructor(requestStarted?: boolean);
+}

package/lib/shared/rate-limit.d.ts

@@ -0,0 +1,5 @@
+/** Cache-aside state shared by upstream clients' durable cooldown stores. */
+export interface RateLimitStore {
+    get(key: string): string | undefined;
+    set(key: string, value: string, ttlMs?: number): void;
+}

package/lib/shared/store.d.ts

@@ -1,27 +1,30 @@
 export declare function retryDelay(attempts: number): number;
-export interface Job {
+export type Job = {
     key: string;
     payload: string;
     version: number;
     attempts: number;
     /** When the job was first queued (ms since the epoch). */
     createdAt: number;
-}
+};
 export declare class QueueStore {
     protected readonly sql: SqlStorage;
     protected readonly now: () => number;
-    constructor(sql: SqlStorage, now?: () => number);
+    private readonly atomic;
+    constructor(sql: SqlStorage, now?: () => number, atomic?: <T>(write: () => T) => T);
+    transaction<T>(write: () => T): T;
     migrate(): void;
     get(key: string): string | undefined;
     set(key: string, value: string, ttlMs?: number): void;
     delete(key: string): void;
-    list(start: string, end: string): string[];
     /**
      * Adds a job, or marks an existing one as needing another run (its version changes). A job
      * that is backing off after failures keeps its schedule.
      */
     enqueue(key: string, priority: number, payload: string, notBefore?: number): void;
     nextDueJob(): Job | undefined;
+    /** A bounded due batch; independent scan and delivery work can select their own keys. */
+    nextDueJobs(limit: number, prefix?: string): Job[];
     /** Earliest due time. */
     nextWakeup(): number | undefined;
     /** Removes a finished job unless it was enqueued again while running. */
@@ -33,5 +36,9 @@ export declare class QueueStore {
      * budget, or Discord rate limits it.
      */
     deferJob(job: Job, delayMs?: number): void;
+    /** One short re-read for a racing status webhook, then wait for an event or a sweep. */
+    holdJob(job: Job): void;
+    /** Suspended conversation jobs need reconciliation even outside the ordinary activity window. */
+    wakeHeldJobs(): void;
     prune(): void;
 }

package/lib/shared/types.d.ts

@@ -49,7 +49,9 @@ export interface RelayConversation {
         blocked?: boolean;
         avatarUrl?: string | null;
     };
+    /** Person only; agent bots are represented as unassigned. */
     assignee?: RelayAssignee | null;
+    assigneeType?: string | null;
     customAttributes: Record<string, unknown>;
 }
 export interface RelayMessage {
@@ -64,6 +66,8 @@ export interface RelayMessage {
     emailSubject?: string | null;
     /** An automatic email reply (out of office, for example): relayed without notifications. */
     autoReply?: boolean;
+    /** A qualifying public reply follows this message in Chatwoot. */
+    answered?: boolean;
     attachments: RelayAttachment[];
     /** A bot's options to pick, cards, or articles, with a link each when they have one. */
     items?: RelayItem[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chatwoot-router",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Route Chatwoot conversations with TypeSafe Jev on Cloudflare Workers.",
   "keywords": [
     "chatwoot",

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

@@ -1,14 +0,0 @@
-import { z } from "zod";
-import type { RoutingContext, RoutingStore } from "./routing.ts";
-declare const effectSchema: z.ZodObject<{
-    inputId: z.ZodNumber;
-    kind: z.ZodNullable<z.ZodString>;
-    handled: z.ZodNumber;
-}, z.core.$strip>;
-export declare function actOnce(ctx: RoutingContext, key: string, effect: z.infer<typeof effectSchema>, record: "before" | "after", act: () => Promise<unknown>): Promise<void>;
-export declare function readEffects(store: RoutingStore, accountId: number, conversationId: number): {
-    inputId: number;
-    kind: string | null;
-    handled: number;
-}[];
-export {};

package/lib/shared/attributes.d.ts

@@ -1,6 +0,0 @@
-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/sweep.d.ts

@@ -1,11 +0,0 @@
-import { z } from "zod";
-import type { reconcileSchema } from "./config.ts";
-import type { QueueStore } from "./store.ts";
-declare const passSchema: z.ZodObject<{
-    cutoff: z.ZodNumber;
-    page: z.ZodNumber;
-    startedAt: z.ZodNumber;
-}, z.core.$strip>;
-export declare function readSweepPass(store: QueueStore, accountId: number, reconcile: z.infer<typeof reconcileSchema>): z.infer<typeof passSchema>;
-export declare function saveSweepPass(store: QueueStore, accountId: number, pass: z.infer<typeof passSchema>, nextPage?: number): void;
-export {};