@saacms/storage-r2 0.1.0

package/README.md

@@ -0,0 +1,31 @@
+# @saacms/storage-r2
+
+Cloudflare R2 storage adapter for saacms. Implements the `StorageAdapter` interface (`{ put, get, delete, signedUrl }`) over a Workers `R2Bucket` binding, for use by Media Collections in `bucket` storage mode.
+
+See [ADR 0009 — Media as Collection kind](../../docs/adr/0009-media-as-collection-kind.md) for the storage-adapter interface and the bucket vs repo modes, and [ADR 0024 — v1 alpha scope](../../docs/adr/0024-v1-alpha-scope-astro-cloudflare.md) for why R2 is the v1 default bucket.
+
+## Status
+
+Scaffold. The `put` / `get` / `delete` operations forward to the `R2Bucket` binding the host passes in. `signedUrl` returns a public URL when `publicBaseUrl` is configured; pre-signed URL generation (AWS SigV4 over R2's S3 endpoint, via `aws4fetch`) is deferred until ADR 0009's open question on transform URL syntax is resolved.
+
+## Usage (target shape)
+
+```ts
+// saacms.config.ts
+import { defineConfig } from "saacms"
+import { r2Adapter } from "@saacms/storage-r2"
+
+export default defineConfig({
+  storage: r2Adapter({
+    bucket: env.SAACMS_MEDIA, // R2Bucket binding from wrangler.toml
+    prefix: "media/",
+    publicBaseUrl: "https://cdn.example.com",
+  }),
+})
+```
+
+The `bucket` field is the Workers R2 binding object — saacms doesn't open the binding for you; the host (Astro on Cloudflare Pages, per ADR 0024) injects it from `wrangler.toml`.
+
+## Known reconciliation TODO
+
+The local `StorageAdapter` interface in `src/r2-adapter.ts` is a copy with TODO. Replace with `import type { StorageAdapter } from "@saacms/core"` once the cross-package contract test (per ADR 0019) is wired up to enforce conformance.

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @saacms/storage-r2 — public surface.
+ *
+ * Cloudflare R2 implementation of the saacms `StorageAdapter` interface
+ * (per ADR 0009 § 3 — bucket-mode storage adapters expose `{ put, get, delete, signedUrl }`).
+ *
+ * v1 alpha status: scaffold. `put` / `get` / `delete` forward to the Workers
+ * `R2Bucket` binding the host passes in; `signedUrl` returns a public URL
+ * when `publicBaseUrl` is set, and throws `NOT_IMPLEMENTED` otherwise
+ * (ADR 0009 open question on transform URL syntax).
+ */
+export { r2Adapter } from "./r2-adapter.ts";
+export type { R2AdapterOpts, StorageAdapter, StorageError, SignedUrlOpts, } from "./r2-adapter.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAC3C,YAAY,EACV,aAAa,EACb,cAAc,EACd,YAAY,EACZ,aAAa,GACd,MAAM,iBAAiB,CAAA"}

package/dist/index.js

@@ -0,0 +1,56 @@
+// src/r2-adapter.ts
+class StorageError extends Error {
+  code;
+  cause;
+  name = "StorageError";
+  constructor(code, message, cause) {
+    super(message);
+    this.code = code;
+    this.cause = cause;
+  }
+}
+function r2Adapter(opts) {
+  const { bucket, prefix = "", publicBaseUrl } = opts;
+  const fullKey = (key) => prefix + key;
+  return {
+    async put(key, body, contentType) {
+      const k = fullKey(key);
+      try {
+        await bucket.put(k, body, {
+          httpMetadata: contentType !== undefined ? { contentType } : undefined
+        });
+        return { key: k };
+      } catch (cause) {
+        throw new StorageError("PUT_FAILED", `R2 put failed for key "${k}"`, cause);
+      }
+    },
+    async get(key) {
+      const k = fullKey(key);
+      try {
+        return await bucket.get(k);
+      } catch (cause) {
+        throw new StorageError("GET_FAILED", `R2 get failed for key "${k}"`, cause);
+      }
+    },
+    async delete(key) {
+      const k = fullKey(key);
+      try {
+        await bucket.delete(k);
+      } catch (cause) {
+        throw new StorageError("DELETE_FAILED", `R2 delete failed for key "${k}"`, cause);
+      }
+    },
+    async signedUrl(key, _opts) {
+      const k = fullKey(key);
+      if (publicBaseUrl !== undefined) {
+        const base = publicBaseUrl.replace(/\/+$/, "");
+        const path = k.replace(/^\/+/, "");
+        return `${base}/${path}`;
+      }
+      throw new StorageError("NOT_IMPLEMENTED", "signed URLs require AWS SigV4 (e.g. via aws4fetch); see ADR 0009 open question on transform URL syntax");
+    }
+  };
+}
+export {
+  r2Adapter
+};

