@pipelex/sdk 0.58.0 → 0.59.0

package/dist/cli/script.d.ts

@@ -15,7 +15,7 @@ import type { CommandIO } from "./io.js";
  * update notice and npm 12's run notices off the script's stderr, which carries the command's
  * own lines, while npm's warnings and errors still print.
  */
-export declare const SCRIPT_RUNNER = "npx --yes --no-update-notifier --loglevel=warn @pipelex/sdk@0.58.0";
+export declare const SCRIPT_RUNNER = "npx --yes --no-update-notifier --loglevel=warn @pipelex/sdk@0.59.0";
 export declare const SCRIPT_WRITER = "@pipelex/sdk";
 export declare const SCRIPT_NEEDS = "Node 22.12 or later";
 /** Run `pipelex-sdk script` and return its exit code. */

package/dist/client.d.ts

@@ -4,6 +4,7 @@ import { type GetRunResultOptions, type RunProgress, type RunRead, type RunResul
 import type { BillingPortalResponse, ChangePlanResponse, CheckoutResponse, DraftFileFromFileInput, DraftFileFromFileResult, FileArchive, FileArchiveRequest, FileDetail, FileLinkTarget, FileLinksResult, FilePage, FileRecord, FileRecordList, FileRenameInput, FileSummary, GetFileQuery, GetFilesByUriOptions, InvoiceView, Membership, MembershipsResponse, OrganizationBranding, OrganizationBrandingUpdate, ListFilesQuery, ListMethodCopiesQuery, ListMethodExamplesQuery, ListMethodsQuery, ListMethodVersionsQuery, ListRunFilesQuery, MethodCopyInput, MethodCopyPage, MethodCopyResult, MethodData, MethodDeletionAccepted, MethodDetail, MethodDraftInput, MethodExample, MethodExampleAssistantSaveInput, MethodExampleAssistantSaveResult, MethodExampleCreateInput, MethodExampleLatestRunInput, MethodExampleLatestRunResult, MethodExamplePage, MethodExampleUpdateInput, MethodPage, MethodPublishInput, MethodPublishResult, MethodRenameInput, MethodSummary, MethodVersion, MethodVersionPage, MethodWriteInput, OnboardingSubmission, PipelexApiKeyCreated, PipelexApiKeyList, ListRunsQuery, RunHistoryItem, RunDetail, RunFilesPage, RunPage, PlanView, ResolvedStorageUrl, SavedMethodFile, SubscriptionResponse, UpdateRunInput, UploadGrant, UploadGrantInput, UploadInput, UploadedFile, UserProfile } from "./product-models.js";
 import type { MethodTreeForms, MethodTreeLimits } from "./method-trees.js";
 import type { AppInfo } from "./user-agent.js";
+import type { WebhookDeliveryDetail, WebhookDeliveryList, WebhookReplayAccepted, WebhookSecret, WebhookSecretRotateOptions } from "./webhooks.js";
 import type { UploadableAsset, UploadFileOptions, UploadRecord } from "./upload.js";
 import type { PrepareInputsRequest, PreparedInputs } from "./prepare-inputs.js";
 import type { BulkResolveStorageUrlsInput, BulkResolvedStorageUrls, DownloadArtifactsRequest, DownloadArtifactsResult, FetchArtifactOptions, ResolvedArtifact } from "./artifacts.js";
@@ -37,6 +38,27 @@ export interface PipelexApiRunExtensions {
      * An empty string is treated as absent and is not sent.
      */
     method_ref?: string | null;
+    /**
+     * Webhook URLs to call once the run has ended, each with a signed `run.finished` event whose
+     * `data` is the run's status read, so a caller learns of the end without polling. Read the call
+     * with `verifyWebhook`, then fetch the results with the event's `pipeline_run_id`; see
+     * `docs/webhooks.md`.
+     *
+     * A layer-2 extension: the hosted API and a self-hosted runner both take it on `start` and
+     * `execute`, and each holds the URLs to its own rules, which this client does not restate. The
+     * hosted API takes at most 5 HTTPS URLs of at most 2,048 characters, none repeated, and refuses a
+     * URL whose host resolves to a private, loopback, link-local or metadata address with a `422`
+     * `request.invalid` naming it as `callback_urls.<index>`; a deployment that does not deliver
+     * caller webhooks refuses the list with a `422` `request.unsupported`. A self-hosted runner
+     * whose operator configured no signing secret refuses it with a `422`
+     * `pipelex.webhook.secret_not_configured`. The start's acknowledgement and every read of the run
+     * list the URLs redacted, as `callback_urls`.
+     *
+     * Not a run source: a run still needs something to run. A value that is not an array of strings
+     * is a `RequestArgumentError` before anything is sent, and an empty array is treated as absent
+     * and is not sent.
+     */
+    callback_urls?: readonly string[] | null;
 }
 /**
  * The hosted API's own run arguments — the layer-3 extensions this client adds
@@ -1557,6 +1579,31 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * the write may have landed or not: the same input sent again is safe.
      */
     updateOrganizationBranding(orgId: string, input: OrganizationBrandingUpdate): Promise<OrganizationBranding>;
+    /**
+     * The organization's webhook signing secret — `GET /v1/organizations/{org_id}/webhook-secret`:
+     * the `whsec_` secret every caller webhook of the organization is signed with, which a receiver
+     * hands to `verifyWebhook`. The platform generates it on this first read when the organization
+     * has none. Treat the answer as a credential: never log or cache it.
+     *
+     * An admin's route, from a web session only: the hosted gateway refuses an API key on it. Throws
+     * `ApiResponseError`: `403` `auth.forbidden` whose `params.requirement` names `admin` for any
+     * other role, `403` `pipelex.org.mismatch` for an organization other than the caller's active
+     * one, and `404` `pipelex.org.not_found` for one with no record.
+     */
+    getWebhookSecret(orgId: string): Promise<WebhookSecret>;
+    /**
+     * Rotate the organization's webhook signing secret — `POST
+     * /v1/organizations/{org_id}/webhook-secret/rotate`: a new secret is current at once, and the
+     * one it replaces keeps signing beside it for 24 hours, then is dropped, so a receiver has a day
+     * to take the new one. An organization with no secret yet gets its first. Answers the new secret,
+     * as `getWebhookSecret` does, with its guards and refusals.
+     *
+     * `options.idempotencyKey` is sent as the `Idempotency-Key` header. The answer carries a secret,
+     * so the platform never replays it: the same key sent again is refused `409`
+     * `request.already_executed` and rotates nothing more, and the secret is then read with
+     * `getWebhookSecret`. A malformed key is a `RequestArgumentError` before anything is sent.
+     */
+    rotateWebhookSecret(orgId: string, options?: WebhookSecretRotateOptions): Promise<WebhookSecret>;
     /** The active org's subscription state — `GET /v1/billing/subscription`. */
     getSubscription(): Promise<SubscriptionResponse>;
     /** Available plans (with `is_current`) — `GET /v1/billing/plans`. */
@@ -2066,6 +2113,50 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * string nor `null`, is an answer the SDK cannot read, thrown as an `ApiResponseError` too.
      */
     listRunFiles(runId: string, query?: ListRunFilesQuery): Promise<RunFilesPage>;
+    /**
+     * A run's caller-webhook deliveries — `GET /v1/runs/{id}/webhook-deliveries`: one per URL the
+     * run registered in `callback_urls`, in their order, once the run has ended, each with its
+     * state and every attempt, its URL redacted. A run that registered none, or has not ended, lists
+     * none. Any member of the organization reads them, by web session or API key.
+     *
+     * Throws `RequestArgumentError` for a run id that is empty, `.` or `..`, or holds a lone
+     * surrogate, before any request. Throws `ApiResponseError`: `404` `run.not_found` for a run that
+     * is not the organization's, exactly as for one that does not exist. An answer whose
+     * `deliveries` is not an array is an answer the SDK cannot read, thrown as an `ApiResponseError`
+     * too.
+     */
+    listRunWebhookDeliveries(runId: string): Promise<WebhookDeliveryList>;
+    /**
+     * One delivery of a run's webhooks, with its event as sent —
+     * `GET /v1/runs/{id}/webhook-deliveries/{delivery_id}`: the body of its latest attempt, which a
+     * receiver's log can be matched against byte for byte once written as compact JSON.
+     * `deliveryId` is the delivery's `delivery_id`, the receiver's `webhook-id`.
+     *
+     * Throws `RequestArgumentError` for an id that is empty, `.` or `..`, or holds a lone surrogate,
+     * before any request. Throws `ApiResponseError`: `404` `run.not_found` for a run the caller
+     * cannot read, and `422` `request.invalid` naming `delivery_id` for a delivery the run does not
+     * have.
+     */
+    getRunWebhookDelivery(runId: string, deliveryId: string): Promise<WebhookDeliveryDetail>;
+    /**
+     * Send a settled delivery again — `POST /v1/runs/{id}/webhook-deliveries/{delivery_id}/replay`:
+     * one new attempt under the same `webhook-id`, with the same `data`, the next `attempt`, a fresh
+     * timestamp, and the signatures of the secrets live when it is sent. A replay the receiver
+     * accepts marks the delivery `delivered`; one it does not leaves its state as it was, and the
+     * attempt is recorded either way. A replay never returns a delivery to `pending`. Anyone who
+     * can read the run asks for one, an API key included, under the organization's replay rate.
+     *
+     * Answers the attempt number the replay is sent under; a replay asked again before it is sent is
+     * that same attempt. Throws `RequestArgumentError` for an id that is empty, `.` or `..`, or holds
+     * a lone surrogate, before any request. Throws `ApiResponseError`: `404` `run.not_found` for a
+     * run the caller cannot read; `422` `request.invalid` naming `delivery_id` for a delivery the run
+     * does not have; `409` `pipelex.org.not_manageable` with the reason `webhook_delivery_pending`
+     * for a delivery still on its retry schedule, or `webhook_delivery_attempts_exhausted` for one
+     * holding the most attempts a delivery holds; `429` `account.rate_limited`, with its
+     * `retry_after`, past the organization's replay rate; and a `500` or `503` when the replay could
+     * not be queued, which then counts nothing against the rate.
+     */
+    replayRunWebhookDelivery(runId: string, deliveryId: string): Promise<WebhookReplayAccepted>;
     /** Patch a run's status (admin/manual) — `PUT /v1/runs/{id}`. */
     updateRun(runId: string, input: UpdateRunInput): Promise<void>;
     /**
@@ -2079,8 +2170,8 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
     /**
      * Blocking `POST /v1/execute` adapted onto `RunResults` — the bare-runner
      * path. Forwards every protocol field PLUS every extension surface: the
-     * runner-resolved `method_ref`, the hosted `method_id`, and the generic
-     * `extra` passthrough. An extension-only call (`{ extra }` with no
+     * runner-resolved `method_ref`, the run's `callback_urls`, the hosted
+     * `method_id`, and the generic `extra` passthrough. An extension-only call (`{ extra }` with no
      * pipe_code/bundle) or a vendor selector riding `extra` must survive this
      * path, not just the durable one — a `method_ref` run must run the same
      * fetched package here, and a hosted `method_id` must reach the server too,

package/dist/client.js

@@ -240,6 +240,10 @@ const ARCHIVE_ID_ARGUMENT = {
     name: "archive_id",
     what: "an archive id, the archive's non-empty `archive_id`",
 };
+const DELIVERY_ID_ARGUMENT = {
+    name: "delivery_id",
+    what: "a delivery id, the delivery's non-empty `delivery_id`",
+};
 /** What the run id of each example write is, as a refusal of it names it. */
 const CREATE_RUN_ID_ARGUMENT = {
     name: "run_id",
@@ -2939,6 +2943,39 @@ export class PipelexApiClient {
         const segment = idPathSegment(orgId, "updateOrganizationBranding", ORG_ID_ARGUMENT);
         return this.requestProductObject("PATCH", `organizations/${segment}/branding`, input);
     }
+    /**
+     * The organization's webhook signing secret — `GET /v1/organizations/{org_id}/webhook-secret`:
+     * the `whsec_` secret every caller webhook of the organization is signed with, which a receiver
+     * hands to `verifyWebhook`. The platform generates it on this first read when the organization
+     * has none. Treat the answer as a credential: never log or cache it.
+     *
+     * An admin's route, from a web session only: the hosted gateway refuses an API key on it. Throws
+     * `ApiResponseError`: `403` `auth.forbidden` whose `params.requirement` names `admin` for any
+     * other role, `403` `pipelex.org.mismatch` for an organization other than the caller's active
+     * one, and `404` `pipelex.org.not_found` for one with no record.
+     */
+    async getWebhookSecret(orgId) {
+        const segment = idPathSegment(orgId, "getWebhookSecret", ORG_ID_ARGUMENT);
+        return this.requestProductObject("GET", `organizations/${segment}/webhook-secret`);
+    }
+    /**
+     * Rotate the organization's webhook signing secret — `POST
+     * /v1/organizations/{org_id}/webhook-secret/rotate`: a new secret is current at once, and the
+     * one it replaces keeps signing beside it for 24 hours, then is dropped, so a receiver has a day
+     * to take the new one. An organization with no secret yet gets its first. Answers the new secret,
+     * as `getWebhookSecret` does, with its guards and refusals.
+     *
+     * `options.idempotencyKey` is sent as the `Idempotency-Key` header. The answer carries a secret,
+     * so the platform never replays it: the same key sent again is refused `409`
+     * `request.already_executed` and rotates nothing more, and the secret is then read with
+     * `getWebhookSecret`. A malformed key is a `RequestArgumentError` before anything is sent.
+     */
+    async rotateWebhookSecret(orgId, options = {}) {
+        const endpoint = `organizations/${idPathSegment(orgId, "rotateWebhookSecret", ORG_ID_ARGUMENT)}/webhook-secret/rotate`;
+        const idempotencyKey = idempotencyKeyOf(options, "rotate the secret");
+        const res = await this.requestProductAnswer("POST", endpoint, undefined, { idempotencyKey });
+        return this.readObjectAnswer("POST", endpoint, res);
+    }
     /** The active org's subscription state — `GET /v1/billing/subscription`. */
     async getSubscription() {
         return this.requestProduct("GET", "billing/subscription");
@@ -3669,6 +3706,69 @@ export class PipelexApiClient {
         }
         return { ...rest, nextCursor };
     }
+    /**
+     * A run's caller-webhook deliveries — `GET /v1/runs/{id}/webhook-deliveries`: one per URL the
+     * run registered in `callback_urls`, in their order, once the run has ended, each with its
+     * state and every attempt, its URL redacted. A run that registered none, or has not ended, lists
+     * none. Any member of the organization reads them, by web session or API key.
+     *
+     * Throws `RequestArgumentError` for a run id that is empty, `.` or `..`, or holds a lone
+     * surrogate, before any request. Throws `ApiResponseError`: `404` `run.not_found` for a run that
+     * is not the organization's, exactly as for one that does not exist. An answer whose
+     * `deliveries` is not an array is an answer the SDK cannot read, thrown as an `ApiResponseError`
+     * too.
+     */
+    async listRunWebhookDeliveries(runId) {
+        const segment = idPathSegment(runId, "listRunWebhookDeliveries", RUN_ID_ARGUMENT);
+        const endpoint = `runs/${segment}/webhook-deliveries`;
+        const res = await this.requestProductAnswer("GET", endpoint, undefined);
+        const list = this.readObjectAnswer("GET", endpoint, res);
+        if (!Array.isArray(list.deliveries)) {
+            throw this.unreadableAnswer("GET", `/${API_PREFIX}/${endpoint}`, res, "a run's deliveries whose `deliveries` is not an array");
+        }
+        return list;
+    }
+    /**
+     * One delivery of a run's webhooks, with its event as sent —
+     * `GET /v1/runs/{id}/webhook-deliveries/{delivery_id}`: the body of its latest attempt, which a
+     * receiver's log can be matched against byte for byte once written as compact JSON.
+     * `deliveryId` is the delivery's `delivery_id`, the receiver's `webhook-id`.
+     *
+     * Throws `RequestArgumentError` for an id that is empty, `.` or `..`, or holds a lone surrogate,
+     * before any request. Throws `ApiResponseError`: `404` `run.not_found` for a run the caller
+     * cannot read, and `422` `request.invalid` naming `delivery_id` for a delivery the run does not
+     * have.
+     */
+    async getRunWebhookDelivery(runId, deliveryId) {
+        const call = "getRunWebhookDelivery";
+        const run = idPathSegment(runId, call, RUN_ID_ARGUMENT);
+        const delivery = idPathSegment(deliveryId, call, DELIVERY_ID_ARGUMENT);
+        return this.requestProductObject("GET", `runs/${run}/webhook-deliveries/${delivery}`);
+    }
+    /**
+     * Send a settled delivery again — `POST /v1/runs/{id}/webhook-deliveries/{delivery_id}/replay`:
+     * one new attempt under the same `webhook-id`, with the same `data`, the next `attempt`, a fresh
+     * timestamp, and the signatures of the secrets live when it is sent. A replay the receiver
+     * accepts marks the delivery `delivered`; one it does not leaves its state as it was, and the
+     * attempt is recorded either way. A replay never returns a delivery to `pending`. Anyone who
+     * can read the run asks for one, an API key included, under the organization's replay rate.
+     *
+     * Answers the attempt number the replay is sent under; a replay asked again before it is sent is
+     * that same attempt. Throws `RequestArgumentError` for an id that is empty, `.` or `..`, or holds
+     * a lone surrogate, before any request. Throws `ApiResponseError`: `404` `run.not_found` for a
+     * run the caller cannot read; `422` `request.invalid` naming `delivery_id` for a delivery the run
+     * does not have; `409` `pipelex.org.not_manageable` with the reason `webhook_delivery_pending`
+     * for a delivery still on its retry schedule, or `webhook_delivery_attempts_exhausted` for one
+     * holding the most attempts a delivery holds; `429` `account.rate_limited`, with its
+     * `retry_after`, past the organization's replay rate; and a `500` or `503` when the replay could
+     * not be queued, which then counts nothing against the rate.
+     */
+    async replayRunWebhookDelivery(runId, deliveryId) {
+        const call = "replayRunWebhookDelivery";
+        const run = idPathSegment(runId, call, RUN_ID_ARGUMENT);
+        const delivery = idPathSegment(deliveryId, call, DELIVERY_ID_ARGUMENT);
+        return this.requestProductObject("POST", `runs/${run}/webhook-deliveries/${delivery}/replay`);
+    }
     /** Patch a run's status (admin/manual) — `PUT /v1/runs/{id}`. */
     async updateRun(runId, input) {
         const segment = idPathSegment(runId, "updateRun", RUN_ID_ARGUMENT);
@@ -3685,6 +3785,8 @@ export class PipelexApiClient {
         const extensions = buildExtensions(options.extra);
         const api = buildApiRunExtensions(options);
         const hosted = buildHostedRunExtensions(options);
+        // Not a run source, so outside `api`, whose size the precondition below reads.
+        const webhooks = buildCallbackUrls(call, options);
         const forms = protocolTreeForms(call, options);
         const treeForms = treeFormsGiven(forms);
         if (!options.pipe_code &&
@@ -3696,13 +3798,13 @@ export class PipelexApiClient {
         }
         assertMethodRefPairsWithNothing(options, treeForms);
         assertLinkageMethodIdIsBare(options, treeForms);
-        return { forms, extensions, api, hosted };
+        return { forms, extensions, api, hosted, webhooks };
     }
     /**
      * Blocking `POST /v1/execute` adapted onto `RunResults` — the bare-runner
      * path. Forwards every protocol field PLUS every extension surface: the
-     * runner-resolved `method_ref`, the hosted `method_id`, and the generic
-     * `extra` passthrough. An extension-only call (`{ extra }` with no
+     * runner-resolved `method_ref`, the run's `callback_urls`, the hosted
+     * `method_id`, and the generic `extra` passthrough. An extension-only call (`{ extra }` with no
      * pipe_code/bundle) or a vendor selector riding `extra` must survive this
      * path, not just the durable one — a `method_ref` run must run the same
      * fetched package here, and a hosted `method_id` must reach the server too,
@@ -3724,6 +3826,8 @@ export class PipelexApiClient {
             tree: options.tree ?? undefined,
             files: options.files ?? undefined,
             method_ref: options.method_ref ?? undefined,
+            // A runner calls the run's webhooks once the blocking run has ended, as the platform does.
+            callback_urls: options.callback_urls ?? undefined,
             method_id: options.method_id ?? undefined,
             extra: options.extra ?? undefined,
         }, signal, sending);
@@ -3798,12 +3902,12 @@ const PROTOCOL_REQUEST_KEYS = [
     "dynamic_output_concept_ref",
     "files",
 ];
-// The PIPELEX API's own request field — the layer-2 extension the runner reads
-// itself (`method_ref`, a run source in its own right). Reserved on `extra` for
-// the same reason the protocol fields are: `extra` merges last, so a smuggled
-// copy would overwrite the validated named option and bypass the
-// selector-exclusivity check.
-const PIPELEX_API_REQUEST_KEYS = ["method_ref"];
+// The PIPELEX API's own request fields — the layer-2 extensions the runner reads
+// itself: `method_ref`, a run source in its own right, and `callback_urls`, the
+// webhooks to call once the run has ended. Reserved on `extra` for the same
+// reason the protocol fields are: `extra` merges last, so a smuggled copy would
+// overwrite the validated named option and bypass its checks.
+const PIPELEX_API_REQUEST_KEYS = ["method_ref", "callback_urls"];
 // The HOSTED API's own request fields — the layer-3 extensions this client
 // names itself. Reserved on `extra` for the same reason the protocol fields
 // are: `extra` merges last, so a smuggled copy would overwrite the validated
@@ -3906,6 +4010,7 @@ function runRequestBody(call, options, files, parts) {
             : options.dynamic_output_concept_ref,
         files: files ?? undefined,
         ...parts.api,
+        ...parts.webhooks,
         ...parts.hosted,
         ...parts.extensions,
     };
@@ -3986,6 +4091,29 @@ function buildApiRunExtensions(options) {
     const methodRef = nonEmptyString(options.method_ref);
     return methodRef === undefined ? {} : { method_ref: methodRef };
 }
+/**
+ * Copy a run's `callback_urls` onto the wire body, `call` naming the caller's method in a refusal.
+ * An absent, `null` or empty list yields an empty object, so the key is not sent, as the platform
+ * treats an empty list as absent. A value that is not an array, or an array holding anything but
+ * strings, is refused before anything is sent; the URLs themselves are the server's to judge,
+ * since the hosted API and a self-hosted runner each hold them to their own rules. The Python SDK
+ * reads the argument the same way.
+ */
+function buildCallbackUrls(call, options) {
+    const urls = options.callback_urls;
+    if (urls == null)
+        return {};
+    if (!Array.isArray(urls)) {
+        throw new RequestArgumentError(`${call}() takes callback_urls as an array of URLs; got ${typeof urls}.`, { problem: argumentInvalidProblem("callback_urls", "not_a_list") });
+    }
+    const copy = [...urls];
+    if (copy.some((url) => typeof url !== "string")) {
+        throw new RequestArgumentError(`${call}() takes each of callback_urls as a string URL.`, {
+            problem: argumentInvalidProblem("callback_urls", "not_a_string"),
+        });
+    }
+    return copy.length === 0 ? {} : { callback_urls: copy };
+}
 /**
  * Copy the hosted API's own run arguments onto the wire body. Named options,
  * not `extra` entries — see `PipelexHostedRunExtensions`.