@ithousecall/chat 0.0.0-stage → 0.2.1

package/dist/chat/teams.d.ts

@@ -0,0 +1,75 @@
+import type { Hono } from "hono";
+import { type AdapterHandlers, type ApprovalDecision, type ApprovalOutcome, type ApprovalPrompt, type Attachment, type ChatAdapter, type ChatUser, type InboundMessage, type MessageRef, type ThreadRef } from "./adapter.ts";
+/** The fields housecall reads from a Teams message activity. */
+type TeamsMessage = {
+    id: string;
+    serviceUrl?: string | undefined;
+    text?: string | undefined;
+    from: {
+        id: string;
+        name?: string | undefined;
+    };
+    recipient: {
+        id: string;
+    };
+    conversation: {
+        id: string;
+        conversationType?: string | undefined;
+    };
+    entities?: readonly {
+        type: string;
+        mentioned?: {
+            id: string;
+        } | undefined;
+        text?: string | null | undefined;
+    }[] | undefined;
+    attachments?: readonly {
+        contentType: string;
+        contentUrl?: string | undefined;
+        content?: unknown;
+        name?: string | undefined;
+    }[] | undefined;
+};
+/** The fields housecall reads from an Adaptive Card `Action.Execute` invoke. */
+type TeamsCardAction = {
+    from: {
+        id: string;
+        name?: string | undefined;
+    };
+    value: {
+        action: {
+            verb?: string | undefined;
+            data: unknown;
+        };
+    };
+};
+export declare function normalizeTeamsMessage(activity: TeamsMessage): InboundMessage;
+export declare function normalizeTeamsCardAction(activity: TeamsCardAction): ApprovalDecision | undefined;
+type TeamsCredentials = {
+    clientId: string;
+    clientSecret: string;
+    tenantId: string;
+};
+/**
+ * Microsoft Teams through an Azure Bot; Teams posts to `/api/messages`. Replies go through the default
+ * Bot Framework service URL. Teams offers no thread history without Microsoft Graph, so only mentions are seen.
+ */
+export declare class TeamsAdapter implements ChatAdapter {
+    #private;
+    readonly platform = "teams";
+    readonly maxMessageLength = 20000;
+    constructor(http: Hono, credentials: TeamsCredentials, options?: {
+        allowUnauthenticated?: boolean;
+    });
+    start(handlers: AdapterHandlers): Promise<void>;
+    stop(): Promise<void>;
+    post(thread: ThreadRef, markdown: string): Promise<MessageRef>;
+    update(ref: MessageRef, markdown: string): Promise<void>;
+    remove(ref: MessageRef): Promise<void>;
+    postApproval(thread: ThreadRef, prompt: ApprovalPrompt): Promise<MessageRef>;
+    resolveApprovalMessage(ref: MessageRef, prompt: ApprovalPrompt, outcome: ApprovalOutcome, by?: ChatUser): Promise<void>;
+    /** Attachments other than SharePoint uploads are under their activity's service URL, so they get the bot's token. */
+    download(attachment: Attachment, signal: AbortSignal): Promise<Uint8Array>;
+    fetchThread(): Promise<InboundMessage[]>;
+}
+export {};

package/dist/chat/teams.js

