@rovela-ai/sdk 0.1.26 → 0.1.27

package/dist/media/server/index.js

@@ -0,0 +1,13 @@
+/**
+ * @rovela-ai/sdk/media/server
+ *
+ * Server-side media utilities.
+ * Only import this in server components and API routes.
+ */
+// R2 Client
+export { getR2Client, clearR2ClientCache, getBucketName, getPublicUrlBase, getStoreId } from './r2-client';
+// Presigned URLs
+export { generatePresignedUrl, generatePresignedUrls, isR2Url, validateStoreUrl, } from './presign';
+// File Deletion
+export { deleteFile, deleteFileByKey, deleteFiles, safeDeleteFile } from './delete';
+//# sourceMappingURL=index.js.map

package/dist/media/server/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/media/server/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,YAAY;AACZ,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,aAAa,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAE1G,iBAAiB;AACjB,OAAO,EACL,oBAAoB,EACpB,qBAAqB,EACrB,OAAO,EACP,gBAAgB,GAEjB,MAAM,WAAW,CAAA;AAElB,gBAAgB;AAChB,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA"}

package/dist/media/server/presign.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @rovela-ai/sdk/media/server/presign
+ *
+ * Presigned URL generation for direct browser uploads to R2.
+ * Server-side only - do not import in client components.
+ */
+import type { PresignedUrlRequest, PresignedUrlResponse, MediaStorageConfig } from '../types';
+/**
+ * Options for generating a presigned URL
+ */
+export interface GeneratePresignedUrlOptions {
+    /** URL expiration time in seconds (default: 300 = 5 minutes) */
+    expiresIn?: number;
+    /** Optional storage config override */
+    config?: MediaStorageConfig;
+}
+/**
+ * Generate a presigned URL for uploading a file to R2.
+ *
+ * The presigned URL allows the browser to upload directly to R2
+ * without the file passing through your server.
+ *
+ * @param request - Upload request details
+ * @param options - Optional configuration
+ * @returns Presigned URL response with upload URL and final public URL
+ *
+ * @example
+ * ```typescript
+ * const result = await generatePresignedUrl({
+ *   filename: 'product-image.jpg',
+ *   contentType: 'image/jpeg',
+ *   folder: 'products',
+ *   entityId: 'prod_abc123',
+ * });
+ *
+ * // Client uploads directly to result.uploadUrl
+ * // After upload, image is accessible at result.publicUrl
+ * ```
+ */
+export declare function generatePresignedUrl(request: PresignedUrlRequest, options?: GeneratePresignedUrlOptions): Promise<PresignedUrlResponse>;
+/**
+ * Generate presigned URLs for multiple files at once.
+ *
+ * @param requests - Array of upload request details
+ * @param options - Optional configuration
+ * @returns Array of presigned URL responses
+ */
+export declare function generatePresignedUrls(requests: PresignedUrlRequest[], options?: GeneratePresignedUrlOptions): Promise<PresignedUrlResponse[]>;
+/**
+ * Check if a URL is from this store's R2 storage
+ */
+export declare function isR2Url(url: string, config?: MediaStorageConfig): boolean;
+/**
+ * Validate that a URL belongs to this store's storage prefix
+ */
+export declare function validateStoreUrl(url: string, config?: MediaStorageConfig): boolean;
+//# sourceMappingURL=presign.d.ts.map

package/dist/media/server/presign.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"presign.d.ts","sourceRoot":"","sources":["../../../src/media/server/presign.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EACV,mBAAmB,EACnB,oBAAoB,EACpB,kBAAkB,EACnB,MAAM,UAAU,CAAA;AAcjB;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C,gEAAgE;IAChE,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,uCAAuC;IACvC,MAAM,CAAC,EAAE,kBAAkB,CAAA;CAC5B;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,mBAAmB,EAC5B,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,oBAAoB,CAAC,CAwC/B;AAED;;;;;;GAMG;AACH,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,mBAAmB,EAAE,EAC/B,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAEjC;AAMD;;GAEG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAGzE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAiBlF"}

package/dist/media/server/presign.js

