@revealui/core 0.7.0 → 0.9.0

package/dist/storage/types.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Provider-agnostic storage interface for the RevealUI fleet.
+ *
+ * Per `feedback_revealui_agnosticism_principle` + `feedback_pluggable_provider_pattern`:
+ * slim interface, tag + factory, explicit "no-X" opt-in, mock provider for tests.
+ *
+ * Providers implement this interface; consumers (apps/server media routes,
+ * apps/admin health probes, packages/core Payload-style plugin shims) depend
+ * only on this contract. Switching providers becomes a config change.
+ *
+ * GAP-208 introduces this abstraction during the Vercel Blob → Cloudflare R2
+ * swap (2026-05-18). The vercel-blob Payload-style plugin (vercel-blob.ts)
+ * stays in place during migration for backward compat; once consumers migrate
+ * to the interface, the legacy plugin is dropped.
+ */
+export interface StorageProvider {
+    /** Upload binary data. Returns a fully-qualified URL the value is reachable at. */
+    put(key: string, data: Blob | ArrayBuffer | Uint8Array | ReadableStream<Uint8Array>, opts?: PutOptions): Promise<PutResult>;
+    /** Delete by either provider URL or storage key. Best-effort; missing keys are not errors. */
+    del(keyOrUrl: string): Promise<void>;
+    /** List items, optionally filtered by key prefix. Used by health probes + admin browsing. */
+    list(opts?: ListOptions): Promise<ListResult>;
+    /** Provider tag (e.g. "r2", "vercel-blob", "mock") — exposed so consumers can adapt URL handling. */
+    readonly provider: string;
+}
+export interface PutOptions {
+    /** MIME type — written to the object's Content-Type header. Defaults to "application/octet-stream". */
+    contentType?: string;
+    /**
+     * Public read access (no auth required for GET on the returned URL).
+     * Defaults to "public" because the current media-upload flow needs public CDN URLs.
+     * Providers that don't support public access (e.g. private-bucket-only configs)
+     * MUST throw when access: "public" is requested.
+     */
+    access?: 'public' | 'private';
+    /** Cache-Control header value. Provider may apply a sensible default if omitted. */
+    cacheControl?: string;
+    /** Custom user-metadata. Keys are lowercased; values are strings. Limits vary by provider. */
+    metadata?: Record<string, string>;
+}
+export interface PutResult {
+    /** The storage key the object was written to (provider-relative, e.g. "media/uuid.jpg"). */
+    key: string;
+    /** Fully-qualified URL the object is reachable at for GET. */
+    url: string;
+    /** Storage size in bytes. Always populated by every provider. */
+    size: number;
+    /** Provider tag that wrote this object (matches StorageProvider.provider). */
+    provider: string;
+}
+export interface ListOptions {
+    /** Filter to keys starting with this prefix. */
+    prefix?: string;
+    /** Maximum items per page. Providers cap this internally (typically 1000). */
+    limit?: number;
+    /** Opaque pagination cursor from a previous ListResult. */
+    cursor?: string;
+}
+export interface ListResult {
+    items: ListItem[];
+    /** Next-page cursor if hasMore is true; undefined when listing is exhausted. */
+    cursor?: string;
+    hasMore: boolean;
+}
+export interface ListItem {
+    key: string;
+    url: string;
+    size: number;
+    uploadedAt: Date;
+}
+/**
+ * Discriminated union over `provider`. Adding a new provider means:
+ *   1. add a tag here + the per-provider config shape
+ *   2. add a case in the createStorage factory
+ *   3. implement the StorageProvider interface in a new file
+ *
+ * No silent fallback per `feedback_pluggable_provider_pattern`: unknown tags
+ * throw with a clear "valid tags: ..." message.
+ */
+export type StorageConfig = {
+    provider: 'r2';
+    r2: R2Config;
+} | {
+    provider: 'vercel-blob';
+    vercelBlob: VercelBlobConfig;
+} | {
+    provider: 'mock';
+};
+export interface R2Config {
+    /** Cloudflare account ID (visible at top of the R2 dashboard). */
+    accountId: string;
+    /** R2 API token Access Key ID (NOT the global account API token). */
+    accessKeyId: string;
+    /** R2 API token Secret Access Key (paired with accessKeyId). */
+    secretAccessKey: string;
+    /** Bucket name (per-account-globally-unique within R2). */
+    bucket: string;
+    /**
+     * Optional public base URL for objects (e.g. "https://media.revealui.com" if a
+     * custom domain is bound, or "https://<account-id>.r2.cloudflarestorage.com/<bucket>"
+     * for the dev URL). When set, PutResult.url uses this base. When omitted, PutResult.url
+     * falls back to a presigned URL (private bucket pattern).
+     */
+    publicBaseUrl?: string;
+}
+export interface VercelBlobConfig {
+    /** vercel_blob_rw_* token from the Vercel Blob dashboard. */
+    token: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/storage/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/storage/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,MAAM,WAAW,eAAe;IAC9B,mFAAmF;IACnF,GAAG,CACD,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,IAAI,GAAG,WAAW,GAAG,UAAU,GAAG,cAAc,CAAC,UAAU,CAAC,EAClE,IAAI,CAAC,EAAE,UAAU,GAChB,OAAO,CAAC,SAAS,CAAC,CAAC;IAEtB,8FAA8F;IAC9F,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAErC,6FAA6F;IAC7F,IAAI,CAAC,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAE9C,qGAAqG;IACrG,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAID,MAAM,WAAW,UAAU;IACzB,uGAAuG;IACvG,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;IAE9B,oFAAoF;IACpF,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,8FAA8F;IAC9F,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,SAAS;IACxB,4FAA4F;IAC5F,GAAG,EAAE,MAAM,CAAC;IAEZ,8DAA8D;IAC9D,GAAG,EAAE,MAAM,CAAC;IAEZ,iEAAiE;IACjE,IAAI,EAAE,MAAM,CAAC;IAEb,8EAA8E;IAC9E,QAAQ,EAAE,MAAM,CAAC;CAClB;AAID,MAAM,WAAW,WAAW;IAC1B,gDAAgD;IAChD,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,8EAA8E;IAC9E,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,2DAA2D;IAC3D,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,QAAQ,EAAE,CAAC;IAElB,gFAAgF;IAChF,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,QAAQ;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,IAAI,CAAC;CAClB;AAID;;;;;;;;GAQG;AACH,MAAM,MAAM,aAAa,GACrB;IAAE,QAAQ,EAAE,IAAI,CAAC;IAAC,EAAE,EAAE,QAAQ,CAAA;CAAE,GAChC;IAAE,QAAQ,EAAE,aAAa,CAAC;IAAC,UAAU,EAAE,gBAAgB,CAAA;CAAE,GACzD;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzB,MAAM,WAAW,QAAQ;IACvB,kEAAkE;IAClE,SAAS,EAAE,MAAM,CAAC;IAElB,qEAAqE;IACrE,WAAW,EAAE,MAAM,CAAC;IAEpB,gEAAgE;IAChE,eAAe,EAAE,MAAM,CAAC;IAExB,2DAA2D;IAC3D,MAAM,EAAE,MAAM,CAAC;IAEf;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,6DAA6D;IAC7D,KAAK,EAAE,MAAM,CAAC;CACf"}

package/dist/storage/types.js

@@ -0,0 +1,16 @@
+/**
+ * Provider-agnostic storage interface for the RevealUI fleet.
+ *
+ * Per `feedback_revealui_agnosticism_principle` + `feedback_pluggable_provider_pattern`:
+ * slim interface, tag + factory, explicit "no-X" opt-in, mock provider for tests.
+ *
+ * Providers implement this interface; consumers (apps/server media routes,
+ * apps/admin health probes, packages/core Payload-style plugin shims) depend
+ * only on this contract. Switching providers becomes a config change.
+ *
+ * GAP-208 introduces this abstraction during the Vercel Blob → Cloudflare R2
+ * swap (2026-05-18). The vercel-blob Payload-style plugin (vercel-blob.ts)
+ * stays in place during migration for backward compat; once consumers migrate
+ * to the interface, the legacy plugin is dropped.
+ */
+export {};

package/dist/storage/vercel-blob-provider.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Vercel Blob implementation of StorageProvider.
+ *
+ * Legacy backend retained during the GAP-208 Cloudflare R2 cutover so the
+ * media-upload path can fall back to Vercel Blob when R2 is not configured.
+ * Wraps @vercel/blob's put/del/list behind the provider-agnostic
+ * StorageProvider interface. Cloudflare R2 (r2.ts) is the canonical backend;
+ * this provider is removed once the Blob store is decommissioned.
+ *
+ * NOTE: distinct from vercel-blob.ts in this directory, which is the legacy
+ * Payload-style upload *plugin* still wired into apps/admin's
+ * revealui.config.ts. This file is the StorageProvider the createStorage
+ * factory returns for the 'vercel-blob' tag.
+ *
+ * Server-only. Do NOT import from client-side code or edge runtime.
+ */
+import type { ListOptions, ListResult, PutOptions, PutResult, StorageProvider, VercelBlobConfig } from './types.js';
+declare class VercelBlobProvider implements StorageProvider {
+    readonly provider = "vercel-blob";
+    private readonly token;
+    constructor(config: VercelBlobConfig);
+    put(key: string, data: Blob | ArrayBuffer | Uint8Array | ReadableStream<Uint8Array>, opts?: PutOptions): Promise<PutResult>;
+    del(keyOrUrl: string): Promise<void>;
+    list(opts?: ListOptions): Promise<ListResult>;
+}
+export declare function createVercelBlobProvider(config: VercelBlobConfig): StorageProvider;
+export type { VercelBlobProvider };
+//# sourceMappingURL=vercel-blob-provider.d.ts.map

package/dist/storage/vercel-blob-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vercel-blob-provider.d.ts","sourceRoot":"","sources":["../../src/storage/vercel-blob-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,KAAK,EAEV,WAAW,EACX,UAAU,EACV,UAAU,EACV,SAAS,EACT,eAAe,EACf,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAKpB,cAAM,kBAAmB,YAAW,eAAe;IACjD,QAAQ,CAAC,QAAQ,iBAAgB;IACjC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;gBAEnB,MAAM,EAAE,gBAAgB;IAW9B,GAAG,CACP,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,IAAI,GAAG,WAAW,GAAG,UAAU,GAAG,cAAc,CAAC,UAAU,CAAC,EAClE,IAAI,CAAC,EAAE,UAAU,GAChB,OAAO,CAAC,SAAS,CAAC;IAmCf,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOpC,IAAI,CAAC,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;CAqBpD;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,gBAAgB,GAAG,eAAe,CAElF;AAED,YAAY,EAAE,kBAAkB,EAAE,CAAC"}

package/dist/storage/vercel-blob-provider.js

@@ -0,0 +1,88 @@
+/**
+ * Vercel Blob implementation of StorageProvider.
+ *
+ * Legacy backend retained during the GAP-208 Cloudflare R2 cutover so the
+ * media-upload path can fall back to Vercel Blob when R2 is not configured.
+ * Wraps @vercel/blob's put/del/list behind the provider-agnostic
+ * StorageProvider interface. Cloudflare R2 (r2.ts) is the canonical backend;
+ * this provider is removed once the Blob store is decommissioned.
+ *
+ * NOTE: distinct from vercel-blob.ts in this directory, which is the legacy
+ * Payload-style upload *plugin* still wired into apps/admin's
+ * revealui.config.ts. This file is the StorageProvider the createStorage
+ * factory returns for the 'vercel-blob' tag.
+ *
+ * Server-only. Do NOT import from client-side code or edge runtime.
+ */
+import { del, list, put } from '@vercel/blob';
+import { toUint8Array } from './_helpers.js';
+const PROVIDER_TAG = 'vercel-blob';
+const DEFAULT_LIST_LIMIT = 1000;
+class VercelBlobProvider {
+    provider = PROVIDER_TAG;
+    token;
+    constructor(config) {
+        if (!config.token) {
+            throw new Error('Vercel Blob provider requires VercelBlobConfig.token (the ' +
+                'BLOB_READ_WRITE_TOKEN value). For new deployments prefer Cloudflare ' +
+                'R2 (provider: "r2").');
+        }
+        this.token = config.token;
+    }
+    async put(key, data, opts) {
+        if (opts?.access === 'private') {
+            throw new Error("Vercel Blob provider does not support access: 'private' — every blob " +
+                'is publicly readable. Use Cloudflare R2 for private-access patterns.');
+        }
+        // Normalize to bytes so the result carries an accurate size regardless of
+        // input shape (ReadableStream has no length until consumed). Re-wrap in a
+        // fresh Uint8Array so the Blob part is backed by a non-shared ArrayBuffer,
+        // satisfying the DOM BlobPart type under TS strict typed-array generics.
+        const body = await toUint8Array(data);
+        const result = await put(key, new Blob([new Uint8Array(body)]), {
+            access: 'public',
+            token: this.token,
+            contentType: opts?.contentType,
+            // Keys are caller-controlled (callers pre-randomize, e.g. media/<uuid>.ext);
+            // never append a second random suffix or the returned URL won't match `key`.
+            addRandomSuffix: false,
+        });
+        // Vercel Blob has no per-object user-metadata or Cache-Control-header API
+        // (only cacheControlMaxAge); opts.metadata / opts.cacheControl are ignored
+        // by this legacy provider. R2 honors both.
+        return {
+            key,
+            url: result.url,
+            size: body.byteLength,
+            provider: PROVIDER_TAG,
+        };
+    }
+    async del(keyOrUrl) {
+        // Vercel's del is idempotent (deleting an absent blob is a no-op), so this
+        // satisfies the best-effort contract. It requires the full blob URL, which
+        // is what media records persist.
+        await del(keyOrUrl, { token: this.token });
+    }
+    async list(opts) {
+        const response = await list({
+            token: this.token,
+            prefix: opts?.prefix,
+            limit: opts?.limit ?? DEFAULT_LIST_LIMIT,
+            cursor: opts?.cursor,
+        });
+        const items = response.blobs.map((blob) => ({
+            key: blob.pathname,
+            url: blob.url,
+            size: blob.size,
+            uploadedAt: blob.uploadedAt,
+        }));
+        return {
+            items,
+            cursor: response.cursor,
+            hasMore: response.hasMore,
+        };
+    }
+}
+export function createVercelBlobProvider(config) {
+    return new VercelBlobProvider(config);
+}

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@revealui/core",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "RevealUI's runtime engine — admin UI, REST API, auth, rich text, plugin system, and access control. The heart of the open-source platform.",
   "license": "MIT",
   "dependencies": {
-    "@electric-sql/pglite": "^0.4.4",
+    "@aws-sdk/client-s3": "^3.1053.0",
+    "@electric-sql/pglite": "^0.4.5",
     "@lexical/clipboard": "^0.44.0",
     "@lexical/code": "^0.44.0",
     "@lexical/html": "^0.44.0",
@@ -21,19 +22,19 @@
     "dataloader": "^2.2.3",
     "jose": "^6.2.3",
     "lexical": "^0.44.0",
-    "pg": "^8.20.0",
+    "pg": "^8.21.0",
     "yjs": "^13.6.30",
     "zod": "^4.4.3",
-    "@revealui/cache": "0.1.5",
-    "@revealui/contracts": "0.5.0",
+    "@revealui/cache": "0.2.1",
+    "@revealui/contracts": "0.6.0",
     "@revealui/resilience": "0.2.4",
-    "@revealui/security": "0.3.1",
+    "@revealui/security": "0.4.0",
     "@revealui/utils": "0.3.5"
   },
   "devDependencies": {
     "@types/json-schema": "^7.0.15",
     "@types/pg": "^8.20.0",
-    "@types/react": "^19.2.14",
+    "@types/react": "^19.2.15",
     "@types/react-dom": "^19.2.3",
     "@vitest/coverage-v8": "^4.1.5",
     "expect-type": "^1.3.0",

package/dist/storage/vercel-blob.d.ts

@@ -1,17 +0,0 @@
-/**
- * Vercel Blob Storage Plugin
- *
- * WARNING: This module is server-only.
- * Do NOT import in client-side code or edge runtime.
- */
-import type { Plugin } from '../types/index.js';
-export interface VercelBlobStorageConfig {
-    enabled?: boolean;
-    collections?: {
-        [key: string]: boolean;
-    };
-    token?: string;
-    prefix?: string;
-}
-export declare function vercelBlobStorage(config: VercelBlobStorageConfig): Plugin;
-//# sourceMappingURL=vercel-blob.d.ts.map

package/dist/storage/vercel-blob.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"vercel-blob.d.ts","sourceRoot":"","sources":["../../src/storage/vercel-blob.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAEhD,MAAM,WAAW,uBAAuB;IACtC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE;QACZ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KACxB,CAAC;IACF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,uBAAuB,GAAG,MAAM,CAyFzE"}