@bigbucket-ai/sdk 0.0.0-stage → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,260 @@
+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 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>;
+}
+
+/**
+ * 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 TransportConfig, UnsupportedFormatError, type UploadOptions, type UploadSession, type UploadStatus, UploadsResource, UsageResource, type UsageSummary };