@butlerbot/sdk 0.0.37 → 0.0.39

package/dist/config.d.ts

@@ -60,7 +60,7 @@ export declare const CONFIG: {
             };
         };
         jobs: {
-            /** The collection. One job is `${base}/${jobId}`, its cancel `${base}/${jobId}/cancel`. */
+            /** The collection. One job is `${base}/${jobId}`, its cancel `${base}/${jobId}/cancel` and its resume `${base}/${jobId}/resume`. */
             base: string;
             /** The owner's job settings, which live on the user rather than on a job. */
             settings: string;

package/dist/config.js

@@ -52,7 +52,7 @@ exports.CONFIG = {
             }
         },
         jobs: {
-            /** The collection. One job is `${base}/${jobId}`, its cancel `${base}/${jobId}/cancel`. */
+            /** The collection. One job is `${base}/${jobId}`, its cancel `${base}/${jobId}/cancel` and its resume `${base}/${jobId}/resume`. */
             base: "/api/jobs",
             /** The owner's job settings, which live on the user rather than on a job. */
             settings: "/api/user/jobs-settings",

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import { APIPath } from "./config";
 import { Link, LinkOptions } from "./link";
 import { Conversation, ConversationOptions } from "./modules/conversation";
 import { UsagePolicyDataOptions } from "./modules/usage";
-import { type CancelJobOptions, type GetJobJournalOptions, type GetJobOptions, type ListJobsOptions, type UpdateJobOptions, type UpdateJobSettingsOptions } from "./modules/jobs";
+import { type CancelJobOptions, type GetJobJournalOptions, type GetJobOptions, type SetPhaseModelOptions, type ListJobsOptions, type ResumeJobOptions, 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 */
@@ -52,8 +52,12 @@ export declare class ButlerBotClient {
     getJobJournal(config: OptionalApiKey<GetJobJournalOptions>): Promise<import("./types/type_registry").JobJournalPage>;
     /** Stops a job. Throws a `ButlerBotAPIError` with `isConflict` when it had already finished */
     cancelJob(config: OptionalApiKey<CancelJobOptions>): Promise<import("./types/type_registry").JobCancelResponse>;
+    /** Continues a job parked waiting for budget. Throws a `ButlerBotAPIError` with `isConflict` when it is in any other status */
+    resumeJob(config: OptionalApiKey<ResumeJobOptions>): Promise<import("./types/type_registry").JobResumeResponse>;
     /** Changes one job's name, and its 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 the model one phase of a job's plan runs on; only a phase that has not started */
+    setPhaseModel(config: OptionalApiKey<SetPhaseModelOptions>): Promise<import("./types/type_registry").JobPhaseModelResponse>;
     /** 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 */
@@ -70,8 +74,8 @@ 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 { listJobs, getJob, cancelJob, resumeJob, updateJob, updateJobSettings } from "./modules/jobs";
+export type { JobsRequestOptions, ListJobsOptions, GetJobOptions, CancelJobOptions, ResumeJobOptions, 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";

package/dist/index.js

@@ -14,7 +14,7 @@ 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.answerDelivery = exports.listDeliveries = exports.updateJobSettings = exports.updateJob = exports.cancelJob = exports.getJob = exports.listJobs = exports.ButlerBotAPIError = exports.Conversation = exports.ButlerBotClient = void 0;
+exports.SSEConversationTransport = exports.LinkConversationTransport = exports.answerDelivery = exports.listDeliveries = exports.updateJobSettings = exports.updateJob = exports.resumeJob = 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");
@@ -88,10 +88,18 @@ class ButlerBotClient {
     cancelJob(config) {
         return (0, jobs_1.cancelJob)(this.forRequest(config));
     }
+    /** Continues a job parked waiting for budget. Throws a `ButlerBotAPIError` with `isConflict` when it is in any other status */
+    resumeJob(config) {
+        return (0, jobs_1.resumeJob)(this.forRequest(config));
+    }
     /** Changes one job's name, and its 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 the model one phase of a job's plan runs on; only a phase that has not started */
+    setPhaseModel(config) {
+        return (0, jobs_1.setPhaseModel)(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));
@@ -119,6 +127,7 @@ 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, "resumeJob", { enumerable: true, get: function () { return jobs_2.resumeJob; } });
 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");

package/dist/modules/jobs.d.ts

@@ -1,4 +1,4 @@
-import type { JobAutonomy, JobCancelResponse, JobDetailResponse, JobJournalPage, JobListResponse, JobSettingsResponse, JobSettingsUpdate, JobStatus, JobUpdateResponse } from "../types/jobs";
+import type { JobAutonomy, JobCancelResponse, JobDetailResponse, JobJournalPage, JobListResponse, JobPhaseModelResponse, JobResumeResponse, 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;
@@ -28,6 +28,9 @@ export type GetJobJournalOptions = JobsRequestOptions & {
 export type CancelJobOptions = JobsRequestOptions & {
     jobId: string;
 };
+export type ResumeJobOptions = JobsRequestOptions & {
+    jobId: string;
+};
 export type UpdateJobOptions = JobsRequestOptions & {
     jobId: string;
     /** A new short name for the job, a few words at most. */
@@ -38,6 +41,15 @@ export type UpdateJobOptions = JobsRequestOptions & {
     autonomyUntil?: string | number | null;
     /** Things this job asks about however free it otherwise is. */
     alwaysAsk?: string[];
+    /** A ceiling on what the job may spend in all, in dollars. Null clears it. */
+    capUsd?: number | null;
+};
+export type SetPhaseModelOptions = JobsRequestOptions & {
+    jobId: string;
+    /** The phase's id as the plan names it. */
+    phaseId: string;
+    /** One of the detail's `phaseModels`. */
+    model: string;
 };
 export type UpdateJobSettingsOptions = JobsRequestOptions & JobSettingsUpdate;
 /** A page of the caller's jobs, newest first, with what their jobs may spend today. */
@@ -53,7 +65,23 @@ export declare function getJobJournal(options: GetJobJournalOptions): Promise<Jo
  * `isConflict` is true and whose `body` still carries the job as it stands.
  */
 export declare function cancelJob(options: CancelJobOptions): Promise<JobCancelResponse>;
+/**
+ * Continues a job that is parked waiting for budget, when there is room for it again.
+ *
+ * The answer says what happened either way: `resumed` is the job queued again, and otherwise
+ * `reason`, `action` and `message` say why it is still parked and what would change that. A
+ * job in any other status 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 resumeJob(options: ResumeJobOptions): Promise<JobResumeResponse>;
 /** Changes one job's name, and its autonomy: how far it may act, until when, and what it always asks about. */
 export declare function updateJob(options: UpdateJobOptions): Promise<JobUpdateResponse>;
+/**
+ * Changes the model one phase of a job's plan runs on.
+ *
+ * Only a phase that has not started or is blocked: a running or done phase's model is what its
+ * work ran on. A model the owner's plan cannot run is a 400 whose body names the ones it can.
+ */
+export declare function setPhaseModel(options: SetPhaseModelOptions): Promise<JobPhaseModelResponse>;
 /** 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

@@ -4,7 +4,9 @@ exports.listJobs = listJobs;
 exports.getJob = getJob;
 exports.getJobJournal = getJobJournal;
 exports.cancelJob = cancelJob;
+exports.resumeJob = resumeJob;
 exports.updateJob = updateJob;
+exports.setPhaseModel = setPhaseModel;
 exports.updateJobSettings = updateJobSettings;
 const config_1 = require("../config");
 const url_formatter_1 = require("../util/url_formatter");
@@ -50,16 +52,43 @@ 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}` });
 }
+/**
+ * Continues a job that is parked waiting for budget, when there is room for it again.
+ *
+ * The answer says what happened either way: `resumed` is the job queued again, and otherwise
+ * `reason`, `action` and `message` say why it is still parked and what would change that. A
+ * job in any other status is a 409: the call throws a `ButlerBotAPIError` whose `isConflict`
+ * is true and whose `body` still carries the job as it stands.
+ */
+async function resumeJob(options) {
+    const url = (0, url_formatter_1.formatURL)(`${jobsBase(options)}/${encodeURIComponent(options.jobId)}/resume`, {}, { apiKey: options.apiKey, debug: options.debug });
+    return (0, api_request_1.requestAPI)({ url, method: "POST", action: `resume job ${options.jobId}` });
+}
 /** Changes one job's name, and its 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({ title: options.title, autonomy: options.autonomy, autonomyUntil: options.autonomyUntil, alwaysAsk: options.alwaysAsk }),
+        body: body({ title: options.title, autonomy: options.autonomy, autonomyUntil: options.autonomyUntil, alwaysAsk: options.alwaysAsk, capUsd: options.capUsd }),
         action: `update job ${options.jobId}`,
     });
 }
+/**
+ * Changes the model one phase of a job's plan runs on.
+ *
+ * Only a phase that has not started or is blocked: a running or done phase's model is what its
+ * work ran on. A model the owner's plan cannot run is a 400 whose body names the ones it can.
+ */
+async function setPhaseModel(options) {
+    const url = (0, url_formatter_1.formatURL)(`${jobsBase(options)}/${encodeURIComponent(options.jobId)}/plan/${encodeURIComponent(options.phaseId)}`, {}, { apiKey: options.apiKey, debug: options.debug });
+    return (0, api_request_1.requestAPI)({
+        url,
+        method: "PATCH",
+        body: { model: options.model },
+        action: `set the model of phase ${options.phaseId} of 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);

package/dist/types/jobs/job.d.ts

@@ -31,6 +31,13 @@ export type JobView = {
     reviewRounds: number;
     /** What the job has spent in total, in USD. */
     spentUsd: number;
+    /**
+     * A ceiling on what this job may spend over its whole life, in dollars, or null for none.
+     *
+     * Measured against everything the job and its sub-jobs have spent. A job that reaches it
+     * with work left parks blocked and asks; raising it starts the job again.
+     */
+    capUsd: number | null;
     /** What the job has spent today, in USD. */
     spendTodayUsd: number;
     /** How many questions of this job's are waiting on the user. */
@@ -73,7 +80,7 @@ export type JobAllowanceRefused = {
 export type JobAllowance = JobAllowanceGranted | JobAllowanceRefused;
 /** Whether an allowance is a refusal rather than a grant. */
 export declare function isJobAllowanceRefused(allowance: JobAllowance): allowance is JobAllowanceRefused;
-export type JobPlanPhaseKind = "plan" | "work" | "review";
+export type JobPlanPhaseKind = "plan" | "work" | "map" | "review";
 export type JobPlanPhaseStatus = "pending" | "running" | "blocked" | "done";
 /** One phase of a job's plan, as the plan card spells it out. */
 export type JobPlanPhase = {
@@ -182,6 +189,13 @@ export type JobDetailResponse = {
     journalTotal: number;
     /** Questions of this job's nobody has answered yet. */
     openDeliveries: Delivery[];
+    /** The model names a phase of this job may be set to: the aliases first, then the tier's models. */
+    phaseModels: string[];
+};
+/** A phase after its model was changed. */
+export type JobPhaseModelResponse = {
+    success: true;
+    phase: JobPlanPhase;
 };
 /** One page of a job's journal. Page 1 is the newest; within a page the entries are in written order. */
 export type JobJournalPage = {
@@ -206,3 +220,29 @@ export type JobSettingsResponse = {
     success: true;
     jobs: JobSettings;
 };
+/**
+ * Why a resume answered as it did.
+ *
+ * `resumed` is the job queued again; the rest are why it was left where it is — the owner's
+ * tier does not allow the job to run, today's allowance is spent, or the server refused for a
+ * reason of its own.
+ */
+export type JobResumeReason = "resumed" | "over_tier_limit" | "allowance_spent" | "refused";
+/** What the user can do about a job that was not resumed. */
+export type JobResumeAction = "raise_allowance" | "upgrade_tier" | "wait";
+/**
+ * A job after a resume was asked for.
+ *
+ * `resumed` says whether it is queued again; when it is not, `reason` and `action` say why and
+ * what would change it, and `wakeAt` is the earliest the runner would pick it up on its own,
+ * in epoch milliseconds. `message` is the same thing in a sentence or two, ready to show.
+ */
+export type JobResumeResponse = {
+    success: true;
+    resumed: boolean;
+    reason: JobResumeReason;
+    action?: JobResumeAction;
+    wakeAt?: number;
+    message: string;
+    job: JobView;
+};

package/package.json

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

package/readme.md

@@ -332,14 +332,22 @@ const { jobs, allowance, spentTodayUsd } = await client.listJobs({ status: "runn
 const { job, plan, journal, journalTotal, openDeliveries, autonomyLine } = await client.getJob({ jobId });
 const { entries, hasMore } = await client.getJobJournal({ jobId, page: 2 });
 
-await client.updateJob({ jobId, title: "Flat hunt", autonomy: "free", autonomyUntil: Date.now() + 86_400_000 });
+await client.updateJob({ jobId, title: "Flat hunt", autonomy: "free", autonomyUntil: Date.now() + 86_400_000, capUsd: 5 });
+await client.setPhaseModel({ jobId, phaseId: "search", model: "Butler-Auto-Smart" });
 await client.cancelJob({ jobId });
+const { resumed, reason, action, message } = await client.resumeJob({ jobId });
 ```
 
 `getJob` carries the newest page of the journal and `journalTotal`; `getJobJournal` pages the rest,
 newest page first, with each page in the order its entries were written and `hasMore` saying whether
 an older page exists. Each entry says which shift wrote it (`shiftIndex`, `shiftKind`) and on which
-model. A job's `title` is a few words of its own, set at start or renamed with `updateJob`.
+model. A job's `title` is a few words of its own, set at start or renamed with `updateJob`, which
+also takes `capUsd`, a ceiling on what the job may spend in all (null clears it). `setPhaseModel`
+changes the model a phase that has not started runs on, to one of the detail's `phaseModels`.
+`resumeJob` continues a job parked as `waiting_budget` when there is room for it again: it answers
+with `resumed`, a `reason` of `resumed`, `over_tier_limit`, `allowance_spent` or `refused`, an
+`action` of `raise_allowance`, `upgrade_tier` or `wait` when there is one, a `wakeAt` when the job
+would carry on by itself, and a `message` written for the user. A job in any other status is a 409.
 
 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