@bigbucket-ai/sdk 0.1.0 → 0.2.0

package/README.md

@@ -97,7 +97,32 @@ console.log("Total images:", response.pagination.total);
 console.log("Has next page:", response.pagination.hasNext);
 ```
 
-### 4. Deleting an Image
+### 4. On-the-Fly Dynamic Image Transformations
+
+Generate optimized, responsive image delivery URLs without storing multiple sizes:
+
+```typescript
+import { buildTransformUrl } from "@bigbucket-ai/sdk";
+
+// 1. Resize width to 400px with 80% WebP compression
+const mobileUrl = buildTransformUrl(image.url, {
+  width: 400,
+  quality: 80,
+  format: "webp",
+});
+// -> "https://.../asset.png?w=400&q=80&fmt=webp"
+
+// 2. 1:1 aspect ratio square product crop
+const productCardUrl = buildTransformUrl(image.url, {
+  tr: "w-1280,ar-1200-1200,f-auto,q-80",
+});
+// -> "https://.../asset.png?tr=w-1280,ar-1200-1200,f-auto,q-80"
+
+// 3. Or use the method directly on your client instance:
+const thumbUrl = bigbucket.transformUrl(image.url, { w: 250, h: 250, fit: "cover" });
+```
+
+### 5. Deleting an Image
 Deletes the object from storage (Cloudflare R2) and frees project usage accounting atomically:
 
 ```typescript

package/dist/index.d.mts

