nestjs-apcore 0.1.0

package/dist/schema/schema-extractor.service.d.ts

@@ -0,0 +1,58 @@
+import type { TSchema } from '@sinclair/typebox';
+import type { SchemaAdapter } from './adapters/schema-adapter.interface.js';
+/**
+ * Thrown when no registered adapter is able to handle the provided input.
+ */
+export declare class SchemaExtractionError extends Error {
+    readonly name = "SchemaExtractionError";
+    constructor(message: string);
+}
+/**
+ * Orchestrator service that delegates schema detection, extraction, and
+ * JSON Schema conversion to a prioritised chain of {@link SchemaAdapter}s.
+ *
+ * Built-in adapters (tried in descending priority order):
+ *
+ * | Adapter            | Priority |
+ * |--------------------|----------|
+ * | TypeBoxAdapter     | 100      |
+ * | ZodAdapter         | 50       |
+ * | JsonSchemaAdapter  | 30       |
+ * | DtoAdapter         | 20       |
+ *
+ * Custom adapters can be added via {@link registerAdapter} and will be
+ * inserted into the chain according to their priority value (highest first).
+ */
+export declare class SchemaExtractor {
+    private adapters;
+    constructor();
+    /**
+     * Register a custom adapter and re-sort the adapter chain by priority
+     * (highest first).
+     */
+    registerAdapter(adapter: SchemaAdapter): void;
+    /**
+     * Returns the name of the first adapter whose `detect()` returns `true`
+     * for the given input, or `null` if no adapter matches.
+     */
+    detect(input: unknown): string | null;
+    /**
+     * Extracts a TypeBox-compatible `TSchema` from the given input using the
+     * first matching adapter.
+     *
+     * @throws {SchemaExtractionError} If no adapter can handle the input.
+     */
+    extract(input: unknown): TSchema;
+    /**
+     * Extracts a plain JSON Schema object from the given input using the
+     * first matching adapter.
+     *
+     * @throws {SchemaExtractionError} If no adapter can handle the input.
+     */
+    extractJsonSchema(input: unknown): Record<string, unknown>;
+    /**
+     * Sort adapters in descending priority order (highest priority first).
+     */
+    private sortAdapters;
+}
+//# sourceMappingURL=schema-extractor.service.d.ts.map

package/dist/schema/schema-extractor.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-extractor.service.d.ts","sourceRoot":"","sources":["../../src/schema/schema-extractor.service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wCAAwC,CAAC;AAM5E;;GAEG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,SAAkB,IAAI,2BAA2B;gBAErC,OAAO,EAAE,MAAM;CAK5B;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAkB;;IAYlC;;;OAGG;IACH,eAAe,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI;IAK7C;;;OAGG;IACH,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI;IASrC;;;;;OAKG;IACH,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO;IAYhC;;;;;OAKG;IACH,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAY1D;;OAEG;IACH,OAAO,CAAC,YAAY;CAGrB"}

package/dist/schema/schema-extractor.service.js

