@marlinjai/storage-brain-sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,367 @@
+/**
+ * Allowed MIME types for file uploads
+ */
+declare const ALLOWED_FILE_TYPES: {
+    readonly 'image/jpeg': {
+        readonly extension: "jpg";
+        readonly category: "image";
+    };
+    readonly 'image/png': {
+        readonly extension: "png";
+        readonly category: "image";
+    };
+    readonly 'image/webp': {
+        readonly extension: "webp";
+        readonly category: "image";
+    };
+    readonly 'image/gif': {
+        readonly extension: "gif";
+        readonly category: "image";
+    };
+    readonly 'image/avif': {
+        readonly extension: "avif";
+        readonly category: "image";
+    };
+    readonly 'application/pdf': {
+        readonly extension: "pdf";
+        readonly category: "document";
+    };
+};
+type AllowedMimeType = keyof typeof ALLOWED_FILE_TYPES;
+declare const ALLOWED_MIME_TYPES: AllowedMimeType[];
+declare const IMAGE_MIME_TYPES: ("image/jpeg" | "image/png" | "image/webp" | "image/gif" | "image/avif" | "application/pdf")[];
+declare const DOCUMENT_MIME_TYPES: ("image/jpeg" | "image/png" | "image/webp" | "image/gif" | "image/avif" | "application/pdf")[];
+/**
+ * Processing contexts
+ */
+declare const PROCESSING_CONTEXTS: readonly ["newsletter", "invoice", "framer-site", "default"];
+type ProcessingContext = (typeof PROCESSING_CONTEXTS)[number];
+/**
+ * File size limits
+ */
+declare const MAX_FILE_SIZE_BYTES: number;
+/**
+ * Thumbnail sizes
+ */
+declare const THUMBNAIL_SIZES: {
+    readonly thumb: {
+        readonly width: 200;
+        readonly height: 200;
+    };
+    readonly medium: {
+        readonly width: 400;
+        readonly height: 400;
+    };
+    readonly large: {
+        readonly width: 800;
+        readonly height: 800;
+    };
+};
+type ThumbnailSize = keyof typeof THUMBNAIL_SIZES;
+/**
+ * Processing statuses
+ */
+declare const PROCESSING_STATUSES: readonly ["pending", "processing", "completed", "failed"];
+type ProcessingStatus = (typeof PROCESSING_STATUSES)[number];
+
+/**
+ * File metadata (stored as JSON)
+ */
+interface FileMetadata {
+    thumbnailUrls?: ThumbnailUrls;
+    ocrData?: OcrResult;
+    imageInfo?: ImageInfo;
+    processingError?: string;
+    [key: string]: unknown;
+}
+/**
+ * Thumbnail URLs for different sizes
+ */
+type ThumbnailUrls = {
+    [K in ThumbnailSize]?: string;
+};
+/**
+ * OCR result from Google Cloud Vision
+ */
+interface OcrResult {
+    fullText: string;
+    confidence: number;
+    blocks: OcrBlock[];
+}
+interface OcrBlock {
+    text: string;
+    confidence: number;
+    boundingBox: BoundingBox;
+}
+interface BoundingBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Image information extracted from EXIF
+ */
+interface ImageInfo {
+    width: number;
+    height: number;
+    format: string;
+    colorSpace?: string;
+    hasAlpha?: boolean;
+}
+/**
+ * Configuration for Storage Brain client
+ */
+interface StorageBrainConfig {
+    /** API key for authentication (sk_live_... or sk_test_...) */
+    apiKey: string;
+    /** Base URL of the Storage Brain API (defaults to production) */
+    baseUrl?: string;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Number of retry attempts for failed requests (default: 3) */
+    maxRetries?: number;
+}
+/**
+ * Options for uploading a file
+ */
+interface UploadOptions {
+    /** Processing context for the file */
+    context: ProcessingContext;
+    /** Optional tags for the file */
+    tags?: Record<string, string>;
+    /** Progress callback (0-100) */
+    onProgress?: (progress: number) => void;
+    /** Optional webhook URL to call after processing */
+    webhookUrl?: string;
+    /** Abort signal for cancellation */
+    signal?: AbortSignal;
+}
+/**
+ * File information returned from the API
+ */
+interface FileInfo {
+    /** Unique file identifier */
+    id: string;
+    /** Public URL to access the file */
+    url: string;
+    /** Original file name */
+    originalName: string;
+    /** MIME type */
+    fileType: AllowedMimeType;
+    /** File size in bytes */
+    sizeBytes: number;
+    /** Processing context */
+    context: ProcessingContext;
+    /** User-defined tags */
+    tags: Record<string, string> | null;
+    /** Processing results and metadata */
+    metadata: FileMetadata | null;
+    /** Current processing status */
+    processingStatus: ProcessingStatus;
+    /** ISO 8601 timestamp */
+    createdAt: string;
+}
+/**
+ * Options for listing files
+ */
+interface ListFilesOptions {
+    /** Maximum number of files to return (1-100, default: 20) */
+    limit?: number;
+    /** Cursor for pagination */
+    cursor?: string;
+    /** Filter by processing context */
+    context?: ProcessingContext;
+    /** Filter by file type */
+    fileType?: AllowedMimeType;
+}
+/**
+ * Result of listing files
+ */
+interface ListFilesResult {
+    /** Array of file information */
+    files: FileInfo[];
+    /** Cursor for next page, null if no more pages */
+    nextCursor: string | null;
+    /** Total number of files matching the query */
+    total: number;
+}
+/**
+ * Quota usage information
+ */
+interface QuotaInfo {
+    /** Total quota in bytes */
+    quotaBytes: number;
+    /** Used storage in bytes */
+    usedBytes: number;
+    /** Available storage in bytes */
+    availableBytes: number;
+    /** Usage percentage (0-100) */
+    usagePercent: number;
+}
+/**
+ * Tenant information
+ */
+interface TenantInfo {
+    /** Tenant ID */
+    id: string;
+    /** Tenant name */
+    name: string;
+    /** Allowed file types for this tenant */
+    allowedFileTypes: AllowedMimeType[] | null;
+    /** ISO 8601 timestamp */
+    createdAt: string;
+}
+/**
+ * Upload handshake response
+ */
+interface UploadHandshake {
+    /** File ID assigned to this upload */
+    fileId: string;
+    /** Presigned URL for uploading */
+    presignedUrl: string;
+    /** Expiration timestamp (ISO 8601) */
+    expiresAt: string;
+    /** Upload constraints */
+    uploadMetadata: {
+        maxSizeBytes: number;
+        allowedTypes: AllowedMimeType[];
+    };
+}
+
+/**
+ * Storage Brain SDK Client
+ *
+ * @example
+ * ```typescript
+ * const storage = new StorageBrain({
+ *   apiKey: 'sk_live_...',
+ * });
+ *
+ * // Upload a file
+ * const file = await storage.upload(fileBlob, {
+ *   context: 'newsletter',
+ *   onProgress: (p) => console.log(`${p}%`),
+ * });
+ *
+ * console.log(file.url);
+ * ```
+ */
+declare class StorageBrain {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    private readonly maxRetries;
+    constructor(config: StorageBrainConfig);
+    /**
+     * Upload a file
+     */
+    upload(file: File | Blob, options: UploadOptions): Promise<FileInfo>;
+    /**
+     * Request an upload handshake
+     */
+    private requestUpload;
+    /**
+     * Upload file content to presigned URL
+     */
+    private uploadToPresignedUrl;
+    /**
+     * Wait for file processing to complete
+     */
+    private waitForProcessing;
+    /**
+     * Get a file by ID
+     */
+    getFile(fileId: string): Promise<FileInfo>;
+    /**
+     * List files
+     */
+    listFiles(options?: ListFilesOptions): Promise<ListFilesResult>;
+    /**
+     * Delete a file
+     */
+    deleteFile(fileId: string): Promise<void>;
+    /**
+     * Get quota usage
+     */
+    getQuota(): Promise<QuotaInfo>;
+    /**
+     * Get tenant information
+     */
+    getTenantInfo(): Promise<TenantInfo>;
+    /**
+     * Make an authenticated API request with retry logic
+     */
+    private request;
+}
+
+/**
+ * Base error class for Storage Brain SDK
+ */
+declare class StorageBrainError extends Error {
+    code: string;
+    statusCode?: number | undefined;
+    details?: Record<string, unknown> | undefined;
+    constructor(message: string, code: string, statusCode?: number | undefined, details?: Record<string, unknown> | undefined);
+}
+/**
+ * Authentication error - invalid or missing API key
+ */
+declare class AuthenticationError extends StorageBrainError {
+    constructor(message?: string);
+}
+/**
+ * Quota exceeded error
+ */
+declare class QuotaExceededError extends StorageBrainError {
+    quotaBytes?: number | undefined;
+    usedBytes?: number | undefined;
+    constructor(message?: string, quotaBytes?: number | undefined, usedBytes?: number | undefined);
+}
+/**
+ * Invalid file type error
+ */
+declare class InvalidFileTypeError extends StorageBrainError {
+    constructor(fileType: string, allowedTypes?: string[]);
+}
+/**
+ * File too large error
+ */
+declare class FileTooLargeError extends StorageBrainError {
+    constructor(fileSize: number, maxSize: number);
+}
+/**
+ * File not found error
+ */
+declare class FileNotFoundError extends StorageBrainError {
+    constructor(fileId: string);
+}
+/**
+ * Network error - connection issues
+ */
+declare class NetworkError extends StorageBrainError {
+    originalError?: Error | undefined;
+    constructor(message?: string, originalError?: Error | undefined);
+}
+/**
+ * Upload error - file upload failed
+ */
+declare class UploadError extends StorageBrainError {
+    originalError?: Error | undefined;
+    constructor(message: string, originalError?: Error | undefined);
+}
+/**
+ * Validation error - request validation failed
+ */
+declare class ValidationError extends StorageBrainError {
+    errors?: Array<{
+        path: string;
+        message: string;
+    }> | undefined;
+    constructor(message: string, errors?: Array<{
+        path: string;
+        message: string;
+    }> | undefined);
+}
+
+export { ALLOWED_FILE_TYPES, ALLOWED_MIME_TYPES, type AllowedMimeType, AuthenticationError, type BoundingBox, DOCUMENT_MIME_TYPES, type FileInfo, type FileMetadata, FileNotFoundError, FileTooLargeError, IMAGE_MIME_TYPES, type ImageInfo, InvalidFileTypeError, type ListFilesOptions, type ListFilesResult, MAX_FILE_SIZE_BYTES, NetworkError, type OcrBlock, type OcrResult, PROCESSING_CONTEXTS, PROCESSING_STATUSES, type ProcessingContext, type ProcessingStatus, QuotaExceededError, type QuotaInfo, StorageBrain, type StorageBrainConfig, StorageBrainError, THUMBNAIL_SIZES, type TenantInfo, type ThumbnailSize, type ThumbnailUrls, UploadError, type UploadHandshake, type UploadOptions, ValidationError, StorageBrain as default };

