@maravilla-labs/platform 0.2.5 → 0.3.1

package/src/transforms.ts

@@ -0,0 +1,251 @@
+/**
+ * @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.
+ */
+
+// Isomorphic SHA-256 via @noble/hashes — runs in Node, Deno, and every
+// browser without a bundler-specific shim. `node:crypto` would pull
+// Node built-ins into browser bundles and break Vite builds that
+// consume this package client-side.
+import { sha256 } from '@noble/hashes/sha2';
+
+// ── Types — mirror `crates/platform/src/media/transforms/types.rs` ──────
+
+/** Video container targets supported by v1. */
+export type VideoFormat = 'mp4' | 'webm';
+
+/** Image output formats supported by v1. */
+export type ImageFormat = 'jpg' | 'png' | 'webp';
+
+/** Lifecycle state of a transform job. */
+export type JobStatus = 'pending' | 'running' | 'complete' | 'failed';
+
+/** Options for `transforms.transcode`. */
+export 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. */
+export 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`. */
+export interface ResizeOpts {
+  width?: number;
+  height?: number;
+  format: ImageFormat;
+  quality?: number;
+  strip_metadata?: boolean;
+}
+
+/** Options for `transforms.ocr`. */
+export 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`. */
+export 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. */
+export 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. */
+export interface JobHandle {
+  id: string;
+  src_key: string;
+  output_key: string;
+  status: JobStatus;
+}
+
+/** Returned by `transforms.job(id)`. */
+export interface JobStatusResponse {
+  id: string;
+  status: JobStatus;
+}
+
+// ── Service interface (matches the JS object the runtime injects) ───────
+
+export 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>;
+}
+
+// ── derive_key mirror ───────────────────────────────────────────────────
+
+/** Sort object keys recursively so the canonical JSON is stable. */
+function sortKeys(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(sortKeys);
+  if (value && typeof value === 'object') {
+    const out: Record<string, unknown> = {};
+    for (const k of Object.keys(value as Record<string, unknown>).sort()) {
+      out[k] = sortKeys((value as Record<string, unknown>)[k]);
+    }
+    return out;
+  }
+  return value;
+}
+
+/**
+ * Canonical JSON encoding — matches `serde_json::to_string` over a
+ * recursively key-sorted object. Numbers, booleans, strings, null, and
+ * nested objects/arrays only; no `undefined`, no functions.
+ */
+function canonicalJson(value: unknown): string {
+  return JSON.stringify(sortKeys(value));
+}
+
+/** Hex-encoded SHA-256 of the input bytes, truncated to 16 chars (8 bytes). */
+function shortHexSha256(input: string): string {
+  const bytes = new TextEncoder().encode(input);
+  const hash = sha256(bytes);
+  return Array.from(hash.slice(0, 8))
+    .map((b) => b.toString(16).padStart(2, '0'))
+    .join('');
+}
+
+/**
+ * Output extension for a spec — drives the `.<ext>` suffix on the
+ * derived key. Matches `TransformSpec::output_extension` in Rust.
+ */
+function outputExtension(spec: TransformSpec): string {
+  switch (spec.kind) {
+    case 'transcode':
+      return spec.format; // 'mp4' | 'webm'
+    case 'thumbnail':
+    case 'resize': {
+      // thumbnail's `format` is optional in TS (defaults to jpg server-side);
+      // mirror that default here so keyFor matches the canonical Rust form.
+      const fmt = (spec as { format?: ImageFormat }).format ?? 'jpg';
+      return fmt;
+    }
+    case 'ocr':
+      return 'txt';
+    default: {
+      const _exhaust: never = spec;
+      throw new Error(`unknown transform kind: ${(_exhaust as { kind: string }).kind}`);
+    }
+  }
+}
+
+/**
+ * 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`.
+ */
+export function keyFor(srcKey: string, spec: TransformSpec): string {
+  const srcHash = shortHexSha256(srcKey);
+  // Re-encode so the canonical JSON includes the `kind` discriminator at
+  // a sorted position alongside the inlined opts fields — matches what
+  // Rust's `serde_json::to_value(&spec)` produces for the tagged enum.
+  const variantHash = shortHexSha256(canonicalJson(spec));
+  const ext = outputExtension(spec);
+  return `__derived/${srcHash}/${variantHash}.${ext}`;
+}
+
+/** Convenience namespace mirroring the Rust `transforms::keyFor` re-export. */
+export const transforms = {
+  keyFor,
+};
+
+// ── Declarative `transforms` config (consumed by the adapter compiler) ──
+//
+// Mirrors the build-time `TransformsConfig` in `@maravilla-labs/adapter-core`,
+// duplicated here so user code that writes `defineConfig({ transforms: {...} })`
+// gets full IDE completion without depending on adapter-core at runtime.
+//
+// The two type definitions are structurally identical — adapter-core's
+// `compileTransforms` consumes either shape interchangeably (it only walks the
+// JSON-shaped values, not the type-level identity).
+
+/**
+ * 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.
+ */
+export 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 },
+ *       ],
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export type TransformsConfig = Record<string, TransformsPatternSpec>;