@@ -0,0 +1,100 @@
+import { TypeBoxAdapter } from './adapters/typebox.adapter.js';
+import { ZodAdapter } from './adapters/zod.adapter.js';
+import { JsonSchemaAdapter } from './adapters/json-schema.adapter.js';
+import { DtoAdapter } from './adapters/dto.adapter.js';
+/**
+ * Thrown when no registered adapter is able to handle the provided input.
+ */
+export class SchemaExtractionError extends Error {
+    name = 'SchemaExtractionError';
+    constructor(message) {
+        super(message);
+        // Restore prototype chain (needed when targeting ES5 or when extending built-ins)
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/**
+ * Orchestrator service that delegates schema detection, extraction, and
+ * JSON Schema conversion to a prioritised chain of {@link SchemaAdapter}s.
+ *
+ * Built-in adapters (tried in descending priority order):
+ *
+ * | Adapter            | Priority |
+ * |--------------------|----------|
+ * | TypeBoxAdapter     | 100      |
+ * | ZodAdapter         | 50       |
+ * | JsonSchemaAdapter  | 30       |
+ * | DtoAdapter         | 20       |
+ *
+ * Custom adapters can be added via {@link registerAdapter} and will be
+ * inserted into the chain according to their priority value (highest first).
+ */
+export class SchemaExtractor {
+    adapters;
+    constructor() {
+        this.adapters = [
+            new TypeBoxAdapter(),
+            new ZodAdapter(),
+            new JsonSchemaAdapter(),
+            new DtoAdapter(),
+        ];
+        this.sortAdapters();
+    }
+    /**
+     * Register a custom adapter and re-sort the adapter chain by priority
+     * (highest first).
+     */
+    registerAdapter(adapter) {
+        this.adapters.push(adapter);
+        this.sortAdapters();
+    }
+    /**
+     * Returns the name of the first adapter whose `detect()` returns `true`
+     * for the given input, or `null` if no adapter matches.
+     */
+    detect(input) {
+        for (const adapter of this.adapters) {
+            if (adapter.detect(input)) {
+                return adapter.name;
+            }
+        }
+        return null;
+    }
+    /**
+     * Extracts a TypeBox-compatible `TSchema` from the given input using the
+     * first matching adapter.
+     *
+     * @throws {SchemaExtractionError} If no adapter can handle the input.
+     */
+    extract(input) {
+        for (const adapter of this.adapters) {
+            if (adapter.detect(input)) {
+                return adapter.extract(input);
+            }
+        }
+        throw new SchemaExtractionError('No adapter matched the provided input. ' +
+            'Ensure the input is a valid TypeBox, Zod, JSON Schema, or class-validator DTO schema.');
+    }
+    /**
+     * Extracts a plain JSON Schema object from the given input using the
+     * first matching adapter.
+     *
+     * @throws {SchemaExtractionError} If no adapter can handle the input.
+     */
+    extractJsonSchema(input) {
+        for (const adapter of this.adapters) {
+            if (adapter.detect(input)) {
+                return adapter.extractJsonSchema(input);
+            }
+        }
+        throw new SchemaExtractionError('No adapter matched the provided input. ' +
+            'Ensure the input is a valid TypeBox, Zod, JSON Schema, or class-validator DTO schema.');
+    }
+    /**
+     * Sort adapters in descending priority order (highest priority first).
+     */
+    sortAdapters() {
+        this.adapters.sort((a, b) => b.priority - a.priority);
+    }
+}
+//# sourceMappingURL=schema-extractor.service.js.map

package/dist/schema/schema-extractor.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-extractor.service.js","sourceRoot":"","sources":["../../src/schema/schema-extractor.service.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AACtE,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAEvD;;GAEG;AACH,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAC5B,IAAI,GAAG,uBAAuB,CAAC;IAEjD,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,kFAAkF;QAClF,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;CACF;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,OAAO,eAAe;IAClB,QAAQ,CAAkB;IAElC;QACE,IAAI,CAAC,QAAQ,GAAG;YACd,IAAI,cAAc,EAAE;YACpB,IAAI,UAAU,EAAE;YAChB,IAAI,iBAAiB,EAAE;YACvB,IAAI,UAAU,EAAE;SACjB,CAAC;QACF,IAAI,CAAC,YAAY,EAAE,CAAC;IACtB,CAAC;IAED;;;OAGG;IACH,eAAe,CAAC,OAAsB;QACpC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC5B,IAAI,CAAC,YAAY,EAAE,CAAC;IACtB,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,KAAc;QACnB,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YACpC,IAAI,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC1B,OAAO,OAAO,CAAC,IAAI,CAAC;YACtB,CAAC;QACH,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;OAKG;IACH,OAAO,CAAC,KAAc;QACpB,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YACpC,IAAI,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC1B,OAAO,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;YAChC,CAAC;QACH,CAAC;QACD,MAAM,IAAI,qBAAqB,CAC7B,yCAAyC;YACvC,uFAAuF,CAC1F,CAAC;IACJ,CAAC;IAED;;;;;OAKG;IACH,iBAAiB,CAAC,KAAc;QAC9B,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YACpC,IAAI,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC1B,OAAO,OAAO,CAAC,iBAAiB,CAAC,KAAK,CAAC,CAAC;YAC1C,CAAC;QACH,CAAC;QACD,MAAM,IAAI,qBAAqB,CAC7B,yCAAyC;YACvC,uFAAuF,CAC1F,CAAC;IACJ,CAAC;IAED;;OAEG;IACK,YAAY;QAClB,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC;IACxD,CAAC;CACF"}

package/dist/types.d.ts

@@ -0,0 +1,106 @@
+export type { ModuleAnnotations, ModuleExample, Module, Context, Identity, ModuleDescriptor, } from 'apcore-js';
+/** Annotations describing tool behavior characteristics. */
+export interface ApToolAnnotations {
+    readonly?: boolean;
+    destructive?: boolean;
+    idempotent?: boolean;
+    requiresApproval?: boolean;
+    openWorld?: boolean;
+    streaming?: boolean;
+}
+/** Example entry for a tool invocation. */
+export interface ApToolExample {
+    title: string;
+    inputs: Record<string, unknown>;
+    output: Record<string, unknown>;
+    description?: string;
+}
+/** Options accepted by the @ApTool decorator. */
+export interface ApToolOptions {
+    description: string;
+    id?: string | null;
+    inputSchema?: unknown | null;
+    outputSchema?: unknown | null;
+    annotations?: ApToolAnnotations | null;
+    tags?: string[];
+    documentation?: string | null;
+    examples?: ApToolExample[];
+}
+/** Options accepted by the @ApModule decorator. */
+export interface ApModuleOptions {
+    namespace: string;
+    description?: string | null;
+    tags?: string[];
+    annotations?: ApToolAnnotations | null;
+}
+/** Options for ApcoreModule.forRoot(). */
+export interface ApcoreModuleOptions {
+    extensionsDir?: string | null;
+    acl?: unknown | null;
+    middleware?: unknown[];
+    bindings?: string | null;
+    schema?: {
+        adapters?: string[];
+        strictOutput?: boolean;
+    };
+}
+/** Async options for ApcoreModule.forRootAsync(). */
+export interface ApcoreModuleAsyncOptions {
+    imports?: unknown[];
+    useFactory: (...args: unknown[]) => Promise<ApcoreModuleOptions> | ApcoreModuleOptions;
+    inject?: unknown[];
+}
+/** Options for ApcoreMcpModule.forRoot(). */
+export interface ApcoreMcpModuleOptions {
+    transport?: 'stdio' | 'streamable-http' | 'sse';
+    host?: string;
+    port?: number;
+    name?: string;
+    version?: string;
+    tags?: string[] | null;
+    prefix?: string | null;
+    explorer?: boolean;
+    explorerPrefix?: string;
+    allowExecute?: boolean;
+    dynamic?: boolean;
+    validateInputs?: boolean;
+    logLevel?: 'DEBUG' | 'INFO' | 'WARNING' | 'ERROR' | 'CRITICAL';
+    onStartup?: () => void | Promise<void>;
+    onShutdown?: () => void | Promise<void>;
+    metricsCollector?: {
+        exportPrometheus(): string;
+    };
+    authenticator?: import('apcore-mcp').Authenticator;
+    exemptPaths?: string[];
+}
+/** Async options for ApcoreMcpModule.forRootAsync(). */
+export interface ApcoreMcpModuleAsyncOptions {
+    imports?: unknown[];
+    useFactory: (...args: unknown[]) => Promise<ApcoreMcpModuleOptions> | ApcoreMcpModuleOptions;
+    inject?: unknown[];
+}
+/** Options for registering a single method as an apcore module. */
+export interface RegisterMethodOptions {
+    instance: object;
+    method: string;
+    description: string;
+    id?: string;
+    inputSchema?: unknown;
+    outputSchema?: unknown;
+    annotations?: ApToolAnnotations;
+    tags?: string[];
+    documentation?: string | null;
+    examples?: ApToolExample[];
+}
+/** Options for registering an entire service (multiple methods) at once. */
+export interface RegisterServiceOptions {
+    instance: object;
+    description?: string;
+    methods: string[] | '*';
+    exclude?: string[];
+    namespace?: string;
+    annotations?: ApToolAnnotations;
+    tags?: string[];
+    methodOptions?: Record<string, Partial<RegisterMethodOptions>>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/utils/id-generator.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Normalize a NestJS class name by stripping common framework suffixes
+ * and converting the remainder from PascalCase to snake_case.
+ *
+ * If the name consists *only* of a suffix (e.g. "Service"), it is
+ * returned as-is in lowercase rather than producing an empty string.
+ *
+ * @example
+ * normalizeClassName('EmailService')   // 'email'
+ * normalizeClassName('MyGreatService') // 'my_great'
+ * normalizeClassName('HTTPClient')     // 'http_client'
+ * normalizeClassName('email')          // 'email'
+ */
+export declare function normalizeClassName(name: string): string;
+/**
+ * Normalize a method name by converting camelCase to snake_case.
+ *
+ * @example
+ * normalizeMethodName('sendEmail')  // 'send_email'
+ * normalizeMethodName('batchSend')  // 'batch_send'
+ * normalizeMethodName('send')       // 'send'
+ * normalizeMethodName('send_email') // 'send_email'
+ */
+export declare function normalizeMethodName(name: string): string;
+/**
+ * Generate a fully-qualified module ID in the form "namespace.method".
+ *
+ * @param namespace  - The class / namespace portion of the ID.
+ * @param method     - The method portion of the ID.
+ * @param normalizeInputs - When true, applies {@link normalizeClassName}
+ *   to `namespace` and {@link normalizeMethodName} to `method`.
+ * @param explicitId - If provided (non-null), returned as-is, bypassing
+ *   all generation logic.
+ *
+ * @example
+ * generateModuleId('email', 'send')                          // 'email.send'
+ * generateModuleId('EmailService', 'sendEmail', true)        // 'email.send_email'
+ * generateModuleId('any', 'thing', false, 'custom.override') // 'custom.override'
+ */
+export declare function generateModuleId(namespace: string, method: string, normalizeInputs?: boolean, explicitId?: string | null): string;
+//# sourceMappingURL=id-generator.d.ts.map

package/dist/utils/id-generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"id-generator.d.ts","sourceRoot":"","sources":["../../src/utils/id-generator.ts"],"names":[],"mappings":"AA8BA;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAWvD;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,eAAe,CAAC,EAAE,OAAO,EACzB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,GACzB,MAAM,CASR"}

package/dist/utils/id-generator.js

@@ -0,0 +1,87 @@
+/**
+ * NestJS suffixes to strip from class names during normalization.
+ */
+const NESTJS_SUFFIXES = [
+    'Service',
+    'Controller',
+    'Handler',
+    'Module',
+    'Provider',
+    'Gateway',
+    'Guard',
+    'Interceptor',
+    'Pipe',
+    'Filter',
+];
+/**
+ * Convert a PascalCase or camelCase string to snake_case.
+ *
+ * Handles consecutive uppercase letters (acronyms) by inserting an
+ * underscore before the last uppercase letter of the run when followed
+ * by a lowercase letter.  For example: "HTTPClient" -> "http_client".
+ */
+function toSnakeCase(value) {
+    return value
+        .replace(/([A-Z]+)([A-Z][a-z])/g, '$1_$2')
+        .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+        .toLowerCase();
+}
+/**
+ * Normalize a NestJS class name by stripping common framework suffixes
+ * and converting the remainder from PascalCase to snake_case.
+ *
+ * If the name consists *only* of a suffix (e.g. "Service"), it is
+ * returned as-is in lowercase rather than producing an empty string.
+ *
+ * @example
+ * normalizeClassName('EmailService')   // 'email'
+ * normalizeClassName('MyGreatService') // 'my_great'
+ * normalizeClassName('HTTPClient')     // 'http_client'
+ * normalizeClassName('email')          // 'email'
+ */
+export function normalizeClassName(name) {
+    let stripped = name;
+    for (const suffix of NESTJS_SUFFIXES) {
+        if (name.endsWith(suffix) && name.length > suffix.length) {
+            stripped = name.slice(0, -suffix.length);
+            break;
+        }
+    }
+    return toSnakeCase(stripped);
+}
+/**
+ * Normalize a method name by converting camelCase to snake_case.
+ *
+ * @example
+ * normalizeMethodName('sendEmail')  // 'send_email'
+ * normalizeMethodName('batchSend')  // 'batch_send'
+ * normalizeMethodName('send')       // 'send'
+ * normalizeMethodName('send_email') // 'send_email'
+ */
+export function normalizeMethodName(name) {
+    return toSnakeCase(name);
+}
+/**
+ * Generate a fully-qualified module ID in the form "namespace.method".
+ *
+ * @param namespace  - The class / namespace portion of the ID.
+ * @param method     - The method portion of the ID.
+ * @param normalizeInputs - When true, applies {@link normalizeClassName}
+ *   to `namespace` and {@link normalizeMethodName} to `method`.
+ * @param explicitId - If provided (non-null), returned as-is, bypassing
+ *   all generation logic.
+ *
+ * @example
+ * generateModuleId('email', 'send')                          // 'email.send'
+ * generateModuleId('EmailService', 'sendEmail', true)        // 'email.send_email'
+ * generateModuleId('any', 'thing', false, 'custom.override') // 'custom.override'
+ */
+export function generateModuleId(namespace, method, normalizeInputs, explicitId) {
+    if (explicitId != null) {
+        return explicitId;
+    }
+    const ns = normalizeInputs ? normalizeClassName(namespace) : namespace;
+    const m = normalizeInputs ? normalizeMethodName(method) : method;
+    return `${ns}.${m}`;
+}
+//# sourceMappingURL=id-generator.js.map

package/dist/utils/id-generator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"id-generator.js","sourceRoot":"","sources":["../../src/utils/id-generator.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,eAAe,GAAG;IACtB,SAAS;IACT,YAAY;IACZ,SAAS;IACT,QAAQ;IACR,UAAU;IACV,SAAS;IACT,OAAO;IACP,aAAa;IACb,MAAM;IACN,QAAQ;CACT,CAAC;AAEF;;;;;;GAMG;AACH,SAAS,WAAW,CAAC,KAAa;IAChC,OAAO,KAAK;SACT,OAAO,CAAC,uBAAuB,EAAE,OAAO,CAAC;SACzC,OAAO,CAAC,oBAAoB,EAAE,OAAO,CAAC;SACtC,WAAW,EAAE,CAAC;AACnB,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC7C,IAAI,QAAQ,GAAG,IAAI,CAAC;IAEpB,KAAK,MAAM,MAAM,IAAI,eAAe,EAAE,CAAC;QACrC,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC;YACzD,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YACzC,MAAM;QACR,CAAC;IACH,CAAC;IAED,OAAO,WAAW,CAAC,QAAQ,CAAC,CAAC;AAC/B,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,OAAO,WAAW,CAAC,IAAI,CAAC,CAAC;AAC3B,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,gBAAgB,CAC9B,SAAiB,EACjB,MAAc,EACd,eAAyB,EACzB,UAA0B;IAE1B,IAAI,UAAU,IAAI,IAAI,EAAE,CAAC;QACvB,OAAO,UAAU,CAAC;IACpB,CAAC;IAED,MAAM,EAAE,GAAG,eAAe,CAAC,CAAC,CAAC,kBAAkB,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACvE,MAAM,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IAEjE,OAAO,GAAG,EAAE,IAAI,CAAC,EAAE,CAAC;AACtB,CAAC"}

package/package.json

@@ -0,0 +1,100 @@
+{
+  "name": "nestjs-apcore",
+  "version": "0.1.0",
+  "description": "NestJS adapter for the apcore AI-Perceivable module ecosystem",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsc -p tsconfig.build.json --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src/ tests/",
+    "clean": "rm -rf dist"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "@nestjs/common": ">=10.0.0",
+    "@nestjs/core": ">=10.0.0",
+    "reflect-metadata": ">=0.1.13",
+    "rxjs": ">=7.0.0"
+  },
+  "peerDependenciesMeta": {
+    "class-validator": {
+      "optional": true
+    },
+    "class-transformer": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "apcore-js": "^0.6.0",
+    "apcore-mcp": "^0.7.0",
+    "js-yaml": "^4.1.0"
+  },
+  "devDependencies": {
+    "@nestjs/common": "^10.0.0",
+    "@nestjs/core": "^10.0.0",
+    "@nestjs/platform-express": "^10.0.0",
+    "@nestjs/testing": "^10.0.0",
+    "@sinclair/typebox": "^0.34.0",
+    "@types/js-yaml": "^4.0.0",
+    "@types/node": "^20.0.0",
+    "@vitest/coverage-v8": "^3.0.0",
+    "apdev-js": "^0.2.0",
+    "class-transformer": "^0.5.0",
+    "class-validator": "^0.14.0",
+    "reflect-metadata": "^0.2.0",
+    "rxjs": "^7.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^3.0.0",
+    "zod": "^3.23.0"
+  },
+  "keywords": [
+    "nestjs",
+    "apcore",
+    "mcp",
+    "model-context-protocol",
+    "ai",
+    "ai-tools",
+    "llm",
+    "openai",
+    "tool-calling",
+    "nestjs-module",
+    "decorator",
+    "typescript"
+  ],
+  "author": "aipartnerup",
+  "homepage": "https://github.com/aipartnerup/nestjs-apcore#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aipartnerup/nestjs-apcore.git"
+  },
+  "bugs": {
+    "url": "https://github.com/aipartnerup/nestjs-apcore/issues"
+  },
+  "license": "Apache-2.0",
+  "apdev": {
+    "base_package": "nestjs-apcore"
+  }
+}