nestjs-apcore 0.1.0

package/README.md

@@ -0,0 +1,304 @@
+# nestjs-apcore
+
+NestJS adapter for the [apcore](https://github.com/aipartnerup/apcore-js) AI-Perceivable module ecosystem. Turn your existing NestJS services into AI-callable [MCP](https://modelcontextprotocol.io/) tools and OpenAI-compatible function definitions — with zero changes to your business logic.
+
+## Features
+
+- **Decorator-driven** — Mark methods with `@ApTool` and classes with `@ApModule` to expose them as AI tools
+- **Auto-discovery** — `ApToolScannerService` scans all providers at startup and registers decorated methods automatically
+- **Multi-schema support** — TypeBox, Zod, class-validator DTOs, and plain JSON Schema, auto-detected via a priority chain
+- **MCP server built-in** — Serve tools over stdio, Streamable HTTP, or SSE transports with optional Tool Explorer UI
+- **OpenAI-compatible** — Convert registered tools to OpenAI function-calling format with `toOpenaiTools()`
+- **YAML bindings** — Register tools declaratively from YAML files without touching source code
+- **Dual access** — Services remain injectable into REST controllers while simultaneously available as MCP tools
+
+## Installation
+
+```bash
+npm install nestjs-apcore apcore-js apcore-mcp @modelcontextprotocol/sdk js-yaml
+```
+
+**Peer dependencies** (required):
+
+```bash
+npm install @nestjs/common @nestjs/core reflect-metadata rxjs
+```
+
+**Optional** (for schema adapters):
+
+```bash
+npm install zod                                # ZodAdapter
+npm install class-validator class-transformer  # DtoAdapter
+npm install @sinclair/typebox                  # TypeBoxAdapter (recommended)
+```
+
+**Requirements:** Node.js >= 18, NestJS >= 10
+
+## Quick Start
+
+### 1. Wire up modules
+
+```typescript
+// app.module.ts
+import { Module } from '@nestjs/common';
+import { ApcoreModule, ApcoreMcpModule, ApToolScannerService } from 'nestjs-apcore';
+
+@Module({
+  imports: [
+    ApcoreModule.forRoot({}),
+    ApcoreMcpModule.forRoot({
+      transport: 'streamable-http',
+      port: 8000,
+      name: 'my-app',
+      version: '1.0.0',
+      explorer: true,
+    }),
+    TodoModule,
+  ],
+  providers: [ApToolScannerService],
+})
+export class AppModule {}
+```
+
+### 2. Decorate your services
+
+```typescript
+// todo.service.ts
+import { Injectable } from '@nestjs/common';
+import { Type } from '@sinclair/typebox';
+import { ApModule, ApTool } from 'nestjs-apcore';
+
+@ApModule({ namespace: 'todo', description: 'Todo list management' })
+@Injectable()
+export class TodoService {
+  private todos = [];
+
+  @ApTool({
+    description: 'List all todos, optionally filtered by status',
+    inputSchema: Type.Object({
+      done: Type.Optional(Type.Boolean()),
+    }),
+    annotations: { readonly: true, idempotent: true },
+    tags: ['todo', 'query'],
+  })
+  list(inputs: Record<string, unknown>) {
+    const { done } = inputs;
+    const filtered = done !== undefined
+      ? this.todos.filter((t) => t.done === done)
+      : this.todos;
+    return { todos: filtered, count: filtered.length };
+  }
+
+  @ApTool({
+    description: 'Create a new todo item',
+    inputSchema: Type.Object({
+      title: Type.String(),
+    }),
+    annotations: { readonly: false },
+    tags: ['todo', 'mutate'],
+  })
+  create(inputs: Record<string, unknown>) {
+    const todo = { id: this.todos.length + 1, title: inputs.title, done: false };
+    this.todos.push(todo);
+    return todo;
+  }
+}
+```
+
+### 3. Boot the app
+
+```typescript
+// main.ts
+import { NestFactory } from '@nestjs/core';
+import { AppModule } from './app.module';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+  await app.listen(3000);
+  // MCP server starts automatically on port 8000
+}
+bootstrap();
+```
+
+Your service is now available as:
+- **REST API** at `http://localhost:3000` (via NestJS controllers)
+- **MCP server** at `http://localhost:8000` (for AI agents)
+- **Tool Explorer** at `http://localhost:8000/explorer/` (interactive web UI)
+
+## API Reference
+
+### Modules
+
+#### `ApcoreModule`
+
+Provides the core `Registry` and `Executor` as NestJS singletons.
+
+```typescript
+// Sync
+ApcoreModule.forRoot({ extensionsDir?, acl?, middleware?, bindings? })
+
+// Async (e.g. inject ConfigService)
+ApcoreModule.forRootAsync({ imports, useFactory, inject })
+```
+
+#### `ApcoreMcpModule`
+
+Configures and starts the MCP server.
+
+The MCP server runs **standalone on its own port** (e.g. 8000), separate from NestJS's REST server (e.g. 3000). Both share the same Registry and Executor instances.
+
+```typescript
+ApcoreMcpModule.forRoot({
+  transport: 'stdio' | 'streamable-http' | 'sse',
+  host?: string,
+  port?: number,
+  name?: string,
+  version?: string,
+  tags?: string[],          // only expose tools matching these tags
+  prefix?: string,          // only expose tools with this ID prefix
+  explorer?: boolean,       // enable Tool Explorer web UI
+  explorerPrefix?: string,  // URL prefix for the Explorer
+  allowExecute?: boolean,   // allow execution from Explorer
+  dynamic?: boolean,        // enable dynamic tool list updates
+  validateInputs?: boolean,
+  logLevel?: 'DEBUG' | 'INFO' | 'WARNING' | 'ERROR' | 'CRITICAL',
+  authenticator?: Authenticator,   // JWT or custom auth
+  exemptPaths?: string[],          // paths that bypass auth (default: ['/health', '/metrics'])
+  metricsCollector?: { exportPrometheus(): string },
+  onStartup?: () => void | Promise<void>,
+  onShutdown?: () => void | Promise<void>,
+})
+```
+
+### Decorators
+
+| Decorator | Target | Description |
+|---|---|---|
+| `@ApModule(opts)` | Class | Sets namespace for all `@ApTool` methods (e.g. `todo`) |
+| `@ApTool(opts)` | Method | Registers the method as an AI-callable tool |
+| `@ApContext()` | Parameter | Injects the apcore `Context` object (callerId, trace info) |
+
+#### `@ApTool` options
+
+```typescript
+@ApTool({
+  description: string,        // required
+  id?: string,                 // auto-generated in snake_case if omitted (e.g. 'email.send_batch')
+  inputSchema?: any,           // TypeBox, Zod, DTO class, or JSON Schema
+  outputSchema?: any,
+  annotations?: {
+    readonly?: boolean,
+    destructive?: boolean,
+    idempotent?: boolean,
+    requiresApproval?: boolean,
+    openWorld?: boolean,
+    streaming?: boolean,
+  },
+  tags?: string[],
+  documentation?: string,
+  examples?: ApToolExample[],
+})
+```
+
+### Services
+
+| Service | Description |
+|---|---|
+| `ApcoreRegistryService` | Register/unregister tools, query the registry |
+| `ApcoreExecutorService` | Execute tools: `call()`, `stream()`, `validate()` |
+| `ApcoreMcpService` | MCP server lifecycle: `start()`, `stop()`, `restart()`, `toOpenaiTools()` |
+| `ApToolScannerService` | Auto-discovers and registers `@ApTool` decorated methods at startup |
+
+### Schema Adapters
+
+Schemas are auto-detected and converted via a priority chain:
+
+| Adapter | Priority | Input |
+|---|---|---|
+| TypeBoxAdapter | 100 | `@sinclair/typebox` schemas |
+| ZodAdapter | 50 | Zod schemas |
+| JsonSchemaAdapter | 30 | Plain JSON Schema objects |
+| DtoAdapter | 20 | `class-validator` decorated DTO classes |
+
+### YAML Bindings
+
+Register tools without decorators:
+
+```yaml
+bindings:
+  - module_id: email.send
+    target: EmailService.send
+    description: Send an email
+    input_schema:
+      type: object
+      properties:
+        to: { type: string }
+        subject: { type: string }
+        body: { type: string }
+    tags: [email, mutate]
+    annotations:
+      readonly: false
+```
+
+### JWT Authentication
+
+Enable JWT auth by passing a `JWTAuthenticator` to `ApcoreMcpModule`. The Explorer UI and `/health` endpoint are always exempt.
+
+```typescript
+import { JWTAuthenticator, getCurrentIdentity } from 'nestjs-apcore';
+
+// In app.module.ts
+const jwtSecret = process.env.JWT_SECRET;
+ApcoreMcpModule.forRoot({
+  transport: 'streamable-http',
+  port: 8000,
+  authenticator: jwtSecret ? new JWTAuthenticator({ secret: jwtSecret }) : undefined,
+})
+
+// Inside any @ApTool method
+list(inputs: Record<string, unknown>) {
+  const caller = getCurrentIdentity()?.id ?? 'anonymous';
+  return { items: [...], caller };
+}
+```
+
+`JWTAuthenticator` options: `secret`, `algorithms` (default `['HS256']`), `audience`, `issuer`, `claimMapping`, `requireClaims`, `requireAuth` (default `true`).
+
+### Re-exported Utilities
+
+From `apcore-mcp`:
+- `reportProgress`, `elicit`, `createBridgeContext`
+- `JWTAuthenticator`, `getCurrentIdentity`, `identityStorage`
+
+## Examples
+
+The `demo/` directory contains a full working app with Todo and Weather services:
+
+```bash
+cd demo
+npm install
+npx tsx src/main.ts
+```
+
+Or with Docker:
+
+```bash
+cd demo
+docker compose up --build
+```
+
+## Scripts
+
+| Command | Description |
+|---|---|
+| `npm run build` | Compile TypeScript |
+| `npm run dev` | Watch mode compilation |
+| `npm test` | Run tests (vitest) |
+| `npm run test:watch` | Run tests in watch mode |
+| `npm run test:coverage` | Run tests with coverage |
+| `npm run typecheck` | Type-check without emitting |
+| `npm run lint` | Lint source and tests |
+
+## License
+
+Apache-2.0

package/dist/bridge/binding-loader.d.ts

@@ -0,0 +1,33 @@
+import { ApcoreRegistryService } from '../core/apcore-registry.service.js';
+/**
+ * A function that resolves a class name to a service instance.
+ */
+export type InstanceProvider = (className: string) => object | undefined;
+/**
+ * NestJS injectable service that loads YAML binding files and registers
+ * modules with the ApcoreRegistryService.
+ *
+ * Each binding maps a module_id to a "ClassName.methodName" target,
+ * optionally providing schema, annotations, tags, and documentation.
+ */
+export declare class ApBindingLoader {
+    private readonly registry;
+    private readonly instanceProvider?;
+    constructor(registry: ApcoreRegistryService, instanceProvider?: InstanceProvider | undefined);
+    /**
+     * Parse YAML content describing bindings and register each as a
+     * FunctionModule with the registry.
+     *
+     * @param content - Raw YAML string
+     * @returns Array of registered module IDs
+     */
+    loadFromString(content: string): string[];
+    /**
+     * Read a YAML file from disk and register its bindings.
+     *
+     * @param filePath - Absolute or relative path to the YAML file
+     * @returns Array of registered module IDs
+     */
+    loadFromFile(filePath: string): Promise<string[]>;
+}
+//# sourceMappingURL=binding-loader.d.ts.map

package/dist/bridge/binding-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"binding-loader.d.ts","sourceRoot":"","sources":["../../src/bridge/binding-loader.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAuB3E;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;AAmBzE;;;;;;GAMG;AACH,qBACa,eAAe;IAGxB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAGzB,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAC;gBAHjB,QAAQ,EAAE,qBAAqB,EAG/B,gBAAgB,CAAC,EAAE,gBAAgB,YAAA;IAGtD;;;;;;OAMG;IACH,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE;IAkDzC;;;;;OAKG;IACG,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;CAIxD"}

package/dist/bridge/binding-loader.js

@@ -0,0 +1,118 @@
+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 __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Injectable, Inject, Optional } from '@nestjs/common';
+import * as yaml from 'js-yaml';
+import { readFile } from 'node:fs/promises';
+import { Type as t } from '@sinclair/typebox';
+import { FunctionModule } from 'apcore-js';
+import { ApcoreRegistryService } from '../core/apcore-registry.service.js';
+/**
+ * Normalize a method return value to a Record<string, unknown>.
+ *
+ * - null / undefined -> {}
+ * - non-object (string, number, boolean) or array -> { result: value }
+ * - object -> returned as-is
+ */
+function normalizeReturnValue(value) {
+    if (value == null) {
+        return {};
+    }
+    if (typeof value !== 'object' || Array.isArray(value)) {
+        return { result: value };
+    }
+    return value;
+}
+/**
+ * NestJS injectable service that loads YAML binding files and registers
+ * modules with the ApcoreRegistryService.
+ *
+ * Each binding maps a module_id to a "ClassName.methodName" target,
+ * optionally providing schema, annotations, tags, and documentation.
+ */
+let ApBindingLoader = class ApBindingLoader {
+    registry;
+    instanceProvider;
+    constructor(registry, instanceProvider) {
+        this.registry = registry;
+        this.instanceProvider = instanceProvider;
+    }
+    /**
+     * Parse YAML content describing bindings and register each as a
+     * FunctionModule with the registry.
+     *
+     * @param content - Raw YAML string
+     * @returns Array of registered module IDs
+     */
+    loadFromString(content) {
+        const parsed = yaml.load(content);
+        const bindings = parsed?.bindings ?? [];
+        const ids = [];
+        for (const binding of bindings) {
+            const moduleId = binding.module_id;
+            const [className, methodName] = binding.target.split('.');
+            // Attempt to resolve the service instance
+            let instance;
+            if (this.instanceProvider) {
+                instance = this.instanceProvider(className);
+            }
+            // Build the execute function
+            let execute;
+            if (instance && methodName in instance) {
+                execute = async (inputs) => {
+                    const raw = await instance[methodName](inputs);
+                    return normalizeReturnValue(raw);
+                };
+            }
+            else {
+                execute = async () => {
+                    return {
+                        error: `No instance available for ${className}.${methodName}`,
+                    };
+                };
+            }
+            const funcModule = new FunctionModule({
+                moduleId,
+                description: binding.description,
+                inputSchema: binding.input_schema ?? t.Object({}),
+                outputSchema: binding.output_schema ?? t.Object({}),
+                tags: binding.tags ?? null,
+                annotations: binding.annotations ?? null,
+                documentation: binding.documentation ?? null,
+                examples: null,
+                execute,
+            });
+            this.registry.register(moduleId, funcModule);
+            ids.push(moduleId);
+        }
+        return ids;
+    }
+    /**
+     * Read a YAML file from disk and register its bindings.
+     *
+     * @param filePath - Absolute or relative path to the YAML file
+     * @returns Array of registered module IDs
+     */
+    async loadFromFile(filePath) {
+        const content = await readFile(filePath, 'utf-8');
+        return this.loadFromString(content);
+    }
+};
+ApBindingLoader = __decorate([
+    Injectable(),
+    __param(0, Inject(ApcoreRegistryService)),
+    __param(1, Optional()),
+    __param(1, Inject('APCORE_INSTANCE_PROVIDER')),
+    __metadata("design:paramtypes", [ApcoreRegistryService, Function])
+], ApBindingLoader);
+export { ApBindingLoader };
+//# sourceMappingURL=binding-loader.js.map

