@saltsquareio/nestjs-backend-platform 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SaltSquare
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,72 @@
+# @saltsquareio/nestjs-backend-platform
+
+Reusable NestJS platform library for SaltSquare backend services: configuration,
+database + migrations, logging, HTTP client, health, exceptions, rate limiting,
+scheduling, audit logging, auth primitives, WebSocket tokens, observability, and an
+optional AI module.
+
+> Pre-1.0 (`0.x`). Every release may contain breaking changes — pin an exact version.
+
+## Install
+
+```bash
+npm install @saltsquareio/nestjs-backend-platform
+```
+
+Most capabilities are framework-aligned **peer dependencies** (install the ones your
+app uses — `@nestjs/*`, `typeorm`, `pino`, etc.). The AI stack (`ai`, `@ai-sdk/*`,
+`mem0ai`) and `newrelic` are **optional** peers.
+
+## Quick start
+
+```ts
+// main.ts
+import { initialize } from '@saltsquareio/nestjs-backend-platform';
+import { AppModule } from './app.module';
+
+async function bootstrap() {
+  const app = await initialize(AppModule);
+  await app.listen(process.env.PORT ?? 3000);
+}
+void bootstrap();
+```
+
+```ts
+// app.module.ts
+import {
+  ConfigurationModule,
+  DatabaseModule,
+  LoggerModule,
+  HealthModule,
+} from '@saltsquareio/nestjs-backend-platform';
+
+@Module({
+  imports: [
+    ConfigurationModule.forRoot(),
+    LoggerModule,
+    DatabaseModule.forRootAsync(),
+    HealthModule,
+  ],
+})
+export class AppModule {}
+```
+
+The AI module is imported from a subpath so its heavy deps stay optional:
+
+```ts
+import { AiModule } from '@saltsquareio/nestjs-backend-platform/ai';
+// AiModule.forRoot({ defaultModel, safety, summarization, costRates, memory })
+```
+
+## Documentation
+
+- [Configuration](./docs/configuration.md) — env model, namespaces, defaults, extension
+- [Database](./docs/database.md) — config, overridable defaults, transactions
+- [Migrations](./docs/migrations.md) — the `platform-db` CLI and what the lib vs consumer owns
+- [Modules](./docs/modules.md) — catalogue of what the library provides
+- [AI](./docs/ai.md) — providers, memory, cost, safety, summarization (business-agnostic)
+- [Releasing](./docs/releasing.md) — conventional commits + release-please
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/cli/migrate.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/migrate.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_path_1 = require("node:path");
+const typeorm_1 = require("typeorm");
+const run_migrations_1 = require("../core/migrations/run-migrations");
+const COMMANDS = ['run', 'show', 'revert'];
+function loadDataSource(path) {
+    const mod = require((0, node_path_1.resolve)(path));
+    const candidate = mod.default ?? mod.MigrationsDataSource ?? mod.dataSource;
+    if (!(candidate instanceof typeorm_1.DataSource)) {
+        throw new Error(`No DataSource export in ${path} (expected default, MigrationsDataSource, or dataSource)`);
+    }
+    return candidate;
+}
+async function main() {
+    const args = process.argv.slice(2);
+    const command = (args[0] ?? 'run');
+    if (!COMMANDS.includes(command)) {
+        throw new Error(`Unknown command "${command}". Expected one of: ${COMMANDS.join(', ')}`);
+    }
+    const flag = args.findIndex((arg) => arg === '-d' || arg === '--datasource');
+    const datasourcePath = flag >= 0 ? args[flag + 1] : process.env.MIGRATIONS_DATASOURCE;
+    if (!datasourcePath) {
+        throw new Error('Missing datasource: pass -d <compiled-datasource-path> or set MIGRATIONS_DATASOURCE');
+    }
+    const steps = command === 'revert' ? Number(args[1] ?? '1') : 1;
+    await (0, run_migrations_1.runMigrations)(loadDataSource(datasourcePath), command, steps);
+}
+void main().catch((err) => {
+    console.error('[migrations] failed:', err);
+    process.exit(1);
+});
+//# sourceMappingURL=migrate.js.map

