@rr-vault/r2 1.0.0

package/README.md

@@ -0,0 +1,117 @@
+# @rr-vault/sdk 🚀
+
+**RR-Vault SDK** is a developer-first cloud storage client designed for securely uploading, managing, and delivering files using API keys and app-based access.
+
+This SDK acts as a **Secure Thin Client**. Instead of storing cloud credentials (like R2/S3 keys) on the client-side, it proxies all requests through your backend API, ensuring your infrastructure remains 100% private.
+
+---
+
+## 📦 Installation
+
+Install the package via npm:
+
+```bash
+npm install @rr-vault/sdk
+```
+
+---
+
+## ⚡ Quick Start
+
+### 1. Configure the SDK
+Initialize the SDK with your `appId`, `apiKey`, and `secretKey`. These will be sent to your backend with every request for verification.
+
+```typescript
+import { RRVault } from '@rr-vault/sdk';
+
+RRVault.config({
+  appId: 'your-app-id',
+  apiKey: 'your-api-key',
+  secretKey: 'your-secret-key'
+});
+```
+
+### 2. Upload a File
+The SDK sends the file and your credentials to your backend API (`/api/v1/upload`). Your backend then handles the actual storage logic.
+
+```typescript
+try {
+  const fileContent = Buffer.from("Hello RR-Vault!"); // Or a File/Blob/Uint8Array
+  
+  const result = await RRVault.upload(fileContent, "myfile.txt", {
+    folder: "documents",
+    contentType: "text/plain"
+  });
+
+  console.log("Upload Success:", result.url);
+  console.log("Storage Key:", result.key);
+} catch (error) {
+  console.error("Upload failed:", error.message);
+}
+```
+
+### 3. Delete a File
+Delete files securely by sending a delete request through your proxy.
+
+```typescript
+const result = await RRVault.delete("documents/171165...-myfile.txt");
+
+if (result.success) {
+  console.log("File deleted successfully");
+} else {
+  console.log("Delete failed:", result.message);
+}
+```
+
+---
+
+## 🛡️ Security Architecture
+The SDK implements a **Zero-Secret Client Policy**:
+- **No Cloud Keys:** Access Key IDs and Secret Access Keys for R2/S3 are **NEVER** stored in the SDK or frontend code.
+- **Backend Proxy:** All operations (`upload`, `delete`) are routed through your server. 
+- **Centralized Validation:** Your backend validates the `appId` and `secretKey` before interacting with the storage provider.
+
+---
+
+## 🛠️ API Reference
+
+### `RRVault.config(options: RRVaultConfig)`
+Sets up the SDK credentials.
+- `appId`: Your application ID.
+- `apiKey`: Your application API key.
+- `secretKey`: Your secret key.
+
+### `RRVault.upload(file, fileName, options?)`
+Uploads a file via your backend proxy.
+- `file`: Buffer, Blob, or Uint8Array.
+- `fileName`: Original name of the file.
+- `options`:
+  - `folder`: (Optional) Virtual folder path.
+  - `contentType`: (Optional) MIME type.
+  - `metadata`: (Optional) Key-value pairs for storage metadata.
+
+### `RRVault.delete(key)`
+Deletes a file by its key via your backend proxy.
+- `key`: The storage key returned during upload.
+
+---
+
+## 📄 Types
+
+```typescript
+export interface UploadResult {
+    key: string;       // Unique storage path
+    url: string;       // Public delivery URL
+    etag?: string;     // entity tag
+}
+
+export interface DeleteResult {
+    success: boolean;
+    message?: string;
+}
+```
+
+---
+
+## ⚖️ License
+ISC License. Built with ❤️ by Md. Ridoy Babu.

package/dist/config.d.ts

@@ -0,0 +1,5 @@
+import { RRVaultConfig } from "./types.js";
+export declare function setConfig(newConfig: RRVaultConfig): void;
+export declare function getUserConfig(): RRVaultConfig;
+export declare function getApiUrl(): string;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAM3C,wBAAgB,SAAS,CAAC,SAAS,EAAE,aAAa,QAEjD;AAED,wBAAgB,aAAa,IAAI,aAAa,CAO7C;AAED,wBAAgB,SAAS,IAAI,MAAM,CAElC"}

package/dist/config.js