package/dist/index.js

@@ -0,0 +1,347 @@
+// src/constants.ts
+var ALLOWED_FILE_TYPES = {
+  // Images
+  "image/jpeg": { extension: "jpg", category: "image" },
+  "image/png": { extension: "png", category: "image" },
+  "image/webp": { extension: "webp", category: "image" },
+  "image/gif": { extension: "gif", category: "image" },
+  "image/avif": { extension: "avif", category: "image" },
+  // Documents
+  "application/pdf": { extension: "pdf", category: "document" }
+};
+var ALLOWED_MIME_TYPES = Object.keys(ALLOWED_FILE_TYPES);
+var IMAGE_MIME_TYPES = ALLOWED_MIME_TYPES.filter(
+  (type) => ALLOWED_FILE_TYPES[type].category === "image"
+);
+var DOCUMENT_MIME_TYPES = ALLOWED_MIME_TYPES.filter(
+  (type) => ALLOWED_FILE_TYPES[type].category === "document"
+);
+var PROCESSING_CONTEXTS = ["newsletter", "invoice", "framer-site", "default"];
+var MAX_FILE_SIZE_BYTES = 100 * 1024 * 1024;
+var THUMBNAIL_SIZES = {
+  thumb: { width: 200, height: 200 },
+  medium: { width: 400, height: 400 },
+  large: { width: 800, height: 800 }
+};
+var PROCESSING_STATUSES = ["pending", "processing", "completed", "failed"];
+var RETRY_CONFIG = {
+  initialDelayMs: 1e3,
+  maxDelayMs: 1e4,
+  backoffMultiplier: 2
+};
+
+// src/errors.ts
+var StorageBrainError = class extends Error {
+  constructor(message, code, statusCode, details) {
+    super(message);
+    this.code = code;
+    this.statusCode = statusCode;
+    this.details = details;
+    this.name = "StorageBrainError";
+  }
+};
+var AuthenticationError = class extends StorageBrainError {
+  constructor(message = "Authentication failed") {
+    super(message, "AUTHENTICATION_ERROR", 401);
+    this.name = "AuthenticationError";
+  }
+};
+var QuotaExceededError = class extends StorageBrainError {
+  constructor(message = "Storage quota exceeded", quotaBytes, usedBytes) {
+    super(message, "QUOTA_EXCEEDED", 403, { quotaBytes, usedBytes });
+    this.quotaBytes = quotaBytes;
+    this.usedBytes = usedBytes;
+    this.name = "QuotaExceededError";
+  }
+};
+var InvalidFileTypeError = class extends StorageBrainError {
+  constructor(fileType, allowedTypes) {
+    super(
+      `File type '${fileType}' is not allowed`,
+      "INVALID_FILE_TYPE",
+      400,
+      { fileType, allowedTypes }
+    );
+    this.name = "InvalidFileTypeError";
+  }
+};
+var FileTooLargeError = class extends StorageBrainError {
+  constructor(fileSize, maxSize) {
+    super(
+      `File size ${fileSize} bytes exceeds maximum of ${maxSize} bytes`,
+      "FILE_TOO_LARGE",
+      400,
+      { fileSize, maxSize }
+    );
+    this.name = "FileTooLargeError";
+  }
+};
+var FileNotFoundError = class extends StorageBrainError {
+  constructor(fileId) {
+    super(`File not found: ${fileId}`, "FILE_NOT_FOUND", 404, { fileId });
+    this.name = "FileNotFoundError";
+  }
+};
+var NetworkError = class extends StorageBrainError {
+  constructor(message = "Network error occurred", originalError) {
+    super(message, "NETWORK_ERROR", void 0, { originalError: originalError?.message });
+    this.originalError = originalError;
+    this.name = "NetworkError";
+  }
+};
+var UploadError = class extends StorageBrainError {
+  constructor(message, originalError) {
+    super(message, "UPLOAD_ERROR", void 0, { originalError: originalError?.message });
+    this.originalError = originalError;
+    this.name = "UploadError";
+  }
+};
+var ValidationError = class extends StorageBrainError {
+  constructor(message, errors) {
+    super(message, "VALIDATION_ERROR", 400, { errors });
+    this.errors = errors;
+    this.name = "ValidationError";
+  }
+};
+function parseApiError(statusCode, response) {
+  const { code, message, details } = response.error ?? {};
+  switch (code) {
+    case "UNAUTHORIZED":
+      return new AuthenticationError(message);
+    case "QUOTA_EXCEEDED":
+      return new QuotaExceededError(
+        message,
+        details?.quotaBytes,
+        details?.usedBytes
+      );
+    case "INVALID_FILE_TYPE":
+      return new InvalidFileTypeError(
+        details?.fileType,
+        details?.allowedTypes
+      );
+    case "FILE_TOO_LARGE":
+      return new FileTooLargeError(
+        details?.fileSize,
+        details?.maxSize
+      );
+    case "FILE_NOT_FOUND":
+    case "NOT_FOUND":
+      return new FileNotFoundError(details?.fileId ?? "unknown");
+    case "VALIDATION_ERROR":
+      return new ValidationError(
+        message ?? "Validation failed",
+        details?.errors
+      );
+    default:
+      return new StorageBrainError(
+        message ?? "An error occurred",
+        code ?? "UNKNOWN_ERROR",
+        statusCode,
+        details
+      );
+  }
+}
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://storage-brain-api.marlin-pohl.workers.dev";
+var DEFAULT_TIMEOUT = 3e4;
+var DEFAULT_MAX_RETRIES = 3;
+var StorageBrain = class {
+  apiKey;
+  baseUrl;
+  timeout;
+  maxRetries;
+  constructor(config) {
+    if (!config.apiKey) {
+      throw new StorageBrainError("API key is required", "CONFIGURATION_ERROR");
+    }
+    this.apiKey = config.apiKey;
+    this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+    this.timeout = config.timeout ?? DEFAULT_TIMEOUT;
+    this.maxRetries = config.maxRetries ?? DEFAULT_MAX_RETRIES;
+  }
+  /**
+   * Upload a file
+   */
+  async upload(file, options) {
+    const { context, tags, onProgress, webhookUrl, signal } = options;
+    const fileName = file instanceof File ? file.name : "file";
+    const fileType = file.type;
+    const fileSize = file.size;
+    if (!ALLOWED_MIME_TYPES.includes(fileType)) {
+      throw new InvalidFileTypeError(fileType, [...ALLOWED_MIME_TYPES]);
+    }
+    const handshake = await this.requestUpload({
+      fileType,
+      fileName,
+      fileSizeBytes: fileSize,
+      context,
+      tags,
+      webhookUrl
+    });
+    onProgress?.(10);
+    await this.uploadToPresignedUrl(handshake.presignedUrl, file, fileType, (progress) => {
+      onProgress?.(10 + Math.round(progress * 0.8));
+    }, signal);
+    onProgress?.(90);
+    const fileInfo = await this.waitForProcessing(handshake.fileId, signal);
+    onProgress?.(100);
+    return fileInfo;
+  }
+  /**
+   * Request an upload handshake
+   */
+  async requestUpload(params) {
+    return this.request("POST", "/api/v1/upload/request", params);
+  }
+  /**
+   * Upload file content to presigned URL
+   */
+  async uploadToPresignedUrl(presignedUrl, file, contentType, onProgress, signal) {
+    const uploadUrl = presignedUrl.startsWith("/") ? `${this.baseUrl}${presignedUrl}` : presignedUrl;
+    try {
+      await new Promise((resolve, reject) => {
+        const xhr = new XMLHttpRequest();
+        xhr.upload.addEventListener("progress", (event) => {
+          if (event.lengthComputable && onProgress) {
+            onProgress(Math.round(event.loaded / event.total * 100));
+          }
+        });
+        xhr.addEventListener("load", () => {
+          if (xhr.status >= 200 && xhr.status < 300) {
+            resolve();
+          } else {
+            reject(new UploadError(`Upload failed with status ${xhr.status}`));
+          }
+        });
+        xhr.addEventListener("error", () => {
+          reject(new NetworkError("Network error during upload"));
+        });
+        xhr.addEventListener("abort", () => {
+          reject(new UploadError("Upload was cancelled"));
+        });
+        if (signal) {
+          signal.addEventListener("abort", () => {
+            xhr.abort();
+          });
+        }
+        xhr.open("PUT", uploadUrl);
+        xhr.setRequestHeader("Content-Type", contentType);
+        if (presignedUrl.startsWith("/")) {
+          xhr.setRequestHeader("Authorization", `Bearer ${this.apiKey}`);
+        }
+        xhr.send(file);
+      });
+    } catch (error) {
+      if (error instanceof StorageBrainError) {
+        throw error;
+      }
+      throw new UploadError(
+        "Failed to upload file",
+        error instanceof Error ? error : void 0
+      );
+    }
+  }
+  /**
+   * Wait for file processing to complete
+   */
+  async waitForProcessing(fileId, signal, maxWaitMs = 6e4, pollIntervalMs = 1e3) {
+    const startTime = Date.now();
+    while (Date.now() - startTime < maxWaitMs) {
+      if (signal?.aborted) {
+        throw new UploadError("Operation was cancelled");
+      }
+      const file = await this.getFile(fileId);
+      if (file.processingStatus === "completed" || file.processingStatus === "failed") {
+        return file;
+      }
+      await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+    }
+    return this.getFile(fileId);
+  }
+  /**
+   * Get a file by ID
+   */
+  async getFile(fileId) {
+    return this.request("GET", `/api/v1/files/${fileId}`);
+  }
+  /**
+   * List files
+   */
+  async listFiles(options) {
+    const params = new URLSearchParams();
+    if (options?.limit) params.set("limit", options.limit.toString());
+    if (options?.cursor) params.set("cursor", options.cursor);
+    if (options?.context) params.set("context", options.context);
+    if (options?.fileType) params.set("fileType", options.fileType);
+    const query = params.toString();
+    const path = query ? `/api/v1/files?${query}` : "/api/v1/files";
+    return this.request("GET", path);
+  }
+  /**
+   * Delete a file
+   */
+  async deleteFile(fileId) {
+    await this.request("DELETE", `/api/v1/files/${fileId}`);
+  }
+  /**
+   * Get quota usage
+   */
+  async getQuota() {
+    return this.request("GET", "/api/v1/tenant/quota");
+  }
+  /**
+   * Get tenant information
+   */
+  async getTenantInfo() {
+    return this.request("GET", "/api/v1/tenant/info");
+  }
+  /**
+   * Make an authenticated API request with retry logic
+   */
+  async request(method, path, body) {
+    const url = `${this.baseUrl}${path}`;
+    let lastError;
+    for (let attempt = 0; attempt < this.maxRetries; attempt++) {
+      try {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        const response = await fetch(url, {
+          method,
+          headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${this.apiKey}`
+          },
+          body: body ? JSON.stringify(body) : void 0,
+          signal: controller.signal
+        });
+        clearTimeout(timeoutId);
+        if (!response.ok) {
+          const errorBody = await response.json().catch(() => ({}));
+          throw parseApiError(response.status, errorBody);
+        }
+        return await response.json();
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+        if (error instanceof StorageBrainError && error.statusCode && error.statusCode < 500) {
+          throw error;
+        }
+        if (attempt < this.maxRetries - 1) {
+          const delay = Math.min(
+            RETRY_CONFIG.initialDelayMs * Math.pow(RETRY_CONFIG.backoffMultiplier, attempt),
+            RETRY_CONFIG.maxDelayMs
+          );
+          await new Promise((resolve) => setTimeout(resolve, delay));
+        }
+      }
+    }
+    throw new NetworkError(
+      `Request failed after ${this.maxRetries} attempts`,
+      lastError
+    );
+  }
+};
+
+export { ALLOWED_FILE_TYPES, ALLOWED_MIME_TYPES, AuthenticationError, DOCUMENT_MIME_TYPES, FileNotFoundError, FileTooLargeError, IMAGE_MIME_TYPES, InvalidFileTypeError, MAX_FILE_SIZE_BYTES, NetworkError, PROCESSING_CONTEXTS, PROCESSING_STATUSES, QuotaExceededError, StorageBrain, StorageBrainError, THUMBNAIL_SIZES, UploadError, ValidationError, StorageBrain as default };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map