@bigbucket-ai/sdk 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BigBucket
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,203 @@
-# Temporary Holding Version
+# @bigbucket-ai/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Official TypeScript and JavaScript SDK for [BigBucket](https://github.com/bigbucket/bigbucket) — the high-performance, developer-friendly image storage and management platform powered by Cloudflare R2 and FastAPI.
+
+---
+
+## What is BigBucket?
+
+BigBucket provides image infrastructure as a service. Instead of configuring S3 buckets, CORS policies, presigned URL signing algorithms, image optimization workers, and metadata databases in your application, you can integrate BigBucket in minutes.
+
+---
+
+## Installation
+
+```bash
+# npm
+npm install @bigbucket-ai/sdk
+
+# pnpm
+pnpm add @bigbucket-ai/sdk
+
+# yarn
+yarn add @bigbucket-ai/sdk
+```
+
+---
+
+## Getting Started
+
+### 1. Account & Project Setup
+1. Register your developer account on the BigBucket platform.
+2. Create a project representing your application (e.g. "My E-Commerce Website").
+3. Generate a secret API key for your project (`bb_live_...`).
+
+### 2. Environment Variables
+Store your API key in your server environment:
+```bash
+BIGBUCKET_API_KEY=bb_live_your_secret_api_key_here
+BIGBUCKET_API_URL=https://api.bigbucket.example.com/api/v1 # or http://localhost:8000/api/v1 for local dev
+```
+
+### 3. Client Initialization
+```typescript
+import { BigBucket } from "@bigbucket-ai/sdk";
+
+const bigbucket = new BigBucket({
+  apiKey: process.env.BIGBUCKET_API_KEY!,
+  baseUrl: process.env.BIGBUCKET_API_URL, // optional, defaults to http://localhost:8000/api/v1
+  timeout: 30000,                         // optional, request timeout in ms
+});
+```
+
+---
+
+## Core Features & Examples
+
+### 1. Uploading an Image
+Upload file buffers, `Uint8Array`, `ArrayBuffer`, or browser `Blob`/`File` instances. BigBucket automatically negotiates presigned S3/R2 direct upload URLs, performs content verification and Pillow image decode checks on the server, and returns a verified asset with its stable delivery URL.
+
+```typescript
+import fs from "node:fs/promises";
+
+const fileBuffer = await fs.readFile("./product.webp");
+
+const image = await bigbucket.upload(fileBuffer, {
+  filename: "product.webp",
+  contentType: "image/webp",
+});
+
+console.log("Image ID:", image.id);
+console.log("Delivery URL:", image.url);
+console.log("Dimensions:", `${image.width}x${image.height}`);
+console.log("Format:", image.format);
+```
+
+### 2. Retrieving Image Metadata
+```typescript
+const image = await bigbucket.images.get("image-uuid-123");
+console.log(image.status); // "ready"
+console.log(image.url);    // "https://images.example.com/..."
+```
+
+### 3. Listing & Paginating Images
+```typescript
+const response = await bigbucket.images.list({
+  page: 1,
+  pageSize: 20,
+  status: "ready",
+  format: "webp",
+});
+
+for (const img of response.data) {
+  console.log(img.id, img.url);
+}
+
+console.log("Total images:", response.pagination.total);
+console.log("Has next page:", response.pagination.hasNext);
+```
+
+### 4. Deleting an Image
+Deletes the object from storage (Cloudflare R2) and frees project usage accounting atomically:
+
+```typescript
+await bigbucket.images.delete("image-uuid-123");
+console.log("Image deleted successfully");
+```
+
+### 5. Inspecting Usage Statistics
+```typescript
+const usage = await bigbucket.usage.get("project-id");
+
+console.log(`Stored Bytes:   ${usage.totalStoredBytes}`);
+console.log(`Ready Images:   ${usage.totalReadyImages}`);
+console.log(`Total Uploads:  ${usage.successfulUploads}`);
+console.log(`Total Deletes:  ${usage.deletedImages}`);
+```
+
+---
+
+## Next.js Integration (App Router)
+
+The SDK must be executed on the server to keep your project API key secure.
+
+```typescript
+// app/api/upload/route.ts
+import { NextResponse } from "next/server";
+import { BigBucket, BigBucketError } from "@bigbucket-ai/sdk";
+
+const bigbucket = new BigBucket({
+  apiKey: process.env.BIGBUCKET_API_KEY!,
+});
+
+export async function POST(request: Request) {
+  try {
+    const formData = await request.formData();
+    const file = formData.get("file") as File | null;
+
+    if (!file) {
+      return NextResponse.json({ error: "Missing file" }, { status: 400 });
+    }
+
+    const arrayBuffer = await file.arrayBuffer();
+    const image = await bigbucket.upload(new Uint8Array(arrayBuffer), {
+      filename: file.name,
+      contentType: file.type || "image/png",
+      fileSize: file.size,
+    });
+
+    return NextResponse.json({ data: image });
+  } catch (error) {
+    if (error instanceof BigBucketError) {
+      return NextResponse.json(
+        { error: { code: error.code, message: error.message } },
+        { status: error.statusCode }
+      );
+    }
+    return NextResponse.json({ error: "Upload failed" }, { status: 500 });
+  }
+}
+```
+
+---
+
+## Error Handling
+
+All API errors throw typed subclasses of `BigBucketError`:
+
+```typescript
+import {
+  BigBucket,
+  AuthenticationError,
+  NotFoundError,
+  PayloadTooLargeError,
+  UnsupportedFormatError,
+  RateLimitError,
+} from "@bigbucket-ai/sdk";
+
+try {
+  await bigbucket.images.get("invalid-id");
+} catch (error) {
+  if (error instanceof AuthenticationError) {
+    console.error("Invalid or revoked API key");
+  } else if (error instanceof NotFoundError) {
+    console.error("Image was not found");
+  } else if (error instanceof PayloadTooLargeError) {
+    console.error("Image file exceeded maximum allowed size");
+  } else if (error instanceof UnsupportedFormatError) {
+    console.error("Format not supported (allowed: JPEG, PNG, WebP, GIF)");
+  } else if (error instanceof RateLimitError) {
+    console.error("Rate limit exceeded, retry later");
+  } else {
+    console.error("Unexpected BigBucket error:", error);
+  }
+}
+```
+
+---
+
+## Security Guidelines
+
+1. **Keep Keys Server-Side**: Never import or bundle `@bigbucket-ai/sdk` with a permanent `bb_live_...` key in client-side React, Vue, or browser scripts.
+2. **Key Rotation**: Rotate your keys regularly using `bigbucket.projects.apiKeys.rotate()` or the BigBucket console.
+3. **Restricted Tokens**: For direct client uploads from browsers, have your backend call `bigbucket.uploads.create()` and return only the temporary presigned upload URL to the browser.

package/dist/index.d.mts

@@ -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 };