@maravilla-labs/platform 0.8.0 → 0.8.3

package/dist/{transforms-BkgPh93b.d.ts → transforms-BR1PyWa-.d.ts}

@@ -17,6 +17,7 @@
  * 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. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maravilla-labs/platform",
-  "version": "0.8.0",
+  "version": "0.8.3",
   "description": "Universal platform client for Maravilla runtime",
   "type": "module",
   "main": "./dist/index.js",
@@ -32,7 +32,7 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@maravilla-labs/types": "^0.6.0",
+    "@maravilla-labs/types": "^0.8.3",
     "@noble/hashes": "^1.5.0",
     "livekit-client": "^2.18.1"
   },

package/src/config.ts

@@ -419,6 +419,45 @@ export interface BrandingConfig {
   custom_css?: string;
 }
 
+// ── Email ──
+
+/**
+ * Transactional email settings for the hosted `_auth` flows (currently the
+ * password-reset email). Reconciled server-side on deploy.
+ *
+ * The visible `From` *address* is always the platform's verified sender
+ * (Maravilla Cloud) and is not configurable. The `From` display *name* is safe
+ * to customise via `from_name`; surface your own address via `reply_to`.
+ */
+export interface EmailConfig {
+  /** Master switch. When `false`, the reset flow still mints a token but no email is sent. Defaults to `true`. */
+  enabled?: boolean;
+  /** `From` display name (e.g. `"Acme Support"`) → `Acme Support <noreply@maravilla.cloud>`. The address is fixed; only the name is yours. */
+  from_name?: string;
+  /** Reply-To address. The visible `From` is always the platform sender; replies go here. */
+  reply_to?: string;
+  /** Override the password-reset email subject line. */
+  password_reset_subject?: string;
+  /** Full custom HTML body. Use the literal `{{reset_url}}` placeholder for the link. */
+  password_reset_html?: string;
+  /** Full custom plain-text body (same `{{reset_url}}` placeholder). */
+  password_reset_text?: string;
+  /** Enable passwordless "magic link" email login on the hosted `/_auth/login` page. Off by default; requires `enabled` to send. */
+  magic_link_enabled?: boolean;
+  /** Override the magic-link email subject line. */
+  magic_link_subject?: string;
+  /** Full custom HTML body for the magic-link email. Use the literal `{{magic_link_url}}` placeholder. */
+  magic_link_html?: string;
+  /** Full custom plain-text body for the magic-link email (same `{{magic_link_url}}` placeholder). */
+  magic_link_text?: string;
+  /** Override the email-verification email subject line. */
+  verification_subject?: string;
+  /** Full custom HTML body for the verification email. Use the literal `{{verify_url}}` placeholder. */
+  verification_html?: string;
+  /** Full custom plain-text body for the verification email (same `{{verify_url}}` placeholder). */
+  verification_text?: string;
+}
+
 // ── Top-level shape ──
 
 export interface AuthConfigBlock {
@@ -429,6 +468,8 @@ export interface AuthConfigBlock {
   oauth?: OAuthProvidersConfig;
   security?: SecurityConfig;
   branding?: BrandingConfig;
+  /** Transactional email settings for the hosted `_auth` flows. */
+  email?: EmailConfig;
   /**
    * Named, reusable policy fragments. Reference a fragment from any
    * resource policy with `fragment('name')`; {@link defineConfig} expands

package/src/remote-client.ts

@@ -1,4 +1,4 @@
-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, PolicyService, VectorIndexSpec, VectorIndexDescriptor, VectorQueryWithFilter, VectorSearchHit, IndexSpec, IndexDescriptor, Workflows, WorkflowHandle, WorkflowRun, WorkflowStepRecord } from './types.js';
+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, 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 { RemoteMediaService } from './media.js';
 import { getRequestAuthHeader } from './request-scope.js';
@@ -1137,11 +1137,16 @@ export function createRemoteClient(baseUrl: string, tenant: string) {
   const policy = new RemotePolicyService();
   const workflows = new RemoteWorkflows(baseUrl, headers);
 
+  const browser = new RemoteBrowserClient(baseUrl, headers);
+  const frames = new RemoteFramesClient(baseUrl, headers);
+
   return {
     env: {
       KV: kvProxy,
       DB: db,
       STORAGE: storage,
+      BROWSER: browser,
+      FRAMES: frames,
     },
     media,
     realtime,
@@ -1151,6 +1156,70 @@ export function createRemoteClient(baseUrl: string, tenant: string) {
   };
 }
 
+/**
+ * Remote `platform.env.BROWSER` for development. Posts to the dev-server
+ * `/api/media/browser/*` routes and returns the same {@link BrowserJobHandle}
+ * shape the native runtime returns. Phase 1 plumbing — the worker marks
+ * the job `failed("not implemented")` immediately; clients can still
+ * exercise the full request → handle → poll cycle.
+ *
+ * @internal
+ */
+class RemoteBrowserClient implements BrowserClient {
+  constructor(
+    private baseUrl: string,
+    private headers: Record<string, string>,
+  ) {}
+
+  private async post(path: string, body: unknown): Promise<BrowserJobHandle> {
+    const res = await fetch(`${this.baseUrl}/api/media/browser${path}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', ...this.headers, ...getRequestAuthHeader() },
+      body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+      const text = await res.text();
+      throw new Error(`Browser error (${res.status}): ${text}`);
+    }
+    return res.json() as Promise<BrowserJobHandle>;
+  }
+
+  screenshot(request: ScreenshotRequest): Promise<BrowserJobHandle> {
+    return this.post('/screenshot', request);
+  }
+
+  pdf(request: PdfRequest): Promise<BrowserJobHandle> {
+    return this.post('/pdf', request);
+  }
+}
+
+/**
+ * Remote `platform.env.FRAMES` for development. Posts to the dev-server
+ * `/api/media/frames/render` route. Same plumbing stub story as
+ * {@link RemoteBrowserClient}.
+ *
+ * @internal
+ */
+class RemoteFramesClient implements FramesClient {
+  constructor(
+    private baseUrl: string,
+    private headers: Record<string, string>,
+  ) {}
+
+  async render(request: FramesRenderRequest): Promise<BrowserJobHandle> {
+    const res = await fetch(`${this.baseUrl}/api/media/frames/render`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', ...this.headers, ...getRequestAuthHeader() },
+      body: JSON.stringify(request),
+    });
+    if (!res.ok) {
+      const text = await res.text();
+      throw new Error(`Frames render error (${res.status}): ${text}`);
+    }
+    return res.json() as Promise<BrowserJobHandle>;
+  }
+}
+
 /**
  * Remote `platform.media.transforms` for development. Each method posts
  * to the dev-server's `/api/media/transforms/*` route and returns the

package/src/transforms.ts

@@ -24,6 +24,43 @@
 // consume this package client-side.
 import { sha256 } from '@noble/hashes/sha2';
 
+// ── Headless-browser + frames-render re-exports ─────────────────────────
+//
+// The contract types live in `@maravilla-labs/types` so the runtime crate
+// and downstream packages (adapter-core, app code) consume one canonical
+// shape. We re-export them through this module so app code that already
+// reaches for `@maravilla-labs/platform/transforms` for media-related
+// helpers also gets the browser / frames request types without a second
+// import.
+//
+// The methods themselves — `platform.env.BROWSER.screenshot(...)`,
+// `.pdf(...)`, `platform.env.FRAMES.render(...)` — are injected by the
+// runtime and typed by the `BrowserClient` / `FramesClient` interfaces
+// (declared in `@maravilla-labs/types`, re-exported below). All three
+// return a `BrowserJobHandle` whose `output_key` equals the
+// caller-supplied `target` storage key; poll status with
+// `platform.media.transforms.job(handle.id)`, then read the rendered
+// bytes from `platform.env.STORAGE`. See `BrowserClient.screenshot` /
+// `BrowserClient.pdf` / `FramesClient.render` for per-method JSDoc with
+// runnable examples; see
+// `docs/recipes/{screenshot-public-url,render-animated-title-card,og-image-from-own-page}.md`
+// for full walkthroughs.
+export type {
+  BrowserClient,
+  BrowserCookie,
+  BrowserJobHandle,
+  BrowserJobStatus,
+  BrowserViewport,
+  BrowserWaitFor,
+  FramesClient,
+  FramesCodec,
+  FramesRenderRequest,
+  PdfPageFormat,
+  PdfRequest,
+  ScreenshotFormat,
+  ScreenshotRequest,
+} from '@maravilla-labs/types';
+
 // ── Types — mirror `crates/platform/src/media/transforms/types.rs` ──────
 
 /** Video container targets supported by v1. */

package/src/types.ts

@@ -741,9 +741,9 @@ export interface Storage {
  * This is the main interface for accessing KV storage, database, and object storage operations.
  */
 export interface PlatformEnv {
-  /** 
+  /**
    * Key-Value storage namespaces. Access different KV namespaces by property name.
-   * 
+   *
    * @example
    * ```typescript
    * const userCache = platform.env.KV.users;
@@ -755,6 +755,19 @@ export interface PlatformEnv {
   DB: Database;
   /** Object/file storage interface */
   STORAGE: Storage;
+  /**
+   * Headless-browser screenshot / PDF render. Returns a job handle
+   * polled via the shared transforms job ledger. Phase 1 plumbing stub —
+   * the worker marks browser jobs `failed("not implemented")` until
+   * Task #2 lands the Chromium pipeline.
+   */
+  BROWSER: BrowserClient;
+  /**
+   * Deterministic HTML → MP4 / WebM render. Path-only: the renderer hits
+   * a route on the tenant's own deployment. Phase 1 plumbing stub —
+   * real implementation in Task #3.
+   */
+  FRAMES: FramesClient;
 }
 
 /**
@@ -805,7 +818,22 @@ export interface PresenceService {
 //
 // `AuthService` is also imported (not just re-exported) because the
 // `Platform` interface below references it within this module's scope.
-import type { AuthService } from '@maravilla-labs/types';
+import type { AuthService, BrowserClient, FramesClient } from '@maravilla-labs/types';
+export type {
+  BrowserClient,
+  FramesClient,
+  BrowserCookie,
+  BrowserJobHandle,
+  BrowserJobStatus,
+  BrowserViewport,
+  BrowserWaitFor,
+  FramesCodec,
+  FramesRenderRequest,
+  PdfPageFormat,
+  PdfRequest,
+  ScreenshotFormat,
+  ScreenshotRequest,
+} from '@maravilla-labs/types';
 export type {
   AuthUser,
   AuthCaller,