glasswork 0.12.1 → 0.13.0

package/dist/list-query/casl.d.ts

@@ -1,37 +1,36 @@
-import type { ListQueryBuilder } from './builder.js';
+export type CaslAccessibleBy = (ability: any, action?: string) => Record<string, Record<string, unknown>>;
 /**
- * Create a CASL scope function that can be applied to a ListQueryBuilder
- *
- * @param ability - The CASL ability instance (any object that works with @casl/prisma's accessibleBy)
- * @param subject - The Prisma model name (e.g., 'User', 'Organization')
- * @returns A function that applies the CASL conditions to a builder
+ * Register CASL integration dependencies.
+ * This must be called at application startup if you use CASL features.
  *
  * @example
  * ```typescript
- * import { PureAbility } from '@casl/ability';
- * const scope = await createCaslScope(ability, 'User');
- * const params = createListQuery({ filter: UserFilterSchema })
- *   .parse(query)
- *   .apply(scope)
- *   .build();
+ * import { accessibleBy } from '@casl/prisma';
+ * import { registerCasl } from 'glasswork';
+ *
+ * registerCasl({ accessibleBy });
  * ```
  */
-export declare function createCaslScope<TAbility = any>(ability: TAbility, subject: string): Promise<(builder: ListQueryBuilder<any, any>) => ListQueryBuilder<any, any>>;
+export declare function registerCasl(options: {
+    accessibleBy: CaslAccessibleBy;
+}): void;
 /**
  * Create a CASL scope helper that extracts ability from context
  *
+ * @param ability - The CASL ability instance
+ * @param action - The action to check ('read', 'update', etc.)
  * @param subject - The Prisma model name (e.g., 'User', 'Organization')
- * @returns An async function that takes a builder and ability, and applies the CASL conditions
+ * @returns The CASL conditions object (Prisma where clause)
  *
  * @example
  * ```typescript
- * import { PureAbility } from '@casl/ability';
- * const scopeUsers = withCaslScope('User');
- * const params = await createListQuery({ filter: UserFilterSchema })
+ * import { accessibleBy } from '@casl/prisma';
+ *
+ * const params = createListQuery({ filter: UserFilterSchema })
  *   .parse(query)
- *   .applyAsync(scopeUsers, ability)
+ *   .scope(withCaslScope(ability, 'read', 'User'))
  *   .build();
  * ```
  */
-export declare function withCaslScope(subject: string): <TAbility = any>(builder: ListQueryBuilder<any, any>, ability: TAbility) => Promise<ListQueryBuilder<any, any>>;
+export declare function withCaslScope<TAbility = any>(ability: TAbility, action: string, subject: string): Record<string, unknown>;
 //# sourceMappingURL=casl.d.ts.map

package/dist/list-query/casl.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"casl.d.ts","sourceRoot":"","sources":["../../src/list-query/casl.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAkBrD;;;;;;;;;;;;;;;;GAgBG;AAEH,wBAAsB,eAAe,CAAC,QAAQ,GAAG,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,qBAKrE,gBAAgB,CAAC,GAAG,EAAE,GAAG,CAAC,iCAC5C;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,IAE7B,QAAQ,GAAG,GAAG,EAE1B,SAAS,gBAAgB,CAAC,GAAG,EAAE,GAAG,CAAC,EACnC,SAAS,QAAQ,yCAMpB"}
+{"version":3,"file":"casl.d.ts","sourceRoot":"","sources":["../../src/list-query/casl.ts"],"names":[],"mappings":"AACA,MAAM,MAAM,gBAAgB,GAAG,CAE7B,OAAO,EAAE,GAAG,EACZ,MAAM,CAAC,EAAE,MAAM,KACZ,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAU7C;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE;IAAE,YAAY,EAAE,gBAAgB,CAAA;CAAE,QAEvE;AAeD;;;;;;;;;;;;;;;;;GAiBG;AAEH,wBAAgB,aAAa,CAAC,QAAQ,GAAG,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,2BAY/F"}

package/dist/list-query/casl.js

