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

package/packages/drop-core/analytics.ts

@@ -0,0 +1,122 @@
+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.
+ */
+
+/** 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.
+ */
+export const DROPZONE_EVENTS = {
+  /** Files arrived via drag — the picker path reports its files on outcome events instead. */
+  FILES_DROPPED: 'dropzone_files_dropped',
+  /** The native file picker was opened (keyboard or click). */
+  BROWSE_OPENED: 'dropzone_browse_opened',
+  /** The drop needs a build — it will be built in place, stashed, or handed off. */
+  BUILD_REQUIRED: 'dropzone_build_required',
+  /** A static deploy went live (anonymous or into the visitor's account). */
+  DEPLOY_SUCCEEDED: 'dropzone_deploy_succeeded',
+  /** A build was enqueued in the visitor's account. */
+  BUILD_DEPLOY_SUCCEEDED: 'dropzone_build_deploy_succeeded',
+  /** Any attempt ended in an error (including a failed resume). */
+  DEPLOY_FAILED: 'dropzone_deploy_failed',
+  /** A logged-out build drop was stashed locally before the signup hand-off. */
+  PROJECT_STASHED: 'dropzone_project_stashed',
+  /** A stashed build drop was picked up for automatic deployment. */
+  RESUMED: 'dropzone_resumed',
+} as const;
+
+export type DropZoneEventName = (typeof DROPZONE_EVENTS)[keyof typeof DROPZONE_EVENTS];
+
+/** Properties the component adds to every event. */
+export interface DropZoneBaseEventProps {
+  /** Present when the consumer sets `analyticsId` — tells multiple zones apart. */
+  dropzone_id?: string;
+}
+
+export interface FilesDroppedProps extends DropZoneBaseEventProps {
+  method: 'drag';
+  file_count: number;
+  /** Omitted — never `[]` — when the browser exposes no files. */
+  file_types?: string[];
+}
+
+export interface BrowseOpenedProps extends DropZoneBaseEventProps {
+  method: 'keyboard' | 'click';
+}
+
+export interface BuildRequiredProps extends DropZoneBaseEventProps {
+  method: DropMethod;
+  reason: BuildReason | null;
+  file_count: number;
+  file_types?: string[];
+}
+
+export interface DeploySucceededProps extends DropZoneBaseEventProps {
+  method: DropMethod;
+  site_name: string;
+  file_count: number;
+  /** Whether the deploy landed directly in the visitor's account. */
+  authenticated: boolean;
+  /** Present only when an authenticated attempt bounced (stale login hint) and the drop completed anonymously. */
+  auth_fallback?: true;
+  file_types?: string[];
+}
+
+export interface BuildDeploySucceededProps extends DropZoneBaseEventProps {
+  method: DropMethod;
+  reason: BuildReason | null;
+  site_name: string;
+  file_count: number;
+  /** Present when build settings were synthesised into the archive. */
+  framework?: string;
+  file_types?: string[];
+}
+
+export interface DeployFailedProps extends DropZoneBaseEventProps {
+  /** Absent when the failure comes from a stash resume rather than a live drop gesture. */
+  method?: DropMethod;
+  /** Raw failure reason (e.g. "drop failed: 429", "resume_failed") — the humanized copy goes to the UI, not here. */
+  reason: string;
+  /** Present only when the file set is known (absent when reading itself threw). */
+  file_count?: number;
+  file_types?: string[];
+}
+
+export interface ProjectStashedProps extends DropZoneBaseEventProps {
+  method: DropMethod;
+  reason: BuildReason | null;
+  file_count: number;
+  file_types?: string[];
+}
+
+/** A resume starts from storage, not a fresh gesture — no method or file set to report. */
+export type ResumedProps = DropZoneBaseEventProps;
+
+/** Event name → its property shape, for typed emitters and sinks on either side of the seam. */
+export interface DropZoneEventProperties {
+  dropzone_files_dropped: FilesDroppedProps;
+  dropzone_browse_opened: BrowseOpenedProps;
+  dropzone_build_required: BuildRequiredProps;
+  dropzone_deploy_succeeded: DeploySucceededProps;
+  dropzone_build_deploy_succeeded: BuildDeploySucceededProps;
+  dropzone_deploy_failed: DeployFailedProps;
+  dropzone_project_stashed: ProjectStashedProps;
+  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.
+ */
+export type TrackFn = (event: string, properties?: Record<string, unknown>) => void;

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

@@ -0,0 +1,100 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { createSiteInAccount, pollDeployUntilSettled } from './authedApi';
+import { NotAuthenticatedError, SiteCreateError } from './errors';
+
+const PROXY = '/access-control/bb-api/api/v1';
+
+afterEach(() => vi.unstubAllGlobals());
+
+describe('createSiteInAccount', () => {
+  const record = () => {
+    const calls: Array<{ url: string; init: RequestInit }> = [];
+    vi.stubGlobal('fetch', async (url: unknown, init: RequestInit = {}) => {
+      calls.push({ url: String(url), init });
+      return { ok: true, status: 200, json: async () => ({ id: 's', name: 'n' }) } as Response;
+    });
+    return calls;
+  };
+
+  it('POSTs through the proxy on the session cookie, attributed to drop', async () => {
+    const calls = record();
+    const site = await createSiteInAccount(PROXY);
+    expect(site).toEqual({ id: 's', name: 'n' });
+    expect(calls[0].url).toBe(`${PROXY}/sites`);
+    expect(calls[0].init.credentials).toBe('include');
+    expect(JSON.parse(String(calls[0].init.body))).toEqual({ created_via: 'drop' });
+  });
+
+  it('scopes to the account slug when given', async () => {
+    const calls = record();
+    await createSiteInAccount(PROXY, 'my-team');
+    expect(calls[0].url).toBe(`${PROXY}/my-team/sites`);
+  });
+
+  it.each([401, 403])(
+    'maps a %i — pre-mutation — to NotAuthenticatedError',
+    async (status: number) => {
+      vi.stubGlobal('fetch', async () => ({ ok: false, status, json: async () => ({}) }));
+      await expect(createSiteInAccount(PROXY)).rejects.toBeInstanceOf(NotAuthenticatedError);
+    }
+  );
+
+  it('wraps any other failure in SiteCreateError with the status', async () => {
+    vi.stubGlobal('fetch', async () => ({ ok: false, status: 500, json: async () => ({}) }));
+    const failure = await createSiteInAccount(PROXY).catch(e => e);
+    expect(failure).toBeInstanceOf(SiteCreateError);
+    expect(failure.status).toBe(500);
+  });
+});
+
+describe('pollDeployUntilSettled', () => {
+  const poll = (states: Array<{ ok: boolean; state?: string; error_message?: string }>) => {
+    let call = 0;
+    const urls: string[] = [];
+    vi.stubGlobal('fetch', async (url: unknown, init: RequestInit = {}) => {
+      urls.push(String(url) + `|${init.credentials}`);
+      const next = states[Math.min(call++, states.length - 1)];
+      return { ok: next.ok, status: 200, json: async () => next } as Response;
+    });
+    return {
+      urls,
+      run: () =>
+        pollDeployUntilSettled({
+          proxyBase: PROXY,
+          deployId: 'd',
+          pollIntervalMs: 1,
+          timeoutMs: 5,
+        }),
+    };
+  };
+
+  it('reads the deploy through the proxy on the cookie until ready', async () => {
+    const { run, urls } = poll([
+      { ok: true, state: 'processing' },
+      { ok: true, state: 'ready' },
+    ]);
+    expect(await run()).toEqual({ outcome: 'ready' });
+    expect(urls[0]).toBe(`${PROXY}/deploys/d|include`);
+  });
+
+  it('reports terminal failures with the API error message', async () => {
+    const { run } = poll([{ ok: true, state: 'error', error_message: 'boom' }]);
+    expect(await run()).toEqual({ outcome: 'failed', errorMessage: 'boom' });
+  });
+
+  it('treats rejected as a failure too', async () => {
+    const { run } = poll([{ ok: true, state: 'rejected' }]);
+    expect(await run()).toEqual({ outcome: 'failed', errorMessage: undefined });
+  });
+
+  it('skips transient non-ok reads rather than failing the deploy', async () => {
+    const { run } = poll([{ ok: false }, { ok: true, state: 'ready' }]);
+    expect(await run()).toEqual({ outcome: 'ready' });
+  });
+
+  it('times out after timeoutMs / pollIntervalMs polls', async () => {
+    const { run, urls } = poll([{ ok: true, state: 'building' }]);
+    expect(await run()).toEqual({ outcome: 'timed-out' });
+    expect(urls).toHaveLength(5);
+  });
+});

package/packages/drop-core/authedApi.ts

@@ -0,0 +1,94 @@
+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.)
+ */
+
+/**
+ * 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.
+ */
+export async function createSiteInAccount(
+  proxyBase: string,
+  accountSlug?: string
+): Promise<BuildSite> {
+  const path = accountSlug ? `/${accountSlug}/sites` : '/sites';
+  const res = await fetch(`${proxyBase}${path}`, {
+    method: 'POST',
+    credentials: 'include',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ created_via: 'drop' }),
+  });
+  if (res.status === 401 || res.status === 403) throw new NotAuthenticatedError();
+  if (!res.ok) throw new SiteCreateError(res.status);
+  return res.json();
+}
+
+/** How a watched deploy ended. `errorMessage` is the API's own explanation, when it gave one. */
+export type SettledDeploy =
+  { outcome: 'ready' } | { outcome: 'failed'; errorMessage?: string } | { outcome: 'timed-out' };
+
+/** Deploy states that end the wait — `ready` succeeds, the rest are failures. */
+const TERMINAL_STATES = new Set(['ready', 'error', 'rejected']);
+
+interface DeployState {
+  state?: string;
+  error_message?: string;
+}
+
+/**
+ * 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.
+ */
+export async function pollDeployUntilSettled(options: {
+  proxyBase: string;
+  deployId: string;
+  pollIntervalMs: number;
+  timeoutMs: number;
+}): Promise<SettledDeploy> {
+  const { proxyBase, deployId, pollIntervalMs, timeoutMs } = options;
+  const deadline = timeoutMs / pollIntervalMs;
+  for (let i = 0; i < deadline; i++) {
+    const res = await fetch(`${proxyBase}/deploys/${deployId}`, { credentials: 'include' });
+    if (res.ok) {
+      const deploy: DeployState = await res.json();
+      if (deploy.state && TERMINAL_STATES.has(deploy.state)) {
+        if (deploy.state === 'ready') return { outcome: 'ready' };
+        return { outcome: 'failed', errorMessage: deploy.error_message };
+      }
+    }
+    await new Promise(r => setTimeout(r, pollIntervalMs));
+  }
+  return { outcome: 'timed-out' };
+}

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

