@openlup/platform 0.0.0 → 0.16.0

package/dist/bff/envelope.js

@@ -0,0 +1,80 @@
+// BFF response envelope.
+//
+// Every BFF response is JSON `{ ok: true, data, meta? }` or `{ ok: false, error: { code, message,
+// details? }, meta? }`. A private response carries the request reference in the `x-request-id`
+// header and, for errors or responses with meta, in `meta.requestId`; a shared-cache response
+// (public or s-maxage) carries neither. `undefined` members are stripped before serialization.
+export const BFF_REQUEST_REFERENCE_HEADER = "x-request-id";
+export const BFF_ERROR_CODES = [
+    "BAD_REQUEST",
+    "UNAUTHORIZED",
+    "FORBIDDEN",
+    "NOT_FOUND",
+    "METHOD_NOT_ALLOWED",
+    "CONFLICT",
+    "RATE_LIMITED",
+    "UPSTREAM_UNAVAILABLE",
+    "INTERNAL",
+    "INVALID_RESPONSE",
+];
+/** The HTTP status each error code answers with unless the caller names another. */
+export const BFF_ERROR_STATUS = {
+    BAD_REQUEST: 400,
+    UNAUTHORIZED: 401,
+    FORBIDDEN: 403,
+    NOT_FOUND: 404,
+    METHOD_NOT_ALLOWED: 405,
+    CONFLICT: 409,
+    RATE_LIMITED: 429,
+    UPSTREAM_UNAVAILABLE: 503,
+    INTERNAL: 500,
+    INVALID_RESPONSE: 502,
+};
+/** Build the envelope writers a deployment's handlers share. */
+export function createBffResponder(options = {}) {
+    function sendBffSuccess(res, data, meta, successOptions = {}) {
+        sendJson(res, 200, { ok: true, data, meta }, successOptions.cacheControl);
+    }
+    function sendBffError(res, code, message, errorOptions = {}) {
+        sendJson(res, errorOptions.status ?? BFF_ERROR_STATUS[code], {
+            ok: false,
+            error: { code, message, details: errorOptions.details },
+            meta: errorOptions.meta,
+        });
+    }
+    function sendMethodNotAllowed(res, allowedMethods) {
+        res.setHeader("Allow", allowedMethods.join(", "));
+        sendBffError(res, "METHOD_NOT_ALLOWED", "Method not allowed", { status: 405 });
+    }
+    function sendJson(res, status, body, cacheControl = "no-store") {
+        const shared = /(?:^|,)\s*(?:public\b|s-maxage\s*=)/i.test(cacheControl);
+        const requestId = shared ? undefined : options.responseRequestId?.(res);
+        const responseBody = withRequestReference(body, requestId, shared);
+        res.setHeader("Content-Type", "application/json");
+        res.setHeader("Cache-Control", cacheControl);
+        if (shared && typeof res.removeHeader === "function")
+            res.removeHeader(BFF_REQUEST_REFERENCE_HEADER);
+        else if (requestId)
+            res.setHeader(BFF_REQUEST_REFERENCE_HEADER, requestId);
+        res.status(status).json(stripUndefined(responseBody));
+    }
+    return { sendBffSuccess, sendBffError, sendMethodNotAllowed };
+}
+function withRequestReference(body, requestId, omitRequestId) {
+    if (requestId && (body.ok === false || body.meta)) {
+        return { ...body, meta: { ...body.meta, requestId } };
+    }
+    if (!omitRequestId || !body.meta || !("requestId" in body.meta))
+        return body;
+    const { requestId: _omitted, ...meta } = body.meta;
+    return { ...body, meta: Object.keys(meta).length > 0 ? meta : undefined };
+}
+function stripUndefined(value) {
+    if (Array.isArray(value))
+        return value.map(stripUndefined);
+    if (!value || typeof value !== "object")
+        return value;
+    return Object.fromEntries(Object.entries(value)
+        .filter(([, entryValue]) => entryValue !== undefined)
+        .map(([key, entryValue]) => [key, stripUndefined(entryValue)]));
+}

package/dist/bff/health.d.ts

