@maravilla-labs/platform 0.13.0 → 0.15.0

package/dist/{transforms-CbM38kf7.d.ts → transforms-BPrlJoYd.d.ts}

@@ -32,6 +32,15 @@ interface TranscodeOpts {
     max_height?: number;
     audio_codec?: string;
     bitrate_kbps?: number;
+    /**
+     * Force a constant output frame rate (fps). Pass this for variable-frame-rate
+     * sources (e.g. MediaRecorder WebM) so the MP4 stays frame-accurately
+     * seekable for the frames pipeline — without it, a near-static VFR segment
+     * can collapse to a handful of frames that a fixed-rate renderer stalls on.
+     * When omitted, the worker auto-applies CFR only if it probes the source as
+     * VFR; a determinate-rate source is left untouched.
+     */
+    fps?: number;
 }
 /** Options for `transforms.thumbnail` — extract a single video frame. */
 interface ThumbnailOpts {
@@ -62,6 +71,43 @@ interface ExtractFramesOpts {
     seek_ms?: number;
     /** How much of the clip to extract from `seek_ms`, ms (default: to end). */
     duration_ms?: number;
+    /**
+     * Also extract the source's audio track to `detach_audio.target` in the SAME
+     * job — one call yields both the frame set and a detachable audio asset
+     * (folds the upload-time "detach audio" step into frame extraction). The
+     * frame-set manifest is still the job's primary output; the audio is written
+     * to the caller-chosen `target` key.
+     */
+    detach_audio?: DetachAudioOpts;
+}
+/**
+ * Bundle a detached-audio side-output into an {@link ExtractFramesOpts} job.
+ * The worker runs one extra audio-extraction pass on the same source and writes
+ * the AAC/m4a result to `target` (a caller-chosen, tenant-scoped storage key).
+ */
+interface DetachAudioOpts {
+    /** Storage key to write the extracted audio (AAC/m4a) to. */
+    target: string;
+    /** Output bitrate, kbps. Server picks a sensible AAC bitrate when omitted. */
+    bitrate_kbps?: number;
+    /** Start offset into the source, ms (default 0). */
+    seek_ms?: number;
+    /** How much of the source to extract from `seek_ms`, ms (default: to end). */
+    duration_ms?: number;
+}
+/**
+ * Options for `transforms.extractAudio` — split a video's audio track off into
+ * a standalone AAC/m4a asset. Used to detach the mic/system audio recorded
+ * alongside a camera/screen clip so it can be placed + ducked independently on
+ * the frames timeline.
+ */
+interface ExtractAudioOpts {
+    /** Output bitrate, kbps. Server picks a sensible AAC bitrate when omitted. */
+    bitrate_kbps?: number;
+    /** Start offset into the source, ms (default 0). */
+    seek_ms?: number;
+    /** How much of the source to extract from `seek_ms`, ms (default: to end). */
+    duration_ms?: number;
 }
 /**
  * Result of an `extractFrames` job: a JSON manifest stored at the job's
@@ -87,12 +133,80 @@ interface ResizeOpts {
     format: ImageFormat;
     quality?: number;
     strip_metadata?: boolean;
+    /**
+     * Crop strategy when BOTH `width` and `height` are given (the output is
+     * cropped to fill the exact box rather than letterboxed):
+     * - `'center'` — crop around the geometric center.
+     * - `'focal'` — crop around the source's focal point. The server injects
+     *   the focal point from the persisted {@link FocalPointRecord} (set via
+     *   `detectFaces` or `setFocalPoint`); if none exists it falls back to
+     *   center.
+     * Omit for the default aspect-preserving fit (no crop).
+     */
+    crop?: 'focal' | 'center';
+    /**
+     * Explicit focal point for `crop: 'focal'`, normalized `0..=1`. Server-
+     * injected — callers normally omit this and let the platform resolve the
+     * stored focal point for `src_key`. Present here so the wire type mirrors
+     * the Rust `ResizeOpts` exactly.
+     */
+    focal?: FocalPoint;
 }
 /** Options for `transforms.ocr`. */
 interface OcrOpts {
     /** Tesseract language code(s). Defaults to `"eng"` server-side when omitted. */
     lang?: string;
 }
