@voyant-travel/storage 0.104.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may accept and charge a
+      fee for, the acceptance of support, warranty, indemnity, or
+      other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 PixelMakers Studio SRL
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,50 @@
+# @voyant-travel/storage
+
+Storage provider abstraction for Voyant. `StorageProvider` interface plus providers for local (in-memory), Cloudflare R2, and S3-compatible (AWS SigV4 via Web Crypto — works in Cloudflare Workers).
+
+## Install
+
+```bash
+pnpm add @voyant-travel/storage
+```
+
+## Usage
+
+```typescript
+import { createStorageService } from "@voyant-travel/storage"
+import { s3Provider } from "@voyant-travel/storage/providers/s3"
+
+const storage = createStorageService(
+  s3Provider({
+    region: "us-east-1",
+    bucket: "my-bucket",
+    accessKeyId: env.AWS_ACCESS_KEY_ID,
+    secretAccessKey: env.AWS_SECRET_ACCESS_KEY,
+  }),
+)
+
+await storage.upload({ key: "files/x.pdf", body: buffer })
+const url = await storage.signedUrl({ key: "files/x.pdf", expiresIn: 300 })
+```
+
+The S3 provider supports `forcePathStyle` and a custom `endpoint` for S3-compatible services (Wasabi, MinIO, etc.). SigV4 signing is verified against AWS canonical test vectors.
+
+The R2 binding provider cannot mint signed URLs by itself. Configure either
+`publicBaseUrl` or a custom `signer` before calling `signedUrl`; otherwise the
+provider throws instead of returning a raw storage key.
+
+## Exports
+
+| Entry | Description |
+| --- | --- |
+| `.` | Barrel re-exports |
+| `./types` | `StorageProvider` interface |
+| `./service` | `createStorageService` |
+| `./providers/local` | In-memory provider |
+| `./providers/r2` | Cloudflare R2 binding provider |
+| `./providers/s3` | S3 provider with SigV4 |
+| `./lib/sigv4` | `signRequest`, `presignUrl` primitives |
+
+## License
+
+Apache-2.0

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export type { PresignUrlInput, SignedRequestHeaders, SignRequestInput, SigV4Context, SigV4Credentials, } from "./lib/sigv4.js";
+export { presignUrl, signRequest } from "./lib/sigv4.js";
+export type { LocalStorageOptions } from "./providers/local.js";
+export { createLocalStorageProvider } from "./providers/local.js";
+export type { R2BucketLike, R2ObjectLike, R2ProviderOptions, R2PutOptionsLike, } from "./providers/r2.js";
+export { createR2Provider } from "./providers/r2.js";
+export type { S3Fetch, S3ProviderOptions } from "./providers/s3.js";
+export { createS3Provider } from "./providers/s3.js";
+export type { StorageService } from "./service.js";
+export { createStorageService, StorageError } from "./service.js";
+export type { StorageObject, StorageProvider, StorageUploadBody, UploadOptions, } from "./types.js";
+//# 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,YAAY,EACV,eAAe,EACf,oBAAoB,EACpB,gBAAgB,EAChB,YAAY,EACZ,gBAAgB,GACjB,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AACxD,YAAY,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAA;AAC/D,OAAO,EAAE,0BAA0B,EAAE,MAAM,sBAAsB,CAAA;AACjE,YAAY,EACV,YAAY,EACZ,YAAY,EACZ,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA;AACpD,YAAY,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AACnE,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA;AACpD,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAClD,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AACjE,YAAY,EACV,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,aAAa,GACd,MAAM,YAAY,CAAA"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export { presignUrl, signRequest } from "./lib/sigv4.js";
+export { createLocalStorageProvider } from "./providers/local.js";
+export { createR2Provider } from "./providers/r2.js";
+export { createS3Provider } from "./providers/s3.js";
+export { createStorageService, StorageError } from "./service.js";

package/dist/lib/sigv4.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Minimal AWS SigV4 signing implementation using Web Crypto. Works in
+ * Cloudflare Workers, modern Node, Deno, and browsers.
+ *
+ * Supports two use cases needed by the S3 storage provider:
+ * - `signRequest`: attach an `Authorization` header for a direct request
+ * - `presignUrl`: produce a time-limited URL via query-string signing
+ *
+ * Reference:
+ * https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv_create-signed-request.html
+ */
+export interface SigV4Credentials {
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken?: string;
+}
+export interface SigV4Context {
+    credentials: SigV4Credentials;
+    region: string;
+    service: string;
+}
+export interface SignRequestInput extends SigV4Context {
+    method: string;
+    url: string;
+    headers?: Record<string, string>;
+    body?: Uint8Array;
+    /** Override "now" (milliseconds since epoch). Useful for tests. */
+    now?: number;
+}
+export interface SignedRequestHeaders {
+    headers: Record<string, string>;
+}
+export interface PresignUrlInput extends SigV4Context {
+    method: string;
+    url: string;
+    expiresIn: number;
+    /** Extra signed headers beyond the default `host`. */
+    headers?: Record<string, string>;
+    /** Override "now" (milliseconds since epoch). Useful for tests. */
+    now?: number;
+}
+/**
+ * Sign a request and return the `Authorization` (and related) headers.
+ */
+export declare function signRequest(input: SignRequestInput): Promise<SignedRequestHeaders>;
+/**
+ * Produce a presigned URL (query-string signing) for the given method.
+ */
+export declare function presignUrl(input: PresignUrlInput): Promise<string>;
+//# sourceMappingURL=sigv4.d.ts.map

