alepha 0.10.5 → 0.10.7

package/api/files.d.ts

@@ -1,8 +1,10 @@
 import { BucketDescriptor } from "alepha/bucket";
 import * as _alepha_core1 from "alepha";
 import { Alepha, FileLike, Static } from "alepha";
+import "alepha/server/security";
 import * as _alepha_postgres50 from "alepha/postgres";
 import { Page } from "alepha/postgres";
+import * as _alepha_server0 from "alepha/server";
 import { Ok } from "alepha/server";
 import { DateTimeProvider, DurationLike } from "alepha/datetime";
 import * as _alepha_logger0 from "alepha/logger";
@@ -68,6 +70,11 @@ declare const fileQuerySchema: typebox68.TObject<{
   sort: typebox68.TOptional<typebox68.TString>;
   bucket: typebox68.TOptional<typebox68.TString>;
   tags: typebox68.TOptional<typebox68.TArray<typebox68.TString>>;
+  name: typebox68.TOptional<typebox68.TString>;
+  mimeType: typebox68.TOptional<typebox68.TString>;
+  creator: typebox68.TOptional<typebox68.TString>;
+  createdAfter: typebox68.TOptional<typebox68.TString>;
+  createdBefore: typebox68.TOptional<typebox68.TString>;
 }>;
 type FileQuery = Static<typeof fileQuerySchema>;
 //#endregion
@@ -91,6 +98,33 @@ declare const fileResourceSchema: typebox68.TObject<{
 }>;
 type FileResource = Static<typeof fileResourceSchema>;
 //#endregion