@@ -0,0 +1,112 @@
+/**
+ * @rovela-ai/sdk/media/server/presign
+ *
+ * Presigned URL generation for direct browser uploads to R2.
+ * Server-side only - do not import in client components.
+ */
+import { PutObjectCommand } from '@aws-sdk/client-s3';
+import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
+import { generateUniqueFilename } from '../types';
+import { buildStorageKey, buildPublicUrl, requireMediaConfig } from '../config';
+import { getR2Client, getBucketName, getPublicUrlBase, getStoreId } from './r2-client';
+// =============================================================================
+// Presigned URL Generation
+// =============================================================================
+/**
+ * Default presigned URL expiration time in seconds (5 minutes)
+ */
+const DEFAULT_EXPIRES_IN = 5 * 60;
+/**
+ * Generate a presigned URL for uploading a file to R2.
+ *
+ * The presigned URL allows the browser to upload directly to R2
+ * without the file passing through your server.
+ *
+ * @param request - Upload request details
+ * @param options - Optional configuration
+ * @returns Presigned URL response with upload URL and final public URL
+ *
+ * @example
+ * ```typescript
+ * const result = await generatePresignedUrl({
+ *   filename: 'product-image.jpg',
+ *   contentType: 'image/jpeg',
+ *   folder: 'products',
+ *   entityId: 'prod_abc123',
+ * });
+ *
+ * // Client uploads directly to result.uploadUrl
+ * // After upload, image is accessible at result.publicUrl
+ * ```
+ */
+export async function generatePresignedUrl(request, options = {}) {
+    const { expiresIn = DEFAULT_EXPIRES_IN, config } = options;
+    // Get configuration
+    const resolvedConfig = config || requireMediaConfig();
+    const client = getR2Client(resolvedConfig);
+    const bucketName = getBucketName(resolvedConfig);
+    const publicUrlBase = getPublicUrlBase(resolvedConfig);
+    const storeId = getStoreId(resolvedConfig);
+    // Generate unique filename to prevent overwrites
+    const uniqueFilename = generateUniqueFilename(request.filename);
+    // Build the storage key (path)
+    const key = buildStorageKey(storeId, request.folder, uniqueFilename, request.entityId);
+    // Create the PutObject command
+    const command = new PutObjectCommand({
+        Bucket: bucketName,
+        Key: key,
+        ContentType: request.contentType,
+    });
+    // Generate presigned URL
+    const uploadUrl = await getSignedUrl(client, command, {
+        expiresIn,
+    });
+    // Calculate expiration time
+    const expiresAt = new Date(Date.now() + expiresIn * 1000);
+    // Build public URL
+    const publicUrl = buildPublicUrl(publicUrlBase, key);
+    return {
+        uploadUrl,
+        publicUrl,
+        key,
+        expiresAt,
+    };
+}
+/**
+ * Generate presigned URLs for multiple files at once.
+ *
+ * @param requests - Array of upload request details
+ * @param options - Optional configuration
+ * @returns Array of presigned URL responses
+ */
+export async function generatePresignedUrls(requests, options = {}) {
+    return Promise.all(requests.map((request) => generatePresignedUrl(request, options)));
+}
+// =============================================================================
+// URL Validation
+// =============================================================================
+/**
+ * Check if a URL is from this store's R2 storage
+ */
+export function isR2Url(url, config) {
+    const resolvedConfig = config || requireMediaConfig();
+    return url.startsWith(resolvedConfig.publicUrl);
+}
+/**
+ * Validate that a URL belongs to this store's storage prefix
+ */
+export function validateStoreUrl(url, config) {
+    const resolvedConfig = config || requireMediaConfig();
+    if (!isR2Url(url, resolvedConfig)) {
+        return false;
+    }
+    // Extract key from URL and check prefix
+    const baseUrl = resolvedConfig.publicUrl.endsWith('/')
+        ? resolvedConfig.publicUrl.slice(0, -1)
+        : resolvedConfig.publicUrl;
+    const key = url.slice(baseUrl.length + 1);
+    // Key should start with stores/{storeId}/
+    const expectedPrefix = `stores/${resolvedConfig.storeId}/`;
+    return key.startsWith(expectedPrefix);
+}
+//# sourceMappingURL=presign.js.map

package/dist/media/server/presign.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"presign.js","sourceRoot":"","sources":["../../../src/media/server/presign.ts"],"names":[],"mappings":"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"}

