@butlerbot/sdk 0.0.33 → 0.0.35

package/dist/types/outreach/delivery.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Outreach: what Alfred has told or asked this user outside a chat, and their answers.
+ *
+ * A delivery is the record itself, so the inbox listing is the delivery rather than a
+ * notification about one. Answering closes it, and when it belongs to a job the answer is put
+ * on that job's inbox.
+ */
+export declare const DELIVERY_INTENTS: readonly ["question", "update", "approval", "statement"];
+export type DeliveryIntent = typeof DELIVERY_INTENTS[number];
+/** The intents that leave something outstanding until the user answers. */
+export declare const ANSWERABLE_DELIVERY_INTENTS: readonly DeliveryIntent[];
+export declare const DELIVERY_SURFACES: readonly ["web", "discord"];
+/** Where a delivery was put. */
+export type DeliverySurfaceName = typeof DELIVERY_SURFACES[number];
+export declare const DELIVERY_SURFACE_STATUSES: readonly ["pending", "sent", "failed"];
+export type DeliverySurfaceStatus = typeof DELIVERY_SURFACE_STATUSES[number];
+/** How one surface's send went. */
+export type DeliverySurface = {
+    surface: DeliverySurfaceName;
+    status: DeliverySurfaceStatus;
+    /** Where on the surface it went: a Discord channel id, or "DM". */
+    channelId?: string | null;
+    /** What the channel called the message it sent. */
+    messageId?: string | null;
+    /** Why the last attempt failed. */
+    error?: string | null;
+    attempts: number;
+    /** When the last attempt was made, in UTC milliseconds. */
+    lastAt: number;
+};
+export declare const DELIVERY_ANSWER_VIA: readonly ["web", "discord", "chat", "tool"];
+/** Which surface the answer came back on. */
+export type DeliveryAnsweredVia = typeof DELIVERY_ANSWER_VIA[number];
+export type DeliveryAnswer = {
+    at: number;
+    text: string;
+    via: DeliveryAnsweredVia;
+    /** On an approval, what the user decided. */
+    decision?: "approve" | "deny";
+};
+/** One delivery, as the inbox reads it. */
+export type Delivery = {
+    deliveryId: string;
+    ownerUserId: string;
+    /** The chat this is about, so answering opens the conversation it belongs to. */
+    originConversationId: string | null;
+    /** The job this is about, when it is about one. */
+    jobId: string | null;
+    intent: DeliveryIntent;
+    message: string;
+    surfaces: DeliverySurface[];
+    /** Null until somebody answers. Only ever set once. */
+    answered: DeliveryAnswer | null;
+    created: number;
+};
+/** Whether a delivery is still waiting on the user. */
+export declare function isDeliveryOpen(delivery: Delivery): boolean;
+export type DeliveryListResponse = {
+    success: true;
+    deliveries: Delivery[];
+    page: number;
+    limit: number;
+    total: number;
+};
+/** What became of the answer once it was handed to the job that asked. */
+export type DeliveryAnswerJobResult = {
+    jobId: string;
+    /** What the job did with it, or "dropped" when it could not take it. */
+    delivered: string;
+    /** Why it could not be delivered, when it could not. */
+    error?: string;
+};
+export type DeliveryAnswerResponse = {
+    success: true;
+    delivery: Delivery;
+    /** Present only when the delivery belonged to a job. */
+    job?: DeliveryAnswerJobResult;
+};

package/dist/types/outreach/delivery.js

@@ -0,0 +1,21 @@
+"use strict";
+/**
+ * Outreach: what Alfred has told or asked this user outside a chat, and their answers.
+ *
+ * A delivery is the record itself, so the inbox listing is the delivery rather than a
+ * notification about one. Answering closes it, and when it belongs to a job the answer is put
+ * on that job's inbox.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DELIVERY_ANSWER_VIA = exports.DELIVERY_SURFACE_STATUSES = exports.DELIVERY_SURFACES = exports.ANSWERABLE_DELIVERY_INTENTS = exports.DELIVERY_INTENTS = void 0;
+exports.isDeliveryOpen = isDeliveryOpen;
+exports.DELIVERY_INTENTS = ["question", "update", "approval", "statement"];
+/** The intents that leave something outstanding until the user answers. */
+exports.ANSWERABLE_DELIVERY_INTENTS = ["question", "approval"];
+exports.DELIVERY_SURFACES = ["web", "discord"];
+exports.DELIVERY_SURFACE_STATUSES = ["pending", "sent", "failed"];
+exports.DELIVERY_ANSWER_VIA = ["web", "discord", "chat", "tool"];
+/** Whether a delivery is still waiting on the user. */
+function isDeliveryOpen(delivery) {
+    return exports.ANSWERABLE_DELIVERY_INTENTS.includes(delivery.intent) && !delivery.answered;
+}

