@openlup/platform 0.0.0 → 0.15.0

package/sql/20260809150001_job_run_ledger_v3.sql

@@ -0,0 +1,70 @@
+-- Job-run ledger v3 entry points: invocation-aware claim and finish.
+--
+-- Applies after 20260809150000_job_run_ledger.sql, whose v2 claim and finish these delegate to.
+-- The trigger kind and invocation source are evidence folded into the run metadata, never an
+-- authorization control. CREATE OR REPLACE lets a database whose own migration chain already
+-- defines these functions with the same bodies apply this file without change.
+
+CREATE OR REPLACE FUNCTION public.platform_claim_job_run_v3(
+  p_job_name text,
+  p_trigger_kind text,
+  p_invocation_source text,
+  p_lease_seconds integer DEFAULT 900,
+  p_metadata jsonb DEFAULT '{}'::jsonb
+)
+RETURNS TABLE (
+  acquired boolean,
+  run_id uuid,
+  reason text,
+  lease_until timestamptz
+)
+LANGUAGE plpgsql
+SET search_path = public, pg_catalog
+AS $$
+DECLARE
+  v_trigger_kind text := COALESCE(NULLIF(btrim(p_trigger_kind), ''), '');
+  v_invocation_source text := COALESCE(NULLIF(btrim(p_invocation_source), ''), '');
+BEGIN
+  IF p_job_name IS NULL OR btrim(p_job_name) = '' THEN
+    RAISE EXCEPTION 'platform_job_name_required' USING ERRCODE = '22023';
+  END IF;
+
+  IF v_trigger_kind NOT IN ('worker', 'scheduler', 'operator') THEN
+    RAISE EXCEPTION 'platform_job_invalid_trigger_kind' USING ERRCODE = '22023';
+  END IF;
+
+  IF v_invocation_source = '' OR length(v_invocation_source) > 128 THEN
+    RAISE EXCEPTION 'platform_job_invocation_source_required' USING ERRCODE = '22023';
+  END IF;
+
+  -- The invocation source is evidence, never an authorization control, so it is folded into
+  -- the metadata this ledger stores and never interprets.
+  RETURN QUERY
+  SELECT claimed.acquired, claimed.run_id, claimed.reason, claimed.lease_until
+    FROM public.platform_claim_job_run(
+      p_job_name,
+      v_trigger_kind,
+      p_lease_seconds,
+      COALESCE(p_metadata, '{}'::jsonb) || jsonb_build_object(
+        'triggerKind', v_trigger_kind, 'invocationSource', v_invocation_source)
+    ) AS claimed;
+END;
+$$;
+
+CREATE OR REPLACE FUNCTION public.platform_finish_job_run_v3(
+  p_job_name text,
+  p_run_id uuid,
+  p_status text,
+  p_checked integer DEFAULT NULL,
+  p_updated integer DEFAULT NULL,
+  p_error text DEFAULT NULL,
+  p_support_code text DEFAULT NULL,
+  p_metadata jsonb DEFAULT '{}'::jsonb
+)
+RETURNS boolean
+LANGUAGE sql
+SET search_path = public, pg_catalog
+AS $$
+  SELECT public.platform_finish_job_run_v2(
+    p_job_name, p_run_id, p_status, p_checked, p_updated, p_error, p_support_code, p_metadata);
+$$;

package/src/bff/dispatch.ts