package/dist/bridge/binding-loader.js.map

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

package/dist/bridge/index.d.ts

@@ -0,0 +1,3 @@
+export { ApBindingLoader } from './binding-loader.js';
+export type { InstanceProvider } from './binding-loader.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/bridge/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,YAAY,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/bridge/index.js

@@ -0,0 +1,2 @@
+export { ApBindingLoader } from './binding-loader.js';
+//# sourceMappingURL=index.js.map

package/dist/bridge/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/bridge/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/constants.d.ts

@@ -0,0 +1,6 @@
+export declare const APCORE_MODULE_OPTIONS: "APCORE_MODULE_OPTIONS";
+export declare const APCORE_MCP_MODULE_OPTIONS: "APCORE_MCP_MODULE_OPTIONS";
+export declare const AP_TOOL_METADATA_KEY: "apcore:tool";
+export declare const AP_MODULE_METADATA_KEY: "apcore:module";
+export declare const AP_CONTEXT_METADATA_KEY: "apcore:context";
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,qBAAqB,EAAG,uBAAgC,CAAC;AACtE,eAAO,MAAM,yBAAyB,EAAG,2BAAoC,CAAC;AAG9E,eAAO,MAAM,oBAAoB,EAAG,aAAsB,CAAC;AAC3D,eAAO,MAAM,sBAAsB,EAAG,eAAwB,CAAC;AAC/D,eAAO,MAAM,uBAAuB,EAAG,gBAAyB,CAAC"}

