@netlify/spark-ui 1.31.0-alpha.4 → 1.31.0-alpha.6

package/packages/drop-core/analytics.ts

@@ -1,20 +1,13 @@
 import type { BuildReason } from './detectBuild';
 
-/**
- * The Drop Zone's analytics contract — the canonical event names and property
- * shapes, exported so no consumer (this package's own component, a host site's
- * GTM wiring, or another Netlify surface implementing its own Drop UI over
- * drop-core) ever hand-writes the strings.
- */
+/** The analytics contract: canonical event names + property shapes, so no consumer hand-writes them. */
 
 /** How the files reached the zone — carried on every drop-initiated event as `method`. */
 export type DropMethod = 'drag' | 'browse';
 
 /**
- * Canonical Drop Zone lifecycle events. The values are the wire names:
- * analytics history in Amplitude/Segment keys off these exact strings, so
- * renaming a value silently forks every funnel built on it — treat them as
- * append-only.
+ * The wire names. Amplitude/Segment history keys off these exact strings —
+ * append-only, never rename.
  */
 export const DROPZONE_EVENTS = {
   /** Files arrived via drag — the picker path reports its files on outcome events instead. */
@@ -114,9 +107,5 @@ export interface DropZoneEventProperties {
   dropzone_resumed: ResumedProps;
 }
 
-/**
- * Provider-agnostic analytics sink. Deliberately loose (string, not the event
- * union): hosts forward these to Segment/GA/GTM and often pipe their own
- * events through the same function.
- */
+/** Provider-agnostic sink — loose on purpose, since hosts pipe their own events through it too. */
 export type TrackFn = (event: string, properties?: Record<string, unknown>) => void;

package/packages/drop-core/authedApi.ts

@@ -2,35 +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).
  */
 
 /**
- * Default root for proxied JSON calls. On netlify.com the `/access-control/*`
- * rewrite targets the app's access-control function, making this path the API
- * root. The paths a given origin may call 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 can't carry. */
-export const DEFAULT_API_BASE = 'https://api.netlify.com/api/v1';
-
-export const DEFAULT_POLL_INTERVAL_MS = 1000;
-export const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
-
-/**
- * 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,
@@ -61,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

@@ -1,37 +1,23 @@
+import { createSiteInAccount, pollDeployUntilSettled } from './authedApi';
 import {
-  createSiteInAccount,
   DEFAULT_API_BASE,
   DEFAULT_POLL_INTERVAL_MS,
   DEFAULT_PROXY_BASE,
   DEFAULT_TIMEOUT_MS,
-  pollDeployUntilSettled,
-} from './authedApi';
+  TOKEN_REUSE_MS,
+} from './constants';
 import { apiError, type DropClient } from './client';
-import { NotAuthenticatedError } from './errors';
+import { DeployFailedError, DeployTimeoutError, NotAuthenticatedError } from './errors';
 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. */
@@ -42,13 +28,6 @@ export interface AuthenticatedDropClientConfig {
   timeoutMs?: number;
 }
 