+/**
+ * Options for `transforms.detectFaces` — run face detection over an image and
+ * persist the resulting focal point (the center of the highest-scoring face,
+ * or the centroid of all faces) as a {@link FocalPointRecord} keyed on the
+ * source. The derived output is a JSON artifact listing the detected boxes.
+ */
+interface DetectFacesOpts {
+    /** Minimum detector confidence to keep a face, `0..=1`. Defaults to `0.6` server-side. */
+    min_score?: number;
+    /** Cap on the number of faces retained (highest-scoring first). Defaults to `32` server-side. */
+    max_faces?: number;
+    /** Trade accuracy for latency (smaller detector input). Defaults to `false` server-side. */
+    fast?: boolean;
+}
+/** A focal point in normalized image coordinates, each component `0..=1`. */
+interface FocalPoint {
+    x: number;
+    y: number;
+}
+/** A single detected face box, normalized to `0..1` of the image dimensions. */
+interface FaceBox {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    /** Detector confidence, `0..1`. */
+    score: number;
+}
+/**
+ * Persisted focal-point record for a source image — the result of
+ * `detectFaces` or a manual `setFocalPoint`. Returned by `getFocalPoint`.
+ */
+interface FocalPointRecord {
+    /** Storage key of the source image this focal point belongs to. */
+    src_key: string;
+    /** The resolved focal point, normalized `0..=1`. */
+    focal: FocalPoint;
+    /** Whether the point came from face detection or a manual override. */
+    source: 'faces' | 'manual';
+    /** Number of faces detected (`null` until a detection has run for this key). */
+    face_count: number | null;
+    /** The detected face boxes, when `source === 'faces'`. */
+    faces?: FaceBox[];
+    /** Content hash of the source bytes the detection ran against. */
+    src_hash?: string;
+    /** Version tag of the detector that produced this record. */
+    detector_version?: string;
+    /** Unix-epoch milliseconds the record was last written. */
+    updated_at: number;
+}
 /**
  * LibreOffice-supported output container for `doc_convert`. Each value
  * maps to a `--convert-to` filter and a derived-key extension.
@@ -213,8 +327,12 @@ type TransformSpec = ({
 } & ThumbnailOpts) | ({
     kind: 'extract_frames';
 } & ExtractFramesOpts) | ({
+    kind: 'extract_audio';
+} & ExtractAudioOpts) | ({
     kind: 'resize';
 } & ResizeOpts) | ({
+    kind: 'detect_faces';
+} & DetectFacesOpts) | ({
     kind: 'ocr';
 } & OcrOpts) | ({
     kind: 'doc_to_pdf';
@@ -264,9 +382,38 @@ interface TransformsService {
      * complete; frames live under `${manifest.prefix}/frame_NNNNNN.<ext>`.
      */
     extractFrames(srcKey: string, opts: ExtractFramesOpts): Promise<JobHandle>;
+    /**
+     * Extract a video's audio track to a standalone AAC/m4a asset. Resolves to a
+     * `JobHandle` whose `output_key` holds the audio file once complete.
+     */
+    extractAudio(srcKey: string, opts?: ExtractAudioOpts | null): Promise<JobHandle>;
     resize(srcKey: string, opts: ResizeOpts): Promise<JobHandle>;
     probe(srcKey: string): Promise<MediaInfo>;
     ocr(srcKey: string, opts?: OcrOpts | null): Promise<JobHandle>;
+    /**
+     * Run face detection over an image and persist the resulting focal point as
+     * a {@link FocalPointRecord}. Resolves to a `JobHandle` whose `output_key`
+     * holds a JSON artifact of the detected {@link FaceBox | boxes} once
+     * complete. Subsequent `resize` calls with `crop: 'focal'` on the same
+     * source pick up the stored focal point automatically.
+     */
+    detectFaces(srcKey: string, opts?: DetectFacesOpts | null): Promise<JobHandle>;
+    /**
+     * Manually set (or override) the focal point for a source image, normalized
+     * `0..=1`. Persists a {@link FocalPointRecord} with `source: 'manual'`.
+     * Resolves to `null`.
+     */
+    setFocalPoint(srcKey: string, point: FocalPoint): Promise<null>;
+    /**
+     * Read the persisted {@link FocalPointRecord} for a source, or `null` when
+     * none has been set (neither `detectFaces` nor `setFocalPoint` has run).
+     */
+    getFocalPoint(srcKey: string): Promise<FocalPointRecord | null>;
+    /**
+     * Remove the persisted focal point for a source. Resolves to `true` when a
+     * record was deleted, `false` when there was nothing to clear.
+     */
+    clearFocalPoint(srcKey: string): Promise<boolean>;
     /** Convert a LibreOffice-supported document to PDF. */
     docToPdf(srcKey: string, opts?: DocToPdfOpts | null): Promise<JobHandle>;
     /** Render a single page of a document as a raster thumbnail. */
