@north-light/comms 0.0.0-stage → 0.1.0

package/dist/fake/store.js

@@ -0,0 +1,356 @@
+// The fake server's in-memory state and rules: contacts, messages, idempotency, and the
+// STOP / START / HELP keywords. No I/O: every operation returns the webhook events and logged
+// sends it produced, and server.ts delivers and prints them.
+import { randomUUID } from "node:crypto";
+import { MAX_TEXT_LENGTH } from "../helpers/format.js";
+/** The fictional app number every fake contact texts. */
+export const FAKE_NUMBER = "+15555550100";
+/** The keyword sets of the spec's "STOP, START, HELP" table. */
+const STOP_WORDS = new Set([
+    "stop",
+    "end",
+    "unsubscribe",
+    "cancel",
+    "quit",
+    "stopall",
+]);
+const START_WORDS = new Set(["start", "unstop", "yes"]);
+const HELP_WORDS = new Set(["help", "info"]);
+const E164 = /^\+[1-9]\d{6,14}$/;
+const EMAIL = /^[^\s@]+@[^\s@]+$/;
+const SIGN_IN_LINK_TTL_MS = 15 * 60_000;
+/** A refusal the server answers in the shared error envelope. */
+export class FakeApiError extends Error {
+    status;
+    code;
+    param;
+    name = "FakeApiError";
+    constructor(status, code, message, param) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.param = param;
+    }
+}
+const id = (prefix) => `${prefix}_${randomUUID()}`;
+function body(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        throw new FakeApiError(400, "invalid_request", "The request body must be a JSON object");
+    return value;
+}
+function text(source, key, options = {}) {
+    const value = source[key];
+    if (value === undefined && options.optional)
+        return undefined;
+    if (typeof value !== "string" || value === "")
+        throw new FakeApiError(400, "invalid_request", `\`${key}\` must be a non-empty string`, key);
+    return value;
+}
+const bareUser = (userId) => userId.replace(/^user:/, "");
+export class FakeStore {
+    #contacts = new Map();
+    #byHandle = new Map();
+    #messages = new Map();
+    #replays = new Map();
+    #links = new Map();
+    #displayName;
+    #helpText;
+    #now;
+    #users = 0;
+    constructor(options = {}) {
+        this.#displayName = options.displayName ?? "Fake App";
+        this.#helpText =
+            options.helpText ??
+                "This is the fake Comms server. Text STOP to opt out.";
+        this.#now = options.now ?? (() => new Date());
+    }
+    // ---- Simulated inbound ----------------------------------------------------
+    /** A person texts the app's fictional number. `userId` makes the contact a Northlight user. */
+    inbound(input) {
+        const source = body(input);
+        const from = text(source, "from");
+        if (!E164.test(from) && !EMAIL.test(from))
+            throw new FakeApiError(400, "invalid_request", "`from` must be an E.164 phone number such as +15550001, or an email", "from");
+        const message = text(source, "text");
+        const userId = text(source, "user_id", { optional: true });
+        const contact = this.#contactFor(from);
+        if (userId !== undefined)
+            contact.user = { id: `user:${bareUser(userId)}` };
+        const messageId = id("msg");
+        const word = message.trim().toLowerCase();
+        const result = (disposition) => ({
+            disposition,
+            messageId,
+            contactId: contact.id,
+            events: [],
+            sends: [],
+        });
+        const reply = (result_, reply_) => {
+            result_.sends.push(this.#system(contact, reply_));
+        };
+        if (STOP_WORDS.has(word)) {
+            contact.optedOut = true;
+            const out = result("stop");
+            reply(out, `${this.#displayName}: you won't get more texts from us. Text START to turn them back on.`);
+            out.events.push(this.#event("contact.opted_out", { contact_id: contact.id }));
+            return out;
+        }
+        if (contact.optedOut && START_WORDS.has(word)) {
+            contact.optedOut = false;
+            const out = result("start");
+            reply(out, `${this.#displayName}: texts are back on. Text STOP to stop.`);
+            out.events.push(this.#event("contact.opted_in", { contact_id: contact.id }));
+            return out;
+        }
+        if (HELP_WORDS.has(word)) {
+            const out = result("help");
+            reply(out, this.#helpText);
+            return out;
+        }
+        if (contact.optedOut)
+            return result("opted_out_ignored");
+        this.#remember(messageId, contact.id, "text", "delivered");
+        const out = result("forwarded");
+        out.events.push(this.#event("message.received", {
+            message_id: messageId,
+            number: FAKE_NUMBER,
+            contact: this.#webhookContact(contact),
+            content: { type: "text", text: message },
+            reply_to_message_id: null,
+            received_at: this.#now().toISOString(),
+        }));
+        return out;
+    }
+    // ---- Send API -------------------------------------------------------------
+    sendMessage(input) {
+        const source = body(input);
+        const key = text(source, "idempotency_key");
+        const to = body(source["to"]);
+        const message = text(source, "text", { optional: true });
+        const file = source["file"] === undefined ? undefined : body(source["file"]);
+        const fileUrl = file ? text(file, "url") : undefined;
+        text(source, "reply_to_message_id", { optional: true });
+        if (message === undefined && fileUrl === undefined)
+            throw new FakeApiError(400, "invalid_request", "`text` or `file` is required", "text");
+        if (message !== undefined && message.length > MAX_TEXT_LENGTH)
+            throw new FakeApiError(400, "invalid_request", `\`text\` is at most ${MAX_TEXT_LENGTH} characters`, "text");
+        const fingerprint = {
+            to,
+            text: message,
+            file,
+            reply_to_message_id: source["reply_to_message_id"],
+        };
+        const replayed = this.#replay(key, "message", fingerprint);
+        if (replayed)
+            return { answer: replayed };
+        const contact = this.#recipient(to);
+        if (contact.optedOut)
+            throw new FakeApiError(403, "opted_out", "This contact sent STOP and cannot be texted");
+        const messageId = id("msg");
+        this.#remember(messageId, contact.id, fileUrl === undefined ? "text" : "attachment", "sent");
+        const answer = { message_id: messageId, status: "queued" };
+        this.#accept(key, "message", fingerprint, answer);
+        return {
+            answer,
+            send: {
+                messageId,
+                contactId: contact.id,
+                handle: contact.handle,
+                kind: "message",
+                ...(message === undefined ? {} : { text: message }),
+                ...(fileUrl === undefined ? {} : { fileUrl }),
+            },
+        };
+    }
+    sendReaction(targetMessageId, input) {
+        const source = body(input);
+        const key = text(source, "idempotency_key");
+        const reaction = text(source, "reaction");
+        const kind = `reaction:${targetMessageId}`;
+        const replayed = this.#replay(key, kind, { reaction });
+        if (replayed)
+            return { answer: replayed };
+        const target = this.#messages.get(targetMessageId);
+        if (!target)
+            throw new FakeApiError(404, "message_not_found", "Unknown message");
+        if (target.kind === "reaction")
+            throw new FakeApiError(422, "invalid_target", "A reaction cannot be the target of a reaction");
+        const contact = this.#contacts.get(target.contactId);
+        if (contact.optedOut)
+            throw new FakeApiError(403, "opted_out", "This contact sent STOP and cannot be texted");
+        const messageId = id("msg");
+        this.#remember(messageId, contact.id, "reaction", "sent");
+        const answer = { message_id: messageId, status: "queued" };
+        this.#accept(key, kind, { reaction }, answer);
+        return {
+            answer,
+            send: {
+                messageId,
+                contactId: contact.id,
+                handle: contact.handle,
+                kind: "reaction",
+                reaction,
+                targetMessageId,
+            },
+        };
+    }
+    getMessage(messageId) {
+        const message = this.#messages.get(messageId);
+        if (!message)
+            throw new FakeApiError(404, "message_not_found", "Unknown message");
+        return {
+            message_id: message.id,
+            contact_id: message.contactId,
+            status: message.status,
+            reason: null,
+            created_at: message.createdAt,
+        };
+    }
+    getContact(contactId) {
+        const contact = this.#contact(contactId);
+        return {
+            id: contact.id,
+            user: contact.user,
+            handle_kind: contact.handleKind,
+            handle: contact.handle,
+            opted_out: contact.optedOut,
+            number: FAKE_NUMBER,
+            created_at: contact.createdAt,
+        };
+    }
+    setTyping(contactId, input) {
+        this.#contact(contactId);
+        if (typeof body(input)["on"] !== "boolean")
+            throw new FakeApiError(400, "invalid_request", "`on` must be a boolean", "on");
+    }
+    publicNumber() {
+        return FAKE_NUMBER;
+    }
+    signInLink(contactId, input, origin) {
+        const contact = this.#contact(contactId);
+        const source = body(input);
+        const returnTo = text(source, "return_to", { optional: true });
+        if (returnTo !== undefined && !URL.canParse(returnTo))
+            throw new FakeApiError(400, "invalid_request", "`return_to` must be an absolute URL", "return_to");
+        if (contact.user)
+            throw new FakeApiError(409, "already_user", "This contact is a user");
+        if (contact.handleKind === "email")
+            throw new FakeApiError(409, "no_phone", "This contact has an email handle, not a phone number");
+        if (contact.optedOut)
+            throw new FakeApiError(403, "opted_out", "This contact sent STOP and cannot be texted");
+        const token = randomUUID();
+        const expiresAt = new Date(this.#now().getTime() + SIGN_IN_LINK_TTL_MS);
+        this.#links.set(token, { contactId, returnTo, expiresAt });
+        return {
+            url: `${origin}/_fake/sign-in/${token}`,
+            expires_at: expiresAt.toISOString(),
+        };
+    }
+    /** Pressing a fake sign-in link links the contact to a fake user. */
+    consumeSignInLink(token) {
+        const link = this.#links.get(token);
+        if (!link || link.expiresAt < this.#now())
+            throw new FakeApiError(404, "not_found", "Unknown or expired link");
+        this.#links.delete(token);
+        const contact = this.#contact(link.contactId);
+        contact.user ??= { id: `user:fake-${++this.#users}` };
+        return {
+            returnTo: link.returnTo,
+            event: this.#event("contact.user_linked", {
+                contact_id: contact.id,
+                user: contact.user,
+            }),
+        };
+    }
+    // ---- Internals ------------------------------------------------------------
+    #contact(contactId) {
+        const contact = this.#contacts.get(contactId);
+        if (!contact)
+            throw new FakeApiError(404, "contact_not_found", "Unknown contact");
+        return contact;
+    }
+    #recipient(to) {
+        const contactId = to["contact_id"];
+        const userId = to["user_id"];
+        if ((contactId === undefined) === (userId === undefined))
+            throw new FakeApiError(400, "invalid_request", "`to` needs exactly one of `contact_id` or `user_id`", "to");
+        if (typeof contactId === "string")
+            return this.#contact(contactId);
+        if (typeof userId !== "string")
+            throw new FakeApiError(400, "invalid_request", "`to.user_id` must be a string", "to");
+        for (const contact of this.#contacts.values())
+            if (contact.user && bareUser(contact.user.id) === bareUser(userId))
+                return contact;
+        throw new FakeApiError(403, "not_texted_first", "This user has not texted the app");
+    }
+    /** A repeated key returns the first answer; the same key with another body is a conflict. */
+    #replay(key, kind, parts) {
+        const seen = this.#replays.get(key);
+        if (seen === undefined)
+            return undefined;
+        if (seen.fingerprint !== JSON.stringify([kind, parts]))
+            throw new FakeApiError(409, "idempotency_conflict", "This idempotency_key was used with a different request");
+        return seen.answer;
+    }
+    /** Only an accepted send holds its key; a refused one can be retried under the same key. */
+    #accept(key, kind, parts, answer) {
+        this.#replays.set(key, {
+            fingerprint: JSON.stringify([kind, parts]),
+            answer,
+        });
+    }
+    #contactFor(handle) {
+        const existing = this.#byHandle.get(handle);
+        if (existing)
+            return this.#contacts.get(existing);
+        const contact = {
+            id: id("ct"),
+            user: null,
+            handleKind: handle.startsWith("+") ? "phone" : "email",
+            handle,
+            optedOut: false,
+            createdAt: this.#now().toISOString(),
+        };
+        this.#contacts.set(contact.id, contact);
+        this.#byHandle.set(handle, contact.id);
+        return contact;
+    }
+    #remember(messageId, contactId, kind, status) {
+        this.#messages.set(messageId, {
+            id: messageId,
+            contactId,
+            kind,
+            status,
+            createdAt: this.#now().toISOString(),
+        });
+    }
+    /** STOP, START and HELP replies: the only sends that reach an opted-out contact. */
+    #system(contact, reply) {
+        const messageId = id("msg");
+        this.#remember(messageId, contact.id, "text", "sent");
+        return {
+            messageId,
+            contactId: contact.id,
+            handle: contact.handle,
+            kind: "system",
+            text: reply,
+        };
+    }
+    #webhookContact(contact) {
+        return {
+            id: contact.id,
+            user: contact.user,
+            handle_kind: contact.handleKind,
+            handle: contact.handle,
+        };
+    }
+    #event(type, data) {
+        return {
+            id: id("evt"),
+            type,
+            environment: "test",
+            occurred_at: this.#now().toISOString(),
+            data,
+        };
+    }
+}