@@ -0,0 +1,81 @@
+// BFF dispatch mechanism.
+//
+// The route table and its handlers belong to the deployment. This module owns the
+// platform-neutral matching loop, so every HttpRuntimePort adapter (a hosted function or the Node
+// runtime of this package) mounts the same route table without duplicating dispatch logic.
+//
+// Per request, in order: the deployment's `beforeDispatch` hook, path normalization, the first
+// matching route, its availability, its decoded path parameters, the deployment's `preflight`
+// hook, then the handler. An unmatched or unavailable path goes to the deployment's `notFound`.
+
+import type { HttpRequest, HttpResponse } from "../http/index.js";
+import { getBundleDescriptor, resolveBundleId } from "../kernel/index.js";
+
+export type RouteEntry = {
+  route: string;
+  pattern: RegExp;
+  params: string[];
+  handler: (req: HttpRequest, res: HttpResponse) => unknown;
+  /** Fail unsupported hosted bundles closed before auth without weakening direct-route auth. */
+  availability?: "direct-postgres";
+};
+
+/** Match `routes` against one request and run the handler, or answer not found. */
+export type BffDispatch = (
+  routes: readonly RouteEntry[],
+  req: HttpRequest,
+  res: HttpResponse,
+) => Promise<unknown>;
+
+export interface BffDispatcherOptions {
+  /** Environment read on each request to decide a route's bundle availability. */
+  env: () => Record<string, string | undefined>;
+  /** Writes the deployment's not-found response for an unmatched or unavailable path. */
+  notFound: (res: HttpResponse, pathname: string) => void;
+  /** Runs once per request before matching (for example, ambient request configuration). */
+  beforeDispatch?: () => void;
+  /**
+   * Runs after matching and before the handler, for example route authorization; resolving false
+   * means it already answered. Required, so no composition skips it by omission; a deployment
+   * without guarded routes passes `() => true`.
+   */
+  preflight: (req: HttpRequest, res: HttpResponse, route: string) => Promise<boolean> | boolean;
+}
+
+// Only the pathname is read, and it does not depend on the URL base; this host only completes a
+// request that carries no Host header.
+const FALLBACK_HOST = "bff.invalid";
+
+function requestPath(req: HttpRequest): string {
+  const rawUrl = typeof req.url === "string" ? req.url : "/";
+  const host = typeof req.headers?.host === "string" ? req.headers.host : FALLBACK_HOST;
+  return new URL(rawUrl, "https://" + host).pathname.replace(/\/+$/, "") || "/";
+}
+
+/** Build the dispatcher a deployment mounts on its hosted and Node entrypoints alike. */
+export function createBffDispatcher(options: BffDispatcherOptions): BffDispatch {
+  return async function dispatch(routes, req, res) {
+    options.beforeDispatch?.();
+    const pathname = requestPath(req);
+    for (const entry of routes) {
+      const match = entry.pattern.exec(pathname);
+      if (!match) continue;
+      if (entry.availability === "direct-postgres"
+        && getBundleDescriptor(resolveBundleId(options.env())).capabilities.data !== "postgres") {
+        options.notFound(res, pathname);
+        return undefined;
+      }
+      if (entry.params.length > 0) {
+        const query = { ...(req.query ?? {}) };
+        entry.params.forEach((param, index) => {
+          query[param] = decodeURIComponent(match[index + 1] ?? "");
+        });
+        req.query = query;
+      }
+      if (!(await options.preflight(req, res, entry.route))) return undefined;
+      return entry.handler(req, res);
+    }
+    options.notFound(res, pathname);
+    return undefined;
+  };
+}

package/src/bff/envelope.ts