package/dist/constants.js

@@ -0,0 +1,8 @@
+// NestJS dependency-injection tokens
+export const APCORE_MODULE_OPTIONS = 'APCORE_MODULE_OPTIONS';
+export const APCORE_MCP_MODULE_OPTIONS = 'APCORE_MCP_MODULE_OPTIONS';
+// Reflect metadata keys used by decorators
+export const AP_TOOL_METADATA_KEY = 'apcore:tool';
+export const AP_MODULE_METADATA_KEY = 'apcore:module';
+export const AP_CONTEXT_METADATA_KEY = 'apcore:context';
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,qCAAqC;AACrC,MAAM,CAAC,MAAM,qBAAqB,GAAG,uBAAgC,CAAC;AACtE,MAAM,CAAC,MAAM,yBAAyB,GAAG,2BAAoC,CAAC;AAE9E,2CAA2C;AAC3C,MAAM,CAAC,MAAM,oBAAoB,GAAG,aAAsB,CAAC;AAC3D,MAAM,CAAC,MAAM,sBAAsB,GAAG,eAAwB,CAAC;AAC/D,MAAM,CAAC,MAAM,uBAAuB,GAAG,gBAAyB,CAAC"}

package/dist/core/apcore-executor.service.d.ts

@@ -0,0 +1,42 @@
+import type { Executor } from 'apcore-js';
+import type { Context, ValidationResult } from 'apcore-js';
+/**
+ * NestJS-injectable wrapper around the upstream apcore-js {@link Executor}.
+ *
+ * All mutation-free delegation methods normalise `null` / `undefined` inputs
+ * to an empty object (`{}`) so callers never need to worry about nullability.
+ */
+export declare class ApcoreExecutorService {
+    private readonly executor;
+    constructor(executor: Executor);
+    /** Access the underlying apcore-js Executor directly. */
+    get raw(): Executor;
+    /**
+     * Execute a module by ID.
+     *
+     * @param moduleId  Fully-qualified module identifier (e.g. `"email.send"`).
+     * @param inputs    Key/value inputs for the module.  `null` and `undefined`
+     *                  are normalised to `{}`.
+     * @param context   Optional execution context (identity, trace, etc.).
+     */
+    call(moduleId: string, inputs?: Record<string, unknown> | null, context?: Context | null): Promise<Record<string, unknown>>;
+    /**
+     * Stream execution results from a module.
+     *
+     * Yields each chunk produced by the upstream `executor.stream()` generator.
+     *
+     * @param moduleId  Fully-qualified module identifier.
+     * @param inputs    Key/value inputs for the module.  `null` and `undefined`
+     *                  are normalised to `{}`.
+     * @param context   Optional execution context.
+     */
+    stream(moduleId: string, inputs?: Record<string, unknown> | null, context?: Context | null): AsyncGenerator<Record<string, unknown>>;
+    /**
+     * Validate inputs against a module's input schema without executing it.
+     *
+     * @param moduleId  Fully-qualified module identifier.
+     * @param inputs    Key/value inputs to validate.
+     */
+    validate(moduleId: string, inputs: Record<string, unknown>): ValidationResult;
+}
+//# sourceMappingURL=apcore-executor.service.d.ts.map