@@ -314,6 +461,16 @@ interface TransformsPatternSpec {
     /** Sugar for `resize` arrays — same shape, same semantics. */
     variants?: ResizeOpts[];
     ocr?: OcrOpts | OcrOpts[];
+    /**
+     * Run face detection on matching uploads and persist a focal point so
+     * `resize`/`variants` entries with `crop: 'focal'` crop around faces. Pass
+     * `true` for detector defaults, or an object to tune the detection.
+     */
+    detectFaces?: boolean | {
+        min_score?: number;
+        max_faces?: number;
+        fast?: boolean;
+    };
 }
 /**
  * Top-level `transforms` block. Keys are glob path patterns matched against
@@ -343,4 +500,4 @@ interface TransformsPatternSpec {
  */
 type TransformsConfig = Record<string, TransformsPatternSpec>;
 
-export { type DocFormat as D, type ExtractFramesOpts as E, type FramesetManifest as F, type ImageFormat as I, type JobStatus as J, type MediaInfo as M, type OcrOpts as O, type QrCodeSpec as Q, type ResizeOpts as R, type TransformsConfig as T, type VideoFormat as V, type TransformsPatternSpec as a, type TranscodeOpts as b, type ThumbnailOpts as c, type DocToPdfOpts as d, type DocThumbnailOpts as e, type DocConvertOpts as f, type DocToMarkdownOpts as g, type DocToHtmlOpts as h, type ImageRef as i, type DocReplaceImagesOpts as j, type DocInsertQrCodeOpts as k, type QrPayload as l, type DocTemplateMergeOpts as m, type TransformSpec as n, type JobHandle as o, type JobStatusResponse as p, type TransformsService as q, keyFor as r, transforms as t };
+export { type DetachAudioOpts as D, type ExtractFramesOpts as E, type FramesetManifest as F, type ImageFormat as I, type JobStatus as J, type MediaInfo as M, type OcrOpts as O, type QrCodeSpec as Q, type ResizeOpts as R, type TransformsConfig as T, type VideoFormat as V, type TransformsPatternSpec as a, type TranscodeOpts as b, type ThumbnailOpts as c, type ExtractAudioOpts as d, type DetectFacesOpts as e, type FocalPoint as f, type FaceBox as g, type FocalPointRecord as h, type DocFormat as i, type DocToPdfOpts as j, type DocThumbnailOpts as k, type DocConvertOpts as l, type DocToMarkdownOpts as m, type DocToHtmlOpts as n, type ImageRef as o, type DocReplaceImagesOpts as p, type DocInsertQrCodeOpts as q, type QrPayload as r, type DocTemplateMergeOpts as s, type TransformSpec as t, type JobHandle as u, type JobStatusResponse as v, type TransformsService as w, keyFor as x, transforms as y };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maravilla-labs/platform",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "Universal platform client for Maravilla runtime",
   "type": "module",
   "main": "./dist/index.js",

package/src/config.ts