-/**
- * How long a minted upload token is reused before minting another. The server
- * issues non-app origins a 30s token, so this leaves a margin for the request
- * it authorizes to finish.
- */
-const TOKEN_REUSE_MS = 20 * 1000;
-
 /** Response body of `POST /sites/{id}/deploys` — the slice the drop flow needs. */
 interface SiteDeployResponse {
   /** deploy id (BSON) */
@@ -58,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;
@@ -104,11 +68,8 @@ export class AuthenticatedDropClient implements DropClient {
   }
 
   /**
-   * The auth gate. Minting here — before anything is created — is what lets a
-   * logged-out visitor fail cleanly and fall back to the anonymous flow. The
-   * returned token is threaded through `deployFiles`, but only the uploads
-   * actually need one, and they re-mint rather than trusting this to still be
-   * valid by the time they run.
+   * The auth gate: minting here, before anything is created, is what lets a
+   * logged-out visitor fail cleanly and fall back to the anonymous flow.
    */
   async getToken(): Promise<string> {
     const token = await this.getUploadToken();
@@ -118,13 +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.
-   *
-   * Deliberately NOT `NotAuthenticatedError` when minting fails: by the time
-   * uploads run the site already exists, and that error would send the drop
-   * back through the anonymous path — leaving an empty project behind and
-   * deploying a duplicate. See the 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();
@@ -137,14 +93,8 @@ 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> {
-    // A logged-out visitor fails inside createSiteInAccount, before anything is
-    // created — the one point an anonymous fallback is still safe (class doc).
     const site: BuildSite = await createSiteInAccount(this.proxyBase, this.accountSlug);
 
     const deployRes = await fetch(`${this.proxyBase}/sites/${site.id}/deploys`, {
@@ -164,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,
@@ -184,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,
@@ -197,14 +139,9 @@ export class AuthenticatedDropClient implements DropClient {
       timeoutMs: this.timeoutMs,
     });
     if (settled.outcome === 'ready') return;
-    // Plain errors on purpose: humanizeDropError maps them, and nothing here
-    // may look like NotAuthenticatedError once the site exists (class doc).
-    if (settled.outcome === 'failed') {
-      throw new Error(
-        settled.errorMessage ? `deploy failed: ${settled.errorMessage}` : 'deploy failed'
-      );
-    }
-    // Same message the anonymous client uses, so humanizeDropError maps it.
-    throw new Error('Deploy did not become ready in time');
+    // Neither class is NotAuthenticatedError-shaped on purpose: once the site
+    // exists, nothing here may trigger the anonymous fallback (class doc).
+    if (settled.outcome === 'failed') throw new DeployFailedError(settled.errorMessage);
+    throw new DeployTimeoutError();
   }
 }

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

@@ -1,24 +1,17 @@
+import { createSiteInAccount, pollDeployUntilSettled } from './authedApi';
 import {
-  createSiteInAccount,
   DEFAULT_API_BASE,
   DEFAULT_POLL_INTERVAL_MS,
   DEFAULT_PROXY_BASE,
   DEFAULT_TIMEOUT_MS,
-  pollDeployUntilSettled,
-} from './authedApi';
-import {
-  BuildCreateError,
-  BuildFailedError,
-  BuildTimeoutError,
-  NotAuthenticatedError,
-} from './errors';
+} from './constants';
+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;
@@ -31,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. */
@@ -66,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;
@@ -104,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);
@@ -137,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;
@@ -164,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.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 {
@@ -92,11 +82,7 @@ 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
@@ -139,11 +125,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;

package/packages/drop-core/client.ts

@@ -1,3 +1,9 @@
+/**
+ * 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';
 import type { DropResponse, Digest } from './types';
 
 /** A normal Error with the response's HTTP status attached, so callers can branch on it directly. */
@@ -12,14 +18,16 @@ export interface DropClient {
   waitUntilReady(deploy: DropResponse, token: string): Promise<void>;
 }
 
-const API = 'https://api.netlify.com/api/v1';
-
 /**
  * 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(private apiBase = API) {}
+  constructor(
+    private apiBase = DEFAULT_API_BASE,
+    private pollIntervalMs = DEFAULT_POLL_INTERVAL_MS,
+    private timeoutMs = DEFAULT_TIMEOUT_MS
+  ) {}
 
   async getToken(): Promise<string> {
     const res = await fetch(`${this.apiBase}/drop/token`, { method: 'POST' });
@@ -53,17 +61,17 @@ 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!.
-    for (let i = 0; i < 600; i++) {
+    // `/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}`, {
         headers: { Authorization: `Bearer ${token}` },
       });
       if (res.ok && (await res.json()).state === 'ready') return;
-      await new Promise(r => setTimeout(r, 1000));
+      await new Promise(r => setTimeout(r, this.pollIntervalMs));
     }
-    throw new Error('Deploy did not become ready in time');
+    throw new DeployTimeoutError();
   }
 }

package/packages/drop-core/constants.ts

@@ -0,0 +1,25 @@
+/** 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
+// (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. */
+export const DEFAULT_API_BASE = 'https://api.netlify.com/api/v1';
+
+// How often a waiting deploy/build is re-read: 1 second
+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)
+export const MAX_CONCURRENT_UPLOADS = 5;
+
+// 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 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];