package/dist/media/server/r2-client.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @rovela-ai/sdk/media/server/r2-client
+ *
+ * S3-compatible client for Cloudflare R2 storage.
+ * Server-side only - do not import in client components.
+ */
+import { S3Client } from '@aws-sdk/client-s3';
+import type { MediaStorageConfig } from '../types';
+/**
+ * Get or create the S3 client for R2.
+ * Caches the client instance for reuse.
+ */
+export declare function getR2Client(config?: MediaStorageConfig): S3Client;
+/**
+ * Clear the cached client (useful for testing)
+ */
+export declare function clearR2ClientCache(): void;
+/**
+ * Get the configured bucket name
+ */
+export declare function getBucketName(config?: MediaStorageConfig): string;
+/**
+ * Get the public URL base for the bucket
+ */
+export declare function getPublicUrlBase(config?: MediaStorageConfig): string;
+/**
+ * Get the store ID for path prefixing
+ */
+export declare function getStoreId(config?: MediaStorageConfig): string;
+//# sourceMappingURL=r2-client.d.ts.map

package/dist/media/server/r2-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"r2-client.d.ts","sourceRoot":"","sources":["../../../src/media/server/r2-client.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAC7C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAA;AAoBlD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,MAAM,CAAC,EAAE,kBAAkB,GAAG,QAAQ,CAsBjE;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAGzC;AAMD;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,CAAC,EAAE,kBAAkB,GAAG,MAAM,CAGjE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,CAAC,EAAE,kBAAkB,GAAG,MAAM,CAGpE;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,MAAM,CAAC,EAAE,kBAAkB,GAAG,MAAM,CAG9D"}

package/dist/media/server/r2-client.js

@@ -0,0 +1,76 @@
+/**
+ * @rovela-ai/sdk/media/server/r2-client
+ *
+ * S3-compatible client for Cloudflare R2 storage.
+ * Server-side only - do not import in client components.
+ */
+import { S3Client } from '@aws-sdk/client-s3';
+import { requireMediaConfig } from '../config';
+// =============================================================================
+// Client Instance Management
+// =============================================================================
+/** Cached S3 client instance */
+let cachedClient = null;
+/** Cached config used to create the client */
+let cachedConfigHash = null;
+/**
+ * Create a hash of the config for cache invalidation
+ */
+function hashConfig(config) {
+    return `${config.accountId}:${config.bucketName}:${config.accessKeyId.slice(0, 8)}`;
+}
+/**
+ * Get or create the S3 client for R2.
+ * Caches the client instance for reuse.
+ */
+export function getR2Client(config) {
+    const resolvedConfig = config || requireMediaConfig();
+    const configHash = hashConfig(resolvedConfig);
+    // Return cached client if config hasn't changed
+    if (cachedClient && cachedConfigHash === configHash) {
+        return cachedClient;
+    }
+    // Create new client
+    cachedClient = new S3Client({
+        region: 'auto',
+        endpoint: `https://${resolvedConfig.accountId}.r2.cloudflarestorage.com`,
+        credentials: {
+            accessKeyId: resolvedConfig.accessKeyId,
+            secretAccessKey: resolvedConfig.secretAccessKey,
+        },
+    });
+    cachedConfigHash = configHash;
+    return cachedClient;
+}
+/**
+ * Clear the cached client (useful for testing)
+ */
+export function clearR2ClientCache() {
+    cachedClient = null;
+    cachedConfigHash = null;
+}
+// =============================================================================
+// Bucket Operations
+// =============================================================================
+/**
+ * Get the configured bucket name
+ */
+export function getBucketName(config) {
+    const resolvedConfig = config || requireMediaConfig();
+    return resolvedConfig.bucketName;
+}
+/**
+ * Get the public URL base for the bucket
+ */
+export function getPublicUrlBase(config) {
+    const resolvedConfig = config || requireMediaConfig();
+    return resolvedConfig.publicUrl;
+}
+/**
+ * Get the store ID for path prefixing
+ */
+export function getStoreId(config) {
+    const resolvedConfig = config || requireMediaConfig();
+    return resolvedConfig.storeId;
+}
+//# sourceMappingURL=r2-client.js.map