@@ -0,0 +1,202 @@
+import { App } from "@microsoft/teams.apps";
+import { z } from "zod";
+import { approvalArgs, decisionText, messageRef, } from "./adapter.js";
+import { fetchCapped } from "./download.js";
+const FILE_DOWNLOAD_INFO = "application/vnd.microsoft.teams.file.download.info";
+const SHAREPOINT = ".sharepoint.com";
+const FileDownloadInfo = z.object({
+    downloadUrl: z.url({ protocol: /^https$/, hostname: /\.sharepoint\.com$/ }),
+    fileType: z.string().optional(),
+});
+/**
+ * Pasted images are `image/*` attachments under the activity's service URL, read with the bot's token. Files uploaded
+ * in a personal chat carry a pre-authorized SharePoint download URL, read without a token. Files in channels and group
+ * chats need Microsoft Graph and are left out.
+ */
+function teamsAttachments(activity) {
+    let pasted = 0;
+    return (activity.attachments ?? []).flatMap((attachment) => {
+        if (attachment.contentType === FILE_DOWNLOAD_INFO) {
+            const info = FileDownloadInfo.safeParse(attachment.content);
+            if (!info.success)
+                return [];
+            const name = attachment.name ?? "file";
+            const type = info.data.fileType ?? name.split(".").at(-1) ?? "";
+            return [
+                {
+                    name,
+                    mimeType: /^(png|jpe?g|gif|webp)$/i.test(type) ? "image/*" : "application/octet-stream",
+                    source: info.data.downloadUrl,
+                },
+            ];
+        }
+        const url = attachment.contentUrl;
+        if (!attachment.contentType.startsWith("image/") ||
+            url === undefined ||
+            !underServiceUrl(url, activity.serviceUrl)) {
+            return [];
+        }
+        pasted++;
+        return [{ name: attachment.name ?? `image-${pasted}`, mimeType: attachment.contentType, source: url }];
+    });
+}
+function underServiceUrl(url, serviceUrl) {
+    if (serviceUrl === undefined || !URL.canParse(url) || !URL.canParse(serviceUrl))
+        return false;
+    const target = new URL(url);
+    const base = new URL(serviceUrl);
+    const path = base.pathname.endsWith("/") ? base.pathname : `${base.pathname}/`;
+    return target.protocol === "https:" && target.origin === base.origin && target.pathname.startsWith(path);
+}
+const VERB = "housecall_approval";
+const ActionData = z.object({ approvalId: z.string(), decision: z.enum(["approve", "deny"]) });
+function teamsUser(account) {
+    return account.name === undefined ? { id: account.id } : { id: account.id, name: account.name };
+}
+export function normalizeTeamsMessage(activity) {
+    const botMentions = (activity.entities ?? []).filter((entity) => entity.type === "mention" && entity.mentioned?.id === activity.recipient.id);
+    let text = activity.text ?? "";
+    for (const mention of botMentions)
+        if (mention.text)
+            text = text.replaceAll(mention.text, "");
+    const [spaceId = activity.conversation.id] = activity.conversation.id.split(";");
+    const isChannel = activity.conversation.conversationType === "channel";
+    return {
+        platform: "teams",
+        spaceId,
+        threadId: isChannel && !activity.conversation.id.includes(";messageid=")
+            ? `${activity.conversation.id};messageid=${activity.id}`
+            : activity.conversation.id,
+        messageId: activity.id,
+        user: teamsUser(activity.from),
+        text: text.trim(),
+        attachments: teamsAttachments(activity),
+        isDirect: activity.conversation.conversationType === "personal",
+        mentionsBot: botMentions.length > 0,
+        cursor: activity.id,
+    };
+}
+export function normalizeTeamsCardAction(activity) {
+    if (activity.value.action.verb !== VERB)
+        return undefined;
+    const data = ActionData.safeParse(activity.value.action.data);
+    return data.success ? { ...data.data, user: teamsUser(activity.from) } : undefined;
+}
+function approvalCard(prompt) {
+    const action = (title, decision) => ({
+        type: "Action.Execute",
+        title,
+        verb: VERB,
+        data: { approvalId: prompt.approvalId, decision },
+    });
+    return {
+        type: "AdaptiveCard",
+        version: "1.5",
+        body: [
+            { type: "TextBlock", text: "Approval needed", weight: "Bolder", size: "Medium" },
+            { type: "TextBlock", text: prompt.summary, wrap: true },
+            {
+                type: "TextBlock",
+                text: `${prompt.tool} ${approvalArgs(prompt)}`,
+                wrap: true,
+                isSubtle: true,
+                fontType: "Monospace",
+            },
+            {
+                type: "TextBlock",
+                text: `Only ${prompt.requester.name ?? prompt.requester.id} can approve or deny.`,
+                wrap: true,
+                isSubtle: true,
+            },
+        ],
+        actions: [action("Approve", "approve"), action("Deny", "deny")],
+    };
+}
+/** Lets the Teams SDK serve `/api/messages` on housecall's own HTTP server; the SDK still validates every token. */
+class HonoRoutes {
+    #http;
+    constructor(http) {
+        this.#http = http;
+    }
+    registerRoute(_method, path, handler) {
+        this.#http.post(path, async (c) => {
+            const body = await c.req.json().catch(() => undefined);
+            const response = await handler({ body, headers: Object.fromEntries(c.req.raw.headers) });
+            return response.body === undefined
+                ? new Response(null, { status: response.status })
+                : Response.json(response.body, { status: response.status });
+        });
+    }
+}
+/**
+ * Microsoft Teams through an Azure Bot; Teams posts to `/api/messages`. Replies go through the default
+ * Bot Framework service URL. Teams offers no thread history without Microsoft Graph, so only mentions are seen.
+ */
+export class TeamsAdapter {
+    platform = "teams";
+    maxMessageLength = 20_000;
+    #app;
+    constructor(http, credentials, options = {}) {
+        this.#app = new App({
+            ...credentials,
+            httpServerAdapter: new HonoRoutes(http),
+            dangerouslyAllowUnauthenticatedRequests: options.allowUnauthenticated === true,
+            activity: { mentions: { stripText: false } },
+        });
+    }
+    async start(handlers) {
+        this.#app.on("message", async ({ activity }) => {
+            void handlers.onMessage(normalizeTeamsMessage(activity));
+        });
+        this.#app.on("card.action", async ({ activity }) => {
+            const decision = normalizeTeamsCardAction(activity);
+            const feedback = decision === undefined ? undefined : await handlers.onApproval(decision);
+            return {
+                statusCode: 200,
+                type: "application/vnd.microsoft.activity.message",
+                value: feedback?.text ?? "This button is not one of @housecall's.",
+            };
+        });
+        await this.#app.initialize();
+    }
+    async stop() { }
+    async #send(conversationId, activity) {
+        return (await this.#app.send(conversationId, activity)).id;
+    }
+    async post(thread, markdown) {
+        return messageRef(thread, await this.#send(thread.threadId, { type: "message", text: markdown, textFormat: "markdown" }));
+    }
+    async update(ref, markdown) {
+        await this.#send(ref.threadId, { type: "message", id: ref.messageId, text: markdown, textFormat: "markdown" });
+    }
+    async remove(ref) {
+        await this.#app.api.conversations.activities(ref.threadId).delete(ref.messageId);
+    }
+    async postApproval(thread, prompt) {
+        const activity = {
+            type: "message",
+            attachments: [{ contentType: "application/vnd.microsoft.card.adaptive", content: approvalCard(prompt) }],
+        };
+        return messageRef(thread, await this.#send(thread.threadId, activity));
+    }
+    async resolveApprovalMessage(ref, prompt, outcome, by) {
+        await this.#send(ref.threadId, {
+            type: "message",
+            id: ref.messageId,
+            text: decisionText(prompt, outcome, by),
+            attachments: [],
+        });
+    }
+    /** Attachments other than SharePoint uploads are under their activity's service URL, so they get the bot's token. */
+    async download(attachment, signal) {
+        if (new URL(attachment.source).hostname.endsWith(SHAREPOINT))
+            return fetchCapped(attachment.source, { signal });
+        const token = await this.#app.tokenProvider.getAppToken();
+        if (token === null)
+            throw new Error("Teams gave no bot token");
+        return fetchCapped(attachment.source, { headers: { authorization: `Bearer ${token.toString()}` }, signal });
+    }
+    async fetchThread() {
+        return [];
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,79 @@
+import { z } from "zod";
+declare const ConfigSchema: z.ZodObject<{
+    model: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        provider: z.ZodLiteral<"openai_compatible">;
+        base_url: z.ZodURL;
+        id: z.ZodString;
+        context_window: z.ZodDefault<z.ZodNumber>;
+        max_tokens: z.ZodDefault<z.ZodNumber>;
+        reasoning: z.ZodDefault<z.ZodBoolean>;
+        images: z.ZodDefault<z.ZodBoolean>;
+        api_key_env: z.ZodDefault<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        provider: z.ZodLiteral<"openai">;
+        id: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        provider: z.ZodLiteral<"anthropic">;
+        id: z.ZodString;
+    }, z.core.$strict>], "provider">;
+    chat: z.ZodDefault<z.ZodObject<{
+        slack: z.ZodDefault<z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strict>>;
+        teams: z.ZodDefault<z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strict>>;
+        googlechat: z.ZodDefault<z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodBoolean>;
+            endpoint_url: z.ZodOptional<z.ZodURL>;
+            project_number: z.ZodOptional<z.ZodCoercedString<unknown>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    http: z.ZodDefault<z.ZodObject<{
+        port: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>>;
+    docs: z.ZodDefault<z.ZodObject<{
+        sync_interval_minutes: z.ZodDefault<z.ZodNumber>;
+        sources: z.ZodDefault<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"local">;
+            name: z.ZodString;
+            path: z.ZodString;
+            url_base: z.ZodOptional<z.ZodURL>;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"google_drive">;
+            name: z.ZodString;
+            folder_id: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"confluence">;
+            name: z.ZodString;
+            site: z.ZodURL;
+            space_key: z.ZodOptional<z.ZodString>;
+            parent_page_id: z.ZodOptional<z.ZodCoercedString<unknown>>;
+        }, z.core.$strict>], "type">>>;
+    }, z.core.$strict>>;
+    mcp: z.ZodDefault<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+        name: z.ZodString;
+        command: z.ZodString;
+        args: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        env: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+        read_only: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>, z.ZodObject<{
+        name: z.ZodString;
+        url: z.ZodURL;
+        headers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+        read_only: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>]>>>;
+    approvals: z.ZodDefault<z.ZodObject<{
+        timeout_minutes: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>>;
+    system_prompt: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type Config = z.infer<typeof ConfigSchema>;
+export type ModelConfig = Config["model"];
+export type DocsSourceConfig = Config["docs"]["sources"][number];
+export type McpServerConfig = Config["mcp"][number];
+export declare class ConfigError extends Error {
+}
+export declare function parseConfig(text: string, env?: NodeJS.ProcessEnv): Config;
+export declare function loadConfig(path: string): Config;
+export {};

package/dist/config.js

@@ -0,0 +1,155 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { parse } from "yaml";
+import { z } from "zod";
+const Name = z.string().regex(/^[a-z0-9_-]+$/, "use lowercase letters, digits, _ or -");
+const McpName = Name.refine((name) => !name.includes("__"), "must not contain __ (tools are named mcp__<name>__<tool>)");
+const ModelSchema = z.discriminatedUnion("provider", [
+    z.strictObject({
+        provider: z.literal("openai_compatible"),
+        base_url: z.url(),
+        id: z.string().min(1),
+        context_window: z.number().int().positive().default(128_000),
+        max_tokens: z.number().int().positive().default(16_384),
+        reasoning: z.boolean().default(false),
+        images: z.boolean().default(true),
+        api_key_env: z.string().min(1).default("LLM_API_KEY"),
+    }),
+    z.strictObject({ provider: z.literal("openai"), id: z.string().min(1) }),
+    z.strictObject({ provider: z.literal("anthropic"), id: z.string().min(1) }),
+]);
+const Platform = z.strictObject({ enabled: z.boolean().default(false) });
+const DocsSourceSchema = z.discriminatedUnion("type", [
+    z.strictObject({
+        type: z.literal("local"),
+        name: Name,
+        path: z.string().min(1),
+        url_base: z.url().optional(),
+    }),
+    z.strictObject({
+        type: z.literal("google_drive"),
+        name: Name,
+        folder_id: z.string().regex(/^[A-Za-z0-9_-]+$/, "a Drive folder ID, from the folder's URL"),
+    }),
+    z
+        .strictObject({
+        type: z.literal("confluence"),
+        name: Name,
+        site: z.url(),
+        space_key: z
+            .string()
+            .regex(/^~?[A-Za-z0-9]+$/, "a space key, like IT")
+            .optional(),
+        parent_page_id: z.coerce.string().regex(/^\d+$/, "a page ID: the number in the page URL").optional(),
+    })
+        .refine((source) => source.space_key !== undefined || source.parent_page_id !== undefined, {
+        message: "set space_key, parent_page_id, or both",
+    }),
+]);
+const McpSchema = z.union([
+    z.strictObject({
+        name: McpName,
+        command: z.string().min(1),
+        args: z.array(z.string()).default([]),
+        env: z.record(z.string(), z.string()).default({}),
+        read_only: z.array(z.string()).default([]),
+    }),
+    z.strictObject({
+        name: McpName,
+        url: z.url(),
+        headers: z.record(z.string(), z.string()).default({}),
+        read_only: z.array(z.string()).default([]),
+    }),
+]);
+const ConfigSchema = z.strictObject({
+    model: ModelSchema,
+    chat: z
+        .strictObject({
+        slack: Platform.default({ enabled: false }),
+        teams: Platform.default({ enabled: false }),
+        googlechat: z
+            .strictObject({
+            enabled: z.boolean().default(false),
+            endpoint_url: z.url().optional(),
+            project_number: z.coerce
+                .string()
+                .regex(/^\d+$/, "the Google Cloud project number, from the project's dashboard")
+                .optional(),
+        })
+            .refine((chat) => !chat.enabled || (chat.endpoint_url !== undefined && chat.project_number !== undefined), {
+            message: "endpoint_url and project_number are required when googlechat is enabled",
+        })
+            .default({ enabled: false }),
+    })
+        .default({ slack: { enabled: false }, teams: { enabled: false }, googlechat: { enabled: false } }),
+    http: z.strictObject({ port: z.number().int().positive().default(3978) }).default({ port: 3978 }),
+    docs: z
+        .strictObject({
+        sync_interval_minutes: z.number().positive().default(30),
+        sources: z.array(DocsSourceSchema).default([]),
+    })
+        .refine((docs) => new Set(docs.sources.map((source) => source.name)).size === docs.sources.length, {
+        message: "docs source names must be unique",
+    })
+        .default({ sync_interval_minutes: 30, sources: [] }),
+    mcp: z
+        .array(McpSchema)
+        .refine((servers) => new Set(servers.map((server) => server.name)).size === servers.length, {
+        message: "mcp server names must be unique",
+    })
+        .default([]),
+    approvals: z.strictObject({ timeout_minutes: z.number().positive().default(60) }).default({ timeout_minutes: 60 }),
+    system_prompt: z.string().optional(),
+});
+export class ConfigError extends Error {
+}
+function substitute(value, env, path, missing) {
+    if (typeof value === "string") {
+        return value.replaceAll(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_match, name) => {
+            const found = env[name];
+            if (found === undefined) {
+                missing.push(`${path}: environment variable ${name} is not set`);
+                return "";
+            }
+            return found;
+        });
+    }
+    if (Array.isArray(value)) {
+        return value.map((item, index) => substitute(item, env, `${path}.${index}`, missing));
+    }
+    if (value !== null && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [
+            key,
+            substitute(item, env, path === "" ? key : `${path}.${key}`, missing),
+        ]));
+    }
+    return value;
+}
+export function parseConfig(text, env = process.env) {
+    const missing = [];
+    const raw = substitute(parse(text), env, "", missing);
+    if (missing.length > 0)
+        throw new ConfigError(missing.join("\n"));
+    const result = ConfigSchema.safeParse(raw);
+    if (!result.success) {
+        throw new ConfigError(result.error.issues.map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`).join("\n"));
+    }
+    const config = result.data;
+    return {
+        ...config,
+        docs: {
+            ...config.docs,
+            sources: config.docs.sources.map((source) => source.type === "local" ? { ...source, path: resolve(source.path) } : source),
+        },
+    };
+}
+export function loadConfig(path) {
+    let text;
+    try {
+        text = readFileSync(path, "utf8");
+    }
+    catch {
+        throw new ConfigError(`${path}: not found`);
+    }
+    return parseConfig(text);
+}

package/dist/docs/chunk.d.ts

@@ -0,0 +1,7 @@
+type Chunk = {
+    heading: string;
+    text: string;
+};
+/** Split Markdown into searchable chunks: one or more per section, each prefixed by its heading path. */
+export declare function chunkMarkdown(title: string, markdown: string, size?: number, overlap?: number): Chunk[];
+export {};

package/dist/docs/chunk.js

@@ -0,0 +1,70 @@
+const HEADING = /^(#{1,6})\s+(.+?)\s*#*\s*$/;
+const FENCE = /^\s*(```|~~~)/;
+function sections(title, markdown) {
+    const found = [];
+    const stack = [];
+    let current = { path: [title], lines: [] };
+    let fenced = false;
+    for (const line of markdown.split(/\r?\n/)) {
+        if (FENCE.test(line))
+            fenced = !fenced;
+        const heading = fenced ? null : HEADING.exec(line);
+        if (heading?.[1] === undefined || heading[2] === undefined) {
+            current.lines.push(line);
+            continue;
+        }
+        found.push(current);
+        stack.length = heading[1].length - 1;
+        stack[heading[1].length - 1] = heading[2];
+        current = { path: [title, ...stack.filter((part) => part !== "" && part !== title)], lines: [] };
+    }
+    found.push(current);
+    return found;
+}
+function tail(text, size) {
+    if (text.length <= size)
+        return text;
+    const start = text.indexOf(" ", text.length - size);
+    return start === -1 ? text.slice(-size) : text.slice(start + 1);
+}
+function pieces(paragraph, size, overlap) {
+    const step = size - overlap;
+    const out = [];
+    for (let start = 0; start < paragraph.length; start += step) {
+        out.push(paragraph.slice(start, start + size));
+        if (start + size >= paragraph.length)
+            break;
+    }
+    return out;
+}
+/** Split Markdown into searchable chunks: one or more per section, each prefixed by its heading path. */
+export function chunkMarkdown(title, markdown, size = 1200, overlap = 200) {
+    const chunks = [];
+    for (const section of sections(title, markdown)) {
+        const heading = section.path.join(" > ");
+        const paragraphs = section.lines
+            .join("\n")
+            .split(/\n\s*\n/)
+            .map((paragraph) => paragraph.trim())
+            .filter((paragraph) => paragraph !== "");
+        let text = "";
+        for (const paragraph of paragraphs) {
+            if (paragraph.length > size) {
+                if (text !== "")
+                    chunks.push({ heading, text });
+                for (const piece of pieces(paragraph, size, overlap))
+                    chunks.push({ heading, text: piece });
+                text = "";
+                continue;
+            }
+            if (text !== "" && text.length + paragraph.length + 2 > size) {
+                chunks.push({ heading, text });
+                text = tail(text, overlap);
+            }
+            text = text === "" ? paragraph : `${text}\n\n${paragraph}`;
+        }
+        if (text !== "")
+            chunks.push({ heading, text });
+    }
+    return chunks;
+}

package/dist/docs/confluence.d.ts

@@ -0,0 +1,12 @@
+import type { DocsSource } from "./source.ts";
+type ConfluenceScope = {
+    site: string;
+    spaceKey?: string;
+    parentPageId?: string;
+};
+/** Pages of one space, or of one page and everything below it, through the Confluence Cloud REST API v2. */
+export declare function confluenceSource(name: string, scope: ConfluenceScope, credentials: {
+    email: string;
+    apiToken: string;
+}, fetchFn?: typeof fetch): DocsSource;
+export {};

package/dist/docs/confluence.js

@@ -0,0 +1,68 @@
+import { z } from "zod";
+import { storageToMarkdown } from "./html.js";
+const Links = z.object({ next: z.string().optional(), base: z.string().optional() }).optional();
+const Spaces = z.object({ results: z.array(z.object({ id: z.string(), key: z.string() })) });
+const Page = z.object({
+    id: z.string(),
+    title: z.string(),
+    parentId: z.string().nullish(),
+    version: z.object({ createdAt: z.string() }),
+    _links: z.object({ webui: z.string() }),
+});
+const PageWithSpace = Page.extend({ spaceId: z.string() });
+const Pages = z.object({ results: z.array(Page), _links: Links });
+const PageBody = z.object({ body: z.object({ storage: z.object({ value: z.string() }) }) });
+/** Pages of one space, or of one page and everything below it, through the Confluence Cloud REST API v2. */
+export function confluenceSource(name, scope, credentials, fetchFn = fetch) {
+    const site = scope.site.replace(/\/+$/, "");
+    const authorization = `Basic ${Buffer.from(`${credentials.email}:${credentials.apiToken}`).toString("base64")}`;
+    async function get(path, schema, signal) {
+        const response = await fetchFn(`${site}${path}`, {
+            headers: { authorization, accept: "application/json" },
+            signal,
+        });
+        if (!response.ok)
+            throw new Error(`Confluence ${path} answered ${response.status}`);
+        return schema.parse(await response.json());
+    }
+    async function spaceId(signal) {
+        if (scope.spaceKey !== undefined) {
+            const spaces = await get(`/wiki/api/v2/spaces?keys=${encodeURIComponent(scope.spaceKey)}`, Spaces, signal);
+            const space = spaces.results.find((candidate) => candidate.key === scope.spaceKey);
+            if (space === undefined)
+                throw new Error(`Confluence space ${scope.spaceKey} not found`);
+            return space.id;
+        }
+        if (scope.parentPageId === undefined)
+            throw new Error("Confluence scope needs a space key or a parent page");
+        return (await get(`/wiki/api/v2/pages/${scope.parentPageId}`, PageWithSpace, signal)).spaceId;
+    }
+    return {
+        name,
+        list: async (signal) => {
+            const pages = [];
+            let base = `${site}/wiki`;
+            let next = `/wiki/api/v2/spaces/${await spaceId(signal)}/pages?limit=250&status=current`;
+            while (next !== undefined) {
+                const page = await get(next, Pages, signal);
+                pages.push(...page.results);
+                base = page._links?.base ?? base;
+                next = page._links?.next;
+            }
+            const inScope = scope.parentPageId === undefined ? pages : subtree(pages, scope.parentPageId);
+            return inScope.map((page) => ({
+                id: page.id,
+                title: page.title,
+                url: `${base}${page._links.webui}`,
+                updatedAt: page.version.createdAt,
+            }));
+        },
+        fetch: async (id, signal) => storageToMarkdown((await get(`/wiki/api/v2/pages/${id}?body-format=storage`, PageBody, signal)).body.storage.value),
+    };
+}
+/** The root page and every page whose parent chain reaches it. */
+function subtree(pages, rootId) {
+    const parents = new Map(pages.map((page) => [page.id, page.parentId ?? undefined]));
+    const reaches = (id, depth) => id !== undefined && depth < 1000 && (id === rootId || reaches(parents.get(id), depth + 1));
+    return pages.filter((page) => reaches(page.id, 0));
+}