@capturly/capture-sdk 2.10.2

package/CHANGELOG.md

@@ -0,0 +1 @@
+# @capturly/capture-sdk

package/LICENSE

@@ -0,0 +1,23 @@
+Copyright (c) 2025 Corey Alan LLC. All rights reserved.
+
+PROPRIETARY SOFTWARE LICENSE
+
+This software and associated documentation files (the "Software") are
+proprietary and confidential. Unauthorized copying, modification,
+distribution, or use of this Software, via any medium, is strictly
+prohibited without the express written permission of Corey Alan LLC.
+
+The Software is licensed, not sold. This license does not grant you any
+rights to use the Software except as expressly set forth in a separate
+written agreement between you and Corey Alan LLC.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+COREY ALAN LLC BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF
+OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+For licensing inquiries, contact: contact@capturly.app
+

package/README.md

@@ -0,0 +1,144 @@
+# @capturly/capture-sdk
+
+Record full-quality audio and video on your user's own device, from your own
+product. The recording happens locally and uploads afterwards, so a weak
+connection costs your user a slow upload rather than a ruined take. What lands
+in your Capturly library is the original file, not a re-encode of a stream
+that was fighting their WiFi.
+
+This is the browser half of Capturly's capture-request flow. Your backend
+creates the request and mints a per-person link; this package records against
+it.
+
+## Install
+
+```bash
+npm install @capturly/capture-sdk
+```
+
+Public package. Nothing here needs npm scope access; the recording engine it
+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.
+
+`getUserMedia` also requires a secure context, so this will not work on a page
+served over plain HTTP (localhost excepted).
+
+## The shape of an integration
+
+Three things happen on your server and one in the browser.
+
+**1. Your backend creates a capture request** with your secret API key. Never
+put that key in a browser; it carries your whole organization's access.
+
+```js
+const res = await fetch('https://capturly.app/api/v1/capture-requests', {
+  method: 'POST',
+  headers: { authorization: `Bearer ${process.env.CAPTURLY_API_KEY}`, 'content-type': 'application/json' },
+  body: JSON.stringify({ title: 'Customer stories', prompt: 'How did it go?', status: 'active' }),
+});
+const { captureRequest } = await res.json();
+```
+
+**2. Your backend adds the person** and gets their personal link back. Adding a
+contact does not email them. Sending is yours, if you want to send anything at
+all.
+
+```js
+const res = await fetch(
+  `https://capturly.app/api/v1/capture-requests/${captureRequest.id}/contacts`,
+  {
+    method: 'POST',
+    headers: { authorization: `Bearer ${process.env.CAPTURLY_API_KEY}`, 'content-type': 'application/json' },
+    body: JSON.stringify({ contacts: [{ email: 'jane@example.com', name: 'Jane Doe' }] }),
+  },
+);
+const { contacts } = await res.json();
+// contacts[0].url is https://capturly.app/c/<contactId>?k=<key>
+```
+
+**3. Your frontend records** with the id and key from that URL.
+
+```js
+import { CaptureClient } from '@capturly/capture-sdk';
+
+const client = new CaptureClient({
+  access: { mode: 'contact', contactId, key },
+});
+
+const stream = await client.preview();       // shows the permission prompt
+videoEl.srcObject = stream;                  // render it however you like
+
+await client.start();
+// ...
+const take = await client.stop();            // nothing has left the browser yet
+previewEl.src = take.previewUrl;             // let them watch it back
+
+await client.submit({ releaseAccepted: true, onProgress: (p) => setBar(p) });
+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.
+
+The recording id is not returned to the browser. Trust your backend for it.
+
+## Consent
+
+If the capture request requires a release, read its `release.text` from the API
+and show it before recording, then pass `releaseAccepted: true` only if the
+person actually accepted it. That stores a consent record with the text
+verbatim as it was displayed. Editing the request's wording later never rewrites what a
+past respondent appears to have agreed to; passing `true` without showing them
+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 |
+
+A retry for the middle row can never succeed.
+
+## What this does not do
+
+**Multi-participant sessions.** This records one person at a time. Hosting a
+room where several people record at once needs signaling, TURN and a join
+ceremony, and is not part of this package.
+
+**UI.** You get a `MediaStream` and state events; you render the buttons.
+
+**Transcription.** Capturly delivers masters. Transcription is your pipeline's
+job.
+
+## Reference
+
+- `CaptureClient.isSupported()` probes before you show a record button
+- `listDevices()` lists cameras and microphones; labels only populate after the
+  first permission grant
+- `preview(options)` requests devices and returns the `MediaStream` to render
+- `start()` and `stop()` drive recording; `stop()` returns the take
+- `submit(options)` uploads and records the submission
+- `discard()` throws the take away so you can record again
+- `destroy()` releases the camera and microphone; call it on unmount
+- `onStateChange(fn)` reports `idle`, `starting`, `recording`, `stopping`,
+  `stopped`
+
+## Licence
+
+Proprietary. See [LICENSE](./LICENSE).

package/dist/CaptureClient.d.ts

@@ -0,0 +1,47 @@
+import { type CaptureClientOptions, type CaptureDevice, type CaptureState, type CaptureTake, type PreviewOptions, type SubmitOptions, type SubmitResult } from './types.js';
+type Listener<T> = (value: T) => void;
+export declare class CaptureClient {
+    #private;
+    constructor(options: CaptureClientOptions);
+    /** What the recorder is doing right now. */
+    get state(): CaptureState;
+    /** Subscribe to state changes. Returns an unsubscribe function. */
+    onStateChange(listener: Listener<CaptureState>): () => void;
+    /**
+     * Whether this browser can record. Check before showing a record button; a
+     * browser that fails cannot be retried into working, so offer another one.
+     */
+    static isSupported(): boolean;
+    /**
+     * Cameras and microphones. Labels are blank until permission has been
+     * granted once, so call this again after `preview()` to fill a picker.
+     */
+    listDevices(): Promise<CaptureDevice[]>;
+    /**
+     * Request the camera and microphone and return the stream to render.
+     * Separate from `start()` so people can see themselves before recording.
+     */
+    preview(options?: PreviewOptions): Promise<MediaStream>;
+    /** Begin recording the current preview stream. */
+    start(): Promise<void>;
+    /**
+     * Stop and return the take. Nothing has left the browser yet — the file sits
+     * in OPFS until `submit()`, so it can be reviewed or re-recorded first.
+     */
+    stop(): Promise<CaptureTake>;
+    /**
+     * Upload the take and record the submission: request a signed target, PUT
+     * the bytes straight to storage, then confirm. The API never sees the bytes.
+     * Confirming is keyed on the object name, so a retry after a lost response
+     * resolves to the same submission.
+     */
+    submit(options: SubmitOptions): Promise<SubmitResult>;
+    /** Throw the take away without submitting, so someone can record again. */
+    discard(): void;
+    /**
+     * Release the camera, microphone and recorder. Call it on unmount, or the
+     * camera light stays on after the person has navigated away.
+     */
+    destroy(): void;
+}
+export {};

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+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';