@@ -0,0 +1,196 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { AuthenticatedDropClient } from './authedDropClient';
+import { NotAuthenticatedError } from './errors';
+
+const PROXY = '/access-control/bb-api/api/v1';
+const API = 'https://api.netlify.com/api/v1';
+
+interface RecordedCall {
+  url: string;
+  init: RequestInit;
+}
+
+/** Stub fetch that answers like the happy-path API and records every request. */
+function stubApi() {
+  const calls: RecordedCall[] = [];
+  vi.stubGlobal('fetch', async (url: unknown, init: RequestInit = {}) => {
+    calls.push({ url: String(url), init });
+    const u = String(url);
+    const body = u.endsWith('/sites')
+      ? { id: 'site-uuid', name: 'my-account-site' }
+      : u.endsWith('/deploys')
+        ? { id: 'deploy-bson', required: ['aaa'] }
+        : { state: 'ready' };
+    return { ok: true, status: 200, json: async () => body } as Response;
+  });
+  return calls;
+}
+
+const client = (getUploadToken = async (): Promise<string | null> => 'bearer-abc') =>
+  new AuthenticatedDropClient({ getUploadToken, pollIntervalMs: 1, timeoutMs: 5 });
+
+const content = new TextEncoder().encode('x').buffer as ArrayBuffer;
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+});
+
+describe('AuthenticatedDropClient transport', () => {
+  it('splits requests: JSON rides the cookie proxy, uploads go direct with the bearer', async () => {
+    const calls = stubApi();
+    const c = client();
+    const token = await c.getToken();
+    const deploy = await c.createDeploy({ '/index.html': 'aaa' }, token);
+    await c.uploadFile(deploy.deploy_id, '/index.html', content, token);
+    await c.waitUntilReady(deploy, token);
+
+    const [site, deployCreate, upload, poll] = calls;
+    expect(site.url).toBe(`${PROXY}/sites`);
+    expect(deployCreate.url).toBe(`${PROXY}/sites/site-uuid/deploys`);
+    // Readiness and file PUTs key off deploy_id (BSON), never the site UUID.
+    expect(upload.url).toBe(`${API}/deploys/deploy-bson/files/index.html`);
+    expect(poll.url).toBe(`${PROXY}/deploys/deploy-bson`);
+
+    for (const jsonCall of [site, deployCreate, poll]) {
+      expect(jsonCall.init.credentials).toBe('include');
+      expect((jsonCall.init.headers as Record<string, string>)?.Authorization).toBeUndefined();
+    }
+    expect((upload.init.headers as Record<string, string>).Authorization).toBe('Bearer bearer-abc');
+    expect(upload.init.credentials).toBeUndefined();
+  });
+
+  it('creates the site with created_via: drop and the deploy with the digest', async () => {
+    const calls = stubApi();
+    const c = client();
+    await c.createDeploy({ '/index.html': 'aaa' }, await c.getToken());
+    expect(JSON.parse(String(calls[0].init.body))).toEqual({ created_via: 'drop' });
+    expect(JSON.parse(String(calls[1].init.body))).toEqual({
+      files: { '/index.html': 'aaa' },
+      deploy_source: 'drop',
+    });
+  });
+
+  it('scopes site creation to the account slug when given', async () => {
+    const calls = stubApi();
+    const c = new AuthenticatedDropClient({
+      getUploadToken: async () => 'tok',
+      accountSlug: 'my-team',
+    });
+    await c.createDeploy({}, 'tok');
+    expect(calls[0].url).toBe(`${PROXY}/my-team/sites`);
+  });
+
+  it('maps the site + deploy responses into the anonymous DropResponse shape', async () => {
+    stubApi();
+    const c = client();
+    const deploy = await c.createDeploy({ '/index.html': 'aaa' }, 'tok');
+    expect(deploy).toEqual({
+      id: 'site-uuid',
+      deploy_id: 'deploy-bson',
+      subdomain: 'my-account-site',
+      required: ['aaa'],
+    });
+  });
+});
+
+describe('AuthenticatedDropClient upload-token lifecycle', () => {
+  it('reuses the gate-minted token inside the reuse window', async () => {
+    stubApi();
+    let minted = 0;
+    const c = client(async () => `tok-${++minted}`);
+    const token = await c.getToken();
+    await c.uploadFile('d', '/a', content, token);
+    await c.uploadFile('d', '/b', content, token);
+    expect(minted).toBe(1);
+  });
+
+  it('re-mints once the cached token nears the server-side 30s expiry', async () => {
+    stubApi();
+    let minted = 0;
+    let now = 1_000_000;
+    vi.spyOn(Date, 'now').mockImplementation(() => now);
+
+    const c = client(async () => `tok-${++minted}`);
+    const token = await c.getToken();
+    await c.uploadFile('d', '/a', content, token);
+    expect(minted).toBe(1);
+
+    now += 21_000; // past TOKEN_REUSE_MS (20s)
+    await c.uploadFile('d', '/b', content, token);
+    expect(minted).toBe(2);
+
+    await c.uploadFile('d', '/c', content, token);
+    expect(minted).toBe(2); // the renewed token is reused in turn
+  });
+});
+
+describe('AuthenticatedDropClient auth boundaries', () => {
+  it('throws NotAuthenticatedError at the gate when no token can be minted', async () => {
+    await expect(client(async () => null).getToken()).rejects.toBeInstanceOf(NotAuthenticatedError);
+  });
+
+  it('throws NotAuthenticatedError when site creation is refused — pre-mutation, fallback-safe', async () => {
+    vi.stubGlobal('fetch', async () => ({ ok: false, status: 401, json: async () => ({}) }));
+    await expect(client().createDeploy({}, 'tok')).rejects.toBeInstanceOf(NotAuthenticatedError);
+  });
+
+  it('throws a plain Error — never NotAuthenticatedError — when minting fails mid-upload', async () => {
+    // The anti-duplicate invariant: by upload time the site exists, and a
+    // NotAuthenticatedError would send the drop back through the anonymous
+    // path, stranding an empty project and deploying twice.
+    stubApi();
+    let minted = 0;
+    let now = 1_000_000;
+    vi.spyOn(Date, 'now').mockImplementation(() => now);
+    const c = client(async () => (++minted === 1 ? 'tok' : null));
+    const token = await c.getToken();
+    now += 60_000;
+    const failure = await c.uploadFile('d', '/a', content, token).catch(e => e);
+    expect(failure).toBeInstanceOf(Error);
+    expect(failure).not.toBeInstanceOf(NotAuthenticatedError);
+  });
+
+  it('surfaces upload HTTP failures with the status attached', async () => {
+    vi.stubGlobal('fetch', async () => ({ ok: false, status: 413, json: async () => ({}) }));
+    const c = client();
+    const failure = await c.uploadFile('d', '/big', content, 'tok').catch(e => e);
+    expect(failure.status).toBe(413);
+  });
+});
+
+describe('AuthenticatedDropClient polling', () => {
+  const pollClient = (states: Array<{ ok: boolean; state?: string; error_message?: string }>) => {
+    let call = 0;
+    vi.stubGlobal('fetch', async () => {
+      const next = states[Math.min(call++, states.length - 1)];
+      return { ok: next.ok, status: next.ok ? 200 : 500, json: async () => next } as Response;
+    });
+    return client();
+  };
+
+  it('resolves when the deploy goes ready, skipping transient bad reads', async () => {
+    const c = pollClient([
+      { ok: false },
+      { ok: true, state: 'processing' },
+      { ok: true, state: 'ready' },
+    ]);
+    await expect(
+      c.waitUntilReady({ id: 's', deploy_id: 'd', subdomain: 'x', required: [] }, 'tok')
+    ).resolves.toBeUndefined();
+  });
+
+  it('fails with the deploy error message on a terminal error state', async () => {
+    const c = pollClient([{ ok: true, state: 'error', error_message: 'no index.html' }]);
+    await expect(
+      c.waitUntilReady({ id: 's', deploy_id: 'd', subdomain: 'x', required: [] }, 'tok')
+    ).rejects.toThrow('deploy failed: no index.html');
+  });
+
+  it('times out with the shared humanizable message', async () => {
+    const c = pollClient([{ ok: true, state: 'uploading' }]);
+    await expect(
+      c.waitUntilReady({ id: 's', deploy_id: 'd', subdomain: 'x', required: [] }, 'tok')
+    ).rejects.toThrow('Deploy did not become ready in time');
+  });
+});

