@capturly/capture-sdk 2.10.2 → 2.11.1

package/CHANGELOG.md

@@ -1 +1,42 @@
 # @capturly/capture-sdk
+
+## 2.11.1
+
+### Patch Changes
+
+- [#464](https://github.com/Corey-Alan-Consulting/capturly.app/pull/464) [`47c00ea`](https://github.com/Corey-Alan-Consulting/capturly.app/commit/47c00ea9b1943850a4427a78004f85cf165adaf8) Thanks [@NX211](https://github.com/NX211)! - Add a `@capturly/capture-sdk/transport` subpath exposing the bare respondent
+  transport (`requestUpload`, `uploadBlob`, `finalizeSubmission`) for hosts that
+  bring their own recorder, and a new `fetchCaptureView` call (both entries)
+  that returns what the person is being asked — title, prompt, branding,
+  release text, limits, and any existing submission — via the new
+  `/api/campaigns/respond/view` endpoint. Existing APIs are unchanged.
+
+- [#464](https://github.com/Corey-Alan-Consulting/capturly.app/pull/464) [`47c00ea`](https://github.com/Corey-Alan-Consulting/capturly.app/commit/47c00ea9b1943850a4427a78004f85cf165adaf8) Thanks [@NX211](https://github.com/NX211)! - Harden the capture-request respond and collect surfaces, and the recording
+  storage lifecycle, per the branch's second review round:
+  - OPFS garbage collection now fails closed: an unreadable or corrupt
+    recovery marker aborts the sweep instead of reading as "nothing
+    referenced" and reclaiming crash-recovery takes.
+  - The mobile respondent flow can always be exited (persistent Close on
+    every non-recording phase), its API calls time out instead of spinning
+    forever, and a storage-full refusal is no longer misreported as
+    "take too large" with retry disabled.
+  - Respondent links are parsed origin-strictly, malformed escapes are
+    refused instead of thrown, and email unsubscribe links stay out of the
+    app on iOS (AASA exclude) while Android completes them natively.
+  - The web respondent page no longer blanks in Safari private mode, the
+    submission-received owner email can no longer be dropped or hang
+    finalize (bounded Mailgun timeout, awaited send), and view decoders
+    refuse a missing recording time limit instead of defaulting to zero.
+  - The desktop Collect screen drops stale detail responses (preventing a
+    personal link rendering under the wrong request), shows mapped error
+    copy instead of raw API codes, and its badge only polls while signed in.
+  - Take Delete / Share controls are reachable by screen readers, clock
+    labels can no longer render ":60", and saved filenames defuse Windows
+    reserved device names.
+
+  GET /api/capture-requests is now cursor-paginated (`cursor`/`limit`,
+  `nextCursor` in the response; default 50, max 100). List rows and detail
+  views group the owning studio as one nullable `studio { id, name }` object
+  in place of the previous studioId/studioName pair.
+
+## 2.11.0

package/README.md

@@ -21,11 +21,16 @@ uses is bundled in.
 
 ## Environment
 
-Browsers only. It needs `MediaRecorder` or WebCodecs, OPFS
-(`navigator.storage`), and `getUserMedia`: roughly Chrome/Edge 111+,
-Firefox 113+, Safari 16.4+. Call `CaptureClient.isSupported()` before you show
-a record button; a browser that fails it cannot be talked into working, so
-offer another browser rather than a retry.
+Browsers only. It needs MP4 `MediaRecorder` or WebCodecs, OPFS
+(`navigator.storage`), and `getUserMedia`: Chrome/Edge 124+ and Safari 16.4+.
+
+**Firefox is not supported.** It has neither MP4 `MediaRecorder` nor
+`MediaStreamTrackProcessor`, so there is no way to write the file — this is a
+missing capability, not a version floor.
+
+Call `CaptureClient.isSupported()` before you show a record button; a browser
+that fails it cannot be talked into working, so offer another browser rather
+than a retry.
 
 `getUserMedia` also requires a secure context, so this will not work on a page
 served over plain HTTP (localhost excepted).
@@ -86,10 +91,13 @@ client.destroy();
 
 **4. Your backend learns it landed**, from the
 `capture_request.submission_received` webhook, or by polling
-`GET /v1/capture-requests/{id}/submissions`. Download the master through
-`GET /v1/recordings/{id}`, where it arrives with its capture manifest: codecs,
-resolution, frame rate, dropped frames, checksum, and the consent that was
-accepted.
+`GET /v1/capture-requests/{id}/submissions`, which carries the consent the
+respondent accepted.
+
+`GET /v1/recordings/{id}` returns the recording's metadata and its files.
+Download a file with
+`GET /v1/recordings/{id}/files/{fileId}/download-url`, which mints a signed
+URL — the API never proxies the bytes.
 
 The recording id is not returned to the browser. Trust your backend for it.
 
@@ -104,16 +112,43 @@ anything produces a record that says something untrue.
 
 ## Errors
 
-Every failure is a `CaptureError` with a `code`. The split that matters is
-between what your user can fix and what only you can:
-
-| Code | Who can act |
-| --- | --- |
-| `unsupported_browser`, `permission_denied`, `no_devices` | your user |
-| `link_expired`, `request_closed`, `quota_exceeded` | you |
-| `network`, `upload_failed` | retryable |
+Every failure is a `CaptureError` with a `code`. What matters is whether
+retrying can work, and who has to act:
+
+| Code | Meaning | Retry? |
+| --- | --- | --- |
+| `unsupported_browser` | No MP4 recording in this browser | No — offer another browser |
+| `permission_denied` | Camera or microphone refused | No — your user must allow it |
+| `no_devices` | No camera or microphone found | No — your user must connect one |
+| `not_recording`, `nothing_to_submit` | Called out of order | No — fix the call sequence |
+| `invalid_request` | The call or its payload was rejected — missing release, missing name, take too long | No — fix the input |
+| `link_expired` | Unknown link, or a key that no longer matches | No |
+| `request_closed` | The capture request is closed, past its deadline, revoked, or the workspace has lapsed | No |
+| `superseded` | Another take for this person landed first | No — their other submission is the live one |
+| `quota_exceeded` | No room right now: take too large, or the request is at its cap | No — the workspace owner must act |
+| `rate_limited` | Too many requests | **Yes**, after a pause |
+| `upload_failed` | Storage or the API failed server-side | **Yes** |
+| `network` | The request never reached Capturly | **Yes** |
+
+Only the last three are worth retrying as-is. Retrying anything above them
+re-uploads the whole take to fail the same way.
+
+### Cancelling
+
+`submit` takes an `AbortSignal`. Aborting rejects with `aborted` and leaves the
+take in local storage, so the same client can submit it again.
+
+```ts
+const controller = new AbortController();
+cancelButton.onclick = () => controller.abort();
+
+await client.submit({ releaseAccepted: true, signal: controller.signal });
+```
 
-A retry for the middle row can never succeed.
+You do not need a timeout of your own. JSON calls give up after 30 seconds, and
+an upload that stops making progress for 60 seconds is abandoned with a
+retryable `network` error — an idle limit rather than a total one, so a long
+take on a slow connection is never cut off mid-upload.
 
 ## What this does not do
 

package/dist/CaptureClient.d.ts

@@ -36,7 +36,13 @@ export declare class CaptureClient {
      * resolves to the same submission.
      */
     submit(options: SubmitOptions): Promise<SubmitResult>;
-    /** Throw the take away without submitting, so someone can record again. */
+    /**
+     * Throw the take away without submitting, so someone can record again.
+     *
+     * Stops the recorder first if one is running: setting the state to idle
+     * while the session kept writing left the client claiming to be idle with a
+     * recording still going into OPFS.
+     */
     discard(): void;
     /**
      * Release the camera, microphone and recorder. Call it on unmount, or the

package/dist/chunk-CZPDQKMD.js

@@ -0,0 +1,278 @@
+var LOOPBACK_HOSTS = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "[::1]", "::1"]);
+function isSecureTransportUrl(value) {
+  if (typeof value !== "string")
+    return false;
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    return false;
+  }
+  if (url.protocol === "https:")
+    return true;
+  if (url.protocol === "http:")
+    return LOOPBACK_HOSTS.has(url.hostname);
+  return false;
+}
+
+// src/types.ts
+var CaptureError = class extends Error {
+  code;
+  cause;
+  constructor(code, message, cause) {
+    super(message);
+    this.name = "CaptureError";
+    this.code = code;
+    if (cause !== void 0) this.cause = cause;
+  }
+};
+
+// src/transport.ts
+function isStringMap(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+  return Object.values(value).every((v) => typeof v === "string");
+}
+var CLOSED_ERROR = "ended";
+var RATE_LIMITED_ERROR = "rate_limited";
+var SUPERSEDED_ERROR = "superseded";
+function accessBody(access) {
+  return access.mode === "contact" ? { mode: "contact", contactId: access.contactId, key: access.key } : { mode: "open", campaignId: access.campaignId, key: access.key };
+}
+function codeForResponse(status, error) {
+  if (error === RATE_LIMITED_ERROR) return "rate_limited";
+  if (error === SUPERSEDED_ERROR || status === 409) return "superseded";
+  if (error === CLOSED_ERROR || status === 410) return "request_closed";
+  if (status === 401 || status === 403 || status === 404) return "link_expired";
+  if (status === 413 || status === 429) return "quota_exceeded";
+  if (status >= 400 && status < 500) return "invalid_request";
+  return "upload_failed";
+}
+var REQUEST_TIMEOUT_MS = 3e4;
+var UPLOAD_STALL_MS = 6e4;
+function linkedAbort(signal, timeoutMs) {
+  const controller = new AbortController();
+  let timedOut = false;
+  const timer = setTimeout(() => {
+    timedOut = true;
+    controller.abort();
+  }, timeoutMs);
+  const onAbort = () => controller.abort();
+  if (signal?.aborted) controller.abort();
+  else signal?.addEventListener("abort", onAbort, { once: true });
+  return {
+    signal: controller.signal,
+    timedOut: () => timedOut,
+    dispose: () => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
+    }
+  };
+}
+async function postJson(baseUrl, path, body, signal) {
+  const link = linkedAbort(signal, REQUEST_TIMEOUT_MS);
+  let res;
+  try {
+    res = await fetch(`${baseUrl}${path}`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+      signal: link.signal
+    });
+  } catch (err) {
+    if (signal?.aborted) throw new CaptureError("aborted", "The request was cancelled.", err);
+    if (link.timedOut()) {
+      throw new CaptureError("network", "Capturly did not respond in time.", err);
+    }
+    throw new CaptureError("network", "Could not reach Capturly.", err);
+  } finally {
+    link.dispose();
+  }
+  const json = await res.json().catch(() => null);
+  if (!res.ok) {
+    const error = typeof json?.error === "string" ? json.error : null;
+    throw new CaptureError(
+      codeForResponse(res.status, error),
+      error ?? `Capturly returned ${res.status}.`
+    );
+  }
+  return json ?? {};
+}
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+var stringOrNull = (v) => typeof v === "string" ? v : null;
+async function fetchCaptureView(args) {
+  const json = await postJson(
+    args.baseUrl,
+    "/api/campaigns/respond/view",
+    accessBody(args.access),
+    args.signal
+  );
+  const view = json.view;
+  if (!isRecord(view) || typeof view.title !== "string" || typeof view.prompt !== "string") {
+    throw new CaptureError("unknown", "Capturly did not return the capture request.");
+  }
+  const branding = isRecord(view.branding) ? {
+    studioName: typeof view.branding.studioName === "string" ? view.branding.studioName : "",
+    brandColor: stringOrNull(view.branding.brandColor),
+    brandSecondaryColor: stringOrNull(view.branding.brandSecondaryColor),
+    brandAccentColor: stringOrNull(view.branding.brandAccentColor),
+    coverPath: stringOrNull(view.branding.coverPath)
+  } : {
+    studioName: "",
+    brandColor: null,
+    brandSecondaryColor: null,
+    brandAccentColor: null,
+    coverPath: null
+  };
+  if (typeof view.maxDurationSec !== "number" || view.maxDurationSec <= 0) {
+    throw new CaptureError("unknown", "Capturly returned no recording time limit.");
+  }
+  const existing = isRecord(view.existing) && typeof view.existing.submissionId === "string" && typeof view.existing.submittedAt === "string" ? {
+    submissionId: view.existing.submissionId,
+    submittedAt: view.existing.submittedAt,
+    durationSec: typeof view.existing.durationSec === "number" ? view.existing.durationSec : 0
+  } : null;
+  return {
+    title: view.title,
+    prompt: view.prompt,
+    deadline: stringOrNull(view.deadline),
+    timezone: typeof view.timezone === "string" ? view.timezone : "UTC",
+    maxDurationSec: view.maxDurationSec,
+    releaseRequired: view.releaseRequired === true,
+    releaseText: typeof view.releaseText === "string" ? view.releaseText : "",
+    respondentName: stringOrNull(view.respondentName),
+    branding,
+    promptVideoUrl: stringOrNull(view.promptVideoUrl),
+    targetHeight: typeof view.targetHeight === "number" ? view.targetHeight : 1080,
+    existing
+  };
+}
+async function requestUpload(args) {
+  const json = await postJson(
+    args.baseUrl,
+    "/api/campaigns/respond/upload-url",
+    {
+      ...accessBody(args.access),
+      contentType: "video/mp4",
+      sizeBytes: args.sizeBytes,
+      durationSec: args.durationSec,
+      ...args.displayName ? { displayName: args.displayName } : {},
+      releaseAccepted: args.releaseAccepted
+    },
+    args.signal
+  );
+  const objectName = typeof json.objectName === "string" ? json.objectName : null;
+  if (!objectName) {
+    throw new CaptureError("upload_failed", "Capturly did not return an upload target.");
+  }
+  const url = json.url;
+  if (!isSecureTransportUrl(url)) {
+    throw new CaptureError("upload_failed", "Capturly returned an unusable upload URL.");
+  }
+  if (json.method !== "PUT") {
+    throw new CaptureError("upload_failed", "Capturly returned an unsupported upload method.");
+  }
+  const headers = json.headers;
+  if (!isStringMap(headers)) {
+    throw new CaptureError("upload_failed", "Capturly returned unusable upload headers.");
+  }
+  return { objectName, url, method: "PUT", headers };
+}
+function uploadBlob(args) {
+  return new Promise((resolve, reject) => {
+    if (args.signal?.aborted) {
+      reject(new CaptureError("aborted", "The upload was cancelled."));
+      return;
+    }
+    const xhr = new XMLHttpRequest();
+    let stalled = false;
+    let cancelled = false;
+    let stallTimer;
+    const onCallerAbort = () => {
+      cancelled = true;
+      xhr.abort();
+    };
+    const armStall = () => {
+      clearTimeout(stallTimer);
+      stallTimer = setTimeout(() => {
+        stalled = true;
+        xhr.abort();
+      }, UPLOAD_STALL_MS);
+    };
+    const cleanup = () => {
+      clearTimeout(stallTimer);
+      args.signal?.removeEventListener("abort", onCallerAbort);
+    };
+    xhr.open(args.target.method, args.target.url, true);
+    for (const [name, value] of Object.entries(args.target.headers)) {
+      xhr.setRequestHeader(name, value);
+    }
+    xhr.upload.onprogress = (event) => {
+      armStall();
+      if (!event.lengthComputable || !args.onProgress) return;
+      args.onProgress(Math.min(1, event.loaded / event.total));
+    };
+    xhr.onload = () => {
+      cleanup();
+      if (xhr.status >= 200 && xhr.status < 300) {
+        args.onProgress?.(1);
+        resolve();
+        return;
+      }
+      reject(new CaptureError("upload_failed", `Storage rejected the upload (${xhr.status}).`));
+    };
+    xhr.onerror = () => {
+      cleanup();
+      reject(new CaptureError("network", "The upload could not reach storage."));
+    };
+    xhr.onabort = () => {
+      cleanup();
+      if (cancelled) {
+        reject(new CaptureError("aborted", "The upload was cancelled."));
+      } else if (stalled) {
+        reject(new CaptureError("network", "The upload stopped making progress."));
+      } else {
+        reject(new CaptureError("upload_failed", "The upload was aborted."));
+      }
+    };
+    args.signal?.addEventListener("abort", onCallerAbort, { once: true });
+    armStall();
+    xhr.send(args.blob);
+  });
+}
+async function finalizeSubmission(args) {
+  const json = await postJson(
+    args.baseUrl,
+    "/api/campaigns/respond/finalize",
+    {
+      ...accessBody(args.access),
+      objectName: args.objectName,
+      durationSec: args.durationSec,
+      ...args.displayName ? { displayName: args.displayName } : {},
+      releaseAccepted: args.releaseAccepted
+    },
+    args.signal
+  );
+  const submissionId = typeof json.submissionId === "string" ? json.submissionId : null;
+  if (!submissionId) {
+    throw new CaptureError(
+      "unknown",
+      "The recording was submitted but Capturly did not return its id."
+    );
+  }
+  return {
+    submissionId,
+    submittedAt: typeof json.submittedAt === "string" ? json.submittedAt : (/* @__PURE__ */ new Date()).toISOString(),
+    replaced: json.replaced === true
+  };
+}
+
+export {
+  isSecureTransportUrl,
+  CaptureError,
+  fetchCaptureView,
+  requestUpload,
+  uploadBlob,
+  finalizeSubmission
+};

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 export { CaptureClient } from './CaptureClient.js';
-export { CaptureError, type CaptureAccess, type CaptureClientOptions, type CaptureDevice, type CaptureErrorCode, type CaptureState, type CaptureTake, type PreviewOptions, type SubmitOptions, type SubmitResult, } from './types.js';
+export { fetchCaptureView } from './transport.js';
+export { CaptureError, type CaptureAccess, type CaptureClientOptions, type CaptureDevice, type CaptureErrorCode, type CaptureRequestBranding, type CaptureRequestView, type CaptureState, type CaptureTake, type PreviewOptions, type SubmitOptions, type SubmitResult, } from './types.js';

