@maravilla-labs/types 0.1.18 → 0.1.21

package/index.d.ts

@@ -94,6 +94,115 @@ export interface DbCollection {
 export interface Database {
     [collection: string]: DbCollection;
 }
+/**
+ * Storage metadata for uploaded files
+ */
+export interface StorageMetadata {
+    /** MIME content type */
+    contentType: string;
+    /** File size in bytes */
+    size: number;
+    /** Upload timestamp (Unix timestamp in seconds) */
+    uploadedAt: number;
+    /** Optional custom tags */
+    tags?: Record<string, string>;
+    /** Original filename if provided */
+    filename?: string;
+    /** Checksum/ETag */
+    etag?: string;
+}
+/**
+ * Storage object information (for list operations)
+ */
+export interface StorageObjectInfo {
+    /** Object key/path */
+    key: string;
+    /** Object metadata */
+    metadata: StorageMetadata;
+    /** Last modified timestamp */
+    lastModified: number;
+}
+/**
+ * Presigned URL information for uploads/downloads
+ */
+export interface PresignedUrl {
+    /** The presigned URL */
+    url: string;
+    /** HTTP method to use (PUT for upload, GET for download) */
+    method: string;
+    /** Headers that must be included in the request */
+    headers: Record<string, string>;
+    /** Expiration time in seconds */
+    expiresIn: number;
+}
+/**
+ * Options for generating upload URLs
+ */
+export interface UploadUrlOptions {
+    /** Maximum file size in bytes */
+    sizeLimit?: number;
+    /** Custom metadata tags */
+    tags?: Record<string, string>;
+}
+/**
+ * Options for listing storage objects
+ */
+export interface StorageListOptions {
+    /** Key prefix to filter by */
+    prefix?: string;
+    /** Maximum number of results */
+    limit?: number;
+}
+/**
+ * Storage service interface
+ */
+export interface Storage {
+    /**
+     * Generate a presigned URL for uploading a file
+     * @param key - The storage key/path for the file
+     * @param contentType - MIME type of the file
+     * @param options - Upload options
+     * @returns Presigned URL information
+     */
+    generateUploadUrl(key: string, contentType: string, options?: UploadUrlOptions): Promise<PresignedUrl>;
+    /**
+     * Upload data directly (for small files)
+     * @param key - The storage key/path for the file
+     * @param data - File data (can be ArrayBuffer, Uint8Array, Blob, or string)
+     * @param metadata - File metadata
+     */
+    put(key: string, data: ArrayBuffer | Uint8Array | Blob | string, metadata?: Partial<StorageMetadata>): Promise<void>;
+    /**
+     * Download a file
+     * @param key - The storage key/path for the file
+     * @returns File data as ArrayBuffer
+     */
+    get(key: string): Promise<ArrayBuffer>;
+    /**
+     * Generate a presigned URL for downloading a file
+     * @param key - The storage key/path for the file
+     * @param expiresIn - How long the URL should be valid (in seconds)
+     * @returns Presigned URL information
+     */
+    generateDownloadUrl(key: string, expiresIn?: number): Promise<PresignedUrl>;
+    /**
+     * Delete a file
+     * @param key - The storage key/path for the file
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * List files with a given prefix
+     * @param options - List options
+     * @returns List of storage objects
+     */
+    list(options?: StorageListOptions): Promise<StorageObjectInfo[]>;
+    /**
+     * Get file metadata without downloading the file
+     * @param key - The storage key/path for the file
+     * @returns File metadata
+     */
+    getMetadata(key: string): Promise<StorageMetadata>;
+}
 /**
  * Main platform interface available in runtime
  */
@@ -102,10 +211,13 @@ export interface Platform {
     kv: KvStore;
     /** Database instance with dynamic collection access */
     db: Database;
+    /** Storage service instance */
+    storage: Storage;
     /** Legacy aliases for compatibility */
     env: {
         KV: KvStore;
         DB: Database;
+        STORAGE: Storage;
     };
 }
 /**

package/index.ts

@@ -111,6 +111,129 @@ export interface Database {
   [collection: string]: DbCollection;
 }
 
+// Storage Types
+
+/**
+ * Storage metadata for uploaded files
+ */
+export interface StorageMetadata {
+  /** MIME content type */
+  contentType: string;
+  /** File size in bytes */
+  size: number;
+  /** Upload timestamp (Unix timestamp in seconds) */
+  uploadedAt: number;
+  /** Optional custom tags */
+  tags?: Record<string, string>;
+  /** Original filename if provided */
+  filename?: string;
+  /** Checksum/ETag */
+  etag?: string;
+}
+
+/**
+ * Storage object information (for list operations)
+ */
+export interface StorageObjectInfo {
+  /** Object key/path */
+  key: string;
+  /** Object metadata */
+  metadata: StorageMetadata;
+  /** Last modified timestamp */
+  lastModified: number;
+}
+
+/**
+ * Presigned URL information for uploads/downloads
+ */
+export interface PresignedUrl {
+  /** The presigned URL */
+  url: string;
+  /** HTTP method to use (PUT for upload, GET for download) */
+  method: string;
+  /** Headers that must be included in the request */
+  headers: Record<string, string>;
+  /** Expiration time in seconds */
+  expiresIn: number;
+}
+
+/**
+ * Options for generating upload URLs
+ */
+export interface UploadUrlOptions {
+  /** Maximum file size in bytes */
+  sizeLimit?: number;
+  /** Custom metadata tags */
+  tags?: Record<string, string>;
+}
+
+/**
+ * Options for listing storage objects
+ */
+export interface StorageListOptions {
+  /** Key prefix to filter by */
+  prefix?: string;
+  /** Maximum number of results */
+  limit?: number;
+}
+
+/**
+ * Storage service interface
+ */
+export interface Storage {
+  /**
+   * Generate a presigned URL for uploading a file
+   * @param key - The storage key/path for the file
+   * @param contentType - MIME type of the file
+   * @param options - Upload options
+   * @returns Presigned URL information
+   */
+  generateUploadUrl(key: string, contentType: string, options?: UploadUrlOptions): Promise<PresignedUrl>;
+  
+  /**
+   * Upload data directly (for small files)
+   * @param key - The storage key/path for the file
+   * @param data - File data (can be ArrayBuffer, Uint8Array, Blob, or string)
+   * @param metadata - File metadata
+   */
+  put(key: string, data: ArrayBuffer | Uint8Array | Blob | string, metadata?: Partial<StorageMetadata>): Promise<void>;
+  
+  /**
+   * Download a file
+   * @param key - The storage key/path for the file
+   * @returns File data as ArrayBuffer
+   */
+  get(key: string): Promise<ArrayBuffer>;
+  
+  /**
+   * Generate a presigned URL for downloading a file
+   * @param key - The storage key/path for the file
+   * @param expiresIn - How long the URL should be valid (in seconds)
+   * @returns Presigned URL information
+   */
+  generateDownloadUrl(key: string, expiresIn?: number): Promise<PresignedUrl>;
+  
+  /**
+   * Delete a file
+   * @param key - The storage key/path for the file
+   */
+  delete(key: string): Promise<void>;
+  
+  /**
+   * List files with a given prefix
+   * @param options - List options
+   * @returns List of storage objects
+   */
+  list(options?: StorageListOptions): Promise<StorageObjectInfo[]>;
+  
+  /**
+   * Get file metadata without downloading the file
+   * @param key - The storage key/path for the file
+   * @returns File metadata
+   */
+  getMetadata(key: string): Promise<StorageMetadata>;
+}
+
 // Platform Types
 
 /**
@@ -121,10 +244,13 @@ export interface Platform {
   kv: KvStore;
   /** Database instance with dynamic collection access */
   db: Database;
+  /** Storage service instance */
+  storage: Storage;
   /** Legacy aliases for compatibility */
   env: {
     KV: KvStore;
     DB: Database;
+    STORAGE: Storage;
   };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maravilla-labs/types",
-  "version": "0.1.18",
+  "version": "0.1.21",
   "description": "TypeScript definitions for Maravilla Runtime platform APIs",
   "main": "index.ts",
   "types": "index.ts",
@@ -21,5 +21,8 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "dependencies": {
+    "undici-types": "^7.15.0"
   }
 }