package/src/types.ts

@@ -687,6 +687,26 @@ export interface Storage {
     lastModified: string;
     metadata?: any;
   } | null>;
+
+  /**
+   * Notify the platform that a presigned-PUT upload completed at the given
+   * key. The bytes never crossed the server, so no `storage.put` event would
+   * fire automatically — call this from your form action right after the
+   * client's direct PUT succeeds. The platform looks up the object's
+   * metadata and publishes the matching `storage.put` event so any registered
+   * event handlers (including the synthesized handlers from a `transforms`
+   * config block) fire as if the upload had streamed through the server.
+   *
+   * Idempotent — safe to call more than once with the same key (the server
+   * dedupes by emitting at most one event per (tenant, key, mtime) tuple).
+   *
+   * @example
+   * ```ts
+   * await fetch(presignedUrl, { method: 'PUT', body: blob });
+   * await platform.env.STORAGE.confirm(key);
+   * ```
+   */
+  confirm(key: string): Promise<void>;
 }
 
 /**
@@ -1346,6 +1366,83 @@ export interface PushService {
   rotateVapidKeys(): Promise<PublicPushConfig>;
 }
 
+/** State of a workflow run. */
+export type WorkflowRunStatus =
+  | 'queued'
+  | 'running'
+  | 'sleeping'
+  | 'waiting_event'
+  | 'completed'
+  | 'failed'
+  | 'cancelled';
+
+/** Kind of a recorded step. */
+export type WorkflowStepKind = 'run' | 'sleep' | 'wait_event' | 'ai' | 'mcp' | 'invoke';
+
+/** A durable workflow run as stored in the ledger. */
+export interface WorkflowRun {
+  runId: string;
+  workflowId: string;
+  projectId?: string;
+  deploymentId: string;
+  input: unknown;
+  status: WorkflowRunStatus;
+  attempt: number;
+  createdAt: number;
+  updatedAt: number;
+  completedAt?: number;
+  output?: unknown;
+  error?: unknown;
+}
+
+/** A single step in a run's history. */
+export interface WorkflowStepRecord {
+  name: string;
+  kind: WorkflowStepKind;
+  status: 'pending' | 'completed' | 'failed';
+  output?: unknown;
+  error?: unknown;
+  startedAt: number;
+  completedAt?: number;
+  wakeAt?: number;
+}
+
+/**
+ * Handle returned by `platform.workflows.start()` — poll status, await
+ * the final result, cancel, or inspect step history.
+ */
+export interface WorkflowHandle {
+  /** The run's unique id. */
+  readonly runId: string;
+  /** Current run record, or `null` if the run does not exist. */
+  status(): Promise<WorkflowRun | null>;
+  /** Full step history — useful for debugging. */
+  history(): Promise<WorkflowStepRecord[]>;
+  /**
+   * Wait for the run to reach a terminal state and return its output.
+   * Throws if the run ended `failed` or `cancelled`; the thrown error
+   * carries the run record on the `run` property.
+   */
+  result(options?: { timeoutMs?: number }): Promise<unknown>;
+  /** Best-effort cancellation. Returns `true` if the run transitioned. */
+  cancel(): Promise<boolean>;
+}
+
+/** Durable multi-step workflow service. */
+export interface Workflows {
+  /** Start a new run of the workflow with the given input. */
+  start(workflowId: string, input?: unknown): Promise<WorkflowHandle>;
+  /** Get a handle to an existing run without starting one. */
+  handle(runId: string): WorkflowHandle;
+  /**
+   * Signal an event to any runs paused on `step.waitForEvent`. Returns
+   * the number of runs resolved. Matching rules: `eventType` must equal
+   * the waiter's filter `type`; each key in the filter's `match` must
+   * be present in `payload` with an equal value.
+   */
+  sendEvent(eventType: string, payload?: unknown): Promise<number>;
+}
+
 export interface Platform {
   /** Environment containing all available platform services */
   env: PlatformEnv;
@@ -1364,4 +1461,6 @@ export interface Platform {
    * fallback that doesn't proxy to delivery.
    */
   push?: PushService;
+  /** Durable multi-step workflows — `start / handle / sendEvent`. */
+  workflows: Workflows;
 }

package/tests/derive-key.test.ts

@@ -0,0 +1,68 @@
+/**
+ * Cross-language golden vectors for `transforms.keyFor`.
+ *
+ * Loads `crates/platform/tests/derive_key_vectors.json` — the same
+ * fixture the Rust `derive_key` integration test consumes — and asserts
+ * that the TypeScript mirror produces byte-identical output for every
+ * vector. If this fails, either:
+ *   - the JS algorithm has drifted from Rust → fix `transforms.ts`;
+ *   - the Rust algorithm changed deliberately → regenerate the fixture
+ *     via `cargo run --example gen_derive_key_vectors -p platform > …`
+ *     and update the JS impl in lockstep.
+ */
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { describe, expect, it } from 'vitest';
+
+import { keyFor, type TransformSpec } from '../src/transforms.js';
+
+interface Vector {
+  name: string;
+  src: string;
+  spec: Record<string, unknown>;
+  expected_key: string;
+}
+
+const fixturePath = join(
+  __dirname,
+  '..',
+  '..',
+  '..',
+  'crates',
+  'platform',
+  'tests',
+  'derive_key_vectors.json',
+);
+
+function loadVectors(): Vector[] {
+  const raw = readFileSync(fixturePath, 'utf8');
+  const parsed = JSON.parse(raw) as Vector[];
+  if (!Array.isArray(parsed) || parsed.length === 0) {
+    throw new Error(`expected non-empty vector array in ${fixturePath}`);
+  }
+  return parsed;
+}
+
+describe('transforms.keyFor (golden vectors shared with Rust)', () => {
+  const vectors = loadVectors();
+
+  it('loads at least 8 vectors from the shared fixture', () => {
+    expect(vectors.length).toBeGreaterThanOrEqual(8);
+  });
+
+  it('covers every TransformSpec variant', () => {
+    const kinds = new Set(vectors.map((v) => v.spec['kind'] as string));
+    for (const required of ['transcode', 'thumbnail', 'resize', 'ocr']) {
+      expect(kinds.has(required), `missing ${required}`).toBe(true);
+    }
+  });
+
+  for (const v of vectors) {
+    it(`matches Rust derive_key for ${v.name}`, () => {
+      const got = keyFor(v.src, v.spec as unknown as TransformSpec);
+      expect(got).toBe(v.expected_key);
+    });
+  }
+});