@@ -25,6 +25,58 @@ declare class HttpTransport {
  * TypeScript types for @bigbucket-ai/sdk matching the BigBucket API.
  */
 type ImageFormat = "jpeg" | "png" | "webp" | "gif";
+type TransformFit = "cover" | "contain" | "scale";
+type TransformFormat = "auto" | "webp" | "jpeg" | "png";
+interface TransformOptions {
+    /**
+     * Target width in pixels (1 to 4096).
+     */
+    width?: number | undefined;
+    /**
+     * Alias for width.
+     */
+    w?: number | undefined;
+    /**
+     * Target height in pixels (1 to 4096).
+     */
+    height?: number | undefined;
+    /**
+     * Alias for height.
+     */
+    h?: number | undefined;
+    /**
+     * Fit mode for resizing:
+     * - 'cover': Smart crop preserving aspect ratio to exact dimensions without distortion.
+     * - 'contain': Shrink to fit inside bounding box maintaining aspect ratio.
+     * - 'scale': Direct scale to width and height.
+     */
+    fit?: TransformFit | undefined;
+    /**
+     * Compression quality from 1 to 100 (default: 85).
+     */
+    quality?: number | undefined;
+    /**
+     * Alias for quality.
+     */
+    q?: number | undefined;
+    /**
+     * Target output format:
+     * - 'auto': Automatically negotiates next-gen WebP for supported browsers.
+     * - 'webp': Convert to WebP.
+     * - 'jpeg': Convert to JPEG.
+     * - 'png': Convert to PNG.
+     */
+    format?: TransformFormat | undefined;
+    /**
+     * Alias for format.
+     */
+    fmt?: TransformFormat | undefined;
+    /**
+     * Transformation shorthand string.
+     * Example: 'w-1280,ar-1200-1200,f-auto,q-80'
+     */
+    tr?: string | undefined;
+}
 type ImageStatus = "pending" | "processing" | "ready" | "failed" | "deleted";
 interface BigBucketOptions {
     /**
@@ -214,8 +266,49 @@ declare class BigBucket {
      * 4. Returns verified ImageAsset with delivery URL.
      */
     upload(file: FileInput, options: UploadOptions): Promise<ImageAsset>;
+    /**
+     * 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: string, options?: TransformOptions): string;
 }
 
+/**
+ * Image transformation utilities for BigBucket.
+ * Supports URL construction for on-the-fly resizing, cropping, compression,
+ * format conversion, and shorthand transforms.
+ */
+
+/**
+ * Build an optimized, transformed image delivery URL.
+ *
+ * @param baseUrl The stable public delivery URL of the image asset.
+ * @param options Transformation parameters (width, height, fit, quality, format, or 'tr' shorthand).
+ * @returns Fully formatted URL with query parameters.
+ *
+ * @example
+ * ```ts
+ * import { buildTransformUrl } from "@bigbucket-ai/sdk";
+ *
+ * // Resize to 400px width with 80% WebP compression
+ * const thumbUrl = buildTransformUrl(image.url, {
+ *   width: 400,
+ *   quality: 80,
+ *   format: "webp",
+ * });
+ * // -> "https://.../asset.png?w=400&q=80&fmt=webp"
+ *
+ * // 1:1 aspect ratio square crop
+ * const squareUrl = buildTransformUrl(image.url, {
+ *   tr: "w-1280,ar-1200-1200,f-auto,q-80",
+ * });
+ * // -> "https://.../asset.png?tr=w-1280,ar-1200-1200,f-auto,q-80"
+ * ```
+ */
+declare function buildTransformUrl(baseUrl: string, options?: TransformOptions): string;
+
 /**
  * Typed Error hierarchy for BigBucket SDK.
  */
@@ -257,4 +350,4 @@ declare class TimeoutError extends BigBucketError {
     constructor(message?: string);
 }
 
-export { AuthenticationError, BigBucket, BigBucketError, type BigBucketErrorOptions, type BigBucketOptions, type FileInput, HttpTransport, type ImageAsset, type ImageFormat, type ImageListOptions, type ImageStatus, type ImageVariant, ImagesResource, NotFoundError, type PaginatedImages, type Pagination, PayloadTooLargeError, type PresignedDetails, RateLimitError, StorageUploadError, TimeoutError, type TransportConfig, UnsupportedFormatError, type UploadOptions, type UploadSession, type UploadStatus, UploadsResource, UsageResource, type UsageSummary };
+export { AuthenticationError, BigBucket, BigBucketError, type BigBucketErrorOptions, type BigBucketOptions, type FileInput, HttpTransport, type ImageAsset, type ImageFormat, type ImageListOptions, type ImageStatus, type ImageVariant, ImagesResource, NotFoundError, type PaginatedImages, type Pagination, PayloadTooLargeError, type PresignedDetails, RateLimitError, StorageUploadError, TimeoutError, type TransformFit, type TransformFormat, type TransformOptions, type TransportConfig, UnsupportedFormatError, type UploadOptions, type UploadSession, type UploadStatus, UploadsResource, UsageResource, type UsageSummary, buildTransformUrl };

package/dist/index.d.ts

@@ -25,6 +25,58 @@ declare class HttpTransport {
  * TypeScript types for @bigbucket-ai/sdk matching the BigBucket API.
  */
 type ImageFormat = "jpeg" | "png" | "webp" | "gif";
+type TransformFit = "cover" | "contain" | "scale";
+type TransformFormat = "auto" | "webp" | "jpeg" | "png";
+interface TransformOptions {
+    /**
+     * Target width in pixels (1 to 4096).
+     */
+    width?: number | undefined;
+    /**
+     * Alias for width.
+     */
+    w?: number | undefined;
+    /**
+     * Target height in pixels (1 to 4096).
+     */
+    height?: number | undefined;
+    /**
+     * Alias for height.
+     */
+    h?: number | undefined;
+    /**
+     * Fit mode for resizing:
+     * - 'cover': Smart crop preserving aspect ratio to exact dimensions without distortion.
+     * - 'contain': Shrink to fit inside bounding box maintaining aspect ratio.
+     * - 'scale': Direct scale to width and height.
+     */
+    fit?: TransformFit | undefined;
+    /**
+     * Compression quality from 1 to 100 (default: 85).
+     */
+    quality?: number | undefined;
+    /**
+     * Alias for quality.
+     */
+    q?: number | undefined;
+    /**
+     * Target output format:
+     * - 'auto': Automatically negotiates next-gen WebP for supported browsers.
+     * - 'webp': Convert to WebP.
+     * - 'jpeg': Convert to JPEG.
+     * - 'png': Convert to PNG.
+     */
+    format?: TransformFormat | undefined;
+    /**
+     * Alias for format.
+     */
+    fmt?: TransformFormat | undefined;
+    /**
+     * Transformation shorthand string.
+     * Example: 'w-1280,ar-1200-1200,f-auto,q-80'
+     */
+    tr?: string | undefined;
+}
 type ImageStatus = "pending" | "processing" | "ready" | "failed" | "deleted";
 interface BigBucketOptions {
     /**
@@ -214,8 +266,49 @@ declare class BigBucket {
      * 4. Returns verified ImageAsset with delivery URL.
      */
     upload(file: FileInput, options: UploadOptions): Promise<ImageAsset>;
+    /**
+     * 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: string, options?: TransformOptions): string;
 }
 
+/**
+ * Image transformation utilities for BigBucket.
+ * Supports URL construction for on-the-fly resizing, cropping, compression,
+ * format conversion, and shorthand transforms.
+ */
+
+/**
+ * Build an optimized, transformed image delivery URL.
+ *
+ * @param baseUrl The stable public delivery URL of the image asset.
+ * @param options Transformation parameters (width, height, fit, quality, format, or 'tr' shorthand).
+ * @returns Fully formatted URL with query parameters.
+ *
+ * @example
+ * ```ts
+ * import { buildTransformUrl } from "@bigbucket-ai/sdk";
+ *
+ * // Resize to 400px width with 80% WebP compression
+ * const thumbUrl = buildTransformUrl(image.url, {
+ *   width: 400,
+ *   quality: 80,
+ *   format: "webp",
+ * });
+ * // -> "https://.../asset.png?w=400&q=80&fmt=webp"
+ *
+ * // 1:1 aspect ratio square crop
+ * const squareUrl = buildTransformUrl(image.url, {
+ *   tr: "w-1280,ar-1200-1200,f-auto,q-80",
+ * });
+ * // -> "https://.../asset.png?tr=w-1280,ar-1200-1200,f-auto,q-80"
+ * ```
+ */
+declare function buildTransformUrl(baseUrl: string, options?: TransformOptions): string;
+
 /**
  * Typed Error hierarchy for BigBucket SDK.
  */
@@ -257,4 +350,4 @@ declare class TimeoutError extends BigBucketError {
     constructor(message?: string);
 }
 
-export { AuthenticationError, BigBucket, BigBucketError, type BigBucketErrorOptions, type BigBucketOptions, type FileInput, HttpTransport, type ImageAsset, type ImageFormat, type ImageListOptions, type ImageStatus, type ImageVariant, ImagesResource, NotFoundError, type PaginatedImages, type Pagination, PayloadTooLargeError, type PresignedDetails, RateLimitError, StorageUploadError, TimeoutError, type TransportConfig, UnsupportedFormatError, type UploadOptions, type UploadSession, type UploadStatus, UploadsResource, UsageResource, type UsageSummary };
+export { AuthenticationError, BigBucket, BigBucketError, type BigBucketErrorOptions, type BigBucketOptions, type FileInput, HttpTransport, type ImageAsset, type ImageFormat, type ImageListOptions, type ImageStatus, type ImageVariant, ImagesResource, NotFoundError, type PaginatedImages, type Pagination, PayloadTooLargeError, type PresignedDetails, RateLimitError, StorageUploadError, TimeoutError, type TransformFit, type TransformFormat, type TransformOptions, type TransportConfig, UnsupportedFormatError, type UploadOptions, type UploadSession, type UploadStatus, UploadsResource, UsageResource, type UsageSummary, buildTransformUrl };

package/dist/index.js

@@ -32,7 +32,8 @@ __export(index_exports, {
   TimeoutError: () => TimeoutError,
   UnsupportedFormatError: () => UnsupportedFormatError,
   UploadsResource: () => UploadsResource,
-  UsageResource: () => UsageResource
+  UsageResource: () => UsageResource,
+  buildTransformUrl: () => buildTransformUrl
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -428,6 +429,36 @@ var UsageResource = class {
   }
 };
 
+// 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;
@@ -496,6 +527,15 @@ var BigBucket = class {
     );
     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);
+  }
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
@@ -511,5 +551,6 @@ var BigBucket = class {
   TimeoutError,
   UnsupportedFormatError,
   UploadsResource,
-  UsageResource
+  UsageResource,
+  buildTransformUrl
 });

package/dist/index.mjs

@@ -390,6 +390,36 @@ var UsageResource = class {
   }
 };
 
+// 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;
@@ -458,6 +488,15 @@ var BigBucket = class {
     );
     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,
@@ -472,5 +511,6 @@ export {
   TimeoutError,
   UnsupportedFormatError,
   UploadsResource,
-  UsageResource
+  UsageResource,
+  buildTransformUrl
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bigbucket-ai/sdk",
-  "version": "0.1.0",
+  "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",