package/dist/helpers/agent-bridge.d.ts

@@ -0,0 +1,72 @@
+/** What `runs.start` and `runs.message` return for a message: the id `runs.reply` follows. */
+export interface SentRunMessage {
+    run_id: string;
+    message_id: string;
+    sequence_number: number;
+}
+/** The agent's answer to one message (`@north-light/sdk`'s `RunReply`). Consume it once. */
+export interface RunReplyStream {
+    /** The whole reply and how its turn ended (`completed`, `error`, `waiting_on_user` or `settled`). */
+    collect(options?: {
+        onDelta?: (delta: string) => void;
+    }): Promise<{
+        text: string;
+        ended: "completed" | "error" | "waiting_on_user" | "settled";
+    }>;
+    /** The reply text alone. */
+    text(options?: {
+        onDelta?: (delta: string) => void;
+    }): Promise<string>;
+}
+/** The part of the runtime client (`Crouter` from `@north-light/sdk`) this helper uses. */
+export interface RuntimeClient {
+    runs: {
+        start(params: {
+            prompt: string;
+            message?: string;
+            metadata?: Record<string, unknown>;
+        }, options?: {
+            idempotencyKey?: string;
+        }): Promise<{
+            run_id: string;
+            message?: SentRunMessage;
+        }>;
+        message(runId: string, message: string, options?: {
+            idempotencyKey?: string;
+        }): Promise<SentRunMessage>;
+        reply(runId: string, sent: SentRunMessage): RunReplyStream;
+    };
+}
+/** The standing instructions of a run this helper starts. */
+export declare const DEFAULT_RUN_PROMPT = "You are chatting with a person over text message. Reply briefly, in plain text.";
+export type ContinueInRuntimeOptions = ({
+    /** The person's runtime, `https://…`, from their grant. */
+    runtimeUrl: string;
+    /** Your app's token for that runtime, or a function that returns a fresh one for each request. */
+    appToken: string | (() => string | Promise<string>);
+} | {
+    /** A client you already hold, instead of `runtimeUrl` and `appToken`. */
+    client: RuntimeClient;
+}) & {
+    /** What the person said (join a burst with `createBatcher` first). */
+    message: string;
+    /** The run to continue, as returned by an earlier call. Without it a new run starts. */
+    runId?: string;
+    /** Standing instructions when a run starts. Ignored when `runId` is set. */
+    prompt?: string;
+    /** Stored with a run that starts; handy for finding the run again. Ignored when `runId` is set. */
+    metadata?: Record<string, unknown>;
+    /** Makes a retry of this call deliver the message once. Derive it from your own record of the delivery (the webhook event id). */
+    idempotencyKey?: string;
+};
+export interface ContinuedRun {
+    runId: string;
+    /** The agent's reply to this message. Consume it once: `await reply.collect()` or `await reply.text()`. */
+    reply: RunReplyStream;
+}
+/**
+ * Starts a run for the message, or sends it to the run named by `runId`, and returns the
+ * run id with the agent's reply to it. Errors are the runtime client's own (`APIError` and
+ * its subclasses); a retry with the same `idempotencyKey` does not deliver twice.
+ */
+export declare function continueInRuntime(options: ContinueInRuntimeOptions): Promise<ContinuedRun>;