package/dist/lib/sigv4.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sigv4.d.ts","sourceRoot":"","sources":["../../src/lib/sigv4.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAA;IACnB,eAAe,EAAE,MAAM,CAAA;IACvB,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,gBAAgB,CAAA;IAC7B,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,gBAAiB,SAAQ,YAAY;IACpD,MAAM,EAAE,MAAM,CAAA;IACd,GAAG,EAAE,MAAM,CAAA;IACX,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC,IAAI,CAAC,EAAE,UAAU,CAAA;IACjB,mEAAmE;IACnE,GAAG,CAAC,EAAE,MAAM,CAAA;CACb;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAChC;AAED,MAAM,WAAW,eAAgB,SAAQ,YAAY;IACnD,MAAM,EAAE,MAAM,CAAA;IACd,GAAG,EAAE,MAAM,CAAA;IACX,SAAS,EAAE,MAAM,CAAA;IACjB,sDAAsD;IACtD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC,mEAAmE;IACnE,GAAG,CAAC,EAAE,MAAM,CAAA;CACb;AAED;;GAEG;AACH,wBAAsB,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAqDxF;AAED;;GAEG;AACH,wBAAsB,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC,CAgDxE"}

package/dist/lib/sigv4.js

@@ -0,0 +1,165 @@
+/**
+ * Minimal AWS SigV4 signing implementation using Web Crypto. Works in
+ * Cloudflare Workers, modern Node, Deno, and browsers.
+ *
+ * Supports two use cases needed by the S3 storage provider:
+ * - `signRequest`: attach an `Authorization` header for a direct request
+ * - `presignUrl`: produce a time-limited URL via query-string signing
+ *
+ * Reference:
+ * https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv_create-signed-request.html
+ */
+const encoder = new TextEncoder();
+/**
+ * Sign a request and return the `Authorization` (and related) headers.
+ */
+export async function signRequest(input) {
+    const { amzDate, dateStamp } = datesFromNow(input.now);
+    const url = new URL(input.url);
+    const bodyBytes = input.body ?? new Uint8Array();
+    const payloadHash = await hexHash(bodyBytes);
+    const baseHeaders = {
+        ...(input.headers ?? {}),
+        host: url.host,
+        "x-amz-date": amzDate,
+        "x-amz-content-sha256": payloadHash,
+    };
+    if (input.credentials.sessionToken) {
+        baseHeaders["x-amz-security-token"] = input.credentials.sessionToken;
+    }
+    const canonicalQuery = canonicalQueryString(url);
+    const { canonicalHeaders, signedHeaders } = canonicalizeHeaders(baseHeaders);
+    const canonicalRequest = [
+        input.method.toUpperCase(),
+        canonicalUri(url.pathname),
+        canonicalQuery,
+        canonicalHeaders,
+        signedHeaders,
+        payloadHash,
+    ].join("\n");
+    const scope = `${dateStamp}/${input.region}/${input.service}/aws4_request`;
+    const stringToSign = [
+        "AWS4-HMAC-SHA256",
+        amzDate,
+        scope,
+        await hexHash(encoder.encode(canonicalRequest)),
+    ].join("\n");
+    const signingKey = await deriveSigningKey(input.credentials.secretAccessKey, dateStamp, input.region, input.service);
+    const signature = hex(await hmac(signingKey, stringToSign));
+    const authHeader = `AWS4-HMAC-SHA256 Credential=${input.credentials.accessKeyId}/${scope}` +
+        `, SignedHeaders=${signedHeaders}, Signature=${signature}`;
+    return {
+        headers: {
+            ...baseHeaders,
+            Authorization: authHeader,
+        },
+    };
+}
+/**
+ * Produce a presigned URL (query-string signing) for the given method.
+ */
+export async function presignUrl(input) {
+    const { amzDate, dateStamp } = datesFromNow(input.now);
+    const url = new URL(input.url);
+    const scope = `${dateStamp}/${input.region}/${input.service}/aws4_request`;
+    const headers = {
+        ...(input.headers ?? {}),
+        host: url.host,
+    };
+    const { canonicalHeaders, signedHeaders } = canonicalizeHeaders(headers);
+    const params = new URLSearchParams(url.searchParams);
+    params.set("X-Amz-Algorithm", "AWS4-HMAC-SHA256");
+    params.set("X-Amz-Credential", `${input.credentials.accessKeyId}/${scope}`);
+    params.set("X-Amz-Date", amzDate);
+    params.set("X-Amz-Expires", String(input.expiresIn));
+    params.set("X-Amz-SignedHeaders", signedHeaders);
+    if (input.credentials.sessionToken) {
+        params.set("X-Amz-Security-Token", input.credentials.sessionToken);
+    }
+    url.search = params.toString();
+    const canonicalRequest = [
+        input.method.toUpperCase(),
+        canonicalUri(url.pathname),
+        canonicalQueryString(url),
+        canonicalHeaders,
+        signedHeaders,
+        "UNSIGNED-PAYLOAD",
+    ].join("\n");
+    const stringToSign = [
+        "AWS4-HMAC-SHA256",
+        amzDate,
+        scope,
+        await hexHash(encoder.encode(canonicalRequest)),
+    ].join("\n");
+    const signingKey = await deriveSigningKey(input.credentials.secretAccessKey, dateStamp, input.region, input.service);
+    const signature = hex(await hmac(signingKey, stringToSign));
+    params.set("X-Amz-Signature", signature);
+    url.search = params.toString();
+    return url.toString();
+}
+// --- helpers --- //
+function datesFromNow(nowMs) {
+    const d = new Date(nowMs ?? Date.now());
+    const iso = d.toISOString().replace(/[:-]|\.\d{3}/g, "");
+    // iso is like "20251005T223045Z"
+    return { amzDate: iso, dateStamp: iso.slice(0, 8) };
+}
+function canonicalUri(path) {
+    // S3 keys should be path-encoded but preserve "/"
+    if (!path)
+        return "/";
+    return path
+        .split("/")
+        .map((segment) => encodeRfc3986(segment))
+        .join("/");
+}
+function canonicalQueryString(url) {
+    const pairs = [];
+    for (const [key, value] of url.searchParams.entries()) {
+        pairs.push([encodeRfc3986(key), encodeRfc3986(value)]);
+    }
+    pairs.sort((a, b) => (a[0] === b[0] ? (a[1] < b[1] ? -1 : 1) : a[0] < b[0] ? -1 : 1));
+    return pairs.map(([k, v]) => `${k}=${v}`).join("&");
+}
+function canonicalizeHeaders(headers) {
+    const entries = Object.entries(headers)
+        .map(([k, v]) => [k.toLowerCase(), v.trim().replace(/\s+/g, " ")])
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    const canonicalHeaders = `${entries.map(([k, v]) => `${k}:${v}`).join("\n")}\n`;
+    const signedHeaders = entries.map(([k]) => k).join(";");
+    return { canonicalHeaders, signedHeaders };
+}
+function encodeRfc3986(value) {
+    return encodeURIComponent(value).replace(/[!'()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
+}
+async function hexHash(data) {
+    const copy = new Uint8Array(data.byteLength);
+    copy.set(data);
+    const digest = await crypto.subtle.digest("SHA-256", copy);
+    return hex(digest);
+}
+async function hmac(key, data) {
+    const source = key instanceof Uint8Array ? key : new Uint8Array(key);
+    const keyBytes = new Uint8Array(source.byteLength);
+    keyBytes.set(source);
+    const cryptoKey = await crypto.subtle.importKey("raw", keyBytes, { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    const payloadSource = encoder.encode(data);
+    const payload = new Uint8Array(payloadSource.byteLength);
+    payload.set(payloadSource);
+    return crypto.subtle.sign("HMAC", cryptoKey, payload);
+}
+async function deriveSigningKey(secret, dateStamp, region, service) {
+    const kDate = await hmac(encoder.encode(`AWS4${secret}`), dateStamp);
+    const kRegion = await hmac(kDate, region);
+    const kService = await hmac(kRegion, service);
+    const kSigning = await hmac(kService, "aws4_request");
+    return kSigning;
+}
+function hex(buffer) {
+    const bytes = new Uint8Array(buffer);
+    let out = "";
+    for (const b of bytes) {
+        out += b.toString(16).padStart(2, "0");
+    }
+    return out;
+}

package/dist/providers/local.d.ts

@@ -0,0 +1,26 @@
+import type { StorageProvider } from "../types.js";
+/**
+ * Options for {@link createLocalStorageProvider}.
+ */
+export interface LocalStorageOptions {
+    /** Provider name (defaults to `"local"`). */
+    name?: string;
+    /**
+     * Base URL used to construct the string returned from `signedUrl` and
+     * `upload`. Defaults to `"local://"`. The final URL is `${baseUrl}${key}`.
+     */
+    baseUrl?: string;
+    /**
+     * Function used to mint random keys when `UploadOptions.key` is not
+     * provided. Defaults to `crypto.randomUUID()` via the global `crypto`.
+     */
+    generateKey?: () => string;
+}
+/**
+ * Create an in-memory storage provider. Useful for unit tests and for
+ * locally running workflows without touching remote storage. Data is
+ * kept in a `Map` held inside the closure and is lost when the process
+ * exits.
+ */
+export declare function createLocalStorageProvider(options?: LocalStorageOptions): StorageProvider;
+//# sourceMappingURL=local.d.ts.map

package/dist/providers/local.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local.d.ts","sourceRoot":"","sources":["../../src/providers/local.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiB,eAAe,EAAoC,MAAM,aAAa,CAAA;AAEnG;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,6CAA6C;IAC7C,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,MAAM,CAAA;CAC3B;AAQD;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,GAAE,mBAAwB,GAAG,eAAe,CAwC7F"}

package/dist/providers/local.js

@@ -0,0 +1,54 @@
+/**
+ * Create an in-memory storage provider. Useful for unit tests and for
+ * locally running workflows without touching remote storage. Data is
+ * kept in a `Map` held inside the closure and is lost when the process
+ * exits.
+ */
+export function createLocalStorageProvider(options = {}) {
+    const name = options.name ?? "local";
+    const baseUrl = options.baseUrl ?? "local://";
+    const generateKey = options.generateKey ??
+        (() => {
+            const g = globalThis;
+            return g.crypto?.randomUUID?.() ?? `${Date.now()}-${Math.random().toString(36).slice(2)}`;
+        });
+    const store = new Map();
+    async function upload(body, opts = {}) {
+        const key = opts.key ?? generateKey();
+        const bytes = await toBytes(body);
+        const record = { bytes };
+        if (opts.contentType !== undefined)
+            record.contentType = opts.contentType;
+        if (opts.metadata !== undefined)
+            record.metadata = opts.metadata;
+        store.set(key, record);
+        return { key, url: `${baseUrl}${key}` };
+    }
+    return {
+        name,
+        upload,
+        async delete(key) {
+            store.delete(key);
+        },
+        async signedUrl(key) {
+            return `${baseUrl}${key}`;
+        },
+        async get(key) {
+            const record = store.get(key);
+            if (!record)
+                return null;
+            // Copy into a fresh ArrayBuffer so downstream mutation can't corrupt the store.
+            const copy = new Uint8Array(record.bytes.byteLength);
+            copy.set(record.bytes);
+            return copy.buffer;
+        },
+    };
+}
+async function toBytes(body) {
+    if (body instanceof Uint8Array)
+        return body;
+    if (body instanceof ArrayBuffer)
+        return new Uint8Array(body);
+    const buffer = await body.arrayBuffer();
+    return new Uint8Array(buffer);
+}

package/dist/providers/r2.d.ts

@@ -0,0 +1,71 @@
+import type { StorageProvider } from "../types.js";
+export declare const R2_SIGNED_URL_CONFIGURATION_ERROR_MESSAGE = "R2 provider: signedUrl requires a `signer` to be configured \u2014 a public base URL cannot produce a time-limited URL. Use publicUrl(key) for permanent public URLs, or configure a signer (e.g. R2's S3-compatible API with SigV4 credentials).";
+/**
+ * Subset of the Cloudflare Workers `R2Bucket` binding we depend on. Kept
+ * as a minimal structural type so this package does not need a runtime
+ * dependency on `@cloudflare/workers-types`.
+ */
+export interface R2BucketLike {
+    put(key: string, value: ArrayBuffer | ArrayBufferView | Blob | string | ReadableStream | null, options?: R2PutOptionsLike): Promise<unknown>;
+    delete(key: string | string[]): Promise<void>;
+    get(key: string): Promise<R2ObjectLike | null>;
+}
+export interface R2PutOptionsLike {
+    httpMetadata?: {
+        contentType?: string;
+    };
+    customMetadata?: Record<string, string>;
+}
+export interface R2ObjectLike {
+    arrayBuffer(): Promise<ArrayBuffer>;
+}
+/**
+ * Options for {@link createR2Provider}.
+ */
+export interface R2ProviderOptions {
+    /** Cloudflare R2 bucket binding (from `env.BUCKET_NAME`). */
+    bucket: R2BucketLike;
+    /**
+     * Base URL used to construct public object URLs. Typical values:
+     * - a public R2 custom domain: `https://cdn.example.com/`
+     * - a Worker route that proxies to the binding: `https://api.example.com/assets/`
+     */
+    publicBaseUrl?: string;
+    /**
+     * Signer invoked by `signedUrl`. Cloudflare R2 bindings do not produce
+     * signed URLs directly; templates pass a custom signer that either:
+     *   - returns a short-lived Worker route URL, or
+     *   - calls R2's S3-compatible API with SigV4 credentials.
+     * Calling `signedUrl` without a signer is a configuration error: a
+     * `publicBaseUrl` alone can only produce **permanent, unauthenticated**
+     * URLs, which would silently ignore `expiresIn` and defeat the
+     * time-limited-access contract. Use `publicUrl(key)` when a permanent
+     * public URL is actually what you want.
+     */
+    signer?: (key: string, expiresIn: number) => Promise<string> | string;
+    /** Provider name (defaults to `"r2"`). */
+    name?: string;
+    /** Custom key generator; defaults to `crypto.randomUUID()`. */
+    generateKey?: () => string;
+}
+/**
+ * R2 storage provider. Extends the base {@link StorageProvider} contract
+ * with {@link R2StorageProvider.publicUrl} for the (R2-common) case where
+ * objects are served through a public custom domain or Worker route.
+ */
+export interface R2StorageProvider extends StorageProvider {
+    /**
+     * Permanent, unauthenticated URL for an object: `${publicBaseUrl}${key}`.
+     * Only valid for objects that are meant to be public. Throws when
+     * `publicBaseUrl` is not configured. For time-limited access to private
+     * objects use `signedUrl` (requires a `signer`).
+     */
+    publicUrl(key: string): string;
+}
+/**
+ * Create a Cloudflare R2 storage provider bound to an R2 bucket binding.
+ * The R2 binding handles authentication transparently at the Worker
+ * runtime boundary, so no credentials are required at this layer.
+ */
+export declare function createR2Provider(options: R2ProviderOptions): R2StorageProvider;
+//# sourceMappingURL=r2.d.ts.map

package/dist/providers/r2.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"r2.d.ts","sourceRoot":"","sources":["../../src/providers/r2.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiB,eAAe,EAAoC,MAAM,aAAa,CAAA;AAEnG,eAAO,MAAM,yCAAyC,sPAC0L,CAAA;AAEhP;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,GAAG,CACD,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,WAAW,GAAG,eAAe,GAAG,IAAI,GAAG,MAAM,GAAG,cAAc,GAAG,IAAI,EAC5E,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,OAAO,CAAC,CAAA;IACnB,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC7C,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAA;CAC/C;AAED,MAAM,WAAW,gBAAgB;IAC/B,YAAY,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IACvC,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACxC;AAED,MAAM,WAAW,YAAY;IAC3B,WAAW,IAAI,OAAO,CAAC,WAAW,CAAC,CAAA;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,6DAA6D;IAC7D,MAAM,EAAE,YAAY,CAAA;IACpB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;;;;;;;;;;OAUG;IACH,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAA;IACrE,0CAA0C;IAC1C,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,+DAA+D;IAC/D,WAAW,CAAC,EAAE,MAAM,MAAM,CAAA;CAC3B;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAkB,SAAQ,eAAe;IACxD;;;;;OAKG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;CAC/B;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,GAAG,iBAAiB,CAoD9E"}

package/dist/providers/r2.js

@@ -0,0 +1,62 @@
+export const R2_SIGNED_URL_CONFIGURATION_ERROR_MESSAGE = "R2 provider: signedUrl requires a `signer` to be configured — a public base URL cannot produce a time-limited URL. Use publicUrl(key) for permanent public URLs, or configure a signer (e.g. R2's S3-compatible API with SigV4 credentials).";
+/**
+ * Create a Cloudflare R2 storage provider bound to an R2 bucket binding.
+ * The R2 binding handles authentication transparently at the Worker
+ * runtime boundary, so no credentials are required at this layer.
+ */
+export function createR2Provider(options) {
+    const name = options.name ?? "r2";
+    const publicBaseUrl = options.publicBaseUrl ?? "";
+    const generateKey = options.generateKey ??
+        (() => {
+            const g = globalThis;
+            return g.crypto?.randomUUID?.() ?? `${Date.now()}-${Math.random().toString(36).slice(2)}`;
+        });
+    async function upload(body, opts = {}) {
+        const key = opts.key ?? generateKey();
+        const putOptions = {};
+        if (opts.contentType !== undefined) {
+            putOptions.httpMetadata = { contentType: opts.contentType };
+        }
+        if (opts.metadata !== undefined) {
+            putOptions.customMetadata = opts.metadata;
+        }
+        await options.bucket.put(key, await toPutBody(body), putOptions);
+        return { key, url: publicBaseUrl ? `${publicBaseUrl}${key}` : "" };
+    }
+    return {
+        name,
+        upload,
+        async delete(key) {
+            await options.bucket.delete(key);
+        },
+        async signedUrl(key, expiresIn) {
+            // Security (assessment L7): never fall back to `${publicBaseUrl}${key}`
+            // here — that would silently return a PERMANENT public URL while the
+            // caller believes it expires after `expiresIn` seconds.
+            if (!options.signer) {
+                throw new Error(R2_SIGNED_URL_CONFIGURATION_ERROR_MESSAGE);
+            }
+            return options.signer(key, expiresIn);
+        },
+        publicUrl(key) {
+            if (!publicBaseUrl) {
+                throw new Error("R2 provider: publicUrl requires `publicBaseUrl` to be configured (a public R2 custom domain or a Worker route that proxies the bucket)");
+            }
+            return `${publicBaseUrl}${key}`;
+        },
+        async get(key) {
+            const obj = await options.bucket.get(key);
+            if (!obj)
+                return null;
+            return obj.arrayBuffer();
+        },
+    };
+}
+async function toPutBody(body) {
+    if (body instanceof Uint8Array)
+        return body;
+    if (body instanceof ArrayBuffer)
+        return body;
+    return body;
+}

package/dist/providers/s3.d.ts

@@ -0,0 +1,57 @@
+import type { StorageProvider } from "../types.js";
+/**
+ * Fetch shape used by the S3 provider. Matches the global `fetch` and
+ * Cloudflare Workers `fetch`. Tests can stub this.
+ */
+export type S3Fetch = (input: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body?: Uint8Array;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    arrayBuffer: () => Promise<ArrayBuffer>;
+    text: () => Promise<string>;
+}>;
+/**
+ * Options for {@link createS3Provider}.
+ */
+export interface S3ProviderOptions {
+    /** AWS access key id. */
+    accessKeyId: string;
+    /** AWS secret access key. */
+    secretAccessKey: string;
+    /** Optional session token for temporary credentials. */
+    sessionToken?: string;
+    /** S3 region (e.g. `"us-east-1"`). */
+    region: string;
+    /** S3 bucket name. */
+    bucket: string;
+    /**
+     * Endpoint URL override. Defaults to the public AWS S3 endpoint for the
+     * region (`https://s3.<region>.amazonaws.com`). Set this for S3-compatible
+     * services (MinIO, Backblaze B2, DigitalOcean Spaces, Wasabi, R2 S3 API).
+     */
+    endpoint?: string;
+    /**
+     * When `true`, put the bucket in the URL path rather than the hostname
+     * subdomain. Defaults to `true` to stay compatible with the widest set
+     * of S3-compatible services. Set to `false` to use
+     * `https://<bucket>.s3.<region>.amazonaws.com` virtual-hosted style.
+     */
+    forcePathStyle?: boolean;
+    /** Base URL used for the public `url` field returned from `upload`. */
+    publicBaseUrl?: string;
+    /** Override `fetch` (e.g. in tests). Defaults to global `fetch`. */
+    fetch?: S3Fetch;
+    /** Provider name (defaults to `"s3"`). */
+    name?: string;
+    /** Custom key generator; defaults to `crypto.randomUUID()`. */
+    generateKey?: () => string;
+}
+/**
+ * Create an S3 / S3-compatible storage provider. Uses Web Crypto to sign
+ * requests with AWS SigV4, so no AWS SDK dependency is required.
+ */
+export declare function createS3Provider(options: S3ProviderOptions): StorageProvider;
+//# sourceMappingURL=s3.d.ts.map

package/dist/providers/s3.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"s3.d.ts","sourceRoot":"","sources":["../../src/providers/s3.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAiB,eAAe,EAAoC,MAAM,aAAa,CAAA;AAEnG;;;GAGG;AACH,MAAM,MAAM,OAAO,GAAG,CACpB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE;IACJ,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC/B,IAAI,CAAC,EAAE,UAAU,CAAA;CAClB,KACE,OAAO,CAAC;IACX,EAAE,EAAE,OAAO,CAAA;IACX,MAAM,EAAE,MAAM,CAAA;IACd,WAAW,EAAE,MAAM,OAAO,CAAC,WAAW,CAAC,CAAA;IACvC,IAAI,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAA;CAC5B,CAAC,CAAA;AAMF;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,yBAAyB;IACzB,WAAW,EAAE,MAAM,CAAA;IACnB,6BAA6B;IAC7B,eAAe,EAAE,MAAM,CAAA;IACvB,wDAAwD;IACxD,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAA;IACd,sBAAsB;IACtB,MAAM,EAAE,MAAM,CAAA;IACd;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,uEAAuE;IACvE,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,oEAAoE;IACpE,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,0CAA0C;IAC1C,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,+DAA+D;IAC/D,WAAW,CAAC,EAAE,MAAM,MAAM,CAAA;CAC3B;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,GAAG,eAAe,CAsH5E"}

package/dist/providers/s3.js

@@ -0,0 +1,141 @@
+import { presignUrl, signRequest } from "../lib/sigv4.js";
+function defaultS3Fetch(input, init) {
+    return globalThis.fetch(input, { ...init, body: init.body });
+}
+/**
+ * Create an S3 / S3-compatible storage provider. Uses Web Crypto to sign
+ * requests with AWS SigV4, so no AWS SDK dependency is required.
+ */
+export function createS3Provider(options) {
+    const name = options.name ?? "s3";
+    const forcePathStyle = options.forcePathStyle ?? true;
+    const endpoint = options.endpoint ??
+        (forcePathStyle
+            ? `https://s3.${options.region}.amazonaws.com`
+            : `https://${options.bucket}.s3.${options.region}.amazonaws.com`);
+    const publicBaseUrl = options.publicBaseUrl ?? "";
+    const fetchImpl = options.fetch ?? defaultS3Fetch;
+    const credentials = {
+        accessKeyId: options.accessKeyId,
+        secretAccessKey: options.secretAccessKey,
+    };
+    if (options.sessionToken !== undefined)
+        credentials.sessionToken = options.sessionToken;
+    const generateKey = options.generateKey ??
+        (() => {
+            const g = globalThis;
+            return g.crypto?.randomUUID?.() ?? `${Date.now()}-${Math.random().toString(36).slice(2)}`;
+        });
+    function buildUrl(key) {
+        if (forcePathStyle) {
+            return `${endpoint}/${encodeURIComponent(options.bucket)}/${encodeKey(key)}`;
+        }
+        return `${endpoint}/${encodeKey(key)}`;
+    }
+    async function upload(body, opts = {}) {
+        if (!fetchImpl)
+            throw new Error("S3 provider requires a fetch implementation");
+        const key = opts.key ?? generateKey();
+        const bytes = await toBytes(body);
+        const url = buildUrl(key);
+        const headers = {};
+        if (opts.contentType)
+            headers["content-type"] = opts.contentType;
+        if (opts.metadata) {
+            for (const [k, v] of Object.entries(opts.metadata)) {
+                headers[`x-amz-meta-${k.toLowerCase()}`] = v;
+            }
+        }
+        const signed = await signRequest({
+            method: "PUT",
+            url,
+            headers,
+            body: bytes,
+            credentials,
+            region: options.region,
+            service: "s3",
+        });
+        const response = await fetchImpl(url, {
+            method: "PUT",
+            headers: signed.headers,
+            body: bytes,
+        });
+        if (!response.ok) {
+            const text = await response.text().catch(() => "");
+            throw new Error(`S3 upload failed (${response.status}): ${text}`);
+        }
+        return { key, url: publicBaseUrl ? `${publicBaseUrl}${key}` : "" };
+    }
+    return {
+        name,
+        upload,
+        async delete(key) {
+            if (!fetchImpl)
+                throw new Error("S3 provider requires a fetch implementation");
+            const url = buildUrl(key);
+            const signed = await signRequest({
+                method: "DELETE",
+                url,
+                credentials,
+                region: options.region,
+                service: "s3",
+            });
+            const response = await fetchImpl(url, {
+                method: "DELETE",
+                headers: signed.headers,
+            });
+            // S3 returns 204 on successful delete, 404 on missing — treat both as success.
+            if (!response.ok && response.status !== 404) {
+                const text = await response.text().catch(() => "");
+                throw new Error(`S3 delete failed (${response.status}): ${text}`);
+            }
+        },
+        async signedUrl(key, expiresIn) {
+            return presignUrl({
+                method: "GET",
+                url: buildUrl(key),
+                expiresIn,
+                credentials,
+                region: options.region,
+                service: "s3",
+            });
+        },
+        async get(key) {
+            if (!fetchImpl)
+                throw new Error("S3 provider requires a fetch implementation");
+            const url = buildUrl(key);
+            const signed = await signRequest({
+                method: "GET",
+                url,
+                credentials,
+                region: options.region,
+                service: "s3",
+            });
+            const response = await fetchImpl(url, {
+                method: "GET",
+                headers: signed.headers,
+            });
+            if (response.status === 404)
+                return null;
+            if (!response.ok) {
+                const text = await response.text().catch(() => "");
+                throw new Error(`S3 get failed (${response.status}): ${text}`);
+            }
+            return response.arrayBuffer();
+        },
+    };
+}
+function encodeKey(key) {
+    return key
+        .split("/")
+        .map((segment) => encodeURIComponent(segment).replace(/[!'()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`))
+        .join("/");
+}
+async function toBytes(body) {
+    if (body instanceof Uint8Array)
+        return body;
+    if (body instanceof ArrayBuffer)
+        return new Uint8Array(body);
+    const buffer = await body.arrayBuffer();
+    return new Uint8Array(buffer);
+}

package/dist/service.d.ts

@@ -0,0 +1,21 @@
+import type { StorageProvider } from "./types.js";
+/**
+ * Thrown when a storage operation cannot find the requested provider.
+ */
+export declare class StorageError extends Error {
+    constructor(message: string);
+}
+/**
+ * Convenience wrapper exposing a single provider. Most deployments use
+ * exactly one storage backend at a time; for those cases the service is
+ * just a named wrapper.
+ */
+export interface StorageService extends StorageProvider {
+    /** The wrapped provider. */
+    readonly provider: StorageProvider;
+}
+/**
+ * Create a storage service that delegates all calls to the given provider.
+ */
+export declare function createStorageService(provider: StorageProvider): StorageService;
+//# sourceMappingURL=service.d.ts.map

package/dist/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD;;GAEG;AACH,qBAAa,YAAa,SAAQ,KAAK;gBACzB,OAAO,EAAE,MAAM;CAI5B;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAe,SAAQ,eAAe;IACrD,4BAA4B;IAC5B,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAA;CACnC;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,eAAe,GAAG,cAAc,CAS9E"}

package/dist/service.js

@@ -0,0 +1,22 @@
+/**
+ * Thrown when a storage operation cannot find the requested provider.
+ */
+export class StorageError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "StorageError";
+    }
+}
+/**
+ * Create a storage service that delegates all calls to the given provider.
+ */
+export function createStorageService(provider) {
+    return {
+        provider,
+        name: provider.name,
+        upload: provider.upload.bind(provider),
+        delete: provider.delete.bind(provider),
+        signedUrl: provider.signedUrl.bind(provider),
+        get: provider.get.bind(provider),
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Accepted body shapes for uploads. Providers normalize to `Uint8Array`
+ * or pass through to their native API.
+ */
+export type StorageUploadBody = ArrayBuffer | Uint8Array | Blob;
+/**
+ * Options controlling an upload.
+ */
+export interface UploadOptions {
+    /**
+     * Override the object key. When omitted, providers generate a random
+     * key (typically `${randomUUID()}` — UUID v4 where available).
+     */
+    key?: string;
+    /** MIME content type (e.g. `"image/png"`). */
+    contentType?: string;
+    /** Custom metadata; persisted by providers that support it (R2, S3). */
+    metadata?: Record<string, string>;
+}
+/**
+ * Result of a successful upload.
+ */
+export interface StorageObject {
+    /** Object key inside the bucket/store. */
+    key: string;
+    /**
+     * Public URL for the object when the provider exposes one. Empty string
+     * when the object is private and can only be accessed via `signedUrl`.
+     */
+    url: string;
+}
+/**
+ * Pluggable object storage provider.
+ *
+ * Built-in implementations:
+ * - `local` — in-memory, for dev and tests
+ * - `r2`    — Cloudflare R2 via the workers binding
+ * - `s3`    — Amazon S3 / S3-compatible via SigV4
+ */
+export interface StorageProvider {
+    /** Unique provider name (e.g. `"r2"`, `"s3"`, `"local"`). */
+    readonly name: string;
+    /** Upload an object. */
+    upload(body: StorageUploadBody, options?: UploadOptions): Promise<StorageObject>;
+    /** Delete an object by key. No-op if the key does not exist. */
+    delete(key: string): Promise<void>;
+    /**
+     * Produce a time-limited URL that grants GET access to the object.
+     * `expiresIn` is in seconds.
+     */
+    signedUrl(key: string, expiresIn: number): Promise<string>;
+    /**
+     * Fetch an object's bytes. Returns `null` when the object is absent.
+     */
+    get(key: string): Promise<ArrayBuffer | null>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG,WAAW,GAAG,UAAU,GAAG,IAAI,CAAA;AAE/D;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,8CAA8C;IAC9C,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,0CAA0C;IAC1C,GAAG,EAAE,MAAM,CAAA;IACX;;;OAGG;IACH,GAAG,EAAE,MAAM,CAAA;CACZ;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,6DAA6D;IAC7D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,wBAAwB;IACxB,MAAM,CAAC,IAAI,EAAE,iBAAiB,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,CAAA;IAChF,gEAAgE;IAChE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAClC;;;OAGG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAC1D;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAA;CAC9C"}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@voyant-travel/storage",
+  "version": "0.104.1",
+  "license": "Apache-2.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "import": "./dist/types.js",
+      "default": "./dist/types.js"
+    },
+    "./service": {
+      "types": "./dist/service.d.ts",
+      "import": "./dist/service.js",
+      "default": "./dist/service.js"
+    },
+    "./providers/local": {
+      "types": "./dist/providers/local.d.ts",
+      "import": "./dist/providers/local.js",
+      "default": "./dist/providers/local.js"
+    },
+    "./providers/r2": {
+      "types": "./dist/providers/r2.d.ts",
+      "import": "./dist/providers/r2.js",
+      "default": "./dist/providers/r2.js"
+    },
+    "./providers/s3": {
+      "types": "./dist/providers/s3.d.ts",
+      "import": "./dist/providers/s3.js",
+      "default": "./dist/providers/s3.js"
+    },
+    "./lib/sigv4": {
+      "types": "./dist/lib/sigv4.d.ts",
+      "import": "./dist/lib/sigv4.js",
+      "default": "./dist/lib/sigv4.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2",
+    "@voyant-travel/voyant-typescript-config": "^0.1.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/voyant-travel/voyant.git",
+    "directory": "packages/storage"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check src/",
+    "test": "vitest run",
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts"
+}