@breadstone/archipel-mcp 0.0.39 → 0.0.41

package/data/guides/blob-storage.md

@@ -18,16 +18,17 @@ yarn add @breadstone/archipel-platform-blob-storage
 
 ---
 
-## Choose a Provider
+## Choose a Strategy
 
-`platform-blob-storage` abstracts file operations behind a unified `BlobService`. You select the provider at module registration time. Supported providers:
+`platform-blob-storage` abstracts file operations behind a unified `BlobService`. You select the storage strategy at module registration time. Built-in strategies:
 
-| Provider   | Kind constant              | When to use                                 |
-| ---------- | -------------------------- | ------------------------------------------- |
-| **Vercel** | `BlobProviderKinds.Vercel` | Vercel-hosted apps with Vercel Blob storage |
-| **Azure**  | `BlobProviderKinds.Azure`  | Azure Blob Storage accounts                 |
-| **AWS S3** | `BlobProviderKinds.AwsS3`  | Amazon S3 or S3-compatible providers        |
-| **Custom** | `BlobProviderKinds.Custom` | Your own storage backend                    |
+| Strategy                      | Import subpath        | When to use                                 |
+| ----------------------------- | --------------------- | ------------------------------------------- |
+| **Vercel**                    | `strategies/vercel`   | Vercel-hosted apps with Vercel Blob storage |
+| **Azure**                     | `strategies/azure`    | Azure Blob Storage accounts                 |
+| **AWS S3**                    | `strategies/aws-s3`   | Amazon S3 or S3-compatible providers        |
+| **Local**                     | `strategies/local`    | Local filesystem (development / testing)    |
+| **Custom**                    | —                     | Extend `BlobStorageStrategyBase`            |
 
 ---
 
@@ -35,14 +36,14 @@ yarn add @breadstone/archipel-platform-blob-storage
 
 ```typescript
 import { Module } from '@nestjs/common';
-import { BlobModule, BlobProviderKinds } from '@breadstone/archipel-platform-blob-storage';
+import { BlobModule } from '@breadstone/archipel-platform-blob-storage';
+import { AwsS3BlobStorageStrategy, AWS_S3_CONFIG_ENTRIES } from '@breadstone/archipel-platform-blob-storage/strategies/aws-s3';
 
 @Module({
   imports: [
-    BlobModule.forRoot({
-      provider: {
-        kind: BlobProviderKinds.AwsS3,
-      },
+    BlobModule.register({
+      storageStrategy: AwsS3BlobStorageStrategy,
+      configEntries: AWS_S3_CONFIG_ENTRIES,
     }),
   ],
 })
@@ -234,8 +235,11 @@ export class PrismaBlobVariantAdapter extends BlobVariantPersistencePort {
 ### Register with Persistence
 
 ```typescript