package/dist/helpers/agent-bridge.js

@@ -0,0 +1,48 @@
+// Agent bridge: continue a run in the person's runtime. A run is an agent conversation hosted
+// by the person's runtime; the first text of a contact starts one, later texts continue it.
+// `@north-light/sdk` is an optional peer dependency, loaded only when this helper is called.
+// The types below are the slice of its `runs` resource this helper uses, so this package's own
+// declarations never import it.
+/** The standing instructions of a run this helper starts. */
+export const DEFAULT_RUN_PROMPT = "You are chatting with a person over text message. Reply briefly, in plain text.";
+async function connect(options) {
+    if ("client" in options)
+        return options.client;
+    let module;
+    try {
+        module = await import("@north-light/sdk");
+    }
+    catch (cause) {
+        throw new Error("continueInRuntime needs the optional peer dependency @north-light/sdk; install it with your package manager", { cause });
+    }
+    const { appToken, runtimeUrl } = options;
+    return new module.Crouter(typeof appToken === "string"
+        ? { baseURL: runtimeUrl, token: appToken }
+        : { baseURL: runtimeUrl, tokenSource: async () => appToken() });
+}
+/**
+ * Starts a run for the message, or sends it to the run named by `runId`, and returns the
+ * run id with the agent's reply to it. Errors are the runtime client's own (`APIError` and
+ * its subclasses); a retry with the same `idempotencyKey` does not deliver twice.
+ */
+export async function continueInRuntime(options) {
+    const client = await connect(options);
+    const send = options.idempotencyKey === undefined
+        ? {}
+        : { idempotencyKey: options.idempotencyKey };
+    if (options.runId !== undefined) {
+        const sent = await client.runs.message(options.runId, options.message, send);
+        return { runId: sent.run_id, reply: client.runs.reply(sent.run_id, sent) };
+    }
+    const started = await client.runs.start({
+        prompt: options.prompt ?? DEFAULT_RUN_PROMPT,
+        message: options.message,
+        ...(options.metadata === undefined ? {} : { metadata: options.metadata }),
+    }, send);
+    if (!started.message)
+        throw new Error("The runtime started a run without the first message");
+    return {
+        runId: started.run_id,
+        reply: client.runs.reply(started.run_id, started.message),
+    };
+}

