manage-storage 0.0.62 → 0.0.63

package/dist/manage-storage.d.ts

@@ -1,5 +1,10 @@
+import { S3Client } from '@aws-sdk/client-s3';
+
 /**
- * Storage operation action type
+ * Storage operation action type.
+ *
+ * @deprecated Actions belong to the {@link manageStorage} function. Call the
+ * matching {@link StorageManager} method instead.
  */
 export declare type Action = "upload" | "download" | "delete" | "list" | "deleteAll" | "copy" | "rename";
 
@@ -39,96 +44,61 @@ export declare interface DeleteResult {
 }
 
 /**
- * Universal cloud storage manager supporting Amazon S3, Backblaze B2, and Cloudflare R2.
- * Automatically detects the configured provider from environment variables.
- *
- * @param action - The storage operation to perform
- * @param options - Operation-specific options
- * @returns
- *   - upload: Returns {success: true, key: string}
- *   - download: Returns the file content as a string
- *   - delete: Returns {success: true, key: string}
- *   - list: Returns array of object keys
- *   - deleteAll: Returns {success: true, count: number}
- * @throws {Error} When credentials are missing or operation fails
- *
- * @example
- * // Upload a file
- * await manageStorage('upload', {
- *   key: 'documents/report.pdf',
- *   body: fileContent
- * });
+ * Which provider the environment is configured for, by looking for a complete
+ * set of credentials under each prefix in turn: Cloudflare, Backblaze, Amazon.
  *
- * @example
- * // Download a file
- * const data = await manageStorage('download', {
- *   key: 'documents/report.pdf'
- * });
- *
- * @example
- * // List all files
- * const files = await manageStorage('list');
+ * @returns The detected provider, or `cloudflare` when none is fully configured
+ * (in which case the missing credentials are reported on the first call).
  *
  * @example
- * // Delete a file
- * await manageStorage('delete', {
- *   key: 'documents/report.pdf'
- * });
+ * // With CLOUDFLARE_* set
+ * detectProvider(); // "cloudflare"
+ */
+export declare function detectProvider(): Provider;
+
+/**
+ * The original action-string API, kept working for already-published callers.
  *
- * @example
- * // Copy a file
- * await manageStorage('copy', {
- *   key: 'documents/report.pdf',
- *   destinationKey: 'documents/report-copy.pdf'
- * });
+ * @deprecated Use {@link StorageManager}. `manageStorage("upload", { key, body })`
+ * becomes `new StorageManager().upload(key, body)` — same requests, but the
+ * arguments each method needs are in its signature instead of an option bag
+ * whose required fields change per action.
  *
- * @example
- * // Rename a file (copy + delete)
- * await manageStorage('rename', {
- *   key: 'documents/old-name.pdf',
- *   destinationKey: 'documents/new-name.pdf'
- * });
+ * @param action - `upload`, `download`, `delete`, `list`, `deleteAll`, `copy` or `rename`
+ * @param options - The key, body, destination and credential overrides
  *
  * @example
- * // Force a specific provider with runtime credentials
- * await manageStorage('upload', {
- *   key: 'test.txt',
- *   body: 'Hello!',
- *   provider: 'cloudflare',
- *   BUCKET_NAME: 'my-bucket',
- *   ACCESS_KEY_ID: 'key-id',
- *   SECRET_ACCESS_KEY: 'secret',
- *   BUCKET_URL: 'https://account.r2.cloudflarestorage.com'
- * });
+ * // Deprecated:
+ * await manageStorage("upload", { key: "a.txt", body: "hi" });
+ * // Current:
+ * await new StorageManager().upload("a.txt", "hi");
  */
