@netlify/spark-ui 1.31.0-alpha.5 → 1.31.0-alpha.7

package/packages/drop-core/authedApi.ts

@@ -2,22 +2,15 @@ import type { BuildSite } from './types';
 import { NotAuthenticatedError, SiteCreateError } from './errors';
 
 /**
- * The transport both authenticated clients share: JSON calls ride the
- * consumer's access-control rewrite on the session cookie, so nothing
- * credential-shaped lives in the browser and nothing can expire mid-deploy.
- * (Uploads are the exception — the proxy's Lambda caps request bodies at
- * ~6MB — and each client handles its own, bearer-authorized.)
+ * Transport shared by both authenticated clients: JSON rides the consumer's
+ * access-control rewrite on the session cookie. Uploads are each client's own
+ * (bearer-direct — the proxy can't carry them).
  */
 
 /**
- * Create a site in the visitor's account via `POST {proxyBase}/sites` (scoped
- * to `accountSlug` when given, else the user's default account), attributed
- * `created_via: 'drop'`.
- *
- * A logged-out visitor 401s here, before anything is created — the one
- * pre-mutation point where callers may still safely fall back to an anonymous
- * flow, which is why it maps to `NotAuthenticatedError`. Any other failure is
- * a `SiteCreateError` carrying the status.
+ * `POST {proxyBase}/sites`, attributed `created_via: 'drop'`. A logged-out
+ * visitor 401s here, before anything is created — the one point an anonymous
+ * fallback is still safe, hence NotAuthenticatedError.
  */
 export async function createSiteInAccount(
   proxyBase: string,
@@ -48,15 +41,9 @@ interface DeployState {
 }
 
 /**
- * Poll `GET {proxyBase}/deploys/{deployId}` on the session cookie until the
- * deploy settles, and report how. Purely mechanical on purpose: each caller
- * maps the outcome onto its own error vocabulary (the drop client throws plain
- * errors `humanizeDropError` understands; the build client throws
- * `BuildFailedError`/`BuildTimeoutError`), so that knowledge stays next to the
- * class it belongs to.
- *
- * A non-ok poll response is skipped, not fatal — a transient proxy hiccup
- * shouldn't kill a deploy that is still progressing.
+ * Polls the deploy on the session cookie and reports the terminal outcome —
+ * callers map it onto their own error vocabulary. Non-ok reads are skipped,
+ * not fatal: a proxy hiccup shouldn't kill a progressing deploy.
  */
 export async function pollDeployUntilSettled(options: {
   proxyBase: string;

package/packages/drop-core/authedDropClient.ts

@@ -11,27 +11,13 @@ import { DeployFailedError, DeployTimeoutError, NotAuthenticatedError } from './
 import type { BuildSite, Digest, DropResponse } from './types';
 
 export interface AuthenticatedDropClientConfig {
-  /**
-   * Base for JSON API calls, routed through the consumer's access-control
-   * rewrite so the session cookie authenticates them. On netlify.com that
-   * rewrite is `/access-control/*` → the app's access-control function, which
-   * makes `/access-control/bb-api/api/v1` the API root (the default here).
-   */
+  /** Root for session-cookie JSON calls, via the consumer's access-control rewrite. */
   proxyBase?: string;
-  /**
-   * Direct API base for the file uploads. The proxy above runs in a Lambda with
-   * a ~6MB request body limit, so file PUTs go straight to `api.netlify.com`
-   * (whose `/api/*` CORS policy allows any origin).
-   */
+  /** Direct base for file PUTs — the proxy's ~6MB Lambda body limit can't carry uploads. */
   apiBase?: string;
   /**
-   * Mint a bearer token for those direct uploads. On netlify.com this is
-   * `GET /access-control/generate-access-control-token`, whose
-   * `accessControlToken` the API decrypts back into the user's access token.
-   * Resolving `null` means "no session" and surfaces as `NotAuthenticatedError`.
-   *
-   * Called repeatedly, not once: the token issued to a non-app origin lives
-   * only 30 seconds, which a multi-file upload routinely outlasts.
+   * Mint the upload bearer; `null` means "no session". Called repeatedly —
+   * non-app origins get 30-second tokens, which an upload queue outlasts.
    */
   getUploadToken: () => Promise<string | null>;
   /** Create the site in this account. Omit to use the user's default account. */
@@ -51,25 +37,10 @@ interface SiteDeployResponse {
 }
 
 /**
- * Authenticated drop client for logged-in visitors. Unlike `AnonymousDropClient`
- * — which creates an account-less site the visitor must later claim — this
- * deploys straight into the visitor's account via the sites/deploys API,
- * mirroring what app.netlify.com does for a logged-in drag-and-drop deploy.
- * There is no claim step, so the caller should hand off to the site's dashboard
- * page rather than the claim page.
- *
- * Requests split across two hosts by necessity. JSON calls (create the site,
- * create the deploy, poll it) go through the consumer's access-control proxy on
- * the session cookie — no token involved, and nothing that can expire mid-deploy.
- * File uploads can't: the proxy caps bodies at ~6MB, so they go direct to
- * `api.netlify.com` with a bearer, re-minted as it ages (see `TOKEN_REUSE_MS`).
- *
- * Error-mapping invariant: only pre-mutation failures — a null upload token at
- * the gate, or a 401/403 creating the site — throw `NotAuthenticatedError`,
- * which is the signal the drop flow may safely retry anonymously. Once the site
- * exists, any auth failure throws a plain error instead: falling back at that
- * point would strand an empty site in the account *and* deploy a duplicate
- * anonymously.
+ * Deploys a static drop straight into a logged-in visitor's account — no claim
+ * step. JSON rides the cookie proxy; file PUTs go direct on a re-minted bearer.
+ * Invariant: NotAuthenticatedError only pre-mutation — after the site exists, a
+ * fallback would strand an empty site and deploy a duplicate.
  */
 export class AuthenticatedDropClient implements DropClient {
   private proxyBase: string;
@@ -108,9 +79,8 @@ export class AuthenticatedDropClient implements DropClient {
   }
 
   /**
-   * A token young enough to authorize an upload, minting a new one once the
-   * cached one nears its 30s expiry. A mint failure here is a plain `Error`,
-   * never `NotAuthenticatedError` — the site exists by now (class doc).
+   * A token younger than its 30s expiry. Mint failures here are plain Errors,
+   * never NotAuthenticatedError — the site exists by now (class doc).
    */
   private async freshToken(): Promise<string> {
     const now = Date.now();
@@ -123,11 +93,7 @@ export class AuthenticatedDropClient implements DropClient {
     return value;
   }
 
-  /**
-   * Two proxied calls: create the site in the visitor's account, then the
-   * deploy on it. Mapped into the anonymous `DropResponse` shape so
-   * `deployFiles` runs unchanged over either client.
-   */
+  /** Site + deploy via the proxy, mapped into `DropResponse` so `deployFiles` runs unchanged. */
   async createDeploy(files: Digest, _token: string): Promise<DropResponse> {
     const site: BuildSite = await createSiteInAccount(this.proxyBase, this.accountSlug);
 
@@ -148,11 +114,7 @@ export class AuthenticatedDropClient implements DropClient {
     };
   }
 
-  /**
-   * Direct to `api.netlify.com` on a freshly-aged bearer — the threaded `token`
-   * is ignored because an upload queue easily outlives the 30 seconds it was
-   * minted with. PUT (not POST) so paths with "&" etc. work.
-   */
+  /** Direct on a fresh bearer (the threaded one has expired). PUT so paths with "&" work. */
   async uploadFile(
     deployId: string,
     path: string,
@@ -168,11 +130,7 @@ export class AuthenticatedDropClient implements DropClient {
     if (!res.ok) throw apiError(`upload ${path}`, res.status);
   }
 
-  /**
-   * Poll the deploy through the proxy until it settles: resolve on `ready`,
-   * throw on `error`/`rejected`, throw on timeout. On the session cookie rather
-   * than a bearer, so a deploy taking minutes can't outlive its own credentials.
-   */
+  /** Polls on the session cookie, so a slow deploy can't outlive its own credentials. */
   async waitUntilReady(deploy: DropResponse, _token: string): Promise<void> {
     const settled = await pollDeployUntilSettled({
       proxyBase: this.proxyBase,

package/packages/drop-core/buildClient.test.ts

@@ -56,10 +56,25 @@ describe('AuthenticatedBuildClient.createBuildFromZip', () => {
     expect(body.get('title')).toBe('Build from drop deployment');
   });
 
-  it('throws NotAuthenticatedError when no upload token can be minted', async () => {
-    await expect(client(async () => null).createBuildFromZip('s', zip)).rejects.toBeInstanceOf(
-      NotAuthenticatedError
-    );
+  // The site exists by the time this method runs, so a NotAuthenticatedError
+  // here would read as "nothing was created" and send the drop back to the
+  // stash — leaving an empty project behind, and another on the next resume.
+  it('reports a missing upload token as BuildCreateError, never NotAuthenticatedError', async () => {
+    const failure = await client(async () => null)
+      .createBuildFromZip('s', zip)
+      .catch(e => e);
+    expect(failure).toBeInstanceOf(BuildCreateError);
+    expect(failure).not.toBeInstanceOf(NotAuthenticatedError);
+  });
+
+  it('reports a 401 from an expired upload token as BuildCreateError', async () => {
+    vi.stubGlobal('fetch', async () => ({ ok: false, status: 401, json: async () => ({}) }));
+    const failure = await client()
+      .createBuildFromZip('s', zip)
+      .catch(e => e);
+    expect(failure).toBeInstanceOf(BuildCreateError);
+    expect(failure).not.toBeInstanceOf(NotAuthenticatedError);
+    expect(failure.status).toBe(401);
   });
 
   it('wraps other upload failures in BuildCreateError with the status', async () => {

package/packages/drop-core/buildClient.ts

@@ -5,19 +5,13 @@ import {
   DEFAULT_PROXY_BASE,
   DEFAULT_TIMEOUT_MS,
 } from './constants';
-import {
-  BuildCreateError,
-  BuildFailedError,
-  BuildTimeoutError,
-  NotAuthenticatedError,
-} from './errors';
+import { BuildCreateError, BuildFailedError, BuildTimeoutError } from './errors';
 import type { BuildSite } from './types';
 
 export type { BuildSite } from './types';
 
 /** The subset of a Netlify Build returned by `POST /sites/{id}/builds`. */
 export interface BuildResponse {
-  /** build id */
   id: string;
   /** the deploy the build produces — present as soon as the build is enqueued */
   deploy_id?: string;
@@ -30,28 +24,14 @@ export interface BuildClient {
 }
 
 export interface AuthenticatedBuildClientConfig {
-  /**
-   * Base for JSON API calls, routed through the consumer's access-control
-   * rewrite so the session cookie authenticates them. On netlify.com that
-   * rewrite is `/access-control/*` → the app's access-control function, which
-   * makes `/access-control/bb-api/api/v1` the API root (the default here).
-   */
+  /** Root for session-cookie JSON calls, via the consumer's access-control rewrite. */
   proxyBase?: string;
-  /**
-   * Direct API base for the zip upload. The proxy above runs in a Lambda with a
-   * ~6MB request body limit, so the multipart POST has to go straight to
-   * `api.netlify.com` (whose `/api/*` CORS policy allows any origin).
-   */
+  /** Direct base for the zip upload — the proxy's ~6MB Lambda body limit can't carry it. */
   apiBase?: string;
   /**
-   * Mint a bearer token for that direct upload. On netlify.com this is
-   * `GET /access-control/generate-access-control-token`, whose
-   * `accessControlToken` the API decrypts back into the user's access token.
-   * Resolving `null` means "no session" and surfaces as `NotAuthenticatedError`.
-   *
-   * Note the token issued to a non-app origin lives only 30 seconds. It is
-   * minted immediately before the upload, but a zip that takes longer than that
-   * to transfer will still be rejected mid-flight — see `createBuildFromZip`.
+   * Mint the upload bearer; `null` means "no session". Non-app origins get
+   * 30-second tokens — a zip slower than that fails mid-flight (see
+   * `createBuildFromZip`).
    */
   getUploadToken: () => Promise<string | null>;
   /** Create the site in this account. Omit to use the user's default account. */
@@ -65,16 +45,9 @@ export interface AuthenticatedBuildClientConfig {
 }
 
 /**
- * Authenticated drop client for projects that need a build. Unlike
- * `AnonymousDropClient` — which creates an account-less static site and can only
- * upload pre-built files — this creates a real site in the user's account and
- * hands buildbot a source archive to build, mirroring what app.netlify.com does
- * for a drag-and-drop build.
- *
- * Requests split across two hosts by necessity: JSON calls go through the
- * consumer's access-control proxy (cookie session, no token handling in the
- * browser), while the zip upload goes direct to `api.netlify.com` with a
- * short-lived bearer token because the proxy can't carry a body that large.
+ * Builds a drop in a logged-in visitor's account: create the site, hand
+ * buildbot the source zip. JSON rides the cookie proxy; the zip goes direct
+ * with a bearer (the proxy can't carry it).
  */
 export class AuthenticatedBuildClient implements BuildClient {
   private proxyBase: string;
@@ -103,29 +76,24 @@ export class AuthenticatedBuildClient implements BuildClient {
     this.timeoutMs = timeoutMs;
   }
 
-  /**
-   * Create the site the build deploys into. A logged-out visitor fails here,
-   * before anything is created — see `createSiteInAccount` for the error
-   * mapping that makes the signup fallback safe.
-   */
+  /** A logged-out visitor fails here, before anything is created (see `createSiteInAccount`). */
   async createSite(): Promise<BuildSite> {
     return createSiteInAccount(this.proxyBase, this.accountSlug);
   }
 
   /**
-   * Upload the source archive and enqueue a build. Direct to `api.netlify.com`
-   * (see the note on `apiBase`), authorized by a freshly minted bearer token.
-   * `Content-Type` is left unset on purpose so the browser adds the multipart
-   * boundary itself.
+   * One multipart request on a fresh 30s bearer — a slower zip fails mid-flight
+   * (the app origin gets 300s; raising ours is a platform-side change).
+   * Content-Type stays unset so the browser adds the multipart boundary.
    *
-   * Known ceiling: this is one request on a 30s token, and re-minting can't
-   * help once it is in flight. A zip that takes longer than that to upload will
-   * fail — the app origin gets 300s for exactly this reason, and lifting the
-   * limit for other origins is a platform-side change.
+   * Never NotAuthenticatedError, including for a 401: the site exists by the
+   * time this runs, so signalling "no session" would strand it and re-stash
+   * the drop for the next visit to strand another. `createSite` is the auth
+   * gate for this path.
    */
   async createBuildFromZip(siteId: string, zip: File): Promise<BuildResponse> {
     const token = await this.getUploadToken();
-    if (!token) throw new NotAuthenticatedError();
+    if (!token) throw new BuildCreateError();
 
     const body = new FormData();
     body.append('zip', zip);
@@ -136,22 +104,14 @@ export class AuthenticatedBuildClient implements BuildClient {
       headers: { Authorization: `Bearer ${token}` },
       body,
     });
-    if (res.status === 401 || res.status === 403) throw new NotAuthenticatedError();
     if (!res.ok) throw new BuildCreateError(res.status);
     return res.json();
   }
 
   /**
-   * Poll the build's deploy until it settles, mirroring
-   * `AnonymousDropClient.waitUntilReady` — resolve on `ready`, throw on
-   * `error`/`rejected`, throw on timeout. A build that hasn't been given a
-   * deploy id yet has nothing pollable, so it resolves immediately and the
-   * caller falls back to the site page.
-   *
-   * Optional in the drop flow, and off by default: a build takes minutes, so
-   * the useful hand-off is usually the project page rather than a spinner.
-   * Polling rides the session cookie, so it cannot outlive its credentials the
-   * way a 30s bearer would.
+   * Optional (a build takes minutes; the useful hand-off is the project page).
+   * Polls on the cookie, so it can't outlive its credentials; no deploy id yet
+   * means nothing pollable, so it resolves immediately.
    */
   async waitUntilBuildReady(build: BuildResponse): Promise<void> {
     if (!build.deploy_id) return;
@@ -163,8 +123,6 @@ export class AuthenticatedBuildClient implements BuildClient {
       timeoutMs: this.timeoutMs,
     });
     if (settled.outcome === 'ready') return;
-    // The build's own error message is the only actionable part of a failure,
-    // so it travels on the typed error rather than being flattened away.
     if (settled.outcome === 'failed') throw new BuildFailedError(settled.errorMessage);
     throw new BuildTimeoutError();
   }

package/packages/drop-core/buildStash.test.ts

@@ -47,6 +47,25 @@ describe('buildStash', () => {
     expect(await stash?.zipFile.text()).toBe('zip-bytes');
   });
 
+  // Same key AND same value shape as react-ui's setWithExpiry, so the app can
+  // adopt this module without stranding a marker its own code already wrote.
+  it('writes the marker in react-ui’s { value, expiry } shape', async () => {
+    await saveDropStash(zip());
+    const marker = JSON.parse(localStorage.getItem('dropBuildStash') as string);
+    expect(marker.value).toBe('true');
+    expect(marker.expiry).toBeGreaterThan(Date.now());
+    expect(marker.expiry).toBeLessThanOrEqual(Date.now() + 24 * 60 * 60 * 1000);
+  });
+
+  // The row delete is what makes the stash unusable; dropping the database is
+  // cleanup, so a 200MB archive doesn't linger in the visitor's profile.
+  it('drops the database, not just the row, once the stash is consumed', async () => {
+    const deleteDatabase = vi.spyOn(indexedDB, 'deleteDatabase');
+    await saveDropStash(zip());
+    await clearDropStash();
+    expect(deleteDatabase).toHaveBeenCalledWith('netlify-drop');
+  });
+
   it('clears the stash and marker idempotently', async () => {
     await saveDropStash(zip());
     await clearDropStash();

package/packages/drop-core/buildStash.ts

@@ -1,21 +1,11 @@
 import type { InferredBuildSettings } from './detectBuild';
 
 /**
- * Carry a build-required drop across the signup round-trip.
- *
- * A logged-out visitor's drop can't be built (builds have no anonymous
- * equivalent), so before handing them to signup the zone stashes the source
- * archive here — IndexedDB, because the zip is far beyond localStorage's
- * budget. When they return to this origin authenticated, the zone deploys the
- * stash automatically instead of asking them to drop again.
- *
- * Storage is per-origin: a stash written on www.netlify.com can only ever be
- * resumed on www.netlify.com. That is the design, not a limitation — it is
- * exactly why the hand-off page must bring the visitor back here.
- *
- * Every operation is failure-swallowing: the stash is an enhancement, and a
- * browser without IndexedDB (or with a full quota) degrades to the plain
- * signup redirect the zone always supported.
+ * Carries a build drop across the signup round-trip: stash the zip in
+ * IndexedDB before the hand-off, deploy it when the visitor returns
+ * authenticated. Storage is per-origin by design — the hand-off must bring
+ * them back here. Every operation swallows failures: no storage means the
+ * plain signup redirect the zone always supported.
  */
 
 export interface DropBuildStash {
@@ -45,6 +35,16 @@ const withTimeout = <T>(promise: Promise<T>): Promise<T> =>
     }),
   ]);
 
+// Resolves on `blocked` too: another tab holding the database open is not worth
+// stalling the caller for, and the row delete already made the stash unusable.
+const deleteDatabase = (): Promise<void> =>
+  new Promise((resolve, reject) => {
+    const request = indexedDB.deleteDatabase(DB_NAME);
+    request.onsuccess = () => resolve();
+    request.onblocked = () => resolve();
+    request.onerror = () => reject(request.error);
+  });
+
 const openDatabase = (): Promise<IDBDatabase> =>
   new Promise((resolve, reject) => {
     const request = indexedDB.open(DB_NAME, DB_VERSION);
@@ -84,19 +84,20 @@ const hasEnoughQuota = async (bytes: number): Promise<boolean> => {
 
 // The marker is a plain localStorage flag with its own expiry, so page loads can
 // ask "is there anything to resume?" synchronously without opening IndexedDB.
+// `{ value, expiry }` is react-ui's setWithExpiry shape — same key, same shape,
+// so the app can adopt this module without stranding a marker it already wrote.
 const setMarker = () => {
-  localStorage.setItem(MARKER_KEY, JSON.stringify({ expiresAt: Date.now() + STASH_TTL_MS }));
+  localStorage.setItem(
+    MARKER_KEY,
+    JSON.stringify({ value: 'true', expiry: Date.now() + STASH_TTL_MS })
+  );
 };
 
 const clearMarker = () => {
   localStorage.removeItem(MARKER_KEY);
 };
 
-/**
- * Stash a drop's source archive for an automatic deploy after signup. Returns
- * whether it was actually stored — callers use that only to phrase the
- * hand-off, never to block it.
- */
+/** Stash the archive for auto-deploy after signup. The result phrases the hand-off, never blocks it. */
 export async function saveDropStash(
   zipFile: File,
   buildSettings: InferredBuildSettings | null = null
@@ -110,7 +111,13 @@ export async function saveDropStash(
     ) {
       return false;
     }
-    const record: DropBuildStash = { zipFile, buildSettings, createdAt: Date.now() };
+    const record: DropBuildStash = {
+      // Round-trip through JSON so an injected detector's richer object can't
+      // fail the structured clone the put() below performs.
+      buildSettings: buildSettings && JSON.parse(JSON.stringify(buildSettings)),
+      zipFile,
+      createdAt: Date.now(),
+    };
     await runStoreOperation('readwrite', store => store.put(record, STASH_KEY));
     setMarker();
     return true;
@@ -139,11 +146,9 @@ export async function loadDropStash(): Promise<DropBuildStash | null> {
 }
 
 /**
- * The archive back out of storage as a real `File`. Structured clone should
- * preserve File identity, but implementations vary in whether the name and
- * prototype survive — and the build upload needs both (the multipart field is
- * named by the File). A Blob-shaped survivor is rewrapped; anything else is
- * treated as a corrupt record.
+ * Rewraps a Blob-shaped survivor into a named File — structured-clone
+ * implementations vary in preserving File identity, and the multipart upload
+ * needs the name. Anything less Blob-shaped is a corrupt record.
  */
 function rehydrateZipFile(stored: unknown): File | null {
   if (stored instanceof File && stored.name) return stored;
@@ -162,7 +167,11 @@ export async function clearDropStash(): Promise<void> {
   }
   try {
     if (typeof indexedDB === 'undefined') return;
+    // The row delete is what guarantees the stash can't come back; dropping the
+    // database afterwards is cleanup, so the visitor's project source doesn't
+    // sit in their profile once we're done with it. It reappears on the next drop.
     await runStoreOperation('readwrite', store => store.delete(STASH_KEY));
+    await withTimeout(deleteDatabase());
   } catch {
     // best effort — an orphaned record expires via its TTL
   }
@@ -173,8 +182,8 @@ export function hasDropStashMarker(): boolean {
   try {
     const marker = localStorage.getItem(MARKER_KEY);
     if (!marker) return false;
-    const { expiresAt } = JSON.parse(marker) as { expiresAt?: number };
-    if (typeof expiresAt !== 'number' || Date.now() > expiresAt) {
+    const { value, expiry } = JSON.parse(marker) as { value?: string; expiry?: number };
+    if (value !== 'true' || typeof expiry !== 'number' || Date.now() > expiry) {
       clearMarker();
       return false;
     }

package/packages/drop-core/client.ts

@@ -1,9 +1,6 @@
 /**
- * The `DropClient` seam: the four calls a static deploy needs — mint a token,
- * create the deploy, upload a file, wait until ready — behind one interface,
- * so `deployFiles` runs the same pipeline whether the deploy is anonymous
- * (this file's `AnonymousDropClient`, claimed later by the visitor) or lands
- * directly in an account (`authedDropClient.ts`).
+ * The DropClient seam: the four calls a static deploy needs, behind one
+ * interface, so `deployFiles` runs the same pipeline anonymous or authenticated.
  */
 import { DEFAULT_API_BASE, DEFAULT_POLL_INTERVAL_MS, DEFAULT_TIMEOUT_MS } from './constants';
 import { DeployTimeoutError } from './errors';
@@ -23,7 +20,7 @@ export interface DropClient {
 
 /**
  * Unauthenticated drop client. Authorized server-side by the Referer header,
- * so it only works from an allowlisted origin (see backend checklist).
+ * so it only works from an allowlisted origin.
  */
 export class AnonymousDropClient implements DropClient {
   constructor(
@@ -64,10 +61,9 @@ export class AnonymousDropClient implements DropClient {
   }
 
   async waitUntilReady(deploy: DropResponse, token: string): Promise<void> {
-    // Poll the deploy with the drop token until ready.
-    // Note: `/deploys/{id}` expects the deploy_id (BSON), not the site id (UUID)
-    // that lives at `deploy.id`. See drop_controller.rb; Deploy.find(uuid) is nil
-    // and the request 401s misleadingly via require_current_actor!.
+    // `/deploys/{id}` expects the deploy_id (BSON), not the site id (UUID) that
+    // lives at `deploy.id`. See drop_controller.rb; Deploy.find(uuid) is nil and
+    // the request 401s misleadingly via require_current_actor!.
     const deadline = this.timeoutMs / this.pollIntervalMs;
     for (let i = 0; i < deadline; i++) {
       const res = await fetch(`${this.apiBase}/deploys/${deploy.deploy_id}`, {

package/packages/drop-core/constants.ts

@@ -1,15 +1,7 @@
-/**
- * The tunables shared across drop-core, one place and one comment each.
- * Module-specific constants (e.g. buildStash's storage caps) stay with their
- * module; anything two modules read belongs here.
- */
+/** Tunables shared across drop-core. Module-specific constants stay with their module. */
 
-/**
- * Root for session-cookie JSON calls, via the consumer's access-control
- * rewrite. On netlify.com, `/access-control/*` targets the app's
- * access-control function; the paths an origin may call are allowlisted
- * server-side.
- */
+// Root for session-cookie JSON calls via the consumer's access-control rewrite
+// (paths per origin are allowlisted server-side)
 export const DEFAULT_PROXY_BASE = '/access-control/bb-api/api/v1';
 
 /** Direct api.netlify.com root for the uploads the proxy's ~6MB Lambda body limit can't carry. */
@@ -21,19 +13,13 @@ export const DEFAULT_POLL_INTERVAL_MS = 1000;
 // How long to keep polling before giving up: 10 minutes
 export const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
 
-// Concurrent file uploads (matches netlify-cli's deploy engine)
+// Concurrent file uploads
 export const MAX_CONCURRENT_UPLOADS = 5;
 
-/**
- * How long a minted upload token is reused before minting another: 20 seconds.
- * The server issues non-app origins a 30s token; the gap leaves margin for the
- * request the token authorizes to finish.
- */
+// Reuse window for a minted upload token: 20s (server TTL is 30s; the gap is
+// margin for the request it authorizes to finish)
 export const TOKEN_REUSE_MS = 20 * 1000;
 
-/**
- * Waits between attempts of a failed file upload, as data so the whole curve
- * can be overridden (the tus-js-client `retryDelays` idiom). Three retries,
- * linear backoff; 400/422 responses never retry — see `uploadWithRetry`.
- */
+// Waits between upload retries, as data so the curve is overridable.
+// 400/422 never retry — see uploadWithRetry.
 export const UPLOAD_RETRY_DELAYS_MS: readonly number[] = [1_000, 2_000, 3_000];

package/packages/drop-core/deploy.ts

@@ -9,11 +9,7 @@ import { zipFiles, type ZipResult } from './zip';
 /** Responses that mean the request itself is wrong — retrying can only repeat the answer. */
 const NON_RETRIABLE_STATUSES = new Set([400, 422]);
 
-/**
- * Upload one file, retrying transient failures (5xx, 429, network errors) on
- * the given delay curve. A single flaky PUT among hundreds shouldn't kill the
- * whole deploy — every deploy client we know of retries here.
- */
+/** Retries transient failures (5xx/429/network) — one flaky PUT shouldn't kill the deploy. */
 async function uploadWithRetry(
   client: DropClient,
   deployId: string,
@@ -96,7 +92,6 @@ export async function deployFiles(
 }
 
 export interface BuildDeployResult {
-  /** The site created for this build. */
   site: BuildSite;
   /** The enqueued build; `deploy_id` is what the app's deploy page keys off. */
   build: BuildResponse;
@@ -108,22 +103,15 @@ export interface BuildDeployResult {
 
 export interface BuildDeployOptions extends DeployOptions {
   /**
-   * Poll until the build finishes instead of returning as soon as it's enqueued.
-   * Off by default: a build takes minutes, so the useful hand-off is usually the
-   * app's deploy page with its live logs, not a spinner. Turn it on when the
-   * caller needs to know the outcome — only then can a `BuildFailedError` reach
-   * it with the build's own error message.
+   * Wait for the build instead of returning at enqueue. Off by default (builds
+   * take minutes); on is the only way a BuildFailedError reaches the caller.
    */
   waitForBuild?: boolean;
 }
 
 /**
- * The build counterpart to `deployFiles`: zip the drop, create a site in the
- * user's account, and hand the archive to buildbot. Requires an authenticated
- * client — builds have no anonymous equivalent.
- *
- * Site creation deliberately happens *after* zipping, so a zip that fails
- * doesn't leave an empty site behind in the user's account.
+ * Zip the drop, create a site, hand buildbot the archive. Zipping comes first
+ * on purpose: a failed zip must not leave an empty site behind.
  */
 export async function deployBuild(
   client: BuildClient,
@@ -138,11 +126,7 @@ export async function deployBuild(
   return deployZippedBuild(client, archive, opts);
 }
 
-/**
- * Deploy an archive that was already zipped — the resume path for a drop
- * stashed across the signup round-trip (see `buildStash`), where `source.zip`
- * and its synthesised settings were produced before the visitor left.
- */
+/** Deploy an already-zipped archive — the resume path for a stashed drop (see `buildStash`). */
 export async function deployZippedBuild(
   client: BuildClient,
   { file: zip, buildSettings }: ZipResult,