package/dist/index.js

@@ -1,3 +1,12 @@
+import {
+  CaptureError,
+  fetchCaptureView,
+  finalizeSubmission,
+  isSecureTransportUrl,
+  requestUpload,
+  uploadBlob
+} from "./chunk-CZPDQKMD.js";
+
 var MP4_MIME = "video/mp4;codecs=avc1.42E01E,mp4a.40.2";
 function pickMuxStrategy() {
   if (typeof MediaRecorder !== "undefined" && MediaRecorder.isTypeSupported(MP4_MIME)) {
@@ -62,23 +71,6 @@ var RecordingEngineError = class _RecordingEngineError extends Error {
   }
 };
 
-var LOOPBACK_HOSTS = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "[::1]", "::1"]);
-function isSecureTransportUrl(value) {
-  if (typeof value !== "string")
-    return false;
-  let url2;
-  try {
-    url2 = new URL(value);
-  } catch {
-    return false;
-  }
-  if (url2.protocol === "https:")
-    return true;
-  if (url2.protocol === "http:")
-    return LOOPBACK_HOSTS.has(url2.hostname);
-  return false;
-}
-
 var CHUNK_ALIGNMENT = 256 * 1024;
 var RESUMABLE_CHUNK_BYTES = 32 * CHUNK_ALIGNMENT;
 var CHUNK_TIMEOUT_MS = 4 * 60 * 1e3;