-BlobModule.forRoot({
-  provider: { kind: BlobProviderKinds.AwsS3 },
+import { AwsS3BlobStorageStrategy, AWS_S3_CONFIG_ENTRIES } from '@breadstone/archipel-platform-blob-storage/strategies/aws-s3';
+
+BlobModule.register({
+  storageStrategy: AwsS3BlobStorageStrategy,
+  configEntries: AWS_S3_CONFIG_ENTRIES,
   objectPersistence: PrismaBlobObjectAdapter,
   variantPersistence: PrismaBlobVariantAdapter,
 }),
@@ -245,7 +249,7 @@ BlobModule.forRoot({
 
 ## Security
 
-All built-in blob providers (AWS S3, Azure, Vercel) apply automatic key normalization via the internal `normalizeKey` method before any storage operation. This includes:
+All built-in blob storage strategies (AWS S3, Azure, Vercel, Local) apply automatic key normalization via the internal `normalizeKey` method before any storage operation. This includes:
 
 - **Path traversal prevention** — segments such as `..` and `.` are removed so callers cannot escape the intended directory.
 - **Backslash normalization** — backslashes (`\`) are converted to forward slashes before processing.

package/data/packages/platform-blob-storage/api/Class.AwsS3BlobStorageStrategy.md

@@ -0,0 +1,197 @@
+---
+title: 'Class: AwsS3BlobStorageStrategy'
+generated: true
+editUrl: false
+---
+# Class: AwsS3BlobStorageStrategy
+
+Defined in: [strategies/aws-s3/AwsS3BlobStorageStrategy.ts:26](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-blob-storage/src/strategies/aws-s3/AwsS3BlobStorageStrategy.ts#L26)
+
+Provides a blob storage strategy backed by Amazon S3.
+
+## Extends
+
+- [`BlobStorageStrategyBase`](Class.BlobStorageStrategyBase)
+
+## Constructors
+
+### Constructor
+
+```ts
+new AwsS3BlobStorageStrategy(configService): AwsS3BlobStorageStrategy;
+```
+
+Defined in: [strategies/aws-s3/AwsS3BlobStorageStrategy.ts:47](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-blob-storage/src/strategies/aws-s3/AwsS3BlobStorageStrategy.ts#L47)
+
+Initializes a new instance of the AwsS3BlobStorageStrategy class.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `configService` | `ConfigService` | The configuration service providing environment values. |
+
+#### Returns
+
+`AwsS3BlobStorageStrategy`
+
+#### Overrides
+
+[`BlobStorageStrategyBase`](Class.BlobStorageStrategyBase).[`constructor`](Class.BlobStorageStrategyBase#constructor)
+
+## Properties
+
+### providerId
+
+```ts
+readonly providerId: string = 'aws-s3';
+```
+
+Defined in: [strategies/aws-s3/AwsS3BlobStorageStrategy.ts:77](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-blob-storage/src/strategies/aws-s3/AwsS3BlobStorageStrategy.ts#L77)
+
+Gets the unique identifier for this storage provider.
+
+#### Overrides
+
+[`BlobStorageStrategyBase`](Class.BlobStorageStrategyBase).[`providerId`](Class.BlobStorageStrategyBase#providerid)
+
+## Accessors
+
+### defaultBucket
+
+#### Get Signature
+
+```ts
+get defaultBucket(): string;
+```
+
+Defined in: [strategies/aws-s3/AwsS3BlobStorageStrategy.ts:80](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-blob-storage/src/strategies/aws-s3/AwsS3BlobStorageStrategy.ts#L80)
+
+Gets the default bucket (container/directory) configured for the provider.
+
+##### Returns
+
+`string`
+
+Gets the default bucket (container/directory) configured for the provider.
+
+#### Overrides
+
+[`BlobStorageStrategyBase`](Class.BlobStorageStrategyBase).[`defaultBucket`](Class.BlobStorageStrategyBase#defaultbucket)
+
+## Methods
+
+### createSignedUrl()
+
+```ts
+createSignedUrl(request): Promise<string>;
+```
+
+Defined in: [strategies/aws-s3/AwsS3BlobStorageStrategy.ts:177](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-blob-storage/src/strategies/aws-s3/AwsS3BlobStorageStrategy.ts#L177)
+
+Creates a signed URL for the specified blob object.
+Not all providers support this operation.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `request` | [`IBlobSignedUrlRequest`](Interface.IBlobSignedUrlRequest) | The request describing the object to link. |
+
+#### Returns
+
+`Promise`\<`string`\>
+
+The generated signed URL.
+
+#### Overrides
+
+[`BlobStorageStrategyBase`](Class.BlobStorageStrategyBase).[`createSignedUrl`](Class.BlobStorageStrategyBase#createsignedurl)
+
+***
+
+### deleteObject()
+
+```ts
+deleteObject(request): Promise<void>;
+```
+
+Defined in: [strategies/aws-s3/AwsS3BlobStorageStrategy.ts:159](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-blob-storage/src/strategies/aws-s3/AwsS3BlobStorageStrategy.ts#L159)
+
+Deletes a blob object from the storage backend.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `request` | [`IBlobDeleteRequest`](Interface.IBlobDeleteRequest) | The delete request describing the object to remove. |
+
+#### Returns
+
+`Promise`\<`void`\>
+
+#### Overrides
+
+[`BlobStorageStrategyBase`](Class.BlobStorageStrategyBase).[`deleteObject`](Class.BlobStorageStrategyBase#deleteobject)
+
+***
+
+### downloadObject()
+
+```ts
+downloadObject<TData>(request): Promise<IBlobDownloadResult<TData>>;
+```
+
+Defined in: [strategies/aws-s3/AwsS3BlobStorageStrategy.ts:134](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-blob-storage/src/strategies/aws-s3/AwsS3BlobStorageStrategy.ts#L134)
+
+Downloads a blob object from the storage backend.
+
+#### Type Parameters
+
+| Type Parameter |
+| ------ |
+| `TData` |
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `request` | [`IBlobDownloadRequest`](Interface.IBlobDownloadRequest) | The download request describing the object to download. |
+
+#### Returns
+
+`Promise`\<[`IBlobDownloadResult`](Interface.IBlobDownloadResult)\<`TData`\>\>
+
+The download result including payload and metadata.
+
+#### Overrides
+
+[`BlobStorageStrategyBase`](Class.BlobStorageStrategyBase).[`downloadObject`](Class.BlobStorageStrategyBase#downloadobject)
+
+***
+
+### uploadObject()
+
+```ts
+uploadObject(request): Promise<IBlobUploadResult>;
+```
+
+Defined in: [strategies/aws-s3/AwsS3BlobStorageStrategy.ts:89](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-blob-storage/src/strategies/aws-s3/AwsS3BlobStorageStrategy.ts#L89)
+
+Uploads a blob object to the storage backend.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `request` | [`IBlobUploadRequest`](Interface.IBlobUploadRequest) | The upload request describing the object to upload. |
+
+#### Returns
+
+`Promise`\<[`IBlobUploadResult`](Interface.IBlobUploadResult)\>
+
+The resulting upload metadata.
+
+#### Overrides
+
+[`BlobStorageStrategyBase`](Class.BlobStorageStrategyBase).[`uploadObject`](Class.BlobStorageStrategyBase#uploadobject)

package/data/packages/platform-blob-storage/api/Class.AzureBlobStorageStrategy.md

@@ -0,0 +1,197 @@
+---
+title: 'Class: AzureBlobStorageStrategy'
+generated: true
+editUrl: false
+---
+# Class: AzureBlobStorageStrategy
+
+Defined in: [strategies/azure/AzureBlobStorageStrategy.ts:25](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-blob-storage/src/strategies/azure/AzureBlobStorageStrategy.ts#L25)
+
+Provides a blob storage strategy backed by Microsoft Azure Blob Storage.
+
+## Extends
+
+- [`BlobStorageStrategyBase`](Class.BlobStorageStrategyBase)
+
+## Constructors
+
+### Constructor
+
+```ts
+new AzureBlobStorageStrategy(configService): AzureBlobStorageStrategy;
+```
+
+Defined in: [strategies/azure/AzureBlobStorageStrategy.ts:44](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-blob-storage/src/strategies/azure/AzureBlobStorageStrategy.ts#L44)
+
+Initializes a new instance of the AzureBlobStorageStrategy class.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `configService` | `ConfigService` | The configuration service providing environment values. |
+
+#### Returns
+
+`AzureBlobStorageStrategy`
+
+#### Overrides
+
+[`BlobStorageStrategyBase`](Class.BlobStorageStrategyBase).[`constructor`](Class.BlobStorageStrategyBase#constructor)
+
+## Properties
+
+### providerId
+
+```ts
+readonly providerId: string = 'azure';
+```
+
+Defined in: [strategies/azure/AzureBlobStorageStrategy.ts:67](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-blob-storage/src/strategies/azure/AzureBlobStorageStrategy.ts#L67)
+
+Gets the unique identifier for this storage provider.
+
+#### Overrides
+
+[`BlobStorageStrategyBase`](Class.BlobStorageStrategyBase).[`providerId`](Class.BlobStorageStrategyBase#providerid)
+
+## Accessors
+
+### defaultBucket
+
+#### Get Signature
+
+```ts
+get defaultBucket(): string;
+```
+
+Defined in: [strategies/azure/AzureBlobStorageStrategy.ts:70](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-blob-storage/src/strategies/azure/AzureBlobStorageStrategy.ts#L70)
+
+Gets the default bucket (container/directory) configured for the provider.
+
+##### Returns
+
+`string`
+
+Gets the default bucket (container/directory) configured for the provider.
+
+#### Overrides
+
+[`BlobStorageStrategyBase`](Class.BlobStorageStrategyBase).[`defaultBucket`](Class.BlobStorageStrategyBase#defaultbucket)
+
+## Methods
+
+### createSignedUrl()
+
+```ts
+createSignedUrl(request): Promise<string>;
+```
+
+Defined in: [strategies/azure/AzureBlobStorageStrategy.ts:154](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-blob-storage/src/strategies/azure/AzureBlobStorageStrategy.ts#L154)
+
+Creates a signed URL for the specified blob object.
+Not all providers support this operation.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `request` | [`IBlobSignedUrlRequest`](Interface.IBlobSignedUrlRequest) | The request describing the object to link. |
+
+#### Returns
+
+`Promise`\<`string`\>
+
+The generated signed URL.
+
+#### Overrides
+
+[`BlobStorageStrategyBase`](Class.BlobStorageStrategyBase).[`createSignedUrl`](Class.BlobStorageStrategyBase#createsignedurl)
+
+***
+
+### deleteObject()
+
+```ts
+deleteObject(request): Promise<void>;
+```
+
+Defined in: [strategies/azure/AzureBlobStorageStrategy.ts:141](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-blob-storage/src/strategies/azure/AzureBlobStorageStrategy.ts#L141)
+
+Deletes a blob object from the storage backend.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `request` | [`IBlobDeleteRequest`](Interface.IBlobDeleteRequest) | The delete request describing the object to remove. |
+
+#### Returns
+
+`Promise`\<`void`\>
+
+#### Overrides
+
+[`BlobStorageStrategyBase`](Class.BlobStorageStrategyBase).[`deleteObject`](Class.BlobStorageStrategyBase#deleteobject)
+
+***
+
+### downloadObject()
+
+```ts
+downloadObject<TData>(request): Promise<IBlobDownloadResult<TData>>;
+```
+
+Defined in: [strategies/azure/AzureBlobStorageStrategy.ts:121](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-blob-storage/src/strategies/azure/AzureBlobStorageStrategy.ts#L121)
+
+Downloads a blob object from the storage backend.
+
+#### Type Parameters
+
+| Type Parameter |
+| ------ |
+| `TData` |
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `request` | [`IBlobDownloadRequest`](Interface.IBlobDownloadRequest) | The download request describing the object to download. |
+
+#### Returns
+
+`Promise`\<[`IBlobDownloadResult`](Interface.IBlobDownloadResult)\<`TData`\>\>
+
+The download result including payload and metadata.
+
+#### Overrides
+
+[`BlobStorageStrategyBase`](Class.BlobStorageStrategyBase).[`downloadObject`](Class.BlobStorageStrategyBase#downloadobject)
+
+***
+
+### uploadObject()
+
+```ts
+uploadObject(request): Promise<IBlobUploadResult>;
+```
+
+Defined in: [strategies/azure/AzureBlobStorageStrategy.ts:79](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-blob-storage/src/strategies/azure/AzureBlobStorageStrategy.ts#L79)
+
+Uploads a blob object to the storage backend.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `request` | [`IBlobUploadRequest`](Interface.IBlobUploadRequest) | The upload request describing the object to upload. |
+
+#### Returns
+
+`Promise`\<[`IBlobUploadResult`](Interface.IBlobUploadResult)\>
+
+The resulting upload metadata.
+
+#### Overrides
+
+[`BlobStorageStrategyBase`](Class.BlobStorageStrategyBase).[`uploadObject`](Class.BlobStorageStrategyBase#uploadobject)

package/data/packages/platform-blob-storage/api/Class.BlobModule.md

@@ -5,9 +5,22 @@ editUrl: false
 ---
 # Class: BlobModule
 
-Defined in: [BlobModule.ts:82](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-blob-storage/src/BlobModule.ts#L82)
+Defined in: [BlobModule.ts:47](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-blob-storage/src/BlobModule.ts#L47)
 
 NestJS module responsible for providing blob storage services.
+Uses a strategy pattern to support pluggable storage backends.
+
+## Example
+
+```typescript
+import { BlobModule } from '@breadstone/archipel-platform-blob-storage';
+import { VercelBlobStorageStrategy, VERCEL_CONFIG_ENTRIES } from '@breadstone/archipel-platform-blob-storage/strategies/vercel';
+
+BlobModule.register({
+  storageStrategy: VercelBlobStorageStrategy,
+  configEntries: VERCEL_CONFIG_ENTRIES,
+});
+```
 
 ## Constructors
 
@@ -23,27 +36,24 @@ new BlobModule(): BlobModule;
 
 ## Methods
 
-### forRoot()
+### register()
 
 ```ts
-static forRoot(options?): DynamicModule;
+static register(options): DynamicModule;
 ```
 
-Defined in: [BlobModule.ts:93](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-blob-storage/src/BlobModule.ts#L93)
+Defined in: [BlobModule.ts:57](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-blob-storage/src/BlobModule.ts#L57)
 
-Configures the module with the specified options.
-When `objectPersistence` / `variantPersistence` are provided the
-corresponding adapters are registered as ports. Otherwise the
-service works without metadata tracking.
+Configures the module with the specified storage strategy.
 
 #### Parameters
 
 | Parameter | Type | Description |
 | ------ | ------ | ------ |
-| `options?` | [`IBlobModuleOptions`](Interface.IBlobModuleOptions) | The module configuration options. |
+| `options` | [`IBlobModuleOptions`](Interface.IBlobModuleOptions) | The module configuration options. |
 
 #### Returns
 
 `DynamicModule`
 
-Dynamic module definition
+Dynamic module definition.

package/data/packages/platform-blob-storage/api/Class.BlobService.md

@@ -15,7 +15,7 @@ Provides a generic abstraction for blob storage operations independent of the un
 
 ```ts
 new BlobService(
-   blobProvider, 
+   storageStrategy, 
    objectPersistence, 
    variantPersistence): BlobService;
 ```
@@ -28,7 +28,7 @@ Initializes a new instance of the BlobService class.
 
 | Parameter | Type | Description |
 | ------ | ------ | ------ |
-| `blobProvider` | [`IBlobProvider`](Interface.IBlobProvider) | The concrete blob provider implementation. |
+| `storageStrategy` | [`BlobStorageStrategyBase`](Class.BlobStorageStrategyBase) | The concrete blob storage strategy implementation. |
 | `objectPersistence` | \| [`BlobObjectPersistencePort`](Class.BlobObjectPersistencePort) \| `null` | Optional port persisting original blob metadata. |
 | `variantPersistence` | \| [`BlobVariantPersistencePort`](Class.BlobVariantPersistencePort) \| `null` | Optional port persisting derived blob metadata. |
 
@@ -44,7 +44,7 @@ Initializes a new instance of the BlobService class.
 createSignedUrl(request): Promise<string>;
 ```
 
-Defined in: [services/BlobService.ts:130](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-blob-storage/src/services/BlobService.ts#L130)
+Defined in: [services/BlobService.ts:121](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-blob-storage/src/services/BlobService.ts#L121)
 
 Generates a signed URL for the specified object.
 
@@ -68,7 +68,7 @@ A signed URL that can be used to access the object.
 deleteFile(key): Promise<void>;
 ```
 
-Defined in: [services/BlobService.ts:183](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-blob-storage/src/services/BlobService.ts#L183)
+Defined in: [services/BlobService.ts:171](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-blob-storage/src/services/BlobService.ts#L171)
 
 Deletes a file by key.
 
@@ -90,7 +90,7 @@ Deletes a file by key.
 deleteObject(request): Promise<void>;
 ```
 
-Defined in: [services/BlobService.ts:112](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-blob-storage/src/services/BlobService.ts#L112)
+Defined in: [services/BlobService.ts:108](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-blob-storage/src/services/BlobService.ts#L108)
 
 Deletes an object from the configured blob provider.
 
@@ -112,7 +112,7 @@ Deletes an object from the configured blob provider.
 downloadFile<TData>(key, responseType?): Promise<IBlobDownloadResult<TData>>;
 ```
 
-Defined in: [services/BlobService.ts:165](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-blob-storage/src/services/BlobService.ts#L165)
+Defined in: [services/BlobService.ts:156](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-blob-storage/src/services/BlobService.ts#L156)
 
 Downloads a file by key.
 
@@ -143,7 +143,7 @@ The downloaded data and related metadata.
 downloadObject<TData>(request): Promise<IBlobDownloadResult<TData>>;
 ```
 
-Defined in: [services/BlobService.ts:102](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-blob-storage/src/services/BlobService.ts#L102)
+Defined in: [services/BlobService.ts:98](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-blob-storage/src/services/BlobService.ts#L98)
 
 Downloads an object from the configured blob provider.
 
@@ -176,7 +176,7 @@ uploadFile(
 contentType?): Promise<IBlobUploadResult>;
 ```
 
-Defined in: [services/BlobService.ts:147](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-blob-storage/src/services/BlobService.ts#L147)
+Defined in: [services/BlobService.ts:138](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-blob-storage/src/services/BlobService.ts#L138)
 
 Uploads a buffer using the provided key.