@@ -0,0 +1,142 @@
+// 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.
+
+import type { HttpResponse } from "../http/index.js";
+
+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",
+] as const;
+
+export type BffErrorCode = (typeof BFF_ERROR_CODES)[number];
+
+export type BffMeta = { requestId?: string; contractVersion?: string; [key: string]: unknown };
+
+export type BffError = { code: BffErrorCode; message: string; details?: unknown };
+
+export type BffSuccessResponse<T> = { ok: true; data: T; meta?: BffMeta };
+
+export type BffErrorResponse = { ok: false; error: BffError; meta?: BffMeta };
+
+export type BffResponse<T> = BffSuccessResponse<T> | BffErrorResponse;
+
+/** The HTTP status each error code answers with unless the caller names another. */
+export const BFF_ERROR_STATUS: Readonly<Record<BffErrorCode, number>> = {
+  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,
+};
+
+export interface BffErrorOptions {
+  status?: number;
+  details?: unknown;
+  meta?: BffMeta;
+}
+
+export interface BffSuccessOptions {
+  cacheControl?: string;
+}
+
+export interface BffResponderOptions {
+  /** The request reference observed for this response, if the deployment records one. */
+  responseRequestId?: (res: HttpResponse) => string | undefined;
+}
+
+export interface BffResponder {
+  sendBffSuccess<T>(res: HttpResponse, data: T, meta?: BffMeta, options?: BffSuccessOptions): void;
+  sendBffError(res: HttpResponse, code: BffErrorCode, message: string, options?: BffErrorOptions): void;
+  sendMethodNotAllowed(res: HttpResponse, allowedMethods: readonly string[]): void;
+}
+
+/** Build the envelope writers a deployment's handlers share. */
+export function createBffResponder(options: BffResponderOptions = {}): BffResponder {
+  function sendBffSuccess<T>(
+    res: HttpResponse,
+    data: T,
+    meta?: BffMeta,
+    successOptions: BffSuccessOptions = {},
+  ): void {
+    sendJson(res, 200, { ok: true, data, meta }, successOptions.cacheControl);
+  }
+
+  function sendBffError(
+    res: HttpResponse,
+    code: BffErrorCode,
+    message: string,
+    errorOptions: BffErrorOptions = {},
+  ): void {
+    sendJson(res, errorOptions.status ?? BFF_ERROR_STATUS[code], {
+      ok: false,
+      error: { code, message, details: errorOptions.details },
+      meta: errorOptions.meta,
+    });
+  }
+
+  function sendMethodNotAllowed(res: HttpResponse, allowedMethods: readonly string[]): void {
+    res.setHeader("Allow", allowedMethods.join(", "));
+    sendBffError(res, "METHOD_NOT_ALLOWED", "Method not allowed", { status: 405 });
+  }
+
+  function sendJson<T>(
+    res: HttpResponse,
+    status: number,
+    body: BffResponse<T>,
+    cacheControl = "no-store",
+  ): void {
+    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<T>(
+  body: BffResponse<T>,
+  requestId: string | undefined,
+  omitRequestId: boolean,
+): BffResponse<T> {
+  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: unknown): unknown {
+  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/src/bff/health.ts

@@ -0,0 +1,37 @@
+// 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.
+
+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 function createHealthHandler<T extends { contractVersion: string }>(
+  options: HealthHandlerOptions<T>,
+): (req: HttpRequest, res: HttpResponse) => void {
+  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/src/bff/index.ts

@@ -0,0 +1,30 @@
+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/src/bff/lazyRoute.ts

@@ -0,0 +1,28 @@
+// Loads a BFF route module on its first request instead of at cold start.
+//
+// A route table binds each route as `lazyBffRoute(() => import("<specifier>"))`, so the
+// specifier stays a static literal that bundlers and inventories can read, and the load's type
+// keeps every module's default export checked against `RouteEntry["handler"]`.
+//
+// Concurrent first calls share one load. A rejected load is not kept: the requests that awaited
+// it reject as a throwing handler does, and the next request loads again. A module that threw
+// during evaluation stays errored in Node's ESM loader; the retry helps only a failure before
+// evaluation (a missing file or a read error). Once loaded, the module's handler is called
+// synchronously and its result returned.
+import type { RouteEntry } from "./dispatch.js";
+
+export function lazyBffRoute(load: () => Promise<{ default: RouteEntry["handler"] }>): RouteEntry["handler"] {
+  let handler: RouteEntry["handler"] | undefined;
+  let loading: Promise<RouteEntry["handler"]> | undefined;
+  return (req, res) => {
+    if (handler) return handler(req, res);
+    loading ??= load().then(
+      (module) => (handler = module.default),
+      (error: unknown) => {
+        loading = undefined;
+        throw error;
+      },
+    );
+    return loading.then((loaded) => loaded(req, res));
+  };
+}

package/src/bff/requestContext.ts

@@ -0,0 +1,48 @@
+// 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.
+
+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 function createRequestContextStore(options: RequestContextOptions): RequestContextStore {
+  const requestContexts = new WeakMap<HttpRequest, ObservedRequestContext>();
+  const responseContexts = new WeakMap<HttpResponse, ObservedRequestContext>();
+
+  function readOrCreate(req: HttpRequest): ObservedRequestContext {
+    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/src/bff/routerRewrite.ts

@@ -0,0 +1,38 @@
+// 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.
+
+import type { HttpRequest } from "../http/index.js";
+
+const INTERNAL_BFF_PATH_QUERY = "__bffPath";
+
+function firstQueryValue(value: string | string[] | undefined): string | null {
+  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: HttpRequest): void {
+  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/src/blob/binding.ts

@@ -0,0 +1,55 @@
+// 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 type { BlobStoragePort } from "@openlup/core/platform-runtime";
+
+import { createFilesystemBlobStorage } from "./filesystem.js";
+import { createS3BlobStorage, type S3ObjectClient } from "./s3.js";
+import { createS3ClientFromEnv } from "./s3Client.js";
+import { createSupabaseBlobStorage, type SupabaseStorageClient } from "./supabase.js";
+import { createVercelBlobStorage, 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 function bindBlobPort(
+  blobKind: string,
+  env: Env,
+  deps: BlobBindingDeps = {},
+): BlobStoragePort | null {
+  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/src/blob/filesystem.ts

@@ -0,0 +1,86 @@
+// 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";
+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 function createFilesystemBlobStorage(options: FilesystemBlobOptions): BlobStoragePort {
+  const root = resolve(options.root);
+  const baseUrl = options.baseUrl.replace(/\/$/, "");
+
+  const pathFor = (key: string): string => {
+    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: string): string {
+      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: NodeJS.ErrnoException) => {
+        if (error.code === "ENOENT") return [];
+        throw error;
+      });
+      return {
+        keys: keys.map((absolute) => relative(root, absolute).split(sep).join("/")).sort(),
+      };
+    },
+  };
+}
+
+function normalizeKey(key: string): string {
+  return key.replace(/^\/+/, "");
+}
+
+function stripBaseUrl(keyOrUrl: string, baseUrl: string): string {
+  return keyOrUrl.startsWith(`${baseUrl}/`) ? keyOrUrl.slice(baseUrl.length + 1) : keyOrUrl;
+}
+
+async function walk(dir: string): Promise<string[]> {
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+  const out: string[] = [];
+  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/src/blob/index.ts

@@ -0,0 +1,17 @@
+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";