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

package/packages/components/preact/DropZone/DropZone.tsx

@@ -25,26 +25,13 @@ const DRAG_INACTIVE_MS = 120;
 
 const defaultClaimUrl = (siteName: string) => `https://app.netlify.com/drop/${siteName}`;
 
-/**
- * Where an authenticated static deploy lands: the new site's project overview,
- * the same place the app's own logged-in drop sends you.
- */
+/** The project overview — where the app's own logged-in drop lands too. */
 const defaultSiteDashboardUrl = (siteName: string) =>
   `https://app.netlify.com/projects/${siteName}`;
 
-/**
- * Where a build-required drop is sent by default. Mirrors the app's own Drop
- * page: signup with `next=/drop`, so after signup + email verification the user
- * lands back on the authenticated Drop page and can build there.
- */
+// Mirrors the app's own Drop page hand-off.
 const defaultBuildSignupUrl = 'https://app.netlify.com/signup?next=/drop&utm_campaign=drop';
 
-/**
- * Where an authenticated build drop lands: the new site's project overview —
- * the same destination as a static deploy, and where the app's own Drop page
- * sends build drops. The overview surfaces the in-progress deploy; consumers
- * who want the deploy-log page instead can override with `build.deployId`.
- */
 const defaultBuildDeployUrl = ({ siteName }: DeployedBuild) =>
   `https://app.netlify.com/projects/${siteName}`;
 
