checkly 9.5.0 → 10.0.0-rc.1

package/dist/rest/projects.d.ts

@@ -16,6 +16,135 @@ export interface Change {
     type: string;
     action: string;
 }
+/** The API's stand-in for a sensitive value in a reported change. */
+export interface DiffMaskedMarker {
+    $masked: 'same' | 'changed';
+}
+/**
+ * One property of one resource that a deploy would change, or has changed.
+ *
+ * `origin` says which side moved since the last deploy: `code` for a local
+ * edit, `remote` for one made outside the CLI (the web app, the API), `both`
+ * when the property moved on both sides — in which case `remote` carries the
+ * movement the deploy is about to overwrite. A value too large to inline is
+ * reported as a `{ $hash }` object rather than in the clear; under
+ * `detail: 'full'` the deployed text is in the entry's `before`, at the path
+ * the import format gives it (the same one for a script or a request body).
+ * A secret change (`secret: true`) carries its values with every sensitive
+ * position replaced by a `DiffMaskedMarker`, `changed` on the element whose
+ * secret moved on that side; never a value or a hash. A list holding an
+ * unmoved secret carries `same` markers without the flag.
+ * `cause` names the reason for a change with no user-facing property behind
+ * it, such as a new code bundle.
+ */
+export interface DiffChange {
+    path: string;
+    /**
+     * `unmanaged` marks an alert channel or private location attached to this
+     * project's check or group from outside the project: reported on the resource
+     * it belongs to, and only deleted with `--prune-relations`.
+     */
+    origin: 'code' | 'remote' | 'both' | 'unmanaged';
+    before?: unknown;
+    after?: unknown;
+    remote?: {
+        before?: unknown;
+        after?: unknown;
+    };
+    cause?: string;
+    /** Set when a sensitive value moved or a sensitive list element could not be matched; see `DiffMaskedMarker`. */
+    secret?: true;
+}
+/**
+ * One rule of the redaction table the API applies to an entry's `before`, as
+ * a JSON Pointer pattern (`*` for every list position) and the flag test on
+ * the holding element that decides it. The API reports the resource type's
+ * whole table, whatever the deployed row held, so the local side blanks by
+ * the same rules — a credential the code adds included.
+ */
+export interface DiffRedaction {
+    path: string;
+    /** What the rule blanks to: a `value` becomes the empty string, an `object` becomes null. */
+    kind: 'value' | 'object';
+    when?: 'locked' | 'lockedOrSecret';
+}
+/**
+ * A resource in a deploy plan or an applied deploy. `action` is CREATE,
+ * UPDATE, DELETE, DETACH (removed from code but kept in the account) or
+ * UNCHANGED.
+ */
+export interface DiffEntry extends Change {
+    origin?: 'code' | 'remote' | 'unmanaged';
+    /** Absent under `detail: 'summary'`. */
+    changes?: DiffChange[];
+    /**
+     * The resource as currently deployed, in the import format: the payload the
+     * import plan returns for it, references as physical ids, a check's or
+     * group's subscription and assignment rows on it, credential values blanked.
+     * Only under `detail: 'full'`, and only for a retained resource with a
+     * change to show.
+     */
+    before?: Record<string, unknown>;
+    /** With `before`: the type's redaction rule table, applied to it. */
+    redactions?: DiffRedaction[];
+    /**
+     * Set on a relation (an alert channel subscription, a private location
+     * assignment) whose change is reported as part of the check or group it
+     * belongs to, so a renderer can fold it into that resource instead of
+     * listing it separately.
+     */
+    foldedInto?: {
+        type: string;
+        logicalId: string;
+    };
+    /** The file Checkly has recorded for the resource, or null if none. */
+    sourceFile?: string | null;
+    /**
+     * `live` when Checkly had no usable state from an earlier planned deploy to
+     * compare the resource with (the project's first plan, the first after a
+     * deploy without one, a resource added with `checkly import`, or a stored
+     * state a Checkly update made unusable) and compared the code with the
+     * deployed resource instead. The deploy
+     * writes such a resource whatever the comparison found, to set the baseline
+     * for later plans, and `changes` is not exhaustive: a value the deployed
+     * resource holds on a property the code does not set is left out, although
+     * the write may reset it.
+     */
+    basis?: 'live';
+    /**
+     * On a check the deploy created, updated or kept, other than a heartbeat
+     * monitor: whether Checkly selected it to run right after the deploy. Only on
+     * a deploy's result, never on a preview or a dry run, and absent from an API
+     * that predates it.
+     */
+    scheduled?: boolean;
+    /**
+     * Why `scheduled` is false: the deploy did not ask for scheduling, it had
+     * more checks than the scheduling threshold allows, it left the check
+     * unchanged while scheduling changed checks only, or the check runs more
+     * often than the minimum frequency for scheduling on deploy.
+     */
+    scheduleSkippedReason?: 'NOT_REQUESTED' | 'THRESHOLD' | 'UNCHANGED' | 'MIN_FREQUENCY';
+}
+/**
+ * Which checks a deploy schedules: the ones it created or updated, or every
+ * check it deployed, the unchanged ones included.
+ */
+export type ScheduleOnDeployScope = 'changed' | 'all';
+/** How much of each change a preview reports. */
+export type ProjectPreviewDetail = 'summary' | 'changes' | 'full';
+export interface ProjectPreviewResponse {
+    /** The project as currently deployed; absent before its first deploy. */
+    project?: DeployedProject | null;
+    /**
+     * Opaque fingerprint of the Checkly-side state this plan was computed
+     * against. Passing it to a deploy makes that deploy refuse, rather than
+     * apply a different plan than the one that was reviewed, if anything moved
+     * in between.
+     */
+    planToken: string;
+    diff: DiffEntry[];
+}
 export interface ResourceSync {
     logicalId: string;
     physicalId?: string | number;
@@ -86,7 +215,14 @@ export interface DeployedProject extends Project {
 }
 export interface ProjectDeployResponse {
     project: DeployedProject;
-    diff: Array<Change>;
+    diff: Array<DiffEntry>;
+    /**
+     * Whether Checkly scheduled the deployed checks to run. Set by `deploy()`
+     * from the deployment; false when it was asked not to, and when the deploy
+     * had more checks than the scheduling threshold allows. Absent from an API
+     * that predates the threshold.
+     */
+    scheduled?: boolean;
 }
 export type ProjectDeploymentStatus = 'PENDING' | 'RUNNING' | 'SUCCEEDED' | 'FAILED' | 'CANCELLED';
 export interface ProjectDeployment {
@@ -102,6 +238,14 @@ export interface ProjectDeployment {
     } | null;
     /** The applied { project, diff }; present once the deployment has succeeded. */
     result: ProjectDeployResponse | null;
+    /**
+     * Whether the deploy schedules its checks. False when it was sent with
+     * scheduleOnDeploy=false, and when it had more checks than the scheduling
+     * threshold allows, which is decided from the applied diff: until the
+     * deployment has finished it is the request. Absent from an API that
+     * predates the threshold.
+     */
+    scheduleOnDeploy?: boolean;
     createdAt: string;
     startedAt: string | null;
     endedAt: string | null;
@@ -154,6 +298,57 @@ export declare class ProjectAlreadyExistsError extends Error {
 export declare class NoImportableResourcesFoundError extends Error {
     constructor(options?: ErrorOptions);
 }
+/**
+ * The plan a deploy was pinned to no longer describes Checkly's state: a
+ * change landed between the preview and the deploy, so the deploy applied
+ * nothing. `diff` is the plan as it looks now.
+ */
+export declare class ProjectPlanStaleError extends Error {
+    readonly diff: DiffEntry[];
+    constructor(message: string, diff: DiffEntry[], options?: ErrorOptions);
+}
+/**
+ * A deployment that was already running finished while this one waited for it.
+ * Whatever it wrote, it moved the state the plan was computed against, so the
+ * plan is stale before the deploy is even attempted — reported here rather
+ * than after re-sending the whole payload for a refusal that is certain.
+ *
+ * A subtype of {@link ProjectPlanStaleError}: callers recover from both the
+ * same way, by planning again. It carries no diff, because no new plan has
+ * been computed yet.
+ */
+export declare class ProjectPlanSupersededError extends ProjectPlanStaleError {
+    constructor(options?: ErrorOptions);
+}
+/**
+ * The preview could not be computed because another operation is holding the
+ * project. Transient: the operation holding it finishes.
+ */
+export declare class ProjectPreviewUnavailableError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * The account's Checkly API does not have the preview endpoint yet (a
+ * self-hosted or not-yet-updated backend). Callers fall back to the older,
+ * coarser deploy preview.
+ */
+export declare class ProjectPreviewNotSupportedError extends Error {
+    constructor(options?: ErrorOptions);
+}
+/**
+ * The account's Checkly API has deploy plans switched off at the moment. Unlike
+ * an API without the preview endpoint, it knows every payload field a planned
+ * deploy sends, so callers fall back to a deploy without a plan and leave the
+ * payload as it is.
+ */
+export declare class ProjectPlanDisabledError extends Error {
+    constructor(options?: ErrorOptions);
+}
+/**
+ * `code` of what the API answers with while plans are switched off: the 404 of
+ * the preview endpoint, and the 400 a deploy that needs a plan is refused with.
+ */
+export declare const DEPLOY_PLAN_DISABLED = "DEPLOY_PLAN_DISABLED";
 export declare class ImportPlanNotFoundError extends Error {
     constructor(options?: ErrorOptions);
 }
@@ -197,6 +392,26 @@ declare class Projects {
      * (the project does not exist) — a plain result with no deployment to follow.
      */
     private submitDeletion;
+    /**
+     * What deploying this payload would change, per resource and per property,
+     * without writing anything.
+     *
+     * The returned `planToken` pins the plan: pass it to {@link deploy} and the
+     * deploy refuses if Checkly's state moved in between. A code-side edit
+     * between the two is not such a move — the token describes Checkly's state,
+     * not the payload — so previewing, editing and deploying still works.
+     *
+     * @throws {ProjectPreviewNotSupportedError} If the API has no preview endpoint.
+     * @throws {ProjectPlanDisabledError} If the API has deploy plans switched off.
+     * @throws {ProjectPreviewUnavailableError} If the project stayed busy.
+     */
+    preview(resources: ProjectSync, { detail, preserveResources, pruneRelations, onStatus, }?: {
+        detail?: ProjectPreviewDetail;
+        preserveResources?: boolean;
+        pruneRelations?: boolean;
+        /** Human-readable status updates (e.g. while retrying behind another operation). */
+        onStatus?: (message: string) => void;
+    }): Promise<ProjectPreviewResponse>;
     /**
      * Deploy a project. The deployment runs asynchronously on the backend: this
      * submits it, then follows its progress stream to completion, so large projects
@@ -205,14 +420,45 @@ declare class Projects {
      *
      * @throws {ProjectDeployFailedError} If the deployment finishes unsuccessfully.
      */
-    deploy(resources: ProjectSync, { dryRun, scheduleOnDeploy, preserveResources, cancelInProgress, onProgress, onStatus, }?: {
+    deploy(resources: ProjectSync, { dryRun, scheduleOnDeploy, scheduleOnDeployScope, scheduleOnDeployThreshold, scheduleOnDeployMinFrequency, preserveResources, plan, pruneRelations, planToken, cancelInProgress, onProgress, onStatus, }?: {
         dryRun?: boolean;
         scheduleOnDeploy?: boolean;
+        /** Which checks to schedule: the changed ones, or every deployed check. */
+        scheduleOnDeployScope?: ScheduleOnDeployScope;
+        /**
+         * Schedule no checks if the deploy would schedule more than this many,
+         * not counting the ones the scope and the minimum frequency leave out.
+         * Without it Checkly applies its own threshold.
+         */
+        scheduleOnDeployThreshold?: number;
+        /**
+         * Leave out of scheduling the checks that run more often than every this
+         * many minutes. Without it Checkly applies its own minimum.
+         */
+        scheduleOnDeployMinFrequency?: number;
         /**
          * Keep resources removed from code (and their run history) in the account
          * instead of deleting them.
          */
         preserveResources?: boolean;
+        /**
+         * Apply a plan: compare every resource with what was last deployed and
+         * with its current state, and write only the ones that differ. Without
+         * it the deploy writes every resource. `pruneRelations` and `planToken`
+         * are refused by the API unless this is set.
+         */
+        plan?: boolean;
+        /**
+         * Delete the alert channel subscriptions and private location assignments
+         * on this project's checks and groups that the project does not manage.
+         */
+        pruneRelations?: boolean;
+        /**
+         * The `planToken` of the preview this deploy was reviewed against. The
+         * deploy is refused with {@link ProjectPlanStaleError}, having written
+         * nothing, if Checkly's state moved since that preview.
+         */
+        planToken?: string;
         /**
          * On a 409 (another deployment is already in progress), cancel that
          * deployment instead of waiting for it to finish, then retry.
@@ -230,8 +476,12 @@ declare class Projects {
      * optionally cancel it, then wait until it reaches a final state (or is gone)
      * before returning — so the caller re-POSTs only when the slot is actually
      * free, never re-uploading the payload while the predecessor is still running.
-     * Returns early if the overall `deadlineAt` passes (the caller then re-POSTs
-     * once and surfaces the conflict).
+     *
+     * @returns Whether the predecessor was observed to reach a final state.
+     * `false` means the wait hit its deadline with the predecessor still running,
+     * which is a different situation for the caller: nothing has changed, so a
+     * plan computed before the wait still stands, and re-POSTing surfaces the
+     * conflict the caller needs to hear about.
      */
     private resolveInProgressDeployment;
     getDeployment(logicalId: string, deploymentId: string): Promise<import("axios").AxiosResponse<ProjectDeployment, any, {}, any>>;

package/dist/rest/projects.js

@@ -2,6 +2,7 @@ import { isAxiosError } from 'axios';
 import { Readable } from 'node:stream';
 import { compressJSONPayload } from './util.js';
 import { ConflictError, ForbiddenError, handleErrorResponse, NotFoundError, RequestTimeoutError } from './errors.js';
+import { parseRetryAfter } from './retry.js';
 export class ProjectDeployFailedError extends Error {
     constructor(message, options) {
         super(message, options);
@@ -78,6 +79,74 @@ export class NoImportableResourcesFoundError extends Error {
         this.name = 'NoImportableResourcesFoundError';
     }
 }
+/**
+ * The plan a deploy was pinned to no longer describes Checkly's state: a
+ * change landed between the preview and the deploy, so the deploy applied
+ * nothing. `diff` is the plan as it looks now.
+ */
+export class ProjectPlanStaleError extends Error {
+    diff;
+    constructor(message, diff, options) {
+        super(message, options);
+        this.name = 'ProjectPlanStaleError';
+        this.diff = diff;
+    }
+}
+/**
+ * A deployment that was already running finished while this one waited for it.
+ * Whatever it wrote, it moved the state the plan was computed against, so the
+ * plan is stale before the deploy is even attempted — reported here rather
+ * than after re-sending the whole payload for a refusal that is certain.
+ *
+ * A subtype of {@link ProjectPlanStaleError}: callers recover from both the
+ * same way, by planning again. It carries no diff, because no new plan has
+ * been computed yet.
+ */
+export class ProjectPlanSupersededError extends ProjectPlanStaleError {
+    constructor(options) {
+        super('Another deployment of this project finished while this one was waiting for it, '
+            + 'so the plan this deploy was pinned to no longer describes your Checkly account.', [], options);
+        this.name = 'ProjectPlanSupersededError';
+    }
+}
+/**
+ * The preview could not be computed because another operation is holding the
+ * project. Transient: the operation holding it finishes.
+ */
+export class ProjectPreviewUnavailableError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'ProjectPreviewUnavailableError';
+    }
+}
+/**
+ * The account's Checkly API does not have the preview endpoint yet (a
+ * self-hosted or not-yet-updated backend). Callers fall back to the older,
+ * coarser deploy preview.
+ */
+export class ProjectPreviewNotSupportedError extends Error {
+    constructor(options) {
+        super('This Checkly API does not support deploy previews.', options);
+        this.name = 'ProjectPreviewNotSupportedError';
+    }
+}
+/**
+ * The account's Checkly API has deploy plans switched off at the moment. Unlike
+ * an API without the preview endpoint, it knows every payload field a planned
+ * deploy sends, so callers fall back to a deploy without a plan and leave the
+ * payload as it is.
+ */
+export class ProjectPlanDisabledError extends Error {
+    constructor(options) {
+        super('Checkly has deploy plans switched off at the moment.', options);
+        this.name = 'ProjectPlanDisabledError';
+    }
+}
+/**
+ * `code` of what the API answers with while plans are switched off: the 404 of
+ * the preview endpoint, and the 400 a deploy that needs a plan is refused with.
+ */
+export const DEPLOY_PLAN_DISABLED = 'DEPLOY_PLAN_DISABLED';
 export class ImportPlanNotFoundError extends Error {
     constructor(options) {
         super(`Import plan does not exist.`, options);
@@ -94,6 +163,13 @@ export class InvalidImportPlanStateError extends Error {
 // in-progress operation before giving up and surfacing the 409. Generous, since a
 // large predecessor deploy or delete can legitimately run for many minutes.
 const DEPLOY_CONFLICT_WAIT_DEADLINE_MS = 30 * 60_000;
+// A preview conflicts only while something else holds the project, which is
+// measured in seconds, so it is retried a few times rather than waited out
+// like a deploy's predecessor. The cap keeps a server asking for an
+// unreasonable wait from stalling the command instead of failing it.
+const PREVIEW_CONFLICT_ATTEMPTS = 3;
+const PREVIEW_RETRY_AFTER_DEFAULT_MS = 2_000;
+const PREVIEW_RETRY_AFTER_MAX_MS = 10_000;
 class Projects {
     api;
     constructor(api) {
@@ -185,6 +261,54 @@ class Projects {
             throw new ProjectDeployFailedError(completed.error?.message ?? 'The deletion did not complete successfully.');
         }
     }
+    /**
+     * What deploying this payload would change, per resource and per property,
+     * without writing anything.
+     *
+     * The returned `planToken` pins the plan: pass it to {@link deploy} and the
+     * deploy refuses if Checkly's state moved in between. A code-side edit
+     * between the two is not such a move — the token describes Checkly's state,
+     * not the payload — so previewing, editing and deploying still works.
+     *
+     * @throws {ProjectPreviewNotSupportedError} If the API has no preview endpoint.
+     * @throws {ProjectPlanDisabledError} If the API has deploy plans switched off.
+     * @throws {ProjectPreviewUnavailableError} If the project stayed busy.
+     */
+    async preview(resources, { detail = 'changes', preserveResources = false, pruneRelations = false, onStatus, } = {}) {
+        const query = new URLSearchParams({ detail });
+        // Only sent when opted in, like deploy's: false is the default and the
+        // endpoint's contract is easier to keep stable if the CLI omits defaults.
+        if (preserveResources) {
+            query.set('preserveResources', 'true');
+        }
+        if (pruneRelations) {
+            query.set('pruneRelations', 'true');
+        }
+        for (let attempt = 1;; attempt++) {
+            try {
+                const { data } = await this.api.post(`/v1/projects/preview?${query.toString()}`, resources, { transformRequest: compressJSONPayload });
+                return data;
+            }
+            catch (err) {
+                if (err instanceof NotFoundError) {
+                    // Both are a 404: only the body tells an API that has plans switched
+                    // off from one that never had the endpoint.
+                    throw err.data.code === DEPLOY_PLAN_DISABLED
+                        ? new ProjectPlanDisabledError({ cause: err })
+                        : new ProjectPreviewNotSupportedError({ cause: err });
+                }
+                if (!(err instanceof ConflictError)) {
+                    throw err;
+                }
+                if (attempt >= PREVIEW_CONFLICT_ATTEMPTS) {
+                    throw new ProjectPreviewUnavailableError(err.data.message, { cause: err });
+                }
+                const retryAfterMs = Math.min(parseRetryAfter(err.data.retryAfter) ?? PREVIEW_RETRY_AFTER_DEFAULT_MS, PREVIEW_RETRY_AFTER_MAX_MS);
+                onStatus?.('Another operation is holding the project, retrying...');
+                await new Promise(resolve => setTimeout(resolve, retryAfterMs));
+            }
+        }
+    }
     /**
      * Deploy a project. The deployment runs asynchronously on the backend: this
      * submits it, then follows its progress stream to completion, so large projects
@@ -193,7 +317,7 @@ class Projects {
      *
      * @throws {ProjectDeployFailedError} If the deployment finishes unsuccessfully.
      */
-    async deploy(resources, { dryRun = false, scheduleOnDeploy = true, preserveResources = false, cancelInProgress = false, onProgress, onStatus, } = {}) {
+    async deploy(resources, { dryRun = false, scheduleOnDeploy = false, scheduleOnDeployScope = 'changed', scheduleOnDeployThreshold, scheduleOnDeployMinFrequency, preserveResources = false, plan = false, pruneRelations = false, planToken, cancelInProgress = false, onProgress, onStatus, } = {}) {
         const logicalId = resources.project.logicalId;
         // On a 409 the project already has a deployment in progress. By default we
         // wait for it to finish then retry; with cancelInProgress we cancel it first.
@@ -204,7 +328,18 @@ class Projects {
         const deadlineAt = Date.now() + DEPLOY_CONFLICT_WAIT_DEADLINE_MS;
         for (;;) {
             try {
-                return await this.submitDeployment(resources, { dryRun, scheduleOnDeploy, preserveResources, onProgress });
+                return await this.submitDeployment(resources, {
+                    dryRun,
+                    scheduleOnDeploy,
+                    scheduleOnDeployScope,
+                    scheduleOnDeployThreshold,
+                    scheduleOnDeployMinFrequency,
+                    preserveResources,
+                    plan,
+                    pruneRelations,
+                    planToken,
+                    onProgress,
+                });
             }
             catch (err) {
                 if (dryRun
@@ -213,21 +348,46 @@ class Projects {
                     || Date.now() >= deadlineAt) {
                     throw err;
                 }
-                await this.resolveInProgressDeployment(logicalId, err.data.deploymentId, {
+                const finished = await this.resolveInProgressDeployment(logicalId, err.data.deploymentId, {
                     cancel: cancelInProgress,
                     onStatus,
                     deadlineAt,
                 });
+                // A predecessor that ran to completion is what invalidates a plan
+                // token, so re-POSTing with this one would spend the whole payload on a
+                // refusal nobody can act on. Two cases are not that: one we cancelled
+                // ourselves (the caller asked to deploy instead of it, and it may well
+                // have written nothing), and one still running when the wait gave up —
+                // nothing has changed, and the re-POST surfaces the conflict the caller
+                // needs to hear about.
+                if (planToken !== undefined && !cancelInProgress && finished) {
+                    throw new ProjectPlanSupersededError({ cause: err });
+                }
                 // loop → re-POST, now that the predecessor has reached a final state
             }
         }
     }
-    async submitDeployment(resources, { dryRun, scheduleOnDeploy, preserveResources, onProgress }) {
+    async submitDeployment(resources, { dryRun, scheduleOnDeploy, scheduleOnDeployScope, scheduleOnDeployThreshold, scheduleOnDeployMinFrequency, preserveResources, plan, pruneRelations, planToken, onProgress, }) {
         // Only send preserveResources when the user opted in. The endpoint rejects
         // unknown query params, and preserveResources=false is the default (delete)
         // behavior, so omitting it keeps default deploys backwards compatible.
+        // plan, pruneRelations, planToken, scheduleOnDeployThreshold and
+        // scheduleOnDeployMinFrequency are omitted for the same reason: an older
+        // API knows none of them. The scope is always sent: it decides which
+        // checks run after the deploy, whatever the API's own default.
+        const scopeParam = `&scheduleOnDeployScope=${scheduleOnDeployScope}`;
+        const thresholdParam = scheduleOnDeployThreshold === undefined
+            ? ''
+            : `&scheduleOnDeployThreshold=${scheduleOnDeployThreshold}`;
+        const minFrequencyParam = scheduleOnDeployMinFrequency === undefined
+            ? ''
+            : `&scheduleOnDeployMinFrequency=${scheduleOnDeployMinFrequency}`;
         const preserveParam = preserveResources ? '&preserveResources=true' : '';
-        const { data } = await this.api.post(`/v1/projects/deploy?dryRun=${dryRun}&scheduleOnDeploy=${scheduleOnDeploy}${preserveParam}`, resources, { transformRequest: compressJSONPayload });
+        const planParam = plan ? '&plan=true' : '';
+        const pruneParam = pruneRelations ? '&pruneRelations=true' : '';
+        const tokenParam = planToken ? `&planToken=${encodeURIComponent(planToken)}` : '';
+        const { data } = await this.api.post(`/v1/projects/deploy?dryRun=${dryRun}&scheduleOnDeploy=${scheduleOnDeploy}`
+            + `${scopeParam}${thresholdParam}${minFrequencyParam}${preserveParam}${planParam}${pruneParam}${tokenParam}`, resources, { transformRequest: compressJSONPayload });
         // A dry run responds synchronously with the preview diff.
         if (dryRun) {
             return { data: data };
@@ -238,18 +398,30 @@ class Projects {
         if (completed.status === 'CANCELLED') {
             throw new ProjectDeployCancelledError('A newer deployment may have cancelled yours. Try deploying again if you still need to apply your changes.');
         }
+        // A refused plan is not a failed deploy: nothing was written, and the
+        // deployment carries the plan as it looks now so the caller can show what
+        // moved instead of a bare error.
+        if (completed.error?.code === 'PLAN_STALE') {
+            throw new ProjectPlanStaleError(completed.error.message, completed.result?.diff ?? []);
+        }
         if (completed.status !== 'SUCCEEDED' || completed.result === null) {
             throw new ProjectDeployFailedError(completed.error?.message ?? 'The deployment did not complete successfully.');
         }
-        return { data: completed.result };
+        // An API from before the scheduling threshold does not report the outcome;
+        // it scheduled as asked.
+        return { data: { ...completed.result, scheduled: completed.scheduleOnDeploy ?? scheduleOnDeploy } };
     }
     /**
      * Resolve a collision with an in-progress deployment so the caller can retry:
      * optionally cancel it, then wait until it reaches a final state (or is gone)
      * before returning — so the caller re-POSTs only when the slot is actually
      * free, never re-uploading the payload while the predecessor is still running.
-     * Returns early if the overall `deadlineAt` passes (the caller then re-POSTs
-     * once and surfaces the conflict).
+     *
+     * @returns Whether the predecessor was observed to reach a final state.
+     * `false` means the wait hit its deadline with the predecessor still running,
+     * which is a different situation for the caller: nothing has changed, so a
+     * plan computed before the wait still stands, and re-POSTing surfaces the
+     * conflict the caller needs to hear about.
      */
     async resolveInProgressDeployment(logicalId, deploymentId, { cancel, onStatus, deadlineAt }) {
         if (cancel) {
@@ -262,7 +434,7 @@ class Projects {
                 if (!(err instanceof NotFoundError)) {
                     throw err;
                 }
-                return;
+                return true;
             }
         }
         else {
@@ -274,18 +446,18 @@ class Projects {
         for (;;) {
             try {
                 await this.awaitDeploymentCompletion(logicalId, deploymentId);
-                return; // reached a final state → slot free
+                return true; // reached a final state → slot free
             }
             catch (err) {
                 if (err instanceof NotFoundError) {
-                    return; // gone → slot free
+                    return true; // gone → slot free
                 }
                 // 408 = still running after the long-poll window. Keep waiting unless the
                 // overall deadline has passed, in which case return and let the caller
                 // re-POST once and surface the conflict.
                 if (err instanceof RequestTimeoutError) {
                     if (Date.now() >= deadlineAt) {
-                        return;
+                        return false;
                     }
                     continue;
                 }