@butlerbot/sdk 0.0.38 → 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 SetPhaseModelOptions, 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,6 +52,8 @@ 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 */
@@ -72,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,6 +88,10 @@ 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));
@@ -123,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, JobPhaseModelResponse, 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. */
@@ -62,6 +65,15 @@ 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>;
 /**

package/dist/modules/jobs.js

@@ -4,6 +4,7 @@ exports.listJobs = listJobs;
 exports.getJob = getJob;
 exports.getJobJournal = getJobJournal;
 exports.cancelJob = cancelJob;
+exports.resumeJob = resumeJob;
 exports.updateJob = updateJob;
 exports.setPhaseModel = setPhaseModel;
 exports.updateJobSettings = updateJobSettings;
@@ -51,6 +52,18 @@ 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 });

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

@@ -220,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.38",
+	"version": "0.0.39",
 	"description": "The official ButlerBot SDK",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",

package/readme.md

@@ -335,6 +335,7 @@ const { entries, hasMore } = await client.getJobJournal({ jobId, page: 2 });
 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,
@@ -343,6 +344,10 @@ an older page exists. Each entry says which shift wrote it (`shiftIndex`, `shift
 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