@@ -57,29 +44,17 @@ interface Props {
   client?: DropClient;
   /** Build the "claim this site" URL from the assigned site name (subdomain). */
   claimUrl?: (siteName: string) => string;
-  /**
-   * Where an authenticated static deploy sends the visitor — the site already
-   * lives in their account, so there is no claim step. Defaults to the new
-   * site's project overview on app.netlify.com.
-   */
+  /** Destination after an authenticated static deploy (no claim step). Default: the project overview. */
   siteDashboardUrl?: (siteName: string) => string;
   /**
-   * The signup hand-off for a build-required drop that can't be built here (no
-   * session, or no build wiring). The drop is stashed on this origin first, so
-   * a flow that returns the visitor to this page deploys it automatically —
-   * see `resumeStashedBuilds`. Defaults to the app signup page with
-   * `next=/drop`.
+   * Signup hand-off for a build drop with no session. The drop is stashed on
+   * this origin first — return the visitor here and it deploys automatically.
    */
   buildSignupUrl?: string;
   /**
-   * Mint a short-lived bearer token for direct api.netlify.com uploads — pass it
-   * to switch on the whole authenticated path for logged-in visitors: static
-   * drops deploy straight into their account (then `siteDashboardUrl`), and
-   * build-required drops build in place instead of being handed off to the app.
-   * On netlify.com this reads `GET /access-control/generate-access-control-token`.
-   * Resolving `null` means "no session": static drops fall back to the anonymous
-   * claim flow; build drops are stashed and handed to `buildSignupUrl`.
-   * See [Logged-in visitors](#logged-in-visitors).
+   * Mint the upload bearer — passing this switches on the whole authenticated
+   * path. `null` means "no session": static drops fall back to the anonymous
+   * claim flow; build drops stash and hand off. See the docs' Logged-in visitors.
    */
   getUploadToken?: () => Promise<string | null>;
   /**
@@ -87,108 +62,46 @@ interface Props {
    * Takes precedence over `getUploadToken` for the build path.
    */
   buildClient?: BuildClient;
-  /**
-   * Inject a custom authenticated `DropClient` for static drops (tests, staging,
-   * a different account flow). Takes precedence over `getUploadToken` for the
-   * static path. Distinct from `client`, which is the anonymous fallback.
-   */
+  /** Custom authenticated static-drop client; wins over `getUploadToken`. (`client` is the anonymous fallback.) */
   authenticatedDropClient?: DropClient;
-  /**
-   * API root for the authenticated paths' JSON calls, which go through your
-   * access-control rewrite so the session cookie authorizes them. Defaults to
-   * `/access-control/bb-api/api/v1`. (Uploads always go direct to
-   * `api.netlify.com` — the proxy can't carry bodies that large.)
-   */
+  /** Root for the session-cookie JSON calls, via your access-control rewrite. Uploads always go direct. */
   proxyBase?: string;
   /** Create the visitor's new project in this account. Omit for their default account. */
   accountSlug?: string;
-  /**
-   * Where an enqueued build sends the visitor. Defaults to the new site's
-   * project overview, same as a static deploy; `build.deployId` is available for
-   * consumers who want the deploy-log page instead.
-   */
+  /** Destination after a build is enqueued. Default: the project overview (`build.deployId` for the logs page). */
   buildDeployUrl?: (build: DeployedBuild) => string;
   /**
-   * Poll until the build finishes before handing off, instead of redirecting as
-   * soon as it's enqueued. The trade-off: waiting means a failing build surfaces
-   * its own error message here (via `onError` and the overlay) rather than the
-   * visitor discovering it on the deploy page — at the cost of holding them on a
-   * spinner for the length of the build, which is minutes. Off by default.
+   * Hold the visitor until the build finishes (off by default — builds take
+   * minutes). On is the only way a failing build's own message reaches `onError`.
    */
   waitForBuild?: boolean;
-  /**
-   * Called when a build-required drop is detected, instead of building it or
-   * redirecting. Use it to own the hand-off yourself (custom routing, persisting
-   * the drop, gating on auth). When set, the component neither builds nor
-   * redirects. The static drop path is unaffected either way.
-   */
+  /** Take over build-required drops entirely — when set, the component neither builds nor redirects. */
   onBuildRequired?: (info: BuildDetection) => void;
   /**
-   * Called instead of the `buildSignupUrl` redirect when a build-required drop
-   * can't be built here (no session). By this point the drop has been stashed
-   * on this origin (`stashed` says whether that succeeded) — own the hand-off
-   * however fits your auth flow, e.g. open a signup popup that keeps the
-   * visitor on the page. Once they're back authenticated, a remount of the
-   * zone deploys the stash automatically.
+   * Own the signup hand-off instead of the `buildSignupUrl` redirect (e.g. an
+   * auth popup). The drop is already stashed; a remount while authenticated
+   * deploys it.
    */
   onBuildSignupHandoff?: (info: { stashed: boolean; detection: BuildDetection }) => void;
-  /**
-   * Deploy a previously stashed build drop automatically when the zone mounts
-   * with an authenticated visitor (default `true`). The stash is written when a
-   * logged-out build drop is handed to signup; see
-   * [Signup hand-off and auto-resume](#signup-hand-off-and-auto-resume).
-   */
+  /** Auto-deploy a stashed build drop on mount when authenticated (default true). */
   resumeStashedBuilds?: boolean;
   /** Called once the deploy is live. */
   onDeploy?: (result: DeployedSite) => void;
-  /**
-   * Called once a build-required drop has been zipped, uploaded and enqueued —
-   * before the redirect to `buildDeployUrl`. The site exists at this point but
-   * won't serve content until the build finishes.
-   */
+  /** Called once a build is enqueued, before the `buildDeployUrl` redirect. */
   onBuildDeploy?: (build: DeployedBuild) => void;
-  /**
-   * Called when a deploy fails, with a humanized `message` (ready to show a
-   * user — the same copy the built-in overlay uses) and the raw `reason`. Pair
-   * this with `showStatus={false}` to render your own error UI.
-   */
+  /** Deploy failures: humanized `message` (the overlay's copy) + raw `reason`. Pair with showStatus={false}. */
   onError?: (error: DeployError) => void;
   /**
-   * Render the built-in status overlay (drag tint, spinner, progress bar, error).
-   * Set to `false` to suppress it entirely and keep your children visible, then
-   * drive your own feedback from the `data-state` attribute on the root element.
-   * Note: in this mode you're responsible for surfacing errors yourself — use
-   * `onError` to get the message.
+   * Render the built-in overlay. `false` keeps children visible — drive your
+   * own feedback from `data-state`, and surface errors yourself via `onError`.
    */
   showStatus?: boolean;
   /**
-   * Analytics hook. Called at each tracked moment with an event name and
-   * properties. Stays provider-agnostic — wire it to Segment/Amplitude/GA in the
-   * consuming app, e.g. `onTrack={(name, props) => new Analytics().track(name, props)}`.
-   * Emitted events (all include `dropzone_id` when `analyticsId` is set):
-   * - `dropzone_files_dropped`  — files dropped via drag  ({ method: 'drag', file_count, file_types })
-   * - `dropzone_browse_opened`  — file picker opened       ({ method: 'keyboard' | 'click' })
-   * - `dropzone_build_required` — drop needs a build (built here, or handed off) ({ method, reason, file_count, file_types })
-   * - `dropzone_deploy_succeeded` — static deploy went live ({ method, site_name, file_count, authenticated, auth_fallback?, file_types })
-   * - `dropzone_build_deploy_succeeded` — build enqueued for a logged-in visitor ({ method, reason, site_name, file_count, framework?, file_types })
-   * - `dropzone_deploy_failed`  — deploy or build errored out ({ method, reason, file_count?, file_types })
-   *
-   * `authenticated` says whether the deploy landed in the visitor's account;
-   * `auth_fallback: true` is sent only when an authenticated attempt bounced
-   * (stale auth hint) and the drop completed anonymously — omitted otherwise.
-   * `file_types` is the sorted, de-duplicated list of MIME types in the
-   * selection, with `application/octet-stream` standing in wherever the browser
-   * reports none (a dragged folder, an `.exe`). It is omitted when the browser
-   * exposes no files at all. Note `dropzone_files_dropped` only fires for drag —
-   * a file-picker selection reports its types on the outcome events, as
-   * `dropzone_browse_opened` fires before any file exists.
+   * Provider-agnostic analytics hook. Event names and payload shapes live in
+   * DROPZONE_EVENTS / DropZoneEventProperties (drop-core/analytics.ts).
    */
   onTrack?: TrackFn;
-  /**
-   * Stable identifier for this instance, attached to every tracked event as
-   * `dropzone_id`. Set it when a page renders more than one Drop Zone so the
-   * events can be told apart in Amplitude.
-   */
+  /** Stamped on every event as `dropzone_id` — set when a page has more than one zone. */
   analyticsId?: string;
   className?: string;
 }