package/dist/media/server/r2-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"r2-client.js","sourceRoot":"","sources":["../../../src/media/server/r2-client.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAE7C,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AAE9C,gFAAgF;AAChF,6BAA6B;AAC7B,gFAAgF;AAEhF,gCAAgC;AAChC,IAAI,YAAY,GAAoB,IAAI,CAAA;AAExC,8CAA8C;AAC9C,IAAI,gBAAgB,GAAkB,IAAI,CAAA;AAE1C;;GAEG;AACH,SAAS,UAAU,CAAC,MAA0B;IAC5C,OAAO,GAAG,MAAM,CAAC,SAAS,IAAI,MAAM,CAAC,UAAU,IAAI,MAAM,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAA;AACrF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,MAA2B;IACrD,MAAM,cAAc,GAAG,MAAM,IAAI,kBAAkB,EAAE,CAAA;IACrD,MAAM,UAAU,GAAG,UAAU,CAAC,cAAc,CAAC,CAAA;IAE7C,gDAAgD;IAChD,IAAI,YAAY,IAAI,gBAAgB,KAAK,UAAU,EAAE,CAAC;QACpD,OAAO,YAAY,CAAA;IACrB,CAAC;IAED,oBAAoB;IACpB,YAAY,GAAG,IAAI,QAAQ,CAAC;QAC1B,MAAM,EAAE,MAAM;QACd,QAAQ,EAAE,WAAW,cAAc,CAAC,SAAS,2BAA2B;QACxE,WAAW,EAAE;YACX,WAAW,EAAE,cAAc,CAAC,WAAW;YACvC,eAAe,EAAE,cAAc,CAAC,eAAe;SAChD;KACF,CAAC,CAAA;IAEF,gBAAgB,GAAG,UAAU,CAAA;IAE7B,OAAO,YAAY,CAAA;AACrB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,kBAAkB;IAChC,YAAY,GAAG,IAAI,CAAA;IACnB,gBAAgB,GAAG,IAAI,CAAA;AACzB,CAAC;AAED,gFAAgF;AAChF,oBAAoB;AACpB,gFAAgF;AAEhF;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,MAA2B;IACvD,MAAM,cAAc,GAAG,MAAM,IAAI,kBAAkB,EAAE,CAAA;IACrD,OAAO,cAAc,CAAC,UAAU,CAAA;AAClC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAA2B;IAC1D,MAAM,cAAc,GAAG,MAAM,IAAI,kBAAkB,EAAE,CAAA;IACrD,OAAO,cAAc,CAAC,SAAS,CAAA;AACjC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,UAAU,CAAC,MAA2B;IACpD,MAAM,cAAc,GAAG,MAAM,IAAI,kBAAkB,EAAE,CAAA;IACrD,OAAO,cAAc,CAAC,OAAO,CAAA;AAC/B,CAAC"}

package/dist/media/types.d.ts