@@ -151,6 +143,11 @@ var CloudFileSinkHandle = class {
   spilling = false;
   readSource;
   spillRetryTimer = null;
+  // Resolved when the sink reaches a terminal state. close() waits on this
+  // rather than on one worker pass: a pass that arms a retry and returns has
+  // not finished flushing, and treating it as finished is how a truncated
+  // cloud copy gets reported as a healthy one.
+  settleWaiters = [];
   constructor(config) {
     this.path = `cloud:${config.recordingId}/${config.fileId}`;
     this.initUrl = config.initUrl;
@@ -209,6 +206,9 @@ var CloudFileSinkHandle = class {
     this.cancelFlushTimer();
     this.cancelSpillRetry();
     this.kickWorker();
+    const settled = new Promise((resolve) => {
+      this.settleWaiters.push(resolve);
+    });
     const timerHolder = { current: null };
     const timeout = new Promise((resolve) => {
       timerHolder.current = this.scheduler.schedule(() => {
@@ -216,7 +216,7 @@ var CloudFileSinkHandle = class {
         resolve();
       }, CLOSE_TIMEOUT_MS);
     });
-    await Promise.race([this.worker.catch(() => void 0), timeout]);
+    await Promise.race([settled, timeout]);
     timerHolder.current?.cancel();
   }
   async abort() {
@@ -249,11 +249,20 @@ var CloudFileSinkHandle = class {
     if (this.isTerminal())
       return;
     this.state = next;
+    if (this.isTerminal())
+      this.settle();
     try {
       this.callbacks.onState?.(next, info);
     } catch {
     }
   }
+  /** Release anyone waiting on close(); terminal is terminal, so once only. */
+  settle() {
+    const waiters = this.settleWaiters;
+    this.settleWaiters = [];
+    for (const resolve of waiters)
+      resolve();
+  }
   markFailed(reason) {
     if (this.isTerminal())
       return;
@@ -263,6 +272,7 @@ var CloudFileSinkHandle = class {
     this.cancelFlushTimer();
     this.cancelSpillRetry();
     this.inflightAbort?.abort();
+    this.settle();
     try {
       this.callbacks.onState?.("failed", { reason });
     } catch {
@@ -751,6 +761,7 @@ var PADDING = 20;
 var OPACITY = 0.8;
 var FALLBACK_TEXT = "Powered by Capturly";
 var DRAW_WATCHDOG_MS = 1e3;
+var DEGRADED_AFTER_FAILURES = 30;
 function watermarkSupported() {
   return typeof document !== "undefined" && typeof HTMLCanvasElement !== "undefined" && typeof HTMLCanvasElement.prototype.captureStream === "function" && typeof HTMLVideoElement !== "undefined" && "requestVideoFrameCallback" in HTMLVideoElement.prototype;
 }
@@ -765,6 +776,8 @@ var WatermarkCompositor = class {
   watchdog = null;
   lastDrawMs = 0;
   drawFailureLogged = false;
+  consecutiveFailures = 0;
+  degradedReported = false;
   constructor(source, config) {
     this.source = source;
     this.config = config;
@@ -790,25 +803,19 @@ var WatermarkCompositor = class {
     const drawFrame = () => {
       if (this.stopped)
         return;
-      this.draw();
-      this.video.requestVideoFrameCallback(drawFrame);
+      try {
+        this.safeDraw();
+      } finally {
+        this.video.requestVideoFrameCallback(drawFrame);
+      }
     };
-    this.draw();
+    this.safeDraw();
     this.video.requestVideoFrameCallback(drawFrame);
     this.watchdog = setInterval(() => {
       if (this.stopped)
         return;
-      if (Date.now() - this.lastDrawMs >= DRAW_WATCHDOG_MS) {
-        try {
-          this.draw();
-        } catch (err) {
-          if (!this.drawFailureLogged) {
-            this.drawFailureLogged = true;
-            const log = this.config.logError ?? ((component, message, error) => console.error(`${component}: ${message}`, error));
-            log("watermark", "draw failed; watchdog keeps ticking", err);
-          }
-        }
-      }
+      if (Date.now() - this.lastDrawMs >= DRAW_WATCHDOG_MS)
+        this.safeDraw();
     }, DRAW_WATCHDOG_MS);
     const canvasStream = this.canvas.captureStream();
     this.output = new MediaStream([
@@ -817,6 +824,37 @@ var WatermarkCompositor = class {
     ]);
     return this.output;
   }
+  /** True once the mark stopped painting reliably. The take is still recording
+   *  — the canvas keeps emitting frames — so this is the only signal that what
+   *  it captured is not what was asked for. */
+  get degraded() {
+    return this.degradedReported;
+  }
+  /** Every draw goes through here so one throw can never end the loop, and a
+   *  run of them is escalated rather than latched away after the first. */
+  safeDraw() {
+    try {
+      this.draw();
+      this.consecutiveFailures = 0;
+    } catch (err) {
+      this.consecutiveFailures++;
+      if (!this.drawFailureLogged) {
+        this.drawFailureLogged = true;
+        const log = this.config.logError ?? ((component, message, error) => console.error(`${component}: ${message}`, error));
+        log("watermark", "draw failed; loop continues", err);
+      }
+      if (this.consecutiveFailures >= DEGRADED_AFTER_FAILURES && !this.degradedReported) {
+        this.degradedReported = true;
+        const log = this.config.logError ?? ((component, message, error) => console.error(`${component}: ${message}`, error));
+        log("watermark", `mark has not painted for ${String(this.consecutiveFailures)} consecutive frames`, err);
+        try {
+          this.config.onDegraded?.(this.consecutiveFailures);
+        } catch (handlerErr) {
+          log("watermark", "onDegraded handler threw", handlerErr);
+        }
+      }
+    }
+  }
   draw() {
     this.lastDrawMs = Date.now();
     const { canvas, ctx, video } = this;
@@ -3648,11 +3686,10 @@ var TeeFileSinkHandle = class {
     }
   }
   async close() {
-    const primaryClose = this.primary.close();
-    const secondaryClose = this.secondary.close().catch((err) => {
+    await this.secondary.close().catch((err) => {
       this.handleSecondaryError("close", err);
     });
-    await Promise.all([primaryClose, secondaryClose]);
+    await this.primary.close();
   }
   async abort() {
     const primaryAbort = this.primary.abort();
@@ -3756,7 +3793,15 @@ var CaptureSession = class {
           try {
             compositor = new WatermarkCompositor(stream, {
               ...options.watermark,
-              ...this.deps.logError ? { logError: this.deps.logError } : {}
+              ...this.deps.logError ? { logError: this.deps.logError } : {},
+              // The canvas keeps emitting frames whatever the mark does, so
+              // the stall watchdog cannot see this. Surfaced while the take is
+              // still short enough that restarting costs little.
+              onDegraded: (failures) => {
+                this.emit("error", {
+                  message: `Watermark stopped painting after ${String(failures)} failed frames; the recording is continuing without a reliable mark.`
+                });
+              }
             });
             recordStream = await compositor.start();
           } catch (err) {
@@ -3890,8 +3935,10 @@ var CaptureSession = class {
         audioSampleRate: audioSettings?.sampleRate ?? resources.options.audioConstraints?.sampleRate ?? 0,
         surface: this.deps.surface,
         // The compositor, not options.watermark: a requested mark that failed
-        // to start leaves this null, and the manifest must say so.
-        watermarked: resources.compositor !== null,
+        // to start leaves this null, and the manifest must say so. A compositor
+        // that started and then stopped painting is the same claim to avoid —
+        // most of those frames carry no mark.
+        watermarked: resources.compositor !== null && !resources.compositor.degraded,
         ...muxResult.framesDropped !== void 0 ? { framesDropped: muxResult.framesDropped } : {}
       };
       if (muxResult.framesDropped && muxResult.framesDropped > 0) {
@@ -4185,125 +4232,9 @@ function commitResources(r, logError) {
   })();
 }
 
-// src/types.ts
-var CaptureError = class extends Error {
-  code;
-  cause;
-  constructor(code, message, cause) {
-    super(message);
-    this.name = "CaptureError";
-    this.code = code;
-    if (cause !== void 0) this.cause = cause;
-  }
-};
-
-// src/transport.ts
-var TERMINAL_ACCESS_ERRORS = /* @__PURE__ */ new Set([
-  "campaign_closed",
-  "deadline_passed",
-  "link_revoked",
-  "not_found",
-  "forbidden"
-]);
-function accessBody(access) {
-  return access.mode === "contact" ? { mode: "contact", contactId: access.contactId, key: access.key } : { mode: "open", campaignId: access.campaignId, key: access.key };
-}
-function codeForResponse(status, error) {
-  if (status === 413) return "quota_exceeded";
-  if (status === 429) return "quota_exceeded";
-  if (status === 410 || error !== null && TERMINAL_ACCESS_ERRORS.has(error)) {
-    return error === "campaign_closed" ? "request_closed" : "link_expired";
-  }
-  if (status === 401 || status === 403) return "link_expired";
-  return "upload_failed";
-}
-async function postJson(baseUrl, path, body) {
-  let res;
-  try {
-    res = await fetch(`${baseUrl}${path}`, {
-      method: "POST",
-      headers: { "content-type": "application/json" },
-      body: JSON.stringify(body)
-    });
-  } catch (err) {
-    throw new CaptureError("network", "Could not reach Capturly.", err);
-  }
-  const json = await res.json().catch(() => null);
-  if (!res.ok) {
-    const error = typeof json?.error === "string" ? json.error : null;
-    throw new CaptureError(
-      codeForResponse(res.status, error),
-      error ?? `Capturly returned ${res.status}.`
-    );
-  }
-  return json ?? {};
-}
-async function requestUpload(args) {
-  const json = await postJson(args.baseUrl, "/api/campaigns/respond/upload-url", {
-    ...accessBody(args.access),
-    contentType: "video/mp4",
-    sizeBytes: args.sizeBytes
-  });
-  const objectName = typeof json.objectName === "string" ? json.objectName : null;
-  const url2 = typeof json.url === "string" ? json.url : null;
-  if (!objectName || !url2) {
-    throw new CaptureError("upload_failed", "Capturly did not return an upload target.");
-  }
-  return {
-    objectName,
-    url: url2,
-    method: typeof json.method === "string" ? json.method : "PUT",
-    headers: json.headers !== null && typeof json.headers === "object" ? json.headers : {}
-  };
-}
-function uploadBlob(args) {
-  return new Promise((resolve, reject) => {
-    const xhr = new XMLHttpRequest();
-    xhr.open(args.target.method, args.target.url, true);
-    for (const [name, value] of Object.entries(args.target.headers)) {
-      xhr.setRequestHeader(name, value);
-    }
-    xhr.upload.onprogress = (event) => {
-      if (!event.lengthComputable || !args.onProgress) return;
-      args.onProgress(Math.min(1, event.loaded / event.total));
-    };
-    xhr.onload = () => {
-      if (xhr.status >= 200 && xhr.status < 300) {
-        args.onProgress?.(1);
-        resolve();
-        return;
-      }
-      reject(new CaptureError("upload_failed", `Storage rejected the upload (${xhr.status}).`));
-    };
-    xhr.onerror = () => reject(new CaptureError("network", "The upload could not reach storage."));
-    xhr.onabort = () => reject(new CaptureError("upload_failed", "The upload was aborted."));
-    xhr.send(args.blob);
-  });
-}
-async function finalizeSubmission(args) {
-  const json = await postJson(args.baseUrl, "/api/campaigns/respond/finalize", {
-    ...accessBody(args.access),
-    objectName: args.objectName,
-    durationSec: args.durationSec,
-    ...args.displayName ? { displayName: args.displayName } : {},
-    releaseAccepted: args.releaseAccepted
-  });
-  const submissionId = typeof json.submissionId === "string" ? json.submissionId : null;
-  if (!submissionId) {
-    throw new CaptureError(
-      "unknown",
-      "The recording was submitted but Capturly did not return its id."
-    );
-  }
-  return {
-    submissionId,
-    submittedAt: typeof json.submittedAt === "string" ? json.submittedAt : (/* @__PURE__ */ new Date()).toISOString(),
-    replaced: json.replaced === true
-  };
-}
-
 // src/CaptureClient.ts
 var DEFAULT_BASE_URL = "https://capturly.app";
+var SLASH = 47;
 var CaptureClient = class _CaptureClient {
   #options;
   #sink = null;
@@ -4316,7 +4247,16 @@ var CaptureClient = class _CaptureClient {
   #destroyed = false;
   #stateListeners = /* @__PURE__ */ new Set();
   constructor(options) {
-    const baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    const configured = options.baseUrl ?? DEFAULT_BASE_URL;
+    let end = configured.length;
+    while (end > 0 && configured.charCodeAt(end - 1) === SLASH) end--;
+    const baseUrl = configured.slice(0, end);
+    if (!isSecureTransportUrl(baseUrl)) {
+      throw new CaptureError(
+        "invalid_request",
+        `baseUrl must be an https:// URL (got ${baseUrl || "an empty string"}).`
+      );
+    }
     this.#options = {
       access: options.access,
       baseUrl,
@@ -4367,7 +4307,7 @@ var CaptureClient = class _CaptureClient {
     if (!_CaptureClient.isSupported()) {
       throw new CaptureError(
         "unsupported_browser",
-        "This browser cannot record. Chrome, Edge, Firefox or Safari 16.4+ can."
+        "This browser cannot record. Chrome, Edge, or Safari 16.4+ can."
       );
     }
     const constraints = {
@@ -4378,7 +4318,8 @@ var CaptureClient = class _CaptureClient {
     try {
       stream = await navigator.mediaDevices.getUserMedia(constraints);
     } catch (err) {
-      throw new CaptureError(this.#gumCode(err), this.#gumMessage(err), err);
+      const failure = this.#gumFailure(err);
+      throw new CaptureError(failure.code, failure.message, err);
     }
     this.#stopStream();
     this.#stream = stream;
@@ -4392,8 +4333,9 @@ var CaptureClient = class _CaptureClient {
       throw new CaptureError("not_recording", "Call preview() before start().");
     }
     if (this.#session) {
-      throw new CaptureError("not_recording", "Already recording.");
+      throw new CaptureError("invalid_request", "Already recording.");
     }
+    this.#discardPending();
     this.#setState("starting");
     this.#sink ??= new OpfsFileSink({ logError: (m, e) => this.#options.onWarning(m, e) });
     const session = new CaptureSession({
@@ -4433,6 +4375,7 @@ var CaptureClient = class _CaptureClient {
     try {
       artifact = await session.stop();
     } catch (err) {
+      this.#discardPending();
       this.#setState("idle");
       throw new CaptureError("unknown", "Recording could not be finished.", err);
     }
@@ -4461,6 +4404,9 @@ var CaptureClient = class _CaptureClient {
    */
   async submit(options) {
     this.#assertAlive();
+    if (this.#state !== "stopped") {
+      throw new CaptureError("nothing_to_submit", "Stop the recording before submitting.");
+    }
     const pending = this.#pending;
     if (!pending) {
       throw new CaptureError("nothing_to_submit", "Record something before submitting.");
@@ -4478,12 +4424,17 @@ var CaptureClient = class _CaptureClient {
     const target = await requestUpload({
       baseUrl: this.#options.baseUrl,
       access: this.#options.access,
-      sizeBytes: blob.size
+      sizeBytes: blob.size,
+      durationSec: pending.durationSec,
+      displayName: options.displayName,
+      releaseAccepted: options.releaseAccepted,
+      signal: options.signal
     });
     await uploadBlob({
       target,
       blob,
-      ...options.onProgress ? { onProgress: options.onProgress } : {}
+      ...options.onProgress ? { onProgress: options.onProgress } : {},
+      signal: options.signal
     });
     const result = await finalizeSubmission({
       baseUrl: this.#options.baseUrl,
@@ -4491,13 +4442,27 @@ var CaptureClient = class _CaptureClient {
       objectName: target.objectName,
       durationSec: pending.durationSec,
       displayName: options.displayName,
-      releaseAccepted: options.releaseAccepted
+      releaseAccepted: options.releaseAccepted,
+      signal: options.signal
     });
     this.#discardPending();
     return result;
   }
-  /** Throw the take away without submitting, so someone can record again. */
+  /**
+   * Throw the take away without submitting, so someone can record again.
+   *
+   * Stops the recorder first if one is running: setting the state to idle
+   * while the session kept writing left the client claiming to be idle with a
+   * recording still going into OPFS.
+   */
   discard() {
+    const session = this.#session;
+    this.#session = null;
+    if (session) {
+      void session.stop().catch((err) => {
+        this.#options.onWarning("recorder could not be stopped on discard", err);
+      });
+    }
     this.#discardPending();
     this.#setState("idle");
   }
@@ -4528,29 +4493,47 @@ var CaptureClient = class _CaptureClient {
     this.#stream?.getTracks().forEach((t) => t.stop());
     this.#stream = null;
   }
+  /**
+   * Let go of the pending take — the preview URL and the bytes behind it.
+   *
+   * Deleting the file is the part that matters. This SDK records into OPFS
+   * under the EMBEDDING site's origin, one directory per take; revoking the
+   * object URL alone left the video on the visitor's disk forever, with no
+   * surface anywhere for them to clear it. A testimonial widget would
+   * accumulate gigabytes of other people's video in third-party storage.
+   *
+   * Best-effort and fire-and-forget: `discard()` and `destroy()` are
+   * synchronous by contract, and failing to tidy up must never become an
+   * error the integrator has to handle. A failure warns instead — and the
+   * next take still records, because paths are per-take.
+   */
   #discardPending() {
-    if (this.#pending?.previewUrl) URL.revokeObjectURL(this.#pending.previewUrl);
+    const pending = this.#pending;
     this.#pending = null;
+    if (!pending) return;
+    if (pending.previewUrl) URL.revokeObjectURL(pending.previewUrl);
+    const sink = this.#sink;
+    if (!sink) return;
+    void sink.remove(pending.path).catch((err) => {
+      this.#options.onWarning("take could not be removed from local storage", err);
+    });
   }
-  /** getUserMedia DOMException names, mapped to codes. */
-  #gumCode(err) {
+  /** getUserMedia DOMException names, mapped to a code and its copy. Both come
+   *  out of one classification: deriving the message from a second call could
+   *  report a code and a sentence that disagree. */
+  #gumFailure(err) {
     const name = err?.name;
-    if (name === "NotAllowedError" || name === "SecurityError") return "permission_denied";
-    if (name === "NotFoundError" || name === "OverconstrainedError") return "no_devices";
-    return "unknown";
-  }
-  #gumMessage(err) {
-    switch (this.#gumCode(err)) {
-      case "permission_denied":
-        return "Camera and microphone access was denied.";
-      case "no_devices":
-        return "No camera or microphone was available.";
-      default:
-        return "The camera and microphone could not be opened.";
-    }
+    const code = name === "NotAllowedError" || name === "SecurityError" ? "permission_denied" : name === "NotFoundError" || name === "OverconstrainedError" ? "no_devices" : "unknown";
+    return { code, message: GUM_MESSAGES[code] };
   }
 };
+var GUM_MESSAGES = {
+  permission_denied: "Camera and microphone access was denied.",
+  no_devices: "No camera or microphone was available.",
+  unknown: "The camera and microphone could not be opened."
+};
 export {
   CaptureClient,
-  CaptureError
+  CaptureError,
+  fetchCaptureView
 };

package/dist/transport.d.ts

@@ -1,4 +1,18 @@
-import { type CaptureAccess } from './types.js';
+import { CaptureError, type CaptureAccess, type CaptureErrorCode, type CaptureRequestBranding, type CaptureRequestView } from './types.js';
+export { CaptureError };
+export type { CaptureAccess, CaptureErrorCode, CaptureRequestBranding, CaptureRequestView };
+/**
+ * Fetch what the person is being asked — title, prompt, branding, release
+ * text, limits, and any submission they already made. Same access, same
+ * refusal codes as the other calls, so a dead link fails here rather than
+ * after a recording exists. Contact links are marked opened by this call,
+ * exactly as opening the hosted page would.
+ */
+export declare function fetchCaptureView(args: {
+    baseUrl: string;
+    access: CaptureAccess;
+    signal?: AbortSignal | undefined;
+}): Promise<CaptureRequestView>;
 export interface UploadTarget {
     objectName: string;
     url: string;
@@ -7,11 +21,18 @@ export interface UploadTarget {
     headers: Record<string, string>;
 }
 /** Request an upload target. The size is signed in, so it must be the real
- *  byte count of what gets uploaded. */
+ *  byte count of what gets uploaded. Everything finalize will be sent goes
+ *  with it, so the server can finish the submission itself if this browser
+ *  never gets to call finalize — and so a missing release or name fails here
+ *  rather than after the whole take has crossed the wire. */
 export declare function requestUpload(args: {
     baseUrl: string;
     access: CaptureAccess;
     sizeBytes: number;
+    durationSec: number;
+    displayName?: string | undefined;
+    releaseAccepted: boolean;
+    signal?: AbortSignal | undefined;
 }): Promise<UploadTarget>;
 /**
  * Send the bytes. XHR rather than fetch only for `upload.onprogress`; fetch
@@ -21,6 +42,7 @@ export declare function uploadBlob(args: {
     target: UploadTarget;
     blob: Blob;
     onProgress?: (fraction: number) => void;
+    signal?: AbortSignal | undefined;
 }): Promise<void>;
 /**
  * Confirm the upload and record the submission. Idempotent on the object
@@ -33,6 +55,9 @@ export declare function finalizeSubmission(args: {
     durationSec: number;
     displayName?: string | undefined;
     releaseAccepted: boolean;
+    /** Cancelling here is safe but rarely what you want: the bytes have already
+     *  landed, and Capturly finishes an abandoned upload server-side. */
+    signal?: AbortSignal | undefined;
 }): Promise<{
     submissionId: string;
     submittedAt: string;

package/dist/transport.js

@@ -0,0 +1,14 @@
+import {
+  CaptureError,
+  fetchCaptureView,
+  finalizeSubmission,
+  requestUpload,
+  uploadBlob
+} from "./chunk-CZPDQKMD.js";
+export {
+  CaptureError,
+  fetchCaptureView,
+  finalizeSubmission,
+  requestUpload,
+  uploadBlob
+};

package/dist/types.d.ts

@@ -24,6 +24,42 @@ export interface CaptureClientOptions {
     onWarning?: (message: string, cause?: unknown) => void;
 }
 export type CaptureState = 'idle' | 'starting' | 'recording' | 'stopping' | 'stopped';
+export interface CaptureRequestBranding {
+    studioName: string;
+    brandColor: string | null;
+    brandSecondaryColor: string | null;
+    brandAccentColor: string | null;
+    /** Cover-art path under the Capturly origin, or null when unset. */
+    coverPath: string | null;
+}
+/**
+ * What the person is being asked, fetched with the same access the recording
+ * uses. Show `releaseText` before recording whenever `releaseRequired` — a
+ * consent record is only honest if the person actually saw the text.
+ */
+export interface CaptureRequestView {
+    title: string;
+    prompt: string;
+    deadline: string | null;
+    timezone: string;
+    maxDurationSec: number;
+    releaseRequired: boolean;
+    /** Resolved release copy — never empty when `releaseRequired`. */
+    releaseText: string;
+    /** The person's name for a contact link; null for an open link. */
+    respondentName: string | null;
+    branding: CaptureRequestBranding;
+    /** Short-lived signed URL of the video prompt, when the request has one. */
+    promptVideoUrl: string | null;
+    /** Frame-height ceiling the owner's plan records at (e.g. 1080). */
+    targetHeight: number;
+    /** This person's existing submission, when they already answered. */
+    existing: {
+        submissionId: string;
+        submittedAt: string;
+        durationSec: number;
+    } | null;
+}
 export interface CaptureDevice {
     deviceId: string;
     label: string;
@@ -46,11 +82,19 @@ export interface SubmitOptions {
     /** Required for an open link. Ignored for a contact link, which already has
      *  the roster name. */
     displayName?: string;
-    /** Whether the person accepted the request's release text. Read that text
-     *  from the API and show it — this writes a consent record either way. */
+    /** Whether the person accepted the request's release text.
+     *
+     *  Read that text from the API and show it before recording. A consent
+     *  record is written only when the request requires a release AND you pass
+     *  `true`; passing `true` without showing them anything records agreement
+     *  that never happened. If the request requires a release and this is
+     *  `false`, the submission is refused. */
     releaseAccepted: boolean;
     /** 0–1, as the bytes move. */
     onProgress?: (fraction: number) => void;
+    /** Cancel the submission. Aborting rejects with code `aborted`; the take
+     *  stays in local storage, so the same client can submit it again. */
+    signal?: AbortSignal;
 }
 export interface SubmitResult {
     submissionId: string;
@@ -68,7 +112,18 @@ export interface SubmitResult {
  * a retry for those loops forever. `network` and `upload_failed` are worth
  * retrying as-is.
  */
-export type CaptureErrorCode = 'unsupported_browser' | 'permission_denied' | 'no_devices' | 'not_recording' | 'nothing_to_submit' | 'link_expired' | 'request_closed' | 'quota_exceeded' | 'upload_failed' | 'network' | 'unknown';
+export type CaptureErrorCode = 'unsupported_browser' | 'permission_denied' | 'no_devices' | 'not_recording' | 'nothing_to_submit' | 'link_expired' | 'request_closed'
+/** Another take for this person landed first. Terminal: retrying loses the
+ *  same race, and their other submission is the live one. */
+ | 'superseded' | 'quota_exceeded'
+/** Too many requests. The one refusal here that succeeds if you wait. */
+ | 'rate_limited'
+/** Cancelled through the `signal` you passed. The take is untouched. */
+ | 'aborted'
+/** The call was wrong, not the connection — a bad option, or a payload the
+ *  capture request refuses (no release, no name, too long). Retrying the
+ *  same call cannot succeed; fix the input first. */
+ | 'invalid_request' | 'upload_failed' | 'network' | 'unknown';
 export declare class CaptureError extends Error {
     readonly code: CaptureErrorCode;
     readonly cause?: unknown;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capturly/capture-sdk",
-  "version": "2.10.2",
+  "version": "2.11.1",
   "description": "Record full-quality audio and video on your user's own device, from your own product.",
   "keywords": [
     "recording",
@@ -35,6 +35,10 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./transport": {
+      "types": "./dist/transport.d.ts",
+      "default": "./dist/transport.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -46,22 +50,21 @@
   "publishConfig": {
     "access": "public"
   },
+  "dependencies": {},
+  "devDependencies": {
+    "esbuild": "^0.25.0",
+    "typescript": "^5.4.0",
+    "vitest": "^4.1.7",
+    "@capturly/eslint-config": "2.11.1",
+    "@capturly/recording-engine": "2.11.1",
+    "@capturly/tsconfig": "2.11.1"
+  },
   "scripts": {
-    "build": "node build.mjs && tsc -p tsconfig.build.json --emitDeclarationOnly",
+    "build": "pnpm clean && node build.mjs && tsc -p tsconfig.build.json --emitDeclarationOnly",
     "test": "vitest run",
     "test:watch": "vitest",
     "lint": "eslint src --ext .ts",
     "type-check": "tsc --noEmit",
-    "clean": "rm -rf dist",
-    "prepublishOnly": "pnpm clean && pnpm type-check && pnpm test && pnpm build"
-  },
-  "dependencies": {},
-  "devDependencies": {
-    "@capturly/eslint-config": "workspace:*",
-    "@capturly/recording-engine": "workspace:*",
-    "@capturly/tsconfig": "workspace:*",
-    "esbuild": "^0.25.0",
-    "typescript": "^5.4.0",
-    "vitest": "^4.1.7"
+    "clean": "rm -rf dist"
   }
-}
+}