+//#region src/schemas/storageStatsSchema.d.ts
+declare const bucketStatsSchema: typebox68.TObject<{
+  bucket: typebox68.TString;
+  totalSize: typebox68.TNumber;
+  fileCount: typebox68.TNumber;
+}>;
+declare const mimeTypeStatsSchema: typebox68.TObject<{
+  mimeType: typebox68.TString;
+  fileCount: typebox68.TNumber;
+}>;
+declare const storageStatsSchema: typebox68.TObject<{
+  totalSize: typebox68.TNumber;
+  totalFiles: typebox68.TNumber;
+  byBucket: typebox68.TArray<typebox68.TObject<{
+    bucket: typebox68.TString;
+    totalSize: typebox68.TNumber;
+    fileCount: typebox68.TNumber;
+  }>>;
+  byMimeType: typebox68.TArray<typebox68.TObject<{
+    mimeType: typebox68.TString;
+    fileCount: typebox68.TNumber;
+  }>>;
+}>;
+type BucketStats = Static<typeof bucketStatsSchema>;
+type MimeTypeStats = Static<typeof mimeTypeStatsSchema>;
+type StorageStats = Static<typeof storageStatsSchema>;
+//#endregion
 //#region src/services/FileService.d.ts
 declare class FileService {
   protected readonly alepha: Alepha;
@@ -148,22 +182,289 @@ declare class FileService {
   protected readonly defaultBucket: BucketDescriptor;
   protected onUploadFile: _alepha_core1.HookDescriptor<"bucket:file:uploaded">;
   protected onDeleteBucketFile: _alepha_core1.HookDescriptor<"bucket:file:deleted">;
+  /**
+   * Calculates SHA-256 checksum of a file.
+   *
+   * @param file - The file to calculate checksum for
+   * @returns Hexadecimal string representation of the SHA-256 hash
+   * @protected
+   */
+  protected calculateChecksum(file: FileLike): Promise<string>;
+  /**
+   * Gets a bucket descriptor by name.
+   *
+   * @param bucketName - The name of the bucket to retrieve (defaults to "default")
+   * @returns The bucket descriptor
+   * @throws {NotFoundError} If the bucket is not found
+   */
   bucket(bucketName?: string): BucketDescriptor;
+  /**
+   * Finds files matching the given query criteria with pagination support.
+   * Supports filtering by bucket, tags, name, mimeType, creator, and date range.
+   *
+   * @param q - Query parameters including bucket, tags, name, mimeType, creator, date range, pagination, and sorting
+   * @returns Paginated list of file entities
+   */
   findFiles(q?: FileQuery): Promise<Page<FileEntity>>;
+  /**
+   * Finds files that have expired based on their expiration date.
+   * Limited to 1000 files per call to prevent memory issues.
+   *
+   * @returns Array of expired file entities
+   */
   findExpiredFiles(): Promise<FileEntity[]>;
+  /**
+   * Calculates an expiration date based on a TTL (time to live) duration.
+   *
+   * @param ttl - Duration like "1 day", "2 hours", etc.
+   * @returns ISO string representation of the expiration date, or undefined if no TTL provided
+   * @protected
+   */
   protected getExpirationDate(ttl?: DurationLike): string | undefined;
+  /**
+   * Uploads a file to a bucket and creates a database record with metadata.
+   * Automatically calculates and stores the file checksum (SHA-256).
+   *
+   * @param file - The file to upload
+   * @param options - Upload options including bucket, expiration, user, and tags
+   * @param options.bucket - Target bucket name (defaults to "default")
+   * @param options.expirationDate - When the file should expire
+   * @param options.user - User performing the upload (for audit trail)
+   * @param options.tags - Tags to associate with the file
+   * @returns The created file entity with all metadata
+   * @throws {NotFoundError} If the specified bucket doesn't exist
+   */
   uploadFile(file: FileLike, options?: {
     expirationDate?: string | Date;
     bucket?: string;
     user?: UserAccountToken;
     tags?: string[];
   }): Promise<FileEntity>;
+  /**
+   * Streams a file from storage by its database ID.
+   *
+   * @param id - The database ID (UUID) of the file to stream
+   * @returns The file object ready for streaming/downloading
+   * @throws {NotFoundError} If the file doesn't exist in the database
+   * @throws {FileNotFoundError} If the file exists in database but not in storage
+   */
   streamFile(id: string): Promise<FileLike>;
+  /**
+   * Updates file metadata (name, tags, expiration date).
+   * Does not modify the actual file content in storage.
+   *
+   * @param id - The database ID (UUID) of the file to update
+   * @param data - Partial file data to update
+   * @param data.name - New file name
+   * @param data.tags - New tags array
+   * @param data.expirationDate - New expiration date
+   * @returns The updated file entity
+   * @throws {NotFoundError} If the file doesn't exist in the database
+   */
+  updateFile(id: string, data: {
+    name?: string;
+    tags?: string[];
+    expirationDate?: string | Date;
+  }): Promise<FileEntity>;
+  /**
+   * Deletes a file from both storage and database.
+   * Handles cases where file is already deleted from storage gracefully.
+   * Always ensures database record is removed even if storage deletion fails.
+   *
+   * @param id - The database ID (UUID) of the file to delete
+   * @returns Success response with the deleted file ID
+   * @throws {NotFoundError} If the file doesn't exist in the database
+   */
   deleteFile(id: string): Promise<Ok>;
+  /**
+   * Retrieves a file entity by its ID.
+   * If already an entity object, returns it as-is (convenience method).
+   *
+   * @param id - Either a UUID string or an existing FileEntity object
+   * @returns The file entity
+   * @throws {NotFoundError} If the file doesn't exist in the database
+   */
   getFileById(id: string | FileEntity): Promise<FileEntity>;
+  /**
+   * Gets storage statistics including total size, file count, and breakdowns by bucket and MIME type.
+   *
+   * @returns Storage statistics with aggregated data
+   */
+  getStorageStats(): Promise<StorageStats>;
+  /**
+   * Converts a file entity to a file resource (API response format).
+   * Currently a pass-through, but allows for future transformation logic.
+   *
+   * @param entity - The file entity to convert
+   * @returns The file resource for API responses
+   */
   entityToResource(entity: FileEntity): FileResource;
 }
 //#endregion
+//#region src/controllers/FileController.d.ts
+/**
+ * REST API controller for file management operations.
+ * Provides endpoints for uploading, downloading, listing, and deleting files.
+ */
+declare class FileController {
+  protected readonly url = "/files";
+  protected readonly group = "files";
+  protected readonly fileService: FileService;
+  /**
+   * GET /files - Lists files with optional filtering and pagination.
+   * Supports filtering by bucket and tags.
+   */
+  readonly findFiles: _alepha_server0.ActionDescriptorFn<{
+    query: typebox68.TObject<{
+      page: typebox68.TOptional<typebox68.TInteger>;
+      size: typebox68.TOptional<typebox68.TInteger>;
+      sort: typebox68.TOptional<typebox68.TString>;
+      bucket: typebox68.TOptional<typebox68.TString>;
+      tags: typebox68.TOptional<typebox68.TArray<typebox68.TString>>;
+      name: typebox68.TOptional<typebox68.TString>;
+      mimeType: typebox68.TOptional<typebox68.TString>;
+      creator: typebox68.TOptional<typebox68.TString>;
+      createdAfter: typebox68.TOptional<typebox68.TString>;
+      createdBefore: typebox68.TOptional<typebox68.TString>;
+    }>;
+    response: _alepha_postgres50.TPage<typebox68.TObject<{
+      id: _alepha_postgres50.PgAttr<_alepha_postgres50.PgAttr<typebox68.TString, typeof _alepha_postgres50.PG_PRIMARY_KEY>, typeof _alepha_postgres50.PG_DEFAULT>;
+      version: _alepha_postgres50.PgAttr<_alepha_postgres50.PgAttr<typebox68.TInteger, typeof _alepha_postgres50.PG_VERSION>, typeof _alepha_postgres50.PG_DEFAULT>;
+      createdAt: _alepha_postgres50.PgAttr<_alepha_postgres50.PgAttr<typebox68.TString, typeof _alepha_postgres50.PG_CREATED_AT>, typeof _alepha_postgres50.PG_DEFAULT>;
+      updatedAt: _alepha_postgres50.PgAttr<_alepha_postgres50.PgAttr<typebox68.TString, typeof _alepha_postgres50.PG_UPDATED_AT>, typeof _alepha_postgres50.PG_DEFAULT>;
+      blobId: typebox68.TString;
+      creator: typebox68.TOptional<typebox68.TString>;
+      creatorRealm: typebox68.TOptional<typebox68.TString>;
+      creatorName: typebox68.TOptional<typebox68.TString>;
+      bucket: typebox68.TString;
+      expirationDate: typebox68.TOptional<typebox68.TString>;
+      name: typebox68.TString;
+      size: typebox68.TNumber;
+      mimeType: typebox68.TString;
+      tags: typebox68.TOptional<typebox68.TArray<typebox68.TString>>;
+      checksum: typebox68.TOptional<typebox68.TString>;
+    }>>;
+  }>;
+  /**
+   * DELETE /files/:id - Deletes a file from both storage and database.
+   * Removes the file from the bucket and cleans up the database record.
+   */
+  readonly deleteFile: _alepha_server0.ActionDescriptorFn<{
+    params: typebox68.TObject<{
+      id: typebox68.TString;
+    }>;
+    response: typebox68.TObject<{
+      ok: typebox68.TBoolean;
+      id: typebox68.TOptional<typebox68.TUnion<[typebox68.TString, typebox68.TInteger]>>;
+      count: typebox68.TOptional<typebox68.TNumber>;
+    }>;
+  }>;
+  /**
+   * POST /files - Uploads a new file to storage.
+   * Creates a database record with metadata and calculates checksum.
+   * Optionally specify bucket and expiration date.
+   */
+  readonly uploadFile: _alepha_server0.ActionDescriptorFn<{
+    body: typebox68.TObject<{
+      file: _alepha_core1.TFile;
+    }>;
+    query: typebox68.TObject<{
+      expirationDate: typebox68.TOptional<typebox68.TString>;
+      bucket: typebox68.TOptional<typebox68.TString>;
+    }>;
+    response: typebox68.TObject<{
+      id: _alepha_postgres50.PgAttr<_alepha_postgres50.PgAttr<typebox68.TString, typeof _alepha_postgres50.PG_PRIMARY_KEY>, typeof _alepha_postgres50.PG_DEFAULT>;
+      version: _alepha_postgres50.PgAttr<_alepha_postgres50.PgAttr<typebox68.TInteger, typeof _alepha_postgres50.PG_VERSION>, typeof _alepha_postgres50.PG_DEFAULT>;
+      createdAt: _alepha_postgres50.PgAttr<_alepha_postgres50.PgAttr<typebox68.TString, typeof _alepha_postgres50.PG_CREATED_AT>, typeof _alepha_postgres50.PG_DEFAULT>;
+      updatedAt: _alepha_postgres50.PgAttr<_alepha_postgres50.PgAttr<typebox68.TString, typeof _alepha_postgres50.PG_UPDATED_AT>, typeof _alepha_postgres50.PG_DEFAULT>;
+      blobId: typebox68.TString;
+      creator: typebox68.TOptional<typebox68.TString>;
+      creatorRealm: typebox68.TOptional<typebox68.TString>;
+      creatorName: typebox68.TOptional<typebox68.TString>;
+      bucket: typebox68.TString;
+      expirationDate: typebox68.TOptional<typebox68.TString>;
+      name: typebox68.TString;
+      size: typebox68.TNumber;
+      mimeType: typebox68.TString;
+      tags: typebox68.TOptional<typebox68.TArray<typebox68.TString>>;
+      checksum: typebox68.TOptional<typebox68.TString>;
+    }>;
+  }>;
+  /**
+   * PATCH /files/:id - Updates file metadata.
+   * Allows updating name, tags, and expiration date without modifying file content.
+   */
+  readonly updateFile: _alepha_server0.ActionDescriptorFn<{
+    params: typebox68.TObject<{
+      id: typebox68.TString;
+    }>;
+    body: typebox68.TObject<{
+      name: typebox68.TOptional<typebox68.TString>;
+      tags: typebox68.TOptional<typebox68.TArray<typebox68.TString>>;
+      expirationDate: typebox68.TOptional<typebox68.TString>;
+    }>;
+    response: typebox68.TObject<{
+      id: _alepha_postgres50.PgAttr<_alepha_postgres50.PgAttr<typebox68.TString, typeof _alepha_postgres50.PG_PRIMARY_KEY>, typeof _alepha_postgres50.PG_DEFAULT>;
+      version: _alepha_postgres50.PgAttr<_alepha_postgres50.PgAttr<typebox68.TInteger, typeof _alepha_postgres50.PG_VERSION>, typeof _alepha_postgres50.PG_DEFAULT>;
+      createdAt: _alepha_postgres50.PgAttr<_alepha_postgres50.PgAttr<typebox68.TString, typeof _alepha_postgres50.PG_CREATED_AT>, typeof _alepha_postgres50.PG_DEFAULT>;
+      updatedAt: _alepha_postgres50.PgAttr<_alepha_postgres50.PgAttr<typebox68.TString, typeof _alepha_postgres50.PG_UPDATED_AT>, typeof _alepha_postgres50.PG_DEFAULT>;
+      blobId: typebox68.TString;
+      creator: typebox68.TOptional<typebox68.TString>;
+      creatorRealm: typebox68.TOptional<typebox68.TString>;
+      creatorName: typebox68.TOptional<typebox68.TString>;
+      bucket: typebox68.TString;
+      expirationDate: typebox68.TOptional<typebox68.TString>;
+      name: typebox68.TString;
+      size: typebox68.TNumber;
+      mimeType: typebox68.TString;
+      tags: typebox68.TOptional<typebox68.TArray<typebox68.TString>>;
+      checksum: typebox68.TOptional<typebox68.TString>;
+    }>;
+  }>;
+  /**
+   * GET /files/:id - Streams/downloads a file by its ID.
+   * Returns the file content with appropriate Content-Type header.
+   * Cached with ETag support for 1 year (immutable).
+   */
+  readonly streamFile: _alepha_server0.ActionDescriptorFn<{
+    params: typebox68.TObject<{
+      id: typebox68.TString;
+    }>;
+    response: _alepha_core1.TFile;
+  }>;
+}
+//#endregion
+//#region src/controllers/StorageStatsController.d.ts
+/**
+ * REST API controller for storage analytics and statistics.
+ * Provides endpoints for viewing storage usage metrics.
+ */
+declare class StorageStatsController {
+  protected readonly url = "/files/stats";
+  protected readonly group = "files";
+  protected readonly fileService: FileService;
+  /**
+   * GET /files/stats - Gets storage statistics.
+   * Returns aggregated data including total size, file count,
+   * and breakdowns by bucket and MIME type.
+   */
+  readonly getStats: _alepha_server0.ActionDescriptorFn<{
+    response: typebox68.TObject<{
+      totalSize: typebox68.TNumber;
+      totalFiles: typebox68.TNumber;
+      byBucket: typebox68.TArray<typebox68.TObject<{
+        bucket: typebox68.TString;
+        totalSize: typebox68.TNumber;
+        fileCount: typebox68.TNumber;
+      }>>;
+      byMimeType: typebox68.TArray<typebox68.TObject<{
+        mimeType: typebox68.TString;
+        fileCount: typebox68.TNumber;
+      }>>;
+    }>;
+  }>;
+}
+//#endregion
 //#region src/index.d.ts
 declare module "alepha/bucket" {
   interface BucketFileOptions {
@@ -197,5 +498,5 @@ declare module "alepha/bucket" {
  */
 declare const AlephaApiFiles: _alepha_core1.Service<_alepha_core1.Module<{}>>;
 //#endregion
-export { AlephaApiFiles, FileEntity, FileService, files };
+export { AlephaApiFiles, BucketStats, FileController, FileEntity, FileService, MimeTypeStats, StorageStats, StorageStatsController, bucketStatsSchema, files, mimeTypeStatsSchema, storageStatsSchema };
 //# sourceMappingURL=index.d.ts.map