@@ -0,0 +1,271 @@
+/**
+ * @rovela-ai/sdk/media/types
+ *
+ * TypeScript type definitions for media upload functionality.
+ * Supports product images, category covers, and variant swatches.
+ */
+/**
+ * R2/S3 storage configuration
+ */
+export interface MediaStorageConfig {
+    /** Cloudflare account ID (for R2) */
+    accountId: string;
+    /** S3-compatible access key */
+    accessKeyId: string;
+    /** S3-compatible secret key */
+    secretAccessKey: string;
+    /** Bucket name */
+    bucketName: string;
+    /** Public URL for accessing uploaded files */
+    publicUrl: string;
+    /** Store ID for path prefixing */
+    storeId: string;
+}
+/**
+ * Upload constraints configuration
+ */
+export interface UploadConfig {
+    /** Maximum file size in bytes (default: 10MB) */
+    maxSizeBytes: number;
+    /** Allowed MIME types */
+    allowedTypes: string[];
+    /** Maximum files for batch uploads */
+    maxFiles: number;
+}
+/**
+ * Default upload configuration
+ */
+export declare const DEFAULT_UPLOAD_CONFIG: UploadConfig;
+/**
+ * Folder types for organizing uploads
+ */
+export type MediaFolder = 'products' | 'categories' | 'variants' | 'general';
+/**
+ * Request to generate a presigned upload URL
+ */
+export interface PresignedUrlRequest {
+    /** Original filename (used for extension) */
+    filename: string;
+    /** MIME type of the file */
+    contentType: string;
+    /** Target folder for organization */
+    folder: MediaFolder;
+    /** Optional entity ID (productId, categoryId, etc.) */
+    entityId?: string;
+}
+/**
+ * Response containing presigned URL details
+ */
+export interface PresignedUrlResponse {
+    /** Presigned PUT URL for uploading */
+    uploadUrl: string;
+    /** Final public URL after upload completes */
+    publicUrl: string;
+    /** Generated unique key/path in storage */
+    key: string;
+    /** URL expiration timestamp */
+    expiresAt: Date;
+}
+/**
+ * Upload progress information
+ */
+export interface UploadProgress {
+    /** Bytes uploaded so far */
+    loaded: number;
+    /** Total bytes to upload */
+    total: number;
+    /** Progress percentage (0-100) */
+    percentage: number;
+}
+/**
+ * Status of an upload operation
+ */
+export type UploadStatus = 'idle' | 'preparing' | 'uploading' | 'success' | 'error';
+/**
+ * Result of a completed upload
+ */
+export interface UploadResult {
+    /** Whether upload succeeded */
+    success: boolean;
+    /** Final public URL (only if success) */
+    url?: string;
+    /** Original filename */
+    filename: string;
+    /** File size in bytes */
+    size: number;
+    /** MIME type */
+    contentType: string;
+    /** Error message (only if failed) */
+    error?: string;
+}
+/**
+ * State for tracking an upload in progress
+ */
+export interface UploadState {
+    /** Current status */
+    status: UploadStatus;
+    /** Progress information (during upload) */
+    progress: UploadProgress | null;
+    /** Result (after completion) */
+    result: UploadResult | null;
+    /** Error message (if failed) */
+    error: string | null;
+}
+/**
+ * API request body for presign endpoint
+ */
+export interface PresignApiRequest {
+    filename: string;
+    contentType: string;
+    folder: MediaFolder;
+    entityId?: string;
+}
+/**
+ * API response from presign endpoint
+ */
+export interface PresignApiResponse {
+    success: boolean;
+    data?: PresignedUrlResponse;
+    error?: string;
+}
+/**
+ * API request body for delete endpoint
+ */
+export interface DeleteApiRequest {
+    /** URL or key of the file to delete */
+    url: string;
+}
+/**
+ * API response from delete endpoint
+ */
+export interface DeleteApiResponse {
+    success: boolean;
+    error?: string;
+}
+/**
+ * Standard API error response
+ */
+export interface MediaApiError {
+    success: false;
+    error: string;
+    code?: string;
+}
+/**
+ * Options for useUpload hook
+ */
+export interface UseUploadOptions {
+    /** Target folder for uploads */
+    folder: MediaFolder;
+    /** Associated entity ID */
+    entityId?: string;
+    /** Upload configuration overrides */
+    config?: Partial<UploadConfig>;
+    /** Callback when upload completes */
+    onSuccess?: (result: UploadResult) => void;
+    /** Callback when upload fails */
+    onError?: (error: string) => void;
+    /** Callback for progress updates */
+    onProgress?: (progress: UploadProgress) => void;
+}
+/**
+ * Return type of useUpload hook
+ */
+export interface UseUploadReturn {
+    /** Upload a single file */
+    upload: (file: File) => Promise<UploadResult>;
+    /** Upload multiple files */
+    uploadMultiple: (files: File[]) => Promise<UploadResult[]>;
+    /** Current upload status */
+    status: UploadStatus;
+    /** Current progress (if uploading) */
+    progress: UploadProgress | null;
+    /** Whether currently uploading */
+    isUploading: boolean;
+    /** Current error (if any) */
+    error: string | null;
+    /** Reset state to idle */
+    reset: () => void;
+}
+/**
+ * Props for DropZone component
+ */
+export interface DropZoneProps {
+    /** Called when files are dropped/selected */
+    onFiles: (files: File[]) => void;
+    /** Whether to accept multiple files */
+    multiple?: boolean;
+    /** Accepted file types (MIME) */
+    accept?: string[];
+    /** Maximum file size in bytes */
+    maxSize?: number;
+    /** Whether the dropzone is disabled */
+    disabled?: boolean;
+    /** Additional CSS classes */
+    className?: string;
+    /** Custom content inside dropzone */
+    children?: React.ReactNode;
+}
+/**
+ * Props for ImageUpload component
+ */
+export interface ImageUploadProps {
+    /** Current image URL (null if no image) */
+    value: string | null;
+    /** Called when image changes */
+    onChange: (url: string | null) => void;
+    /** Target folder for uploads */
+    folder: MediaFolder;
+    /** Associated entity ID */
+    entityId?: string;
+    /** Maximum file size in MB */
+    maxSizeMB?: number;
+    /** Whether upload is disabled */
+    disabled?: boolean;
+    /** Additional CSS classes */
+    className?: string;
+    /** Placeholder text when no image */
+    placeholder?: string;
+    /** Aspect ratio for preview (e.g., "1/1", "16/9") */
+    aspectRatio?: string;
+}
+/**
+ * Props for ImageGalleryUpload component
+ */
+export interface ImageGalleryUploadProps {
+    /** Current array of image URLs */
+    value: string[];
+    /** Called when images change */
+    onChange: (urls: string[]) => void;
+    /** Target folder for uploads */
+    folder: MediaFolder;
+    /** Associated entity ID */
+    entityId?: string;
+    /** Maximum number of images allowed */
+    maxImages?: number;
+    /** Maximum file size per image in MB */
+    maxSizeMB?: number;
+    /** Whether upload is disabled */
+    disabled?: boolean;
+    /** Additional CSS classes */
+    className?: string;
+}
+/**
+ * File validation result
+ */
+export interface FileValidation {
+    valid: boolean;
+    error?: string;
+}
+/**
+ * Validate a file against upload constraints
+ */
+export declare function validateFile(file: File, config?: UploadConfig): FileValidation;
+/**
+ * Get file extension from filename
+ */
+export declare function getFileExtension(filename: string): string;
+/**
+ * Generate a unique filename with timestamp and random suffix
+ */
+export declare function generateUniqueFilename(originalFilename: string): string;
+//# sourceMappingURL=types.d.ts.map