package/dist/types/outreach/index.d.ts

@@ -0,0 +1 @@
+export * from "./delivery";

package/dist/types/outreach/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+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 });
+__exportStar(require("./delivery"), exports);

package/dist/types/type_registry.d.ts

@@ -3,4 +3,6 @@ export * from "./response/v4";
 export * from "./response/v5";
 export * from "./state/convo_state_response";
 export * from "./conversation/v4/conversation_v4";
+export * from "./jobs";
+export * from "./outreach";
 export * from "./error";

package/dist/types/type_registry.js

@@ -19,4 +19,6 @@ __exportStar(require("./response/v4"), exports);
 __exportStar(require("./response/v5"), exports);
 __exportStar(require("./state/convo_state_response"), exports);
 __exportStar(require("./conversation/v4/conversation_v4"), exports);
+__exportStar(require("./jobs"), exports);
+__exportStar(require("./outreach"), exports);
 __exportStar(require("./error"), exports);

package/dist/util/api_error.d.ts

@@ -0,0 +1,34 @@
+/**
+ * What an API call throws when the server did not answer with a success.
+ *
+ * One error class for every JSON route rather than a result type per method: the status is
+ * what a caller branches on, and it is carried here alongside whatever the server said, so
+ * "the job was already finished" (409) and "no job of yours has that id" (404) are told apart
+ * without parsing a message. `body` is the parsed response when there was one, so a 409 on a
+ * cancel still hands back the job, and a 409 on an answer still hands back the delivery.
+ */
+export declare class ButlerBotAPIError extends Error {
+    /** The HTTP status the server answered with, or 0 when the call never got a response. */
+    readonly status: number;
+    readonly statusText: string;
+    /** The server's short `error`, e.g. "Already finished". */
+    readonly error?: string;
+    /** The server's `errormessage`: the same thing in a sentence. */
+    readonly errormessage?: string;
+    /** The parsed response body, or the raw text when it was not JSON. */
+    readonly body: unknown;
+    constructor(options: {
+        action: string;
+        status: number;
+        statusText?: string;
+        error?: string;
+        errormessage?: string;
+        body?: unknown;
+    });
+    /** The resource is not there, or is not this key's. The two are answered alike on purpose. */
+    get isNotFound(): boolean;
+    /** Somebody got there first: the job had finished, or the delivery was already answered. */
+    get isConflict(): boolean;
+    /** The request itself was refused: a value the server would not take. */
+    get isBadRequest(): boolean;
+}

package/dist/util/api_error.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ButlerBotAPIError = void 0;
+/**
+ * What an API call throws when the server did not answer with a success.
+ *
+ * One error class for every JSON route rather than a result type per method: the status is
+ * what a caller branches on, and it is carried here alongside whatever the server said, so
+ * "the job was already finished" (409) and "no job of yours has that id" (404) are told apart
+ * without parsing a message. `body` is the parsed response when there was one, so a 409 on a
+ * cancel still hands back the job, and a 409 on an answer still hands back the delivery.
+ */
+class ButlerBotAPIError extends Error {
+    constructor(options) {
+        const detail = options.errormessage
+            || options.error
+            // A body that was not JSON at all still says more than "Unknown error" does.
+            || (typeof options.body === "string" && options.body ? options.body.slice(0, 500) : "Unknown error");
+        super(`Failed to ${options.action}: ${options.status} ${options.statusText || ""} - ${detail}`.replace(/\s+-/, " -"));
+        this.name = "ButlerBotAPIError";
+        this.status = options.status;
+        this.statusText = options.statusText || "";
+        this.error = options.error;
+        this.errormessage = options.errormessage;
+        this.body = options.body;
+        // `target: es2020` down-levels the subclass, which breaks `instanceof` without this.
+        Object.setPrototypeOf(this, ButlerBotAPIError.prototype);
+    }
+    /** The resource is not there, or is not this key's. The two are answered alike on purpose. */
+    get isNotFound() {
+        return this.status === 404;
+    }
+    /** Somebody got there first: the job had finished, or the delivery was already answered. */
+    get isConflict() {
+        return this.status === 409;
+    }
+    /** The request itself was refused: a value the server would not take. */
+    get isBadRequest() {
+        return this.status === 400;
+    }
+}
+exports.ButlerBotAPIError = ButlerBotAPIError;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@butlerbot/sdk",
-	"version": "0.0.33",
+	"version": "0.0.35",
 	"description": "The official ButlerBot SDK",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",

package/readme.md

@@ -78,7 +78,12 @@ between you and the socket.
 
 ## Link
 
