chatwoot-router 0.1.0 → 0.2.0

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

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

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

@@ -4,7 +4,6 @@ import type { Settings } from "./config.ts";
 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 {

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

@@ -0,0 +1,86 @@
+import { z } from "zod";
+import { type ChatwootClient } from "../../../shared/chatwoot/api.ts";
+import type { RoutingStore } from "./routing.ts";
+import type { Transition } from "./webhook.ts";
+declare const guardSchema: z.ZodObject<{
+    boundary: z.ZodOptional<z.ZodNumber>;
+    claimed: z.ZodOptional<z.ZodBoolean>;
+    pending: z.ZodOptional<z.ZodBoolean>;
+    transitionAt: z.ZodOptional<z.ZodNumber>;
+    expected: z.ZodOptional<z.ZodObject<{
+        status: z.ZodString;
+        at: z.ZodOptional<z.ZodNumber>;
+        after: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    handoff: z.ZodDefault<z.ZodBoolean>;
+    failures: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+type Guard = z.infer<typeof guardSchema>;
+export declare function readGuard(store: RoutingStore, accountId: number, conversationId: number): Guard;
+export declare function saveGuard(store: RoutingStore, accountId: number, conversationId: number, guard: Guard): void;
+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 class ActivityPendingError extends Error {
+    constructor();
+}
+export declare function readTurn(chatwoot: ChatwootClient, store: RoutingStore, accountId: number, conversationId: number): Promise<{
+    messages: {
+        id: number;
+        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;
+}>;
+export {};

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/chatwoot/api.d.ts

@@ -12,7 +12,11 @@ export declare class ChatwootError extends Error {
  * 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;
     content: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -34,6 +38,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 +73,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. */
@@ -97,13 +107,17 @@ 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>;
+    listInboxes(accountId: number): Promise<number[]>;
+    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 +174,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
@@ -180,6 +194,43 @@ export declare function chatwootClient(baseUrl: string, token: string, fetch: Fe
      */
     createMessage(accountId: number, conversationId: number, message: NewMessage): Promise<void>;
 };
+/** 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/store.d.ts

@@ -15,7 +15,6 @@ export declare class QueueStore {
     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.
@@ -33,5 +32,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.2.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 {};