package/dist/core/apcore-executor.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apcore-executor.service.d.ts","sourceRoot":"","sources":["../../src/core/apcore-executor.service.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,KAAK,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAE3D;;;;;GAKG;AACH,qBACa,qBAAqB;IACpB,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAAR,QAAQ,EAAE,QAAQ;IAM/C,yDAAyD;IACzD,IAAI,GAAG,IAAI,QAAQ,CAElB;IAED;;;;;;;OAOG;IACG,IAAI,CACR,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,EACvC,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,GACvB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAInC;;;;;;;;;OASG;IACI,MAAM,CACX,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,EACvC,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,GACvB,cAAc,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAI1C;;;;;OAKG;IACH,QAAQ,CACN,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,gBAAgB;CAGpB"}

package/dist/core/apcore-executor.service.js

@@ -0,0 +1,68 @@
+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 __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import { Injectable } from '@nestjs/common';
+/**
+ * NestJS-injectable wrapper around the upstream apcore-js {@link Executor}.
+ *
+ * All mutation-free delegation methods normalise `null` / `undefined` inputs
+ * to an empty object (`{}`) so callers never need to worry about nullability.
+ */
+let ApcoreExecutorService = class ApcoreExecutorService {
+    executor;
+    constructor(executor) {
+        this.executor = executor;
+    }
+    // -----------------------------------------------------------------------
+    // Public API
+    // -----------------------------------------------------------------------
+    /** Access the underlying apcore-js Executor directly. */
+    get raw() {
+        return this.executor;
+    }
+    /**
+     * Execute a module by ID.
+     *
+     * @param moduleId  Fully-qualified module identifier (e.g. `"email.send"`).
+     * @param inputs    Key/value inputs for the module.  `null` and `undefined`
+     *                  are normalised to `{}`.
+     * @param context   Optional execution context (identity, trace, etc.).
+     */
+    async call(moduleId, inputs, context) {
+        return this.executor.call(moduleId, inputs ?? {}, context);
+    }
+    /**
+     * Stream execution results from a module.
+     *
+     * Yields each chunk produced by the upstream `executor.stream()` generator.
+     *
+     * @param moduleId  Fully-qualified module identifier.
+     * @param inputs    Key/value inputs for the module.  `null` and `undefined`
+     *                  are normalised to `{}`.
+     * @param context   Optional execution context.
+     */
+    async *stream(moduleId, inputs, context) {
+        yield* this.executor.stream(moduleId, inputs ?? {}, context);
+    }
+    /**
+     * Validate inputs against a module's input schema without executing it.
+     *
+     * @param moduleId  Fully-qualified module identifier.
+     * @param inputs    Key/value inputs to validate.
+     */
+    validate(moduleId, inputs) {
+        return this.executor.validate(moduleId, inputs);
+    }
+};
+ApcoreExecutorService = __decorate([
+    Injectable(),
+    __metadata("design:paramtypes", [Function])
+], ApcoreExecutorService);
+export { ApcoreExecutorService };
+//# sourceMappingURL=apcore-executor.service.js.map

