@devstroupe/devkit-nest 1.1.16 → 1.2.0-beta.1

package/dist/database/typeorm-unit-of-work.d.ts

@@ -0,0 +1,13 @@
+import { DataSource, EntityManager, EntityTarget, ObjectLiteral, Repository } from 'typeorm';
+export interface UnitOfWorkContext {
+    readonly manager: EntityManager;
+    repository<Entity extends ObjectLiteral>(target: EntityTarget<Entity>): Repository<Entity>;
+}
+export interface UnitOfWork {
+    run<Result>(work: (context: UnitOfWorkContext) => Promise<Result>): Promise<Result>;
+}
+export declare class TypeOrmUnitOfWork implements UnitOfWork {
+    private readonly dataSource;
+    constructor(dataSource: Pick<DataSource, 'transaction'>);
+    run<Result>(work: (context: UnitOfWorkContext) => Promise<Result>): Promise<Result>;
+}

package/dist/database/typeorm-unit-of-work.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TypeOrmUnitOfWork = void 0;
+class TypeOrmUnitOfWork {
+    dataSource;
+    constructor(dataSource) {
+        this.dataSource = dataSource;
+    }
+    run(work) {
+        return this.dataSource.transaction((manager) => work({
+            manager,
+            repository: (target) => manager.getRepository(target),
+        }));
+    }
+}
+exports.TypeOrmUnitOfWork = TypeOrmUnitOfWork;

package/dist/database/typeorm-unit-of-work.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/database/typeorm-unit-of-work.test.js

@@ -0,0 +1,34 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const strict_1 = __importDefault(require("node:assert/strict"));
+const node_test_1 = __importDefault(require("node:test"));
+const typeorm_unit_of_work_1 = require("./typeorm-unit-of-work");
+(0, node_test_1.default)('TypeOrmUnitOfWork commits the callback result and uses its manager', async () => {
+    const manager = { getRepository: (target) => ({ target }) };
+    const dataSource = { transaction: async (work) => work(manager) };
+    const result = await new typeorm_unit_of_work_1.TypeOrmUnitOfWork(dataSource).run(async (context) => {
+        strict_1.default.equal(context.manager, manager);
+        strict_1.default.deepEqual(context.repository('invoice'), { target: 'invoice' });
+        return 'committed';
+    });
+    strict_1.default.equal(result, 'committed');
+});
+(0, node_test_1.default)('TypeOrmUnitOfWork propagates an intermediate failure for rollback', async () => {
+    let rolledBack = false;
+    const dataSource = {
+        async transaction(work) {
+            try {
+                return await work({ getRepository() { } });
+            }
+            catch (error) {
+                rolledBack = true;
+                throw error;
+            }
+        },
+    };
+    await strict_1.default.rejects(() => new typeorm_unit_of_work_1.TypeOrmUnitOfWork(dataSource).run(async () => { throw new Error('second write failed'); }), /second write failed/);
+    strict_1.default.equal(rolledBack, true);
+});

package/dist/http/base-crud.controller.d.ts