package/dist/cli/migrate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate.js","sourceRoot":"","sources":["../../src/cli/migrate.ts"],"names":[],"mappings":";;;AACA,yCAAoC;AACpC,qCAAqC;AACrC,sEAG2C;AAE3C,MAAM,QAAQ,GAAuB,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;AAE/D,SAAS,cAAc,CAAC,IAAY;IAElC,MAAM,GAAG,GAAG,OAAO,CAAC,IAAA,mBAAO,EAAC,IAAI,CAAC,CAA4B,CAAC;IAC9D,MAAM,SAAS,GAAG,GAAG,CAAC,OAAO,IAAI,GAAG,CAAC,oBAAoB,IAAI,GAAG,CAAC,UAAU,CAAC;IAC5E,IAAI,CAAC,CAAC,SAAS,YAAY,oBAAU,CAAC,EAAE,CAAC;QACvC,MAAM,IAAI,KAAK,CACb,2BAA2B,IAAI,0DAA0D,CAC1F,CAAC;IACJ,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACnC,MAAM,OAAO,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,KAAK,CAAqB,CAAC;IACvD,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;QAChC,MAAM,IAAI,KAAK,CACb,oBAAoB,OAAO,uBAAuB,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACxE,CAAC;IACJ,CAAC;IAED,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,cAAc,CAAC,CAAC;IAC7E,MAAM,cAAc,GAClB,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC;IACjE,IAAI,CAAC,cAAc,EAAE,CAAC;QACpB,MAAM,IAAI,KAAK,CACb,qFAAqF,CACtF,CAAC;IACJ,CAAC;IAED,MAAM,KAAK,GAAG,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAChE,MAAM,IAAA,8BAAa,EAAC,cAAc,CAAC,cAAc,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC;AACtE,CAAC;AAED,KAAK,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;IACjC,OAAO,CAAC,KAAK,CAAC,sBAAsB,EAAE,GAAG,CAAC,CAAC;IAC3C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/core/ai/ai.module.d.ts

@@ -0,0 +1,5 @@
+import { DynamicModule } from '@nestjs/common';
+import { AiModuleOptions } from './ai.options';
+export declare class AiModule {
+    static forRoot(options?: AiModuleOptions): DynamicModule;
+}

package/dist/core/ai/ai.module.js

@@ -0,0 +1,53 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var AiModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AiModule = void 0;
+const common_1 = require("@nestjs/common");
+const database_1 = require("../database");
+const ai_service_1 = require("./ai.service");
+const ai_options_1 = require("./ai.options");
+const context_formatter_service_1 = require("./context/context-formatter.service");
+const cost_tracking_service_1 = require("./cost/cost-tracking.service");
+const ai_invocation_log_entity_1 = require("./entities/ai-invocation-log.entity");
+const prompt_template_entity_1 = require("./entities/prompt-template.entity");
+const memory_service_1 = require("./memory/memory.service");
+const provider_factory_service_1 = require("./provider/provider-factory.service");
+const safety_guardrail_service_1 = require("./safety/safety-guardrail.service");
+const summarization_service_1 = require("./summarization/summarization.service");
+const template_service_1 = require("./template/template.service");
+let AiModule = AiModule_1 = class AiModule {
+    static forRoot(options = {}) {
+        return {
+            module: AiModule_1,
+            imports: [database_1.DatabaseModule.forFeature([prompt_template_entity_1.PromptTemplate, ai_invocation_log_entity_1.AiInvocationLog])],
+            providers: [
+                { provide: ai_options_1.AI_MODULE_OPTIONS, useValue: options },
+                provider_factory_service_1.ProviderFactory,
+                context_formatter_service_1.ContextFormatterService,
+                template_service_1.TemplateService,
+                memory_service_1.MemoryService,
+                safety_guardrail_service_1.SafetyGuardrailService,
+                cost_tracking_service_1.CostTrackingService,
+                ai_service_1.AiService,
+                summarization_service_1.SummarizationService,
+            ],
+            exports: [
+                ai_service_1.AiService,
+                template_service_1.TemplateService,
+                memory_service_1.MemoryService,
+                summarization_service_1.SummarizationService,
+            ],
+        };
+    }
+};
+exports.AiModule = AiModule;
+exports.AiModule = AiModule = AiModule_1 = __decorate([
+    (0, common_1.Module)({})
+], AiModule);
+//# sourceMappingURL=ai.module.js.map