package/dist/core/apcore-executor.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apcore-executor.service.js","sourceRoot":"","sources":["../../src/core/apcore-executor.service.ts"],"names":[],"mappings":";;;;;;;;;AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAI5C;;;;;GAKG;AAEI,IAAM,qBAAqB,GAA3B,MAAM,qBAAqB;IACH;IAA7B,YAA6B,QAAkB;QAAlB,aAAQ,GAAR,QAAQ,CAAU;IAAG,CAAC;IAEnD,0EAA0E;IAC1E,aAAa;IACb,0EAA0E;IAE1E,yDAAyD;IACzD,IAAI,GAAG;QACL,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,IAAI,CACR,QAAgB,EAChB,MAAuC,EACvC,OAAwB;QAExB,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,EAAE,OAAO,CAAC,CAAC;IAC7D,CAAC;IAED;;;;;;;;;OASG;IACH,KAAK,CAAC,CAAC,MAAM,CACX,QAAgB,EAChB,MAAuC,EACvC,OAAwB;QAExB,KAAK,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,EAAE,OAAO,CAAC,CAAC;IAC/D,CAAC;IAED;;;;;OAKG;IACH,QAAQ,CACN,QAAgB,EAChB,MAA+B;QAE/B,OAAO,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAClD,CAAC;CACF,CAAA;AA1DY,qBAAqB;IADjC,UAAU,EAAE;;GACA,qBAAqB,CA0DjC"}