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

package/packages/components/preact/DropZone/useDropDeploy.ts

@@ -15,7 +15,7 @@ import {
   getSingleNonIndexHtmlFileName,
   hasMultipleHtmlFilesWithoutIndex,
   humanizeDropError,
-  NotAuthenticatedError,
+  isNotAuthenticatedError,
   renameSingleNonIndexHtmlToIndex,
   type BuildClient,
   type BuildDetection,
@@ -88,7 +88,6 @@ export type DeployStatus =
   | { kind: 'redirecting'; target: 'claim' | 'dashboard' | 'signup' | 'build' }
   | { kind: 'error'; message: string };
 
-/** Re-exported from the drop-core analytics contract, where the shape now lives. */
 export type { TrackFn };
 
 interface UseDropDeployOptions {
@@ -185,15 +184,12 @@ export function useDropDeploy({
   track,
 }: UseDropDeployOptions) {
   /**
-   * Typed veneer over the consumer's `track`: event names come from the
-   * DROPZONE_EVENTS contract and each payload is checked against its shape,
-   * so a renamed property fails to compile instead of silently forking the
-   * analytics history.
+   * Typed veneer over the consumer's `track`: each payload is checked against
+   * the DROPZONE_EVENTS contract, so a renamed property fails to compile
+   * instead of silently forking the analytics history.
    */
   const emit = <E extends DropZoneEventName>(event: E, props: DropZoneEventProperties[E]) =>
-    // The cast bridges to TrackFn's loose record: the interfaces have no index
-    // signature (so payloads stay closed for consumers), and the checking that
-    // matters happened against DropZoneEventProperties[E] above.
+    // The event interfaces carry no index signature, hence the cast to TrackFn's record.
     track(event, props as Record<string, unknown>);
 
   const [status, setStatus] = useState<DeployStatus>({ kind: 'idle' });
@@ -247,7 +243,7 @@ export function useDropDeploy({
         buildSettings,
       };
     } catch (err) {
-      if (err instanceof NotAuthenticatedError) return null;
+      if (isNotAuthenticatedError(err)) return null;
       throw err;
     }
   }
@@ -276,17 +272,12 @@ export function useDropDeploy({
 
     const typeProps = fileTypes.length ? { file_types: fileTypes } : {};
 
-    // Surface a failure: move to the error state and emit the matching
-    // analytics event. Centralised so every failure path (empty selection, a
-    // read/deploy throw) reports uniformly — the mirror of the
-    // `dropzone_deploy_succeeded` event on the happy path. `file_count` is only
-    // included where the file set is known (it isn't if `read()` itself threw);
-    // `file_types` rides along on every failure precisely because it *is* known
-    // in that case — a rejected single file is the main thing we want to see.
-    // `reason` goes to analytics as-is (raw, e.g. "drop failed: 429"); `message`
-    // is what the user sees, which for a caught error is humanized separately.
-    // `onError` gets both so a consumer (e.g. with `showStatus={false}`) can show
-    // the humanized message while keeping the raw reason for their own logging.
+    // Every failure path reports through here so the failure event stays
+    // uniform. `file_count` is only included where the file set is known (it
+    // isn't if `read()` threw); `file_types` always rides along because it *is*
+    // known then — a rejected single file is the main thing worth seeing.
+    // `reason` is raw (e.g. "drop failed: 429") for analytics; `message` is the
+    // humanized copy the user sees; `onError` gets both.
     const fail = (message: string, reason: string, extra?: Record<string, unknown>) => {
       setStatus({ kind: 'error', message });
       emit(DROPZONE_EVENTS.DEPLOY_FAILED, { method: source, reason, ...typeProps, ...extra });
@@ -425,7 +416,7 @@ export function useDropDeploy({
         onProgress: e => setStatus(progressToStatus(e)),
       });
     } catch (err) {
-      if (err instanceof NotAuthenticatedError) return null;
+      if (isNotAuthenticatedError(err)) return null;
       throw err;
     }
   }

package/packages/drop-core/README.md

@@ -0,0 +1,91 @@
+# drop-core
+
+The framework-free engine behind the Drop Zone: reading a dropped folder/zip
+into deployable files, deciding whether it needs a build, and deploying it —
+anonymously (claim flow) or into a logged-in visitor's account — plus the
+stash that carries a build drop across the signup round-trip.
+
+Consumed three ways: by the Preact `DropZone` in this repo, by anything
+importing `@netlify/spark-ui/drop-core`, and eventually by other Netlify
+surfaces implementing their own Drop UI over the same core.
+
+## Conventions
+
+These follow the practices shared by the libraries doing our two jobs —
+react-dropzone/Uppy/FilePond on the component side, netlify-cli's deploy
+engine, @vercel/client, and tus-js-client on the pipeline side. Where we
+deliberately differ, that's recorded too, so it isn't re-litigated by accident.
+
+### Boundaries
+
+- **Nothing in `drop-core` may import from `preact`** (or any UI framework).
+  Anything that imports preact may not contain deploy/read/detect logic — it
+  adapts this package to a view, nothing more.
+- **The barrel is the public API.** Nothing is public unless `index.ts` names
+  it; `export *` is reserved for modules that are contracts in their entirety
+  (`types`, `errors`, `analytics`). New helpers default to private.
+- **Granular pure modules, one cohesive orchestrator.** Pure helpers get their
+  own small file named after what they export; the deploy orchestration stays
+  together in `deploy.ts` rather than fragmenting a state machine.
+- **Shared tunables live in `constants.ts`** with a unit-bearing comment each
+  (`// 10 minutes`, not `// the timeout`). Module-specific constants stay with
+  their module. No magic numbers inline.
+
+### Naming
+
+| Kind               | Convention                         | Examples here                                                 |
+| ------------------ | ---------------------------------- | ------------------------------------------------------------- |
+| Outcome callbacks  | `onVerb` / past participle         | `onDeploy`, `onBuildRequired`, `onError`                      |
+| Boolean state      | `isX`                              | `busy` (exception, pre-dates rule), `isNotAuthenticatedError` |
+| Strategy injection | bare noun                          | `client`, `buildClient`, `validator`-style                    |
+| Analytics events   | `dropzone_snake_case` — **frozen** | `DROPZONE_EVENTS` (test-pinned wire names)                    |
+| Error predicates   | `isXError(err)`                    | `isNotAuthenticatedError`                                     |
+| Files              | filename = main export             | `detectBuild.ts`, `buildStash.ts`                             |
+
+### Comments
+
+- **WHY over WHAT.** A comment earns its place by stating something the code
+  can't: an invariant, an observed API behavior, a browser quirk, a
+  don't-simplify warning. Never narrate the next line.
+- **Record observed API behavior, with receipts.** The model comment in this
+  package: readiness polling keys off `deploy_id` (BSON), not `deploy.id` (site
+  UUID), "or the request 401s misleadingly" — naming the server-side file. Say
+  what the server _actually does_, and link the server source when you can.
+- **Repeat load-bearing quirk notes at every call site.** The `deploy_id` note
+  appears in the client _and_ the orchestrator on purpose — a note that only
+  exists where nobody is reading protects nothing.
+- **"Don't simplify" notes name what breaks** — the invariant, and ideally the
+  test that pins it (e.g. the `NotAuthenticatedError` boundary below).
+- **No `@param`/`@returns`.** Types carry the shape; JSDoc carries rationale
+  and edge cases. (react-dropzone: zero `@param` across its entire source.)
+- File-header purpose blocks only where the filename undersells the contents.
+
+### Errors
+
+- **Class per failure, each with a readonly kebab-case `code` brand.** This
+  package ships as raw TS (`./components`) _and_ compiled dist (`./preact`,
+  `./drop-core`) — two copies of a class can coexist in one app and defeat
+  `instanceof`. Detection that steers control flow must go through a
+  code-checking predicate (`isNotAuthenticatedError`), never bare `instanceof`.
+- **`NotAuthenticatedError` is pre-mutation only.** It may be thrown solely
+  before anything is created (token gate, site-create 401) — it is the signal
+  that an anonymous retry is safe. Throwing it after a site exists would strand
+  an empty project and deploy a duplicate. Pinned by tests.
+- **Humanized copy lives in `humanizeDropError`, in this package.** A
+  deliberate divergence from @vercel/client (which leaves rendering to the
+  CLI): our consumers render our copy directly, and the docs promise it.
+- Transient upload failures retry on `UPLOAD_RETRY_DELAYS_MS` (backoff as
+  data, the tus idiom); **400/422 never retry** — the request itself is wrong.
+
+### Considered and rejected
+
+- **Async-generator lifecycles** (@vercel/client): our phase-callback design is
+  equivalent and churn-free; `DeployPhase` is a closed union, which netlify-cli's
+  own author wished theirs was.
+- **Kebab-case event renames**: `dropzone_*` wire names are pinned analytics
+  history; `analytics.test.ts` fails on any rename. Append-only.
+- **`getRootProps`/`getInputProps` attribute getters** (react-dropzone, Uppy):
+  the right shape for a future framework-free UI tier shared with the app —
+  not something to bolt onto the shipped wrapper component.
+- **A `defaultOptions` object** (tus, Uppy): our destructured constructor
+  defaults are react-dropzone's pattern; either is fine, we have this one.

package/packages/drop-core/authedApi.ts

@@ -9,19 +9,6 @@ import { NotAuthenticatedError, SiteCreateError } from './errors';
  * ~6MB — and each client handles its own, bearer-authorized.)
  */
 
-/**
- * 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

package/packages/drop-core/authedDropClient.ts

@@ -1,13 +1,13 @@
+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 {
@@ -42,13 +42,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) */
@@ -104,11 +97,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();
@@ -119,12 +109,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.
+   * cached one nears its 30s expiry. A mint failure here is a plain `Error`,
+   * never `NotAuthenticatedError` — the site exists by now (class doc).
    */
   private async freshToken(): Promise<string> {
     const now = Date.now();
@@ -143,8 +129,6 @@ export class AuthenticatedDropClient implements DropClient {
    * `deployFiles` runs unchanged over either client.
    */
   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`, {
@@ -197,14 +181,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.ts

@@ -1,11 +1,10 @@
+import { createSiteInAccount, pollDeployUntilSettled } from './authedApi';
 import {
-  createSiteInAccount,
   DEFAULT_API_BASE,
   DEFAULT_POLL_INTERVAL_MS,
   DEFAULT_PROXY_BASE,
   DEFAULT_TIMEOUT_MS,
-  pollDeployUntilSettled,
-} from './authedApi';
+} from './constants';
 import {
   BuildCreateError,
   BuildFailedError,

package/packages/drop-core/client.ts

@@ -1,3 +1,12 @@
+/**
+ * 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`).
+ */
+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 +21,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).
  */
 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' });
@@ -57,13 +68,14 @@ export class AnonymousDropClient implements DropClient {
     // 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++) {
+    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,39 @@
+/**
+ * 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.
+ */
+
+/**
+ * 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.
+ */
+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;
+
+/**
+ * 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.
+ */
+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`.
+ */
+export const UPLOAD_RETRY_DELAYS_MS: readonly number[] = [1_000, 2_000, 3_000];

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

@@ -71,6 +71,48 @@ describe('deployFiles', () => {
     expect(phases[1]).toEqual({ phase: 'uploading', uploaded: 0, total: 1 });
   });
 
+  it('retries a transient upload failure and succeeds', async () => {
+    const { client } = stubDropClient(['aaa']);
+    let attempts = 0;
+    (client.uploadFile as ReturnType<typeof vi.fn>).mockImplementation(async () => {
+      if (++attempts === 1) throw Object.assign(new Error('upload failed: 502'), { status: 502 });
+    });
+    await deployFiles(client, files, { retryDelays: [0, 0] });
+    expect(attempts).toBe(2);
+  });
+
+  it('gives up once the retry curve is exhausted', async () => {
+    const { client } = stubDropClient(['aaa']);
+    let attempts = 0;
+    (client.uploadFile as ReturnType<typeof vi.fn>).mockImplementation(async () => {
+      attempts++;
+      throw Object.assign(new Error('upload failed: 503'), { status: 503 });
+    });
+    await expect(deployFiles(client, files, { retryDelays: [0, 0] })).rejects.toThrow('503');
+    expect(attempts).toBe(3); // initial try + one per delay
+  });
+
+  it('never retries a 400/422 — the request itself is wrong', async () => {
+    const { client } = stubDropClient(['aaa']);
+    let attempts = 0;
+    (client.uploadFile as ReturnType<typeof vi.fn>).mockImplementation(async () => {
+      attempts++;
+      throw Object.assign(new Error('upload failed: 422'), { status: 422 });
+    });
+    await expect(deployFiles(client, files, { retryDelays: [0, 0] })).rejects.toThrow('422');
+    expect(attempts).toBe(1);
+  });
+
+  it('retries statusless network failures too', async () => {
+    const { client } = stubDropClient(['aaa']);
+    let attempts = 0;
+    (client.uploadFile as ReturnType<typeof vi.fn>).mockImplementation(async () => {
+      if (++attempts === 1) throw new TypeError('fetch failed');
+    });
+    await deployFiles(client, files, { retryDelays: [0] });
+    expect(attempts).toBe(2);
+  });
+
   it('throws on an empty file set before any network call', async () => {
     const { client } = stubDropClient([]);
     await expect(deployFiles(client, [])).rejects.toThrow('No files to deploy');

package/packages/drop-core/deploy.ts

@@ -1,3 +1,4 @@
+import { MAX_CONCURRENT_UPLOADS, UPLOAD_RETRY_DELAYS_MS } from './constants';
 import { getDigest } from './digest';
 import type { BuildClient, BuildResponse, BuildSite } from './buildClient';
 import type { DropClient } from './client';
@@ -5,7 +6,33 @@ import type { InferredBuildSettings } from './detectBuild';
 import type { DeployProgress, DeployResult, ProcessedFile } from './types';
 import { zipFiles, type ZipResult } from './zip';
 
-const MAX_CONCURRENT_UPLOADS = 5;
+/** 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.
+ */
+async function uploadWithRetry(
+  client: DropClient,
+  deployId: string,
+  file: ProcessedFile,
+  token: string,
+  retryDelays: readonly number[]
+): Promise<void> {
+  for (let attempt = 0; ; attempt++) {
+    try {
+      await client.uploadFile(deployId, file.path, file.content, token);
+      return;
+    } catch (err) {
+      const status = (err as { status?: number }).status;
+      if (status !== undefined && NON_RETRIABLE_STATUSES.has(status)) throw err;
+      if (attempt >= retryDelays.length) throw err;
+      await new Promise(r => setTimeout(r, retryDelays[attempt]));
+    }
+  }
+}
 
 async function uploadRequired(
   client: DropClient,
@@ -13,6 +40,7 @@ async function uploadRequired(
   files: ProcessedFile[],
   required: Set<string>,
   token: string,
+  retryDelays: readonly number[],
   onUploaded?: (uploaded: number) => void
 ) {
   const queue = files.filter(f => required.has(f.sha));
@@ -21,7 +49,7 @@ async function uploadRequired(
   const worker = async () => {
     while (cursor < queue.length) {
       const f = queue[cursor++];
-      await client.uploadFile(deployId, f.path, f.content, token);
+      await uploadWithRetry(client, deployId, f, token, retryDelays);
       onUploaded?.(++done);
     }
   };
@@ -30,6 +58,8 @@ async function uploadRequired(
 
 export interface DeployOptions {
   onProgress?: (e: DeployProgress) => void;
+  /** Waits between retries of a failed file upload. Override for tests or a different curve. */
+  retryDelays?: readonly number[];
 }
 
 export async function deployFiles(
@@ -38,7 +68,7 @@ export async function deployFiles(
   opts: DeployOptions = {}
 ): Promise<DeployResult> {
   if (!files.length) throw new Error('No files to deploy');
-  const { onProgress } = opts;
+  const { onProgress, retryDelays = UPLOAD_RETRY_DELAYS_MS } = opts;
 
   onProgress?.({ phase: 'creating' });
   const token = await client.getToken();
@@ -48,8 +78,14 @@ export async function deployFiles(
   onProgress?.({ phase: 'uploading', uploaded: 0, total });
   // File PUTs and readiness polling both key off `deploy_id` (BSON), NOT
   // `deploy.id` (the site UUID) — see the note in client.waitUntilReady.
-  await uploadRequired(client, deploy.deploy_id, files, new Set(deploy.required), token, uploaded =>
-    onProgress?.({ phase: 'uploading', uploaded, total })
+  await uploadRequired(
+    client,
+    deploy.deploy_id,
+    files,
+    new Set(deploy.required),
+    token,
+    retryDelays,
+    uploaded => onProgress?.({ phase: 'uploading', uploaded, total })
   );
 
   onProgress?.({ phase: 'processing' });

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

@@ -4,12 +4,39 @@ import {
   BuildCreateError,
   BuildFailedError,
   BuildTimeoutError,
+  DeployFailedError,
+  DeployTimeoutError,
   humanizeDropError,
+  isNotAuthenticatedError,
   NotAuthenticatedError,
   SiteCreateError,
   UnsupportedDropError,
 } from './errors';
 
+describe('error codes', () => {
+  it('pins each class to its copy-proof code brand', () => {
+    expect(new UnsupportedDropError().code).toBe('unsupported-drop');
+    expect(new NotAuthenticatedError().code).toBe('not-authenticated');
+    expect(new SiteCreateError().code).toBe('site-create-failed');
+    expect(new BuildCreateError().code).toBe('build-create-failed');
+    expect(new BuildFailedError().code).toBe('build-failed');
+    expect(new BuildTimeoutError().code).toBe('build-timeout');
+    expect(new DeployFailedError().code).toBe('deploy-failed');
+    expect(new DeployTimeoutError().code).toBe('deploy-timeout');
+  });
+
+  it('recognizes a foreign-copy NotAuthenticatedError by its code', () => {
+    // Raw-TS and dist entrypoints can each load their own class copy;
+    // instanceof fails across copies, the code brand does not.
+    const foreignCopy = Object.assign(new Error('not authenticated'), {
+      code: 'not-authenticated',
+    });
+    expect(isNotAuthenticatedError(foreignCopy)).toBe(true);
+    expect(isNotAuthenticatedError(new Error('nope'))).toBe(false);
+    expect(isNotAuthenticatedError('not-authenticated')).toBe(false);
+  });
+});
+
 describe('humanizeDropError', () => {
   it('maps each typed error to its user-facing copy', () => {
     expect(humanizeDropError(new UnsupportedDropError())).toBe(
@@ -44,10 +71,12 @@ describe('humanizeDropError', () => {
     expect(humanizeDropError(new BuildCreateError(413))).toContain('too large');
   });
 
-  it('maps the shared deploy-timeout message', () => {
-    expect(humanizeDropError(new Error('Deploy did not become ready in time'))).toContain(
-      'taking longer than expected'
+  it('maps the deploy timeout and failure classes', () => {
+    expect(humanizeDropError(new DeployTimeoutError())).toContain('taking longer than expected');
+    expect(humanizeDropError(new DeployFailedError('no index.html'))).toBe(
+      'Your deploy failed: no index.html'
     );
+    expect(humanizeDropError(new DeployFailedError())).toBe('Your deploy failed. Please try again.');
   });
 
   it('reads a fetch TypeError as a connectivity problem', () => {