package/dist/core/ai/ai.module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai.module.js","sourceRoot":"","sources":["../../../src/core/ai/ai.module.ts"],"names":[],"mappings":";;;;;;;;;;AAAA,2CAAuD;AACvD,0CAA6C;AAC7C,6CAAyC;AACzC,6CAAkE;AAClE,mFAA8E;AAC9E,wEAAmE;AACnE,kFAAsE;AACtE,8EAAmE;AACnE,4DAAwD;AACxD,kFAAsE;AACtE,gFAA2E;AAC3E,iFAA6E;AAC7E,kEAA8D;AAGvD,IAAM,QAAQ,gBAAd,MAAM,QAAQ;IACnB,MAAM,CAAC,OAAO,CAAC,UAA2B,EAAE;QAC1C,OAAO;YACL,MAAM,EAAE,UAAQ;YAChB,OAAO,EAAE,CAAC,yBAAc,CAAC,UAAU,CAAC,CAAC,uCAAc,EAAE,0CAAe,CAAC,CAAC,CAAC;YACvE,SAAS,EAAE;gBACT,EAAE,OAAO,EAAE,8BAAiB,EAAE,QAAQ,EAAE,OAAO,EAAE;gBACjD,0CAAe;gBACf,mDAAuB;gBACvB,kCAAe;gBACf,8BAAa;gBACb,iDAAsB;gBACtB,2CAAmB;gBACnB,sBAAS;gBACT,4CAAoB;aACrB;YACD,OAAO,EAAE;gBACP,sBAAS;gBACT,kCAAe;gBACf,8BAAa;gBACb,4CAAoB;aACrB;SACF,CAAC;IACJ,CAAC;CACF,CAAA;AAxBY,4BAAQ;mBAAR,QAAQ;IADpB,IAAA,eAAM,EAAC,EAAE,CAAC;GACE,QAAQ,CAwBpB"}

package/dist/core/ai/ai.options.d.ts

@@ -0,0 +1,33 @@
+import type { MemoryConfig as Mem0Config } from 'mem0ai/oss';
+import { AiServiceModelConfig } from './ai.types';
+export declare const AI_MODULE_OPTIONS: unique symbol;
+export interface SafetyPattern {
+    flag: string;
+    pattern: RegExp;
+}
+export interface AiMemoryOptions {
+    enabled?: boolean;
+    config?: Partial<Mem0Config>;
+    factExtractionPrompt?: string;
+    fetchTimeoutMs?: number;
+}
+export interface AiSummarizationOptions {
+    systemPrompt?: string;
+    model?: AiServiceModelConfig;
+    targetTokens?: number;
+    threshold?: number;
+}
+export interface AiModuleOptions {
+    defaultModel?: AiServiceModelConfig;
+    summarization?: AiSummarizationOptions;
+    safety?: {
+        patterns?: SafetyPattern[];
+    };
+    costRates?: Record<string, {
+        input: number;
+        output: number;
+    }>;
+    memory?: AiMemoryOptions;
+}
+export declare const ECHO_MODEL: AiServiceModelConfig;
+export declare const DEFAULT_SUMMARIZATION_PROMPT: string;

