@maravilla-labs/platform 0.14.0 → 0.16.0

package/dist/{transforms-BHWez32E.d.ts → transforms-DkAlUPu6.d.ts}

@@ -133,12 +133,109 @@ 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;
+    /**
+     * Face-box-relative crop zoom for `crop: 'focal'`. A scale factor (`>= 1.0`)
+     * on the smallest output-aspect frame that fully contains the source's
+     * detected face(s): `1.0` frames tightly around the subject; larger values
+     * pull back for more headroom/context; a value large enough to exceed the
+     * image saturates to the plain scale-to-cover crop. Only meaningful with
+     * `crop: 'focal'` on a source that has stored face data (from `detectFaces`);
+     * ignored otherwise. Omit for the legacy point-only crop — when unset it does
+     * not affect the derived key, so existing crops are unchanged.
+     */
+    zoom?: number;
+    /**
+     * Union bounding box of the source's detected faces, normalized `0..=1`.
+     * Server-injected (like {@link ResizeOpts.focal}) and only when `zoom` is set
+     * — callers never pass this. Present so the wire type mirrors the Rust
+     * `ResizeOpts` exactly.
+     */
+    subject_box?: SubjectBox;
+}
+/**
+ * Union bounding box of a source's detected faces, normalized `0..=1`
+ * (top-left `x`/`y` + `w`/`h`). Sizes the `crop: 'focal'` {@link
+ * ResizeOpts.zoom} window; server-injected only.
+ */
+interface SubjectBox {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
 }
 /** 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.
@@ -263,6 +360,8 @@ type TransformSpec = ({
 } & ExtractAudioOpts) | ({
     kind: 'resize';
 } & ResizeOpts) | ({
+    kind: 'detect_faces';
+} & DetectFacesOpts) | ({
     kind: 'ocr';
 } & OcrOpts) | ({
     kind: 'doc_to_pdf';
@@ -320,6 +419,30 @@ interface TransformsService {
     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. */
@@ -349,9 +472,71 @@ interface TransformsService {
  * `crates/platform/tests/derive_key_vectors.json`.
  */
 declare function keyFor(srcKey: string, spec: TransformSpec): string;
+/** Inputs for {@link focalCssFrame}. */
+interface FocalCssFrameInput {
+    /** The source's focal point (from `detectFaces`/`getFocalPoint` or manual). */
+    focal: FocalPoint;
+    /** Detected face boxes (from the same record). Empty/absent → plain cover. */
+    faces?: FaceBox[] | null;
+    /**
+     * Source image intrinsic pixel dimensions — only their ratio is used. In the
+     * browser these are free from a loaded `<img>` (`naturalWidth`/`Height`);
+     * `detectFaces`' output artifact also carries them.
+     */
+    imgWidth: number;
+    imgHeight: number;
+    /** Target container aspect ratio, `width / height`. */
+    containerAspect: number;
+    /**
+     * Frame zoom, clamped to `>= 1`. `1` frames tightly around the face(s); larger
+     * pulls back toward the plain cover view. Defaults to `1`. Mirrors the
+     * server-side `resize({ crop: 'focal', zoom })` semantics.
+     */
+    zoom?: number;
+}
+/** CSS values produced by {@link focalCssFrame}. */
+interface FocalCssFrame {
+    /** `object-position` value, e.g. `"44.0% 27.0%"`. */
+    objectPosition: string;
+    /** `transform: scale(...)` factor to apply on top of `object-fit: cover`. */
+    scale: number;
+    /** `transform-origin` — same anchor as `objectPosition`. */
+    transformOrigin: string;
+}
+/**
+ * Union bounding box of detected faces, clamped to `0..1`; `null` for an empty
+ * list or a degenerate (zero-area) union. Sizes the {@link focalCssFrame} zoom
+ * window; mirrors the server-side union used by `resize({ crop:'focal', zoom })`.
+ */
+declare function unionFaceBox(faces?: FaceBox[] | null): SubjectBox | null;
+/**
+ * Compute CSS values that frame a source image on its detected face(s) for a
+ * container of ANY aspect ratio — the browser-side counterpart to the server's
+ * `resize({ crop: 'focal', zoom })`. Instead of a pre-rendered crop per shape,
+ * apply the result to a single `<img>`:
+ *
+ * ```html
+ * <div style="aspect-ratio: 3/1; overflow: hidden">
+ *   <img
+ *     style="width:100%; height:100%; object-fit:cover;
+ *            object-position: {objectPosition}; transform-origin: {transformOrigin};
+ *            transform: scale({scale})" />
+ * </div>
+ * ```
+ *
+ * `object-position` pans the cover image onto the focal point; the extra
+ * `transform: scale` tightens the frame around the face(s) per `zoom`, scaling
+ * about the same anchor so the face stays put. Framework-agnostic: it returns
+ * plain CSS values — apply them however your framework applies styles.
+ *
+ * With no detected faces it degrades to a plain focal-point cover (`scale: 1`).
+ */
+declare function focalCssFrame(input: FocalCssFrameInput): FocalCssFrame;
 /** Convenience namespace mirroring the Rust `transforms::keyFor` re-export. */
 declare const transforms: {
     keyFor: typeof keyFor;
+    focalCssFrame: typeof focalCssFrame;
+    unionFaceBox: typeof unionFaceBox;
 };
 /**
  * Per-pattern transforms declaration used inside the `transforms` block of
@@ -367,6 +552,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
@@ -396,4 +591,4 @@ interface TransformsPatternSpec {
  */
 type TransformsConfig = Record<string, TransformsPatternSpec>;
 
-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 DocFormat as e, type DocToPdfOpts as f, type DocThumbnailOpts as g, type DocConvertOpts as h, type DocToMarkdownOpts as i, type DocToHtmlOpts as j, type ImageRef as k, type DocReplaceImagesOpts as l, type DocInsertQrCodeOpts as m, type QrPayload as n, type DocTemplateMergeOpts as o, type TransformSpec as p, type JobHandle as q, type JobStatusResponse as r, type TransformsService as s, keyFor as t, transforms as u };
+export { unionFaceBox as A, focalCssFrame as B, transforms as C, 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 SubjectBox as S, 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, type FocalCssFrameInput as y, type FocalCssFrame as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maravilla-labs/platform",
-  "version": "0.14.0",
+  "version": "0.16.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, ExtractFramesOpts, ExtractAudioOpts, 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 }> {
@@ -1300,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 ?? {} });
   }