@butlerbot/sdk 0.0.33 → 0.0.35

package/dist/config.d.ts

@@ -1,5 +1,12 @@
 export declare const CONFIG: {
     server: string;
+    /**
+     * Where links connect.
+     *
+     * Not the core server: links are carried by their own service, so the SDK holds two
+     * addresses rather than one.
+     */
+    link: string;
     healthcheckPath: string;
     paths: {
         conversation: {
@@ -52,6 +59,28 @@ export declare const CONFIG: {
                 };
             };
         };
+        jobs: {
+            /** The collection. One job is `${base}/${jobId}`, its cancel `${base}/${jobId}/cancel`. */
+            base: string;
+            /** The owner's job settings, which live on the user rather than on a job. */
+            settings: string;
+        };
+        outreach: {
+            /** The inbox. One delivery's answer is `${base}/${deliveryId}/answer`. */
+            base: string;
+        };
     };
 };
 export type APIPath = keyof typeof CONFIG.paths.conversation;
+/**
+ * Which server a link should connect to.
+ *
+ * `linkUrl` names it outright and always wins. Failing that, a `serverUrl` pointing anywhere
+ * other than the hosted core is taken at its word: a self-hosted stack is usually one address,
+ * and sending an API key to a host nobody named would be a worse surprise than a wrong path.
+ * Otherwise it is the hosted link service, which is what the core server used to be and is not.
+ */
+export declare function resolveLinkUrl(config: {
+    linkUrl?: string;
+    serverUrl?: string;
+}): string;

package/dist/config.js