@@ -0,0 +1,24 @@
+import type { HttpRequest, HttpResponse } from "../http/index.js";
+import type { BffResponder } from "./envelope.js";
+export interface HealthContract<T extends {
+    contractVersion: string;
+}> {
+    safeParse(value: unknown): {
+        success: true;
+        data: T;
+    } | {
+        success: false;
+    };
+}
+export interface HealthHandlerOptions<T extends {
+    contractVersion: string;
+}> {
+    responder: BffResponder;
+    /** The deployment's strict health contract. */
+    contract: HealthContract<T>;
+    /** Builds this request's health payload: service identity, release provenance and the rest. */
+    read: () => unknown;
+}
+export declare function createHealthHandler<T extends {
+    contractVersion: string;
+}>(options: HealthHandlerOptions<T>): (req: HttpRequest, res: HttpResponse) => void;

package/dist/bff/health.js

@@ -0,0 +1,19 @@
+// BFF health route.
+//
+// GET answers the deployment's health payload, validated by the deployment's strict contract, with
+// the payload's contract version in `meta`; any other method answers 405 with `Allow: GET`. A
+// payload that fails its own contract answers INTERNAL rather than an unchecked body.
+export function createHealthHandler(options) {
+    return function health(req, res) {
+        if (req.method !== "GET") {
+            options.responder.sendMethodNotAllowed(res, ["GET"]);
+            return;
+        }
+        const result = options.contract.safeParse(options.read());
+        if (!result.success) {
+            options.responder.sendBffError(res, "INTERNAL", "Health contract is invalid");
+            return;
+        }
+        options.responder.sendBffSuccess(res, result.data, { contractVersion: result.data.contractVersion });
+    };
+}

package/dist/bff/index.d.ts

@@ -0,0 +1,6 @@
+export { createBffDispatcher, type BffDispatch, type BffDispatcherOptions, type RouteEntry } from "./dispatch.js";
+export { lazyBffRoute } from "./lazyRoute.js";
+export { rewriteBffRouterRequestUrl } from "./routerRewrite.js";
+export { BFF_ERROR_CODES, BFF_ERROR_STATUS, BFF_REQUEST_REFERENCE_HEADER, createBffResponder, type BffError, type BffErrorCode, type BffErrorOptions, type BffErrorResponse, type BffMeta, type BffResponder, type BffResponderOptions, type BffResponse, type BffSuccessOptions, type BffSuccessResponse, } from "./envelope.js";
+export { createHealthHandler, type HealthContract, type HealthHandlerOptions, } from "./health.js";
+export { createRequestContextStore, type ObservedRequestContext, type RequestContextOptions, type RequestContextStore, } from "./requestContext.js";

package/dist/bff/index.js

@@ -0,0 +1,6 @@
+export { createBffDispatcher } from "./dispatch.js";
+export { lazyBffRoute } from "./lazyRoute.js";
+export { rewriteBffRouterRequestUrl } from "./routerRewrite.js";
+export { BFF_ERROR_CODES, BFF_ERROR_STATUS, BFF_REQUEST_REFERENCE_HEADER, createBffResponder, } from "./envelope.js";
+export { createHealthHandler, } from "./health.js";
+export { createRequestContextStore, } from "./requestContext.js";

package/dist/bff/lazyRoute.d.ts

@@ -0,0 +1,4 @@
+import type { RouteEntry } from "./dispatch.js";
+export declare function lazyBffRoute(load: () => Promise<{
+    default: RouteEntry["handler"];
+}>): RouteEntry["handler"];

package/dist/bff/lazyRoute.js

@@ -0,0 +1,13 @@
+export function lazyBffRoute(load) {
+    let handler;
+    let loading;
+    return (req, res) => {
+        if (handler)
+            return handler(req, res);
+        loading ??= load().then((module) => (handler = module.default), (error) => {
+            loading = undefined;
+            throw error;
+        });
+        return loading.then((loaded) => loaded(req, res));
+    };
+}

package/dist/bff/requestContext.d.ts