package/dist/core/ai/ai.options.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_SUMMARIZATION_PROMPT = exports.ECHO_MODEL = exports.AI_MODULE_OPTIONS = void 0;
+exports.AI_MODULE_OPTIONS = Symbol('AI_MODULE_OPTIONS');
+exports.ECHO_MODEL = {
+    provider: 'echo',
+    name: 'echo',
+};
+exports.DEFAULT_SUMMARIZATION_PROMPT = [
+    'Summarize the preceding conversation for context compression.',
+    'Preserve concrete facts, timelines, decisions, and open questions; compress wording, not content.',
+    'Output plain text only — no markdown, headings, or pleasantries.',
+].join(' ');
+//# sourceMappingURL=ai.options.js.map

package/dist/core/ai/ai.options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai.options.js","sourceRoot":"","sources":["../../../src/core/ai/ai.options.ts"],"names":[],"mappings":";;;AAGa,QAAA,iBAAiB,GAAG,MAAM,CAAC,mBAAmB,CAAC,CAAC;AA0ChD,QAAA,UAAU,GAAyB;IAC9C,QAAQ,EAAE,MAAM;IAChB,IAAI,EAAE,MAAM;CACb,CAAC;AAEW,QAAA,4BAA4B,GAAG;IAC1C,+DAA+D;IAC/D,mGAAmG;IACnG,kEAAkE;CACnE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC"}

package/dist/core/ai/ai.service.d.ts

@@ -0,0 +1,49 @@
+import { type SystemModelMessage } from 'ai';
+import { z } from 'zod';
+import { type AiModuleOptions } from './ai.options';
+import { AiServiceProvider, GenerationResult, InvokeOptions, StreamGenerationResult, StreamInvokeOptions, TextInvokeOptions } from './ai.types';
+import { ContextFormatterService } from './context/context-formatter.service';
+import { CostTrackingService } from './cost/cost-tracking.service';
+import { MemoryService } from './memory/memory.service';
+import { ProviderFactory } from './provider/provider-factory.service';
+import { SafetyGuardrailService } from './safety/safety-guardrail.service';
+import { TemplateService } from './template/template.service';
+export declare class AiService {
+    private readonly providerFactory;
+    private readonly contextFormatter;
+    private readonly templateService;
+    private readonly safetyService;
+    private readonly costService;
+    private readonly memoryService;
+    private readonly logger;
+    private readonly defaultModel;
+    private readonly memoryFetchTimeoutMs;
+    constructor(providerFactory: ProviderFactory, contextFormatter: ContextFormatterService, templateService: TemplateService, safetyService: SafetyGuardrailService, costService: CostTrackingService, memoryService: MemoryService, options: AiModuleOptions);
+    invoke<T extends z.ZodType>(options: InvokeOptions<T>): Promise<GenerationResult<z.infer<T>>>;
+    invokeStream(options: StreamInvokeOptions): Promise<StreamGenerationResult>;
+    invokeText(options: TextInvokeOptions): Promise<GenerationResult<string>>;
+    private initialErrorParams;
+    private prepareInvocation;
+    private echoMetadata;
+    private buildMetadata;
+    private logSuccess;
+    private handleError;
+    private fetchMemories;
+    private buildContextSections;
+}
+export declare function mapMessagesWithCache(sourceMessages: Array<{
+    role: 'user' | 'assistant';
+    content: string;
+}>, provider: AiServiceProvider, cacheRecentHistory: boolean): Array<{
+    role: 'user' | 'assistant';
+    content: string;
+    providerOptions?: {
+        anthropic: {
+            cacheControl: {
+                type: string;
+                ttl: string;
+            };
+        };
+    };
+}>;
+export declare function buildSystemParam(provider: AiServiceProvider, rawTemplate: string, contextSections: string[]): string | Array<SystemModelMessage>;