package/packages/{components/preact/DropZone/drop-core → drop-core}/authedDropClient.ts

@@ -1,7 +1,14 @@
+import {
+  createSiteInAccount,
+  DEFAULT_API_BASE,
+  DEFAULT_POLL_INTERVAL_MS,
+  DEFAULT_PROXY_BASE,
+  DEFAULT_TIMEOUT_MS,
+  pollDeployUntilSettled,
+} from './authedApi';
 import { apiError, type DropClient } from './client';
-import type { BuildSite } from './buildClient';
-import type { Digest, DropResponse } from './types';
-import { NotAuthenticatedError, SiteCreateError } from './errors';
+import { NotAuthenticatedError } from './errors';
+import type { BuildSite, Digest, DropResponse } from './types';
 
 export interface AuthenticatedDropClientConfig {
   /**
@@ -35,15 +42,6 @@ export interface AuthenticatedDropClientConfig {
   timeoutMs?: number;
 }
 
-// Same defaults as AuthenticatedBuildClient — the ~15 lines shared with it
-// (constants + site create) are deliberately duplicated rather than extracted,
-// to avoid churn on the in-review build-client branch. Worth unifying once both
-// have landed.
-const PROXY_BASE = '/access-control/bb-api/api/v1';
-const API_BASE = 'https://api.netlify.com/api/v1';
-const POLL_INTERVAL_MS = 1000;
-const TIMEOUT_MS = 10 * 60 * 1000;
-
 /**
  * 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
@@ -51,14 +49,6 @@ const TIMEOUT_MS = 10 * 60 * 1000;
  */
 const TOKEN_REUSE_MS = 20 * 1000;
 
-/** Deploy states that end the wait — `ready` succeeds, the rest are failures. */
-const TERMINAL_STATES = new Set(['ready', 'error', 'rejected']);
-
-interface DeployState {
-  state?: string;
-  error_message?: string;
-}
-
 /** Response body of `POST /sites/{id}/deploys` — the slice the drop flow needs. */
 interface SiteDeployResponse {
   /** deploy id (BSON) */
@@ -98,12 +88,12 @@ export class AuthenticatedDropClient implements DropClient {
   private cachedToken?: { value: string; mintedAt: number };
 
   constructor({
-    proxyBase = PROXY_BASE,
-    apiBase = API_BASE,
+    proxyBase = DEFAULT_PROXY_BASE,
+    apiBase = DEFAULT_API_BASE,
     getUploadToken,
     accountSlug,
-    pollIntervalMs = POLL_INTERVAL_MS,
-    timeoutMs = TIMEOUT_MS,
+    pollIntervalMs = DEFAULT_POLL_INTERVAL_MS,
+    timeoutMs = DEFAULT_TIMEOUT_MS,
   }: AuthenticatedDropClientConfig) {
     this.proxyBase = proxyBase;
     this.apiBase = apiBase;
@@ -153,18 +143,9 @@ export class AuthenticatedDropClient implements DropClient {
    * `deployFiles` runs unchanged over either client.
    */
   async createDeploy(files: Digest, _token: string): Promise<DropResponse> {
-    const path = this.accountSlug ? `/${this.accountSlug}/sites` : '/sites';
-    const siteRes = await fetch(`${this.proxyBase}${path}`, {
-      method: 'POST',
-      credentials: 'include',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ created_via: 'drop' }),
-    });
-    // A logged-out visitor 401s here, before anything is created — the one
-    // point an anonymous fallback is still safe (see the class doc).
-    if (siteRes.status === 401 || siteRes.status === 403) throw new NotAuthenticatedError();
-    if (!siteRes.ok) throw new SiteCreateError(siteRes.status);
-    const site: BuildSite = await siteRes.json();
+    // 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`, {
       method: 'POST',
@@ -209,21 +190,19 @@ export class AuthenticatedDropClient implements DropClient {
    * than a bearer, so a deploy taking minutes can't outlive its own credentials.
    */
   async waitUntilReady(deploy: DropResponse, _token: string): Promise<void> {
-    const deadline = this.timeoutMs / this.pollIntervalMs;
-    for (let i = 0; i < deadline; i++) {
-      const res = await fetch(`${this.proxyBase}/deploys/${deploy.deploy_id}`, {
-        credentials: 'include',
-      });
-      if (res.ok) {
-        const state: DeployState = await res.json();
-        if (state.state && TERMINAL_STATES.has(state.state)) {
-          if (state.state === 'ready') return;
-          throw new Error(
-            state.error_message ? `deploy failed: ${state.error_message}` : 'deploy failed'
-          );
-        }
-      }
-      await new Promise(r => setTimeout(r, this.pollIntervalMs));
+    const settled = await pollDeployUntilSettled({
+      proxyBase: this.proxyBase,
+      deployId: deploy.deploy_id,
+      pollIntervalMs: this.pollIntervalMs,
+      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');