@@ -0,0 +1,17 @@
+import type { HttpRequest, HttpResponse } from "../http/index.js";
+export interface ObservedRequestContext {
+    readonly requestId: string;
+}
+export interface RequestContextOptions {
+    /** Chooses this request's reference. Called once per request. */
+    readRequestId: (req: HttpRequest) => string;
+}
+export interface RequestContextStore {
+    /** Create (or reuse) the request's context and attach it to the response. */
+    install(req: HttpRequest, res: HttpResponse): ObservedRequestContext;
+    /** The request's context, created on first use. */
+    readOrCreate(req: HttpRequest): ObservedRequestContext;
+    /** The context attached to a response by `install`, if any. */
+    readResponse(res: HttpResponse): ObservedRequestContext | undefined;
+}
+export declare function createRequestContextStore(options: RequestContextOptions): RequestContextStore;

package/dist/bff/requestContext.js

@@ -0,0 +1,26 @@
+// Observed request context.
+//
+// One context per request, created on first use and shared by everything that observes the same
+// request or its response. The deployment decides how a request reference is chosen (for example,
+// a host-assigned request ID or a generated one); the context only keeps the answer stable.
+export function createRequestContextStore(options) {
+    const requestContexts = new WeakMap();
+    const responseContexts = new WeakMap();
+    function readOrCreate(req) {
+        const existing = requestContexts.get(req);
+        if (existing)
+            return existing;
+        const context = { requestId: options.readRequestId(req) };
+        requestContexts.set(req, context);
+        return context;
+    }
+    return {
+        install(req, res) {
+            const context = readOrCreate(req);
+            responseContexts.set(res, context);
+            return context;
+        },
+        readOrCreate,
+        readResponse: (res) => responseContexts.get(res),
+    };
+}

package/dist/bff/routerRewrite.d.ts

@@ -0,0 +1,2 @@
+import type { HttpRequest } from "../http/index.js";
+export declare function rewriteBffRouterRequestUrl(req: HttpRequest): void;

package/dist/bff/routerRewrite.js

@@ -0,0 +1,31 @@
+// URL rewrite for a hosted BFF router entrypoint.
+//
+// A host rewrite can deliver every `/api/bff/*` request to one function, passing the original
+// path in the internal `__bffPath` query value. This restores the request URL and query the
+// dispatcher expects before it matches a route.
+const INTERNAL_BFF_PATH_QUERY = "__bffPath";
+function firstQueryValue(value) {
+    if (Array.isArray(value))
+        return value[0] ?? null;
+    return value ?? null;
+}
+// The rewrite keeps only the path and query, which do not depend on the URL base; this host only
+// completes a request that carries no Host header.
+const FALLBACK_HOST = "bff.invalid";
+export function rewriteBffRouterRequestUrl(req) {
+    const routedPath = firstQueryValue(req.query?.[INTERNAL_BFF_PATH_QUERY]);
+    if (!routedPath)
+        return;
+    const host = typeof req.headers?.host === "string" ? req.headers.host : FALLBACK_HOST;
+    const currentUrl = new URL(typeof req.url === "string" ? req.url : "/", `https://${host}`);
+    currentUrl.searchParams.delete(INTERNAL_BFF_PATH_QUERY);
+    currentUrl.searchParams.delete("path");
+    const normalizedPath = routedPath
+        .split("/")
+        .filter(Boolean)
+        .map((segment) => encodeURIComponent(decodeURIComponent(segment)))
+        .join("/");
+    req.url = `/api/bff/${normalizedPath}${currentUrl.search}`;
+    const { [INTERNAL_BFF_PATH_QUERY]: _internal, path: _hostPath, ...query } = req.query ?? {};
+    req.query = query;
+}

package/dist/blob/binding.d.ts

