@bymax-one/nest-storage 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,1210 @@
1
+ import { ModuleMetadata, Type, DynamicModule, OnModuleInit, OnApplicationShutdown, HttpException, HttpStatus } from '@nestjs/common';
2
+ import { S3Client } from '@aws-sdk/client-s3';
3
+
4
+ /**
5
+ * @fileoverview Pluggable upload-validator contract. Implementations run in order
6
+ * before the S3 PutObject — the first that returns `{ ok: false }` aborts the
7
+ * upload.
8
+ * @layer server/interfaces
9
+ */
10
+ /**
11
+ * Pluggable upload validator.
12
+ *
13
+ * @example
14
+ * class PdfMagicByteValidator implements IUploadValidator {
15
+ * readonly name = 'pdf-magic-byte'
16
+ * async validate(ctx) {
17
+ * if (ctx.contentType !== 'application/pdf' || !ctx.readBytes) return { ok: true }
18
+ * const head = await ctx.readBytes(4)
19
+ * return head.toString('ascii') === '%PDF'
20
+ * ? { ok: true }
21
+ * : { ok: false, reason: 'Declared as PDF but missing magic bytes' }
22
+ * }
23
+ * }
24
+ */
25
+ interface IUploadValidator {
26
+ /** Unique name — used in error logs. */
27
+ readonly name: string;
28
+ validate(context: {
29
+ key: string;
30
+ contentType: string;
31
+ size?: number;
32
+ metadata?: Record<string, string>;
33
+ /**
34
+ * Reads up to `maxBytes` from the body without consuming it for the actual
35
+ * upload. Useful for magic-byte sniffing on streams.
36
+ */
37
+ readBytes?: (maxBytes: number) => Promise<Buffer>;
38
+ }): Promise<{
39
+ ok: true;
40
+ } | {
41
+ ok: false;
42
+ reason: string;
43
+ }>;
44
+ }
45
+
46
+ /**
47
+ * @fileoverview Pluggable file-scanner contract (virus, malware, content
48
+ * moderation) and its result shape.
49
+ * @layer server/interfaces
50
+ */
51
+ /**
52
+ * Pluggable file scanner. Receives bytes in pre-upload mode, only metadata in
53
+ * post-upload mode.
54
+ */
55
+ interface IFileScanner {
56
+ scan(input: {
57
+ /** `'pre-upload'` includes `body`; `'post-upload'` has only key/bucket/contentType. */
58
+ mode: 'pre-upload' | 'post-upload';
59
+ body?: Buffer | NodeJS.ReadableStream;
60
+ key: string;
61
+ bucket: string;
62
+ contentType: string;
63
+ size?: number;
64
+ }): Promise<FileScanResult>;
65
+ }
66
+ /** Outcome of a file scan. */
67
+ interface FileScanResult {
68
+ status: 'clean' | 'infected' | 'unknown';
69
+ /** Engine name — e.g. `'clamav-0.103'`, `'aws-macie'`. */
70
+ engine: string;
71
+ /** Threat name when `status === 'infected'`. */
72
+ threat?: string;
73
+ details?: Record<string, unknown>;
74
+ }
75
+
76
+ /**
77
+ * @fileoverview Public configuration contracts for the dynamic module —
78
+ * synchronous options, async options, and the options factory.
79
+ * @layer server/interfaces
80
+ */
81
+
82
+ /**
83
+ * Synchronous configuration for `BymaxStorageModule.forRoot()`.
84
+ *
85
+ * `defaultPublicRead` applies an ACL on uploads. NOTE: ACLs fail with HTTP 400
86
+ * `AccessControlListNotSupported` on modern AWS S3 buckets (Object Ownership =
87
+ * "Bucket owner enforced") and are a no-op on Cloudflare R2 — prefer a bucket
88
+ * policy, a CDN, or signed URLs.
89
+ */
90
+ interface BymaxStorageModuleOptions {
91
+ /** S3-compatible endpoint. REQUIRED. */
92
+ endpoint: string;
93
+ /** Region — `'auto'` for R2, any non-empty string for MinIO. REQUIRED. */
94
+ region: string;
95
+ /** Default bucket — overridable per call. REQUIRED. */
96
+ bucket: string;
97
+ /** Credentials — inject via ConfigService, never hardcode. REQUIRED. */
98
+ credentials: {
99
+ accessKeyId: string;
100
+ secretAccessKey: string;
101
+ /** STS / OIDC temporary session token. */
102
+ sessionToken?: string;
103
+ };
104
+ /** `false` = virtual-hosted, `true` = path-style (MinIO). Default: `false`. */
105
+ forcePathStyle?: boolean;
106
+ /** Public base URL for direct links. Fallback: endpoint + bucket. */
107
+ publicBaseUrl?: string;
108
+ /** When set, `getPublicUrl()` returns the CDN URL instead. */
109
+ cdnBaseUrl?: string;
110
+ /**
111
+ * Apply ACL `public-read` on uploads. Default: `false`. Fails with HTTP 400
112
+ * on modern AWS S3 (ACLs disabled) and is a no-op on R2 — prefer bucket
113
+ * policy / CDN / signed URLs.
114
+ */
115
+ defaultPublicRead?: boolean;
116
+ /** Global key prefix applied to every operation — useful for multi-tenant isolation. */
117
+ keyPrefix?: string;
118
+ /** Default `Cache-Control` header on uploads. */
119
+ defaultCacheControl?: string;
120
+ /** Default `Content-Disposition`. */
121
+ defaultContentDisposition?: 'inline' | 'attachment';
122
+ signedUrls?: {
123
+ /** Default GET TTL (seconds). Default: `300`. */
124
+ defaultGetTtlSeconds?: number;
125
+ /** Default PUT TTL (seconds). Default: `300`. */
126
+ defaultPutTtlSeconds?: number;
127
+ /** Hard cap — higher TTLs are silently clamped. Default: `604800` (7 days). */
128
+ maxTtlSeconds?: number;
129
+ };
130
+ multipart?: {
131
+ /** Bytes threshold to switch to multipart. Default: `5242880` (5 MB). */
132
+ thresholdBytes?: number;
133
+ /** Size per part (S3 minimum: 5 MB). Default: 5 MB. */
134
+ partSizeBytes?: number;
135
+ /** Concurrent parts. Default: `4`. */
136
+ queueSize?: number;
137
+ };
138
+ /** Enables the validation pipeline when present. */
139
+ validation?: {
140
+ /** MIME whitelist — supports wildcards like `'image/*'`. */
141
+ mimeWhitelist?: readonly string[];
142
+ /** Max upload size in bytes. */
143
+ maxSizeBytes?: number;
144
+ /** Custom validators run in order; the first rejection short-circuits. */
145
+ customValidators?: readonly IUploadValidator[];
146
+ };
147
+ /** Enables the file scanner when present. */
148
+ scanner?: {
149
+ impl: IFileScanner;
150
+ /** `'pre-upload'` (default) scans before; `'post-upload'` scans after. */
151
+ mode?: 'pre-upload' | 'post-upload';
152
+ /** Reject when the scanner returns `'unknown'`. Default: `false`. */
153
+ rejectOnUnknown?: boolean;
154
+ };
155
+ /** Server-side encryption. */
156
+ serverSideEncryption?: 'AES256' | 'aws:kms';
157
+ /** Required when `serverSideEncryption === 'aws:kms'`. */
158
+ kmsKeyId?: string;
159
+ /**
160
+ * S3Client `requestChecksumCalculation`. AWS SDK v3 defaults to
161
+ * `'WHEN_SUPPORTED'` (CRC32 integrity headers); non-AWS providers (R2, B2,
162
+ * MinIO, Spaces) require `'WHEN_REQUIRED'`. Provider recipes set it.
163
+ */
164
+ requestChecksumCalculation?: 'WHEN_SUPPORTED' | 'WHEN_REQUIRED';
165
+ /** S3Client `responseChecksumValidation` (checksum mode on GET). Same provider caveat. */
166
+ responseChecksumValidation?: 'WHEN_SUPPORTED' | 'WHEN_REQUIRED';
167
+ /** Total attempts including the first try (maps to `maxAttempts`). Default: `3`. */
168
+ maxAttempts?: number;
169
+ /** Per-request timeout. Default: `30000` ms. */
170
+ requestTimeoutMs?: number;
171
+ }
172
+ /**
173
+ * Asynchronous configuration for `BymaxStorageModule.forRootAsync()` — the
174
+ * standard NestJS async dynamic-module options shape.
175
+ */
176
+ interface BymaxStorageModuleAsyncOptions extends Pick<ModuleMetadata, 'imports'> {
177
+ useFactory?: (...args: unknown[]) => BymaxStorageModuleOptions | Promise<BymaxStorageModuleOptions>;
178
+ inject?: readonly (string | symbol | Type<unknown>)[];
179
+ useExisting?: Type<BymaxStorageModuleOptionsFactory>;
180
+ useClass?: Type<BymaxStorageModuleOptionsFactory>;
181
+ }
182
+ /** Factory contract for `useExisting` / `useClass` async configuration. */
183
+ interface BymaxStorageModuleOptionsFactory {
184
+ createStorageOptions(): BymaxStorageModuleOptions | Promise<BymaxStorageModuleOptions>;
185
+ }
186
+
187
+ /**
188
+ * @fileoverview The `@Global()` dynamic module. `forRoot()` resolves options
189
+ * synchronously; `forRootAsync()` resolves them from injected dependencies
190
+ * (`useFactory`/`useClass`/`useExisting`). Both wire the identical provider and
191
+ * export surface — the S3 client lifecycle, key resolver, the public facades, and
192
+ * the internal validation/scanner services — so the module behaves the same way
193
+ * regardless of how it was configured.
194
+ * @layer server/module
195
+ */
196
+
197
+ declare class BymaxStorageModule {
198
+ /**
199
+ * Synchronous configuration. Validates and resolves the options, then returns
200
+ * the wired dynamic module.
201
+ *
202
+ * @param options - The storage module options.
203
+ * @returns The configured `DynamicModule`.
204
+ * @throws StorageException with code `STORAGE_INVALID_CONFIG` on invalid options.
205
+ *
206
+ * @example
207
+ * BymaxStorageModule.forRoot({
208
+ * endpoint: 'https://s3.us-east-1.amazonaws.com',
209
+ * region: 'us-east-1',
210
+ * bucket: 'my-bucket',
211
+ * credentials: { accessKeyId, secretAccessKey },
212
+ * })
213
+ */
214
+ static forRoot(options: BymaxStorageModuleOptions): DynamicModule;
215
+ /**
216
+ * Asynchronous configuration (the canonical NestJS pattern). Resolves the
217
+ * options from injected dependencies via `useFactory` (+ `inject`), `useClass`,
218
+ * or `useExisting`, running `validateOptions` + `applyDefaults` inside the
219
+ * factory. Replicates every provider and export of {@link forRoot}.
220
+ *
221
+ * @param asyncOptions - The async options descriptor.
222
+ * @returns The configured `DynamicModule`.
223
+ * @throws Error when none of `useFactory`/`useClass`/`useExisting` is provided.
224
+ *
225
+ * @example
226
+ * BymaxStorageModule.forRootAsync({
227
+ * imports: [ConfigModule],
228
+ * inject: [ConfigService],
229
+ * useFactory: (config: ConfigService) => ({
230
+ * endpoint: config.getOrThrow('S3_ENDPOINT'),
231
+ * region: config.getOrThrow('S3_REGION'),
232
+ * bucket: config.getOrThrow('S3_BUCKET'),
233
+ * credentials: {
234
+ * accessKeyId: config.getOrThrow('S3_ACCESS_KEY_ID'),
235
+ * secretAccessKey: config.getOrThrow('S3_SECRET_ACCESS_KEY'),
236
+ * },
237
+ * }),
238
+ * })
239
+ */
240
+ static forRootAsync(asyncOptions: BymaxStorageModuleAsyncOptions): DynamicModule;
241
+ /** Providers shared by both configuration paths (options-agnostic). */
242
+ private static buildCoreProviders;
243
+ /**
244
+ * Public DI surface: the facades, the resolved options, the raw-client token,
245
+ * and the user-supplied validators + scanner tokens. Internal services and the
246
+ * idempotency cache are intentionally not exported.
247
+ */
248
+ private static buildExports;
249
+ /**
250
+ * Builds the options provider plus, for `useClass`, the factory-class provider
251
+ * that must be registered so Nest can instantiate and inject it.
252
+ */
253
+ private static buildAsyncOptionsProviders;
254
+ /** Builds the `BYMAX_STORAGE_OPTIONS` provider from the async descriptor. */
255
+ private static createAsyncOptionsProvider;
256
+ }
257
+
258
+ /**
259
+ * @fileoverview The fully-resolved options shape consumed internally by services
260
+ * so they never deal with `undefined` for fields that carry a default.
261
+ * @layer server/config
262
+ */
263
+
264
+ /** Every optional field with a default is present and typed as required. */
265
+ interface ResolvedBymaxStorageOptions {
266
+ endpoint: string;
267
+ region: string;
268
+ bucket: string;
269
+ credentials: {
270
+ accessKeyId: string;
271
+ secretAccessKey: string;
272
+ sessionToken?: string;
273
+ };
274
+ forcePathStyle: boolean;
275
+ publicBaseUrl: string;
276
+ cdnBaseUrl?: string;
277
+ defaultPublicRead: boolean;
278
+ keyPrefix: string;
279
+ defaultCacheControl: string;
280
+ defaultContentDisposition: 'inline' | 'attachment';
281
+ signedUrls: {
282
+ defaultGetTtlSeconds: number;
283
+ defaultPutTtlSeconds: number;
284
+ maxTtlSeconds: number;
285
+ };
286
+ multipart: {
287
+ thresholdBytes: number;
288
+ partSizeBytes: number;
289
+ queueSize: number;
290
+ };
291
+ validation?: BymaxStorageModuleOptions['validation'];
292
+ scanner?: BymaxStorageModuleOptions['scanner'];
293
+ serverSideEncryption?: 'AES256' | 'aws:kms';
294
+ kmsKeyId?: string;
295
+ requestChecksumCalculation: 'WHEN_SUPPORTED' | 'WHEN_REQUIRED';
296
+ responseChecksumValidation: 'WHEN_SUPPORTED' | 'WHEN_REQUIRED';
297
+ maxAttempts: number;
298
+ requestTimeoutMs: number;
299
+ /** True when both `accessKeyId` and `secretAccessKey` are non-empty. */
300
+ hasCredentials: boolean;
301
+ }
302
+
303
+ /**
304
+ * @fileoverview Per-call options for `StorageService.upload()`.
305
+ * @layer server/interfaces
306
+ */
307
+ /** Options for a single upload call. */
308
+ interface UploadOptions {
309
+ key: string;
310
+ /** Buffer (small/medium), Readable (large), or Uint8Array. */
311
+ body: Buffer | NodeJS.ReadableStream | Uint8Array;
312
+ contentType: string;
313
+ bucket?: string;
314
+ /** Required for validation and optimal multipart sizing. */
315
+ size?: number;
316
+ cacheControl?: string;
317
+ /** `'inline'`, `'attachment'`, or a full `Content-Disposition` value. */
318
+ contentDisposition?: string;
319
+ /** Default: `defaultPublicRead` from module options. */
320
+ publicRead?: boolean;
321
+ /** `'NONE'` forces no SSE even when a default is set globally. */
322
+ serverSideEncryption?: 'AES256' | 'aws:kms' | 'NONE';
323
+ kmsKeyId?: string;
324
+ /** Custom `x-amz-meta-*` headers. */
325
+ metadata?: Record<string, string>;
326
+ /**
327
+ * If the same `idempotencyKey` was seen within the cache TTL window, the
328
+ * cached `UploadResult` is returned without re-uploading.
329
+ */
330
+ idempotencyKey?: string;
331
+ /** Progress callback fired after each multipart part (or once for single). */
332
+ onProgress?: (event: {
333
+ loaded: number;
334
+ total?: number;
335
+ part?: number;
336
+ }) => void;
337
+ }
338
+
339
+ /**
340
+ * @fileoverview Per-call options for `StorageService.download()`.
341
+ * @layer server/interfaces
342
+ */
343
+ /** Options for a single download call. */
344
+ interface DownloadOptions {
345
+ key: string;
346
+ bucket?: string;
347
+ /** S3 Range header — e.g. `'bytes=0-1023'` for partial downloads. */
348
+ range?: string;
349
+ /** Conditional GET — only return if the ETag does NOT match. */
350
+ ifNoneMatch?: string;
351
+ /** Conditional GET — only return if the ETag matches. */
352
+ ifMatch?: string;
353
+ }
354
+
355
+ /**
356
+ * @fileoverview Pure data shapes returned by storage operations. Zero NestJS or
357
+ * AWS SDK dependencies — safe to import in frontends, edge functions, or other
358
+ * non-Node environments.
359
+ * @layer shared/types
360
+ */
361
+ /** Outcome of an upload — returned to the caller. */
362
+ interface UploadResult {
363
+ /** Final key after normalization and the global key prefix. */
364
+ key: string;
365
+ bucket: string;
366
+ etag: string;
367
+ /** Only set on versioned buckets. */
368
+ versionId?: string;
369
+ size?: number;
370
+ contentType: string;
371
+ publicUrl: string;
372
+ /** True when the multipart pathway was used. */
373
+ multipart: boolean;
374
+ /** True when the result was returned from the idempotency cache. */
375
+ fromIdempotencyCache: boolean;
376
+ }
377
+ /** Object metadata as returned by `head()` and `download()`. */
378
+ interface ObjectMetadata {
379
+ key: string;
380
+ bucket: string;
381
+ size: number;
382
+ contentType: string;
383
+ etag: string;
384
+ lastModified: Date;
385
+ cacheControl?: string;
386
+ contentDisposition?: string;
387
+ /** `x-amz-meta-*` custom metadata. */
388
+ metadata: Record<string, string>;
389
+ /** S3 storage class (STANDARD, GLACIER, etc.). */
390
+ storageClass?: string;
391
+ versionId?: string;
392
+ }
393
+ /** Result row returned by `list()`. */
394
+ interface ListedObject {
395
+ key: string;
396
+ size: number;
397
+ etag: string;
398
+ lastModified: Date;
399
+ storageClass?: string;
400
+ }
401
+
402
+ /**
403
+ * @fileoverview Per-call options and the result shape for `StorageService.list()`.
404
+ * @layer server/interfaces
405
+ */
406
+
407
+ /** Options for a single list call. */
408
+ interface ListOptions {
409
+ /** Filter prefix (applied AFTER the global key prefix). */
410
+ prefix?: string;
411
+ bucket?: string;
412
+ /** Page size. Default: `1000` (S3 hard max). */
413
+ maxKeys?: number;
414
+ /** Token from a previous page. */
415
+ continuationToken?: string;
416
+ /**
417
+ * Delimiter for pseudo-hierarchical listing. When `'/'`, objects under
418
+ * sub-prefixes are aggregated into `commonPrefixes`.
419
+ */
420
+ delimiter?: string;
421
+ }
422
+ /** Result of a single list call. */
423
+ interface ListResult {
424
+ objects: ListedObject[];
425
+ commonPrefixes: string[];
426
+ isTruncated: boolean;
427
+ nextContinuationToken?: string;
428
+ }
429
+
430
+ /**
431
+ * @fileoverview Per-call options for `StorageService.copy()`.
432
+ * @layer server/interfaces
433
+ */
434
+ /** Options for a server-side object copy. */
435
+ interface CopyOptions {
436
+ sourceKey: string;
437
+ destinationKey: string;
438
+ sourceBucket?: string;
439
+ destinationBucket?: string;
440
+ publicRead?: boolean;
441
+ cacheControl?: string;
442
+ }
443
+
444
+ /**
445
+ * @fileoverview Per-call options and the result shape for
446
+ * `StorageService.deleteMany()`.
447
+ * @layer server/interfaces
448
+ */
449
+ /** Per-call options for a batch delete. */
450
+ interface DeleteManyOptions {
451
+ bucket?: string;
452
+ }
453
+ /** A single failed key from a batch delete, with a readable provider error. */
454
+ interface FailedDeletion {
455
+ key: string;
456
+ error: string;
457
+ }
458
+ /** Aggregated outcome of a batch delete: succeeded keys and per-key failures. */
459
+ interface DeleteManyResult {
460
+ deleted: string[];
461
+ failed: FailedDeletion[];
462
+ }
463
+
464
+ /**
465
+ * @fileoverview Owns the singleton `S3Client`. Builds it lazily (skipped when
466
+ * credentials are absent so the module still registers), serves it through
467
+ * `getClient()` / `getClientOrNull()`, and releases TCP connections via
468
+ * `destroy()` on application shutdown.
469
+ * @layer server/providers
470
+ */
471
+
472
+ /**
473
+ * When credentials are missing the module registers but never instantiates a
474
+ * client; operations then fail with `STORAGE_NOT_CONFIGURED`. This keeps dev
475
+ * workflows running without storage credentials in the environment.
476
+ */
477
+ declare class S3ClientProvider implements OnModuleInit, OnApplicationShutdown {
478
+ private readonly options;
479
+ private readonly logger;
480
+ private client;
481
+ constructor(options: ResolvedBymaxStorageOptions);
482
+ onModuleInit(): void;
483
+ onApplicationShutdown(): void;
484
+ /**
485
+ * Returns the live client, building it on first use, or `null` when storage is
486
+ * not configured. Used by the public raw-client token so its value does not
487
+ * depend on lifecycle-hook ordering.
488
+ *
489
+ * @returns The singleton client, or `null` when no credentials are configured.
490
+ */
491
+ getClientOrNull(): S3Client | null;
492
+ /**
493
+ * Returns the singleton client. Throws when storage is not configured — call
494
+ * `isConfigured()` first and surface a typed `STORAGE_NOT_CONFIGURED`.
495
+ *
496
+ * @returns The singleton `S3Client`.
497
+ * @throws Error when storage is not configured.
498
+ */
499
+ getClient(): S3Client;
500
+ /**
501
+ * Reports whether the singleton client has been built.
502
+ *
503
+ * @returns `true` once the client exists, `false` otherwise.
504
+ */
505
+ isConfigured(): boolean;
506
+ private resolveClient;
507
+ private createClient;
508
+ }
509
+
510
+ declare class KeyResolverService {
511
+ private readonly keyPrefix;
512
+ constructor(options: ResolvedBymaxStorageOptions);
513
+ /**
514
+ * Normalizes a raw key into the final S3 object key. Rejects empty keys, null
515
+ * bytes, a leading `/`, and any `..` path segment; collapses duplicate slashes;
516
+ * prepends the configured prefix.
517
+ *
518
+ * @param rawKey - The caller-provided key, already URL-decoded by the caller.
519
+ * @returns The prefixed, normalized object key.
520
+ * @throws StorageException with code `STORAGE_KEY_INVALID`.
521
+ */
522
+ normalize(rawKey: string): string;
523
+ /**
524
+ * Strips the global key prefix from a key — useful when returning keys to the
525
+ * consumer so they need not know the prefix exists.
526
+ *
527
+ * @param fullKey - A normalized key that may carry the global prefix.
528
+ * @returns The key without the configured prefix.
529
+ */
530
+ stripPrefix(fullKey: string): string;
531
+ /**
532
+ * Read-only accessor for the resolved prefix.
533
+ *
534
+ * @returns The normalized prefix (empty string when none is configured).
535
+ */
536
+ getPrefix(): string;
537
+ }
538
+
539
+ /**
540
+ * @fileoverview Helpers for the polymorphic upload body (`Buffer`,
541
+ * `NodeJS.ReadableStream`, or `Uint8Array`): type guards, best-effort sizing,
542
+ * a non-consuming first-bytes peek for content validators, and a buffer-to-
543
+ * stream adapter. Hand-rolled with `node:stream` to keep zero runtime deps.
544
+ * @layer server/utils
545
+ */
546
+
547
+ /** Every shape accepted as an upload body. */
548
+ type UploadBody = Buffer | NodeJS.ReadableStream | Uint8Array;
549
+
550
+ /** Minimal subset of upload options consumed by the validation pipeline. */
551
+ interface ValidationInput {
552
+ key: string;
553
+ body: UploadBody;
554
+ contentType: string;
555
+ size?: number;
556
+ metadata?: Record<string, string>;
557
+ }
558
+ declare class ValidationService {
559
+ private readonly options;
560
+ private readonly validators;
561
+ constructor(options: ResolvedBymaxStorageOptions, validators: readonly IUploadValidator[]);
562
+ /**
563
+ * Runs the upload validation pipeline in the canonical order:
564
+ * 1. MIME whitelist (when configured)
565
+ * 2. Size check (best-effort — skipped when `size` is absent)
566
+ * 3. Custom `IUploadValidator` chain (first rejection short-circuits)
567
+ *
568
+ * @param input - The upload options subset used for validation.
569
+ * @returns The validated body (possibly replaced via a tee'd stream).
570
+ * @throws StorageException `STORAGE_MIME_NOT_ALLOWED` on a MIME violation.
571
+ * @throws StorageException `STORAGE_SIZE_EXCEEDED` when `size > maxSizeBytes`.
572
+ * @throws StorageException `STORAGE_VALIDATION_FAILED` on a custom validator rejection.
573
+ */
574
+ validate(input: ValidationInput): Promise<{
575
+ body: UploadBody;
576
+ }>;
577
+ /** Checks the MIME against the configured whitelist (no-op when absent or empty). */
578
+ private checkMime;
579
+ /** Best-effort size check — skipped when size is undefined. */
580
+ private checkSize;
581
+ /**
582
+ * Runs the custom validator chain. When a validator calls `readBytes`, the
583
+ * body is tee'd and the replacement stream is propagated to subsequent
584
+ * validators and the final upload.
585
+ */
586
+ private runCustomValidators;
587
+ }
588
+
589
+ /** Input shape for a scan request. */
590
+ interface ScanInput {
591
+ mode: 'pre-upload' | 'post-upload';
592
+ body?: Buffer | NodeJS.ReadableStream;
593
+ key: string;
594
+ bucket: string;
595
+ contentType: string;
596
+ size?: number;
597
+ }
598
+ declare class FileScannerService {
599
+ private readonly options;
600
+ private readonly scanner;
601
+ private readonly logger;
602
+ constructor(options: ResolvedBymaxStorageOptions, scanner: IFileScanner | null);
603
+ /**
604
+ * Returns `true` when both a scanner implementation and scanner options are
605
+ * configured.
606
+ *
607
+ * @returns `true` when scanning is active.
608
+ */
609
+ isEnabled(): boolean;
610
+ /**
611
+ * Returns the configured scan mode, or `null` when scanning is disabled.
612
+ *
613
+ * @returns `'pre-upload'`, `'post-upload'`, or `null`.
614
+ */
615
+ getMode(): 'pre-upload' | 'post-upload' | null;
616
+ /**
617
+ * Scans the given input. Callers MUST guard with `isEnabled()` — calling this
618
+ * method without a configured scanner is a programming error and throws a
619
+ * plain `Error`.
620
+ *
621
+ * Infected results throw `STORAGE_SCAN_INFECTED`. Inconclusive results throw
622
+ * `STORAGE_SCAN_INCONCLUSIVE` when `rejectOnUnknown` is set; otherwise they
623
+ * are returned with a warning log.
624
+ *
625
+ * @param input - The scan input.
626
+ * @returns The scan result when `status` is `'clean'` or `'unknown'` (non-rejecting).
627
+ * @throws Error when called without a configured scanner.
628
+ * @throws StorageException `STORAGE_SCAN_INFECTED` on an infected result.
629
+ * @throws StorageException `STORAGE_SCAN_INCONCLUSIVE` on an unknown result with `rejectOnUnknown`.
630
+ */
631
+ scan(input: ScanInput): Promise<FileScanResult>;
632
+ }
633
+
634
+ /**
635
+ * In-memory LRU cache for idempotent upload deduplication.
636
+ *
637
+ * A `Map` preserves insertion order, which is the basis of the LRU: a hit
638
+ * deletes-and-reinserts the entry (moving it to the newest position) and
639
+ * eviction removes the oldest insertion (the first key in iteration order).
640
+ *
641
+ * Trade-off: the cache is per-instance. In multi-replica deployments two pods
642
+ * may double-upload the same idempotency key within the TTL window because they
643
+ * do not share state. A cross-instance store is intentionally out of scope for
644
+ * this version.
645
+ */
646
+ declare class IdempotencyCache {
647
+ private readonly maxEntries;
648
+ private readonly ttlMs;
649
+ private readonly now;
650
+ private readonly entries;
651
+ /**
652
+ * @param maxEntries - Hard cap; the oldest entries are evicted beyond it.
653
+ * @param ttlMs - Lifetime of each entry in milliseconds.
654
+ * @param now - Injectable clock for deterministic tests; defaults to `Date.now`.
655
+ */
656
+ constructor(maxEntries: number, ttlMs: number, now?: () => number);
657
+ /**
658
+ * Derives a deterministic cache key by hashing the idempotency key together
659
+ * with the final object key. Hashing avoids storing the raw idempotency key as
660
+ * a `Map` key, where it could be inspected during debugging.
661
+ *
662
+ * The two components are hashed through a structured JSON encoding so their
663
+ * boundary is unambiguous: without it, pairs such as `('a', 'b:c')` and
664
+ * `('a:b', 'c')` would flatten to the same preimage and collide.
665
+ *
666
+ * @param idempotencyKey - The caller-provided idempotency key.
667
+ * @param finalKey - The normalized, prefixed object key.
668
+ * @returns A hex-encoded sha256 digest.
669
+ */
670
+ computeKey(idempotencyKey: string, finalKey: string): string;
671
+ /**
672
+ * Looks up a cached result. Expired entries are dropped and reported as a miss.
673
+ * A live hit is touched (moved to the newest position) to preserve LRU order.
674
+ *
675
+ * @param cacheKey - The key returned by {@link computeKey}.
676
+ * @returns The cached result, or `undefined` on a miss or expiry.
677
+ */
678
+ get(cacheKey: string): UploadResult | undefined;
679
+ /**
680
+ * Stores a result under `cacheKey`, refreshing its position, then evicts the
681
+ * oldest entries while the cache is over capacity.
682
+ *
683
+ * @param cacheKey - The key returned by {@link computeKey}.
684
+ * @param value - The upload result to cache.
685
+ */
686
+ set(cacheKey: string, value: UploadResult): void;
687
+ /**
688
+ * Reports the current number of cached entries.
689
+ *
690
+ * @returns The entry count.
691
+ */
692
+ size(): number;
693
+ /** Removes every cached entry. */
694
+ clear(): void;
695
+ }
696
+
697
+ /** Per-call options that only need to override the target bucket. */
698
+ interface BucketScopedOptions {
699
+ bucket?: string;
700
+ }
701
+ declare class StorageService {
702
+ private readonly options;
703
+ private readonly s3Provider;
704
+ private readonly keyResolver;
705
+ private readonly idempotencyCache;
706
+ private readonly validation;
707
+ private readonly scanner;
708
+ private readonly logger;
709
+ constructor(options: ResolvedBymaxStorageOptions, s3Provider: S3ClientProvider, keyResolver: KeyResolverService, idempotencyCache: IdempotencyCache, validation: ValidationService, scanner: FileScannerService);
710
+ /**
711
+ * Uploads an object, choosing single-shot or multipart automatically. When an
712
+ * `idempotencyKey` is supplied and a matching result is cached within the TTL
713
+ * window, the cached result is returned without re-uploading.
714
+ *
715
+ * @param options - The upload request.
716
+ * @returns The upload result.
717
+ * @throws StorageException for missing configuration, body, or content type.
718
+ */
719
+ upload(options: UploadOptions): Promise<UploadResult>;
720
+ /** Runs a pre-upload scan when configured; throws on infected. */
721
+ private runPreUploadScan;
722
+ /**
723
+ * Coerces a buffer-like scan body (`Buffer` or `Uint8Array`) to a `Buffer` so
724
+ * the scanner always receives its declared contract type; streams pass through
725
+ * unchanged.
726
+ */
727
+ private normalizeScanBody;
728
+ /**
729
+ * Runs a post-upload scan. On infection, deletes the just-uploaded object
730
+ * (logging delete failures as errors) and re-throws the scan exception.
731
+ */
732
+ private runPostUploadScan;
733
+ /**
734
+ * Returns metadata for an object without downloading its body.
735
+ *
736
+ * @param key - The raw object key (normalized internally).
737
+ * @param options - Optional per-call bucket override.
738
+ * @returns The object metadata.
739
+ * @throws StorageException `STORAGE_OBJECT_NOT_FOUND` when the key is absent.
740
+ */
741
+ head(key: string, options?: BucketScopedOptions): Promise<ObjectMetadata>;
742
+ /**
743
+ * Best-effort existence check. Returns `false` for a missing object and, to
744
+ * stay non-throwing, also `false` (with a warning) for any other error.
745
+ *
746
+ * @param key - The raw object key.
747
+ * @param options - Optional per-call bucket override.
748
+ * @returns `true` when the object exists, `false` otherwise.
749
+ */
750
+ exists(key: string, options?: BucketScopedOptions): Promise<boolean>;
751
+ /**
752
+ * Builds the public URL for an object. Not validated against the bucket policy
753
+ * — public delivery depends on the bucket allowing anonymous reads or a CDN.
754
+ *
755
+ * @param key - The raw object key.
756
+ * @param options - Optional per-call bucket override.
757
+ * @returns The public URL.
758
+ */
759
+ getPublicUrl(key: string, options?: BucketScopedOptions): string;
760
+ /**
761
+ * Streams an object. The returned `stream` is a Node `Readable` consumable via
762
+ * `for await` or `.pipe()`. `range` / `ifNoneMatch` / `ifMatch` are forwarded as
763
+ * conditional/partial GET headers.
764
+ *
765
+ * @param options - The download request.
766
+ * @returns The object stream and its metadata.
767
+ * @throws StorageException `STORAGE_OBJECT_NOT_FOUND` when the body is absent.
768
+ */
769
+ download(options: DownloadOptions): Promise<{
770
+ stream: NodeJS.ReadableStream;
771
+ metadata: ObjectMetadata;
772
+ }>;
773
+ /**
774
+ * Materializes an object fully into memory via the sdk-stream-mixin. NOT
775
+ * recommended for files larger than 10 MB — use {@link download} for those.
776
+ *
777
+ * @param options - The download request.
778
+ * @returns The object buffer and its metadata.
779
+ */
780
+ downloadBuffer(options: DownloadOptions): Promise<{
781
+ buffer: Buffer;
782
+ metadata: ObjectMetadata;
783
+ }>;
784
+ /**
785
+ * Deletes an object. Idempotent: a missing object is a no-op (logged as a
786
+ * warning), not an error. Any other failure is propagated.
787
+ *
788
+ * @param key - The raw object key.
789
+ * @param options - Optional per-call bucket override.
790
+ */
791
+ delete(key: string, options?: BucketScopedOptions): Promise<void>;
792
+ /** Throws when the S3 client was never built (missing credentials). */
793
+ private assertConfigured;
794
+ /** Resolves the target bucket from a per-call override or the module default. */
795
+ private resolveBucket;
796
+ /** Builds a public URL, avoiding a duplicated bucket segment in the base. */
797
+ private buildPublicUrl;
798
+ /**
799
+ * Reports whether the base URL already carries the bucket as a real segment —
800
+ * the leading host label (virtual-hosted-style `bucket.host`) or a path segment
801
+ * (path-style `/bucket` or `/bucket/…`) — rather than an incidental substring,
802
+ * so `bucket="test"` is not matched by a `latest` elsewhere in the base.
803
+ */
804
+ private baseCarriesBucket;
805
+ /** Maps an S3 metadata response onto the public `ObjectMetadata` shape. */
806
+ private toObjectMetadata;
807
+ /** Single `PutObject` upload for bodies below the multipart threshold. */
808
+ private uploadSingleShot;
809
+ /**
810
+ * Multipart upload via `@aws-sdk/lib-storage`. `leavePartsOnError: false` makes
811
+ * the SDK abort and clean up parts on failure, so no manual abort is issued.
812
+ */
813
+ private uploadMultipart;
814
+ /** Converts a `Uint8Array` body to a `Buffer` for SDK safety; passes others through. */
815
+ private normalizeSingleShotBody;
816
+ /** Assembles an `UploadResult`, omitting optional fields that are absent. */
817
+ private buildUploadResult;
818
+ /** Emits a progress event, omitting `total`/`part` when they are unknown. */
819
+ private emitProgress;
820
+ /**
821
+ * Lists objects in the bucket as a single page. Applies the global key prefix
822
+ * to the caller's `prefix`, caps `maxKeys` at the S3 hard limit of 1000, threads
823
+ * the continuation token, and strips the global prefix from every returned key.
824
+ *
825
+ * @param options - The listing request.
826
+ * @returns One page of objects plus `commonPrefixes`, truncation, and the next token.
827
+ * @throws StorageException mapped from any AWS failure.
828
+ */
829
+ list(options: ListOptions): Promise<ListResult>;
830
+ /** Maps a `ListObjectsV2` response onto the public `ListResult` shape. */
831
+ private toListResult;
832
+ /** Maps one `Contents` entry onto `ListedObject`, stripping the global prefix. */
833
+ private toListedObject;
834
+ /**
835
+ * Server-side copy of an object (no bytes flow through the app). Supports both
836
+ * same-bucket and cross-bucket copies and preserves the source metadata.
837
+ *
838
+ * @param options - Source/destination keys and buckets plus copy overrides.
839
+ * @returns The new object's ETag.
840
+ * @throws StorageException mapped from any AWS failure.
841
+ */
842
+ copy(options: CopyOptions): Promise<{
843
+ etag: string;
844
+ }>;
845
+ /**
846
+ * Deletes many objects, chunking the input at the S3 hard limit of 1000 keys
847
+ * per request. Reports both successes and per-key failures; a whole-chunk send
848
+ * failure marks every key in that chunk as failed. Returned keys are stripped of
849
+ * the global prefix.
850
+ *
851
+ * @param keys - The raw object keys to delete.
852
+ * @param options - Optional per-call bucket override.
853
+ * @returns The deleted keys and the per-key failures.
854
+ */
855
+ deleteMany(keys: string[], options?: DeleteManyOptions): Promise<DeleteManyResult>;
856
+ /** Deletes one chunk (≤ 1000 keys); a whole-chunk failure fails every key. */
857
+ private deleteChunk;
858
+ }
859
+
860
+ /**
861
+ * @fileoverview Per-call options and results for the signed-URL operations
862
+ * (GET, PUT, and multipart).
863
+ * @layer server/interfaces
864
+ */
865
+ /** Options for a signed GET URL. */
866
+ interface SignedGetUrlOptions {
867
+ key: string;
868
+ bucket?: string;
869
+ /** Silently clamped to `signedUrls.maxTtlSeconds`. */
870
+ ttlSeconds?: number;
871
+ /** e.g. `'attachment; filename="invoice.pdf"'` — overrides on download. */
872
+ responseContentDisposition?: string;
873
+ responseContentType?: string;
874
+ }
875
+ /** Options for a signed PUT URL. */
876
+ interface SignedPutUrlOptions {
877
+ key: string;
878
+ bucket?: string;
879
+ /** Content-Type the client MUST send (it becomes part of the signature). */
880
+ contentType: string;
881
+ ttlSeconds?: number;
882
+ /**
883
+ * Advisory maximum upload size. NOT enforced at presign time — a SigV4 PUT
884
+ * signature can only pin an exact `Content-Length`, never a maximum, so the
885
+ * library does not bind it. Enforce it post-upload via a HEAD/size check plus
886
+ * the scanner path.
887
+ */
888
+ maxSizeBytes?: number;
889
+ publicRead?: boolean;
890
+ metadata?: Record<string, string>;
891
+ }
892
+ /** Options for presigning a multipart upload. */
893
+ interface MultipartUploadUrlsOptions {
894
+ key: string;
895
+ bucket?: string;
896
+ contentType: string;
897
+ /** Number of parts to presign. */
898
+ parts: number;
899
+ ttlSeconds?: number;
900
+ }
901
+ /** Result of presigning a multipart upload. */
902
+ interface MultipartUploadUrlsResult {
903
+ uploadId: string;
904
+ partUrls: {
905
+ partNumber: number;
906
+ url: string;
907
+ }[];
908
+ completeUrl: string;
909
+ }
910
+
911
+ /**
912
+ * @fileoverview Result shape of a signed-URL request. Zero NestJS or AWS SDK
913
+ * dependencies.
914
+ * @layer shared/types
915
+ */
916
+ /** Result of a signed URL request — the caller forwards `url` to a client. */
917
+ interface SignedUrlResult {
918
+ /** The presigned URL. NEVER LOG this — it is a temporary credential. */
919
+ url: string;
920
+ /** Absolute deadline after which the provider stops accepting the URL. */
921
+ expiresAt: Date;
922
+ /** HTTP method the client must use. */
923
+ method: 'GET' | 'PUT';
924
+ /**
925
+ * Headers the client MUST include verbatim — they are part of the signature.
926
+ * Example: `{ 'Content-Type': 'image/png' }`.
927
+ */
928
+ requiredHeaders: Record<string, string>;
929
+ }
930
+
931
+ declare class SignedUrlService {
932
+ private readonly options;
933
+ private readonly s3Provider;
934
+ private readonly keyResolver;
935
+ constructor(options: ResolvedBymaxStorageOptions, s3Provider: S3ClientProvider, keyResolver: KeyResolverService);
936
+ /**
937
+ * Issues a presigned GET URL for downloading an object.
938
+ *
939
+ * SECURITY: The returned URL is a temporary credential. NEVER log it, store it
940
+ * in a database, or cache it across users. Issue a fresh URL per request.
941
+ *
942
+ * @param options - The download URL options.
943
+ * @returns The presigned URL and its expiry metadata.
944
+ * @throws StorageException `STORAGE_NOT_CONFIGURED` when the client is absent.
945
+ * @throws StorageException `STORAGE_SIGNED_URL_TTL_INVALID` for non-positive TTL.
946
+ */
947
+ getDownloadUrl(options: SignedGetUrlOptions): Promise<SignedUrlResult>;
948
+ /**
949
+ * Issues a presigned PUT URL for uploading an object. The client MUST send
950
+ * every header listed in `requiredHeaders` verbatim — each one is part of the
951
+ * URL signature, so an omitted header yields `SignatureDoesNotMatch`. The map
952
+ * always carries `Content-Type` and additionally lists `x-amz-acl` when an ACL
953
+ * is signed and an `x-amz-meta-<key>` entry per metadata pair.
954
+ *
955
+ * SECURITY: The returned URL is a temporary credential — NEVER log it. A signed
956
+ * PUT bypasses the server-side MIME/size validation pipeline. Size limits are
957
+ * NOT enforced at presign time: a SigV4 PUT signature can only pin an exact
958
+ * `Content-Length`, never a maximum, so binding one would reject valid smaller
959
+ * uploads. Enforce size after the fact via a post-upload HEAD/size check plus
960
+ * the post-upload scanner path for defence-in-depth.
961
+ *
962
+ * ACL caveat: `publicRead` emits `ACL: public-read`, which returns HTTP 400
963
+ * `AccessControlListNotSupported` on modern AWS S3 buckets (Object Ownership
964
+ * = "Bucket owner enforced") and is a no-op on Cloudflare R2. Prefer a bucket
965
+ * policy, CDN, or signed GET URL for public delivery.
966
+ *
967
+ * @param options - The upload URL options.
968
+ * @returns The presigned URL, its expiry metadata, and required headers.
969
+ * @throws StorageException `STORAGE_NOT_CONFIGURED` when the client is absent.
970
+ * @throws StorageException `STORAGE_SIGNED_URL_TTL_INVALID` for non-positive TTL.
971
+ */
972
+ getUploadUrl(options: SignedPutUrlOptions): Promise<SignedUrlResult>;
973
+ /**
974
+ * Builds the set of headers a client MUST send for a signed PUT, mirroring the
975
+ * headers folded into the SigV4 signature. Always includes `Content-Type`; adds
976
+ * `x-amz-acl` when an ACL is signed and an `x-amz-meta-<key>` entry (key
977
+ * lowercased to match SigV4 canonicalisation) for every metadata pair.
978
+ */
979
+ private buildPutRequiredHeaders;
980
+ /**
981
+ * Presigns a multipart upload: creates the upload session on S3, then returns
982
+ * N presigned `UploadPart` URLs (1-indexed) and a presigned `CompleteMultipart`
983
+ * URL. The client uploads parts directly to S3 and then calls the complete URL.
984
+ *
985
+ * SECURITY: All returned URLs are temporary credentials — NEVER log them.
986
+ *
987
+ * @param options - The multipart URL options.
988
+ * @returns `uploadId`, `partUrls`, and `completeUrl`.
989
+ * @throws StorageException `STORAGE_NOT_CONFIGURED` when the client is absent.
990
+ * @throws StorageException `STORAGE_SIGNED_URL_TTL_INVALID` for non-positive TTL.
991
+ * @throws StorageException `STORAGE_PROVIDER_ERROR` when no `UploadId` is returned.
992
+ */
993
+ getMultipartUploadUrls(options: MultipartUploadUrlsOptions): Promise<MultipartUploadUrlsResult>;
994
+ /** Presigns all part URLs and the complete URL in parallel. */
995
+ private presignMultipartParts;
996
+ /** Throws when the S3 client was never built (missing credentials). */
997
+ private assertConfigured;
998
+ /** Resolves the target bucket from a per-call override or the module default. */
999
+ private resolveBucket;
1000
+ }
1001
+
1002
+ /**
1003
+ * @fileoverview No-operation upload validator — always passes. Use as the
1004
+ * default when no custom validation logic is needed.
1005
+ * @layer server/providers
1006
+ */
1007
+
1008
+ /**
1009
+ * No-operation upload validator that unconditionally allows every upload.
1010
+ * Useful as a default injectable when the host application does not need
1011
+ * custom validation logic.
1012
+ *
1013
+ * @example
1014
+ * BymaxStorageModule.forRoot({
1015
+ * ...options,
1016
+ * validation: { customValidators: [new NoOpUploadValidator()] },
1017
+ * })
1018
+ */
1019
+ declare class NoOpUploadValidator implements IUploadValidator {
1020
+ /** Identifies this validator in validation-failed error details. */
1021
+ readonly name = "no-op";
1022
+ /**
1023
+ * Always returns `{ ok: true }` — no validation is performed.
1024
+ *
1025
+ * @param _ctx - The upload context (ignored).
1026
+ * @returns A passing validation result.
1027
+ */
1028
+ validate(_ctx: Parameters<IUploadValidator['validate']>[0]): Promise<{
1029
+ ok: true;
1030
+ }>;
1031
+ }
1032
+
1033
+ /**
1034
+ * @fileoverview No-operation file scanner — always reports clean. Use as the
1035
+ * default when no scanner implementation is plugged in.
1036
+ * @layer server/providers
1037
+ */
1038
+
1039
+ /**
1040
+ * No-operation file scanner that unconditionally returns a clean result.
1041
+ * Useful as a default injectable when the host application does not need
1042
+ * virus or content-moderation scanning.
1043
+ *
1044
+ * @example
1045
+ * BymaxStorageModule.forRoot({
1046
+ * ...options,
1047
+ * scanner: { impl: new NoOpFileScanner() },
1048
+ * })
1049
+ */
1050
+ declare class NoOpFileScanner implements IFileScanner {
1051
+ /**
1052
+ * Always returns `{ status: 'clean', engine: 'noop' }`.
1053
+ *
1054
+ * @param _input - The scan input (ignored).
1055
+ * @returns A clean scan result with the `'noop'` engine identifier.
1056
+ */
1057
+ scan(_input: Parameters<IFileScanner['scan']>[0]): Promise<FileScanResult>;
1058
+ }
1059
+
1060
+ /**
1061
+ * @fileoverview Provider Recipes — pure, deterministic factories that produce a
1062
+ * ready-to-spread `BymaxStorageModuleOptions` pre-tuned for one S3-compatible
1063
+ * provider. The decisive detail is the non-AWS checksum opt-out: every provider
1064
+ * except AWS S3 sets `requestChecksumCalculation`/`responseChecksumValidation` to
1065
+ * `'WHEN_REQUIRED'`, because the SDK's default CRC32 integrity headers are
1066
+ * rejected by R2, B2, MinIO, DigitalOcean Spaces, and Wasabi.
1067
+ * @layer server/config
1068
+ */
1069
+
1070
+ /** Shared input for the region-addressed providers (AWS, DO Spaces, Wasabi). */
1071
+ interface BaseInput {
1072
+ region: string;
1073
+ bucket: string;
1074
+ accessKeyId: string;
1075
+ secretAccessKey: string;
1076
+ /** STS / OIDC temporary session token, forwarded only when present. */
1077
+ sessionToken?: string;
1078
+ }
1079
+ /** Cloudflare R2 input — account-addressed, region is always `'auto'`. */
1080
+ interface R2Input extends Omit<BaseInput, 'region' | 'sessionToken'> {
1081
+ /** Cloudflare account id — forms the S3 API endpoint host. */
1082
+ accountId: string;
1083
+ /**
1084
+ * Public delivery domain (r2.dev or a custom domain). REQUIRED for public
1085
+ * reads: the `*.r2.cloudflarestorage.com` host is the S3 API endpoint and does
1086
+ * not serve public object reads, so there is no working default.
1087
+ */
1088
+ customDomain: string;
1089
+ }
1090
+ /** Backblaze B2 input — the endpoint host varies by region cluster. */
1091
+ interface B2Input extends Omit<BaseInput, 'sessionToken'> {
1092
+ /** B2 S3 endpoint host, e.g. `'s3.us-west-002.backblazeb2.com'`. */
1093
+ endpointHost: string;
1094
+ }
1095
+ /** MinIO / dev / self-hosted input — an explicit endpoint, arbitrary region. */
1096
+ interface MinIOInput {
1097
+ endpoint: string;
1098
+ bucket: string;
1099
+ accessKeyId: string;
1100
+ secretAccessKey: string;
1101
+ /** MinIO regions are arbitrary; defaults to `'us-east-1'`. */
1102
+ region?: string;
1103
+ }
1104
+ /**
1105
+ * Pre-tuned configuration factories for each supported S3-compatible provider.
1106
+ * Spread the result into `forRoot`/`forRootAsync` and override any field.
1107
+ *
1108
+ * @example
1109
+ * BymaxStorageModule.forRoot({
1110
+ * ...providerRecipes.cloudflareR2({
1111
+ * accountId,
1112
+ * bucket,
1113
+ * accessKeyId,
1114
+ * secretAccessKey,
1115
+ * customDomain: 'https://cdn.example.com',
1116
+ * }),
1117
+ * keyPrefix: 'tenant-x/',
1118
+ * validation: { mimeWhitelist: ['image/*'] },
1119
+ * })
1120
+ */
1121
+ declare const providerRecipes: {
1122
+ /** AWS S3 — keeps the SDK's default checksum behaviour (`'WHEN_SUPPORTED'`). */
1123
+ readonly awsS3: (input: BaseInput) => BymaxStorageModuleOptions;
1124
+ /** DigitalOcean Spaces — virtual-hosted, public by default, with a CDN host. */
1125
+ readonly digitalOceanSpaces: (input: BaseInput) => BymaxStorageModuleOptions;
1126
+ /** Cloudflare R2 — region `'auto'`; public reads require a custom domain. */
1127
+ readonly cloudflareR2: (input: R2Input) => BymaxStorageModuleOptions;
1128
+ /** Backblaze B2 — S3-compatible API; virtual-hosted matches `publicBaseUrl`. */
1129
+ readonly backblazeB2: (input: B2Input) => BymaxStorageModuleOptions;
1130
+ /** MinIO — dev / CI / self-hosted; path-style addressing. */
1131
+ readonly minio: (input: MinIOInput) => BymaxStorageModuleOptions;
1132
+ /** Wasabi — Hot Cloud Storage; virtual-hosted. */
1133
+ readonly wasabi: (input: BaseInput) => BymaxStorageModuleOptions;
1134
+ };
1135
+
1136
+ /**
1137
+ * @fileoverview Dependency-injection tokens. `Symbol()` tokens are used instead
1138
+ * of strings to avoid collision with tokens from other libraries.
1139
+ * @layer server/di-tokens
1140
+ */
1141
+ declare const BYMAX_STORAGE_OPTIONS: unique symbol;
1142
+ declare const BYMAX_STORAGE_S3_CLIENT: unique symbol;
1143
+ declare const BYMAX_STORAGE_UPLOAD_VALIDATORS: unique symbol;
1144
+ declare const BYMAX_STORAGE_FILE_SCANNER: unique symbol;
1145
+ declare const BYMAX_STORAGE_LOGGER: unique symbol;
1146
+ declare const BYMAX_STORAGE_IDEMPOTENCY_CACHE: unique symbol;
1147
+
1148
+ /**
1149
+ * @fileoverview Provider-recipe contract — a factory that produces
1150
+ * pre-tuned module options for a specific S3-compatible provider.
1151
+ * @layer server/interfaces
1152
+ */
1153
+
1154
+ /**
1155
+ * Provider Recipe — a factory function that produces a
1156
+ * `BymaxStorageModuleOptions` pre-tuned for a specific S3-compatible provider.
1157
+ */
1158
+ type ProviderRecipe<TInput> = (input: TInput) => BymaxStorageModuleOptions;
1159
+
1160
+ /**
1161
+ * @fileoverview Stable string error codes returned in error responses. Host apps
1162
+ * and clients pattern-match on these — they MUST NOT change between minor
1163
+ * versions. `as const` preserves the literal types in the emitted `.d.ts`.
1164
+ * @layer shared/constants
1165
+ */
1166
+ declare const STORAGE_ERROR_CODES: {
1167
+ readonly STORAGE_NOT_CONFIGURED: "STORAGE_NOT_CONFIGURED";
1168
+ readonly STORAGE_KEY_INVALID: "STORAGE_KEY_INVALID";
1169
+ readonly STORAGE_BODY_MISSING: "STORAGE_BODY_MISSING";
1170
+ readonly STORAGE_CONTENT_TYPE_REQUIRED: "STORAGE_CONTENT_TYPE_REQUIRED";
1171
+ readonly STORAGE_MIME_NOT_ALLOWED: "STORAGE_MIME_NOT_ALLOWED";
1172
+ readonly STORAGE_SIZE_EXCEEDED: "STORAGE_SIZE_EXCEEDED";
1173
+ readonly STORAGE_VALIDATION_FAILED: "STORAGE_VALIDATION_FAILED";
1174
+ readonly STORAGE_SCAN_INFECTED: "STORAGE_SCAN_INFECTED";
1175
+ readonly STORAGE_SCAN_INCONCLUSIVE: "STORAGE_SCAN_INCONCLUSIVE";
1176
+ readonly STORAGE_OBJECT_NOT_FOUND: "STORAGE_OBJECT_NOT_FOUND";
1177
+ readonly STORAGE_PROVIDER_ERROR: "STORAGE_PROVIDER_ERROR";
1178
+ readonly STORAGE_SIGNED_URL_TTL_INVALID: "STORAGE_SIGNED_URL_TTL_INVALID";
1179
+ readonly STORAGE_PART_TOO_SMALL: "STORAGE_PART_TOO_SMALL";
1180
+ readonly STORAGE_INVALID_PART_COUNT: "STORAGE_INVALID_PART_COUNT";
1181
+ readonly STORAGE_BUCKET_UNDEFINED: "STORAGE_BUCKET_UNDEFINED";
1182
+ readonly STORAGE_MULTIPART_ABORTED: "STORAGE_MULTIPART_ABORTED";
1183
+ readonly STORAGE_INVALID_CONFIG: "STORAGE_INVALID_CONFIG";
1184
+ readonly STORAGE_TIMEOUT: "STORAGE_TIMEOUT";
1185
+ };
1186
+ /** Union of every stable storage error code. */
1187
+ type StorageErrorCode = (typeof STORAGE_ERROR_CODES)[keyof typeof STORAGE_ERROR_CODES];
1188
+
1189
+ /**
1190
+ * @fileoverview The single exception type thrown by the library. Extends NestJS
1191
+ * `HttpException` so it integrates with host global exception filters.
1192
+ * @layer server/errors
1193
+ */
1194
+
1195
+ /**
1196
+ * Standard exception thrown by the library. The HTTP status defaults to
1197
+ * `STORAGE_ERROR_STATUS[code]`; `code` is exposed so filters can branch without
1198
+ * deserializing the body.
1199
+ *
1200
+ * @example
1201
+ * throw new StorageException('STORAGE_OBJECT_NOT_FOUND', undefined, { key }) // 404 from the status map
1202
+ */
1203
+ declare class StorageException extends HttpException {
1204
+ readonly code: StorageErrorCode;
1205
+ constructor(code: StorageErrorCode,
1206
+ /** Defaults to `STORAGE_ERROR_STATUS[code]`. Pass only to override. */
1207
+ statusCode?: HttpStatus, details?: Record<string, unknown>);
1208
+ }
1209
+
1210
+ export { BYMAX_STORAGE_FILE_SCANNER, BYMAX_STORAGE_IDEMPOTENCY_CACHE, BYMAX_STORAGE_LOGGER, BYMAX_STORAGE_OPTIONS, BYMAX_STORAGE_S3_CLIENT, BYMAX_STORAGE_UPLOAD_VALIDATORS, BymaxStorageModule, type BymaxStorageModuleAsyncOptions, type BymaxStorageModuleOptions, type BymaxStorageModuleOptionsFactory, type CopyOptions, type DeleteManyOptions, type DeleteManyResult, type DownloadOptions, type FailedDeletion, type FileScanResult, type IFileScanner, type IUploadValidator, type ListOptions, type ListResult, type ListedObject, type MultipartUploadUrlsOptions, type MultipartUploadUrlsResult, NoOpFileScanner, NoOpUploadValidator, type ObjectMetadata, type ProviderRecipe, STORAGE_ERROR_CODES, type SignedGetUrlOptions, type SignedPutUrlOptions, type SignedUrlResult, SignedUrlService, type StorageErrorCode, StorageException, StorageService, type UploadOptions, type UploadResult, providerRecipes };