@marlinjai/storage-brain-sdk 0.1.0

package/dist/index.d.cts

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