@@ -393,6 +393,46 @@ export interface SessionConfigDefinition {
 export interface SecurityConfig {
   password_policy?: PasswordPolicyDefinition;
   session?: SessionConfigDefinition;
+  signup?: SignupProtectionConfig;
+}
+
+/**
+ * Bot protection for the registration endpoints, applied to both the hosted
+ * `/_auth/register` form and the `POST /api/platform/auth/register` JSON API.
+ *
+ * These layers are not equally strong:
+ *
+ * - `honeypot` (and its submit-timing check) stops untargeted form spam — bots
+ *   that scrape the HTML and fill every field. Anyone who looks at the page
+ *   defeats it. It is free, so it is on by default, but it is a filter, not a
+ *   gate.
+ * - `rate_limit` bounds how fast anyone can register. On by default.
+ * - `challenge` is the only layer that imposes a real per-attempt cost. `"pow"`
+ *   makes the client burn CPU; `"turnstile"` / `"hcaptcha"` outsource the
+ *   judgement to a third party. Off by default.
+ *
+ * A server-to-server caller cannot solve a browser challenge, so it presents
+ * `signup_secret` in the `x-maravilla-signup-secret` header instead. Without
+ * that header the JSON endpoint enforces exactly the same challenge as the
+ * form — otherwise a bot would simply POST the JSON endpoint to escape.
+ */
+export interface SignupProtectionConfig {
+  /** Default `"none"`. */
+  challenge?: 'none' | 'pow' | 'turnstile' | 'hcaptcha';
+  /** Leading zero bits a proof-of-work solution must have. Default 18. */
+  pow_difficulty?: number;
+  /** Default `true`. */
+  honeypot?: boolean;
+  /** Default `true`. */
+  rate_limit?: boolean;
+  /** Prefer `{ env: "VAR_NAME" }` or `"${env.VAR_NAME}"`. */
+  signup_secret?: SecretRef;
+  /** Required when `challenge` is `"turnstile"`. */
+  turnstile_secret?: SecretRef;
+  /** Required when `challenge` is `"hcaptcha"`. */
+  hcaptcha_secret?: SecretRef;
+  /** Public widget key, rendered into the page. Not a secret. */
+  captcha_site_key?: string;
 }
 
 // ── Branding ──

package/src/remote-client.ts

@@ -1,5 +1,5 @@
 import type { KvNamespace, KvListResult, Database, DbDocument, DbFindOptions, Storage, RealtimeService, PresenceService, AuthService, AuthCaller, AuthUser, AuthSession, AuthField, RegisterOptions, LoginOptions, CreateManagedUserOptions, UserListFilter, UserListResponse, UpdateUserOptions, Relation, AddRelationOptions, ListRelationsOptions, PolicyExplain, CanCheck, ConnectedClient, ApiKeyInfo, LoginSession, PolicyService, VectorIndexSpec, VectorIndexDescriptor, VectorQueryWithFilter, VectorSearchHit, IndexSpec, IndexDescriptor, Workflows, WorkflowHandle, WorkflowRun, WorkflowStepRecord, BrowserClient, FramesClient, BrowserJobHandle, ScreenshotRequest, PdfRequest, FramesRenderRequest } from './types.js';
-import type { TransformsService, TranscodeOpts, ThumbnailOpts, ResizeOpts, OcrOpts, DocToPdfOpts, DocThumbnailOpts, DocConvertOpts, DocToMarkdownOpts, DocToHtmlOpts, DocReplaceImagesOpts, DocInsertQrCodeOpts, DocTemplateMergeOpts, JobHandle, JobStatusResponse, MediaInfo } from './transforms.js';
+import type { TransformsService, TranscodeOpts, ExtractFramesOpts, ExtractAudioOpts, ThumbnailOpts, ResizeOpts, OcrOpts, DetectFacesOpts, FocalPoint, FocalPointRecord, DocToPdfOpts, DocThumbnailOpts, DocConvertOpts, DocToMarkdownOpts, DocToHtmlOpts, DocReplaceImagesOpts, DocInsertQrCodeOpts, DocTemplateMergeOpts, JobHandle, JobStatusResponse, MediaInfo } from './transforms.js';
 import { RemoteMediaService } from './media.js';
 import { getRequestAuthHeader } from './request-scope.js';
 
@@ -133,20 +133,32 @@ class RemoteDatabase implements Database {
     return result.id;
   }
 
-  async updateOne(collection: string, filter: any, update: any): Promise<{ modified: number }> {
+  async updateOne(
+    collection: string,
+    filter: any,
+    update: any,
+  ): Promise<{ modified: number; matched: number; matchedCount: number; modifiedCount: number }> {
     const response = await this.fetch(`${this.baseUrl}/api/db/${collection}/update`, {
       method: 'POST',
       body: JSON.stringify({ filter, update }),
     });
-    return response.json() as Promise<{ modified: number }>;
-  }
-
-  async deleteOne(collection: string, filter: any): Promise<{ deleted: number }> {
+    return response.json() as Promise<{
+      modified: number;
+      matched: number;
+      matchedCount: number;
+      modifiedCount: number;
+    }>;
+  }
+
+  async deleteOne(
+    collection: string,
+    filter: any,
+  ): Promise<{ deleted: number; deletedCount: number }> {
     const response = await this.fetch(`${this.baseUrl}/api/db/${collection}/delete`, {
       method: 'DELETE',
       body: JSON.stringify(filter),
     });
-    return response.json() as Promise<{ deleted: number }>;
+    return response.json() as Promise<{ deleted: number; deletedCount: number }>;
   }
 
   async deleteMany(collection: string, filter: any): Promise<{ deleted: number }> {
@@ -1280,6 +1292,14 @@ class RemoteTransformsService implements TransformsService {
     return this.post<JobHandle>('/transcode', { srcKey, opts });
   }
 
+  extractFrames(srcKey: string, opts: ExtractFramesOpts): Promise<JobHandle> {
+    return this.post<JobHandle>('/extract_frames', { srcKey, opts });
+  }
+
+  extractAudio(srcKey: string, opts?: ExtractAudioOpts | null): Promise<JobHandle> {
+    return this.post<JobHandle>('/extract_audio', { srcKey, opts: opts ?? {} });
+  }
+
   thumbnail(srcKey: string, opts: ThumbnailOpts): Promise<JobHandle> {
     return this.post<JobHandle>('/thumbnail', { srcKey, opts });
   }
@@ -1292,6 +1312,49 @@ class RemoteTransformsService implements TransformsService {
     return this.post<JobHandle>('/ocr', { srcKey, opts: opts ?? {} });
   }
 
+  detectFaces(srcKey: string, opts?: DetectFacesOpts | null): Promise<JobHandle> {
+    return this.post<JobHandle>('/detect-faces', { srcKey, opts: opts ?? {} });
+  }
+
+  async setFocalPoint(srcKey: string, point: FocalPoint): Promise<null> {
+    const res = await fetch(`${this.baseUrl}/api/media/transforms/focal-point`, {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json', ...this.headers, ...getRequestAuthHeader() },
+      body: JSON.stringify({ srcKey, x: point.x, y: point.y }),
+    });
+    if (!res.ok) {
+      const text = await res.text();
+      throw new Error(`Focal-point set error (${res.status}): ${text}`);
+    }
+    return null;
+  }
+
+  async getFocalPoint(srcKey: string): Promise<FocalPointRecord | null> {
+    const res = await fetch(
+      `${this.baseUrl}/api/media/transforms/focal-point?srcKey=${encodeURIComponent(srcKey)}`,
+      { method: 'GET', headers: { ...this.headers, ...getRequestAuthHeader() } },
+    );
+    if (res.status === 404) return null;
+    if (!res.ok) {
+      const text = await res.text();
+      throw new Error(`Focal-point lookup error (${res.status}): ${text}`);
+    }
+    return res.json() as Promise<FocalPointRecord>;
+  }
+
+  async clearFocalPoint(srcKey: string): Promise<boolean> {
+    const res = await fetch(
+      `${this.baseUrl}/api/media/transforms/focal-point?srcKey=${encodeURIComponent(srcKey)}`,
+      { method: 'DELETE', headers: { ...this.headers, ...getRequestAuthHeader() } },
+    );
+    if (!res.ok) {
+      const text = await res.text();
+      throw new Error(`Focal-point clear error (${res.status}): ${text}`);
+    }
+    const data = (await res.json()) as { cleared: boolean };
+    return data.cleared;
+  }
+
   docToPdf(srcKey: string, opts?: DocToPdfOpts | null): Promise<JobHandle> {
     return this.post<JobHandle>('/doc_to_pdf', { srcKey, opts: opts ?? {} });
   }

package/src/transforms.ts

@@ -80,6 +80,15 @@ export interface TranscodeOpts {
   max_height?: number;
   audio_codec?: string;
   bitrate_kbps?: number;
+  /**
+   * Force a constant output frame rate (fps). Pass this for variable-frame-rate
+   * sources (e.g. MediaRecorder WebM) so the MP4 stays frame-accurately
+   * seekable for the frames pipeline — without it, a near-static VFR segment
+   * can collapse to a handful of frames that a fixed-rate renderer stalls on.
+   * When omitted, the worker auto-applies CFR only if it probes the source as
+   * VFR; a determinate-rate source is left untouched.
+   */
+  fps?: number;
 }
 
 /** Options for `transforms.thumbnail` — extract a single video frame. */
@@ -112,6 +121,45 @@ export interface ExtractFramesOpts {
   seek_ms?: number;
   /** How much of the clip to extract from `seek_ms`, ms (default: to end). */
   duration_ms?: number;
+  /**
+   * Also extract the source's audio track to `detach_audio.target` in the SAME
+   * job — one call yields both the frame set and a detachable audio asset
+   * (folds the upload-time "detach audio" step into frame extraction). The
+   * frame-set manifest is still the job's primary output; the audio is written
+   * to the caller-chosen `target` key.
+   */
+  detach_audio?: DetachAudioOpts;
+}
+
+/**
+ * Bundle a detached-audio side-output into an {@link ExtractFramesOpts} job.
+ * The worker runs one extra audio-extraction pass on the same source and writes
+ * the AAC/m4a result to `target` (a caller-chosen, tenant-scoped storage key).
+ */
+export interface DetachAudioOpts {
+  /** Storage key to write the extracted audio (AAC/m4a) to. */
+  target: string;
+  /** Output bitrate, kbps. Server picks a sensible AAC bitrate when omitted. */
+  bitrate_kbps?: number;
+  /** Start offset into the source, ms (default 0). */
+  seek_ms?: number;
+  /** How much of the source to extract from `seek_ms`, ms (default: to end). */
+  duration_ms?: number;
+}
+
+/**
+ * Options for `transforms.extractAudio` — split a video's audio track off into
+ * a standalone AAC/m4a asset. Used to detach the mic/system audio recorded
+ * alongside a camera/screen clip so it can be placed + ducked independently on
+ * the frames timeline.
+ */
+export interface ExtractAudioOpts {
+  /** Output bitrate, kbps. Server picks a sensible AAC bitrate when omitted. */
+  bitrate_kbps?: number;
+  /** Start offset into the source, ms (default 0). */
+  seek_ms?: number;
+  /** How much of the source to extract from `seek_ms`, ms (default: to end). */
+  duration_ms?: number;
 }
 
 /**
@@ -139,6 +187,24 @@ export interface ResizeOpts {
   format: ImageFormat;
   quality?: number;
   strip_metadata?: boolean;
+  /**
+   * Crop strategy when BOTH `width` and `height` are given (the output is
+   * cropped to fill the exact box rather than letterboxed):
+   * - `'center'` — crop around the geometric center.
+   * - `'focal'` — crop around the source's focal point. The server injects
+   *   the focal point from the persisted {@link FocalPointRecord} (set via
+   *   `detectFaces` or `setFocalPoint`); if none exists it falls back to
+   *   center.
+   * Omit for the default aspect-preserving fit (no crop).
+   */
+  crop?: 'focal' | 'center';
+  /**
+   * Explicit focal point for `crop: 'focal'`, normalized `0..=1`. Server-
+   * injected — callers normally omit this and let the platform resolve the
+   * stored focal point for `src_key`. Present here so the wire type mirrors
+   * the Rust `ResizeOpts` exactly.
+   */
+  focal?: FocalPoint;
 }
 
 /** Options for `transforms.ocr`. */
@@ -147,6 +213,60 @@ export interface OcrOpts {
   lang?: string;
 }
 
+/**
+ * Options for `transforms.detectFaces` — run face detection over an image and
+ * persist the resulting focal point (the center of the highest-scoring face,
+ * or the centroid of all faces) as a {@link FocalPointRecord} keyed on the
+ * source. The derived output is a JSON artifact listing the detected boxes.
+ */
+export interface DetectFacesOpts {
+  /** Minimum detector confidence to keep a face, `0..=1`. Defaults to `0.6` server-side. */
+  min_score?: number;
+  /** Cap on the number of faces retained (highest-scoring first). Defaults to `32` server-side. */
+  max_faces?: number;
+  /** Trade accuracy for latency (smaller detector input). Defaults to `false` server-side. */
+  fast?: boolean;
+}
+
+/** A focal point in normalized image coordinates, each component `0..=1`. */
+export interface FocalPoint {
+  x: number;
+  y: number;
+}
+
+/** A single detected face box, normalized to `0..1` of the image dimensions. */
+export interface FaceBox {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+  /** Detector confidence, `0..1`. */
+  score: number;
+}
+
+/**
+ * Persisted focal-point record for a source image — the result of
+ * `detectFaces` or a manual `setFocalPoint`. Returned by `getFocalPoint`.
+ */
+export interface FocalPointRecord {
+  /** Storage key of the source image this focal point belongs to. */
+  src_key: string;
+  /** The resolved focal point, normalized `0..=1`. */
+  focal: FocalPoint;
+  /** Whether the point came from face detection or a manual override. */
+  source: 'faces' | 'manual';
+  /** Number of faces detected (`null` until a detection has run for this key). */
+  face_count: number | null;
+  /** The detected face boxes, when `source === 'faces'`. */
+  faces?: FaceBox[];
+  /** Content hash of the source bytes the detection ran against. */
+  src_hash?: string;
+  /** Version tag of the detector that produced this record. */
+  detector_version?: string;
+  /** Unix-epoch milliseconds the record was last written. */
+  updated_at: number;
+}
+
 /**
  * LibreOffice-supported output container for `doc_convert`. Each value
  * maps to a `--convert-to` filter and a derived-key extension.
@@ -276,7 +396,9 @@ export type TransformSpec =
   | ({ kind: 'transcode' } & TranscodeOpts)
   | ({ kind: 'thumbnail' } & ThumbnailOpts)
   | ({ kind: 'extract_frames' } & ExtractFramesOpts)
+  | ({ kind: 'extract_audio' } & ExtractAudioOpts)
   | ({ kind: 'resize' } & ResizeOpts)
+  | ({ kind: 'detect_faces' } & DetectFacesOpts)
   | ({ kind: 'ocr' } & OcrOpts)
   | ({ kind: 'doc_to_pdf' } & DocToPdfOpts)
   | ({ kind: 'doc_thumbnail' } & DocThumbnailOpts)
@@ -323,9 +445,38 @@ export interface TransformsService {
    * complete; frames live under `${manifest.prefix}/frame_NNNNNN.<ext>`.
    */
   extractFrames(srcKey: string, opts: ExtractFramesOpts): Promise<JobHandle>;
+  /**
+   * Extract a video's audio track to a standalone AAC/m4a asset. Resolves to a
+   * `JobHandle` whose `output_key` holds the audio file once complete.
+   */
+  extractAudio(srcKey: string, opts?: ExtractAudioOpts | null): Promise<JobHandle>;
   resize(srcKey: string, opts: ResizeOpts): Promise<JobHandle>;
   probe(srcKey: string): Promise<MediaInfo>;
   ocr(srcKey: string, opts?: OcrOpts | null): Promise<JobHandle>;
+  /**
+   * Run face detection over an image and persist the resulting focal point as
+   * a {@link FocalPointRecord}. Resolves to a `JobHandle` whose `output_key`
+   * holds a JSON artifact of the detected {@link FaceBox | boxes} once
+   * complete. Subsequent `resize` calls with `crop: 'focal'` on the same
+   * source pick up the stored focal point automatically.
+   */
+  detectFaces(srcKey: string, opts?: DetectFacesOpts | null): Promise<JobHandle>;
+  /**
+   * Manually set (or override) the focal point for a source image, normalized
+   * `0..=1`. Persists a {@link FocalPointRecord} with `source: 'manual'`.
+   * Resolves to `null`.
+   */
+  setFocalPoint(srcKey: string, point: FocalPoint): Promise<null>;
+  /**
+   * Read the persisted {@link FocalPointRecord} for a source, or `null` when
+   * none has been set (neither `detectFaces` nor `setFocalPoint` has run).
+   */
+  getFocalPoint(srcKey: string): Promise<FocalPointRecord | null>;
+  /**
+   * Remove the persisted focal point for a source. Resolves to `true` when a
+   * record was deleted, `false` when there was nothing to clear.
+   */
+  clearFocalPoint(srcKey: string): Promise<boolean>;
   /** Convert a LibreOffice-supported document to PDF. */
   docToPdf(srcKey: string, opts?: DocToPdfOpts | null): Promise<JobHandle>;
   /** Render a single page of a document as a raster thumbnail. */
@@ -389,6 +540,8 @@ function outputExtension(spec: TransformSpec): string {
     case 'extract_frames':
       // Output key is the JSON frameset manifest; frames live under its base.
       return 'json';
+    case 'extract_audio':
+      return 'm4a';
     case 'thumbnail':
     case 'resize': {
       // thumbnail's `format` is optional in TS (defaults to jpg server-side);
@@ -396,6 +549,9 @@ function outputExtension(spec: TransformSpec): string {
       const fmt = (spec as { format?: ImageFormat }).format ?? 'jpg';
       return fmt;
     }
+    case 'detect_faces':
+      // Output key is the JSON artifact listing the detected face boxes.
+      return 'json';
     case 'ocr':
       return 'txt';
     case 'doc_to_pdf':
@@ -477,6 +633,12 @@ export interface TransformsPatternSpec {
   /** Sugar for `resize` arrays — same shape, same semantics. */
   variants?: ResizeOpts[];
   ocr?: OcrOpts | OcrOpts[];
+  /**
+   * Run face detection on matching uploads and persist a focal point so
+   * `resize`/`variants` entries with `crop: 'focal'` crop around faces. Pass
+   * `true` for detector defaults, or an object to tune the detection.
+   */
+  detectFaces?: boolean | { min_score?: number; max_faces?: number; fast?: boolean };
 }
 
 /**

package/src/types.ts

@@ -206,37 +206,46 @@ export interface Database {
 
   /**
    * Update a single document in a collection.
-   * 
+   *
    * @param collection - The collection name
    * @param filter - Query filter to match the document to update
    * @param update - Update operations (MongoDB-style with $set, $inc, etc.)
-   * @returns Promise that resolves to an object with the number of modified documents
-   * 
+   * @returns Promise that resolves to real matched/modified counts — `modified`
+   *   is 0 when the filter matched nothing, so a conditional filter plus an
+   *   atomic operator is safe for enforcement (quotas, redemption caps, seats)
+   *
    * @example
    * ```typescript
-   * const result = await db.updateOne('users',
-   *   { email: 'john@example.com' },
-   *   { $set: { lastLogin: new Date() }, $inc: { loginCount: 1 } }
+   * // Atomic redemption-cap enforcement: only one of N concurrent checkouts
+   * // can win each remaining slot — no read-then-act needed.
+   * const result = await db.updateOne('discount_codes',
+   *   { id, redeemedCount: { $lt: maxRedemptions } },
+   *   { $inc: { redeemedCount: 1 } }
    * );
-   * console.log(`Modified ${result.modified} documents`);
+   * if (result.modified === 0) throw new Error('code exhausted');
    * ```
    */
-  updateOne(collection: string, filter: any, update: any): Promise<{ modified: number }>;
+  updateOne(
+    collection: string,
+    filter: any,
+    update: any,
+  ): Promise<{ modified: number; matched: number; matchedCount: number; modifiedCount: number }>;
 
   /**
    * Delete a single document from a collection.
-   * 
+   *
    * @param collection - The collection name
    * @param filter - Query filter to match the document to delete
-   * @returns Promise that resolves to an object with the number of deleted documents
-   * 
+   * @returns Promise that resolves to the real number of deleted documents
+   *   (0 when the filter matched nothing)
+   *
    * @example
    * ```typescript
    * const result = await db.deleteOne('posts', { _id: postId });
    * console.log(`Deleted ${result.deleted} documents`);
    * ```
    */
-  deleteOne(collection: string, filter: any): Promise<{ deleted: number }>;
+  deleteOne(collection: string, filter: any): Promise<{ deleted: number; deletedCount: number }>;
 
   /**
    * Delete multiple documents from a collection.