@maravilla-labs/platform 0.2.4 → 0.3.0

package/dist/transforms-KzpoYW43.d.ts

@@ -0,0 +1,156 @@
+/**
+ * @fileoverview Media transforms — async ffmpeg / image / OCR jobs.
+ *
+ * Mirrors the Rust `platform.media.transforms` surface. All mutating
+ * methods (transcode/thumbnail/resize/ocr) return a {@link JobHandle}
+ * whose `outputKey` is content-addressed via {@link keyFor} and known
+ * up front — clients can render placeholder UI for the derived asset
+ * before the worker even starts the job.
+ *
+ * The runtime injects the live JS object as `platform.media.transforms`
+ * (see `crates/runtime/src/ops/platform/js_bindings/platform_js.rs`).
+ * The static helper {@link keyFor} is exported separately and runs
+ * client-side — it must produce byte-for-byte identical output to the
+ * Rust `derive_key`. The shared golden-vector fixture
+ * `crates/platform/tests/derive_key_vectors.json` is consumed from both
+ * the Rust integration test (`crates/platform/tests/derive_key_golden.rs`)
+ * and the TS test (`packages/platform/tests/derive-key.test.ts`) to keep
+ * the two in lockstep.
+ */
+/** Video container targets supported by v1. */
+type VideoFormat = 'mp4' | 'webm';
+/** Image output formats supported by v1. */
+type ImageFormat = 'jpg' | 'png' | 'webp';
+/** Lifecycle state of a transform job. */
+type JobStatus = 'pending' | 'running' | 'complete' | 'failed';
+/** Options for `transforms.transcode`. */
+interface TranscodeOpts {
+    format: VideoFormat;
+    codec?: string;
+    max_width?: number;
+    max_height?: number;
+    audio_codec?: string;
+    bitrate_kbps?: number;
+}
+/** Options for `transforms.thumbnail` — extract a single video frame. */
+interface ThumbnailOpts {
+    /** Offset into the source. Accepts `"00:00:01"`, `"1s"`, or a plain number-as-string. */
+    at: string;
+    width?: number;
+    height?: number;
+    /** Defaults to `"jpg"` server-side when omitted. */
+    format?: ImageFormat;
+    quality?: number;
+}
+/** Options for `transforms.resize`. */
+interface ResizeOpts {
+    width?: number;
+    height?: number;
+    format: ImageFormat;
+    quality?: number;
+    strip_metadata?: boolean;
+}
+/** Options for `transforms.ocr`. */
+interface OcrOpts {
+    /** Tesseract language code(s). Defaults to `"eng"` server-side when omitted. */
+    lang?: string;
+}
+/** Tagged union of all transform requests — matches the Rust `TransformSpec`. */
+type TransformSpec = ({
+    kind: 'transcode';
+} & TranscodeOpts) | ({
+    kind: 'thumbnail';
+} & ThumbnailOpts) | ({
+    kind: 'resize';
+} & ResizeOpts) | ({
+    kind: 'ocr';
+} & OcrOpts);
+/** Probe output. All fields optional — ffprobe doesn't fill every one for every input. */
+interface MediaInfo {
+    duration_secs?: number;
+    width?: number;
+    height?: number;
+    video_codec?: string;
+    audio_codec?: string;
+    bitrate_bps?: number;
+    container?: string;
+}
+/** Returned by every mutating transforms method. */
+interface JobHandle {
+    id: string;
+    src_key: string;
+    output_key: string;
+    status: JobStatus;
+}
+/** Returned by `transforms.job(id)`. */
+interface JobStatusResponse {
+    id: string;
+    status: JobStatus;
+}
+interface TransformsService {
+    transcode(srcKey: string, opts: TranscodeOpts): Promise<JobHandle>;
+    thumbnail(srcKey: string, opts: ThumbnailOpts): Promise<JobHandle>;
+    resize(srcKey: string, opts: ResizeOpts): Promise<JobHandle>;
+    probe(srcKey: string): Promise<MediaInfo>;
+    ocr(srcKey: string, opts?: OcrOpts | null): Promise<JobHandle>;
+    job(id: string): Promise<JobStatusResponse>;
+}
+/**
+ * Compute the canonical derived-asset key for `(srcKey, spec)`.
+ *
+ * Shape: `__derived/<srcHash>/<variantHash>.<ext>` where each hash is
+ * the first 16 hex chars (8 bytes / 64 bits) of `SHA-256(...)`.
+ *
+ * **MUST** match Rust `platform::media::transforms::derive_key` byte-for-byte.
+ * Cross-language golden vectors live at
+ * `crates/platform/tests/derive_key_vectors.json`.
+ */
+declare function keyFor(srcKey: string, spec: TransformSpec): string;
+/** Convenience namespace mirroring the Rust `transforms::keyFor` re-export. */
+declare const transforms: {
+    keyFor: typeof keyFor;
+};
+/**
+ * Per-pattern transforms declaration used inside the `transforms` block of
+ * `maravilla.config.ts`. Each field accepts a single opts object or an array.
+ *
+ * `variants` is sugar for `resize` arrays — convenient for the common
+ * "image → multiple resized renditions" case.
+ */
+interface TransformsPatternSpec {
+    transcode?: TranscodeOpts | TranscodeOpts[];
+    thumbnail?: ThumbnailOpts | ThumbnailOpts[];
+    resize?: ResizeOpts | ResizeOpts[];
+    /** Sugar for `resize` arrays — same shape, same semantics. */
+    variants?: ResizeOpts[];
+    ocr?: OcrOpts | OcrOpts[];
+}
+/**
+ * Top-level `transforms` block. Keys are glob path patterns matched against
+ * the storage key of every uploaded object. The adapter compiles each entry
+ * into a synthetic `storage.put` event handler that fans out the declared
+ * transforms via `Promise.all`.
+ *
+ * @example
+ * ```ts
+ * import { defineConfig } from '@maravilla-labs/platform/config';
+ *
+ * export default defineConfig({
+ *   transforms: {
+ *     'uploads/videos/**': {
+ *       transcode: [{ format: 'mp4' }, { format: 'webm' }],
+ *       thumbnail: { at: '1s', width: 640, format: 'jpg' },
+ *     },
+ *     'uploads/photos/**': {
+ *       variants: [
+ *         { width: 1600, format: 'webp', quality: 85 },
+ *         { width: 400,  format: 'webp', quality: 80 },
+ *       ],
+ *     },
+ *   },
+ * });
+ * ```
+ */
+type TransformsConfig = Record<string, TransformsPatternSpec>;
+
+export { type ImageFormat as I, type JobHandle as J, type MediaInfo as M, type OcrOpts as O, type ResizeOpts as R, type TransformsConfig as T, type VideoFormat as V, type TransformsPatternSpec as a, type JobStatus as b, type JobStatusResponse as c, type ThumbnailOpts as d, type TranscodeOpts as e, type TransformSpec as f, type TransformsService as g, keyFor as k, transforms as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maravilla-labs/platform",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "description": "Universal platform client for Maravilla runtime",
   "type": "module",
   "main": "./dist/index.js",
@@ -27,12 +27,14 @@
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
   },
   "devDependencies": {
     "@types/node": "^22.10.6",
     "tsup": "^8.5.0",
-    "typescript": "^5.9.2"
+    "typescript": "^5.9.2",
+    "vitest": "^1.6.0"
   },
   "peerDependencies": {
     "livekit-client": "^2.18.1"

package/src/config.ts

@@ -38,6 +38,9 @@
  */
 export type SecretRef = string | { env: string };
 
+import type { TransformsConfig } from './transforms.js';
+export type { TransformsConfig, TransformsPatternSpec } from './transforms.js';
+
 // ── Resources + policies ──
 
 export interface ResourceDefinition {
@@ -198,6 +201,13 @@ export interface MaravillaConfig {
   auth?: AuthConfigBlock;
   /** Declarative database indexes (regular + vector). Reconciled upsert-only on deploy. */
   database?: DatabaseConfigBlock;
+  /**
+   * Declarative media transforms — each entry compiles into a synthetic
+   * `storage.put` event handler that fans out the declared
+   * `platform.media.transforms.*` calls (via `Promise.all`) for every
+   * matching upload. See {@link TransformsConfig}.
+   */
+  transforms?: TransformsConfig;
 }
 
 // ── Database block ──

package/src/events.ts

@@ -33,6 +33,7 @@ export type EventTrigger =
   | EventTriggerQueue
   | EventTriggerChannel
   | EventTriggerDeploy
+  | EventTriggerStorage
   | EventTriggerRen;
 
 export interface EventTriggerKv {
@@ -84,6 +85,20 @@ export interface EventTriggerDeploy {
   phase: 'ready' | 'draining' | 'stopped';
 }
 
+/**
+ * Object storage trigger — fires when an object is created or removed
+ * under the matching `keyPattern`. Used by both hand-written `onStorage`
+ * handlers and by the synthesized handlers that the adapter compiles
+ * from a `transforms` block in `maravilla.config.ts`.
+ */
+export interface EventTriggerStorage {
+  kind: 'storage';
+  /** Glob-style storage key pattern (e.g. `"uploads/videos/**"`). Omit to match all objects. */
+  keyPattern?: string;
+  /** Operation filter; omit to match both `put` and `delete`. */
+  op?: 'put' | 'delete';
+}
+
 export interface EventTriggerRen {
   kind: 'ren';
   match: { r?: string; t?: string; ns?: string };
@@ -157,6 +172,21 @@ export interface DeployEvent {
   ts: number;
 }
 
+/**
+ * Storage event payload — emitted by the dev-server / runtime when an
+ * object is put or deleted. The synthesized transforms handlers consume
+ * the `key` field to look up the source object.
+ */
+export interface StorageEvent {
+  op: 'put' | 'delete';
+  key: string;
+  /** Present on `put` — content type from the upload metadata, when known. */
+  contentType?: string;
+  /** Present on `put` — size in bytes, when known. */
+  size?: number;
+  ts: number;
+}
+
 // ============ Handler context ============
 
 export interface EventCtx {
@@ -264,6 +294,28 @@ export function onDeploy(
   return register({ kind: 'deploy', phase }, handler);
 }
 
+/**
+ * React to object-storage `put` / `delete` events. `keyPattern` is a
+ * glob (e.g. `"uploads/videos/**"`). Omit `op` to match both put and
+ * delete; omit `keyPattern` to match every object in the tenant's
+ * bucket.
+ *
+ * ```ts
+ * export const onUpload = onStorage(
+ *   { keyPattern: 'uploads/photos/**', op: 'put' },
+ *   async (event, ctx) => {
+ *     await ctx.platform.media.transforms.resize(event.key, { width: 1600, format: 'webp' });
+ *   },
+ * );
+ * ```
+ */
+export function onStorage(
+  config: Omit<EventTriggerStorage, 'kind'>,
+  handler: (event: StorageEvent, ctx: EventCtx) => unknown | Promise<unknown>,
+): RegisteredHandler<StorageEvent> {
+  return register({ kind: 'storage', ...config }, handler);
+}
+
 /** Escape hatch for arbitrary `RenEvent` matches. */
 export function defineEvent(
   config: Omit<EventTriggerRen, 'kind'>,

package/src/index.ts

@@ -52,6 +52,7 @@ export * from './realtime.js';
 export * from './media.js';
 export * from './media-room.js';
 export * from './push.js';
+export * from './transforms.js';
 
 /**
  * Global platform instance injected by Maravilla runtime or development tools.

package/src/remote-client.ts

@@ -1,4 +1,4 @@
-import type { KvNamespace, KvListResult, Database, DbFindOptions, Storage, RealtimeService, PresenceService, AuthService, AuthCaller, AuthUser, AuthSession, AuthField, RegisterOptions, LoginOptions, UserListFilter, UserListResponse, UpdateUserOptions, PolicyService, VectorIndexSpec, VectorIndexDescriptor, VectorQueryWithFilter, VectorSearchHit, IndexSpec, IndexDescriptor } from './types.js';
+import type { KvNamespace, KvListResult, Database, DbFindOptions, Storage, RealtimeService, PresenceService, AuthService, AuthCaller, AuthUser, AuthSession, AuthField, RegisterOptions, LoginOptions, UserListFilter, UserListResponse, UpdateUserOptions, PolicyService, VectorIndexSpec, VectorIndexDescriptor, VectorQueryWithFilter, VectorSearchHit, IndexSpec, IndexDescriptor, Workflows, WorkflowHandle, WorkflowRun, WorkflowStepRecord } from './types.js';
 import { RemoteMediaService } from './media.js';
 
 /**
@@ -396,6 +396,21 @@ class RemoteStorage implements Storage {
     if (response.status === 404) return null;
     return response.json();
   }
+
+  async confirm(key: string): Promise<void> {
+    // Mirrors the dev-server route registered in
+    // `crates/dev-server/src/router.rs`:
+    //   POST /api/storage/confirm  body: { key: "..." }
+    // The handler verifies the object actually landed in the backing store
+    // and publishes the synthesized `storage.put` RenEvent that any
+    // registered handlers (including those synthesized from a `transforms`
+    // config block) react to.
+    await this.fetch(`${this.baseUrl}/api/storage/confirm`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ key }),
+    });
+  }
 }
 
 /**
@@ -628,6 +643,127 @@ class RemotePolicyService implements PolicyService {
   }
 }
 
+/**
+ * Remote Workflows service — HTTP adaptor over the dev-server's
+ * `/api/workflows/*` routes. The runtime (isolate) path uses `Deno.core.ops`
+ * instead; both produce handles with the same shape.
+ *
+ * @internal
+ */
+class RemoteWorkflows implements Workflows {
+  constructor(
+    private baseUrl: string,
+    private headers: Record<string, string>,
+  ) {}
+
+  private async request(path: string, options: RequestInit = {}): Promise<Response> {
+    const response = await fetch(`${this.baseUrl}${path}`, {
+      ...options,
+      headers: { ...this.headers, ...options.headers },
+    });
+    if (!response.ok && response.status !== 404) {
+      const error = await response.text();
+      throw new Error(`Platform API error: ${response.status} - ${error}`);
+    }
+    return response;
+  }
+
+  async start(workflowId: string, input: unknown = {}): Promise<WorkflowHandle> {
+    if (typeof workflowId !== 'string' || !workflowId) {
+      throw new Error('workflows.start: workflowId must be a non-empty string');
+    }
+    const res = await this.request(
+      `/api/workflows/${encodeURIComponent(workflowId)}/start`,
+      { method: 'POST', body: JSON.stringify(input ?? {}) },
+    );
+    const { runId } = (await res.json()) as { runId: string };
+    return makeRemoteWorkflowHandle(this.baseUrl, this.headers, runId);
+  }
+
+  handle(runId: string): WorkflowHandle {
+    if (typeof runId !== 'string' || !runId) {
+      throw new Error('workflows.handle: runId must be a non-empty string');
+    }
+    return makeRemoteWorkflowHandle(this.baseUrl, this.headers, runId);
+  }
+
+  async sendEvent(eventType: string, payload: unknown = null): Promise<number> {
+    if (typeof eventType !== 'string' || !eventType) {
+      throw new Error('workflows.sendEvent: eventType must be a non-empty string');
+    }
+    const res = await this.request(`/api/workflows/signal`, {
+      method: 'POST',
+      body: JSON.stringify({ eventType, payload }),
+    });
+    const data = (await res.json()) as { count: number };
+    return data.count;
+  }
+}
+
+function makeRemoteWorkflowHandle(
+  baseUrl: string,
+  headers: Record<string, string>,
+  runId: string,
+): WorkflowHandle {
+  const doFetch = async (path: string, init: RequestInit = {}): Promise<Response> => {
+    const res = await fetch(`${baseUrl}${path}`, {
+      ...init,
+      headers: { ...headers, ...init.headers },
+    });
+    if (!res.ok && res.status !== 404) {
+      throw new Error(`Platform API error: ${res.status} - ${await res.text()}`);
+    }
+    return res;
+  };
+
+  const handle: WorkflowHandle = {
+    runId,
+    async status(): Promise<WorkflowRun | null> {
+      const res = await doFetch(`/api/workflows/runs/${encodeURIComponent(runId)}`);
+      if (res.status === 404) return null;
+      return (await res.json()) as WorkflowRun;
+    },
+    async history(): Promise<WorkflowStepRecord[]> {
+      const res = await doFetch(
+        `/api/workflows/runs/${encodeURIComponent(runId)}/history`,
+      );
+      return (await res.json()) as WorkflowStepRecord[];
+    },
+    async cancel(): Promise<boolean> {
+      const res = await doFetch(
+        `/api/workflows/runs/${encodeURIComponent(runId)}/cancel`,
+        { method: 'POST' },
+      );
+      const data = (await res.json()) as { cancelled: boolean };
+      return data.cancelled;
+    },
+    async result(options?: { timeoutMs?: number }): Promise<unknown> {
+      const timeoutMs = options?.timeoutMs;
+      const deadline =
+        typeof timeoutMs === 'number' && Number.isFinite(timeoutMs) && timeoutMs > 0
+          ? Date.now() + timeoutMs
+          : null;
+      let delay = 100;
+      while (true) {
+        const run = await handle.status();
+        if (!run) throw new Error(`workflow run not found: ${runId}`);
+        if (run.status === 'completed') return run.output;
+        if (run.status === 'failed' || run.status === 'cancelled') {
+          const err = new Error(`workflow ${run.status}`) as Error & { run: WorkflowRun };
+          err.run = run;
+          throw err;
+        }
+        if (deadline !== null && Date.now() >= deadline) {
+          throw new Error('workflow result timeout');
+        }
+        await new Promise((r) => setTimeout(r, delay));
+        delay = Math.min(delay * 2, 5000);
+      }
+    },
+  };
+  return handle;
+}
+
 /**
  * Create a remote platform client for development environments.
  * 
@@ -671,6 +807,7 @@ export function createRemoteClient(baseUrl: string, tenant: string) {
   const realtime = new RemoteRealtimeService(baseUrl, headers);
   const auth = new RemoteAuthService(baseUrl, headers);
   const policy = new RemotePolicyService();
+  const workflows = new RemoteWorkflows(baseUrl, headers);
 
   return {
     env: {
@@ -682,5 +819,6 @@ export function createRemoteClient(baseUrl: string, tenant: string) {
     realtime,
     auth,
     policy,
+    workflows,
   };
 }

package/src/ren.ts

@@ -122,6 +122,12 @@ export class RenClient {
       'presence.join',
       'presence.leave',
       'presence.update',
+      // Media transform lifecycle (emitted by media-transforms-worker)
+      'transform.queued',
+      'transform.started',
+      'transform.progress',
+      'transform.complete',
+      'transform.failed',
       // Meta events
       'ren.meta'
     ];