package/dist/media/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/media/types.ts"],"names":[],"mappings":"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"}

package/dist/media/types.js

@@ -0,0 +1,52 @@
+/**
+ * @rovela-ai/sdk/media/types
+ *
+ * TypeScript type definitions for media upload functionality.
+ * Supports product images, category covers, and variant swatches.
+ */
+/**
+ * Default upload configuration
+ */
+export const DEFAULT_UPLOAD_CONFIG = {
+    maxSizeBytes: 10 * 1024 * 1024, // 10MB
+    allowedTypes: ['image/jpeg', 'image/png', 'image/webp', 'image/gif'],
+    maxFiles: 10,
+};
+/**
+ * Validate a file against upload constraints
+ */
+export function validateFile(file, config = DEFAULT_UPLOAD_CONFIG) {
+    // Check file size
+    if (file.size > config.maxSizeBytes) {
+        const maxMB = Math.round(config.maxSizeBytes / (1024 * 1024));
+        return {
+            valid: false,
+            error: `File size exceeds ${maxMB}MB limit`,
+        };
+    }
+    // Check file type
+    if (!config.allowedTypes.includes(file.type)) {
+        return {
+            valid: false,
+            error: `File type ${file.type} is not allowed`,
+        };
+    }
+    return { valid: true };
+}
+/**
+ * Get file extension from filename
+ */
+export function getFileExtension(filename) {
+    const parts = filename.split('.');
+    return parts.length > 1 ? parts.pop().toLowerCase() : '';
+}
+/**
+ * Generate a unique filename with timestamp and random suffix
+ */
+export function generateUniqueFilename(originalFilename) {
+    const ext = getFileExtension(originalFilename);
+    const timestamp = Date.now();
+    const random = Math.random().toString(36).substring(2, 8);
+    return ext ? `${timestamp}_${random}.${ext}` : `${timestamp}_${random}`;
+}
+//# sourceMappingURL=types.js.map

package/dist/media/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/media/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAoCH;;GAEG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAiB;IACjD,YAAY,EAAE,EAAE,GAAG,IAAI,GAAG,IAAI,EAAE,OAAO;IACvC,YAAY,EAAE,CAAC,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,WAAW,CAAC;IACpE,QAAQ,EAAE,EAAE;CACb,CAAA;AAwQD;;GAEG;AACH,MAAM,UAAU,YAAY,CAC1B,IAAU,EACV,SAAuB,qBAAqB;IAE5C,kBAAkB;IAClB,IAAI,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC,YAAY,EAAE,CAAC;QACpC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,YAAY,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC,CAAA;QAC7D,OAAO;YACL,KAAK,EAAE,KAAK;YACZ,KAAK,EAAE,qBAAqB,KAAK,UAAU;SAC5C,CAAA;IACH,CAAC;IAED,kBAAkB;IAClB,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAC7C,OAAO;YACL,KAAK,EAAE,KAAK;YACZ,KAAK,EAAE,aAAa,IAAI,CAAC,IAAI,iBAAiB;SAC/C,CAAA;IACH,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAA;AACxB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAgB;IAC/C,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;IACjC,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,EAAG,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAA;AAC3D,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,sBAAsB,CAAC,gBAAwB;IAC7D,MAAM,GAAG,GAAG,gBAAgB,CAAC,gBAAgB,CAAC,CAAA;IAC9C,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;IAC5B,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;IACzD,OAAO,GAAG,CAAC,CAAC,CAAC,GAAG,SAAS,IAAI,MAAM,IAAI,GAAG,EAAE,CAAC,CAAC,CAAC,GAAG,SAAS,IAAI,MAAM,EAAE,CAAA;AACzE,CAAC"}