@@ -0,0 +1,15 @@
+const VALIDATION_API_URL = "http://localhost:8888/api/v1/validate";
+let userConfig = null;
+export function setConfig(newConfig) {
+    userConfig = { ...newConfig };
+}
+export function getUserConfig() {
+    if (!userConfig) {
+        throw new Error("RRVault: SDK not configured. Please call RRVault.config() first.");
+    }
+    return userConfig;
+}
+export function getApiUrl() {
+    return VALIDATION_API_URL;
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAEA,MAAM,kBAAkB,GAAG,uCAAuC,CAAC;AAEnE,IAAI,UAAU,GAAyB,IAAI,CAAC;AAE5C,MAAM,UAAU,SAAS,CAAC,SAAwB;IAChD,UAAU,GAAG,EAAE,GAAG,SAAS,EAAE,CAAC;AAChC,CAAC;AAED,MAAM,UAAU,aAAa;IAC3B,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CACb,kEAAkE,CACnE,CAAC;IACJ,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,MAAM,UAAU,SAAS;IACvB,OAAO,kBAAkB,CAAC;AAC5B,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+import { setConfig } from "./config.js";
+import { upload, deleteFile } from "./s3.js";
+import { RRVaultConfig, UploadOptions, UploadResult, DeleteResult } from "./types.js";
+export declare class RRVault {
+    static config(config: RRVaultConfig): void;
+    static upload(file: any, fileName: string, options?: UploadOptions): Promise<UploadResult>;
+    static delete(key: string): Promise<DeleteResult>;
+}
+export { setConfig as config, upload, deleteFile };
+export type { RRVaultConfig, UploadOptions, UploadResult, DeleteResult };
+//# 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,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAEtF,qBAAa,OAAO;IAElB,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa;WAItB,MAAM,CACjB,IAAI,EAAE,GAAG,EACT,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,YAAY,CAAC;WAIX,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;CAGxD;AAED,OAAO,EACL,SAAS,IAAI,MAAM,EACnB,MAAM,EACN,UAAU,EACX,CAAC;AAEF,YAAY,EACV,aAAa,EACb,aAAa,EACb,YAAY,EACZ,YAAY,EACb,CAAC"}

package/dist/index.js

@@ -0,0 +1,15 @@
+import { setConfig } from "./config.js";
+import { upload, deleteFile } from "./s3.js";
+export class RRVault {
+    static config(config) {
+        setConfig(config);
+    }
+    static async upload(file, fileName, options = {}) {
+        return await upload(file, fileName, options);
+    }
+    static async delete(key) {
+        return await deleteFile(key);
+    }
+}
+export { setConfig as config, upload, deleteFile };
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAG7C,MAAM,OAAO,OAAO;IAElB,MAAM,CAAC,MAAM,CAAC,MAAqB;QACjC,SAAS,CAAC,MAAM,CAAC,CAAC;IACpB,CAAC;IAED,MAAM,CAAC,KAAK,CAAC,MAAM,CACjB,IAAS,EACT,QAAgB,EAChB,UAAyB,EAAE;QAE3B,OAAO,MAAM,MAAM,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC/C,CAAC;IAED,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,GAAW;QAC7B,OAAO,MAAM,UAAU,CAAC,GAAG,CAAC,CAAC;IAC/B,CAAC;CACF;AAED,OAAO,EACL,SAAS,IAAI,MAAM,EACnB,MAAM,EACN,UAAU,EACX,CAAC"}

package/dist/s3.d.ts

@@ -0,0 +1,10 @@
+import { UploadOptions, UploadResult, DeleteResult } from "./types.js";
+/**
+ * Upload a file to RR-Vault via backend proxy
+ */
+export declare function upload(file: any, fileName: string, options?: UploadOptions): Promise<UploadResult>;
+/**
+ * Delete a file from RR-Vault via backend proxy
+ */
+export declare function deleteFile(key: string): Promise<DeleteResult>;
+//# sourceMappingURL=s3.d.ts.map

package/dist/s3.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"s3.d.ts","sourceRoot":"","sources":["../src/s3.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAGvE;;GAEG;AACH,wBAAsB,MAAM,CAC1B,IAAI,EAAE,GAAG,EACT,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,YAAY,CAAC,CA+BvB;AAED;;GAEG;AACH,wBAAsB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAuBnE"}

package/dist/s3.js

@@ -0,0 +1,62 @@
+import axios from "axios";
+import { getUserConfig, getApiUrl } from "./config.js";
+/**
+ * Upload a file to RR-Vault via backend proxy
+ */
+export async function upload(file, fileName, options = {}) {
+    const config = getUserConfig();
+    const apiUrl = getApiUrl();
+    const formData = new FormData();
+    formData.append("file", file);
+    formData.append("fileName", fileName);
+    formData.append("appId", config.appId);
+    formData.append("apiKey", config.apiKey);
+    formData.append("secretKey", config.secretKey);
+    if (options.folder)
+        formData.append("folder", options.folder);
+    if (options.contentType)
+        formData.append("contentType", options.contentType);
+    if (options.cacheControl)
+        formData.append("cacheControl", options.cacheControl);
+    if (options.metadata) {
+        formData.append("metadata", JSON.stringify(options.metadata));
+    }
+    try {
+        const response = await axios.post(apiUrl, formData, {
+            headers: {
+                "Content-Type": "multipart/form-data",
+            },
+        });
+        return response.data;
+    }
+    catch (error) {
+        throw new Error(`RRVault Upload Failed: ${error.response?.data?.message || error.message}`);
+    }
+}
+/**
+ * Delete a file from RR-Vault via backend proxy
+ */
+export async function deleteFile(key) {
+    const config = getUserConfig();
+    const apiUrl = getApiUrl();
+    try {
+        const response = await axios({
+            method: "DELETE",
+            url: apiUrl,
+            data: {
+                key,
+                appId: config.appId,
+                apiKey: config.apiKey,
+                secretKey: config.secretKey,
+            },
+        });
+        return response.data;
+    }
+    catch (error) {
+        return {
+            success: false,
+            message: error.response?.data?.message || error.message || "Failed to delete file",
+        };
+    }
+}
+//# sourceMappingURL=s3.js.map

package/dist/s3.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"s3.js","sourceRoot":"","sources":["../src/s3.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAIvD;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,MAAM,CAC1B,IAAS,EACT,QAAgB,EAChB,UAAyB,EAAE;IAE3B,MAAM,MAAM,GAAG,aAAa,EAAE,CAAC;IAC/B,MAAM,MAAM,GAAG,SAAS,EAAE,CAAC;IAE3B,MAAM,QAAQ,GAAG,IAAI,QAAQ,EAAE,CAAC;IAChC,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAC9B,QAAQ,CAAC,MAAM,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;IACtC,QAAQ,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;IACvC,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;IACzC,QAAQ,CAAC,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC;IAE/C,IAAI,OAAO,CAAC,MAAM;QAAE,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IAC9D,IAAI,OAAO,CAAC,WAAW;QAAE,QAAQ,CAAC,MAAM,CAAC,aAAa,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;IAC7E,IAAI,OAAO,CAAC,YAAY;QAAE,QAAQ,CAAC,MAAM,CAAC,cAAc,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC;IAChF,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;QACrB,QAAQ,CAAC,MAAM,CAAC,UAAU,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;IAChE,CAAC;IAED,IAAI,CAAC;QACH,MAAM,QAAQ,GAAgC,MAAM,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,EAAE;YAC/E,OAAO,EAAE;gBACP,cAAc,EAAE,qBAAqB;aACtC;SACF,CAAC,CAAC;QAEH,OAAO,QAAQ,CAAC,IAAI,CAAC;IACvB,CAAC;IAAC,OAAO,KAAU,EAAE,CAAC;QACpB,MAAM,IAAI,KAAK,CACb,0BAA0B,KAAK,CAAC,QAAQ,EAAE,IAAI,EAAE,OAAO,IAAI,KAAK,CAAC,OAAO,EAAE,CAC3E,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,GAAW;IAC1C,MAAM,MAAM,GAAG,aAAa,EAAE,CAAC;IAC/B,MAAM,MAAM,GAAG,SAAS,EAAE,CAAC;IAE3B,IAAI,CAAC;QACH,MAAM,QAAQ,GAAgC,MAAM,KAAK,CAAC;YACxD,MAAM,EAAE,QAAQ;YAChB,GAAG,EAAE,MAAM;YACX,IAAI,EAAE;gBACJ,GAAG;gBACH,KAAK,EAAE,MAAM,CAAC,KAAK;gBACnB,MAAM,EAAE,MAAM,CAAC,MAAM;gBACrB,SAAS,EAAE,MAAM,CAAC,SAAS;aAC5B;SACF,CAAC,CAAC;QAEH,OAAO,QAAQ,CAAC,IAAI,CAAC;IACvB,CAAC;IAAC,OAAO,KAAU,EAAE,CAAC;QACpB,OAAO;YACL,OAAO,EAAE,KAAK;YACd,OAAO,EAAE,KAAK,CAAC,QAAQ,EAAE,IAAI,EAAE,OAAO,IAAI,KAAK,CAAC,OAAO,IAAI,uBAAuB;SACnF,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,21 @@
+export interface RRVaultConfig {
+    appId: string;
+    apiKey: string;
+    secretKey: string;
+}
+export interface UploadOptions {
+    folder?: string;
+    contentType?: string;
+    metadata?: Record<string, string>;
+    cacheControl?: string;
+}
+export interface UploadResult {
+    key: string;
+    url: string;
+    etag?: string;
+}
+export interface DeleteResult {
+    success: boolean;
+    message?: string;
+}
+//# 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,MAAM,WAAW,aAAa;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CAErB;AAED,MAAM,WAAW,aAAa;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,YAAY,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,YAAY;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,YAAY;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CACpB"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@rr-vault/r2",
+  "version": "1.0.0",
+  "description": "\"RR-Vault SDK is a developer-first cloud storage client for securely uploading, managing, and delivering files using API keys, app-based access, and scalable infrastructure.\"",
+  "keywords": [],
+  "homepage": "https://github.com/mdrezuanislamridoy/rr-vault-sdk#readme",
+  "bugs": {
+    "url": "https://github.com/mdrezuanislamridoy/rr-vault-sdk/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mdrezuanislamridoy/rr-vault-sdk.git"
+  },
+  "license": "ISC",
+  "author": "Ridoy781 <ridoy.babu.781@gmail.com>",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "typescript": "^6.0.2"
+  },
+  "dependencies": {
+    "axios": "^1.14.0"
+  }
+}