@@ -0,0 +1,16 @@
+import type { BlobStoragePort } from "@openlup/core/platform-runtime";
+import { type S3ObjectClient } from "./s3.js";
+import { type SupabaseStorageClient } from "./supabase.js";
+import { type VercelBlobSdk } from "./vercel.js";
+type Env = Record<string, string | undefined>;
+export interface BlobBindingDeps {
+    /** The `@vercel/blob` module; without it the vercel-blob capability stays unbound. */
+    vercelBlob?: VercelBlobSdk;
+    /** S3 client factory; defaults to `createS3ClientFromEnv`. */
+    s3ClientFactory?: (env: Env) => S3ObjectClient;
+    /** Ready Supabase Storage client factory; without it the supabase capability stays unbound. */
+    supabaseStorageClient?: () => SupabaseStorageClient;
+}
+/** Resolve the BlobStoragePort for a blob capability, or null when it cannot be bound. */
+export declare function bindBlobPort(blobKind: string, env: Env, deps?: BlobBindingDeps): BlobStoragePort | null;
+export {};

package/dist/blob/binding.js

@@ -0,0 +1,37 @@
+// Blob port binding for bundle composition.
+//
+// Maps the selected blob capability to a concrete BlobStoragePort built from env: filesystem
+// (the local development default), S3-compatible storage (the default client unless one is
+// injected), Vercel Blob (with the injected `@vercel/blob` module) and Supabase Storage (a
+// ready storage client supplied by the injected factory).
+// A capability whose settings or client are missing stays unbound (null); readiness reports it.
+import { createFilesystemBlobStorage } from "./filesystem.js";
+import { createS3BlobStorage } from "./s3.js";
+import { createS3ClientFromEnv } from "./s3Client.js";
+import { createSupabaseBlobStorage } from "./supabase.js";
+import { createVercelBlobStorage } from "./vercel.js";
+/** Resolve the BlobStoragePort for a blob capability, or null when it cannot be bound. */
+export function bindBlobPort(blobKind, env, deps = {}) {
+    switch (blobKind) {
+        case "vercel-blob":
+            return deps.vercelBlob ? createVercelBlobStorage({ env, sdk: deps.vercelBlob }) : null;
+        case "filesystem":
+            return env.BLOB_FS_ROOT && env.BLOB_FS_BASE_URL
+                ? createFilesystemBlobStorage({ root: env.BLOB_FS_ROOT, baseUrl: env.BLOB_FS_BASE_URL })
+                : null;
+        case "s3":
+            return env.BLOB_S3_BUCKET && env.BLOB_S3_BASE_URL
+                ? createS3BlobStorage((deps.s3ClientFactory ?? createS3ClientFromEnv)(env), {
+                    bucket: env.BLOB_S3_BUCKET,
+                    baseUrl: env.BLOB_S3_BASE_URL,
+                })
+                : null;
+        case "supabase": {
+            if (!deps.supabaseStorageClient || !env.BLOB_SUPABASE_BUCKET)
+                return null;
+            return createSupabaseBlobStorage(deps.supabaseStorageClient(), env.BLOB_SUPABASE_BUCKET);
+        }
+        default:
+            return null;
+    }
+}

package/dist/blob/filesystem.d.ts

@@ -0,0 +1,8 @@
+import type { BlobStoragePort } from "@openlup/core/platform-runtime";
+export interface FilesystemBlobOptions {
+    /** Absolute root directory blobs are written under. */
+    root: string;
+    /** Base URL prefix for urlFor()/upload() result URLs. No trailing slash required. */
+    baseUrl: string;
+}
+export declare function createFilesystemBlobStorage(options: FilesystemBlobOptions): BlobStoragePort;

package/dist/blob/filesystem.js

