@breadstone/archipel-mcp 0.0.21 → 0.0.23
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.
- package/README.md +32 -13
- package/data/guides/ai-text-generation.md +16 -24
- package/data/guides/cryptography-and-otp.md +2 -2
- package/data/guides/database-setup.md +4 -3
- package/data/guides/email-templates.md +52 -42
- package/data/guides/getting-started.md +6 -6
- package/data/guides/resource-management.md +9 -9
- package/data/packages/platform-authentication/api/Interface.IMfaSubjectUpdate.md +1 -1
- package/data/packages/platform-authentication/api/index.md +1 -1
- package/data/packages/platform-blob-storage/api/Variable.AWS_S3_PROVIDER_OPTIONS.md +1 -1
- package/data/packages/platform-blob-storage/api/Variable.AZURE_BLOB_PROVIDER_OPTIONS.md +1 -1
- package/data/packages/platform-blob-storage/api/Variable.BLOB_PROVIDER.md +1 -1
- package/data/packages/platform-blob-storage/api/Variable.VERCEL_BLOB_PROVIDER_OPTIONS.md +1 -1
- package/data/packages/platform-caching/api/Class.RedisLayeredCache.md +3 -3
- package/data/packages/platform-core/api/Class.ErrorTemplateService.md +1 -1
- package/data/packages/platform-core/api/Class.HostService.md +1 -1
- package/data/packages/platform-core/api/Variable.ID_GENERATOR_TOKEN.md +1 -1
- package/data/packages/platform-core/api/index.md +0 -27
- package/data/packages/platform-core/index.md +7 -4
- package/data/packages/platform-cryptography/api/Class.BcryptService.md +4 -4
- package/data/packages/platform-cryptography/api/Class.OtpService.md +6 -6
- package/data/packages/platform-cryptography/api/Variable.BCRYPT_OPTIONS.md +2 -2
- package/data/packages/platform-cryptography/api/Variable.MAX_BCRYPT_PASSWORD_BYTES.md +1 -1
- package/data/packages/platform-cryptography/api/Variable.MIN_BCRYPT_ROUNDS.md +1 -1
- package/data/packages/platform-cryptography/api/Variable.OTP_OPTIONS.md +2 -2
- package/data/packages/platform-cryptography/api/Variable.OTP_SERVICE_TOKEN.md +2 -2
- package/data/packages/platform-cryptography/api/Variable.TOTP_EPOCH_TOLERANCE.md +1 -1
- package/data/packages/platform-cryptography/api/index.md +3 -3
- package/data/packages/platform-documents/api/Class.BaseDocumentRenderer.md +32 -1
- package/data/packages/platform-documents/api/Class.DocumentEngine.md +4 -4
- package/data/packages/platform-documents/api/Class.DocumentModule.md +2 -2
- package/data/packages/platform-documents/api/Class.DocxDocumentRenderer2.md +333 -0
- package/data/packages/platform-documents/api/Class.PdfDocumentRenderer.md +355 -0
- package/data/packages/platform-documents/api/Interface.IDocumentModuleOptions.md +31 -5
- package/data/packages/platform-documents/api/Variable.DOCUMENT_MODULE_OPTIONS.md +1 -1
- package/data/packages/platform-documents/api/Variable.DOCUMENT_PARSER_TOKEN.md +1 -1
- package/data/packages/platform-documents/api/Variable.DOCUMENT_RENDERER_TOKEN.md +1 -1
- package/data/packages/platform-documents/api/Variable.IMAGE_PROCESSOR_TOKEN.md +1 -1
- package/data/packages/platform-documents/api/index.md +2 -0
- package/data/packages/platform-esigning/api/Class.EsigningClientPort.md +1 -1
- package/data/packages/platform-health/index.md +128 -0
- package/data/packages/platform-mailing/api/Class.DeliveryStrategyBase.md +0 -1
- package/data/packages/platform-mailing/api/Class.MailModule.md +1 -1
- package/data/packages/platform-mailing/api/Class.MailVerificationService.md +1 -1
- package/data/packages/platform-mailing/api/Class.TemplateFetchStrategyBase.md +0 -5
- package/data/packages/platform-mailing/api/Variable.SMTP_CONFIG_ENTRIES.md +14 -0
- package/data/packages/platform-mailing/api/Variable.SMTP_HOST.md +14 -0
- package/data/packages/platform-mailing/api/Variable.SMTP_PASSWORD.md +14 -0
- package/data/packages/platform-mailing/api/Variable.SMTP_PORT.md +14 -0
- package/data/packages/platform-mailing/api/Variable.SMTP_SECURE.md +14 -0
- package/data/packages/platform-mailing/api/Variable.SMTP_USER.md +14 -0
- package/data/packages/platform-mailing/api/index.md +7 -4
- package/data/packages/platform-mapping/index.md +121 -0
- package/data/packages/platform-mcp/api/Variable.MCP_MODULE_OPTIONS.md +1 -1
- package/data/packages/platform-openapi/api/Class.SwaggerMultiDocumentService.md +4 -4
- package/data/packages/platform-resources/index.md +135 -0
- package/data/packages/platform-telemetry/api/Class.OtelSdkHolder.md +1 -1
- package/data/packages/platform-telemetry/api/Variable.TELEMETRY_ENABLED.md +1 -1
- package/data/packages/platform-telemetry/api/Variable.TELEMETRY_FACADE.md +1 -1
- package/data/packages/platform-telemetry/api/Variable.TELEMETRY_OPTIONS.md +1 -1
- package/{src/knowledge/configPattern.js → data/patterns/config-pattern.md} +46 -49
- package/{src/knowledge/dtoPattern.js → data/patterns/dto-pattern.md} +58 -61
- package/{src/knowledge/errorHandlingPattern.js → data/patterns/error-handling-pattern.md} +35 -38
- package/{src/knowledge/guardPattern.js → data/patterns/guard-pattern.md} +35 -38
- package/{src/knowledge/mappingPattern.js → data/patterns/mapping-pattern.md} +43 -144
- package/data/patterns/module-pattern.md +182 -0
- package/data/patterns/query-pattern.md +137 -0
- package/data/patterns/repository-pattern.md +208 -0
- package/{src/knowledge/testingPattern.js → data/patterns/testing-pattern.md} +37 -40
- package/package.json +2 -2
- package/src/PatternsLoader.d.ts +12 -0
- package/src/PatternsLoader.js +65 -0
- package/src/generators/mappingPatternGenerator.d.ts +5 -0
- package/src/generators/mappingPatternGenerator.js +107 -0
- package/src/generators/modulePatternGenerator.d.ts +5 -0
- package/src/generators/modulePatternGenerator.js +107 -0
- package/src/generators/queryPatternGenerator.d.ts +4 -0
- package/src/generators/queryPatternGenerator.js +83 -0
- package/src/generators/repositoryPatternGenerator.d.ts +5 -0
- package/src/generators/repositoryPatternGenerator.js +165 -0
- package/src/main.js +15 -9
- package/src/models/IPatternDoc.d.ts +15 -0
- package/src/models/IPatternDoc.js +3 -0
- package/src/tools/registerGetConfigPatternTool.d.ts +2 -1
- package/src/tools/registerGetConfigPatternTool.js +5 -4
- package/src/tools/registerGetDtoPatternTool.d.ts +2 -1
- package/src/tools/registerGetDtoPatternTool.js +5 -4
- package/src/tools/registerGetErrorHandlingPatternTool.d.ts +2 -1
- package/src/tools/registerGetErrorHandlingPatternTool.js +5 -4
- package/src/tools/registerGetGuardPatternTool.d.ts +2 -1
- package/src/tools/registerGetGuardPatternTool.js +5 -4
- package/src/tools/registerGetMappingPatternTool.d.ts +2 -1
- package/src/tools/registerGetMappingPatternTool.js +6 -5
- package/src/tools/registerGetModulePatternTool.d.ts +2 -1
- package/src/tools/registerGetModulePatternTool.js +6 -5
- package/src/tools/registerGetQueryPatternTool.d.ts +2 -1
- package/src/tools/registerGetQueryPatternTool.js +6 -5
- package/src/tools/registerGetRepositoryPatternTool.d.ts +2 -1
- package/src/tools/registerGetRepositoryPatternTool.js +6 -5
- package/src/tools/registerGetTestingPatternTool.d.ts +2 -1
- package/src/tools/registerGetTestingPatternTool.js +5 -4
- package/data/packages/platform-core/api/Class.BlobResourceStrategy.md +0 -195
- package/data/packages/platform-core/api/Class.EmbeddedResourceStrategy.md +0 -215
- package/data/packages/platform-core/api/Class.FileResourceStrategy.md +0 -192
- package/data/packages/platform-core/api/Class.HealthModule.md +0 -42
- package/data/packages/platform-core/api/Class.HealthOrchestrator.md +0 -64
- package/data/packages/platform-core/api/Class.MappingBuilder.md +0 -110
- package/data/packages/platform-core/api/Class.MappingModule.md +0 -46
- package/data/packages/platform-core/api/Class.MappingNotRegisteredError.md +0 -56
- package/data/packages/platform-core/api/Class.MappingProfileBase.md +0 -52
- package/data/packages/platform-core/api/Class.MappingService.md +0 -284
- package/data/packages/platform-core/api/Class.ResourceManager.md +0 -565
- package/data/packages/platform-core/api/Class.ResourceModule.md +0 -46
- package/data/packages/platform-core/api/Class.TypeMappingNotRegisteredError.md +0 -57
- package/data/packages/platform-core/api/Function.createMappingKey.md +0 -39
- package/data/packages/platform-core/api/Interface.IBlobResourceStrategyConfig.md +0 -28
- package/data/packages/platform-core/api/Interface.IBlobServiceAdapter.md +0 -40
- package/data/packages/platform-core/api/Interface.IFileResourceStrategyConfig.md +0 -72
- package/data/packages/platform-core/api/Interface.IHealthCheckResult.md +0 -46
- package/data/packages/platform-core/api/Interface.IHealthIndicator.md +0 -41
- package/data/packages/platform-core/api/Interface.IMappingBuilder.md +0 -76
- package/data/packages/platform-core/api/Interface.IMappingKey.md +0 -58
- package/data/packages/platform-core/api/Interface.IMappingProfile.md +0 -32
- package/data/packages/platform-core/api/Interface.IResourceManagerConfig.md +0 -89
- package/data/packages/platform-core/api/Interface.IResourceMetadata.md +0 -94
- package/data/packages/platform-core/api/Interface.IResourceResult.md +0 -34
- package/data/packages/platform-core/api/Interface.IResourceStrategy.md +0 -134
- package/data/packages/platform-core/api/Variable.HEALTH_INDICATORS_TOKEN.md +0 -14
- package/data/packages/platform-mailing/api/Class.BlobTemplateFetchStrategy.md +0 -60
- package/data/packages/platform-mailing/api/Class.FileTemplateFetchStrategy.md +0 -58
- package/data/packages/platform-mailing/api/Class.LogDeliveryStrategy.md +0 -71
- package/src/knowledge/configPattern.d.ts +0 -5
- package/src/knowledge/dtoPattern.d.ts +0 -5
- package/src/knowledge/errorHandlingPattern.d.ts +0 -5
- package/src/knowledge/guardPattern.d.ts +0 -5
- package/src/knowledge/mappingPattern.d.ts +0 -6
- package/src/knowledge/modulePattern.d.ts +0 -6
- package/src/knowledge/modulePattern.js +0 -283
- package/src/knowledge/queryPattern.d.ts +0 -6
- package/src/knowledge/queryPattern.js +0 -215
- package/src/knowledge/repositoryPattern.d.ts +0 -6
- package/src/knowledge/repositoryPattern.js +0 -367
- package/src/knowledge/testingPattern.d.ts +0 -5
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# @breadstone/archipel-mcp
|
|
2
2
|
|
|
3
|
-
MCP (Model Context Protocol) server that provides Archipel platform knowledge
|
|
3
|
+
MCP (Model Context Protocol) server that provides Archipel platform knowledge - documentation and query patterns - to AI development tools. The server acts as a structured knowledge provider: AI models combine this knowledge with the user's project context to generate framework-compliant code.
|
|
4
4
|
|
|
5
5
|
## Usage
|
|
6
6
|
|
|
@@ -40,30 +40,49 @@ npx @breadstone/archipel-mcp
|
|
|
40
40
|
Returns the complete Archipel v1 query pattern: `IRepositoryQuery` interface, `query()` factory, `QueryResultType`, transactional queries, rules, and usage examples. When a `modelName` and `fields` array are provided, it generates tailored `findFirst`, `findMany`, and `count` query examples for that model.
|
|
41
41
|
|
|
42
42
|
```
|
|
43
|
-
modelName?: string
|
|
44
|
-
fields?: string[]
|
|
43
|
+
modelName?: string - Prisma model name (e.g. "User")
|
|
44
|
+
fields?: string[] - Field names (e.g. ["id", "email", "name", "createdAt"])
|
|
45
45
|
```
|
|
46
46
|
|
|
47
47
|
## Architecture
|
|
48
48
|
|
|
49
49
|
Plain Node.js MCP server using `@modelcontextprotocol/sdk`. No NestJS, no DI container.
|
|
50
50
|
|
|
51
|
-
```
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
51
|
+
```mermaid
|
|
52
|
+
flowchart TB
|
|
53
|
+
MainTs[main.ts\nCLI entry\nstdio transport + tool registration]
|
|
54
|
+
DocsLoader[DocsLoader.ts\nLoads and indexes .docs/packages]
|
|
55
|
+
GuidesLoader[GuidesLoader.ts\nLoads and indexes .docs/guides]
|
|
56
|
+
PatternsLoader[PatternsLoader.ts\nLoads and indexes .docs/patterns]
|
|
57
|
+
|
|
58
|
+
subgraph Models[models/]
|
|
59
|
+
IPackageDoc[IPackageDoc.ts\nPackage documentation interface]
|
|
60
|
+
IGuideDoc[IGuideDoc.ts\nGuide documentation interface]
|
|
61
|
+
IPatternDoc[IPatternDoc.ts\nPattern documentation interface]
|
|
62
|
+
end
|
|
63
|
+
|
|
64
|
+
subgraph Generators[generators/]
|
|
65
|
+
QueryGenerator[queryPatternGenerator.ts]
|
|
66
|
+
RepositoryGenerator[repositoryPatternGenerator.ts]
|
|
67
|
+
MappingGenerator[mappingPatternGenerator.ts]
|
|
68
|
+
ModuleGenerator[modulePatternGenerator.ts]
|
|
69
|
+
end
|
|
70
|
+
|
|
71
|
+
MainTs --> DocsLoader
|
|
72
|
+
MainTs --> GuidesLoader
|
|
73
|
+
MainTs --> PatternsLoader
|
|
74
|
+
DocsLoader --> IPackageDoc
|
|
75
|
+
GuidesLoader --> IGuideDoc
|
|
76
|
+
PatternsLoader --> IPatternDoc
|
|
58
77
|
```
|
|
59
78
|
|
|
60
79
|
### Documentation Resolution
|
|
61
80
|
|
|
62
81
|
The server locates docs in this order:
|
|
63
82
|
|
|
64
|
-
1. **Bundled data**
|
|
65
|
-
2. **Workspace root**
|
|
66
|
-
3. **Relative fallback**
|
|
83
|
+
1. **Bundled data** - `<package>/data/packages/` (shipped with the npm package)
|
|
84
|
+
2. **Workspace root** - `<cwd>/.docs/packages/` (monorepo development)
|
|
85
|
+
3. **Relative fallback** - walks up from compiled source to find `.docs/packages/`
|
|
67
86
|
|
|
68
87
|
## Development
|
|
69
88
|
|
|
@@ -368,28 +368,20 @@ If an AI SDK provider package is not installed, the error message clearly states
|
|
|
368
368
|
|
|
369
369
|
## Architecture Overview
|
|
370
370
|
|
|
371
|
-
```
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
┌─────────────┐ ┌──────────────┐
|
|
388
|
-
│ Provider │ │ Feature │
|
|
389
|
-
│ Loaders │ │ Capabilities │
|
|
390
|
-
│ (OpenAI, │ │ (custom │
|
|
391
|
-
│ Anthropic, │ │ handlers) │
|
|
392
|
-
│ Google, │ │ │
|
|
393
|
-
│ Grok) │ │ │
|
|
394
|
-
└─────────────┘ └──────────────┘
|
|
371
|
+
```mermaid
|
|
372
|
+
flowchart TB
|
|
373
|
+
subgraph IntelligenceModule[IntelligenceModule]
|
|
374
|
+
TextGenerator[IntelligenceTextGenerator\nConfigService -> provider]
|
|
375
|
+
CapabilityRegistry[IntelligenceCapability Registry]
|
|
376
|
+
end
|
|
377
|
+
|
|
378
|
+
GenerateText["generateText(prompt, options?)"]
|
|
379
|
+
ResolveCapability["resolve(intent, context)\nregister(capability)"]
|
|
380
|
+
ProviderLoaders[Provider Loaders\nOpenAI, Anthropic, Google, Grok]
|
|
381
|
+
FeatureCapabilities[Feature Capabilities\ncustom handlers]
|
|
382
|
+
|
|
383
|
+
TextGenerator --> GenerateText
|
|
384
|
+
CapabilityRegistry --> ResolveCapability
|
|
385
|
+
TextGenerator --> ProviderLoaders
|
|
386
|
+
CapabilityRegistry --> FeatureCapabilities
|
|
395
387
|
```
|
|
@@ -105,7 +105,7 @@ The prefix is required and must be a non-empty string. Use short, descriptive pr
|
|
|
105
105
|
|
|
106
106
|
```typescript
|
|
107
107
|
import { Module } from '@nestjs/common';
|
|
108
|
-
import { OtpService, OTP_SERVICE_TOKEN } from '@breadstone/archipel-platform-cryptography';
|
|
108
|
+
import { OtpService, OTP_SERVICE_TOKEN } from '@breadstone/archipel-platform-cryptography/otp';
|
|
109
109
|
|
|
110
110
|
@Module({
|
|
111
111
|
providers: [
|
|
@@ -125,7 +125,7 @@ Generate a secret and a QR code URI for the user's authenticator app:
|
|
|
125
125
|
|
|
126
126
|
```typescript
|
|
127
127
|
import { Inject, Injectable } from '@nestjs/common';
|
|
128
|
-
import { OTP_SERVICE_TOKEN, type IOtpService } from '@breadstone/archipel-platform-cryptography';
|
|
128
|
+
import { OTP_SERVICE_TOKEN, type IOtpService } from '@breadstone/archipel-platform-cryptography/otp';
|
|
129
129
|
|
|
130
130
|
@Injectable()
|
|
131
131
|
export class MfaService {
|
|
@@ -362,7 +362,7 @@ const result = await this._db.transactionCallback(async (tx) => {
|
|
|
362
362
|
|
|
363
363
|
## Health Checks
|
|
364
364
|
|
|
365
|
-
`DatabaseModule` automatically registers a `DatabaseHealthIndicator` with the health orchestrator from `platform-
|
|
365
|
+
`DatabaseModule` automatically registers a `DatabaseHealthIndicator` with the health orchestrator from `platform-health`. Once your application exposes a `/health` endpoint, database connectivity is checked via a `SELECT 1` ping. No additional configuration is needed.
|
|
366
366
|
|
|
367
367
|
If the health check fails, the indicator reports `database: down` with the error details.
|
|
368
368
|
|
|
@@ -484,7 +484,7 @@ export class UserService {
|
|
|
484
484
|
// src/users/UserController.ts
|
|
485
485
|
import { Controller, Get, Param, NotFoundException } from '@nestjs/common';
|
|
486
486
|
import { UserService } from './UserService';
|
|
487
|
-
import { MappingService } from '@breadstone/archipel-platform-
|
|
487
|
+
import { MappingService } from '@breadstone/archipel-platform-mapping';
|
|
488
488
|
import { USER_TO_RESPONSE } from './mapping-keys';
|
|
489
489
|
|
|
490
490
|
@Controller('users')
|
|
@@ -514,7 +514,8 @@ And the root module wiring everything together:
|
|
|
514
514
|
```typescript
|
|
515
515
|
// src/app.module.ts
|
|
516
516
|
import { Module } from '@nestjs/common';
|
|
517
|
-
import { ConfigModule
|
|
517
|
+
import { ConfigModule } from '@breadstone/archipel-platform-configuration';
|
|
518
|
+
import { MappingModule } from '@breadstone/archipel-platform-mapping';
|
|
518
519
|
import { DatabaseModule, PLATFORM_DATABASE_CONFIG_ENTRIES } from '@breadstone/archipel-platform-database';
|
|
519
520
|
import { UserModule } from './users/UserModule';
|
|
520
521
|
|
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: Email Templates
|
|
3
|
-
description: Create, register, and override email templates using the ResourceManager from platform-
|
|
3
|
+
description: Create, register, and override email templates using the ResourceManager from platform-resources and the template engine from platform-mailing.
|
|
4
4
|
order: 8
|
|
5
5
|
---
|
|
6
6
|
|
|
7
7
|
# Email Templates
|
|
8
8
|
|
|
9
|
-
This guide explains how to create email templates for `platform-mailing` and register them with `ResourceManager` from `platform-
|
|
9
|
+
This guide explains how to create email templates for `platform-mailing` and register them with `ResourceManager` from `platform-resources`. It covers the template syntax, the built-in template names, how to provide your own HTML/TXT files, and how to override library defaults.
|
|
10
10
|
|
|
11
11
|
> **Prerequisite:** You should be familiar with [Email Delivery](/guides/email-delivery) for general mail setup and [Resource Management](/guides/resource-management) for how `ResourceManager` strategies work.
|
|
12
12
|
|
|
@@ -16,16 +16,14 @@ This guide explains how to create email templates for `platform-mailing` and reg
|
|
|
16
16
|
|
|
17
17
|
`platform-mailing` does **not** ship ready-made template files. It defines a list of known template **names** and loads the actual content through `ResourceManager` at startup.
|
|
18
18
|
|
|
19
|
-
```
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
(variable interpolation) BlobResourceStrategy
|
|
28
|
-
EmbeddedResourceStrategy
|
|
19
|
+
```mermaid
|
|
20
|
+
flowchart LR
|
|
21
|
+
MailService["MailService<br/>sendTemplate()"] --> MailTemplateEngine["MailTemplateEngine<br/>compileTemplate()"]
|
|
22
|
+
MailTemplateEngine --> ResourceManager["ResourceManager<br/>tryLoadAsync()"]
|
|
23
|
+
MailTemplateEngine --> ContentTemplateEngine["ContentTemplateEngine<br/>variable interpolation"]
|
|
24
|
+
ResourceManager --> FileResourceStrategy[FileResourceStrategy]
|
|
25
|
+
ResourceManager --> BlobResourceStrategy[BlobResourceStrategy]
|
|
26
|
+
ResourceManager --> EmbeddedResourceStrategy[EmbeddedResourceStrategy]
|
|
29
27
|
```
|
|
30
28
|
|
|
31
29
|
1. `MailService.sendTemplate()` passes the template name and context variables to `MailTemplateEngine`.
|
|
@@ -59,18 +57,18 @@ Templates use a Handlebars-style syntax powered by `ContentTemplateEngine`:
|
|
|
59
57
|
|
|
60
58
|
| Syntax | Description |
|
|
61
59
|
| ---------------------------------------------- | --------------------------------- |
|
|
62
|
-
|
|
|
63
|
-
|
|
|
64
|
-
|
|
|
65
|
-
|
|
|
66
|
-
|
|
|
67
|
-
|
|
|
68
|
-
|
|
|
69
|
-
|
|
|
60
|
+
| `<code>{{variableName}}</code>` | Simple variable substitution |
|
|
61
|
+
| `<code>{{#if condition}}...{{/if}}</code>` | Conditional block |
|
|
62
|
+
| `<code>{{#if condition}}...{{else}}...{{/if}}</code>` | Conditional with else |
|
|
63
|
+
| `<code>{{#unless condition}}...{{/unless}}</code>` | Negative conditional |
|
|
64
|
+
| `<code>{{#each items}}...{{/each}}</code>` | Loop over array |
|
|
65
|
+
| `<code>{{#with object}}...{{/with}}</code>` | Context switching |
|
|
66
|
+
| `<code>{{@index}}</code>`, `<code>{{@first}}</code>`, `<code>{{@last}}</code>` | Loop metadata inside `#each` |
|
|
67
|
+
| `<code>{{nested.property}}</code>` | Dot notation for nested values |
|
|
70
68
|
|
|
71
69
|
### Example: `AuthVerify.html`
|
|
72
70
|
|
|
73
|
-
```
|
|
71
|
+
```text
|
|
74
72
|
<!DOCTYPE html>
|
|
75
73
|
<html>
|
|
76
74
|
<head>
|
|
@@ -78,14 +76,14 @@ Templates use a Handlebars-style syntax powered by `ContentTemplateEngine`:
|
|
|
78
76
|
<title>Verify your email</title>
|
|
79
77
|
</head>
|
|
80
78
|
<body>
|
|
81
|
-
<h1>Hello,
|
|
79
|
+
<h1>Hello, {{userName}}!</h1>
|
|
82
80
|
<p>Please verify your email address by clicking the link below:</p>
|
|
83
81
|
<p>
|
|
84
|
-
<a href="
|
|
82
|
+
<a href="{{verificationUrl}}">Verify Email</a>
|
|
85
83
|
</p>
|
|
86
|
-
|
|
87
|
-
<p>This link expires in
|
|
88
|
-
|
|
84
|
+
{{#if expiresInHours}}
|
|
85
|
+
<p>This link expires in {{expiresInHours}} hours.</p>
|
|
86
|
+
{{/if}}
|
|
89
87
|
<p>If you did not create an account, you can safely ignore this email.</p>
|
|
90
88
|
</body>
|
|
91
89
|
</html>
|
|
@@ -94,13 +92,13 @@ Templates use a Handlebars-style syntax powered by `ContentTemplateEngine`:
|
|
|
94
92
|
### Example: `AuthVerify.txt`
|
|
95
93
|
|
|
96
94
|
```text
|
|
97
|
-
Hello,
|
|
95
|
+
Hello, {{userName}}!
|
|
98
96
|
|
|
99
97
|
Please verify your email address by visiting the following link:
|
|
100
98
|
|
|
101
|
-
|
|
99
|
+
{{verificationUrl}}
|
|
102
100
|
|
|
103
|
-
|
|
101
|
+
{{#if expiresInHours}}This link expires in {{expiresInHours}} hours.{{/if}}
|
|
104
102
|
|
|
105
103
|
If you did not create an account, you can safely ignore this email.
|
|
106
104
|
```
|
|
@@ -117,24 +115,36 @@ When the format is `html`, `MailTemplateEngine` automatically **escapes all cont
|
|
|
117
115
|
|
|
118
116
|
Place your template files in your application's assets directory and register the path with `ResourceModule`:
|
|
119
117
|
|
|
120
|
-
```
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
118
|
+
```mermaid
|
|
119
|
+
flowchart TB
|
|
120
|
+
Root[my-app/]
|
|
121
|
+
Src[src/]
|
|
122
|
+
Assets[assets/]
|
|
123
|
+
AppModule[app.module.ts]
|
|
124
|
+
AuthRegisterHtml[AuthRegister.html]
|
|
125
|
+
AuthRegisterTxt[AuthRegister.txt]
|
|
126
|
+
AuthVerifyHtml[AuthVerify.html]
|
|
127
|
+
AuthVerifyTxt[AuthVerify.txt]
|
|
128
|
+
AuthForgotPasswordHtml[AuthForgotPassword.html]
|
|
129
|
+
AppointmentInvitationHtml[AppointmentInvitation.html]
|
|
130
|
+
AppointmentUpdateHtml[AppointmentUpdate.html]
|
|
131
|
+
|
|
132
|
+
Root --> Src
|
|
133
|
+
Src --> Assets
|
|
134
|
+
Src --> AppModule
|
|
135
|
+
Assets --> AuthRegisterHtml
|
|
136
|
+
Assets --> AuthRegisterTxt
|
|
137
|
+
Assets --> AuthVerifyHtml
|
|
138
|
+
Assets --> AuthVerifyTxt
|
|
139
|
+
Assets --> AuthForgotPasswordHtml
|
|
140
|
+
Assets --> AppointmentInvitationHtml
|
|
141
|
+
Assets --> AppointmentUpdateHtml
|
|
132
142
|
```
|
|
133
143
|
|
|
134
144
|
```typescript
|
|
135
145
|
import { Module } from '@nestjs/common';
|
|
136
146
|
import { join } from 'node:path';
|
|
137
|
-
import { ResourceModule, FileResourceStrategy } from '@breadstone/archipel-platform-
|
|
147
|
+
import { ResourceModule, FileResourceStrategy } from '@breadstone/archipel-platform-resources';
|
|
138
148
|
import { MailModule } from '@breadstone/archipel-platform-mailing';
|
|
139
149
|
|
|
140
150
|
@Module({
|
|
@@ -17,10 +17,10 @@ This guide walks you through adding Archipel packages to a NestJS application. B
|
|
|
17
17
|
|
|
18
18
|
## Install the Foundation
|
|
19
19
|
|
|
20
|
-
Every Archipel application starts with `platform-core` and `platform-
|
|
20
|
+
Every Archipel application starts with `platform-core`, `platform-configuration`, and `platform-mapping`. Core provides templates, events, and cryptographic utilities. Mapping provides the object-to-object mapping system. Configuration provides the type-safe config system that all other packages depend on.
|
|
21
21
|
|
|
22
22
|
```bash
|
|
23
|
-
yarn add @breadstone/archipel-platform-core @breadstone/archipel-platform-configuration
|
|
23
|
+
yarn add @breadstone/archipel-platform-core @breadstone/archipel-platform-configuration @breadstone/archipel-platform-mapping
|
|
24
24
|
```
|
|
25
25
|
|
|
26
26
|
### Set Up Configuration
|
|
@@ -85,7 +85,7 @@ The `MappingModule` provides a centralized service for transforming domain entit
|
|
|
85
85
|
```typescript
|
|
86
86
|
import { Module } from '@nestjs/common';
|
|
87
87
|
import { ConfigModule } from '@breadstone/archipel-platform-configuration';
|
|
88
|
-
import { MappingModule } from '@breadstone/archipel-platform-
|
|
88
|
+
import { MappingModule } from '@breadstone/archipel-platform-mapping';
|
|
89
89
|
import { APP_CONFIG_ENTRIES } from './env';
|
|
90
90
|
import { UserMappingProfile } from './mapping/UserMappingProfile';
|
|
91
91
|
|
|
@@ -100,7 +100,7 @@ You define mapping profiles that register transformations:
|
|
|
100
100
|
|
|
101
101
|
```typescript
|
|
102
102
|
import { Injectable } from '@nestjs/common';
|
|
103
|
-
import { MappingProfileBase, type MappingRegistry } from '@breadstone/archipel-platform-
|
|
103
|
+
import { MappingProfileBase, type MappingRegistry } from '@breadstone/archipel-platform-mapping';
|
|
104
104
|
import { USER_TO_RESPONSE } from './mapping-keys';
|
|
105
105
|
|
|
106
106
|
@Injectable()
|
|
@@ -135,7 +135,7 @@ Register the module:
|
|
|
135
135
|
// src/app.module.ts
|
|
136
136
|
import { Module } from '@nestjs/common';
|
|
137
137
|
import { ConfigModule } from '@breadstone/archipel-platform-configuration';
|
|
138
|
-
import { MappingModule } from '@breadstone/archipel-platform-
|
|
138
|
+
import { MappingModule } from '@breadstone/archipel-platform-mapping';
|
|
139
139
|
import { DatabaseModule } from '@breadstone/archipel-platform-database';
|
|
140
140
|
import { APP_CONFIG_ENTRIES } from './env';
|
|
141
141
|
|
|
@@ -286,7 +286,7 @@ Pass your adapter classes to `AuthModule.register()`:
|
|
|
286
286
|
// src/app.module.ts
|
|
287
287
|
import { Module } from '@nestjs/common';
|
|
288
288
|
import { ConfigModule } from '@breadstone/archipel-platform-configuration';
|
|
289
|
-
import { MappingModule } from '@breadstone/archipel-platform-
|
|
289
|
+
import { MappingModule } from '@breadstone/archipel-platform-mapping';
|
|
290
290
|
import { DatabaseModule } from '@breadstone/archipel-platform-database';
|
|
291
291
|
import { AuthModule } from '@breadstone/archipel-platform-authentication';
|
|
292
292
|
import { APP_CONFIG_ENTRIES } from './env';
|
|
@@ -6,16 +6,16 @@ order: 17
|
|
|
6
6
|
|
|
7
7
|
# Resource Management
|
|
8
8
|
|
|
9
|
-
This guide covers working with `ResourceManager` from `platform-
|
|
9
|
+
This guide covers working with `ResourceManager` from `platform-resources`: registering file strategies, loading resources at runtime, and using the built-in caching layer. If your application ships email templates, HTML pages, CSS/JS assets, or any other file-based content, this is how you make it available to services.
|
|
10
10
|
|
|
11
11
|
---
|
|
12
12
|
|
|
13
13
|
## Installation
|
|
14
14
|
|
|
15
|
-
`ResourceManager` is part of `platform-
|
|
15
|
+
`ResourceManager` is part of `platform-resources`.
|
|
16
16
|
|
|
17
17
|
```bash
|
|
18
|
-
yarn add @breadstone/archipel-platform-
|
|
18
|
+
yarn add @breadstone/archipel-platform-resources
|
|
19
19
|
```
|
|
20
20
|
|
|
21
21
|
---
|
|
@@ -47,7 +47,7 @@ If the file exists on disk, it's served immediately. If not, blob storage is che
|
|
|
47
47
|
```typescript
|
|
48
48
|
import { Module } from '@nestjs/common';
|
|
49
49
|
import { join } from 'node:path';
|
|
50
|
-
import { ResourceModule, FileResourceStrategy, EmbeddedResourceStrategy } from '@breadstone/archipel-platform-
|
|
50
|
+
import { ResourceModule, FileResourceStrategy, EmbeddedResourceStrategy } from '@breadstone/archipel-platform-resources';
|
|
51
51
|
|
|
52
52
|
@Module({
|
|
53
53
|
imports: [
|
|
@@ -56,7 +56,7 @@ import { ResourceModule, FileResourceStrategy, EmbeddedResourceStrategy } from '
|
|
|
56
56
|
new FileResourceStrategy({
|
|
57
57
|
basePaths: [
|
|
58
58
|
join(__dirname, 'assets'),
|
|
59
|
-
join(__dirname, '..', 'node_modules', '@breadstone', 'archipel-platform-
|
|
59
|
+
join(__dirname, '..', 'node_modules', '@breadstone', 'archipel-platform-resources', 'assets'),
|
|
60
60
|
join(__dirname, '..', 'node_modules', '@breadstone', 'archipel-platform-openapi', 'assets'),
|
|
61
61
|
join(__dirname, '..', 'node_modules', '@breadstone', 'archipel-platform-mailing', 'assets'),
|
|
62
62
|
],
|
|
@@ -90,7 +90,7 @@ Inject `ResourceManager` and call its load methods. Every method has a `try*` va
|
|
|
90
90
|
|
|
91
91
|
```typescript
|
|
92
92
|
import { Injectable } from '@nestjs/common';
|
|
93
|
-
import { ResourceManager } from '@breadstone/archipel-platform-
|
|
93
|
+
import { ResourceManager } from '@breadstone/archipel-platform-resources';
|
|
94
94
|
|
|
95
95
|
@Injectable()
|
|
96
96
|
export class InvoiceService {
|
|
@@ -172,7 +172,7 @@ The key you pass to `load()` is the **filename** (e.g. `'invoice-template.html'`
|
|
|
172
172
|
Loads from cloud blob storage via a minimal `IBlobServiceAdapter` interface. This is **async-only** — calling `load()` (sync) will throw.
|
|
173
173
|
|
|
174
174
|
```typescript
|
|
175
|
-
import { BlobResourceStrategy, IBlobServiceAdapter } from '@breadstone/archipel-platform-
|
|
175
|
+
import { BlobResourceStrategy, IBlobServiceAdapter } from '@breadstone/archipel-platform-resources';
|
|
176
176
|
|
|
177
177
|
const blobAdapter: IBlobServiceAdapter = {
|
|
178
178
|
async downloadFile(key: string) {
|
|
@@ -247,7 +247,7 @@ const js = this._resourceManager.loadAsString('swagger.js');
|
|
|
247
247
|
|
|
248
248
|
### Application Index Page
|
|
249
249
|
|
|
250
|
-
`platform-core`'s `HostService` loads `index.html` as a template for the root route:
|
|
250
|
+
`platform-core`'s `HostService` loads `index.html` as a template for the root route (the `ResourceManager` itself comes from `platform-resources`):
|
|
251
251
|
|
|
252
252
|
```typescript
|
|
253
253
|
const html = await this._resourceManager.loadAsStringAsync('index.html');
|
|
@@ -300,7 +300,7 @@ Enable `debug: true` in the module config to have `ResourceManager` call `whatDo
|
|
|
300
300
|
Implement `IResourceStrategy` to support a new source (e.g. a database, S3 directly, or a remote API):
|
|
301
301
|
|
|
302
302
|
```typescript
|
|
303
|
-
import { IResourceStrategy, IResourceResult } from '@breadstone/archipel-platform-
|
|
303
|
+
import { IResourceStrategy, IResourceResult } from '@breadstone/archipel-platform-resources';
|
|
304
304
|
|
|
305
305
|
export class DatabaseResourceStrategy implements IResourceStrategy {
|
|
306
306
|
public get name(): string {
|
|
@@ -8,7 +8,7 @@ editUrl: false
|
|
|
8
8
|
Defined in: [libs/platform-authentication/src/contracts/IMfaSubjectUpdate.ts:7](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-authentication/src/contracts/IMfaSubjectUpdate.ts#L7)
|
|
9
9
|
|
|
10
10
|
Data payload for updating MFA state on the underlying entity.
|
|
11
|
-
All properties are optional
|
|
11
|
+
All properties are optional - only the provided ones are applied.
|
|
12
12
|
|
|
13
13
|
## Properties
|
|
14
14
|
|
|
@@ -49,7 +49,7 @@ editUrl: false
|
|
|
49
49
|
| [IMfaConfirmation](Interface.IMfaConfirmation) | Represents the activation result for multi-factor authentication. |
|
|
50
50
|
| [IMfaSetup](Interface.IMfaSetup) | Represents the data required to onboard a multi-factor authenticator. |
|
|
51
51
|
| [IMfaSubject](Interface.IMfaSubject) | Represents an MFA-enabled subject. Contains the data the MFA subsystem needs to read and write MFA state on the underlying user-like entity. |
|
|
52
|
-
| [IMfaSubjectUpdate](Interface.IMfaSubjectUpdate) | Data payload for updating MFA state on the underlying entity. All properties are optional
|
|
52
|
+
| [IMfaSubjectUpdate](Interface.IMfaSubjectUpdate) | Data payload for updating MFA state on the underlying entity. All properties are optional - only the provided ones are applied. |
|
|
53
53
|
| [ISessionRecord](Interface.ISessionRecord) | Represents a persisted session record. |
|
|
54
54
|
| [ISignInResult](Interface.ISignInResult) | Represents the outcome of a sign-in attempt. |
|
|
55
55
|
| [ISocialProfile](Interface.ISocialProfile) | Profile data received from a social / OAuth provider. |
|
|
@@ -9,4 +9,4 @@ editUrl: false
|
|
|
9
9
|
const AWS_S3_PROVIDER_OPTIONS: typeof AWS_S3_PROVIDER_OPTIONS;
|
|
10
10
|
```
|
|
11
11
|
|
|
12
|
-
Defined in: [
|
|
12
|
+
Defined in: [BlobStorageTokens.ts:6](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-blob-storage/src/BlobStorageTokens.ts#L6)
|
|
@@ -9,4 +9,4 @@ editUrl: false
|
|
|
9
9
|
const AZURE_BLOB_PROVIDER_OPTIONS: typeof AZURE_BLOB_PROVIDER_OPTIONS;
|
|
10
10
|
```
|
|
11
11
|
|
|
12
|
-
Defined in: [
|
|
12
|
+
Defined in: [BlobStorageTokens.ts:5](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-blob-storage/src/BlobStorageTokens.ts#L5)
|
|
@@ -9,4 +9,4 @@ editUrl: false
|
|
|
9
9
|
const BLOB_PROVIDER: typeof BLOB_PROVIDER;
|
|
10
10
|
```
|
|
11
11
|
|
|
12
|
-
Defined in: [
|
|
12
|
+
Defined in: [BlobStorageTokens.ts:3](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-blob-storage/src/BlobStorageTokens.ts#L3)
|
|
@@ -9,4 +9,4 @@ editUrl: false
|
|
|
9
9
|
const VERCEL_BLOB_PROVIDER_OPTIONS: typeof VERCEL_BLOB_PROVIDER_OPTIONS;
|
|
10
10
|
```
|
|
11
11
|
|
|
12
|
-
Defined in: [
|
|
12
|
+
Defined in: [BlobStorageTokens.ts:4](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-blob-storage/src/BlobStorageTokens.ts#L4)
|
|
@@ -60,7 +60,7 @@ get(key): TValue | undefined;
|
|
|
60
60
|
|
|
61
61
|
Defined in: [redis/RedisLayeredCache.ts:124](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-caching/src/redis/RedisLayeredCache.ts#L124)
|
|
62
62
|
|
|
63
|
-
Not supported
|
|
63
|
+
Not supported - Redis is inherently asynchronous.
|
|
64
64
|
|
|
65
65
|
#### Parameters
|
|
66
66
|
|
|
@@ -118,7 +118,7 @@ invalidate(key): void;
|
|
|
118
118
|
|
|
119
119
|
Defined in: [redis/RedisLayeredCache.ts:186](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-caching/src/redis/RedisLayeredCache.ts#L186)
|
|
120
120
|
|
|
121
|
-
Not supported
|
|
121
|
+
Not supported - Redis is inherently asynchronous.
|
|
122
122
|
|
|
123
123
|
#### Parameters
|
|
124
124
|
|
|
@@ -196,7 +196,7 @@ set(key, value): void;
|
|
|
196
196
|
|
|
197
197
|
Defined in: [redis/RedisLayeredCache.ts:160](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-caching/src/redis/RedisLayeredCache.ts#L160)
|
|
198
198
|
|
|
199
|
-
Not supported
|
|
199
|
+
Not supported - Redis is inherently asynchronous.
|
|
200
200
|
|
|
201
201
|
#### Parameters
|
|
202
202
|
|
|
@@ -30,7 +30,7 @@ Constructs a new instance of the `ErrorTemplateService` class.
|
|
|
30
30
|
| ------ | ------ |
|
|
31
31
|
| `configService` | `ConfigService` |
|
|
32
32
|
| `contentTemplateEngine` | [`ContentTemplateEngine`](Class.ContentTemplateEngine) |
|
|
33
|
-
| `resourceManager` |
|
|
33
|
+
| `resourceManager` | `ResourceManager` |
|
|
34
34
|
|
|
35
35
|
#### Returns
|
|
36
36
|
|
|
@@ -30,7 +30,7 @@ Constructs a new instance of the `HostService` class.
|
|
|
30
30
|
| ------ | ------ |
|
|
31
31
|
| `configService` | `ConfigService` |
|
|
32
32
|
| `contentTemplateEngine` | [`ContentTemplateEngine`](Class.ContentTemplateEngine) |
|
|
33
|
-
| `resourceManager` |
|
|
33
|
+
| `resourceManager` | `ResourceManager` |
|
|
34
34
|
|
|
35
35
|
#### Returns
|
|
36
36
|
|
|
@@ -9,6 +9,6 @@ editUrl: false
|
|
|
9
9
|
const ID_GENERATOR_TOKEN: typeof ID_GENERATOR_TOKEN;
|
|
10
10
|
```
|
|
11
11
|
|
|
12
|
-
Defined in: [identifiers/IdentifierTokens.ts:6](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-core/src/identifiers/IdentifierTokens.ts#L6)
|
|
12
|
+
Defined in: [identifiers/tokens/IdentifierTokens.ts:6](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-core/src/identifiers/tokens/IdentifierTokens.ts#L6)
|
|
13
13
|
|
|
14
14
|
Interface for ID generators
|