@bigbucket-ai/sdk 0.0.0-stage → 0.2.0

package/dist/index.mjs

@@ -0,0 +1,516 @@
+// src/errors.ts
+var BigBucketError = class extends Error {
+  statusCode;
+  code;
+  requestId;
+  details;
+  isRetryable;
+  constructor(options) {
+    super(options.message);
+    this.name = "BigBucketError";
+    this.statusCode = options.statusCode ?? 500;
+    this.code = options.code ?? "INTERNAL_SERVER_ERROR";
+    this.requestId = options.requestId;
+    this.details = options.details;
+    this.cause = options.cause;
+    this.isRetryable = this.statusCode === 429 || this.statusCode >= 500 && this.statusCode <= 599;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var AuthenticationError = class extends BigBucketError {
+  constructor(options) {
+    super({ ...options, statusCode: options.statusCode ?? 401 });
+    this.name = "AuthenticationError";
+  }
+};
+var NotFoundError = class extends BigBucketError {
+  constructor(options) {
+    super({ ...options, statusCode: 404 });
+    this.name = "NotFoundError";
+  }
+};
+var PayloadTooLargeError = class extends BigBucketError {
+  constructor(options) {
+    super({ ...options, statusCode: 413 });
+    this.name = "PayloadTooLargeError";
+  }
+};
+var UnsupportedFormatError = class extends BigBucketError {
+  constructor(options) {
+    super({ ...options, statusCode: 415 });
+    this.name = "UnsupportedFormatError";
+  }
+};
+var RateLimitError = class extends BigBucketError {
+  constructor(options) {
+    super({ ...options, statusCode: 429 });
+    this.name = "RateLimitError";
+  }
+};
+var StorageUploadError = class extends BigBucketError {
+  constructor(message, cause) {
+    super({
+      message,
+      statusCode: 502,
+      code: "STORAGE_UPLOAD_FAILED",
+      cause
+    });
+    this.name = "StorageUploadError";
+  }
+};
+var TimeoutError = class extends BigBucketError {
+  constructor(message = "Request timed out") {
+    super({
+      message,
+      statusCode: 408,
+      code: "REQUEST_TIMEOUT"
+    });
+    this.name = "TimeoutError";
+  }
+};
+
+// src/http/transport.ts
+var HttpTransport = class {
+  apiKey;
+  baseUrl;
+  timeout;
+  customFetch;
+  constructor(config) {
+    if (!config.apiKey || typeof config.apiKey !== "string") {
+      throw new Error("A valid BigBucket API key is required (e.g. bb_live_...)");
+    }
+    this.apiKey = config.apiKey.trim();
+    this.baseUrl = (config.baseUrl || "http://localhost:8000/api/v1").replace(/\/+$/, "");
+    this.timeout = config.timeout ?? 3e4;
+    this.customFetch = config.fetch ?? globalThis.fetch;
+    if (!this.customFetch) {
+      throw new Error("No native fetch implementation found. Pass a custom fetch in options.");
+    }
+  }
+  /**
+   * Execute an authenticated request against the BigBucket API.
+   */
+  async request(path, options = {}) {
+    const url = `${this.baseUrl}${path.startsWith("/") ? "" : "/"}${path}`;
+    const headers = {
+      Accept: "application/json",
+      "X-API-Key": this.apiKey,
+      ...options.headers
+    };
+    if (options.body && typeof options.body === "string" && !headers["Content-Type"]) {
+      headers["Content-Type"] = "application/json";
+    }
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    let response;
+    try {
+      response = await this.customFetch(url, {
+        ...options,
+        headers,
+        signal: controller.signal
+      });
+    } catch (err) {
+      clearTimeout(timeoutId);
+      if (err instanceof Error && err.name === "AbortError") {
+        throw new TimeoutError(`Request timed out after ${this.timeout}ms`);
+      }
+      throw new BigBucketError({
+        message: `Network request failed: ${err instanceof Error ? err.message : String(err)}`,
+        statusCode: 0,
+        cause: err
+      });
+    } finally {
+      clearTimeout(timeoutId);
+    }
+    const requestId = response.headers.get("X-Request-ID") ?? void 0;
+    let responseBody = null;
+    const contentType = response.headers.get("content-type");
+    if (contentType && contentType.includes("application/json")) {
+      try {
+        responseBody = await response.json();
+      } catch {
+      }
+    }
+    if (!response.ok) {
+      const errPayload = responseBody?.error ?? {};
+      const message = errPayload.message || `Request failed with status ${response.status}`;
+      const code = errPayload.code || "REQUEST_FAILED";
+      const details = errPayload.details;
+      const errorOptions = {
+        message,
+        statusCode: response.status,
+        code,
+        requestId: errPayload.request_id || requestId,
+        details
+      };
+      if (response.status === 401) throw new AuthenticationError(errorOptions);
+      if (response.status === 404) throw new NotFoundError(errorOptions);
+      if (response.status === 413) throw new PayloadTooLargeError(errorOptions);
+      if (response.status === 415) throw new UnsupportedFormatError(errorOptions);
+      if (response.status === 429) throw new RateLimitError(errorOptions);
+      throw new BigBucketError(errorOptions);
+    }
+    return responseBody;
+  }
+  /**
+   * Upload binary data directly to the storage provider (Cloudflare R2 or Local Storage).
+   * Note: Permanent BigBucket credentials MUST NOT be forwarded to the storage provider.
+   */
+  async uploadToPresignedUrl(uploadUrl, method, signedHeaders, body) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout * 2);
+    try {
+      const response = await this.customFetch(uploadUrl, {
+        method: method || "PUT",
+        headers: signedHeaders,
+        body,
+        signal: controller.signal
+      });
+      if (!response.ok) {
+        throw new StorageUploadError(
+          `Direct storage upload failed with status ${response.status} ${response.statusText}`
+        );
+      }
+    } catch (err) {
+      clearTimeout(timeoutId);
+      if (err instanceof BigBucketError) {
+        throw err;
+      }
+      if (err instanceof Error && err.name === "AbortError") {
+        throw new TimeoutError(`Direct storage upload timed out after ${this.timeout * 2}ms`);
+      }
+      throw new StorageUploadError(
+        `Failed to upload image bytes to storage provider: ${err instanceof Error ? err.message : String(err)}`,
+        err
+      );
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+};
+
+// src/resources/images.ts
+var ImagesResource = class {
+  constructor(transport) {
+    this.transport = transport;
+  }
+  transport;
+  mapAsset(d) {
+    return {
+      id: d.id,
+      projectId: d.project_id,
+      url: d.url,
+      originalFilename: d.original_filename,
+      mimeType: d.mime_type,
+      fileSize: d.file_size,
+      width: d.width,
+      height: d.height,
+      format: d.format,
+      status: d.status,
+      createdAt: d.created_at,
+      updatedAt: d.updated_at,
+      variants: (d.variants || []).map((v) => ({
+        variantName: v.variant_name,
+        url: v.url,
+        mimeType: v.mime_type,
+        fileSize: v.file_size,
+        width: v.width,
+        height: v.height,
+        format: v.format
+      }))
+    };
+  }
+  /**
+   * Retrieve metadata and stable delivery URL for an image.
+   */
+  async get(imageId) {
+    const res = await this.transport.request(
+      `/images/${encodeURIComponent(imageId)}`,
+      {
+        method: "GET"
+      }
+    );
+    return this.mapAsset(res.data);
+  }
+  /**
+   * List and paginate media assets belonging to the authenticated project.
+   */
+  async list(options = {}) {
+    const params = new URLSearchParams();
+    if (options.page !== void 0) params.set("page", String(options.page));
+    if (options.pageSize !== void 0) params.set("page_size", String(options.pageSize));
+    if (options.status !== void 0) params.set("status", options.status);
+    if (options.format !== void 0) params.set("format", options.format);
+    const query = params.toString() ? `?${params.toString()}` : "";
+    const res = await this.transport.request(
+      `/images${query}`,
+      {
+        method: "GET"
+      }
+    );
+    return {
+      data: (res.data || []).map((item) => this.mapAsset(item)),
+      pagination: {
+        total: res.pagination.total,
+        page: res.pagination.page,
+        pageSize: res.pagination.page_size,
+        hasNext: res.pagination.has_next
+      }
+    };
+  }
+  /**
+   * Delete an image from storage and mark it deleted in BigBucket.
+   */
+  async delete(imageId) {
+    const res = await this.transport.request(
+      `/images/${encodeURIComponent(imageId)}`,
+      {
+        method: "DELETE"
+      }
+    );
+    return {
+      success: true,
+      id: res.data.id
+    };
+  }
+};
+
+// src/resources/uploads.ts
+var UploadsResource = class {
+  constructor(transport) {
+    this.transport = transport;
+  }
+  transport;
+  /**
+   * Request permission and generate a presigned upload URL.
+   */
+  async create(options) {
+    const res = await this.transport.request("/uploads", {
+      method: "POST",
+      body: JSON.stringify({
+        filename: options.filename,
+        content_type: options.contentType,
+        file_size: options.fileSize
+      })
+    });
+    const d = res.data;
+    return {
+      uploadId: d.upload_id,
+      objectKey: d.object_key,
+      presigned: {
+        url: d.presigned.url,
+        method: d.presigned.method,
+        headers: d.presigned.headers
+      },
+      expiresAt: d.expires_at
+    };
+  }
+  /**
+   * Finalize an upload session once the client has uploaded bytes to the presigned URL.
+   */
+  async complete(uploadId) {
+    const res = await this.transport.request(
+      `/uploads/${encodeURIComponent(uploadId)}/complete`,
+      {
+        method: "POST"
+      }
+    );
+    const d = res.data;
+    return {
+      id: d.id,
+      projectId: d.project_id,
+      url: d.url,
+      originalFilename: d.original_filename,
+      mimeType: d.mime_type,
+      fileSize: d.file_size,
+      width: d.width,
+      height: d.height,
+      format: d.format,
+      status: d.status,
+      createdAt: d.created_at,
+      updatedAt: d.updated_at,
+      variants: (d.variants || []).map((v) => ({
+        variantName: v.variant_name,
+        url: v.url,
+        mimeType: v.mime_type,
+        fileSize: v.file_size,
+        width: v.width,
+        height: v.height,
+        format: v.format
+      }))
+    };
+  }
+  /**
+   * Check the status of an ongoing or completed upload session.
+   */
+  async get(uploadId) {
+    const res = await this.transport.request(
+      `/uploads/${encodeURIComponent(uploadId)}`,
+      {
+        method: "GET"
+      }
+    );
+    const d = res.data;
+    return {
+      id: d.id,
+      projectId: d.project_id,
+      objectKey: d.object_key,
+      expectedFileSize: d.expected_file_size,
+      expectedMimeType: d.expected_mime_type,
+      status: d.status,
+      expiresAt: d.expires_at,
+      createdAt: d.created_at,
+      completedAt: d.completed_at ?? null,
+      assetId: d.asset_id ?? null
+    };
+  }
+};
+
+// src/resources/usage.ts
+var UsageResource = class {
+  constructor(transport) {
+    this.transport = transport;
+  }
+  transport;
+  /**
+   * Retrieve usage metrics for a project or the account.
+   */
+  async get(projectId) {
+    const path = projectId ? `/projects/${encodeURIComponent(projectId)}/usage` : "/usage";
+    const res = await this.transport.request(path, {
+      method: "GET"
+    });
+    const d = res.data;
+    return {
+      totalStoredBytes: d.total_stored_bytes,
+      totalReadyImages: d.total_ready_images,
+      successfulUploads: d.successful_uploads,
+      deletedImages: d.deleted_images
+    };
+  }
+};
+
+// src/transform.ts
+function buildTransformUrl(baseUrl, options) {
+  if (!baseUrl) return "";
+  if (!options || Object.keys(options).length === 0) return baseUrl;
+  const url = new URL(baseUrl);
+  if (options.tr) {
+    url.searchParams.set("tr", options.tr);
+  }
+  const w = options.width ?? options.w;
+  if (w !== void 0) {
+    url.searchParams.set("w", String(w));
+  }
+  const h = options.height ?? options.h;
+  if (h !== void 0) {
+    url.searchParams.set("h", String(h));
+  }
+  if (options.fit) {
+    url.searchParams.set("fit", options.fit);
+  }
+  const q = options.quality ?? options.q;
+  if (q !== void 0) {
+    url.searchParams.set("q", String(q));
+  }
+  const fmt = options.format ?? options.fmt;
+  if (fmt) {
+    url.searchParams.set("fmt", fmt);
+  }
+  return url.toString();
+}
+
+// src/client.ts
+var BigBucket = class {
+  transport;
+  images;
+  uploads;
+  usage;
+  constructor(options) {
+    this.transport = new HttpTransport({
+      apiKey: options.apiKey,
+      baseUrl: options.baseUrl,
+      timeout: options.timeout,
+      fetch: options.fetch
+    });
+    this.images = new ImagesResource(this.transport);
+    this.uploads = new UploadsResource(this.transport);
+    this.usage = new UsageResource(this.transport);
+  }
+  /**
+   * Helper method to normalize arbitrary input types (Buffer, Uint8Array, Blob, etc.)
+   * and resolve byte length.
+   */
+  resolveFileData(file, explicitSize) {
+    if (typeof Blob !== "undefined" && file instanceof Blob) {
+      return { body: file, size: explicitSize ?? file.size };
+    }
+    if (file instanceof ArrayBuffer) {
+      return { body: file, size: explicitSize ?? file.byteLength };
+    }
+    if (file instanceof Uint8Array) {
+      return { body: file, size: explicitSize ?? file.byteLength };
+    }
+    if (typeof file === "object" && file !== null && "buffer" in file && file.buffer instanceof ArrayBuffer) {
+      const buffer = file.buffer;
+      return { body: buffer, size: explicitSize ?? buffer.byteLength };
+    }
+    if (typeof file === "string") {
+      const encoded = new TextEncoder().encode(file);
+      return { body: encoded, size: explicitSize ?? encoded.byteLength };
+    }
+    if (explicitSize !== void 0) {
+      return { body: file, size: explicitSize };
+    }
+    throw new Error(
+      "Unable to determine file size. Please provide 'options.fileSize' explicitly."
+    );
+  }
+  /**
+   * Complete end-to-end image upload workflow:
+   * 1. Requests an upload session and receives presigned storage URL.
+   * 2. Uploads binary data directly to the storage provider (Cloudflare R2).
+   * 3. Finalizes the upload with server verification and content inspection.
+   * 4. Returns verified ImageAsset with delivery URL.
+   */
+  async upload(file, options) {
+    const { body, size } = this.resolveFileData(file, options.fileSize);
+    const session = await this.uploads.create({
+      filename: options.filename,
+      contentType: options.contentType,
+      fileSize: size
+    });
+    await this.transport.uploadToPresignedUrl(
+      session.presigned.url,
+      session.presigned.method,
+      session.presigned.headers,
+      body
+    );
+    return await this.uploads.complete(session.uploadId);
+  }
+  /**
+   * Helper method to generate an optimized, transformed image delivery URL.
+   *
+   * @param baseUrl The original delivery URL of the image asset.
+   * @param options Dynamic transformation parameters (width, height, quality, format, or Zepto shorthand).
+   */
+  transformUrl(baseUrl, options) {
+    return buildTransformUrl(baseUrl, options);
+  }
+};
+export {
+  AuthenticationError,
+  BigBucket,
+  BigBucketError,
+  HttpTransport,
+  ImagesResource,
+  NotFoundError,
+  PayloadTooLargeError,
+  RateLimitError,
+  StorageUploadError,
+  TimeoutError,
+  UnsupportedFormatError,
+  UploadsResource,
+  UsageResource,
+  buildTransformUrl
+};

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@bigbucket-ai/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Official TypeScript/JavaScript SDK for the BigBucket Image Storage and Management Platform",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "test": "vitest run",
+    "type-check": "tsc --noEmit",
+    "lint": "eslint src/ --ext .ts"
+  },
+  "keywords": [
+    "bigbucket",
+    "image-storage",
+    "image-upload",
+    "r2",
+    "cloudflare-r2",
+    "fastapi",
+    "sdk"
+  ],
+  "author": "BigBucket Team",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "tsup": "^8.1.0",
+    "typescript": "^5.4.5",
+    "vitest": "^1.6.0"
+  }
+}