@@ -1,66 +1,60 @@
+const config = {
+    accessibleBy: null,
+};
 /**
- * Dynamically import @casl/prisma to keep it as a truly optional dependency.
- * Only loaded when CASL scope functions are actually used.
- */
-async function getAccessibleBy() {
-    try {
-        const { accessibleBy } = await import('@casl/prisma');
-        return accessibleBy;
-    }
-    catch {
-        throw new Error('@casl/prisma package not found. Install with: npm install @casl/ability @casl/prisma\n' +
-            'Note: @casl/ability is required as a peer dependency of @casl/prisma.');
-    }
-}
-/**
- * Create a CASL scope function that can be applied to a ListQueryBuilder
- *
- * @param ability - The CASL ability instance (any object that works with @casl/prisma's accessibleBy)
- * @param subject - The Prisma model name (e.g., 'User', 'Organization')
- * @returns A function that applies the CASL conditions to a builder
+ * Register CASL integration dependencies.
+ * This must be called at application startup if you use CASL features.
  *
  * @example
  * ```typescript
- * import { PureAbility } from '@casl/ability';
- * const scope = await createCaslScope(ability, 'User');
- * const params = createListQuery({ filter: UserFilterSchema })
- *   .parse(query)
- *   .apply(scope)
- *   .build();
+ * import { accessibleBy } from '@casl/prisma';
+ * import { registerCasl } from 'glasswork';
+ *
+ * registerCasl({ accessibleBy });
  * ```
  */