@@ -218,8 +131,6 @@ export default function DropZone({
   analyticsId,
   className,
 }: Props) {
-  // Tag every event with this instance's id so multiple zones on a page can be
-  // told apart, then hand it off to the consumer's analytics.
   const track: TrackFn = (event, properties = {}) =>
     onTrack?.(event, analyticsId ? { dropzone_id: analyticsId, ...properties } : properties);
 
@@ -253,8 +164,6 @@ export default function DropZone({
     inputRef.current?.click();
   };
 
-  // The overlay only paints when there's something to show — dragging, deploying,
-  // or an error. With `showStatus` off, the consumer drives their own feedback.
   const showOverlay = showStatus && (active || busy || status.kind === 'error');
   const rootClass = [
     'n-dropzone',
@@ -343,11 +252,8 @@ export default function DropZone({
 }
 
 /**
- * Track whether a drag is currently over the zone. A drag has no reliable
- * "cancelled" event — pressing Escape or dropping elsewhere just stops the
- * stream of `dragover` events — so we stay active only while they keep arriving
- * and clear shortly after they stop. This also handles drags over children,
- * where `dragleave` targets a child rather than the zone.
+ * Drag-over tracking by dragover decay: drags have no reliable cancel event,
+ * and dragleave targets children — so stay active while events keep arriving.
  */
 function useDragActive() {
   const [active, setActive] = useState(false);

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

@@ -112,7 +112,6 @@ interface UseDropDeployOptions {
   track: TrackFn;
 }
 
-/** Map a low-level deploy progress event onto our UI status. */
 function progressToStatus(e: DeployProgress): DeployStatus {
   switch (e.phase) {
     case 'zipping':
@@ -129,7 +128,7 @@ function progressToStatus(e: DeployProgress): DeployStatus {
   }
 }
 
-/** Inspect the file set and return a non-blocking index.html warning, if any. */
+/** Advisory only — a missing index.html never fails the deploy. */
 function indexHtmlWarning(files: ProcessedFile[]): string | null {
   const singleNonIndex = getSingleNonIndexHtmlFileName(files);
   if (singleNonIndex) {
@@ -142,12 +141,9 @@ function indexHtmlWarning(files: ProcessedFile[]): string | null {
 }
 
 /**
- * Best-effort local persistence of the anonymous claim handoff. Note this does
- * NOT reach the dashboard: localStorage is per-origin, so a token written here
- * (e.g. www.netlify.com) is invisible to app.netlify.com. The cross-origin
- * handoff is the URL fragment on the claim redirect; this only helps if the
- * drop and claim share an origin. Authenticated deploys never call this —
- * there is no claim token, and the upload bearer must never be persisted.
+ * Best-effort claim persistence. localStorage is per-origin, so this never
+ * reaches app.netlify.com — the URL fragment is the real cross-origin handoff.
+ * Authenticated deploys skip it: no claim token, and bearers are never persisted.
  */
 function persistAnonymousClaimLocally(token: string, siteName: string): void {
   try {
@@ -183,11 +179,7 @@ export function useDropDeploy({
   onError,
   track,
 }: UseDropDeployOptions) {
-  /**
-   * 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.
-   */
+  /** Typed veneer over `track` — a renamed property fails to compile instead of forking analytics history. */
   const emit = <E extends DropZoneEventName>(event: E, props: DropZoneEventProperties[E]) =>
     // The event interfaces carry no index signature, hence the cast to TrackFn's record.
     track(event, props as Record<string, unknown>);
@@ -220,10 +212,8 @@ export function useDropDeploy({
   const busy = status.kind !== 'idle' && status.kind !== 'error';
 
   /**
-   * Create a site and enqueue a build for an already-zipped drop. Returns
-   * `null` when the visitor turns out not to be logged in — nothing is created
-   * in that case, so the caller can still stash the archive and hand off to
-   * signup. Every other failure throws and is reported by the caller's `catch`.
+   * Site + build for a zipped drop. `null` = not logged in (nothing created,
+   * so the caller can still stash and hand off); other failures throw.
    */
   async function enqueueZippedBuild(
     client: BuildClient,
@@ -257,10 +247,8 @@ export function useDropDeploy({
   }
 
   /**
-   * `fileTypes` is the MIME types of the selection, read at the drop boundary
-   * (see `getFileTypes`) and passed in rather than derived here — it has to be
-   * captured before `read()` runs so it survives a read that throws. Omitted
-   * from events when empty rather than sent as `[]`.
+   * `fileTypes` is captured at the drop boundary, before `read()` runs, so it
+   * survives a read that throws. Omitted from events when empty, never `[]`.
    */
   async function deploy(
     read: () => Promise<ProcessedFile[]>,
@@ -272,12 +260,8 @@ export function useDropDeploy({
 
     const typeProps = fileTypes.length ? { file_types: fileTypes } : {};
 
-    // 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.
+    // Single failure funnel. `file_count` only when the file set is known;
+    // `reason` is raw for analytics, `message` is the humanized copy; `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 });
@@ -285,10 +269,9 @@ export function useDropDeploy({
     };
 
     try {
-      // Auto-rename a lone non-index HTML file to index.html so it is served at
-      // the site root. Detection (getSingleNonIndexHtmlFileName) sits on the
-      // read side; recompute the warning on the renamed set so the fixable
-      // single-file case no longer warns and only the multi-HTML case does.
+      // Rename a lone non-index HTML file so it is served at the site root.
+      // Warnings are computed on the renamed set, so the fixable single-file
+      // case no longer warns and only the multi-HTML case does.
       const files = renameSingleNonIndexHtmlToIndex(await read());
       if (!files.length) {
         fail('No files found to deploy.', 'No files found to deploy.', { file_count: 0 });
@@ -319,12 +302,8 @@ export function useDropDeploy({
   }
 
   /**
-   * A drop that needs a build. Build-required projects can't deploy through the
-   * anonymous drop API — it only performs static deploys, so building one this
-   * way yields a broken site. They're routed to the authenticated build path
-   * instead, or stashed and handed off to signup when there is no session.
-   * Consumers can take over entirely with `onBuildRequired`, or own just the
-   * signup hand-off with `onBuildSignupHandoff`.
+   * Build-required drops can't use the anonymous API (static-only): build in
+   * the account, or stash + hand off to signup when there's no session.
    */
   async function handleBuildRequiredDrop(
     files: ProcessedFile[],
@@ -372,8 +351,7 @@ export function useDropDeploy({
 
       // No session after all (the auth hint cookie can outlive the session).
       // Nothing was created — stash the archive so the drop survives the
-      // signup round-trip. When the visitor is back on this origin
-      // authenticated, the mount-time resume deploys it for them.
+      // signup round-trip.
       stashed = await saveDropStash(archive.file, archive.buildSettings);
       if (stashed) {
         emit(DROPZONE_EVENTS.PROJECT_STASHED, {
@@ -399,13 +377,9 @@ export function useDropDeploy({
   }
 
   /**
-   * Try the authenticated static deploy, or report that the visitor has no
-   * session. NotAuthenticatedError is the one failure that returns null and
-   * lets the caller fall back to the anonymous flow — it's thrown before
-   * anything is created (the auth hint cookie can outlive the session), so
-   * retrying anonymously can't strand a half-made site. Any later failure is
-   * real and rethrows: falling back then would leave an empty site in the
-   * account and deploy a duplicate.
+   * `null` = no session (pre-mutation, so the anonymous fallback is safe).
+   * Anything else rethrows — falling back after the site exists would strand
+   * an empty site and deploy a duplicate.
    */
   async function attemptAuthenticatedStaticDeploy(
     client: DropClient,
@@ -447,11 +421,10 @@ export function useDropDeploy({
     }
 
     setStatus({ kind: 'redirecting', target: authenticated ? 'dashboard' : 'claim' });
-    // Fired before the redirect below. Note: the navigation can cut a
-    // fire-and-forget analytics request short — see the docs for delivery
-    // hardening (sendBeacon / deferring the redirect). `auth_fallback` is only
-    // sent when an authenticated attempt bounced (stale auth hint) — omitted
-    // otherwise, like `file_types`.
+    // The redirect below can cut a fire-and-forget analytics request short;
+    // harden delivery with sendBeacon or by deferring the redirect.
+    // `auth_fallback` is only sent when an authenticated attempt bounced
+    // (stale auth hint) — omitted otherwise, like `file_types`.
     emit(DROPZONE_EVENTS.DEPLOY_SUCCEEDED, {
       method: source,
       site_name: result.subdomain,
@@ -471,7 +444,6 @@ export function useDropDeploy({
     redirectAfterStaticDeploy(authenticated, result.subdomain, token);
   }
 
-  /** Hand the visitor to their new site: its dashboard page, or the claim page. */
   function redirectAfterStaticDeploy(authenticated: boolean, siteName: string, token: string) {
     if (authenticated) {
       // The site already lives in the visitor's account — send them straight
@@ -486,13 +458,8 @@ export function useDropDeploy({
   }
 
   /**
-   * Deploy a drop stashed before the signup hand-off (see `buildStash`).
-   *
-   * The stash is consumed only once the visitor is provably authenticated —
-   * the marker (or the auth hint behind `getUploadToken`) can outlive the
-   * session, and consuming on a bounced attempt would quietly lose the drop.
-   * Once past that gate it is consumed whether the deploy succeeds or fails,
-   * so a broken project can never retry-loop.
+   * Deploy the stashed drop. Consumed only once provably authenticated (a
+   * bounced attempt keeps it), then consumed win or lose — no retry loops.
    */
   async function resumeStashedBuild(client: BuildClient) {
     const stash = await loadDropStash();
@@ -517,7 +484,7 @@ export function useDropDeploy({
 
     if (!built) {
       // Still no session — the visitor came back logged out. Keep the stash for
-      // their next authenticated visit and return to idle without fuss.
+      // their next authenticated visit.
       setStatus({ kind: 'idle' });
       return;
     }

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,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 () => {