package/dist/r2-adapter.d.ts

@@ -0,0 +1,94 @@
+/**
+ * R2 storage adapter — implements the saacms `StorageAdapter` interface
+ * over a Cloudflare Workers `R2Bucket` binding.
+ *
+ * Per ADR 0009 § 3, bucket-mode Media Collections delegate binary storage
+ * to a pluggable adapter exposing `{ put, get, delete, signedUrl }`. This
+ * is the v1 alpha R2 implementation (ADR 0024 — the only bucket adapter
+ * shipped at v1.0; `vercelBlobAdapter` and `s3Adapter` follow in v1.x).
+ *
+ * Workers API reference:
+ *   https://developers.cloudflare.com/r2/api/workers/workers-api-reference/
+ */
+/**
+ * The interface every saacms storage adapter implements.
+ *
+ * Defined locally for now; will move to `@saacms/core` (likely
+ * `@saacms/core/storage`) when that surface lands.
+ */
+export interface StorageAdapter {
+    /** Write a binary at the given key. Returns the canonical key (post-prefix). */
+    put(key: string, body: StorageBody, contentType?: string): Promise<{
+        key: string;
+    }>;
+    /** Fetch the object at the given key. Returns null when absent. */
+    get(key: string): Promise<R2ObjectBodyLike | null>;
+    /** Delete the object at the given key. Idempotent. */
+    delete(key: string): Promise<void>;
+    /** Resolve to a URL that serves the object. See implementation for v1 limitations. */
+    signedUrl(key: string, opts?: SignedUrlOpts): Promise<string>;
+}
+/** Body shapes accepted by `put`. Mirrors `R2Bucket.put`'s value parameter. */
+export type StorageBody = ReadableStream | ArrayBuffer | ArrayBufferView | string | null | Blob;
+export interface SignedUrlOpts {
+    /** Lifetime of the signed URL in seconds. v1 ignores this when `publicBaseUrl` is used. */
+    readonly expiresInSeconds?: number;
+    /** Force-download with this filename via `Content-Disposition`. v1 ignored. */
+    readonly downloadAs?: string;
+}
+/**
+ * Tagged error surface for storage operations. Bubbles up to the runtime
+ * which converts to RFC 9457 Problem Details (ADR 0018).
+ */
+export declare class StorageError extends Error {
+    readonly code: "PUT_FAILED" | "GET_FAILED" | "DELETE_FAILED" | "NOT_IMPLEMENTED" | "MISCONFIGURED";
+    readonly cause?: unknown | undefined;
+    readonly name = "StorageError";
+    constructor(code: "PUT_FAILED" | "GET_FAILED" | "DELETE_FAILED" | "NOT_IMPLEMENTED" | "MISCONFIGURED", message: string, cause?: unknown | undefined);
+}
+/** Subset of the `R2PutOptions` shape used by this adapter. */
+export interface R2PutOptionsLike {
+    readonly httpMetadata?: {
+        readonly contentType?: string;
+    };
+}
+/** Subset of `R2Object` returned by `put`. */
+export interface R2ObjectLike {
+    readonly key: string;
+}
+/** Subset of `R2ObjectBody` returned by `get`. */
+export interface R2ObjectBodyLike extends R2ObjectLike {
+    readonly body: ReadableStream | null;
+    arrayBuffer(): Promise<ArrayBuffer>;
+    text(): Promise<string>;
+}
+/** Subset of the `R2Bucket` binding used by this adapter. */
+export interface R2BucketLike {
+    put(key: string, value: StorageBody, options?: R2PutOptionsLike): Promise<R2ObjectLike | null>;
+    get(key: string): Promise<R2ObjectBodyLike | null>;
+    delete(key: string | string[]): Promise<void>;
+}
+export interface R2AdapterOpts {
+    /** The Workers `R2Bucket` binding; supplied by the host (e.g. `env.SAACMS_MEDIA`). */
+    readonly bucket: R2BucketLike;
+    /** Optional key prefix (e.g. `"media/"`). Joined verbatim — caller controls trailing slash. */
+    readonly prefix?: string;
+    /**
+     * Optional public base URL for served objects (e.g. `https://cdn.example.com`).
+     * When set, `signedUrl` returns `${publicBaseUrl}/${prefix}${key}` (with
+     * any duplicate slashes collapsed). When unset, `signedUrl` throws
+     * `NOT_IMPLEMENTED` until pre-signed AWS SigV4 URL generation lands
+     * (ADR 0009 open question on transform URL syntax).
+     */
+    readonly publicBaseUrl?: string;
+}
+/**
+ * Build an R2-backed `StorageAdapter`.
+ *
+ * The `bucket` field is the live Workers binding; this factory does not
+ * open it. On Cloudflare Pages with `@saacms/host-astro`, the host injects
+ * the binding declared in `wrangler.toml` (per ADR 0024 § "R2 binding
+ * name convention" — likely `SAACMS_MEDIA`).
+ */
+export declare function r2Adapter(opts: R2AdapterOpts): StorageAdapter;
+//# sourceMappingURL=r2-adapter.d.ts.map