@@ -1,11 +1,27 @@
-import { RealtimeService } from '../realtime/realtime.service';
-export declare abstract class BaseCrudController<Entity, FilterDto = any> {
-    protected readonly service: any;
-    constructor(service: any);
-    protected readonly realtimeService?: RealtimeService;
-    create(body: any): Promise<Entity>;
-    update(id: string, body: any): Promise<Entity>;
-    findMany(filter: FilterDto): Promise<any>;
-    findById(id: string): Promise<Entity>;
-    delete(id: string): Promise<void>;
+import type { IFilterPagination, IPaginator } from '@devstroupe/devkit-core';
+export interface IdCodec<ID> {
+    decode(raw: string): ID;
+}
+export declare const numberIdCodec: IdCodec<number>;
+export declare const stringIdCodec: IdCodec<string>;
+export declare const uuidIdCodec: IdCodec<string>;
+export interface CrudApplication<Entity, FilterDto, ID, CreateInput, UpdateInput, ListResult> {
+    create(input: CreateInput): Promise<Entity>;
+    update(id: ID, input: UpdateInput): Promise<Entity>;
+    findOne?(id: ID): Promise<Entity | null>;
+    /** Compatibility alias for existing services during migration. */
+    findById?(id: ID): Promise<Entity | null>;
+    findMany(filter: FilterDto): Promise<ListResult>;
+    delete(id: ID): Promise<void>;
+}
+/** Thin typed HTTP adapter. Events, auditing and realtime belong outside HTTP. */
+export declare abstract class BaseCrudController<Entity, FilterDto extends IFilterPagination = IFilterPagination, ID = number, CreateInput = Partial<Entity>, UpdateInput = Partial<Entity>, ListResult = IPaginator<Entity>> {
+    protected readonly application: CrudApplication<Entity, FilterDto, ID, CreateInput, UpdateInput, ListResult>;
+    protected readonly idCodec: IdCodec<ID>;
+    constructor(application: CrudApplication<Entity, FilterDto, ID, CreateInput, UpdateInput, ListResult>, idCodec?: IdCodec<ID>);
+    create(body: CreateInput): Promise<Entity>;
+    update(rawId: string, body: UpdateInput): Promise<Entity>;
+    findMany(filter: FilterDto): Promise<ListResult>;
+    findById(rawId: string): Promise<Entity>;
+    delete(rawId: string): Promise<void>;
 }

package/dist/http/base-crud.controller.js

@@ -12,52 +12,62 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BaseCrudController = void 0;
+exports.BaseCrudController = exports.uuidIdCodec = exports.stringIdCodec = exports.numberIdCodec = void 0;
 const common_1 = require("@nestjs/common");
 const swagger_1 = require("@nestjs/swagger");
-const realtime_service_1 = require("../realtime/realtime.service");
+exports.numberIdCodec = {
+    decode(raw) {
+        if (!/^[1-9]\d*$/.test(raw))
+            throw new Error(`Invalid numeric ID: ${raw}`);
+        return Number(raw);
+    },
+};
+exports.stringIdCodec = {
+    decode(raw) {
+        if (!raw.trim())
+            throw new Error('ID cannot be empty.');
+        return raw;
+    },
+};
+exports.uuidIdCodec = {
+    decode(raw) {
+        if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(raw)) {
+            throw new Error(`Invalid UUID: ${raw}`);
+        }
+        return raw;
+    },
+};
+/** Thin typed HTTP adapter. Events, auditing and realtime belong outside HTTP. */
 class BaseCrudController {
-    service;
-    constructor(service) {
-        this.service = service;
+    application;
+    idCodec;
+    constructor(application, idCodec = exports.numberIdCodec) {
+        this.application = application;
+        this.idCodec = idCodec;
     }
-    realtimeService;
-    async create(body) {
-        const result = await this.service.create(body);
-        if (this.realtimeService) {
-            const entityName = this.constructor.name.replace('Controller', '').replace('MsController', '').toLowerCase();
-            this.realtimeService.publishEntityChange(entityName, 'create', result, result.tenantId);
-        }
-        return result;
+    create(body) {
+        return this.application.create(body);
     }
-    async update(id, body) {
-        const result = await this.service.update(+id, body);
-        if (this.realtimeService) {
-            const entityName = this.constructor.name.replace('Controller', '').replace('MsController', '').toLowerCase();
-            this.realtimeService.publishEntityChange(entityName, 'update', result, result.tenantId);
-        }
-        return result;
+    update(rawId, body) {
+        return this.application.update(this.idCodec.decode(rawId), body);
     }
-    async findMany(filter) {
-        return await this.service.findMany(filter);
+    findMany(filter) {
+        return this.application.findMany(filter);
     }
-    async findById(id) {
-        return await this.service.findOne(+id);
+    async findById(rawId) {
+        const id = this.idCodec.decode(rawId);
+        const result = this.application.findOne
+            ? await this.application.findOne(id)
+            : await this.application.findById?.(id);
+        if (!result)
+            throw new common_1.NotFoundException(`Entity ${rawId} not found.`);
+        return result;
     }
-    async delete(id) {
-        await this.service.delete(+id);
-        if (this.realtimeService) {
-            const entityName = this.constructor.name.replace('Controller', '').replace('MsController', '').toLowerCase();
-            this.realtimeService.publishEntityChange(entityName, 'delete', { id: +id });
-        }
+    delete(rawId) {
+        return this.application.delete(this.idCodec.decode(rawId));
     }
 }
 exports.BaseCrudController = BaseCrudController;
-__decorate([
-    (0, common_1.Inject)(realtime_service_1.RealtimeService),
-    (0, common_1.Optional)(),
-    __metadata("design:type", realtime_service_1.RealtimeService)
-], BaseCrudController.prototype, "realtimeService", void 0);
 __decorate([
     (0, common_1.Post)(),
     (0, swagger_1.ApiOperation)({ summary: 'Create entity' }),
@@ -95,7 +105,7 @@ __decorate([
 ], BaseCrudController.prototype, "findById", null);
 __decorate([
     (0, common_1.Delete)(':id'),
-    (0, swagger_1.ApiOperation)({ summary: 'Delete entity' }),
+    (0, swagger_1.ApiOperation)({ summary: 'Soft delete entity' }),
     __param(0, (0, common_1.Param)('id')),
     __metadata("design:type", Function),
     __metadata("design:paramtypes", [String]),

package/dist/http/base-crud.controller.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/http/base-crud.controller.test.js

@@ -0,0 +1,18 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const strict_1 = __importDefault(require("node:assert/strict"));
+const node_test_1 = __importDefault(require("node:test"));
+const base_crud_controller_1 = require("./base-crud.controller");
+(0, node_test_1.default)('ID codecs preserve string and UUID identifiers', () => {
+    strict_1.default.equal(base_crud_controller_1.stringIdCodec.decode('external-001'), 'external-001');
+    strict_1.default.equal(base_crud_controller_1.uuidIdCodec.decode('550e8400-e29b-41d4-a716-446655440000'), '550e8400-e29b-41d4-a716-446655440000');
+    strict_1.default.equal(base_crud_controller_1.numberIdCodec.decode('42'), 42);
+});
+(0, node_test_1.default)('ID codecs reject malformed values', () => {
+    strict_1.default.throws(() => base_crud_controller_1.numberIdCodec.decode('12x'));
+    strict_1.default.throws(() => base_crud_controller_1.numberIdCodec.decode('0'));
+    strict_1.default.throws(() => base_crud_controller_1.uuidIdCodec.decode('not-a-uuid'));
+});

package/dist/http/module-http-proxy.d.ts

@@ -0,0 +1,16 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { TokenVerifier } from '../platform/security/token';
+export interface GatewayProxyRequest extends IncomingMessage {
+    originalUrl?: string;
+    protocol?: string;
+    user?: Record<string, unknown>;
+}
+export interface GatewayAuthenticationOptions {
+    publicPaths?: readonly string[];
+    requireActor?: boolean;
+    requireTenant?: boolean;
+}
+export declare function authenticateGatewayRequest(request: GatewayProxyRequest, verifier: TokenVerifier, options?: GatewayAuthenticationOptions): Promise<void>;
+export declare class ModuleHttpProxy {
+    forward(target: string, request: GatewayProxyRequest, response: ServerResponse): Promise<void>;
+}

package/dist/http/module-http-proxy.js

@@ -0,0 +1,160 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+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 __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ModuleHttpProxy = void 0;
+exports.authenticateGatewayRequest = authenticateGatewayRequest;
+const common_1 = require("@nestjs/common");
+const http = __importStar(require("node:http"));
+const https = __importStar(require("node:https"));
+const HOP_BY_HOP_HEADERS = new Set([
+    'connection',
+    'keep-alive',
+    'proxy-authenticate',
+    'proxy-authorization',
+    'te',
+    'trailer',
+    'transfer-encoding',
+    'upgrade',
+]);
+const UNTRUSTED_IDENTITY_HEADERS = new Set([
+    'x-actor-id',
+    'x-tenant-id',
+    'x-user-id',
+]);
+function requestPath(request) {
+    return request.originalUrl || request.url || '/';
+}
+function pathname(request) {
+    return new URL(requestPath(request), 'http://gateway.local').pathname;
+}
+function bearerToken(request) {
+    const authorization = request.headers.authorization;
+    if (!authorization)
+        return undefined;
+    const [scheme, token] = authorization.split(' ');
+    return scheme?.toLowerCase() === 'bearer' && token ? token : undefined;
+}
+async function authenticateGatewayRequest(request, verifier, options = {}) {
+    if (request.method?.toUpperCase() === 'OPTIONS')
+        return;
+    if (options.publicPaths?.includes(pathname(request)))
+        return;
+    const token = bearerToken(request);
+    if (!token)
+        throw new common_1.UnauthorizedException('Token not found');
+    try {
+        const claims = await verifier.verify(token);
+        const actor = claims.sub ?? claims['id'];
+        const tenant = claims['tenantId'];
+        if (options.requireActor !== false && actor === undefined) {
+            throw new Error('Token actor is required.');
+        }
+        if (options.requireTenant !== false && tenant === undefined) {
+            throw new Error('Token tenant is required.');
+        }
+        request.user = claims;
+    }
+    catch {
+        throw new common_1.UnauthorizedException('Invalid or expired token');
+    }
+}
+function forwardedHeaders(request, target) {
+    const headers = {};
+    for (const [name, value] of Object.entries(request.headers)) {
+        const normalizedName = name.toLowerCase();
+        if (!HOP_BY_HOP_HEADERS.has(normalizedName) && !UNTRUSTED_IDENTITY_HEADERS.has(normalizedName)) {
+            headers[name] = value;
+        }
+    }
+    const remoteAddress = request.socket.remoteAddress;
+    const existingForwardedFor = request.headers['x-forwarded-for'];
+    const forwardedFor = Array.isArray(existingForwardedFor)
+        ? existingForwardedFor.join(', ')
+        : existingForwardedFor;
+    if (remoteAddress)
+        headers['x-forwarded-for'] = forwardedFor ? `${forwardedFor}, ${remoteAddress}` : remoteAddress;
+    headers['x-forwarded-host'] = request.headers.host;
+    headers['x-forwarded-proto'] = request.protocol || 'http';
+    headers.host = target.host;
+    return headers;
+}
+let ModuleHttpProxy = class ModuleHttpProxy {
+    forward(target, request, response) {
+        const targetUrl = new URL(target);
+        const transport = targetUrl.protocol === 'https:' ? https : http;
+        return new Promise((resolve, reject) => {
+            const proxyRequest = transport.request({
+                protocol: targetUrl.protocol,
+                hostname: targetUrl.hostname,
+                port: targetUrl.port,
+                method: request.method,
+                path: requestPath(request),
+                headers: forwardedHeaders(request, targetUrl),
+            }, (proxyResponse) => {
+                response.statusCode = proxyResponse.statusCode ?? 502;
+                for (const [name, value] of Object.entries(proxyResponse.headers)) {
+                    if (value !== undefined && !HOP_BY_HOP_HEADERS.has(name.toLowerCase()))
+                        response.setHeader(name, value);
+                }
+                proxyResponse.once('end', resolve);
+                proxyResponse.once('error', reject);
+                proxyResponse.pipe(response);
+            });
+            proxyRequest.once('error', () => {
+                if (!response.headersSent) {
+                    response.statusCode = 502;
+                    response.setHeader('content-type', 'application/json; charset=utf-8');
+                    response.end(JSON.stringify({ statusCode: 502, message: 'Upstream service unavailable' }));
+                }
+                else {
+                    response.end();
+                }
+                resolve();
+            });
+            request.once('aborted', () => proxyRequest.destroy());
+            request.pipe(proxyRequest);
+        });
+    }
+};
+exports.ModuleHttpProxy = ModuleHttpProxy;
+exports.ModuleHttpProxy = ModuleHttpProxy = __decorate([
+    (0, common_1.Injectable)()
+], ModuleHttpProxy);

package/dist/http/module-http-proxy.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/http/module-http-proxy.test.js

@@ -0,0 +1,37 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const strict_1 = __importDefault(require("node:assert/strict"));
+const node_test_1 = __importDefault(require("node:test"));
+const common_1 = require("@nestjs/common");
+const module_http_proxy_1 = require("./module-http-proxy");
+function request(path, authorization) {
+    return {
+        method: 'GET',
+        url: path,
+        originalUrl: path,
+        headers: authorization ? { authorization } : {},
+    };
+}
+(0, node_test_1.default)('gateway authentication skips only explicitly public paths', async () => {
+    let calls = 0;
+    const verifier = { verify: async () => { calls += 1; return { sub: '1', tenantId: 'tenant-a' }; } };
+    await (0, module_http_proxy_1.authenticateGatewayRequest)(request('/api/core/auth/login'), verifier, {
+        publicPaths: ['/api/core/auth/login'],
+    });
+    strict_1.default.equal(calls, 0);
+});
+(0, node_test_1.default)('gateway authentication validates stateless actor and tenant claims', async () => {
+    const verifier = { verify: async () => ({ sub: '7', tenantId: 'tenant-a' }) };
+    const incoming = request('/api/catalog/product', 'Bearer valid-token');
+    await (0, module_http_proxy_1.authenticateGatewayRequest)(incoming, verifier);
+    strict_1.default.equal(incoming.user?.sub, '7');
+    strict_1.default.equal(incoming.user?.tenantId, 'tenant-a');
+});
+(0, node_test_1.default)('gateway authentication rejects missing or incomplete tokens', async () => {
+    const verifier = { verify: async () => ({ sub: '7' }) };
+    await strict_1.default.rejects(() => (0, module_http_proxy_1.authenticateGatewayRequest)(request('/api/orders/order'), verifier), common_1.UnauthorizedException);
+    await strict_1.default.rejects(() => (0, module_http_proxy_1.authenticateGatewayRequest)(request('/api/orders/order', 'Bearer incomplete'), verifier), common_1.UnauthorizedException);
+});

package/dist/index.d.ts

@@ -1,8 +1,16 @@
 export * from './database/factory-where';
 export * from './database/base.repository';
 export * from './database/typeorm-query.builder';
+export * from './database/typeorm-unit-of-work';
+export * from './database/typeorm-sql';
+export * from './database/typeorm-reader';
+export * from './database/typeorm-explain';
 export * from './http/base-crud.controller';
+export * from './http/module-http-proxy';
 export * from './storage';
 export * from './auth';
 export * from './realtime';
 export * from './audit';
+export * from './context';
+export * from './application';
+export * from './platform';

package/dist/index.js

@@ -17,8 +17,16 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./database/factory-where"), exports);
 __exportStar(require("./database/base.repository"), exports);
 __exportStar(require("./database/typeorm-query.builder"), exports);
+__exportStar(require("./database/typeorm-unit-of-work"), exports);
+__exportStar(require("./database/typeorm-sql"), exports);
+__exportStar(require("./database/typeorm-reader"), exports);
+__exportStar(require("./database/typeorm-explain"), exports);
 __exportStar(require("./http/base-crud.controller"), exports);
+__exportStar(require("./http/module-http-proxy"), exports);
 __exportStar(require("./storage"), exports);
 __exportStar(require("./auth"), exports);
 __exportStar(require("./realtime"), exports);
 __exportStar(require("./audit"), exports);
+__exportStar(require("./context"), exports);
+__exportStar(require("./application"), exports);
+__exportStar(require("./platform"), exports);

package/dist/platform/index.d.ts

@@ -0,0 +1,3 @@
+export * from './security';
+export * from './messaging';
+export * from './integrations';

package/dist/platform/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./security"), exports);
+__exportStar(require("./messaging"), exports);
+__exportStar(require("./integrations"), exports);

package/dist/platform/integrations/company-registry.d.ts

@@ -0,0 +1,16 @@
+import type { ExternalRequestContext } from './external-http';
+export interface RegisteredCompany {
+    registrationNumber: string;
+    legalName: string;
+    tradeName?: string;
+    status: 'active' | 'inactive' | 'unknown';
+    address?: {
+        city?: string;
+        region?: string;
+        postalCode?: string;
+    };
+}
+/** Capability contract: vendor DTOs remain inside their concrete adapter. */
+export interface CompanyRegistryGateway {
+    findByRegistrationNumber(registrationNumber: string, context: ExternalRequestContext): Promise<RegisteredCompany | null>;
+}

package/dist/platform/integrations/company-registry.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/platform/integrations/external-http.d.ts

@@ -0,0 +1,38 @@
+export interface ExternalRequestContext {
+    correlationId: string;
+    tenantId?: string;
+}
+export interface ExternalHttpPolicy {
+    timeoutMs: number;
+    maxAttempts: number;
+    retryDelayMs: number;
+}
+export interface ExternalMetricSink {
+    record(capability: string, outcome: 'success' | 'failure', durationMs: number): void;
+}
+export interface ExternalLogEntry {
+    capability: string;
+    correlationId: string;
+    attempt: number;
+    outcome: 'success' | 'retry' | 'failure';
+    durationMs: number;
+}
+export interface ExternalLogSink {
+    /** URL, headers, body, credentials and provider DTOs are deliberately absent. */
+    record(entry: ExternalLogEntry): void;
+}
+export declare class ExternalCapabilityError extends Error {
+    readonly capability: string;
+    readonly cause?: unknown | undefined;
+    constructor(capability: string, cause?: unknown | undefined);
+}
+export declare class ExternalHttpClient {
+    private readonly policy;
+    private readonly metrics?;
+    private readonly fetcher;
+    private readonly logs?;
+    constructor(policy?: ExternalHttpPolicy, metrics?: ExternalMetricSink | undefined, fetcher?: typeof fetch, logs?: ExternalLogSink | undefined);
+    json<Response>(capability: string, url: string, init: RequestInit, context: ExternalRequestContext): Promise<Response>;
+    private recordMetric;
+    private recordLog;
+}

package/dist/platform/integrations/external-http.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExternalHttpClient = exports.ExternalCapabilityError = void 0;
+class ExternalCapabilityError extends Error {
+    capability;
+    cause;
+    constructor(capability, cause) {
+        super(`${capability} is temporarily unavailable.`);
+        this.capability = capability;
+        this.cause = cause;
+        this.name = 'ExternalCapabilityError';
+    }
+}
+exports.ExternalCapabilityError = ExternalCapabilityError;
+class ExternalHttpClient {
+    policy;
+    metrics;
+    fetcher;
+    logs;
+    constructor(policy = { timeoutMs: 5_000, maxAttempts: 2, retryDelayMs: 100 }, metrics, fetcher = fetch, logs) {
+        this.policy = policy;
+        this.metrics = metrics;
+        this.fetcher = fetcher;
+        this.logs = logs;
+    }
+    async json(capability, url, init, context) {
+        const startedAt = Date.now();
+        let lastError;
+        for (let attempt = 1; attempt <= this.policy.maxAttempts; attempt += 1) {
+            try {
+                const response = await this.fetcher(url, {
+                    ...init,
+                    signal: AbortSignal.timeout(this.policy.timeoutMs),
+                    headers: { ...init.headers, 'x-correlation-id': context.correlationId },
+                });
+                if (!response.ok)
+                    throw new Error(`External HTTP ${response.status}`);
+                this.recordLog({
+                    capability, correlationId: context.correlationId, attempt,
+                    outcome: 'success', durationMs: Date.now() - startedAt,
+                });
+                this.recordMetric(capability, 'success', Date.now() - startedAt);
+                return await response.json();
+            }
+            catch (error) {
+                lastError = error;
+                if (attempt < this.policy.maxAttempts) {
+                    this.recordLog({
+                        capability, correlationId: context.correlationId, attempt,
+                        outcome: 'retry', durationMs: Date.now() - startedAt,
+                    });
+                    await new Promise((resolve) => setTimeout(resolve, this.policy.retryDelayMs * attempt));
+                }
+                else {
+                    this.recordLog({
+                        capability, correlationId: context.correlationId, attempt,
+                        outcome: 'failure', durationMs: Date.now() - startedAt,
+                    });
+                }
+            }
+        }
+        this.recordMetric(capability, 'failure', Date.now() - startedAt);
+        throw new ExternalCapabilityError(capability, lastError);
+    }
+    recordMetric(capability, outcome, durationMs) {
+        try {
+            this.metrics?.record(capability, outcome, durationMs);
+        }
+        catch { /* telemetry is non-critical */ }
+    }
+    recordLog(entry) {
+        try {
+            this.logs?.record(entry);
+        }
+        catch { /* telemetry is non-critical */ }
+    }
+}
+exports.ExternalHttpClient = ExternalHttpClient;