-declare function manageStorage(action: "upload", options: StorageOptions & {
+export declare function manageStorage(action: "upload", options: StorageOptions & {
     key: string;
-    body: string | Buffer | ReadableStream;
+    body: StorageBody;
 }): Promise<UploadResult>;
 
-declare function manageStorage(action: "download", options: StorageOptions & {
+export declare function manageStorage(action: "download", options: StorageOptions & {
     key: string;
 }): Promise<string>;
 
-declare function manageStorage(action: "delete", options: StorageOptions & {
+export declare function manageStorage(action: "delete", options: StorageOptions & {
     key: string;
 }): Promise<DeleteResult>;
 
-declare function manageStorage(action: "list", options?: StorageOptions): Promise<string[]>;
+export declare function manageStorage(action: "list", options?: StorageOptions): Promise<string[]>;
 
-declare function manageStorage(action: "deleteAll", options?: StorageOptions): Promise<DeleteAllResult>;
+export declare function manageStorage(action: "deleteAll", options?: StorageOptions): Promise<DeleteAllResult>;
 
-declare function manageStorage(action: "copy", options: StorageOptions & {
+export declare function manageStorage(action: "copy", options: StorageOptions & {
     key: string;
     destinationKey: string;
 }): Promise<CopyResult>;
 
-declare function manageStorage(action: "rename", options: StorageOptions & {
+export declare function manageStorage(action: "rename", options: StorageOptions & {
     key: string;
     destinationKey: string;
 }): Promise<RenameResult>;
-export default manageStorage;
-export { manageStorage }
 
 /**
  * Cloud storage provider type
@@ -149,7 +119,231 @@ export declare interface RenameResult {
 }
 
 /**
- * Options for storage operations
+ * Merge explicit config over the environment for one provider.
+ *
+ * @param config - Explicit values, each of which wins over its env var
+ * @returns Everything the S3 client needs, with missing pieces left empty for
+ * the caller to report on
+ *
+ * @example
+ * resolveConfig({ provider: "backblaze", bucket: "my-bucket" });
+ */
+export declare function resolveConfig(config?: StorageConfig): ResolvedConfig;
+
+/** The fully resolved connection details, after env vars and overrides merge. */
+export declare interface ResolvedConfig {
+    provider: Provider;
+    region: string;
+    endpoint: string;
+    bucket: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+}
+
+/** What an upload accepts as its payload. */
+export declare type StorageBody = string | Uint8Array | Buffer | ReadableStream;
+
+/**
+ * How a {@link StorageManager} reaches its bucket.
+ *
+ * Every field is optional: anything left out falls back to the `*_BUCKET_NAME`,
+ * `*_ACCESS_KEY_ID`, `*_SECRET_ACCESS_KEY` and `*_BUCKET_URL` environment
+ * variables for the resolved provider. Edge runtimes have no `process.env` to
+ * read, so there you pass all four.
+ */
+export declare interface StorageConfig {
+    /** Which provider to talk to. Auto-detected from the environment if omitted. */
+    provider?: Provider;
+    /** Bucket name. Falls back to `<PROVIDER>_BUCKET_NAME`. */
+    bucket?: string;
+    /** Access key id. Falls back to `<PROVIDER>_ACCESS_KEY_ID`. */
+    accessKeyId?: string;
+    /** Secret access key. Falls back to `<PROVIDER>_SECRET_ACCESS_KEY`. */
+    secretAccessKey?: string;
+    /** S3 endpoint for the bucket. Falls back to `<PROVIDER>_BUCKET_URL`. */
+    endpoint?: string;
+    /** Region. Only S3 uses it; R2 and B2 are always `auto`. */
+    region?: string;
+    /**
+     * A pre-built client, for tests or for a client configured with retry,
+     * proxy or credential-provider options this class does not expose.
+     */
+    client?: S3Client;
+}
+
+/**
+ * One bucket, on Amazon S3, Cloudflare R2 or Backblaze B2, as an object with a
+ * method per operation.
+ *
+ * Credentials are resolved once, in the constructor, from the config you pass
+ * and the environment: `new StorageManager()` with the env vars set is the whole
+ * setup. The client is built lazily on the first call, so constructing a manager
+ * for a provider you end up not using costs nothing.
+ *
+ * @example
+ * // Env vars configure it; the provider is detected from which ones are set.
+ * const storage = new StorageManager();
+ *
+ * await storage.upload("notes/memo.txt", "Hello, World!");
+ * const text = await storage.download("notes/memo.txt");
+ * const keys = await storage.list("notes/");
+ * await storage.rename("notes/memo.txt", "archive/memo.txt");
+ * await storage.delete("archive/memo.txt");
+ *
+ * @example
+ * // Cloudflare Workers: no process.env, so pass the bindings in.
+ * const storage = new StorageManager({
+ *   provider: "cloudflare",
+ *   bucket: env.CLOUDFLARE_BUCKET_NAME,
+ *   accessKeyId: env.CLOUDFLARE_ACCESS_KEY_ID,
+ *   secretAccessKey: env.CLOUDFLARE_SECRET_ACCESS_KEY,
+ *   endpoint: env.CLOUDFLARE_BUCKET_URL,
+ * });
+ */
+declare class StorageManager_2 {
+    /** The resolved connection details: provider, bucket, endpoint, region. */
+    readonly config: ResolvedConfig;
+    private readonly injectedClient?;
+    private cachedClient?;
+    /**
+     * @param config - Connection details; anything omitted comes from the
+     * environment. Throws only when an operation runs without credentials, not
+     * here, so a manager can be constructed before the environment is loaded.
+     */
+    constructor(config?: StorageConfig);
+    /** Which provider this manager resolved to. */
+    get provider(): Provider;
+    /** Which bucket this manager reads and writes. */
+    get bucket(): string;
+    /**
+     * The S3 client, built on first use.
+     *
+     * The credential check lives here rather than in the constructor because
+     * `dotenv` is often loaded after the module graph is: failing at construction
+     * would break the common `new StorageManager()` at module scope.
+     */
+    private get client();
+    /**
+     * Send one command, tagging any failure with the provider and operation.
+     *
+     * The SDK's errors say what went wrong but not which bucket or provider they
+     * went wrong against, which is the first thing you need when two providers are
+     * configured.
+     */
+    private send;
+    /**
+     * Store bytes at a key, creating or replacing whatever was there.
+     *
+     * @param key - The object key/path
+     * @param body - String, Buffer, Uint8Array or stream to store
+     * @param options - `contentType` sets the stored MIME type, which is what a
+     * browser reads when the object is served from a public bucket
+     *
+     * @example
+     * await storage.upload("config/settings.json", JSON.stringify(settings), {
+     *   contentType: "application/json",
+     * });
+     */
+    upload(key: string, body: StorageBody, options?: {
+        contentType?: string;
+    }): Promise<UploadResult>;
+    /**
+     * Read an object back as text.
+     *
+     * @param key - The object key/path
+     * @returns The object's content, decoded as UTF-8
+     * @throws When the key does not exist — there is no "missing" return value
+     *
+     * @example
+     * const settings = JSON.parse(await storage.download("config/settings.json"));
+     */
+    download(key: string): Promise<string>;
+    /**
+     * Read an object back as bytes, for anything that is not text.
+     *
+     * @param key - The object key/path
+     *
+     * @example
+     * const bytes = await storage.downloadBytes("images/logo.png");
+     */
+    downloadBytes(key: string): Promise<Uint8Array>;
+    /**
+     * Every key in the bucket, or every key under a prefix.
+     *
+     * Paginated: S3 returns at most 1000 keys per response, and this follows the
+     * continuation token to the end rather than silently returning the first page.
+     *
+     * @param prefix - Only keys starting with this string. Keys are flat — there
+     * are no folders — so `"documents/"` is just a prefix match.
+     *
+     * @example
+     * const invoices = await storage.list("invoices/2024/");
+     */
+    list(prefix?: string): Promise<string[]>;
+    /**
+     * Whether a key exists, without downloading it.
+     *
+     * @param key - The object key/path
+     *
+     * @example
+     * if (await storage.exists("config/settings.json")) { … }
+     */
+    exists(key: string): Promise<boolean>;
+    /**
+     * Duplicate an object to another key.
+     *
+     * @param key - The source key
+     * @param destinationKey - The key to copy it to
+     *
+     * @example
+     * await storage.copy("config/settings.json", "config/settings.backup.json");
+     */
+    copy(key: string, destinationKey: string): Promise<CopyResult>;
+    /**
+     * Move an object to another key: a copy, then a delete.
+     *
+     * Not atomic — S3 has no rename — so an interruption between the two can leave
+     * both keys in place. Nothing is deleted unless the copy succeeded.
+     *
+     * @param key - The current key
+     * @param destinationKey - The key to move it to
+     *
+     * @example
+     * await storage.rename("temp/draft.md", "published/article.md");
+     */
+    rename(key: string, destinationKey: string): Promise<RenameResult>;
+    /**
+     * Remove one object. Deleting a key that does not exist succeeds — that is how
+     * S3 behaves, and this does not paper over it with a lookup first.
+     *
+     * @param key - The object key/path
+     *
+     * @example
+     * await storage.delete("notes/memo.txt");
+     */
+    delete(key: string): Promise<DeleteResult>;
+    /**
+     * Empty the bucket, or everything under a prefix. Irreversible.
+     *
+     * Lists and deletes in batches of 1000 (the API's per-request limit) until
+     * nothing is left, so it finishes the job on a bucket of any size.
+     *
+     * @param prefix - Restrict the deletion to keys starting with this string.
+     * Omitting it deletes everything in the bucket.
+     *
+     * @example
+     * const { count } = await storage.deleteAll("temp/");
+     */
+    deleteAll(prefix?: string): Promise<DeleteAllResult>;
+}
+export { StorageManager_2 as StorageManager }
+export default StorageManager_2;
+
+/**
+ * Options for storage operations.
+ *
+ * @deprecated The option bag belongs to {@link manageStorage}. {@link StorageManager}
+ * takes credentials once in its constructor and the key as an argument.
  */
 export declare interface StorageOptions {
     /** The object key/path (required for upload, download, delete) */
@@ -157,7 +351,7 @@ export declare interface StorageOptions {
     /** The destination key/path (required for copy, rename) */
     destinationKey?: string;
     /** The file content to upload (required for upload) */
-    body?: string | Buffer | ReadableStream;
+    body?: StorageBody;
     /** Force a specific cloud provider (auto-detected if omitted) */
     provider?: Provider;
     /** Override bucket name at runtime */

package/dist/manage-storage.js

@@ -1 +1 @@
-import"dotenv";import{m as a,m as e}from"./manage-storage-CGRNU6uH.js";export{a as default,e as manageStorage};
+import"dotenv";import{e as a,e,f as o,m as r,l as t}from"./manage-storage-De0Cb_cq.js";export{a as StorageManager,e as default,o as detectProvider,r as manageStorage,t as resolveConfig};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "manage-storage",
-  "version": "0.0.62",
+  "version": "0.0.63",
   "description": "Storage manager supporting AWS S3, Backblaze B2, and Cloudflare R2 with automatic provider detection",
   "main": "./dist/manage-storage.js",
   "module": "./dist/manage-storage.js",

package/dist/index.browser-CZ9CQ86G.js

@@ -1 +0,0 @@
-import{t as e,f as t}from"./manage-storage-CGRNU6uH.js";import{E as r,a,H as s,I as n,M as i,c as o,S as l,d as c,b as m,e as d,g as y,h,i as u,r as S,j as f}from"./manage-storage-CGRNU6uH.js";class p{marshaller;serializer;deserializer;serdeContext;defaultContentType;constructor({marshaller:e,serializer:t,deserializer:r,serdeContext:a,defaultContentType:s}){this.marshaller=e,this.serializer=t,this.deserializer=r,this.serdeContext=a,this.defaultContentType=s}async serializeEventStream({eventStream:e,requestSchema:t,initialRequest:r}){const a=this.marshaller,s=t.getEventStreamMember(),n=t.getMemberSchema(s),i=this.serializer,o=this.defaultContentType,l=/* @__PURE__ */Symbol("initialRequestMarker"),c={async*[Symbol.asyncIterator](){if(r){const e={":event-type":{type:"string",value:"initial-request"},":message-type":{type:"string",value:"event"},":content-type":{type:"string",value:o}};i.write(t,r);const a=i.flush();yield{[l]:!0,headers:e,body:a}}for await(const t of e)yield t}};return a.serialize(c,e=>{if(e[l])return{headers:e.headers,body:e.body};let t="";for(const n in e)if("__type"!==n){t=n;break}const{additionalHeaders:r,body:a,eventType:s,explicitPayloadContentType:i}=this.writeEventBody(t,n,e);return{headers:{":event-type":{type:"string",value:s},":message-type":{type:"string",value:"event"},":content-type":{type:"string",value:i??o},...r},body:a}})}async deserializeEventStream({response:t,responseSchema:r,initialResponseContainer:a}){const s=this.marshaller,n=r.getEventStreamMember(),i=r.getMemberSchema(n).getMemberSchemas(),o=/* @__PURE__ */Symbol("initialResponseMarker"),l=s.deserialize(t.body,async t=>{let a="";for(const e in t)if("__type"!==e){a=e;break}const s=t[a].body;if("initial-response"===a){const e=await this.deserializer.read(r,s);return delete e[n],{[o]:!0,...e}}if(a in i){const r=i[a];if(r.isStructSchema()){const n={};let i=!1;for(const[o,l]of r.structIterator()){const{eventHeader:r,eventPayload:c}=l.getMergedTraits();if(i=i||Boolean(r||c),c)l.isBlobSchema()?n[o]=s:l.isStringSchema()?n[o]=(this.serdeContext?.utf8Encoder??e)(s):l.isStructSchema()&&(n[o]=await this.deserializer.read(l,s));else if(r){const e=t[a].headers[o]?.value;null!=e&&(l.isNumericSchema()?n[o]=e&&"object"==typeof e&&"bytes"in e?BigInt(e.toString()):Number(e):n[o]=e)}}if(i)return{[a]:n};if(0===s.byteLength)return{[a]:{}}}return{[a]:await this.deserializer.read(r,s)}}return{$unknown:t}}),c=l[Symbol.asyncIterator](),m=await c.next();if(m.done)return l;if(m.value?.[o]){if(!r)throw new Error("@smithy::core/protocols - initial-response event encountered in event stream but no response schema given.");for(const e in m.value)a[e]=m.value[e]}return{async*[Symbol.asyncIterator](){for(m?.value?.[o]||(yield m.value);;){const{done:e,value:t}=await c.next();if(e)break;yield t}}}}writeEventBody(e,r,a){const s=this.serializer;let n,i=e,o=null;const l={};if(r.getSchema()[4].includes(e)){const t=r.getMemberSchema(e);if(t.isStructSchema()){for(const[r,s]of t.structIterator()){const{eventHeader:t,eventPayload:n}=s.getMergedTraits();if(n)o=r;else if(t){const t=a[e][r];let n="binary";s.isNumericSchema()?n=(-2)**31<=t&&t<=2**31-1?"integer":"long":s.isTimestampSchema()?n="timestamp":s.isStringSchema()?n="string":s.isBooleanSchema()&&(n="boolean"),null!=t&&(l[r]={type:n,value:t},delete a[e][r])}}if(null!==o){const r=t.getMemberSchema(o);r.isBlobSchema()?n="application/octet-stream":r.isStringSchema()&&(n="text/plain"),s.write(r,a[e][o])}else s.write(t,a[e])}else{if(!t.isUnitSchema())throw new Error("@smithy/core/event-streams - non-struct member not supported in event stream union.");s.write(t,{})}}else{const[t,r]=a[e];i=t,s.write(15,r)}const c=s.flush()??new Uint8Array;return{body:"string"==typeof c?(this.serdeContext?.utf8Decoder??t)(c):c,eventType:i,explicitPayloadContentType:n,additionalHeaders:l}}}export{r as EventStreamCodec,a as EventStreamMarshaller,p as EventStreamSerde,s as HeaderMarshaller,n as Int64,i as MessageDecoderStream,o as MessageEncoderStream,l as SmithyMessageDecoderStream,c as SmithyMessageEncoderStream,m as UniversalEventStreamMarshaller,d as eventStreamSerdeProvider,y as getChunkedStream,h as getMessageUnmarshaller,u as iterableToReadableStream,S as readableStreamToIterable,f as resolveEventStreamSerdeConfig};