@dcd-sdk/storage-client 0.0.0-stage → 1.0.1

package/dist/index.mjs

@@ -0,0 +1,394 @@
+// src/builder.ts
+var TransformationBuilder = class {
+  constructor(endpoint, publicId) {
+    this.options = {};
+    this.endpoint = endpoint.replace(/\/+$/, "");
+    this.publicId = publicId.replace(/^\/+/, "");
+  }
+  width(w) {
+    this.options.width = Math.round(w);
+    return this;
+  }
+  height(h) {
+    this.options.height = Math.round(h);
+    return this;
+  }
+  resize(params) {
+    if (params.width) this.options.width = Math.round(params.width);
+    if (params.height) this.options.height = Math.round(params.height);
+    if (params.crop) this.options.crop = params.crop;
+    return this;
+  }
+  crop(mode) {
+    this.options.crop = mode;
+    return this;
+  }
+  format(fmt) {
+    this.options.format = fmt;
+    return this;
+  }
+  quality(q) {
+    this.options.quality = q;
+    return this;
+  }
+  blur(sigma = 5) {
+    this.options.blur = sigma;
+    return this;
+  }
+  grayscale(enable = true) {
+    this.options.grayscale = enable;
+    return this;
+  }
+  sharpen(enable = true) {
+    this.options.sharpen = enable;
+    return this;
+  }
+  rotation(rot) {
+    this.options.rotation = rot;
+    return this;
+  }
+  /**
+   * Builds the formatted transformation string (e.g. w_400,h_300,c_fill,f_auto)
+   */
+  toParamsString() {
+    const parts = [];
+    if (this.options.width) parts.push(`w_${this.options.width}`);
+    if (this.options.height) parts.push(`h_${this.options.height}`);
+    if (this.options.crop) parts.push(`c_${this.options.crop}`);
+    if (this.options.format) parts.push(`f_${this.options.format}`);
+    if (this.options.quality) parts.push(`q_${this.options.quality}`);
+    if (this.options.blur) parts.push(`e_blur_${this.options.blur}`);
+    if (this.options.grayscale) parts.push("e_gray");
+    if (this.options.sharpen) parts.push("e_sharp");
+    if (this.options.rotation) parts.push(`r_${this.options.rotation}`);
+    return parts.length > 0 ? parts.join(",") : "original";
+  }
+  /**
+   * Returns the final full URL string
+   */
+  build() {
+    const params = this.toParamsString();
+    if (params === "original") {
+      return `${this.endpoint}/v1/image/${this.publicId}`;
+    }
+    return `${this.endpoint}/v1/image/${params}/${this.publicId}`;
+  }
+  toString() {
+    return this.build();
+  }
+};
+
+// src/errors.ts
+var DCDStorageError = class extends Error {
+  constructor(message, status, code, details) {
+    super(message);
+    this.name = "DCDStorageError";
+    this.status = status;
+    this.code = code;
+    this.details = details;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var AuthenticationError = class extends DCDStorageError {
+  constructor(message = "Authentication failed: Invalid or missing API key", status = 401, details) {
+    super(message, status, "AUTH_ERROR", details);
+    this.name = "AuthenticationError";
+  }
+};
+var NotFoundError = class extends DCDStorageError {
+  constructor(message = "Resource not found", status = 404, details) {
+    super(message, status, "NOT_FOUND", details);
+    this.name = "NotFoundError";
+  }
+};
+var PayloadTooLargeError = class extends DCDStorageError {
+  constructor(message = "File payload exceeds maximum permitted size", status = 413, details) {
+    super(message, status, "PAYLOAD_TOO_LARGE", details);
+    this.name = "PayloadTooLargeError";
+  }
+};
+var UploadError = class extends DCDStorageError {
+  constructor(message, status, details) {
+    super(message, status, "UPLOAD_ERROR", details);
+    this.name = "UploadError";
+  }
+};
+
+// src/client.ts
+var StorageClient = class {
+  constructor(config) {
+    if (!config || !config.endpoint) {
+      throw new Error("StorageClient: endpoint is required");
+    }
+    this.endpoint = config.endpoint.replace(/\/+$/, "");
+    this.apiKey = (config.apiKey || "").trim();
+    this.defaultTimeoutMs = config.timeoutMs || 3e4;
+  }
+  /**
+   * Initializes a fluent URL builder for on-the-fly CDN image transformations
+   */
+  url(publicId) {
+    return new TransformationBuilder(this.endpoint, publicId);
+  }
+  /**
+   * Checks the health and connectivity of the storage engine server
+   */
+  async healthCheck() {
+    const healthUrl = `${this.endpoint}/health`;
+    try {
+      const response = await this.fetchWithTimeout(healthUrl, { method: "GET" });
+      if (!response.ok) {
+        return { status: "error" };
+      }
+      return await response.json();
+    } catch {
+      return { status: "error" };
+    }
+  }
+  /**
+   * Retrieves server performance, storage, and cache statistics (requires authorized API key)
+   */
+  async getStats() {
+    const statsUrl = `${this.endpoint}/v1/admin/stats`;
+    const response = await this.fetchWithTimeout(statsUrl, {
+      method: "GET",
+      headers: this.getAuthHeaders()
+    });
+    const data = await this.parseJsonResponse(response);
+    return data.stats;
+  }
+  /**
+   * Lists files in the storage cluster with pagination and optional folder filter
+   */
+  async listFiles(options = {}) {
+    const url = new URL(`${this.endpoint}/v1/admin/files`);
+    if (options.page) url.searchParams.set("page", String(options.page));
+    if (options.limit) url.searchParams.set("limit", String(options.limit));
+    if (options.folder) url.searchParams.set("folder", options.folder);
+    const response = await this.fetchWithTimeout(url.toString(), {
+      method: "GET",
+      headers: this.getAuthHeaders()
+    });
+    return await this.parseJsonResponse(response);
+  }
+  /**
+   * Generates a short-lived cryptographically signed upload token for safe client-side browser/mobile uploads.
+   * Keeps master API keys strictly on backend servers.
+   */
+  async createSignedUploadToken(options = {}) {
+    if (!this.apiKey) {
+      throw new AuthenticationError("API key is required on backend to generate signed upload tokens.");
+    }
+    const signUrl = `${this.endpoint}/v1/upload/sign`;
+    const response = await this.fetchWithTimeout(signUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        ...this.getAuthHeaders()
+      },
+      body: JSON.stringify(options)
+    });
+    return await this.parseJsonResponse(response);
+  }
+  /**
+   * Directly uploads a file to the storage server.
+   * Supports:
+   *  - String file path (Node.js)
+   *  - Buffer / Uint8Array / ArrayBuffer
+   *  - File / Blob (Browser and universal runtimes)
+   * Auth:
+   *  - Master API Key OR Client Signed Upload Token (dcd_sig_...)
+   */
+  async upload(file, options = {}) {
+    const uploadUrl = `${this.endpoint}/v1/upload`;
+    const formData = new FormData();
+    let fileToAppend = file;
+    let filename = options.filename;
+    if (typeof file === "string") {
+      if (typeof process !== "undefined" && process.versions?.node) {
+        try {
+          const fs = await import("fs");
+          const path = await import("path");
+          if (fs.existsSync(file)) {
+            const buf = fs.readFileSync(file);
+            filename = filename || path.basename(file);
+            fileToAppend = new Blob([new Uint8Array(buf)]);
+          }
+        } catch {
+        }
+      }
+    } else if (typeof Buffer !== "undefined" && Buffer.isBuffer(file)) {
+      fileToAppend = new Blob([new Uint8Array(file)]);
+      filename = filename || "upload.bin";
+    } else if (file instanceof ArrayBuffer) {
+      fileToAppend = new Blob([new Uint8Array(file)]);
+      filename = filename || "upload.bin";
+    } else if (ArrayBuffer.isView(file)) {
+      fileToAppend = new Blob([new Uint8Array(file.buffer, file.byteOffset, file.byteLength)]);
+      filename = filename || "upload.bin";
+    }
+    if (filename) {
+      formData.append("file", fileToAppend, filename);
+    } else {
+      formData.append("file", fileToAppend);
+    }
+    if (options.folder) formData.append("folder", options.folder);
+    if (options.publicId) formData.append("public_id", options.publicId);
+    if (options.overwrite !== void 0) formData.append("overwrite", String(options.overwrite));
+    if (options.uniqueFilename !== void 0) formData.append("unique_filename", String(options.uniqueFilename));
+    const headers = {};
+    if (options.token) {
+      headers["X-Upload-Token"] = options.token;
+    } else if (this.apiKey) {
+      headers["Authorization"] = `Bearer ${this.apiKey}`;
+    } else {
+      throw new AuthenticationError("Either apiKey or a signed upload token must be provided to upload.");
+    }
+    if (typeof XMLHttpRequest !== "undefined" && options.onProgress) {
+      return new Promise((resolve, reject) => {
+        const xhr = new XMLHttpRequest();
+        xhr.open("POST", uploadUrl, true);
+        for (const [k, v] of Object.entries(headers)) {
+          xhr.setRequestHeader(k, v);
+        }
+        xhr.upload.onprogress = (e) => {
+          if (e.lengthComputable && options.onProgress) {
+            const percent = Math.round(e.loaded / e.total * 100);
+            options.onProgress(percent);
+          }
+        };
+        xhr.onload = () => {
+          let errData = null;
+          try {
+            const parsed = JSON.parse(xhr.responseText);
+            if (xhr.status >= 200 && xhr.status < 300) {
+              return resolve(parsed.asset || parsed);
+            }
+            errData = parsed;
+          } catch {
+          }
+          const msg = errData?.error?.message || `Upload failed with HTTP status ${xhr.status}`;
+          if (xhr.status === 401 || xhr.status === 403) {
+            return reject(new AuthenticationError(msg, xhr.status, errData));
+          }
+          if (xhr.status === 413) {
+            return reject(new PayloadTooLargeError(msg, xhr.status, errData));
+          }
+          reject(new UploadError(msg, xhr.status, errData));
+        };
+        xhr.onerror = () => reject(new UploadError("Network connection error during upload"));
+        xhr.ontimeout = () => reject(new UploadError("Upload request timed out"));
+        xhr.timeout = options.timeoutMs || this.defaultTimeoutMs;
+        xhr.send(formData);
+      });
+    }
+    const response = await this.fetchWithTimeout(
+      uploadUrl,
+      {
+        method: "POST",
+        headers,
+        body: formData
+      },
+      options.timeoutMs
+    );
+    const data = await this.parseJsonResponse(response);
+    return data.asset || data;
+  }
+  /**
+   * Helper method for frontend browser/mobile clients to upload using only a signed upload token (zero API key)
+   */
+  async uploadWithToken(file, token, options = {}) {
+    return this.upload(file, { ...options, token });
+  }
+  /**
+   * Permanently deletes a storage asset (requires API key with delete permissions)
+   */
+  async delete(publicId) {
+    const cleanPublicId = publicId.replace(/^\/+/, "");
+    const deleteUrl = `${this.endpoint}/v1/admin/files/${cleanPublicId}`;
+    const response = await this.fetchWithTimeout(deleteUrl, {
+      method: "DELETE",
+      headers: this.getAuthHeaders()
+    });
+    if (response.status === 404) {
+      throw new NotFoundError(`Asset '${cleanPublicId}' not found`);
+    }
+    if (response.status === 401 || response.status === 403) {
+      throw new AuthenticationError("Unauthorized to delete asset", response.status);
+    }
+    return response.ok;
+  }
+  // --- Private Helpers ---
+  getAuthHeaders() {
+    const headers = {};
+    if (this.apiKey) {
+      headers["Authorization"] = `Bearer ${this.apiKey}`;
+    }
+    return headers;
+  }
+  async fetchWithTimeout(url, init, customTimeoutMs) {
+    const timeout = customTimeoutMs || this.defaultTimeoutMs;
+    const controller = new AbortController();
+    const id = setTimeout(() => controller.abort(), timeout);
+    try {
+      const response = await fetch(url, {
+        ...init,
+        signal: controller.signal
+      });
+      return response;
+    } catch (err) {
+      if (err.name === "AbortError") {
+        throw new DCDStorageError(`Request timed out after ${timeout}ms`, 408, "REQUEST_TIMEOUT");
+      }
+      throw new DCDStorageError(`Network error: ${err.message}`, void 0, "NETWORK_ERROR");
+    } finally {
+      clearTimeout(id);
+    }
+  }
+  async parseJsonResponse(response) {
+    let data = null;
+    try {
+      data = await response.json();
+    } catch {
+      throw new DCDStorageError(
+        `Failed to parse server response with HTTP status ${response.status}`,
+        response.status
+      );
+    }
+    if (!response.ok) {
+      const msg = data?.error?.message || `Storage request failed with status ${response.status}`;
+      if (response.status === 401 || response.status === 403) {
+        throw new AuthenticationError(msg, response.status, data);
+      }
+      if (response.status === 404) {
+        throw new NotFoundError(msg, response.status, data);
+      }
+      if (response.status === 413) {
+        throw new PayloadTooLargeError(msg, response.status, data);
+      }
+      throw new DCDStorageError(msg, response.status, data?.error?.code, data);
+    }
+    return data;
+  }
+};
+function createStorageClient(config) {
+  return new StorageClient(config);
+}
+var BucketClient = StorageClient;
+var createBucketClient = createStorageClient;
+var MediaClient = StorageClient;
+var createMediaClient = createStorageClient;
+export {
+  AuthenticationError,
+  BucketClient,
+  DCDStorageError,
+  MediaClient,
+  NotFoundError,
+  PayloadTooLargeError,
+  StorageClient,
+  TransformationBuilder,
+  UploadError,
+  createBucketClient,
+  createMediaClient,
+  createStorageClient
+};

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@dcd-sdk/storage-client",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "Official Node.js & TypeScript client SDK for DevCloudDesk Storage Engine",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": {
+        "import": "./dist/index.d.mts",
+        "require": "./dist/index.d.ts",
+        "default": "./dist/index.d.ts"
+      },
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "default": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs --format esm --dts --clean",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "@types/node": "^20.17.19",
+    "tsup": "^9.0.0",
+    "typescript": "^5.7.3",
+    "vite": "^8.3.4",
+    "vitest": "^5.0.5"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/devclouddesk/dcd-sdk.git",
+    "directory": "packages/storage-client"
+  },
+  "keywords": [
+    "devclouddesk",
+    "storage",
+    "cdn",
+    "image-transformation",
+    "cloudinary-alternative",
+    "s3",
+    "bucket"
+  ],
+  "homepage": "https://devclouddesk.com",
+  "author": "DevCloudDesk Team <support@devclouddesk.com>",
+  "license": "MIT"
+}