@capturly/capture-sdk 2.10.2 → 2.11.0

package/CHANGELOG.md

@@ -1 +1,3 @@
 # @capturly/capture-sdk
+
+## 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/index.js

@@ -151,6 +151,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 +214,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 +224,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 +257,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 +280,7 @@ var CloudFileSinkHandle = class {
     this.cancelFlushTimer();
     this.cancelSpillRetry();
     this.inflightAbort?.abort();
+    this.settle();
     try {
       this.callbacks.onState?.("failed", { reason });
     } catch {
@@ -751,6 +769,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 +784,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 +811,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 +832,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 +3694,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 +3801,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 +3943,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) {
@@ -4198,35 +4253,64 @@ var CaptureError = class extends Error {
 };
 
 // src/transport.ts
-var TERMINAL_ACCESS_ERRORS = /* @__PURE__ */ new Set([
-  "campaign_closed",
-  "deadline_passed",
-  "link_revoked",
-  "not_found",
-  "forbidden"
-]);
+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 (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";
+  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";
 }
-async function postJson(baseUrl, path, body) {
+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)
+      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) {
@@ -4239,35 +4323,72 @@ async function postJson(baseUrl, path, body) {
   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 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;
-  const url2 = typeof json.url === "string" ? json.url : null;
-  if (!objectName || !url2) {
+  if (!objectName) {
     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 : {}
-  };
+  const url2 = json.url;
+  if (!isSecureTransportUrl(url2)) {
+    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: url2, 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();
@@ -4275,19 +4396,38 @@ function uploadBlob(args) {
       }
       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.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
-  });
+  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(
@@ -4304,6 +4444,7 @@ async function finalizeSubmission(args) {
 
 // src/CaptureClient.ts
 var DEFAULT_BASE_URL = "https://capturly.app";
+var SLASH = 47;
 var CaptureClient = class _CaptureClient {
   #options;
   #sink = null;
@@ -4316,7 +4457,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 +4517,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 +4528,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 +4543,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 +4585,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 +4614,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 +4634,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 +4652,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,28 +4703,45 @@ 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

package/dist/transport.d.ts

@@ -7,11 +7,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 +28,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 +41,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/types.d.ts

@@ -46,11 +46,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 +76,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.0",
   "description": "Record full-quality audio and video on your user's own device, from your own product.",
   "keywords": [
     "recording",
@@ -46,22 +46,21 @@
   "publishConfig": {
     "access": "public"
   },
+  "dependencies": {},
+  "devDependencies": {
+    "esbuild": "^0.25.0",
+    "typescript": "^5.4.0",
+    "vitest": "^4.1.7",
+    "@capturly/eslint-config": "2.11.0",
+    "@capturly/tsconfig": "2.11.0",
+    "@capturly/recording-engine": "2.11.0"
+  },
   "scripts": {
     "build": "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"
   }
-}
+}