@@ -0,0 +1,71 @@
+// Filesystem adapter for the platform-runtime BlobStoragePort.
+//
+// Stores blobs as plain files under a root directory and serves them through a configurable
+// public base URL (e.g. a static file server / nginx in a self-hosted node-postgres bundle).
+// This is the credential-free adapter the per-adapter contract test runs against in CI.
+import { promises as fs } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
+export function createFilesystemBlobStorage(options) {
+    const root = resolve(options.root);
+    const baseUrl = options.baseUrl.replace(/\/$/, "");
+    const pathFor = (key) => {
+        const target = resolve(root, normalizeKey(key));
+        if (target !== root && !target.startsWith(root + sep)) {
+            throw new Error(`filesystem_blob_key_escapes_root:${key}`);
+        }
+        return target;
+    };
+    return {
+        urlFor(key) {
+            return `${baseUrl}/${normalizeKey(key)}`;
+        },
+        async upload(key, data, _opts) {
+            const filePath = pathFor(key);
+            await fs.mkdir(dirname(filePath), { recursive: true });
+            await fs.writeFile(filePath, data);
+            return { url: this.urlFor(key), pathname: normalizeKey(key) };
+        },
+        async exists(key) {
+            try {
+                await fs.access(pathFor(key));
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+        async delete(keyOrUrl) {
+            const key = stripBaseUrl(keyOrUrl, baseUrl);
+            await fs.rm(pathFor(key), { force: true });
+        },
+        async list(prefix) {
+            const dir = prefix ? pathFor(prefix) : root;
+            const keys = await walk(dir).catch((error) => {
+                if (error.code === "ENOENT")
+                    return [];
+                throw error;
+            });
+            return {
+                keys: keys.map((absolute) => relative(root, absolute).split(sep).join("/")).sort(),
+            };
+        },
+    };
+}
+function normalizeKey(key) {
+    return key.replace(/^\/+/, "");
+}
+function stripBaseUrl(keyOrUrl, baseUrl) {
+    return keyOrUrl.startsWith(`${baseUrl}/`) ? keyOrUrl.slice(baseUrl.length + 1) : keyOrUrl;
+}
+async function walk(dir) {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    const out = [];
+    for (const entry of entries) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory())
+            out.push(...(await walk(full)));
+        else
+            out.push(full);
+    }
+    return out;
+}

package/dist/blob/index.d.ts

@@ -0,0 +1,6 @@
+export { createFilesystemBlobStorage, type FilesystemBlobOptions } from "./filesystem.js";
+export { createS3BlobStorage, type S3BlobOptions, type S3ObjectClient } from "./s3.js";
+export { createS3ClientFromEnv } from "./s3Client.js";
+export { createSupabaseBlobStorage, type SupabaseStorageBucket, type SupabaseStorageClient, } from "./supabase.js";
+export { createVercelBlobStorage, parseVercelStoreId, type VercelBlobAdapterOptions, type VercelBlobEntry, type VercelBlobSdk, type VercelBlobStorage, } from "./vercel.js";
+export { bindBlobPort, type BlobBindingDeps } from "./binding.js";

package/dist/blob/index.js

@@ -0,0 +1,6 @@
+export { createFilesystemBlobStorage } from "./filesystem.js";
+export { createS3BlobStorage } from "./s3.js";
+export { createS3ClientFromEnv } from "./s3Client.js";
+export { createSupabaseBlobStorage, } from "./supabase.js";
+export { createVercelBlobStorage, parseVercelStoreId, } from "./vercel.js";
+export { bindBlobPort } from "./binding.js";

package/dist/blob/s3.d.ts

@@ -0,0 +1,32 @@
+import type { BlobStoragePort } from "@openlup/core/platform-runtime";
+export interface S3ObjectClient {
+    putObject(input: {
+        Bucket: string;
+        Key: string;
+        Body: Uint8Array | Buffer;
+        ContentType?: string;
+    }): Promise<unknown>;
+    headObject(input: {
+        Bucket: string;
+        Key: string;
+    }): Promise<unknown>;
+    deleteObject(input: {
+        Bucket: string;
+        Key: string;
+    }): Promise<unknown>;
+    listObjectsV2(input: {
+        Bucket: string;
+        Prefix?: string;
+    }): Promise<{
+        Contents?: Array<{
+            Key?: string;
+        }>;
+    }>;
+}
+export interface S3BlobOptions {
+    bucket: string;
+    /** Public base URL for objects, e.g. https://cdn.example.com or https://s3.region.amazonaws.com/bucket. */
+    baseUrl: string;
+    defaultContentType?: string;
+}
+export declare function createS3BlobStorage(client: S3ObjectClient, options: S3BlobOptions): BlobStoragePort;

package/dist/blob/s3.js