-A Link is a live connection to Alfred. It does three things:
+A Link is a live connection to Alfred, served by its own endpoint — `link.butler.now`,
+not the core API server. `createLink` goes there by default; pass `linkUrl` to the client
+(or `serverUrl` to `createLink`) to point somewhere else. A client given a `serverUrl` of
+its own — a self-hosted stack — uses that for links too.
+
+It does three things:
 
 - **Tools** — Alfred calls code that runs on your machine
 - **Hooks** — your code wakes the user's background agents when something happens
@@ -286,9 +291,15 @@ Which to use:
   Best when you are already running a link for tools or hooks, or holding many
   conversations at once — one socket carries them all.
 
-One difference to know about: sessions are ephemeral. If the connection drops mid-turn
-the SDK reopens the session and resends transparently; the conversation itself is
-persisted server-side, so nothing is lost.
+A turn survives losing the connection it was asked for on. Sessions are ephemeral — the
+server drops one with its socket — but the turn belongs to the conversation, so when the
+socket goes mid-answer the SDK reconnects, rejoins the turn from the last event it gave
+you, and carries on into the same stream. The same holds when the platform deploys
+mid-turn and the answer is handed to another instance. A message that had not been
+delivered yet is simply sent again on a fresh session; one that had is never sent twice.
+
+If the turn cannot be picked back up within a minute, the stream ends with a failure that
+says so — the reply may still have finished, and reopening the conversation will show it.
 
 ### Rejoining a turn already in progress
 
@@ -311,6 +322,71 @@ seen. A conversation with nothing running simply ends the stream.
 Neither transport can cancel a turn: `close()` stops delivery locally, and the reply is
 still generated and stored.
 
+## Jobs
+
+A job is long-running work Alfred does on its own, run as a sequence of short shifts against
+a plan it writes. The client reads them and steers them; it does not run them.
+
+```typescript
+const { jobs, allowance, spentTodayUsd } = await client.listJobs({ status: "running", page: 1, limit: 20 });
+const { job, plan, journal, openDeliveries, autonomyLine } = await client.getJob({ jobId });
+
+await client.updateJob({ jobId, autonomy: "free", autonomyUntil: Date.now() + 86_400_000 });
+await client.cancelJob({ jobId });
+```
+
+Paging is 1-based, and every listing answers with `page`, `limit` and `total`. A listing also
+carries `allowance` — what this user's jobs may spend today and what is left of it, or
+`{ perDayUsd: 0, source: null, refused, message }` when their plan does not include jobs.
+
+`autonomy` is how far a job may act outward without asking: `ask`, `free` or `auto`.
+`autonomyUntil` is when a loosened setting lapses back to asking, and `alwaysAsk` is what the
+job asks about however free it otherwise is. `effectiveAutonomy` on a job is what the gate
+actually reads, with the owner's default and any lapse already applied. What new jobs start
+with, and what they may spend, is the user's own setting:
+
+```typescript
+await client.updateJobSettings({ allowanceUsd: 5, autonomy: "ask", alwaysAsk: ["spending money"] });
+```
+
+## Outreach
+
+Outreach is what Alfred has told or asked this user outside a chat. The record is the inbox —
+there is no separate notification — so a question a job is parked on is a delivery with
+`intent: "question"` and no `answered`:
+
+```typescript
+const { deliveries } = await client.listDeliveries({ page: 1, limit: 20 });
+const { delivery, job } = await client.answerDelivery({ deliveryId, text: "The one in Gardens" });
+```
+
+Answering closes the delivery, and when it belongs to a job the answer is put on that job's
+inbox, which wakes a job that was parked waiting for it — `job.delivered` says what became of
+it. An approval takes `decision: "approve" | "deny"` alongside the text.
+
+### When a call fails
+
+Every jobs and outreach call throws `ButlerBotAPIError` when the server does not answer with a
+success. The status is on the error, so the cases worth branching on are told apart without
+reading a message, and the parsed body is kept — a rejected cancel still carries the job, a
+rejected answer still carries the delivery:
+
+```typescript
+import { ButlerBotAPIError } from "@butlerbot/sdk";
+
+try {
+    await client.cancelJob({ jobId });
+} catch (error) {
+    if (error instanceof ButlerBotAPIError && error.isConflict) {
+        // 409: it had already finished. `error.body.job` is how it settled.
+    } else throw error;
+}
+```
+
+`isNotFound` (404), `isConflict` (409) and `isBadRequest` (400) are the three; `status`,
+`error` and `errormessage` are the server's own words. A job or delivery that is not this key's
+is answered exactly as one that does not exist, so a 404 means either.
+
 ## Environment
 
 Node 18+. Node 22 and every browser have a built-in WebSocket; on older Node, install