chatwoot-router 0.2.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,15 +1,11 @@
 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 = 45;
+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, transition?: Transition): Promise<void>;
-    requestSweep(): Promise<void>;
     alarm(): Promise<void>;
-    private sweep;
     private enqueue;
-    private schedule;
 }

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

@@ -1,7 +1,5 @@
 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;
     set(key: string, value: string): void;
@@ -15,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

@@ -1,23 +1,6 @@
-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;
@@ -25,12 +8,62 @@ export declare function requestHandoff(store: RoutingStore, accountId: number, c
 /** 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<{
+    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;
@@ -83,4 +116,3 @@ export declare function readTurn(chatwoot: ChatwootClient, store: RoutingStore,
     boundary: number;
     handoff: boolean;
 }>;
-export {};

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,7 +7,8 @@ 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
@@ -19,6 +21,7 @@ export type ChatwootConversation = components["schemas"]["conversation_show"] &
 };
 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>>;
@@ -96,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. */
@@ -107,7 +110,6 @@ 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>;
@@ -186,13 +188,13 @@ 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): {

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,16 +1,18 @@
 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;
@@ -21,6 +23,8 @@ export declare class QueueStore {
      */
     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. */

package/package.json

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