@bigbucket-ai/sdk 0.0.0-stage → 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,353 @@
+interface TransportConfig {
+    apiKey: string;
+    baseUrl?: string | undefined;
+    timeout?: number | undefined;
+    fetch?: typeof fetch | undefined;
+}
+declare class HttpTransport {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    private readonly customFetch;
+    constructor(config: TransportConfig);
+    /**
+     * Execute an authenticated request against the BigBucket API.
+     */
+    request<T>(path: string, options?: RequestInit): Promise<T>;
+    /**
+     * 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.
+     */
+    uploadToPresignedUrl(uploadUrl: string, method: string, signedHeaders: Record<string, string>, body: BodyInit): Promise<void>;
+}
+
+/**
+ * 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 {
+    /**
+     * Secret project API key (e.g. bb_live_...).
+     * Must only be used in trusted server-side environments.
+     */
+    apiKey: string;
+    /**
+     * Base URL of the BigBucket API. Defaults to http://localhost:8000/api/v1 in local dev.
+     */
+    baseUrl?: string | undefined;
+    /**
+     * Request timeout in milliseconds. Defaults to 30,000 (30 seconds).
+     */
+    timeout?: number | undefined;
+    /**
+     * Optional custom fetch implementation (useful in testing or specialized runtimes).
+     */
+    fetch?: typeof fetch | undefined;
+}
+type FileInput = Uint8Array | ArrayBuffer | Blob | {
+    buffer: ArrayBuffer;
+} | string;
+interface UploadOptions {
+    /**
+     * Original file name (e.g. product.webp).
+     */
+    filename: string;
+    /**
+     * MIME content type (e.g. image/webp, image/jpeg, image/png, image/gif).
+     */
+    contentType: string;
+    /**
+     * File size in bytes (optional, computed automatically when possible).
+     */
+    fileSize?: number | undefined;
+}
+interface ImageVariant {
+    variantName: string;
+    url: string;
+    mimeType: string;
+    fileSize: number;
+    width: number;
+    height: number;
+    format: string;
+}
+interface ImageAsset {
+    id: string;
+    projectId: string;
+    url: string;
+    originalFilename: string;
+    mimeType: string;
+    fileSize: number;
+    width: number;
+    height: number;
+    format: ImageFormat;
+    status: ImageStatus;
+    createdAt: string;
+    updatedAt: string;
+    variants: ImageVariant[];
+}
+interface ImageListOptions {
+    page?: number | undefined;
+    pageSize?: number | undefined;
+    status?: ImageStatus | undefined;
+    format?: string | undefined;
+}
+interface Pagination {
+    total: number;
+    page: number;
+    pageSize: number;
+    hasNext: boolean;
+}
+interface PaginatedImages {
+    data: ImageAsset[];
+    pagination: Pagination;
+}
+interface PresignedDetails {
+    url: string;
+    method: string;
+    headers: Record<string, string>;
+}
+interface UploadSession {
+    uploadId: string;
+    objectKey: string;
+    presigned: PresignedDetails;
+    expiresAt: string;
+}
+interface UploadStatus {
+    id: string;
+    projectId: string;
+    objectKey: string;
+    expectedFileSize: number;
+    expectedMimeType: string;
+    status: string;
+    expiresAt: string;
+    createdAt: string;
+    completedAt: string | null;
+    assetId: string | null;
+}
+interface UsageSummary {
+    totalStoredBytes: number;
+    totalReadyImages: number;
+    successfulUploads: number;
+    deletedImages: number;
+}
+
+/**
+ * Images resource for listing, inspecting, and deleting media assets.
+ */
+
+declare class ImagesResource {
+    private readonly transport;
+    constructor(transport: HttpTransport);
+    private mapAsset;
+    /**
+     * Retrieve metadata and stable delivery URL for an image.
+     */
+    get(imageId: string): Promise<ImageAsset>;
+    /**
+     * List and paginate media assets belonging to the authenticated project.
+     */
+    list(options?: ImageListOptions): Promise<PaginatedImages>;
+    /**
+     * Delete an image from storage and mark it deleted in BigBucket.
+     */
+    delete(imageId: string): Promise<{
+        success: boolean;
+        id: string;
+    }>;
+}
+
+/**
+ * Uploads resource for managing upload sessions and finalization.
+ */
+
+declare class UploadsResource {
+    private readonly transport;
+    constructor(transport: HttpTransport);
+    /**
+     * Request permission and generate a presigned upload URL.
+     */
+    create(options: {
+        filename: string;
+        contentType: string;
+        fileSize: number;
+    }): Promise<UploadSession>;
+    /**
+     * Finalize an upload session once the client has uploaded bytes to the presigned URL.
+     */
+    complete(uploadId: string): Promise<ImageAsset>;
+    /**
+     * Check the status of an ongoing or completed upload session.
+     */
+    get(uploadId: string): Promise<UploadStatus>;
+}
+
+/**
+ * Usage resource for inspecting stored bytes, ready images, and upload metrics.
+ */
+
+declare class UsageResource {
+    private readonly transport;
+    constructor(transport: HttpTransport);
+    /**
+     * Retrieve usage metrics for a project or the account.
+     */
+    get(projectId?: string): Promise<UsageSummary>;
+}
+
+declare class BigBucket {
+    private readonly transport;
+    readonly images: ImagesResource;
+    readonly uploads: UploadsResource;
+    readonly usage: UsageResource;
+    constructor(options: BigBucketOptions);
+    /**
+     * Helper method to normalize arbitrary input types (Buffer, Uint8Array, Blob, etc.)
+     * and resolve byte length.
+     */
+    private resolveFileData;
+    /**
+     * 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.
+     */
+    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.
+ */
+interface BigBucketErrorOptions {
+    message: string;
+    statusCode?: number | undefined;
+    code?: string | undefined;
+    requestId?: string | undefined;
+    details?: unknown;
+    cause?: unknown;
+}
+declare class BigBucketError extends Error {
+    readonly statusCode: number;
+    readonly code: string;
+    readonly requestId: string | undefined;
+    readonly details: unknown;
+    readonly isRetryable: boolean;
+    constructor(options: BigBucketErrorOptions);
+}
+declare class AuthenticationError extends BigBucketError {
+    constructor(options: BigBucketErrorOptions);
+}
+declare class NotFoundError extends BigBucketError {
+    constructor(options: BigBucketErrorOptions);
+}
+declare class PayloadTooLargeError extends BigBucketError {
+    constructor(options: BigBucketErrorOptions);
+}
+declare class UnsupportedFormatError extends BigBucketError {
+    constructor(options: BigBucketErrorOptions);
+}
+declare class RateLimitError extends BigBucketError {
+    constructor(options: BigBucketErrorOptions);
+}
+declare class StorageUploadError extends BigBucketError {
+    constructor(message: string, cause?: unknown);
+}
+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 TransformFit, type TransformFormat, type TransformOptions, type TransportConfig, UnsupportedFormatError, type UploadOptions, type UploadSession, type UploadStatus, UploadsResource, UsageResource, type UsageSummary, buildTransformUrl };