package/dist/r2-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"r2-adapter.d.ts","sourceRoot":"","sources":["../src/r2-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,gFAAgF;IAChF,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IACnF,mEAAmE;IACnE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAA;IAClD,sDAAsD;IACtD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAClC,sFAAsF;IACtF,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;CAC9D;AAED,+EAA+E;AAC/E,MAAM,MAAM,WAAW,GACnB,cAAc,GACd,WAAW,GACX,eAAe,GACf,MAAM,GACN,IAAI,GACJ,IAAI,CAAA;AAER,MAAM,WAAW,aAAa;IAC5B,2FAA2F;IAC3F,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;IAClC,+EAA+E;IAC/E,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAC7B;AAED;;;GAGG;AACH,qBAAa,YAAa,SAAQ,KAAK;IAGnC,QAAQ,CAAC,IAAI,EACT,YAAY,GACZ,YAAY,GACZ,eAAe,GACf,iBAAiB,GACjB,eAAe;IAEnB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO;IAT1B,SAAkB,IAAI,kBAAiB;gBAE5B,IAAI,EACT,YAAY,GACZ,YAAY,GACZ,eAAe,GACf,iBAAiB,GACjB,eAAe,EACnB,OAAO,EAAE,MAAM,EACN,KAAK,CAAC,EAAE,OAAO,YAAA;CAI3B;AAgBD,+DAA+D;AAC/D,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,YAAY,CAAC,EAAE;QAAE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAC1D;AAED,8CAA8C;AAC9C,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CACrB;AAED,kDAAkD;AAClD,MAAM,WAAW,gBAAiB,SAAQ,YAAY;IACpD,QAAQ,CAAC,IAAI,EAAE,cAAc,GAAG,IAAI,CAAA;IACpC,WAAW,IAAI,OAAO,CAAC,WAAW,CAAC,CAAA;IACnC,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAA;CACxB;AAED,6DAA6D;AAC7D,MAAM,WAAW,YAAY;IAC3B,GAAG,CACD,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,WAAW,EAClB,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAA;IAC/B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAA;IAClD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC9C;AAMD,MAAM,WAAW,aAAa;IAC5B,sFAAsF;IACtF,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAA;IAC7B,+FAA+F;IAC/F,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB;;;;;;OAMG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAChC;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,aAAa,GAAG,cAAc,CA+D7D"}