package/dist/helpers/batching.d.ts

@@ -0,0 +1,23 @@
+export interface BatcherOptions<T> {
+    /** Receives a key's items once it has been quiet for `windowMs`. Calls for one key never overlap. */
+    onBatch: (key: string, items: T[]) => void | Promise<void>;
+    /** Receives anything `onBatch` throws; a batch is not retried. */
+    onError: (error: unknown, key: string, items: T[]) => void;
+    /** Quiet time that closes a batch. Default 2000. */
+    windowMs?: number;
+    /** A batch closes this long after its first item even if texts keep arriving. Default 30000. */
+    maxWaitMs?: number;
+}
+export declare const DEFAULT_BATCH_WINDOW_MS = 2000;
+export declare const DEFAULT_BATCH_MAX_WAIT_MS = 30000;
+export declare class Batcher<T> {
+    #private;
+    constructor(options: BatcherOptions<T>);
+    /** Adds an item (key it by contact id) and restarts the key's quiet window. */
+    add(key: string, item: T): void;
+    /** Closes the key's batch now. Resolves when its `onBatch` and any earlier one for the key have finished. */
+    flush(key: string): Promise<void>;
+    /** Closes every open batch now, for a graceful shutdown. */
+    flushAll(): Promise<void>;
+}
+export declare function createBatcher<T>(options: BatcherOptions<T>): Batcher<T>;