@@ -1,8 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CONFIG = void 0;
+exports.resolveLinkUrl = resolveLinkUrl;
 exports.CONFIG = {
     server: "https://core.butler.now",
+    /**
+     * Where links connect.
+     *
+     * Not the core server: links are carried by their own service, so the SDK holds two
+     * addresses rather than one.
+     */
+    link: "https://link.butler.now",
     healthcheckPath: "/api/healthcheck",
     paths: {
         conversation: {
@@ -42,6 +50,32 @@ exports.CONFIG = {
             policy: {
                 v3: { base: "/api/user/usage/v3/policy" },
             }
+        },
+        jobs: {
+            /** The collection. One job is `${base}/${jobId}`, its cancel `${base}/${jobId}/cancel`. */
+            base: "/api/jobs",
+            /** The owner's job settings, which live on the user rather than on a job. */
+            settings: "/api/user/jobs-settings",
+        },
+        outreach: {
+            /** The inbox. One delivery's answer is `${base}/${deliveryId}/answer`. */
+            base: "/api/outreach",
         }
     }
 };
+const withoutTrailingSlash = (url) => url.replace(/\/+$/, "");
+/**
+ * Which server a link should connect to.
+ *
+ * `linkUrl` names it outright and always wins. Failing that, a `serverUrl` pointing anywhere
+ * other than the hosted core is taken at its word: a self-hosted stack is usually one address,
+ * and sending an API key to a host nobody named would be a worse surprise than a wrong path.
+ * Otherwise it is the hosted link service, which is what the core server used to be and is not.
+ */
+function resolveLinkUrl(config) {
+    if (config.linkUrl)
+        return config.linkUrl;
+    if (config.serverUrl && withoutTrailingSlash(config.serverUrl) !== withoutTrailingSlash(exports.CONFIG.server))
+        return config.serverUrl;
+    return exports.CONFIG.link;
+}

package/dist/index.d.ts

@@ -2,6 +2,8 @@ import { APIPath } from "./config";
 import { Link, LinkOptions } from "./link";
 import { Conversation, ConversationOptions } from "./modules/conversation";
 import { UsagePolicyDataOptions } from "./modules/usage";
+import { type CancelJobOptions, type GetJobOptions, type ListJobsOptions, type UpdateJobOptions, type UpdateJobSettingsOptions } from "./modules/jobs";
+import { type AnswerDeliveryOptions, type ListDeliveriesOptions } from "./modules/outreach";
 type OptionalApiKey<T> = Omit<T, "apiKey"> & {
     /** Optional API key, defaults to API key specified in client */
     apiKey?: string;
@@ -9,6 +11,14 @@ type OptionalApiKey<T> = Omit<T, "apiKey"> & {
 export type ButlerBotClientOptions = {
     /** The server endpoint, API calls are sent here */
     serverUrl?: string;
+    /**
+     * Where links connect. Defaults to the hosted link service.
+     *
+     * Links are no longer carried by the core server, so this is a second address rather than
+     * a path on the first. A `serverUrl` pointing at your own stack is used for links too,
+     * unless this names somewhere else.
+     */
+    linkUrl?: string;
     /** The API key to use with ButlerBot */
     apiKey: string;
     /** Whether to enable debug logs */
@@ -17,6 +27,7 @@ export type ButlerBotClientOptions = {
 export declare class ButlerBotClient {
     private apiKey;
     private serverUrl;
+    private linkUrl;
     private debug;
     constructor(config: ButlerBotClientOptions);
     /** Checks the health of the server returning true if server is alive */
@@ -25,17 +36,42 @@ export declare class ButlerBotClient {
     createConversation<V extends APIPath = "v4">(config?: OptionalApiKey<ConversationOptions<V>>): Conversation<V>;
     /**
      * Creates a Link: a live connection that can register tools and hooks, and carry
-     * conversations. Inherits the client's API key and server URL.
+     * conversations. Inherits the client's API key and link URL.
+     *
+     * The link URL, not the server URL: links are served by their own service. Pass
+     * `serverUrl` here, or `linkUrl` to the client, to point somewhere else.
      */
     createLink(config: OptionalApiKey<LinkOptions>): Link;
     /** Get current usage policy data */
     getUsagePolicyData(config: OptionalApiKey<UsagePolicyDataOptions>): Promise<import("./types/usage/policy").UsagePolicyData>;
+    /** A page of this user's jobs, with what their jobs may spend today */
+    listJobs(config?: OptionalApiKey<ListJobsOptions>): Promise<import("./types/type_registry").JobListResponse>;
+    /** One job, with its plan, its journal and the questions waiting on the user */
+    getJob(config: OptionalApiKey<GetJobOptions>): Promise<import("./types/type_registry").JobDetailResponse>;
+    /** Stops a job. Throws a `ButlerBotAPIError` with `isConflict` when it had already finished */
+    cancelJob(config: OptionalApiKey<CancelJobOptions>): Promise<import("./types/type_registry").JobCancelResponse>;
+    /** Changes one job's autonomy: how far it may act, until when, and what it always asks about */
+    updateJob(config: OptionalApiKey<UpdateJobOptions>): Promise<import("./types/type_registry").JobUpdateResponse>;
+    /** Changes this user's job settings: their daily allowance and what new jobs start with */
+    updateJobSettings(config?: OptionalApiKey<UpdateJobSettingsOptions>): Promise<import("./types/type_registry").JobSettingsResponse>;
+    /** A page of the inbox: what Alfred has told or asked this user outside a chat */
+    listDeliveries(config?: OptionalApiKey<ListDeliveriesOptions>): Promise<import("./types/type_registry").DeliveryListResponse>;
+    /** Answers a delivery. Throws a `ButlerBotAPIError` with `isConflict` when it was already answered */
+    answerDelivery(config: OptionalApiKey<AnswerDeliveryOptions>): Promise<import("./types/type_registry").DeliveryAnswerResponse>;
+    /** The client's own server and key underneath whatever the call named itself. */
+    private forRequest;
 }
 export * from "./types/type_registry";
 export * from "./link";
-export { Conversation, ConversationOptions };
+export { Conversation };
+export type { ConversationOptions };
 export type { APIPath };
 export type { ConversationStream, ConversationTransport, TransportTurnRequest, TransportHandlers, } from "./modules/transport";
+export { ButlerBotAPIError } from "./util/api_error";
+export { listJobs, getJob, cancelJob, updateJob, updateJobSettings } from "./modules/jobs";
+export type { JobsRequestOptions, ListJobsOptions, GetJobOptions, CancelJobOptions, UpdateJobOptions, UpdateJobSettingsOptions, } from "./modules/jobs";
+export { listDeliveries, answerDelivery } from "./modules/outreach";
+export type { OutreachRequestOptions, ListDeliveriesOptions, AnswerDeliveryOptions, } from "./modules/outreach";
 export { LinkConversationTransport } from "./modules/transport_link";
 export { SSEConversationTransport } from "./modules/transport_sse";
 export type { SteerResult, TurnStopMode, TurnStopped } from "./modules/transport";

package/dist/index.js

@@ -14,16 +14,31 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SSEConversationTransport = exports.LinkConversationTransport = exports.Conversation = exports.ButlerBotClient = void 0;
+exports.SSEConversationTransport = exports.LinkConversationTransport = exports.answerDelivery = exports.listDeliveries = exports.updateJobSettings = exports.updateJob = exports.cancelJob = exports.getJob = exports.listJobs = exports.ButlerBotAPIError = exports.Conversation = exports.ButlerBotClient = void 0;
 const config_1 = require("./config");
 const link_1 = require("./link");
 const conversation_1 = require("./modules/conversation");
 Object.defineProperty(exports, "Conversation", { enumerable: true, get: function () { return conversation_1.Conversation; } });
 const usage_1 = require("./modules/usage");
+const jobs_1 = require("./modules/jobs");
+const outreach_1 = require("./modules/outreach");
+/**
+ * The options a caller actually gave, with the keys they left out removed.
+ *
+ * A client's own API key and URLs are the fallback for whatever a factory call omits, and the
+ * usual way to omit something is to forward an optional setting that happens to be unset —
+ * `createLink({ serverUrl: process.env.LINK_URL })`. Spread as it stands, that `undefined`
+ * lands on top of the client's resolved value and erases it, so the link ends up at the hosted
+ * service rather than the self-hosted stack the client was pointed at. Absent means "not given".
+ */
+function given(config) {
+    return Object.fromEntries(Object.entries(config).filter(([, value]) => value !== undefined));
+}
 class ButlerBotClient {
     constructor(config) {
         this.apiKey = config.apiKey;
         this.serverUrl = config.serverUrl || config_1.CONFIG.server;
+        this.linkUrl = (0, config_1.resolveLinkUrl)(config);
         this.debug = config.debug || false;
     }
     /** Checks the health of the server returning true if server is alive */
@@ -41,24 +56,70 @@ class ButlerBotClient {
     }
     /** Spawns a new Conversation, inherits api key and server URL */
     createConversation(config = {}) {
-        return new conversation_1.Conversation({ debug: this.debug, apiKey: this.apiKey, serverUrl: this.serverUrl, ...config });
+        return new conversation_1.Conversation({ debug: this.debug, apiKey: this.apiKey, serverUrl: this.serverUrl, ...given(config) });
     }
     /**
      * Creates a Link: a live connection that can register tools and hooks, and carry
-     * conversations. Inherits the client's API key and server URL.
+     * conversations. Inherits the client's API key and link URL.
+     *
+     * The link URL, not the server URL: links are served by their own service. Pass
+     * `serverUrl` here, or `linkUrl` to the client, to point somewhere else.
      */
     createLink(config) {
-        return new link_1.Link({ debug: this.debug, apiKey: this.apiKey, serverUrl: this.serverUrl, ...config });
+        return new link_1.Link({ debug: this.debug, apiKey: this.apiKey, serverUrl: this.linkUrl, ...given(config) });
     }
     /** Get current usage policy data */
     getUsagePolicyData(config) {
         return (0, usage_1.getUsagePolicyData)({ serverURL: this.serverUrl, apiKey: this.apiKey, debug: this.debug, ...config });
     }
+    /** A page of this user's jobs, with what their jobs may spend today */
+    listJobs(config = {}) {
+        return (0, jobs_1.listJobs)(this.forRequest(config));
+    }
+    /** One job, with its plan, its journal and the questions waiting on the user */
+    getJob(config) {
+        return (0, jobs_1.getJob)(this.forRequest(config));
+    }
+    /** Stops a job. Throws a `ButlerBotAPIError` with `isConflict` when it had already finished */
+    cancelJob(config) {
+        return (0, jobs_1.cancelJob)(this.forRequest(config));
+    }
+    /** Changes one job's autonomy: how far it may act, until when, and what it always asks about */
+    updateJob(config) {
+        return (0, jobs_1.updateJob)(this.forRequest(config));
+    }
+    /** Changes this user's job settings: their daily allowance and what new jobs start with */
+    updateJobSettings(config = {}) {
+        return (0, jobs_1.updateJobSettings)(this.forRequest(config));
+    }
+    /** A page of the inbox: what Alfred has told or asked this user outside a chat */
+    listDeliveries(config = {}) {
+        return (0, outreach_1.listDeliveries)(this.forRequest(config));
+    }
+    /** Answers a delivery. Throws a `ButlerBotAPIError` with `isConflict` when it was already answered */
+    answerDelivery(config) {
+        return (0, outreach_1.answerDelivery)(this.forRequest(config));
+    }
+    /** The client's own server and key underneath whatever the call named itself. */
+    forRequest(config) {
+        return { serverURL: this.serverUrl, apiKey: this.apiKey, debug: this.debug, ...given(config) };
+    }
 }
 exports.ButlerBotClient = ButlerBotClient;
 // Expose types from subsequent modules
 __exportStar(require("./types/type_registry"), exports);
 __exportStar(require("./link"), exports);
+var api_error_1 = require("./util/api_error");
+Object.defineProperty(exports, "ButlerBotAPIError", { enumerable: true, get: function () { return api_error_1.ButlerBotAPIError; } });
+var jobs_2 = require("./modules/jobs");
+Object.defineProperty(exports, "listJobs", { enumerable: true, get: function () { return jobs_2.listJobs; } });
+Object.defineProperty(exports, "getJob", { enumerable: true, get: function () { return jobs_2.getJob; } });
+Object.defineProperty(exports, "cancelJob", { enumerable: true, get: function () { return jobs_2.cancelJob; } });
+Object.defineProperty(exports, "updateJob", { enumerable: true, get: function () { return jobs_2.updateJob; } });
+Object.defineProperty(exports, "updateJobSettings", { enumerable: true, get: function () { return jobs_2.updateJobSettings; } });
+var outreach_2 = require("./modules/outreach");
+Object.defineProperty(exports, "listDeliveries", { enumerable: true, get: function () { return outreach_2.listDeliveries; } });
+Object.defineProperty(exports, "answerDelivery", { enumerable: true, get: function () { return outreach_2.answerDelivery; } });
 var transport_link_1 = require("./modules/transport_link");
 Object.defineProperty(exports, "LinkConversationTransport", { enumerable: true, get: function () { return transport_link_1.LinkConversationTransport; } });
 var transport_sse_1 = require("./modules/transport_sse");

package/dist/link/link.d.ts

@@ -49,6 +49,7 @@ export type LinkOptions = {
      * one takes over and the older one's registrations are released.
      */
     linkId: string;
+    /** The link service. Defaults to the hosted one, which is not the core server. */
     serverUrl?: string;
     /** Informational, shown in server logs. Defaults to the SDK name. */
     client?: string;

package/dist/link/link.js

@@ -66,7 +66,7 @@ class Link {
             reconnect: true,
             debug: false,
             client: "@butlerbot/sdk",
-            serverUrl: config_1.CONFIG.server,
+            serverUrl: config_1.CONFIG.link,
             socketFactory: socket_1.defaultSocketFactory,
             ...stripUndefined(options),
         };

package/dist/link/protocol.d.ts

@@ -236,12 +236,19 @@ export type LinkServerPayloads = {
         chatId?: string;
         message: string;
     };
+    /**
+     * A turn ended, one way or another.
+     *
+     * `lastEventId` comes with `turn_suspended`: the turn is still being answered somewhere
+     * and this is where a `conversation.attach` should pick it back up.
+     */
     "conversation.done": {
         chatId?: string;
         ok: boolean;
         code?: string;
         error?: string;
         message?: string;
+        lastEventId?: string;
     };
     /** A turn was stopped. `mode` is what was applied, `requestedMode` what was asked for. */
     "conversation.stopped": {

package/dist/modules/api_request.d.ts

@@ -0,0 +1,18 @@
+export type APIRequestOptions = {
+    url: string;
+    /** GET when nothing says otherwise. */
+    method?: "GET" | "POST" | "PATCH" | "DELETE";
+    /** Sent as JSON. A route that takes no body is called without one. */
+    body?: unknown;
+    /** What the caller was trying to do, for the message a failure carries. */
+    action: string;
+};
+/**
+ * One call to a JSON route, with the failure turned into a `ButlerBotAPIError`.
+ *
+ * The body is read as text once and parsed here rather than through `response.json()`, because
+ * a failing route's body has to be readable both as the parsed `error`/`errormessage` and as
+ * whatever else it carries — the job on a rejected cancel, the delivery on a rejected answer —
+ * and a response body can only be consumed once.
+ */
+export declare function requestAPI<T>(options: APIRequestOptions): Promise<T>;

package/dist/modules/api_request.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requestAPI = requestAPI;
+const api_error_1 = require("../util/api_error");
+/**
+ * One call to a JSON route, with the failure turned into a `ButlerBotAPIError`.
+ *
+ * The body is read as text once and parsed here rather than through `response.json()`, because
+ * a failing route's body has to be readable both as the parsed `error`/`errormessage` and as
+ * whatever else it carries — the job on a rejected cancel, the delivery on a rejected answer —
+ * and a response body can only be consumed once.
+ */
+async function requestAPI(options) {
+    const init = { method: options.method || "GET" };
+    if (options.body !== undefined) {
+        init.headers = { "Content-Type": "application/json" };
+        init.body = JSON.stringify(options.body);
+    }
+    const response = await fetch(options.url, init);
+    const text = await response.text();
+    const data = parseJSON(text);
+    const envelope = (data && typeof data === "object" ? data : {});
+    if (!response.ok || envelope.success !== true) {
+        throw new api_error_1.ButlerBotAPIError({
+            action: options.action,
+            status: response.status,
+            statusText: response.statusText,
+            error: envelope.error,
+            errormessage: envelope.errormessage,
+            body: data ?? text,
+        });
+    }
+    return data;
+}
+function parseJSON(text) {
+    if (!text)
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/modules/jobs.d.ts

@@ -0,0 +1,48 @@
+import type { JobAutonomy, JobCancelResponse, JobDetailResponse, JobListResponse, JobSettingsResponse, JobSettingsUpdate, JobStatus, JobUpdateResponse } from "../types/jobs";
+/** What every jobs call needs: where the server is, and who is asking. */
+export type JobsRequestOptions = {
+    serverURL?: string;
+    /** The base path for jobs, when it is not the default. */
+    path?: string;
+    apiKey: string;
+    debug?: boolean;
+};
+export type ListJobsOptions = JobsRequestOptions & {
+    /** 1-based. The first page when it is not given. */
+    page?: number;
+    /** How many jobs per page. */
+    limit?: number;
+    /** Only jobs in this status. */
+    status?: JobStatus;
+};
+export type GetJobOptions = JobsRequestOptions & {
+    jobId: string;
+};
+export type CancelJobOptions = JobsRequestOptions & {
+    jobId: string;
+};
+export type UpdateJobOptions = JobsRequestOptions & {
+    jobId: string;
+    /** How far this job may act outward on its own. */
+    autonomy?: JobAutonomy;
+    /** When that autonomy lapses back to asking. Null clears it. */
+    autonomyUntil?: string | number | null;
+    /** Things this job asks about however free it otherwise is. */
+    alwaysAsk?: string[];
+};
+export type UpdateJobSettingsOptions = JobsRequestOptions & JobSettingsUpdate;
+/** A page of the caller's jobs, newest first, with what their jobs may spend today. */
+export declare function listJobs(options: ListJobsOptions): Promise<JobListResponse>;
+/** One job with its plan, its journal and the questions of its nobody has answered. */
+export declare function getJob(options: GetJobOptions): Promise<JobDetailResponse>;
+/**
+ * Stops a job.
+ *
+ * A job that had already finished is a 409: the call throws a `ButlerBotAPIError` whose
+ * `isConflict` is true and whose `body` still carries the job as it stands.
+ */
+export declare function cancelJob(options: CancelJobOptions): Promise<JobCancelResponse>;
+/** Changes one job's autonomy: how far it may act, until when, and what it always asks about. */
+export declare function updateJob(options: UpdateJobOptions): Promise<JobUpdateResponse>;
+/** Changes the owner's job settings: their daily allowance and the autonomy new jobs start with. */
+export declare function updateJobSettings(options: UpdateJobSettingsOptions): Promise<JobSettingsResponse>;

package/dist/modules/jobs.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listJobs = listJobs;
+exports.getJob = getJob;
+exports.cancelJob = cancelJob;
+exports.updateJob = updateJob;
+exports.updateJobSettings = updateJobSettings;
+const config_1 = require("../config");
+const url_formatter_1 = require("../util/url_formatter");
+const api_request_1 = require("./api_request");
+function jobsBase(options) {
+    return (options.serverURL || config_1.CONFIG.server) + (options.path || config_1.CONFIG.paths.jobs.base);
+}
+/** Only what was actually given: `URLSearchParams` would otherwise send the word "undefined". */
+function query(params) {
+    const given = {};
+    for (const [key, value] of Object.entries(params)) {
+        if (value !== undefined)
+            given[key] = String(value);
+    }
+    return given;
+}
+/** Only the keys a caller set, so an omitted field is not sent as an explicit `undefined`. */
+function body(fields) {
+    return Object.fromEntries(Object.entries(fields).filter(([, value]) => value !== undefined));
+}
+/** A page of the caller's jobs, newest first, with what their jobs may spend today. */
+async function listJobs(options) {
+    const url = (0, url_formatter_1.formatURL)(jobsBase(options), query({ page: options.page, limit: options.limit, status: options.status }), { apiKey: options.apiKey, debug: options.debug });
+    return (0, api_request_1.requestAPI)({ url, action: "list jobs" });
+}
+/** One job with its plan, its journal and the questions of its nobody has answered. */
+async function getJob(options) {
+    const url = (0, url_formatter_1.formatURL)(`${jobsBase(options)}/${encodeURIComponent(options.jobId)}`, {}, { apiKey: options.apiKey, debug: options.debug });
+    return (0, api_request_1.requestAPI)({ url, action: `read job ${options.jobId}` });
+}
+/**
+ * Stops a job.
+ *
+ * A job that had already finished is a 409: the call throws a `ButlerBotAPIError` whose
+ * `isConflict` is true and whose `body` still carries the job as it stands.
+ */
+async function cancelJob(options) {
+    const url = (0, url_formatter_1.formatURL)(`${jobsBase(options)}/${encodeURIComponent(options.jobId)}/cancel`, {}, { apiKey: options.apiKey, debug: options.debug });
+    return (0, api_request_1.requestAPI)({ url, method: "POST", action: `cancel job ${options.jobId}` });
+}
+/** Changes one job's autonomy: how far it may act, until when, and what it always asks about. */
+async function updateJob(options) {
+    const url = (0, url_formatter_1.formatURL)(`${jobsBase(options)}/${encodeURIComponent(options.jobId)}`, {}, { apiKey: options.apiKey, debug: options.debug });
+    return (0, api_request_1.requestAPI)({
+        url,
+        method: "PATCH",
+        body: body({ autonomy: options.autonomy, autonomyUntil: options.autonomyUntil, alwaysAsk: options.alwaysAsk }),
+        action: `update job ${options.jobId}`,
+    });
+}
+/** Changes the owner's job settings: their daily allowance and the autonomy new jobs start with. */
+async function updateJobSettings(options) {
+    const endpoint = (options.serverURL || config_1.CONFIG.server) + (options.path || config_1.CONFIG.paths.jobs.settings);
+    const url = (0, url_formatter_1.formatURL)(endpoint, {}, { apiKey: options.apiKey, debug: options.debug });
+    return (0, api_request_1.requestAPI)({
+        url,
+        method: "PATCH",
+        body: body({
+            allowanceUsd: options.allowanceUsd,
+            allowancePercent: options.allowancePercent,
+            autonomy: options.autonomy,
+            alwaysAsk: options.alwaysAsk,
+        }),
+        action: "update job settings",
+    });
+}

package/dist/modules/outreach.d.ts

@@ -0,0 +1,31 @@
+import type { DeliveryAnswerResponse, DeliveryListResponse } from "../types/outreach";
+/** What every outreach call needs: where the server is, and who is asking. */
+export type OutreachRequestOptions = {
+    serverURL?: string;
+    /** The base path for outreach, when it is not the default. */
+    path?: string;
+    apiKey: string;
+    debug?: boolean;
+};
+export type ListDeliveriesOptions = OutreachRequestOptions & {
+    /** 1-based. The first page when it is not given. */
+    page?: number;
+    /** How many deliveries per page. */
+    limit?: number;
+};
+export type AnswerDeliveryOptions = OutreachRequestOptions & {
+    deliveryId: string;
+    /** The user's answer, in their own words. */
+    text: string;
+    /** On an approval, what they decided. */
+    decision?: "approve" | "deny";
+};
+/** A page of the inbox: what Alfred has told or asked this user outside a chat. */
+export declare function listDeliveries(options: ListDeliveriesOptions): Promise<DeliveryListResponse>;
+/**
+ * Answers one delivery, which closes it and wakes the job that asked.
+ *
+ * A delivery somebody has already answered is a 409: the call throws a `ButlerBotAPIError`
+ * whose `isConflict` is true and whose `body` still carries the delivery with the answer on it.
+ */
+export declare function answerDelivery(options: AnswerDeliveryOptions): Promise<DeliveryAnswerResponse>;

package/dist/modules/outreach.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listDeliveries = listDeliveries;
+exports.answerDelivery = answerDelivery;
+const config_1 = require("../config");
+const url_formatter_1 = require("../util/url_formatter");
+const api_request_1 = require("./api_request");
+function outreachBase(options) {
+    return (options.serverURL || config_1.CONFIG.server) + (options.path || config_1.CONFIG.paths.outreach.base);
+}
+/** Only what was actually given: `URLSearchParams` would otherwise send the word "undefined". */
+function query(params) {
+    const given = {};
+    for (const [key, value] of Object.entries(params)) {
+        if (value !== undefined)
+            given[key] = String(value);
+    }
+    return given;
+}
+/** A page of the inbox: what Alfred has told or asked this user outside a chat. */
+async function listDeliveries(options) {
+    const url = (0, url_formatter_1.formatURL)(outreachBase(options), query({ page: options.page, limit: options.limit }), { apiKey: options.apiKey, debug: options.debug });
+    return (0, api_request_1.requestAPI)({ url, action: "list deliveries" });
+}
+/**
+ * Answers one delivery, which closes it and wakes the job that asked.
+ *
+ * A delivery somebody has already answered is a 409: the call throws a `ButlerBotAPIError`
+ * whose `isConflict` is true and whose `body` still carries the delivery with the answer on it.
+ */
+async function answerDelivery(options) {
+    const url = (0, url_formatter_1.formatURL)(`${outreachBase(options)}/${encodeURIComponent(options.deliveryId)}/answer`, {}, { apiKey: options.apiKey, debug: options.debug });
+    return (0, api_request_1.requestAPI)({
+        url,
+        method: "POST",
+        body: options.decision === undefined ? { text: options.text } : { text: options.text, decision: options.decision },
+        action: `answer delivery ${options.deliveryId}`,
+    });
+}

package/dist/modules/transport_link.d.ts

@@ -50,6 +50,35 @@ export declare class LinkConversationTransport implements ConversationTransport
      */
     attach(request: TransportAttachRequest, handlers: TransportHandlers): ConversationStream;
     private runTurn;
+    /**
+     * One `conversation.attach`: streams a turn's events to the caller and resolves with how
+     * that watch ended.
+     *
+     * Shared by watching somebody else's turn and by rejoining one of our own, because from
+     * here the two are the same act. `progress` is carried rather than returned: a watch that
+     * dies halfway still has to leave behind where it got to, or a resume would replay from
+     * the beginning and the caller would read the answer twice.
+     */
+    private watch;
+    /**
+     * Picks a turn back up after losing sight of it.
+     *
+     * Two ways to lose one, one way to get it back. The socket can go — a deploy of the link
+     * service, a proxy timing out — which rejects the exchange carrying the turn. Or core can
+     * suspend the turn at its own deploy and hand it to another instance, which the link
+     * service follows for two minutes before giving up and saying `turn_suspended`. Either way
+     * the turn is still being answered and the conversation still holds it, so this re-attaches
+     * from the last event the caller was actually given and the stream reads as one answer.
+     *
+     * `no_active_turn` is the ambiguous reply and it is deliberately not treated as an ending:
+     * during a handover it means "not picked up yet" far more often than it means "gone", and
+     * the window is what decides between them.
+     *
+     * Nothing here throws. It runs behind a stream the caller already holds, so the outcomes
+     * that matter are the ones delivered into it: a completion, or a failure that says plainly
+     * that the answer was lost track of rather than that it failed.
+     */
+    private resume;
     /** Opens a session, or reuses the open one when it is for the same conversation. */
     private session;
 }