@north-light/comms 0.0.0-stage → 0.1.0

package/dist/fake/cli.js

@@ -0,0 +1,107 @@
+// `comms fake` and `comms fake send`. `run` takes its arguments and output as parameters so
+// tests can drive it; bin/comms.js passes the process's.
+import { parseArgs } from "node:util";
+import { DEFAULT_FAKE_PORT, startFakeServer, } from "./server.js";
+const USAGE = `Usage:
+  comms fake --webhook <url> [--port ${DEFAULT_FAKE_PORT}] [--secret whsec_…]
+      Start a local Comms. Point CommsClient's baseUrl at it (any bearer token works) and
+      receive signed webhooks at <url>. Sends and reactions are logged here, never delivered.
+  comms fake send --from <+1555…> --text <text> [--user-id <id>] [--port ${DEFAULT_FAKE_PORT}]
+      Simulate a person texting your app. STOP, START and HELP work as they do in production.
+`;
+export class UsageError extends Error {
+    name = "UsageError";
+}
+function port(value) {
+    const parsed = value === undefined ? DEFAULT_FAKE_PORT : Number(value);
+    if (!Number.isInteger(parsed) || parsed < 0 || parsed > 65_535)
+        throw new UsageError(`--port must be a port number, got "${value}"`);
+    return parsed;
+}
+/**
+ * Runs the CLI. `comms fake` resolves with the running server (the caller keeps the process
+ * alive); `comms fake send` resolves with `undefined` once the fake has answered.
+ */
+export async function run(argv, io) {
+    const [command, subcommand, ...rest] = argv;
+    if (command === undefined || command === "-h" || command === "--help") {
+        io.out(USAGE);
+        return undefined;
+    }
+    if (command !== "fake")
+        throw new UsageError(`Unknown command "${command}"\n\n${USAGE}`);
+    if (subcommand === "send") {
+        const { values } = parseArgs({
+            args: rest,
+            options: {
+                from: { type: "string" },
+                text: { type: "string" },
+                "user-id": { type: "string" },
+                port: { type: "string" },
+            },
+            strict: true,
+        });
+        if (!values.from || values.text === undefined)
+            throw new UsageError(`\`comms fake send\` needs --from and --text\n\n${USAGE}`);
+        const target = `http://127.0.0.1:${port(values.port)}`;
+        let response;
+        try {
+            response = await fetch(`${target}/_fake/inbound`, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({
+                    from: values.from,
+                    text: values.text,
+                    ...(values["user-id"] ? { user_id: values["user-id"] } : {}),
+                }),
+            });
+        }
+        catch (cause) {
+            throw new UsageError(`No fake Comms answered at ${target}. Start one with \`comms fake --webhook <url>\`.`, { cause });
+        }
+        const text = await response.text();
+        if (!response.ok)
+            throw new UsageError(`The fake refused the text: ${text}`);
+        io.out(text);
+        return undefined;
+    }
+    if (subcommand !== undefined && !subcommand.startsWith("-"))
+        throw new UsageError(`Unknown command "fake ${subcommand}"\n\n${USAGE}`);
+    const args = subcommand === undefined ? [] : [subcommand, ...rest];
+    const { values } = parseArgs({
+        args,
+        options: {
+            webhook: { type: "string" },
+            port: { type: "string" },
+            secret: { type: "string" },
+            help: { type: "boolean", short: "h" },
+        },
+        strict: true,
+    });
+    if (values.help) {
+        io.out(USAGE);
+        return undefined;
+    }
+    if (!values.webhook)
+        throw new UsageError(`\`comms fake\` needs --webhook <url>\n\n${USAGE}`);
+    let server;
+    try {
+        server = await startFakeServer({
+            webhookUrl: values.webhook,
+            port: port(values.port),
+            log: io.out,
+            ...(values.secret === undefined ? {} : { secret: values.secret }),
+        });
+    }
+    catch (cause) {
+        if (cause instanceof UsageError)
+            throw cause;
+        throw new UsageError(`Could not start the fake: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+    }
+    io.out(`Fake Comms listening on ${server.url}`);
+    io.out(`  CommsClient baseUrl: ${server.url} (any bearer token works)`);
+    io.out(`  Webhooks go to:      ${values.webhook}`);
+    io.out(`  Signing secret:      ${server.secret}`);
+    io.out(`  Simulate a text:     comms fake send --from +15550001 --text "hi" --port ${server.port}`);
+    return server;
+}

package/dist/fake/server.d.ts

@@ -0,0 +1,33 @@
+import type { WebhookEvent } from "../types.js";
+import { type FakeStoreOptions } from "./store.js";
+export declare const DEFAULT_FAKE_PORT = 7481;
+export interface FakeServerOptions {
+    /** Every webhook is POSTed here. */
+    webhookUrl: string;
+    /** The `whsec_…` signing secret. Default: a fresh random one. */
+    secret?: string;
+    /** Default 7481; `0` picks a free port. */
+    port?: number;
+    /** Default `127.0.0.1`: the fake is for the developer's own machine. */
+    host?: string;
+    /** Where log lines go. Default `console.log`. */
+    log?: (line: string) => void;
+    store?: FakeStoreOptions;
+}
+export interface FakeServer {
+    /** `http://127.0.0.1:<port>`: the `baseUrl` for `CommsClient`. */
+    url: string;
+    port: number;
+    secret: string;
+    close(): Promise<void>;
+}
+/** What happened to one webhook the fake tried to deliver. */
+export interface Delivery {
+    event_id: string;
+    type: WebhookEvent["type"];
+    /** The HTTP status the app answered, or `null` when the request failed. */
+    status: number | null;
+    error?: string;
+}
+export declare function newFakeSecret(): string;
+export declare function startFakeServer(options: FakeServerOptions): Promise<FakeServer>;

package/dist/fake/server.js

@@ -0,0 +1,213 @@
+// The local fake Comms: the send API's paths and bodies over HTTP, plus a control endpoint that
+// simulates a person texting the app. Webhooks are signed with the shared `sign`, so they are
+// byte-for-byte what a real delivery looks like. The only outbound request this server ever
+// makes is the POST to the webhook URL given at start.
+import { randomBytes, randomUUID } from "node:crypto";
+import { createServer, } from "node:http";
+import { sign } from "../webhooks.js";
+import { FakeApiError, FakeStore, } from "./store.js";
+export const DEFAULT_FAKE_PORT = 7481;
+const MAX_BODY_BYTES = 1024 * 1024;
+const WEBHOOK_TIMEOUT_MS = 15_000;
+export function newFakeSecret() {
+    return `whsec_${randomBytes(32).toString("base64")}`;
+}
+export async function startFakeServer(options) {
+    const webhook = new URL(options.webhookUrl);
+    if (webhook.protocol !== "http:" && webhook.protocol !== "https:")
+        throw new TypeError("The webhook URL must be http or https");
+    const secret = options.secret ?? newFakeSecret();
+    sign(secret, "check", 0, ""); // refuses a malformed secret before listening
+    const log = options.log ?? ((line) => console.log(line));
+    const store = new FakeStore(options.store);
+    let origin = "";
+    const logSend = (send) => {
+        const target = `${send.handle} (${send.contactId})`;
+        if (send.kind === "reaction")
+            log(`→ reaction ${send.reaction} on ${send.targetMessageId} to ${target} [${send.messageId}]`);
+        else
+            log(`→ ${send.kind === "system" ? "system text" : "text"} to ${target} [${send.messageId}]: ${send.text ?? ""}${send.fileUrl ? ` (file ${send.fileUrl})` : ""}`);
+    };
+    const deliver = async (event) => {
+        const body = JSON.stringify(event);
+        const timestamp = Math.floor(Date.now() / 1000);
+        const delivery = {
+            event_id: event.id,
+            type: event.type,
+            status: null,
+        };
+        try {
+            const response = await fetch(webhook, {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    "webhook-id": event.id,
+                    "webhook-timestamp": String(timestamp),
+                    "webhook-signature": sign(secret, event.id, timestamp, body),
+                },
+                body,
+                redirect: "manual",
+                signal: AbortSignal.timeout(WEBHOOK_TIMEOUT_MS),
+            });
+            await response.body?.cancel();
+            delivery.status = response.status;
+            log(`⇢ webhook ${event.type} ${event.id} → ${webhook.href}: ${response.status}`);
+        }
+        catch (error) {
+            delivery.error = error instanceof Error ? error.message : String(error);
+            log(`⇢ webhook ${event.type} ${event.id} → ${webhook.href}: failed (${delivery.error})`);
+        }
+        return delivery;
+    };
+    const route = async (request, response) => {
+        const url = new URL(request.url ?? "/", "http://fake");
+        const path = url.pathname;
+        const method = request.method ?? "GET";
+        const send = (status, payload) => {
+            if (payload === undefined)
+                response.writeHead(status).end();
+            else
+                response
+                    .writeHead(status, { "content-type": "application/json" })
+                    .end(JSON.stringify(payload));
+        };
+        if (method === "GET" && path.startsWith("/_fake/sign-in/")) {
+            const { event, returnTo } = store.consumeSignInLink(decodeURIComponent(path.slice("/_fake/sign-in/".length)));
+            log("← sign-in link pressed (fake)");
+            await deliver(event);
+            if (returnTo)
+                response.writeHead(303, { location: returnTo }).end();
+            else
+                response
+                    .writeHead(200, { "content-type": "text/plain" })
+                    .end("Signed in (fake). You can close this page.");
+            return;
+        }
+        const input = method === "POST" ? await readJson(request) : undefined;
+        if (method === "POST" && path === "/_fake/inbound") {
+            const result = store.inbound(input);
+            const source = input;
+            log(`← inbound from ${source.from} (${result.contactId}) [${result.messageId}]: ${source.text}`);
+            for (const logged of result.sends)
+                logSend(logged);
+            const deliveries = [];
+            for (const event of result.events)
+                deliveries.push(await deliver(event));
+            send(200, {
+                message_id: result.messageId,
+                contact_id: result.contactId,
+                disposition: result.disposition,
+                deliveries,
+            });
+            return;
+        }
+        if (path.startsWith("/v1/")) {
+            if (!/^Bearer \S+$/.test(request.headers.authorization ?? ""))
+                throw new FakeApiError(401, "unauthorized", "Send `Authorization: Bearer <any token>`");
+            const segments = path.slice(1).split("/").map(decodeURIComponent);
+            const [, resource, resourceId, action] = segments;
+            if (method === "POST" && path === "/v1/messages") {
+                const sent = store.sendMessage(input);
+                if (sent.send)
+                    logSend(sent.send);
+                return send(202, sent.answer);
+            }
+            if (method === "POST" &&
+                resource === "messages" &&
+                resourceId &&
+                action === "reactions" &&
+                segments.length === 4) {
+                const sent = store.sendReaction(resourceId, input);
+                if (sent.send)
+                    logSend(sent.send);
+                return send(202, sent.answer);
+            }
+            if (method === "GET" &&
+                resource === "messages" &&
+                resourceId &&
+                segments.length === 3)
+                return send(200, store.getMessage(resourceId));
+            if (method === "GET" &&
+                resource === "contacts" &&
+                resourceId &&
+                segments.length === 3)
+                return send(200, store.getContact(resourceId));
+            if (method === "POST" &&
+                resource === "contacts" &&
+                resourceId &&
+                action === "typing" &&
+                segments.length === 4) {
+                store.setTyping(resourceId, input);
+                return send(204);
+            }
+            if (method === "POST" &&
+                resource === "contacts" &&
+                resourceId &&
+                action === "sign-in-link" &&
+                segments.length === 4)
+                return send(201, store.signInLink(resourceId, input, origin));
+            if (method === "GET" && path === "/v1/numbers/public")
+                return send(200, { number: store.publicNumber() });
+        }
+        throw new FakeApiError(404, "not_found", `No route for ${method} ${path}`);
+    };
+    const server = createServer((request, response) => {
+        route(request, response).catch((error) => {
+            const failure = error instanceof FakeApiError
+                ? error
+                : new FakeApiError(500, "server_error", error instanceof Error ? error.message : String(error));
+            if (response.headersSent) {
+                response.end();
+                return;
+            }
+            response
+                .writeHead(failure.status, { "content-type": "application/json" })
+                .end(JSON.stringify({
+                error: {
+                    code: failure.code,
+                    message: failure.message,
+                    ...(failure.param ? { param: failure.param } : {}),
+                    origin: "comms",
+                    retryable: failure.status >= 500,
+                    request_id: randomUUID(),
+                },
+            }));
+        });
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(options.port ?? DEFAULT_FAKE_PORT, options.host ?? "127.0.0.1", () => {
+            server.off("error", reject);
+            resolve();
+        });
+    });
+    const address = server.address();
+    origin = `http://${address.family === "IPv6" ? `[${address.address}]` : address.address}:${address.port}`;
+    return {
+        url: origin,
+        port: address.port,
+        secret,
+        close: () => new Promise((resolve, reject) => {
+            server.close((error) => (error ? reject(error) : resolve()));
+            server.closeAllConnections();
+        }),
+    };
+}
+async function readJson(request) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of request) {
+        size += chunk.length;
+        if (size > MAX_BODY_BYTES)
+            throw new FakeApiError(413, "invalid_request", "The request body is too large");
+        chunks.push(chunk);
+    }
+    if (size === 0)
+        return undefined;
+    try {
+        return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+    }
+    catch {
+        throw new FakeApiError(400, "invalid_request", "The request body is not valid JSON");
+    }
+}