package/dist/helpers/batching.js

@@ -0,0 +1,66 @@
+// Batching: texts from one person often arrive as a burst. A batcher holds each key's items
+// until the key has been quiet for `windowMs`, then hands them over together, in order.
+export const DEFAULT_BATCH_WINDOW_MS = 2_000;
+export const DEFAULT_BATCH_MAX_WAIT_MS = 30_000;
+export class Batcher {
+    #options;
+    #windowMs;
+    #maxWaitMs;
+    #pending = new Map();
+    /** The batch currently being handled per key; the next batch for the key waits for it. */
+    #running = new Map();
+    constructor(options) {
+        this.#options = options;
+        this.#windowMs = options.windowMs ?? DEFAULT_BATCH_WINDOW_MS;
+        this.#maxWaitMs = options.maxWaitMs ?? DEFAULT_BATCH_MAX_WAIT_MS;
+        if (!(this.#windowMs > 0) || !(this.#maxWaitMs >= this.#windowMs))
+            throw new RangeError("windowMs must be positive and at most maxWaitMs");
+    }
+    /** Adds an item (key it by contact id) and restarts the key's quiet window. */
+    add(key, item) {
+        const now = Date.now();
+        const existing = this.#pending.get(key);
+        if (existing)
+            clearTimeout(existing.timer);
+        const startedAt = existing?.startedAt ?? now;
+        const wait = Math.min(this.#windowMs, startedAt + this.#maxWaitMs - now);
+        const timer = setTimeout(() => void this.flush(key), Math.max(0, wait));
+        this.#pending.set(key, {
+            items: [...(existing?.items ?? []), item],
+            startedAt,
+            timer,
+        });
+    }
+    /** Closes the key's batch now. Resolves when its `onBatch` and any earlier one for the key have finished. */
+    flush(key) {
+        const pending = this.#pending.get(key);
+        if (pending) {
+            clearTimeout(pending.timer);
+            this.#pending.delete(key);
+        }
+        const previous = this.#running.get(key) ?? Promise.resolve();
+        if (!pending)
+            return previous;
+        const run = previous.then(async () => {
+            try {
+                await this.#options.onBatch(key, pending.items);
+            }
+            catch (error) {
+                this.#options.onError(error, key, pending.items);
+            }
+        });
+        this.#running.set(key, run);
+        void run.then(() => {
+            if (this.#running.get(key) === run)
+                this.#running.delete(key);
+        });
+        return run;
+    }
+    /** Closes every open batch now, for a graceful shutdown. */
+    async flushAll() {
+        await Promise.all([...new Set([...this.#pending.keys(), ...this.#running.keys()])].map((key) => this.flush(key)));
+    }
+}
+export function createBatcher(options) {
+    return new Batcher(options);
+}

package/dist/helpers/format.d.ts

@@ -0,0 +1,38 @@
+import type { MessageReceivedData, SendMessageRequest } from "../types.js";
+/** The send API refuses a longer `text`. */
+export declare const MAX_TEXT_LENGTH = 10000;
+/**
+ * Markdown to the plain text a person should read: emphasis, headings, quotes, code fences and
+ * HTML are dropped, `[label](url)` becomes `label (url)`, images disappear, lists keep their
+ * `-` and `1.` markers and table rows become `a | b`. Text inside code stays exactly as written.
+ */
+export declare function toPlainText(markdown: string): string;
+/**
+ * Splits a long text into parts of at most `maxLength` characters, preferring to break at a
+ * blank line, then a line, then a space. Each part is sent as its own message, in order.
+ */
+export declare function splitText(text: string, maxLength?: number): string[];
+/** An agent's markdown reply as the texts to send, in order. Empty markdown gives no texts. */
+export declare function formatReply(markdown: string): string[];
+/** The six iMessage tapbacks by name. */
+export declare const TAPBACKS: {
+    readonly love: "❤️";
+    readonly like: "👍";
+    readonly dislike: "👎";
+    readonly laugh: "😂";
+    readonly emphasize: "‼️";
+    readonly question: "❓";
+};
+export type TapbackName = keyof typeof TAPBACKS;
+/** The tapback name for an emoji (`❤️` → `love`), or `null` when it is not a tapback. */
+export declare function tapbackName(emoji: string): TapbackName | null;
+/** The emoji to send as a reaction, from a tapback name (`love`) or an emoji. Throws for anything else. */
+export declare function tapbackEmoji(nameOrEmoji: string): string;
+/** What to add to a send so it threads under the message that was received. */
+export declare function replyTo(received: Pick<MessageReceivedData, "message_id">): Pick<SendMessageRequest, "reply_to_message_id">;
+/**
+ * A received message as one line of text an agent can read: text as written, a reaction as
+ * `[reacted love to message <id>]`, an attachment as `[attachment: name (mime)]` followed by
+ * its caption, and a threaded message prefixed with `[replying to message <id>] `.
+ */
+export declare function describeReceived(received: Pick<MessageReceivedData, "content" | "reply_to_message_id">): string;