@@ -0,0 +1,56 @@
+// S3-compatible adapter for the platform-runtime BlobStoragePort.
+//
+// Targets any S3-compatible object store (AWS S3, MinIO, R2, Spaces) used by a self-hosted
+// node-postgres bundle. To stay credential-free in CI and avoid pulling a new SDK dependency
+// into this wave, it depends on a minimal STRUCTURAL client interface (PutObject/HeadObject/
+// DeleteObject/ListObjectsV2). A thin factory over `@aws-sdk/client-s3` satisfies this shape;
+// tests inject a fake. URLs are derived from a configurable public base (CDN or path-style).
+export function createS3BlobStorage(client, options) {
+    const bucket = options.bucket;
+    const baseUrl = options.baseUrl.replace(/\/$/, "");
+    const defaultContentType = options.defaultContentType ?? "application/octet-stream";
+    return {
+        urlFor(key) {
+            return `${baseUrl}/${normalizeKey(key)}`;
+        },
+        async upload(key, data, opts) {
+            const objectKey = normalizeKey(key);
+            await client.putObject({
+                Bucket: bucket,
+                Key: objectKey,
+                Body: data,
+                ContentType: opts?.contentType ?? defaultContentType,
+            });
+            return { url: this.urlFor(objectKey), pathname: objectKey };
+        },
+        async exists(key) {
+            try {
+                await client.headObject({ Bucket: bucket, Key: normalizeKey(key) });
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+        async delete(keyOrUrl) {
+            await client.deleteObject({ Bucket: bucket, Key: stripBaseUrl(keyOrUrl, baseUrl) });
+        },
+        async list(prefix) {
+            const result = await client.listObjectsV2({
+                Bucket: bucket,
+                Prefix: prefix ? normalizeKey(prefix) : undefined,
+            });
+            const keys = (result.Contents ?? [])
+                .map((entry) => entry.Key)
+                .filter((key) => typeof key === "string")
+                .sort();
+            return { keys };
+        },
+    };
+}
+function normalizeKey(key) {
+    return key.replace(/^\/+/, "");
+}
+function stripBaseUrl(keyOrUrl, baseUrl) {
+    return keyOrUrl.startsWith(`${baseUrl}/`) ? normalizeKey(keyOrUrl.slice(baseUrl.length + 1)) : normalizeKey(keyOrUrl);
+}

package/dist/blob/s3Client.d.ts

@@ -0,0 +1,25 @@
+import type { S3ObjectClient } from "./s3.js";
+type Env = Record<string, string | undefined>;
+export interface S3Sdk {
+    S3Client: new (config: {
+        region: string;
+        endpoint?: string;
+        forcePathStyle: boolean;
+        credentials?: {
+            accessKeyId: string;
+            secretAccessKey: string;
+        };
+    }) => {
+        send(command: unknown): ReturnType<S3ObjectClient["listObjectsV2"]>;
+    };
+    PutObjectCommand: new (input: Parameters<S3ObjectClient["putObject"]>[0]) => unknown;
+    HeadObjectCommand: new (input: Parameters<S3ObjectClient["headObject"]>[0]) => unknown;
+    DeleteObjectCommand: new (input: Parameters<S3ObjectClient["deleteObject"]>[0]) => unknown;
+    ListObjectsV2Command: new (input: Parameters<S3ObjectClient["listObjectsV2"]>[0]) => unknown;
+}
+/**
+ * Build an `S3ObjectClient` whose SDK client is created lazily from the given environment.
+ * `loadSdk` replaces the SDK loader (tests).
+ */
+export declare function createS3ClientFromEnv(env: Env, loadSdk?: () => S3Sdk): S3ObjectClient;
+export {};

package/dist/blob/s3Client.js

@@ -0,0 +1,76 @@
+// Default S3 client for the S3-compatible blob capability, built from the environment.
+//
+// `@aws-sdk/client-s3` is an optional peer: it is loaded on the first storage call, through Node's
+// own module resolution, so an application that never selects S3 needs neither the SDK nor its
+// settings. Settings:
+// BLOB_S3_REGION (default us-east-1), BLOB_S3_ENDPOINT (an S3-compatible service; path-style
+// addressing follows from BLOB_S3_FORCE_PATH_STYLE=true), and BLOB_S3_ACCESS_KEY_ID with
+// BLOB_S3_SECRET_ACCESS_KEY (both, or neither to use the SDK's default credential chain).
+import { createRequire } from "node:module";
+function setting(env, name) {
+    const value = env[name]?.trim();
+    return value ? value : undefined;
+}
+function loadS3Sdk() {
+    return createRequire(import.meta.url)("@aws-sdk/client-s3");
+}
+/**
+ * Build an `S3ObjectClient` whose SDK client is created lazily from the given environment.
+ * `loadSdk` replaces the SDK loader (tests).
+ */
+export function createS3ClientFromEnv(env, loadSdk = loadS3Sdk) {
+    const accessKeyId = setting(env, "BLOB_S3_ACCESS_KEY_ID");
+    const secretAccessKey = setting(env, "BLOB_S3_SECRET_ACCESS_KEY");
+    if ((accessKeyId === undefined) !== (secretAccessKey === undefined)) {
+        throw new Error("blob_s3_credentials_incomplete");
+    }
+    let loaded = null;
+    const connect = async () => {
+        if (loaded)
+            return loaded;
+        let sdk;
+        try {
+            sdk = loadSdk();
+        }
+        catch (cause) {
+            peerMissing(cause);
+        }
+        loaded = {
+            sdk,
+            client: new sdk.S3Client({
+                region: setting(env, "BLOB_S3_REGION") ?? "us-east-1",
+                endpoint: setting(env, "BLOB_S3_ENDPOINT"),
+                forcePathStyle: setting(env, "BLOB_S3_FORCE_PATH_STYLE") === "true",
+                credentials: accessKeyId && secretAccessKey ? { accessKeyId, secretAccessKey } : undefined,
+            }),
+        };
+        return loaded;
+    };
+    return {
+        async putObject(input) {
+            const { sdk, client } = await connect();
+            return client.send(new sdk.PutObjectCommand(input));
+        },
+        async headObject(input) {
+            const { sdk, client } = await connect();
+            return client.send(new sdk.HeadObjectCommand(input));
+        },
+        async deleteObject(input) {
+            const { sdk, client } = await connect();
+            return client.send(new sdk.DeleteObjectCommand(input));
+        },
+        async listObjectsV2(input) {
+            const { sdk, client } = await connect();
+            return client.send(new sdk.ListObjectsV2Command(input));
+        },
+    };
+}
+/** Translate only absence of this optional peer; preserve broken SDKs and other failures. */
+function peerMissing(cause) {
+    if (cause instanceof Error && "code" in cause
+        && (cause.code === "ERR_MODULE_NOT_FOUND" || cause.code === "MODULE_NOT_FOUND")
+        && /^Cannot find (?:package|module) ['"]@aws-sdk\/client-s3['"]/.test(cause.message)) {
+        throw new Error("OPENLUP_E_PEER_MISSING: @aws-sdk/client-s3 is required by the S3 blob capability; install it alongside @openlup/platform", { cause });
+    }
+    throw cause;
+}

package/dist/blob/supabase.d.ts

@@ -0,0 +1,40 @@
+import type { BlobStoragePort } from "@openlup/core/platform-runtime";
+/** Minimal structural shape of the Supabase Storage bucket API we depend on. */
+export interface SupabaseStorageBucket {
+    upload(path: string, bytes: Uint8Array | Buffer, options?: {
+        contentType?: string;
+        upsert?: boolean;
+    }): PromiseLike<{
+        data: unknown;
+        error: {
+            message?: string;
+        } | null;
+    }>;
+    remove(paths: string[]): PromiseLike<{
+        data: unknown;
+        error: {
+            message?: string;
+        } | null;
+    }>;
+    list(prefix?: string): PromiseLike<{
+        data: Array<{
+            name: string;
+        }> | null;
+        error: {
+            message?: string;
+        } | null;
+    }>;
+    getPublicUrl(path: string): {
+        data: {
+            publicUrl: string;
+        };
+    };
+}
+export interface SupabaseStorageClient {
+    storage: {
+        from(bucket: string): SupabaseStorageBucket;
+    };
+}
+export declare function createSupabaseBlobStorage(client: SupabaseStorageClient, bucket: string, options?: {
+    defaultContentType?: string;
+}): BlobStoragePort;