@dereekb/firebase-server 13.11.17 → 13.12.0

package/model/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@dereekb/firebase-server/model",
-  "version": "13.11.17",
+  "version": "13.12.0",
   "peerDependencies": {
-    "@dereekb/analytics": "13.11.17",
-    "@dereekb/date": "13.11.17",
-    "@dereekb/firebase": "13.11.17",
-    "@dereekb/firebase-server": "13.11.17",
-    "@dereekb/model": "13.11.17",
-    "@dereekb/nestjs": "13.11.17",
-    "@dereekb/rxjs": "13.11.17",
-    "@dereekb/util": "13.11.17",
+    "@dereekb/analytics": "13.12.0",
+    "@dereekb/date": "13.12.0",
+    "@dereekb/firebase": "13.12.0",
+    "@dereekb/firebase-server": "13.12.0",
+    "@dereekb/model": "13.12.0",
+    "@dereekb/nestjs": "13.12.0",
+    "@dereekb/rxjs": "13.12.0",
+    "@dereekb/util": "13.12.0",
     "@nestjs/common": "^11.1.19",
     "@nestjs/config": "^4.0.4",
     "archiver": "^7.0.1",

package/model/src/lib/storagefile/extension/compress.pdf.d.ts

@@ -27,10 +27,38 @@ export interface CompressPdfImagesToTargetSizeConfig {
      */
     readonly imageSizeThresholdBytes?: Maybe<number>;
 }
+/**
+ * Per-filter image stream counts (e.g. `{ DCTDecode: 2, FlateDecode: 1 }`). Streams
+ * with no `/Filter` entry are bucketed under `'none'`; multi-filter chains are
+ * joined with `+` (e.g. `'FlateDecode+DCTDecode'`).
+ */
+export type CompressPdfImageStreamsByFilter = Readonly<Record<string, number>>;
+/**
+ * Diagnostic context describing the source PDF — useful for explaining why a
+ * compression attempt did or did not hit its target.
+ */
+export interface CompressPdfImagesToTargetSizeContext {
+    /**
+     * Number of pages in the source PDF.
+     */
+    readonly pageCount: number;
+    /**
+     * Total number of image XObjects (Subtype `/Image`) found in the PDF, regardless
+     * of whether they were compressible by this implementation.
+     */
+    readonly imageStreamCount: number;
+    /**
+     * Breakdown of image XObjects by their PDF filter. If `hitTarget` is `false` and
+     * this map only contains non-JPEG filters (e.g. `FlateDecode`, `CCITTFaxDecode`,
+     * `JBIG2Decode`, `JPXDecode`), the v1 compressor cannot help — callers should
+     * reject the upload or queue a downscale fallback.
+     */
+    readonly imageStreamsByFilter: CompressPdfImageStreamsByFilter;
+}
 /**
  * Result of {@link compressPdfImagesToTargetSize}.
  */
-export interface CompressPdfImagesToTargetSizeResult {
+export interface CompressPdfImagesToTargetSizeResult extends CompressPdfImagesToTargetSizeContext {
     /**
      * Best-effort compressed PDF bytes. Equal to the original buffer if recompression
      * produced no smaller result.

package/model/src/lib/storagefile/index.d.ts

@@ -2,6 +2,7 @@ export * from './extension';
 export * from './storagefile.action.server';
 export * from './storagefile.action.server.init';
 export * from './storagefile.error';
+export * from './storagefile.mcp';
 export * from './storagefile.module';
 export * from './storagefile.task.service.handler';
 export * from './storagefile.upload.service';

package/model/src/lib/storagefile/storagefile.action.server.d.ts

@@ -1,4 +1,4 @@
-import { type FirestoreContextReference, type InitializeStorageFileFromUploadParams, type AsyncStorageFileCreateAction, type StorageFileFirestoreCollections, type ProcessStorageFileParams, type StorageFileDocument, type ProcessStorageFileResult, type CreateStorageFileParams, type AsyncStorageFileUpdateAction, type UpdateStorageFileParams, type NotificationFirestoreCollections, type FirebaseStorageAccessorFile, type InitializeAllStorageFilesFromUploadsResult, type InitializeAllStorageFilesFromUploadsParams, type ProcessAllQueuedStorageFilesParams, type ProcessAllQueuedStorageFilesResult, type DeleteAllQueuedStorageFilesParams, type DeleteAllQueuedStorageFilesResult, type DeleteStorageFileParams, type AsyncStorageFileDeleteAction, type StorageFile, type DownloadStorageFileParams, type DownloadStorageFileResult, type DownloadMultipleStorageFilesParams, type DownloadMultipleStorageFilesResult, type DownloadMultipleStorageFileSuccessItem, type FirestoreModelKey, type SyncStorageFileWithGroupsParams, type SyncAllFlaggedStorageFilesWithGroupsParams, type SyncAllFlaggedStorageFilesWithGroupsResult, type SyncStorageFileWithGroupsResult, type RegenerateAllFlaggedStorageFileGroupsContentParams, type RegenerateAllFlaggedStorageFileGroupsContentResult, type RegenerateStorageFileGroupContentParams, type RegenerateStorageFileGroupContentResult, type StorageFileGroupDocument, type AsyncStorageFileGroupCreateAction, type CreateStorageFileGroupParams, type Transaction, type StorageFileGroup, type StorageFileGroupDocumentReferencePair, type StorageFileGroupId, type UpdateStorageFileGroupParams, type DownloadStorageFileOptions } from '@dereekb/firebase';
+import { type FirestoreContextReference, type InitializeStorageFileFromUploadParams, type AsyncStorageFileCreateAction, type StorageFileFirestoreCollections, type ProcessStorageFileParams, type StorageFileDocument, type ProcessStorageFileResult, type CreateStorageFileParams, type AsyncStorageFileUpdateAction, type UpdateStorageFileParams, type NotificationFirestoreCollections, type FirebaseStorageAccessorFile, type InitializeAllStorageFilesFromUploadsResult, type InitializeAllStorageFilesFromUploadsParams, type ProcessAllQueuedStorageFilesParams, type ProcessAllQueuedStorageFilesResult, type DeleteAllQueuedStorageFilesParams, type DeleteAllQueuedStorageFilesResult, type DeleteStorageFileParams, type AsyncStorageFileDeleteAction, type StorageFile, type DownloadStorageFileParams, type DownloadStorageFileResult, type DownloadMultipleStorageFilesParams, type DownloadMultipleStorageFilesResult, type DownloadMultipleStorageFileSuccessItem, type FirestoreModelKey, type SyncStorageFileWithGroupsParams, type SyncAllFlaggedStorageFilesWithGroupsParams, type SyncAllFlaggedStorageFilesWithGroupsResult, type SyncStorageFileWithGroupsResult, type RegenerateAllFlaggedStorageFileGroupsContentParams, type RegenerateAllFlaggedStorageFileGroupsContentResult, type RegenerateStorageFileGroupContentParams, type RegenerateStorageFileGroupContentResult, type StorageFileGroupDocument, type AsyncStorageFileGroupCreateAction, type CreateStorageFileGroupParams, type Transaction, type StorageFileGroup, type StorageFileGroupDocumentReferencePair, type StorageFileGroupId, type UpdateStorageFileGroupParams, type DownloadStorageFileOptions, type CreateStorageFileSignedUploadUrlParams, type CreateStorageFileSignedUploadUrlResult, type StorageFilePurposeUploadPolicy, type FirebaseAuthUserId, type AsyncFirebaseFunctionCreateAction } from '@dereekb/firebase';
 import { type FirebaseServerStorageServiceRef, type FirebaseServerActionsContext, type FirebaseServerAuthServiceRef } from '@dereekb/firebase-server';
 import { type TransformAndValidateFunctionResult } from '@dereekb/model';
 import { type InjectionToken } from '@nestjs/common';
@@ -24,9 +24,11 @@ export interface BaseStorageFileServerActionsContext extends FirebaseServerActio
 }
 /**
  * Full context for storage file server actions, extending the base with the
- * upload initialization service.
+ * upload initialization service and the per-purpose signed-upload policy
+ * registry consulted by `createStorageFileSignedUploadUrl`.
  */
 export interface StorageFileServerActionsContext extends BaseStorageFileServerActionsContext, StorageFileInitializeFromUploadServiceRef {
+    readonly storageFileSignedUploadPolicies: readonly StorageFilePurposeUploadPolicy[];
 }
 /**
  * Abstract service class defining all server-side storage file CRUD, upload processing, and group management actions.
@@ -45,6 +47,9 @@ export interface StorageFileServerActionsContext extends BaseStorageFileServerAc
  */
 export declare abstract class StorageFileServerActions {
     abstract createStorageFile(params: CreateStorageFileParams): AsyncStorageFileCreateAction<CreateStorageFileParams>;
+    abstract createStorageFileSignedUploadUrl(params: CreateStorageFileSignedUploadUrlParams): AsyncFirebaseFunctionCreateAction<CreateStorageFileSignedUploadUrlParams, CreateStorageFileSignedUploadUrlResult, {
+        readonly uid: FirebaseAuthUserId;
+    }>;
     abstract initializeAllStorageFilesFromUploads(params: InitializeAllStorageFilesFromUploadsParams): Promise<TransformAndValidateFunctionResult<InitializeAllStorageFilesFromUploadsParams, () => Promise<InitializeAllStorageFilesFromUploadsResult>>>;
     abstract initializeStorageFileFromUpload(params: InitializeStorageFileFromUploadParams): AsyncStorageFileCreateAction<InitializeStorageFileFromUploadParams>;
     abstract updateStorageFile(params: UpdateStorageFileParams): AsyncStorageFileUpdateAction<UpdateStorageFileParams>;
@@ -86,6 +91,28 @@ export declare function storageFileServerActions(context: StorageFileServerActio
  * @returns An async transform-and-validate function that creates a StorageFile document.
  */
 export declare function createStorageFileFactory(context: BaseStorageFileServerActionsContext): import("@dereekb/model").TransformAndValidateFunctionResultFunction<CreateStorageFileParams, () => Promise<StorageFileDocument>, object, unknown>;
+/**
+ * Factory for the `createStorageFileSignedUploadUrl` action.
+ *
+ * Issues a short-lived, content-type-pinned signed PUT URL into the caller's
+ * `/uploads/u/{uid}/...` namespace. The path, content-type, and size cap are
+ * derived from the per-purpose policy resolved from the
+ * `storageFileSignedUploadPolicies` registry on the context, so the URL can
+ * only write to a location that both `storage.rules` and the
+ * `StorageFileInitializeFromUploadService` initializer accept.
+ *
+ * Minting a URL does NOT create a StorageFile document — `result.modelKeys` is
+ * always empty. The document is created later by the upload-complete pipeline.
+ *
+ * @param context - The storage file server actions context. Must carry
+ *   `storageFileSignedUploadPolicies` — the list of `StorageFilePurposeUploadPolicy` entries to resolve by purpose.
+ * @returns An async transform-and-validate function whose inner stage takes
+ *   `{ uid }` (the authenticated user) and returns the signed-upload-url
+ *   payload.
+ */
+export declare function createStorageFileSignedUploadUrlFactory(context: StorageFileServerActionsContext): import("@dereekb/model").TransformAndValidateFunctionResultFunction<CreateStorageFileSignedUploadUrlParams, ({ uid }: {
+    readonly uid: FirebaseAuthUserId;
+}) => Promise<CreateStorageFileSignedUploadUrlResult>, object, unknown>;
 /**
  * Factory for the `initializeAllStorageFilesFromUploads` action.
  *

package/model/src/lib/storagefile/storagefile.mcp.d.ts

@@ -0,0 +1,32 @@
+import { type StorageFilePurposeUploadPolicy } from '@dereekb/firebase';
+import { type McpToolDetailsBuilder } from '@dereekb/firebase-server';
+/**
+ * Config for {@link storageFileCreateSignedUploadUrlToolDetailsFactory}.
+ */
+export interface StorageFileCreateSignedUploadUrlToolDetailsFactoryConfig {
+    /**
+     * The list of upload policies the app supports. Each policy's `purpose` is exposed in the
+     * tool's input schema enum and described in the generated tool description.
+     */
+    readonly policies: readonly StorageFilePurposeUploadPolicy[];
+}
+/**
+ * Builds the {@link McpToolDetailsBuilder} that customizes the MCP tool description and
+ * input schema for the `storageFileCreateSignedUploadUrl` create-function.
+ *
+ * The factory captures the policy list once at wiring time; the returned builder is a pure
+ * synchronous function called by the framework on every `tools/list` request.
+ *
+ * @param config - Factory config containing the upload policies that drive the description and `purpose` enum.
+ * @returns A builder that emits the policy-aware tool description and an input schema with the `purpose` enum constrained to the configured purposes.
+ *
+ * @example
+ * ```ts
+ * const toolDetails = storageFileCreateSignedUploadUrlToolDetailsFactory({
+ *   policies: STORAGE_FILE_PURPOSE_UPLOAD_POLICIES
+ * });
+ * ```
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function storageFileCreateSignedUploadUrlToolDetailsFactory(config: StorageFileCreateSignedUploadUrlToolDetailsFactoryConfig): McpToolDetailsBuilder;

package/model/src/lib/storagefile/storagefile.module.d.ts

@@ -1,17 +1,27 @@
-import { type ModuleMetadata } from '@nestjs/common';
+import { type InjectionToken, type ModuleMetadata } from '@nestjs/common';
 import { type Maybe } from '@dereekb/util';
+import { type StorageFilePurposeUploadPolicy } from '@dereekb/firebase';
 import { type BaseStorageFileServerActionsContext, StorageFileServerActions, type StorageFileServerActionsContext } from './storagefile.action.server';
 import { StorageFileInitializeFromUploadService } from './storagefile.upload.service';
 import { StorageFileInitServerActions, type StorageFileInitServerActionsContextConfig } from './storagefile.action.server.init';
+/**
+ * NestJS injection token for the per-purpose `StorageFilePurposeUploadPolicy[]`
+ * registry that the `createStorageFileSignedUploadUrl` factory consults.
+ *
+ * Apps bind this token via {@link appStorageFileModuleMetadata} by passing
+ * `storageFileSignedUploadPolicies` in {@link ProvideAppStorageFileMetadataConfig}.
+ */
+export declare const STORAGE_FILE_SIGNED_UPLOAD_POLICIES_TOKEN: InjectionToken;
 /**
  * Factory that assembles the full {@link StorageFileServerActionsContext} by combining
- * the base context with the upload initialization service.
+ * the base context with the upload initialization service and the signed-upload policy registry.
  *
  * @param context - The base server actions context providing Firebase infrastructure.
  * @param storageFileInitializeFromUploadService - The service for initializing storage files from uploads.
+ * @param storageFileSignedUploadPolicies - The per-purpose upload policy registry consulted by `createStorageFileSignedUploadUrl`.
  * @returns The fully assembled StorageFileServerActionsContext.
  */
-export declare function storageFileServerActionsContextFactory(context: BaseStorageFileServerActionsContext, storageFileInitializeFromUploadService: StorageFileInitializeFromUploadService): StorageFileServerActionsContext;
+export declare function storageFileServerActionsContextFactory(context: BaseStorageFileServerActionsContext, storageFileInitializeFromUploadService: StorageFileInitializeFromUploadService, storageFileSignedUploadPolicies: readonly StorageFilePurposeUploadPolicy[]): StorageFileServerActionsContext;
 /**
  * Factory that creates a {@link StorageFileServerActions} instance from the assembled context.
  *
@@ -38,6 +48,13 @@ export interface ProvideAppStorageFileMetadataConfig extends Pick<ModuleMetadata
      * This module declaration makes it easier to import a module that exports those depenendencies.
      */
     readonly dependencyModule?: Maybe<Required<ModuleMetadata>['imports']['0']>;
+    /**
+     * Per-purpose upload policy registry. Bound to
+     * {@link STORAGE_FILE_SIGNED_UPLOAD_POLICIES_TOKEN} and consulted by the
+     * `createStorageFileSignedUploadUrl` action to resolve the storage path,
+     * allowed content types, and max file size for each purpose.
+     */
+    readonly storageFileSignedUploadPolicies: readonly StorageFilePurposeUploadPolicy[];
 }
 /**
  * Convenience function used to generate ModuleMetadata for an app's StorageFileModule.