package/dist/r2-adapter.js

@@ -0,0 +1,81 @@
+/**
+ * R2 storage adapter — implements the saacms `StorageAdapter` interface
+ * over a Cloudflare Workers `R2Bucket` binding.
+ *
+ * Per ADR 0009 § 3, bucket-mode Media Collections delegate binary storage
+ * to a pluggable adapter exposing `{ put, get, delete, signedUrl }`. This
+ * is the v1 alpha R2 implementation (ADR 0024 — the only bucket adapter
+ * shipped at v1.0; `vercelBlobAdapter` and `s3Adapter` follow in v1.x).
+ *
+ * Workers API reference:
+ *   https://developers.cloudflare.com/r2/api/workers/workers-api-reference/
+ */
+/**
+ * Tagged error surface for storage operations. Bubbles up to the runtime
+ * which converts to RFC 9457 Problem Details (ADR 0018).
+ */
+export class StorageError extends Error {
+    code;
+    cause;
+    name = "StorageError";
+    constructor(code, message, cause) {
+        super(message);
+        this.code = code;
+        this.cause = cause;
+    }
+}
+/**
+ * Build an R2-backed `StorageAdapter`.
+ *
+ * The `bucket` field is the live Workers binding; this factory does not
+ * open it. On Cloudflare Pages with `@saacms/host-astro`, the host injects
+ * the binding declared in `wrangler.toml` (per ADR 0024 § "R2 binding
+ * name convention" — likely `SAACMS_MEDIA`).
+ */
+export function r2Adapter(opts) {
+    const { bucket, prefix = "", publicBaseUrl } = opts;
+    const fullKey = (key) => prefix + key;
+    return {
+        async put(key, body, contentType) {
+            const k = fullKey(key);
+            try {
+                await bucket.put(k, body, {
+                    httpMetadata: contentType !== undefined ? { contentType } : undefined,
+                });
+                return { key: k };
+            }
+            catch (cause) {
+                throw new StorageError("PUT_FAILED", `R2 put failed for key "${k}"`, cause);
+            }
+        },
+        async get(key) {
+            const k = fullKey(key);
+            try {
+                return await bucket.get(k);
+            }
+            catch (cause) {
+                throw new StorageError("GET_FAILED", `R2 get failed for key "${k}"`, cause);
+            }
+        },
+        async delete(key) {
+            const k = fullKey(key);
+            try {
+                await bucket.delete(k);
+            }
+            catch (cause) {
+                throw new StorageError("DELETE_FAILED", `R2 delete failed for key "${k}"`, cause);
+            }
+        },
+        async signedUrl(key, _opts) {
+            const k = fullKey(key);
+            if (publicBaseUrl !== undefined) {
+                // Collapse duplicate slashes between segments. We trust the caller's
+                // base URL otherwise (no protocol re-write, no normalisation).
+                const base = publicBaseUrl.replace(/\/+$/, "");
+                const path = k.replace(/^\/+/, "");
+                return `${base}/${path}`;
+            }
+            throw new StorageError("NOT_IMPLEMENTED", "signed URLs require AWS SigV4 (e.g. via aws4fetch); see ADR 0009 open question on transform URL syntax");
+        },
+    };
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@saacms/storage-r2",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc --build",
+    "typecheck": "tsc --build --noEmit",
+    "prepack": "cp package.json package.json.pack-bak && bun run ../../scripts/prepack-pkg.ts",
+    "postpack": "mv package.json.pack-bak package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@saacms/core": "workspace:*",
+    "@cloudflare/workers-types": "^4.20240925.0"
+  },
+  "peerDependencies": {
+    "aws4fetch": "^1.0.20"
+  },
+  "peerDependenciesMeta": {
+    "aws4fetch": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.7.0"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts"
+}