-// biome-ignore lint/suspicious/noExplicitAny: Ability type is generic to work with any CASL ability instance. The actual type checking happens at runtime when accessibleBy is called.
-export async function createCaslScope(ability, subject) {
-    const accessibleBy = await getAccessibleBy();
-    // biome-ignore lint/suspicious/noExplicitAny: CASL's accessibleBy function has type constraints that don't perfectly align with generic ability types. This cast is necessary for runtime compatibility.
-    const conditions = accessibleBy(ability)[subject];
-    // biome-ignore lint/suspicious/noExplicitAny: Return type must be generic to work with any ListQueryBuilder regardless of its schema types. This maintains maximum flexibility for consumers.
-    return (builder) => builder.scope(conditions);
+export function registerCasl(options) {
+    config.accessibleBy = options.accessibleBy;
+}
+function getAccessibleBy() {
+    if (!config.accessibleBy) {
+        throw new Error('CASL integration not configured. You must call registerCasl({ accessibleBy }) at application startup.\n' +
+            'Example:\n' +
+            "  import { accessibleBy } from '@casl/prisma';\n" +
+            "  import { registerCasl } from 'glasswork';\n" +
+            '  registerCasl({ accessibleBy });');
+    }
+    return config.accessibleBy;
 }
 /**
  * Create a CASL scope helper that extracts ability from context
  *
+ * @param ability - The CASL ability instance
+ * @param action - The action to check ('read', 'update', etc.)
  * @param subject - The Prisma model name (e.g., 'User', 'Organization')
- * @returns An async function that takes a builder and ability, and applies the CASL conditions
+ * @returns The CASL conditions object (Prisma where clause)
  *
  * @example
  * ```typescript
- * import { PureAbility } from '@casl/ability';
- * const scopeUsers = withCaslScope('User');
- * const params = await createListQuery({ filter: UserFilterSchema })
+ * import { accessibleBy } from '@casl/prisma';
+ *
+ * const params = createListQuery({ filter: UserFilterSchema })
  *   .parse(query)
- *   .applyAsync(scopeUsers, ability)
+ *   .scope(withCaslScope(ability, 'read', 'User'))
  *   .build();
  * ```
  */
-export function withCaslScope(subject) {
-    // biome-ignore lint/suspicious/noExplicitAny: Ability type is generic to work with any CASL ability instance. The actual type checking happens at runtime when accessibleBy is called.
-    return async (
-    // biome-ignore lint/suspicious/noExplicitAny: ListQueryBuilder must be generic to work with any schema types. This maintains maximum flexibility for consumers.
-    builder, ability) => {
-        const accessibleBy = await getAccessibleBy();
-        // biome-ignore lint/suspicious/noExplicitAny: CASL's accessibleBy function has type constraints that don't perfectly align with generic ability types. This cast is necessary for runtime compatibility.
-        return builder.scope(accessibleBy(ability)[subject]);
-    };
+// biome-ignore lint/suspicious/noExplicitAny: Ability type is generic
+export function withCaslScope(ability, action, subject) {
+    const accessibleBy = getAccessibleBy();
+    const conditions = accessibleBy(ability, action);
+    if (!(subject in conditions)) {
+        // Return empty object or undefined? Prisma generally assumes conditions exist if asked.
+        // If we assume accessibleBy returns all possible subjects, then missing key might be fine or error.
+        // Let's just return what is there, which is undefined if missing. The types expect Record<string, unknown>.
+        // Casting to allow potentially undefined access if user made a typo.
+        return conditions[subject];
+    }
+    return conditions[subject];
 }
 //# sourceMappingURL=casl.js.map

package/dist/list-query/casl.js.map

@@ -1 +1 @@
-{"version":3,"file":"casl.js","sourceRoot":"","sources":["../../src/list-query/casl.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,KAAK,UAAU,eAAe;IAC5B,IAAI,CAAC;QACH,MAAM,EAAE,YAAY,EAAE,GAAG,MAAM,MAAM,CAAC,cAAc,CAAC,CAAC;QACtD,OAAO,YAAY,CAAC;IACtB,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CACb,wFAAwF;YACtF,uEAAuE,CAC1E,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,uLAAuL;AACvL,MAAM,CAAC,KAAK,UAAU,eAAe,CAAiB,OAAiB,EAAE,OAAe;IACtF,MAAM,YAAY,GAAG,MAAM,eAAe,EAAE,CAAC;IAC7C,yMAAyM;IACzM,MAAM,UAAU,GAAG,YAAY,CAAC,OAAc,CAAC,CAAC,OAAO,CAAC,CAAC;IACzD,8LAA8L;IAC9L,OAAO,CAAC,OAAmC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;AAC5E,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,aAAa,CAAC,OAAe;IAC3C,uLAAuL;IACvL,OAAO,KAAK;IACV,gKAAgK;IAChK,OAAmC,EACnC,OAAiB,EACjB,EAAE;QACF,MAAM,YAAY,GAAG,MAAM,eAAe,EAAE,CAAC;QAC7C,yMAAyM;QACzM,OAAO,OAAO,CAAC,KAAK,CAAC,YAAY,CAAC,OAAc,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IAC9D,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"casl.js","sourceRoot":"","sources":["../../src/list-query/casl.ts"],"names":[],"mappings":"AAWA,MAAM,MAAM,GAAe;IACzB,YAAY,EAAE,IAAI;CACnB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,YAAY,CAAC,OAA2C;IACtE,MAAM,CAAC,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;AAC7C,CAAC;AAED,SAAS,eAAe;IACtB,IAAI,CAAC,MAAM,CAAC,YAAY,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CACb,yGAAyG;YACvG,YAAY;YACZ,kDAAkD;YAClD,+CAA+C;YAC/C,mCAAmC,CACtC,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC,YAAY,CAAC;AAC7B,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,sEAAsE;AACtE,MAAM,UAAU,aAAa,CAAiB,OAAiB,EAAE,MAAc,EAAE,OAAe;IAC9F,MAAM,YAAY,GAAG,eAAe,EAAE,CAAC;IACvC,MAAM,UAAU,GAAG,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAEjD,IAAI,CAAC,CAAC,OAAO,IAAI,UAAU,CAAC,EAAE,CAAC;QAC7B,wFAAwF;QACxF,oGAAoG;QACpG,4GAA4G;QAC5G,qEAAqE;QACrE,OAAO,UAAU,CAAC,OAAO,CAAC,CAAC;IAC7B,CAAC;IACD,OAAO,UAAU,CAAC,OAAO,CAAC,CAAC;AAC7B,CAAC"}

package/dist/uploads/file-upload.d.ts

@@ -0,0 +1,44 @@
+export interface UploadPathConfig {
+    /** Directory path for the file (e.g., 'uploads/avatars/user123/abc123') */
+    readonly dir: string;
+    /** Sanitized file name (e.g., 'photo.jpg') */
+    readonly fileName: string;
+}
+/**
+ * Creates an upload configuration object for presigned URL generation.
+ * Validates IDs and generates a unique random folder to prevent overwrites.
+ *
+ * @param prefix - Upload folder prefix (e.g., 'avatars', 'documents')
+ * @param ids - Array of IDs to include in path (e.g., [userId] or [clientId, orderId])
+ * @param fileName - Sanitized filename (validate with sanitizedFileName schema first)
+ * @returns Configuration object with dir and fileName properties
+ * @throws BadRequestException if prefix is empty or IDs contain invalid characters
+ *
+ * @example
+ * ```typescript
+ * // In route handler:
+ * const config = createUploadConfig('avatars', [user.id], query.name);
+ * const result = await uploadsService.getSignedUploadUrl(config);
+ * // Result path: /uploads/avatars/{userId}/{randomId}/{filename}
+ * ```
+ */
+export declare function createUploadConfig(prefix: string, ids: readonly string[], fileName: string): UploadPathConfig;
+/**
+ * Asserts that a file path belongs to the specified prefix and IDs.
+ * Use this to validate delete operations - ensures users can only delete their own files.
+ *
+ * @param path - The file path to validate (e.g., from query.name)
+ * @param prefix - The expected upload prefix (e.g., 'avatars', 'documents')
+ * @param ids - The expected IDs in the path
+ * @param errorMessage - Custom error message (default: 'Invalid file path')
+ * @throws ForbiddenException if path doesn't match expected structure
+ *
+ * @example
+ * ```typescript
+ * // In delete handler:
+ * assertUploadPathOwnership(query.path, 'avatars', [user.id]);
+ * await uploadsService.deleteFile(query.path);
+ * ```
+ */
+export declare function assertUploadPathOwnership(path: string, prefix: string, ids: readonly string[], errorMessage?: string): void;
+//# sourceMappingURL=file-upload.d.ts.map

package/dist/uploads/file-upload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-upload.d.ts","sourceRoot":"","sources":["../../src/uploads/file-upload.ts"],"names":[],"mappings":"AAeA,MAAM,WAAW,gBAAgB;IAC/B,2EAA2E;IAC3E,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,8CAA8C;IAC9C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,SAAS,MAAM,EAAE,EACtB,QAAQ,EAAE,MAAM,GACf,gBAAgB,CAoBlB;AAsED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,SAAS,MAAM,EAAE,EACtB,YAAY,SAAsB,GACjC,IAAI,CAYN"}

package/dist/uploads/file-upload.js

@@ -0,0 +1,145 @@
+import { customAlphabet } from 'nanoid';
+import { BadRequestException, ForbiddenException } from '../http/errors.js';
+// ============================================================================
+// Constants
+// ============================================================================
+const UPLOAD_RANDOM_ID_LENGTH = 16;
+const MAX_PATH_LENGTH = 1024;
+const NANOID_ALPHABET = '1234567890abcdef';
+// ============================================================================
+// Upload Configuration
+// ============================================================================
+/**
+ * Creates an upload configuration object for presigned URL generation.
+ * Validates IDs and generates a unique random folder to prevent overwrites.
+ *
+ * @param prefix - Upload folder prefix (e.g., 'avatars', 'documents')
+ * @param ids - Array of IDs to include in path (e.g., [userId] or [clientId, orderId])
+ * @param fileName - Sanitized filename (validate with sanitizedFileName schema first)
+ * @returns Configuration object with dir and fileName properties
+ * @throws BadRequestException if prefix is empty or IDs contain invalid characters
+ *
+ * @example
+ * ```typescript
+ * // In route handler:
+ * const config = createUploadConfig('avatars', [user.id], query.name);
+ * const result = await uploadsService.getSignedUploadUrl(config);
+ * // Result path: /uploads/avatars/{userId}/{randomId}/{filename}
+ * ```
+ */
+export function createUploadConfig(prefix, ids, fileName) {
+    if (!prefix || prefix.trim() === '') {
+        throw new BadRequestException('Prefix cannot be empty');
+    }
+    for (const id of ids) {
+        if (!id || typeof id !== 'string') {
+            throw new BadRequestException(`Invalid ID: ${id}`);
+        }
+        if (id.includes('/') || id.includes('\\') || id.includes('..')) {
+            throw new BadRequestException(`Invalid character in ID: ${id}`);
+        }
+    }
+    /*
+     * Handle empty IDs array gracefully to avoid double slashes.
+     * If ids are present, join them with '/', otherwise use empty string.
+     */
+    const idPath = ids.length > 0 ? `${ids.join('/')}/` : '';
+    const randomId = customAlphabet(NANOID_ALPHABET, UPLOAD_RANDOM_ID_LENGTH)();
+    const dir = `uploads/${prefix}/${idPath}${randomId}`;
+    return { dir, fileName };
+}
+// ============================================================================
+// Path Ownership Validation
+// ============================================================================
+/**
+ * Validate IDs don't contain path traversal characters.
+ */
+function validateIdsForPath(ids, errorMessage) {
+    for (const id of ids) {
+        if (!id || typeof id !== 'string') {
+            throw new ForbiddenException(errorMessage);
+        }
+        if (id.includes('/') || id.includes('\\') || id.includes('..')) {
+            throw new ForbiddenException(errorMessage);
+        }
+    }
+}
+/**
+ * Check if path contains control characters (security measure).
+ */
+function hasControlCharacters(path) {
+    for (let i = 0; i < path.length; i++) {
+        const code = path.charCodeAt(i);
+        if ((code >= 0x00 && code <= 0x1f) || code === 0x7f) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Decode and normalize path, rejecting traversal attempts.
+ */
+function decodeAndNormalizePath(path, errorMessage) {
+    let decodedPath;
+    try {
+        decodedPath = decodeURIComponent(path);
+    }
+    catch {
+        throw new ForbiddenException(errorMessage);
+    }
+    if (decodedPath.includes('..') || decodedPath.includes('./') || decodedPath.includes('.\\')) {
+        throw new ForbiddenException(errorMessage);
+    }
+    if (decodedPath.includes('\\')) {
+        throw new ForbiddenException(errorMessage);
+    }
+    const normalizedPath = decodedPath.replace(/\/+/g, '/');
+    if (normalizedPath !== decodedPath) {
+        throw new ForbiddenException(errorMessage);
+    }
+    return normalizedPath;
+}
+/**
+ * Validate relative path has a valid filename at the end.
+ */
+function validateRelativePath(relativePath, errorMessage) {
+    if (relativePath === '' || relativePath.endsWith('/')) {
+        throw new ForbiddenException(errorMessage);
+    }
+    const lastSlashIndex = relativePath.lastIndexOf('/');
+    const filename = lastSlashIndex >= 0 ? relativePath.slice(lastSlashIndex + 1) : relativePath;
+    if (!filename || filename.trim() === '') {
+        throw new ForbiddenException(errorMessage);
+    }
+}
+/**
+ * Asserts that a file path belongs to the specified prefix and IDs.
+ * Use this to validate delete operations - ensures users can only delete their own files.
+ *
+ * @param path - The file path to validate (e.g., from query.name)
+ * @param prefix - The expected upload prefix (e.g., 'avatars', 'documents')
+ * @param ids - The expected IDs in the path
+ * @param errorMessage - Custom error message (default: 'Invalid file path')
+ * @throws ForbiddenException if path doesn't match expected structure
+ *
+ * @example
+ * ```typescript
+ * // In delete handler:
+ * assertUploadPathOwnership(query.path, 'avatars', [user.id]);
+ * await uploadsService.deleteFile(query.path);
+ * ```
+ */
+export function assertUploadPathOwnership(path, prefix, ids, errorMessage = 'Invalid file path') {
+    validateIdsForPath(ids, errorMessage);
+    if (path.length > MAX_PATH_LENGTH || hasControlCharacters(path)) {
+        throw new ForbiddenException(errorMessage);
+    }
+    const normalizedPath = decodeAndNormalizePath(path, errorMessage);
+    const idPath = ids.length > 0 ? `${ids.join('/')}/` : '';
+    const expectedPrefix = `/uploads/${prefix}/${idPath}`;
+    if (!normalizedPath.startsWith(expectedPrefix)) {
+        throw new ForbiddenException(errorMessage);
+    }
+    validateRelativePath(normalizedPath.slice(expectedPrefix.length), errorMessage);
+}
+//# sourceMappingURL=file-upload.js.map

package/dist/uploads/file-upload.js.map

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

package/dist/uploads/index.d.ts

@@ -0,0 +1,6 @@
+export type { UploadPathConfig } from './file-upload.js';
+export { assertUploadPathOwnership, createUploadConfig } from './file-upload.js';
+export type { SignedDownloadUrlResponse, SignedUrlResponse, StreamFileResult, UploadFileConfig, UploadsServiceConfig, } from './uploads.service.js';
+export { UploadsService } from './uploads.service.js';
+export { fileNameWithExtension, sanitizedFileName } from './validators.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/uploads/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/uploads/index.ts"],"names":[],"mappings":"AAEA,YAAY,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEzD,OAAO,EAAE,yBAAyB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACjF,YAAY,EACV,yBAAyB,EACzB,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAGtD,OAAO,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/uploads/index.js

@@ -0,0 +1,7 @@
+// Service
+// Utilities
+export { assertUploadPathOwnership, createUploadConfig } from './file-upload.js';
+export { UploadsService } from './uploads.service.js';
+// Validators
+export { fileNameWithExtension, sanitizedFileName } from './validators.js';
+//# sourceMappingURL=index.js.map

package/dist/uploads/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/uploads/index.ts"],"names":[],"mappings":"AAAA,UAAU;AAGV,YAAY;AACZ,OAAO,EAAE,yBAAyB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAQjF,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD,aAAa;AACb,OAAO,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/uploads/uploads.service.d.ts

@@ -0,0 +1,98 @@
+import type { Readable } from 'node:stream';
+export interface UploadFileConfig {
+    /** Directory path for the file (e.g., 'uploads/avatars/user123/abc123') */
+    readonly dir: string;
+    /** Sanitized file name (e.g., 'photo.jpg') */
+    readonly fileName: string;
+}
+export interface SignedUrlResponse {
+    /** Presigned URL for uploading the file */
+    readonly uploadUrl: string;
+    /** Relative path where the file will be stored (e.g., '/uploads/avatars/...') */
+    readonly path: string;
+    /** Expiration timestamp of the presigned URL */
+    readonly expiresAt: Date;
+}
+export interface SignedDownloadUrlResponse {
+    /** Presigned URL for downloading the file */
+    readonly downloadUrl: string;
+    /** Expiration timestamp of the presigned URL */
+    readonly expiresAt: Date;
+}
+export interface StreamFileResult {
+    /** Readable stream of the file contents */
+    readonly body: Readable;
+    /** MIME type of the file */
+    readonly contentType: string | undefined;
+    /** Size of the file in bytes */
+    readonly contentLength: number | undefined;
+}
+export interface UploadsServiceConfig {
+    /** AWS region (e.g., 'eu-west-1') */
+    readonly region: string;
+    /** S3 bucket name */
+    readonly bucketName: string;
+    /** Presigned URL expiration in seconds (default: 3600) */
+    readonly urlExpiration?: number;
+}
+/**
+ * Service for S3 file operations including presigned URL generation and streaming.
+ * Framework-agnostic - can be used anywhere TypeScript runs.
+ *
+ * @example
+ * ```typescript
+ * const uploadsService = new UploadsService({
+ *   region: 'eu-west-1',
+ *   bucketName: 'my-files-bucket',
+ *   urlExpiration: 3600,
+ * });
+ *
+ * // Generate presigned upload URL
+ * const { uploadUrl, path } = await uploadsService.getSignedUploadUrl({
+ *   dir: 'uploads/avatars/user123',
+ *   fileName: 'photo.jpg',
+ * });
+ *
+ * // Stream file for private access
+ * const { body, contentType } = await uploadsService.streamFile('/uploads/docs/file.pdf');
+ *
+ * // Generate presigned download URL for private files
+ * const { downloadUrl } = await uploadsService.getSignedDownloadUrl('/uploads/docs/private.pdf');
+ * ```
+ */
+export declare class UploadsService {
+    private readonly client;
+    private readonly bucketName;
+    private readonly urlExpiration;
+    constructor(config: UploadsServiceConfig);
+    /**
+     * Generate a presigned URL for uploading a file to S3.
+     * The URL allows direct upload from the client without going through Lambda.
+     */
+    getSignedUploadUrl(fileConfig: UploadFileConfig): Promise<SignedUrlResponse>;
+    /**
+     * Stream a file from S3 for private file access.
+     * Returns a readable stream that can be piped to the HTTP response.
+     *
+     * **Note**: Lambda has a 6MB response payload limit for synchronous invocations.
+     * For larger files, consider using presigned GET URLs with short expiration.
+     */
+    streamFile(filePath: string): Promise<StreamFileResult>;
+    /**
+     * Generate a presigned URL for downloading a file from S3.
+     * Use this instead of streaming for files that may exceed Lambda's 6MB response limit.
+     *
+     * @param filePath - Relative path to the file (e.g., '/uploads/docs/file.pdf')
+     * @param expiresIn - Optional expiration in seconds (default: service urlExpiration)
+     */
+    getSignedDownloadUrl(filePath: string, expiresIn?: number): Promise<SignedDownloadUrlResponse>;
+    /**
+     * Delete a file from S3 by path.
+     */
+    deleteFile(filePath: string): Promise<void>;
+    /**
+     * Normalize file path to S3 key format (strip leading slashes).
+     */
+    private normalizeKey;
+}
+//# sourceMappingURL=uploads.service.d.ts.map

package/dist/uploads/uploads.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uploads.service.d.ts","sourceRoot":"","sources":["../../src/uploads/uploads.service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAe5C,MAAM,WAAW,gBAAgB;IAC/B,2EAA2E;IAC3E,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,8CAA8C;IAC9C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,iBAAiB;IAChC,2CAA2C;IAC3C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,iFAAiF;IACjF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gDAAgD;IAChD,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,yBAAyB;IACxC,6CAA6C;IAC7C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,gDAAgD;IAChD,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAC/B,2CAA2C;IAC3C,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,4BAA4B;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,gCAAgC;IAChC,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5C;AAED,MAAM,WAAW,oBAAoB;IACnC,qCAAqC;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,qBAAqB;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,0DAA0D;IAC1D,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAaD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAW;IAClC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;gBAE3B,MAAM,EAAE,oBAAoB;IAMxC;;;OAGG;IACG,kBAAkB,CAAC,UAAU,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAgBlF;;;;;;OAMG;IACG,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAsB7D;;;;;;OAMG;IACG,oBAAoB,CACxB,QAAQ,EAAE,MAAM,EAChB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,yBAAyB,CAAC;IAgBrC;;OAEG;IACG,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IASjD;;OAEG;IACH,OAAO,CAAC,YAAY;CAGrB"}

package/dist/uploads/uploads.service.js

@@ -0,0 +1,134 @@
+import { DeleteObjectCommand, GetObjectCommand, PutObjectCommand, S3Client, S3ServiceException, } from '@aws-sdk/client-s3';
+import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
+import { NotFoundException } from '../http/errors.js';
+// ============================================================================
+// Constants
+// ============================================================================
+const DEFAULT_URL_EXPIRATION = 3600; // 1 hour
+const MILLISECONDS_PER_SECOND = 1000;
+// ============================================================================
+// Service
+// ============================================================================
+/**
+ * Service for S3 file operations including presigned URL generation and streaming.
+ * Framework-agnostic - can be used anywhere TypeScript runs.
+ *
+ * @example
+ * ```typescript
+ * const uploadsService = new UploadsService({
+ *   region: 'eu-west-1',
+ *   bucketName: 'my-files-bucket',
+ *   urlExpiration: 3600,
+ * });
+ *
+ * // Generate presigned upload URL
+ * const { uploadUrl, path } = await uploadsService.getSignedUploadUrl({
+ *   dir: 'uploads/avatars/user123',
+ *   fileName: 'photo.jpg',
+ * });
+ *
+ * // Stream file for private access
+ * const { body, contentType } = await uploadsService.streamFile('/uploads/docs/file.pdf');
+ *
+ * // Generate presigned download URL for private files
+ * const { downloadUrl } = await uploadsService.getSignedDownloadUrl('/uploads/docs/private.pdf');
+ * ```
+ */
+export class UploadsService {
+    client;
+    bucketName;
+    urlExpiration;
+    constructor(config) {
+        this.client = new S3Client({ region: config.region });
+        this.bucketName = config.bucketName;
+        this.urlExpiration = config.urlExpiration ?? DEFAULT_URL_EXPIRATION;
+    }
+    /**
+     * Generate a presigned URL for uploading a file to S3.
+     * The URL allows direct upload from the client without going through Lambda.
+     */
+    async getSignedUploadUrl(fileConfig) {
+        const filePath = `${fileConfig.dir}/${fileConfig.fileName}`;
+        const command = new PutObjectCommand({
+            Bucket: this.bucketName,
+            Key: filePath,
+        });
+        const url = await getSignedUrl(this.client, command, {
+            expiresIn: this.urlExpiration,
+        });
+        return {
+            uploadUrl: url,
+            path: `/${filePath}`,
+            expiresAt: new Date(Date.now() + this.urlExpiration * MILLISECONDS_PER_SECOND),
+        };
+    }
+    /**
+     * Stream a file from S3 for private file access.
+     * Returns a readable stream that can be piped to the HTTP response.
+     *
+     * **Note**: Lambda has a 6MB response payload limit for synchronous invocations.
+     * For larger files, consider using presigned GET URLs with short expiration.
+     */
+    async streamFile(filePath) {
+        try {
+            const key = this.normalizeKey(filePath);
+            const command = new GetObjectCommand({
+                Bucket: this.bucketName,
+                Key: key,
+            });
+            const response = await this.client.send(command);
+            const body = response.Body;
+            return {
+                body,
+                contentType: response.ContentType,
+                contentLength: response.ContentLength,
+            };
+        }
+        catch (error) {
+            if (error instanceof S3ServiceException && error.name === 'NoSuchKey') {
+                throw new NotFoundException('File not found');
+            }
+            throw error;
+        }
+    }
+    /**
+     * Generate a presigned URL for downloading a file from S3.
+     * Use this instead of streaming for files that may exceed Lambda's 6MB response limit.
+     *
+     * @param filePath - Relative path to the file (e.g., '/uploads/docs/file.pdf')
+     * @param expiresIn - Optional expiration in seconds (default: service urlExpiration)
+     */
+    async getSignedDownloadUrl(filePath, expiresIn) {
+        const key = this.normalizeKey(filePath);
+        const expiration = expiresIn ?? this.urlExpiration;
+        const command = new GetObjectCommand({
+            Bucket: this.bucketName,
+            Key: key,
+        });
+        const url = await getSignedUrl(this.client, command, {
+            expiresIn: expiration,
+        });
+        return {
+            downloadUrl: url,
+            expiresAt: new Date(Date.now() + expiration * MILLISECONDS_PER_SECOND),
+        };
+    }
+    /**
+     * Delete a file from S3 by path.
+     */
+    async deleteFile(filePath) {
+        const key = this.normalizeKey(filePath);
+        const command = new DeleteObjectCommand({
+            Bucket: this.bucketName,
+            Key: key,
+        });
+        await this.client.send(command);
+    }
+    /**
+     * Normalize file path to S3 key format (strip leading slashes).
+     */
+    normalizeKey(filePath) {
+        return filePath.replace(/^\/+/, '').replace(/\/+/g, '/');
+    }
+}
+//# sourceMappingURL=uploads.service.js.map