package/dist/fake/store.d.ts

@@ -0,0 +1,59 @@
+import type { Contact, MessageRecord, QueuedMessage, SignInLink, WebhookEvent } from "../types.js";
+/** The fictional app number every fake contact texts. */
+export declare const FAKE_NUMBER = "+15555550100";
+/** A refusal the server answers in the shared error envelope. */
+export declare class FakeApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly param?: string | undefined;
+    readonly name = "FakeApiError";
+    constructor(status: number, code: string, message: string, param?: string | undefined);
+}
+/** Something the fake "sent": logged by the server, never delivered. */
+export interface LoggedSend {
+    messageId: string;
+    contactId: string;
+    handle: string;
+    kind: "message" | "reaction" | "system";
+    text?: string;
+    fileUrl?: string;
+    reaction?: string;
+    targetMessageId?: string;
+}
+export interface InboundResult {
+    disposition: "forwarded" | "stop" | "start" | "help" | "opted_out_ignored";
+    messageId: string;
+    contactId: string;
+    events: WebhookEvent[];
+    sends: LoggedSend[];
+}
+export interface FakeStoreOptions {
+    /** The display name in STOP and START replies. */
+    displayName?: string;
+    helpText?: string;
+    now?: () => Date;
+}
+export declare class FakeStore {
+    #private;
+    constructor(options?: FakeStoreOptions);
+    /** A person texts the app's fictional number. `userId` makes the contact a Northlight user. */
+    inbound(input: unknown): InboundResult;
+    sendMessage(input: unknown): {
+        answer: QueuedMessage;
+        send?: LoggedSend;
+    };
+    sendReaction(targetMessageId: string, input: unknown): {
+        answer: QueuedMessage;
+        send?: LoggedSend;
+    };
+    getMessage(messageId: string): MessageRecord;
+    getContact(contactId: string): Contact;
+    setTyping(contactId: string, input: unknown): void;
+    publicNumber(): string;
+    signInLink(contactId: string, input: unknown, origin: string): SignInLink;
+    /** Pressing a fake sign-in link links the contact to a fake user. */
+    consumeSignInLink(token: string): {
+        event: WebhookEvent;
+        returnTo: string | undefined;
+    };
+}