@mayhem93/nexxus-core-lib 0.0.1 → 0.0.2

package/dist-esm/models/User.js

@@ -1,6 +1,15 @@
-import { NexxusBaseModel, MODEL_REGISTRY } from "./BaseModel";
+import { MODEL_REGISTRY } from "./BaseModel";
+import { NexxusBuiltinModel } from "./BuiltinModel";
+import { NEXXUS_BUILTIN_MODEL_SCHEMAS } from "../common/BuiltinSchemas";
 import { InvalidUserModelException } from "../lib/Exceptions";
-export class NexxusApplicationUser extends NexxusBaseModel {
+export class NexxusUser extends NexxusBuiltinModel {
+    static getModelSchema(userDetails) {
+        const base = { ...NEXXUS_BUILTIN_MODEL_SCHEMAS.user };
+        if (userDetails) {
+            base.details = { type: 'object', required: false, properties: userDetails };
+        }
+        return base;
+    }
     constructor(data) {
         super({ ...data, type: MODEL_REGISTRY.user });
         if (this.data.appId === undefined || typeof this.data.appId !== 'string') {

package/dist-esm/models/User.js.map

@@ -1 +1 @@
-{"version":3,"file":"User.js","sourceRoot":"","sources":["../../src/models/User.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EAEf,cAAc,EACf,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,yBAAyB,EAAE,MAAM,mBAAmB,CAAC;AAgB9D,MAAM,OAAO,qBAAsB,SAAQ,eAAoC;IAC7E,YAAY,IAAyB;QACnC,KAAK,CAAC,EAAE,GAAG,IAAI,EAAE,IAAI,EAAE,cAAc,CAAC,IAAI,EAAE,CAAC,CAAC;QAE9C,IAAI,IAAI,CAAC,IAAI,CAAC,KAAK,KAAK,SAAS,IAAI,OAAO,IAAI,CAAC,IAAI,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;YACzE,MAAM,IAAI,yBAAyB,CAAC,+CAA+C,CAAC,CAAC;QACvF,CAAC;QAED,IAAI,IAAI,CAAC,IAAI,CAAC,QAAQ,KAAK,SAAS,IAAI,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;YAC/E,MAAM,IAAI,yBAAyB,CAAC,kDAAkD,CAAC,CAAC;QAC1F,CAAC;QAED,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,KAAK,SAAS,IAAI,IAAI,CAAC,IAAI,CAAC,QAAQ,KAAK,IAAI,CAAC,IAAI,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;YAChH,MAAM,IAAI,yBAAyB,CAAC,8CAA8C,CAAC,CAAC;QACtF,CAAC;QAED,IAAI,IAAI,CAAC,IAAI,CAAC,aAAa,KAAK,SAAS,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC,OAAO,EAAE,KAAK,QAAQ,CAAC,EAAE,CAAC;YACnJ,MAAM,IAAI,yBAAyB,CAAC,kEAAkE,CAAC,CAAC;QAC1G,CAAC;QAED,IAAI,IAAI,CAAC,IAAI,CAAC,OAAO,KAAK,SAAS,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;YACzE,MAAM,IAAI,yBAAyB,CAAC,4CAA4C,CAAC,CAAC;QACpF,CAAC;aAAM,CAAC;YACN,MAAM,aAAa,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC,OAAO,QAAQ,KAAK,QAAQ,CAAC,CAAC;YAExF,IAAI,CAAC,aAAa,EAAE,CAAC;gBACnB,MAAM,IAAI,yBAAyB,CAAC,4CAA4C,CAAC,CAAC;YACpF,CAAC;QACH,CAAC;QAED,IAAI,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;YAC3C,MAAM,IAAI,yBAAyB,CAAC,kCAAkC,CAAC,CAAC;QAC1E,CAAC;QAED,IAAI,IAAI,CAAC,IAAI,CAAC,OAAO,KAAK,SAAS,IAAI,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;YAC7E,MAAM,IAAI,yBAAyB,CAAC,8CAA8C,CAAC,CAAC;QACtF,CAAC;IACH,CAAC;CACF"}
+{"version":3,"file":"User.js","sourceRoot":"","sources":["../../src/models/User.ts"],"names":[],"mappings":"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"}

package/dist-types/common/BuiltinSchemas.d.ts

@@ -1,6 +1,6 @@
 /**
- * Universal fields present in all models
- * Note: 'type' and 'appId' are excluded as they are handled separately in queries
+ * Universal fields present in all models (auto-managed by NexxusBaseModel).
+ * 'type' and 'appId' are excluded as they are handled separately in queries.
  */
 export declare const NEXXUS_UNIVERSAL_FIELDS: {
     readonly id: {
@@ -17,13 +17,31 @@ export declare const NEXXUS_UNIVERSAL_FIELDS: {
     };
 };
 /**
- * Schema definitions for built-in (reserved) models. Only used for
+ * Field names reserved by Nexxus across ALL app models. App developers cannot
+ * declare a field of these names in their application schemas — the
+ * `NexxusApplication` constructor enforces this on schema registration.
+ *
+ * Most of these are caller-settable at model construction time (e.g. `appId`,
+ * `userId`, `type` — set by the API/Worker). `version` is the sole exception:
+ * it's set exclusively by the database adapter and rejected from user input
+ * (see the inline check in `NexxusSchemaValidator.validateAgainstSchema`).
+ */
+export declare const NEXXUS_RESERVED_FIELD_NAMES: ReadonlySet<string>;
+/**
+ * Schema definitions for built-in (reserved) models. These are the runtime
+ * source of truth for built-in model field shapes; the corresponding TS
+ * interfaces (INexxusUser, INexxusApplication) are derived from these.
  */
 export declare const NEXXUS_BUILTIN_MODEL_SCHEMAS: {
     readonly user: {
+        readonly appId: {
+            readonly type: "string";
+            readonly required: true;
+            readonly filterable: true;
+        };
         readonly userType: {
             readonly type: "string";
-            readonly required: false;
+            readonly required: true;
             readonly filterable: true;
         };
         readonly username: {
@@ -33,7 +51,8 @@ export declare const NEXXUS_BUILTIN_MODEL_SCHEMAS: {
         };
         readonly password: {
             readonly type: "string";
-            readonly required: false;
+            readonly required: true;
+            readonly nullable: true;
         };
         readonly authProviders: {
             readonly type: "array";
@@ -57,6 +76,41 @@ export declare const NEXXUS_BUILTIN_MODEL_SCHEMAS: {
             readonly required: true;
             readonly filterable: true;
         };
+        readonly description: {
+            readonly type: "string";
+            readonly required: false;
+        };
+        /**
+         * Per-application auth block. When `authEnabled` is true this must be
+         * present and contain a non-empty `strategies` map; when false it should
+         * be absent or have an empty `strategies`. The conditional rule isn't
+         * expressible in the static schema — it's enforced imperatively in the
+         * `NexxusApplication` constructor.
+         *
+         * `strategies` is a free-form map keyed by strategy name (e.g. 'local',
+         * 'google'). The shape of each value is validated by that strategy's
+         * own JSON Schema, loaded by the `NexxusAuthStrategy` base class.
+         */
+        readonly auth: {
+            readonly type: "object";
+            readonly required: false;
+            readonly nullable: true;
+            readonly properties: {
+                readonly jwtSecret: {
+                    readonly type: "string";
+                    readonly required: true;
+                };
+                readonly jwtExpiresIn: {
+                    readonly type: "string";
+                    readonly required: false;
+                };
+                readonly strategies: {
+                    readonly type: "object";
+                    readonly required: true;
+                    readonly properties: {};
+                };
+            };
+        };
     };
 };
 /**

package/dist-types/common/FilterQuery.d.ts

@@ -1,7 +1,5 @@
 import type { NexxusModelDef } from '../common/ModelTypes';
-import { type NexxusBuiltinModelType } from './BuiltinSchemas';
-import type { NexxusAppModelType } from '../models/AppModel';
-import type { NexxusUserDetailSchema } from '../models/User';
+import type { INexxusAppModel } from '../models/AppModel';
 export type NexxusComparisonOperator = 'gte' | 'lte' | 'gt' | 'lt' | 'ne' | 'in';
 export type NexxusLogicalOperator = '$and' | '$or';
 export type NexxusFieldValue = string | number | boolean;
@@ -30,21 +28,15 @@ type FilterNodeWithContext = FilterNode & {
     depth: number;
     parentOperator?: NexxusLogicalOperator;
 };
-export type NexxusFilterQueryConfig = {
-    appModelDef: NexxusModelDef;
-} | {
-    modelType: NexxusBuiltinModelType;
-    userDetailsSchema?: NexxusUserDetailSchema;
-};
 export declare class NexxusFilterQuery {
     private query;
     private nodes;
     private modelDef;
-    constructor(query: NexxusFilterQueryType, config: NexxusFilterQueryConfig);
+    constructor(query: NexxusFilterQueryType, schema: NexxusModelDef);
     getNodes(): FilterNode[];
     getNormalizedQuery(): NexxusFilterQueryType;
     [Symbol.iterator](): Generator<FilterNodeWithContext>;
-    test(object: Partial<NexxusAppModelType>): boolean;
+    test(object: Partial<INexxusAppModel>): boolean;
     private testNode;
     private validateAndParse;
     private parseQuery;

package/dist-types/common/InferModel.d.ts

@@ -0,0 +1,29 @@
+export type InferFieldDef<D> = D extends {
+    type: 'string';
+} ? string : D extends {
+    type: 'number';
+} ? number : D extends {
+    type: 'boolean';
+} ? boolean : D extends {
+    type: 'date';
+} ? number : D extends {
+    type: 'array';
+    arrayType: infer AT;
+    properties?: infer P;
+} ? AT extends 'object' ? P extends Record<string, any> ? Array<InferModel<P>> : never : AT extends 'string' ? string[] : AT extends 'number' ? number[] : AT extends 'boolean' ? boolean[] : AT extends 'date' ? number[] : never : D extends {
+    type: 'object';
+    properties: infer P;
+} ? P extends Record<string, any> ? InferModel<P> : never : never;
+type ApplyNullable<D, T> = D extends {
+    nullable: true;
+} ? T | null : T;
+export type InferModel<S> = {
+    -readonly [K in keyof S as S[K] extends {
+        required: true;
+    } ? K : never]: ApplyNullable<S[K], InferFieldDef<S[K]>>;
+} & {
+    -readonly [K in keyof S as S[K] extends {
+        required: true;
+    } ? never : K]?: ApplyNullable<S[K], InferFieldDef<S[K]>>;
+};
+export {};

package/dist-types/common/JsonPatch.d.ts

@@ -1,8 +1,5 @@
-import { NexxusApplicationSchema } from '../models/Application';
-import type { NexxusModelFieldType } from '../common/ModelTypes';
-import { NexxusAppModelType } from '../models/AppModel';
-import { NexxusBuiltinModelType } from './BuiltinSchemas';
-import type { NexxusUserDetailSchema } from '../models/User';
+import type { NexxusModelDef, NexxusModelFieldType } from '../common/ModelTypes';
+import { INexxusAppModel } from '../models/AppModel';
 declare const JSON_OPS: readonly ["replace", "append", "prepend", "incr", "decr"];
 export type NexxusJsonPatchConstructor = {
     op: typeof JSON_OPS[number];
@@ -26,12 +23,6 @@ type NexxusJsonPatchMetadataInternal = NexxusJsonPatchMetadata & {
     pathFieldTypes?: NexxusModelFieldType[];
 };
 export type NexxusJsonPatchMetadataConstructor = Omit<NexxusJsonPatchMetadata, 'pathFieldTypes'>;
-export type NexxusJsonPatchValidationConfig = {
-    appSchema: NexxusApplicationSchema;
-} | {
-    modelType: NexxusBuiltinModelType;
-    userDetailsSchema?: NexxusUserDetailSchema;
-};
 export declare class NexxusJsonPatch {
     private valid;
     private fullPatch;
@@ -39,40 +30,8 @@ export declare class NexxusJsonPatch {
     constructor(fullPatch: NexxusJsonPatchConstructor | NexxusJsonPatchInternal);
     get(): NexxusJsonPatchInternal;
     isValid(): boolean;
-    getPartialModel(): Partial<NexxusAppModelType>;
-    validate(config: NexxusJsonPatchValidationConfig): void;
-    private static validateAgainstType;
+    getPartialModel(): Partial<INexxusAppModel>;
+    validate(schema: NexxusModelDef): void;
     private static traverseSchema;
-    private static validateValueType;
-    /**
-   * Validate string type
-   */
-    private static validateString;
-    /**
-     * Validate number type
-     */
-    private static validateNumber;
-    /**
-     * Validate boolean type
-     */
-    private static validateBoolean;
-    /**
-     * Validate date type
-     */
-    private static validateDate;
-    /**
-     * Validate object type (recursively validates properties)
-     */
-    private static validateObject;
-    /**
-   * Validate array type (recursively validates elements)
-   */
-    private static validateArray;
-    /**
-   * Helper to validate primitive types (reusable for arrays)
-   */
-    private static validatePrimitiveType;
-    private static isObjectFieldDef;
-    private static isArrayFieldDef;
 }
 export {};

package/dist-types/common/ModelTypes.d.ts

@@ -3,6 +3,7 @@ export type NexxusModelFieldType = NexxusModelPrimitiveType | 'array' | 'object'
 interface BaseFieldDef {
     type: NexxusModelFieldType;
     required?: boolean;
+    nullable?: boolean;
 }
 export interface PrimitiveFieldDef extends BaseFieldDef {
     type: NexxusModelPrimitiveType;

package/dist-types/common/QueuePayloads.d.ts

@@ -1,4 +1,4 @@
-import { NexxusAppModelType } from '../models/AppModel';
+import { INexxusAppModel } from '../models/AppModel';
 import { NexxusJsonPatchInternal, NexxusJsonPatchMetadata } from '../common/JsonPatch';
 export interface NexxusBaseQueuePayload {
     event: string;
@@ -6,65 +6,87 @@ export interface NexxusBaseQueuePayload {
 }
 export type NexxusModelCreatedPayload = {
     event: 'model_created';
-    data: NexxusAppModelType;
+    data: INexxusAppModel;
 };
 export type NexxusModelUpdatedPayload = {
     event: 'model_updated';
     data: Array<NexxusJsonPatchInternal>;
 };
-export type NexxusModelDeletedData = Pick<NexxusAppModelType, 'id' | 'type' | 'appId' | 'userId'>;
+export type NexxusModelDeletedData = Pick<INexxusAppModel, 'id' | 'type' | 'appId' | 'userId'>;
 export type NexxusModelDeletedPayload = {
     event: 'model_deleted';
     data: NexxusModelDeletedData;
 };
 export type NexxusWriterPayload = NexxusModelCreatedPayload | NexxusModelUpdatedPayload | NexxusModelDeletedPayload;
-export type NexxusTransportManagetJsonPatch = Omit<NexxusJsonPatchInternal, 'metadata'> & {
+export type NexxusTransportManagerJsonPatch = Omit<NexxusJsonPatchInternal, 'metadata'> & {
     metadata: NexxusJsonPatchMetadata & {
-        partialModel: Partial<NexxusAppModelType>;
+        partialModel: Partial<INexxusAppModel>;
     };
 };
 export type NexxusTransportManagerModelUpdatedPayload = {
     event: 'model_updated';
-    data: Array<NexxusTransportManagetJsonPatch>;
+    data: Array<NexxusTransportManagerJsonPatch>;
 };
 export type NexxusTransportManagerPayload = NexxusModelCreatedPayload | NexxusTransportManagerModelUpdatedPayload | NexxusModelDeletedPayload;
-export interface NexxusWebSocketJsonPatchMetadata {
-    id: string;
+/**
+ * Metadata for transport-bound model events (create/update/delete alike).
+ * Carries the channels that matched the subscription router for this device,
+ * so the client can correlate the event with its local subscription containers.
+ */
+export interface NexxusTransportMetadata {
     channels: Array<string>;
 }
 /**
- * JsonPatch type for WebSocket transport workers
+ * Payload for any transport worker - model created
+ */
+export type NexxusTransportModelCreatedPayload = {
+    event: 'model_created';
+    model: INexxusAppModel;
+    metadata: NexxusTransportMetadata;
+};
+/**
+ * Payload for any transport worker - model deleted
  */
-export type NexxusWebSocketJsonPatch = Omit<NexxusJsonPatchInternal, 'metadata'> & {
-    metadata: NexxusWebSocketJsonPatchMetadata;
+export type NexxusTransportModelDeletedPayload = {
+    event: 'model_deleted';
+    model: NexxusModelDeletedData;
+    metadata: NexxusTransportMetadata;
 };
 /**
- * Payload for WebSocket Transport - slim metadata with just channel
+ * Payload for any transport worker - model updated.
+ * All patches in a single event target the same model — its identity is hoisted
+ * into `model`, and the matched channels into top-level `metadata`. Per-patch
+ * metadata is intentionally absent (it was redundant across patches of the same
+ * update event under the previous shape).
  */
-export type NexxusWebSocketModelUpdatedPayload = {
+export type NexxusTransportModelUpdatedPayload = {
     event: 'model_updated';
-    data: Array<NexxusWebSocketJsonPatch>;
+    /**
+     * Includes `version` — the post-update version stamp assigned by the adapter.
+     * Clients use it for gap detection: apply if `model.version === local.version + 1`,
+     * request a fresh GET if there's a gap, ignore if it's already been applied.
+     */
+    model: Pick<INexxusAppModel, 'id' | 'type' | 'appId' | 'userId' | 'version'>;
+    patches: Array<Omit<NexxusJsonPatchInternal, 'metadata'>>;
+    metadata: NexxusTransportMetadata;
 };
-export type NexxusWebsocketPayload = {
+/**
+ * Canonical payload consumed by ALL transport workers (volatile and persistent alike).
+ * The shape is identical across transports; each transport translates the inner `data`
+ * into its own wire format inside its `sendToDevice` implementation.
+ */
+export type NexxusTransportWorkerPayload = {
     event: 'device_message';
     deviceIds: Array<string>;
-    data: NexxusModelCreatedPayload | NexxusWebSocketModelUpdatedPayload | NexxusModelDeletedPayload;
-};
-export type NexxusMqttPayload = {
-    event: 'mqtt_publish';
-    topic: string;
-    payload: Buffer;
-} | {
-    event: 'mqtt_subscribe';
-    topic: string;
+    data: NexxusTransportModelCreatedPayload | NexxusTransportModelUpdatedPayload | NexxusTransportModelDeletedPayload;
 };
 export interface NexxusBuiltInQueuePayloadMap {
     'writer': NexxusWriterPayload;
     'transport-manager': NexxusTransportManagerPayload;
 }
 export interface NexxusDynamicQueuePayloadMap {
-    'websockets-transport': NexxusWebsocketPayload;
-    'mqtt-transport': NexxusMqttPayload;
+    'websockets-transport': NexxusTransportWorkerPayload;
+    'mqtt-transport': NexxusTransportWorkerPayload;
 }
 export type NexxusBuiltInQueueName = keyof NexxusBuiltInQueuePayloadMap;
 export type NexxusDynamicQueueType = keyof NexxusDynamicQueuePayloadMap;

package/dist-types/common/SchemaValidator.d.ts

@@ -1,4 +1,44 @@
-import { NexxusUserDetailSchema } from "../models/User";
+import type { NexxusFieldDef, NexxusModelDef } from './ModelTypes';
+/**
+ * Pure schema-aware validation + normalization for a single value against a
+ * field definition, or for whole-model data against a model definition.
+ *
+ * Returns a normalized copy of the input value (e.g. date strings become
+ * integer timestamps). Throws InvalidSchemaDataException on the first violation.
+ *
+ * Used by:
+ *   - NexxusJsonPatch (per-path validation on patch operations)
+ *   - NexxusAppModel (whole-model validation on construction)
+ *
+ * Required-field checking is intentionally NOT performed here yet; only fields
+ * present in the input are validated.
+ */
 export declare class NexxusSchemaValidator {
-    static validateUserDetails(partialDetails: Record<string, any>, userDetailSchema: NexxusUserDetailSchema): boolean;
+    /**
+     * Validate every present field of `data` against the model definition.
+     * Returns a shallow-merged copy of `data` with each value normalized.
+     * Unknown fields (present in data but not declared in modelDef) are passed
+     * through unchanged.
+     */
+    static validateAgainstSchema(data: Record<string, unknown>, modelDef: NexxusModelDef): Record<string, unknown>;
+    /**
+     * Validate a single value against a field definition. Returns the normalized
+     * value. Throws InvalidSchemaDataException on failure.
+     *
+     * `path` is used only for error messages.
+     */
+    static validateValue(value: unknown, fieldDef: NexxusFieldDef, path: string): unknown;
+    private static validateString;
+    private static validateNumber;
+    private static validateBoolean;
+    /**
+     * Accepts: number (ms timestamp), ISO date string, or numeric string.
+     * Returns: integer ms timestamp.
+     *
+     * This is the single canonical date parser for the system; the previous
+     * inconsistency between `Date.parse()` and `new Date(s).getTime()` is gone.
+     */
+    private static validateDate;
+    private static validateObject;
+    private static validateArray;
 }

package/dist-types/index.d.ts

@@ -6,7 +6,10 @@ export * from "./lib/Logger";
 export * from "./common/QueuePayloads";
 export * from "./common/JsonPatch";
 export * from "./common/FilterQuery";
+export * from "./common/InferModel";
+export * from "./common/SchemaValidator";
 export * from "./models/BaseModel";
+export * from "./models/BuiltinModel";
 export * from './common/BuiltinSchemas';
 export * from "./models/AppModel";
 export * from "./models/Application";

package/dist-types/lib/BaseService.d.ts

@@ -1,5 +1,5 @@
 import type { ConfigEnvVars, ConfigCliArgs, AddJsonSchemaDefFuncArg, NexxusConfigManager } from './ConfigManager';
-import type { NexxusBaseLogger } from "./Logger";
+import type { NexxusBaseLogger } from './Logger';
 import { NexxusConfig } from './ConfigProvider';
 export type EventMap = Record<string | symbol, any[]>;
 export interface INexxusBaseServices {
@@ -18,6 +18,13 @@ export declare abstract class NexxusBaseService<T extends NexxusConfig, Ev exten
     protected config: Readonly<T>;
     protected static envVars: ConfigEnvVars;
     protected static cliArgs: ConfigCliArgs;
+    /**
+     * The top-level key under which this service's configuration sits in the merged
+     * root config (e.g. "logger", "database", "redis", "app"). Required for every
+     * concrete service — ConfigManager uses it as the property name when grafting
+     * the service's schema definition into the root JSON Schema.
+     */
+    protected static configRootKey: string;
     protected static schemaPath: string;
     private static schemaContents;
     constructor(config: Readonly<T>);

package/dist-types/lib/ConfigManager.d.ts

@@ -9,21 +9,17 @@ export type AddJsonSchemaDefFuncArg = {
 };
 type EnvVarsSpec = {
     name: string;
+    /** Dot-notation path relative to the service's configRootKey (e.g. "host", "auth.jwtSecret"). */
     location: string;
 };
-export type ConfigEnvVars = {
-    source: string;
-    specs: Array<EnvVarsSpec>;
-};
+export type ConfigEnvVars = Array<EnvVarsSpec>;
 type CliArgsSpec = {
     name: string;
+    /** Dot-notation path relative to the service's configRootKey. */
     location: string;
     type: CliArgType;
 };
-export type ConfigCliArgs = {
-    source: string;
-    specs: Array<CliArgsSpec>;
-};
+export type ConfigCliArgs = Array<CliArgsSpec>;
 export declare class NexxusConfigManager {
     private static CONF_FILE_NAME;
     private jsonSchema;
@@ -32,12 +28,10 @@ export declare class NexxusConfigManager {
     private data;
     private configProviders;
     private customProviders;
-    constructor(confFile?: string);
+    constructor(configFileName?: string);
     addCustomProvider(provider: INexxusConfigProvider): void;
     private addJsonSchemaDef;
-    validateServices(svcs: Array<typeof NexxusBaseService>): void;
-    private addCliArgsToSpec;
-    private addEnvVarsToSpec;
+    validateServices(svcs: Array<typeof NexxusBaseService>): Promise<void>;
     private populateFromCliArgs;
     private populateFromEnvVars;
     private populateFromCustomProviders;

package/dist-types/lib/Exceptions.d.ts

@@ -5,6 +5,7 @@ export declare enum NexxusExceptions {
     INVALID_CONFIG = "InvalidConfigException",
     INVALID_JSON_PATCH = "InvalidJsonPatchException",
     INVALID_QUERY_FILTER = "InvalidQueryFilterException",
+    INVALID_SCHEMA_DATA = "InvalidSchemaDataException",
     INVALID_USER_MODEL = "InvalidUserModelException"
 }
 export declare class NexxusException extends Error {
@@ -28,6 +29,9 @@ export declare class InvalidJsonPatchException extends NexxusException {
 export declare class InvalidQueryFilterException extends NexxusException {
     constructor(message: string);
 }
+export declare class InvalidSchemaDataException extends NexxusException {
+    constructor(message: string);
+}
 export declare class InvalidUserModelException extends NexxusException {
     constructor(message: string);
 }

package/dist-types/lib/Logger.d.ts

@@ -1,7 +1,7 @@
 import { ConfigEnvVars, ConfigCliArgs } from './ConfigManager';
 import { NexxusBaseService, INexxusBaseServices } from './BaseService';
 import { NexxusConfig } from './ConfigProvider';
-type LoggableType = string | object | number | boolean | null | undefined;
+export type LogAttributes = Record<string, unknown>;
 export declare const enum NexxusLoggerLevels {
     EMERGENCY = "emerg",
     ALERT = "alert",
@@ -12,37 +12,107 @@ export declare const enum NexxusLoggerLevels {
     INFO = "info",
     DEBUG = "debug"
 }
+export type StdoutTransportConfig = {
+    type: 'stdout';
+};
+export type FileTransportConfig = {
+    type: 'file';
+    filename: string;
+    maxSize?: number;
+    maxFiles?: number;
+};
+/**
+ * Catch-all for transports loaded dynamically from npm packages. The `type`
+ * field is the package name (e.g. "winston-papertrail"); `export` optionally
+ * names the class export within the package; `options` is the passthrough
+ * config object handed to the transport's constructor.
+ *
+ * The schema's `oneOf` discriminator excludes built-in type strings from this
+ * variant, so the TS-side `type: string` doesn't cause ambiguity at runtime.
+ */
+export type CustomTransportConfig = {
+    type: string;
+    export?: string;
+    options?: Record<string, unknown>;
+};
+export type WinstonNexxusTransportConfig = StdoutTransportConfig | FileTransportConfig | CustomTransportConfig;
 type WinstonNexxusLoggerConfig = {
     level: NexxusLoggerLevels;
     logType: "json" | "text";
     timestamps: boolean;
     colors: boolean;
+    transports?: Array<WinstonNexxusTransportConfig>;
 } & NexxusConfig;
 export interface INexxusLogger {
-    log(level: NexxusLoggerLevels, message: LoggableType, label?: string): void;
+    log(level: NexxusLoggerLevels, message: string, attributes?: LogAttributes, label?: string): void;
 }
-export interface INexxusAsyncLogger extends INexxusLogger {
-    log(level: NexxusLoggerLevels, message: LoggableType, label?: string): Promise<void>;
+export interface INexxusAsyncLogger {
+    log(level: NexxusLoggerLevels, message: string, attributes?: LogAttributes, label?: string): Promise<void>;
 }
 interface NexxusLoggerServices extends Omit<INexxusBaseServices, 'logger'> {
 }
 export declare abstract class NexxusBaseLogger<T extends NexxusConfig> extends NexxusBaseService<T> implements INexxusLogger {
+    protected static configRootKey: string;
     constructor(services: NexxusLoggerServices);
-    abstract log(level: NexxusLoggerLevels, message: LoggableType, label?: string): void;
-    debug(message: LoggableType, label?: string): void;
-    info(message: LoggableType, label?: string): void;
-    warn(message: LoggableType, label?: string): void;
-    error(message: LoggableType, label?: string): void;
-    critical(message: LoggableType, label?: string): void;
-    alert(message: LoggableType, label?: string): void;
-    emerg(message: LoggableType, label?: string): void;
+    abstract log(level: NexxusLoggerLevels, message: string, attributes?: LogAttributes, label?: string): void;
+    protected static serializeError(err: Error): Record<string, unknown>;
+    protected static makeSafeReplacer(): (key: string, value: unknown) => unknown;
+    protected static safeStringify(value: unknown): string;
+    debug(message: string, label?: string): void;
+    debug(message: string, attributes: LogAttributes, label?: string): void;
+    info(message: string, label?: string): void;
+    info(message: string, attributes: LogAttributes, label?: string): void;
+    warn(message: string, label?: string): void;
+    warn(message: string, attributes: LogAttributes, label?: string): void;
+    error(message: string, label?: string): void;
+    error(message: string, attributes: LogAttributes, label?: string): void;
+    critical(message: string, label?: string): void;
+    critical(message: string, attributes: LogAttributes, label?: string): void;
+    alert(message: string, label?: string): void;
+    alert(message: string, attributes: LogAttributes, label?: string): void;
+    emerg(message: string, label?: string): void;
+    emerg(message: string, attributes: LogAttributes, label?: string): void;
+    private dispatch;
 }
 export declare class WinstonNexxusLogger extends NexxusBaseLogger<WinstonNexxusLoggerConfig> {
     private winston;
     protected static schemaPath: string;
     protected static envVars: ConfigEnvVars;
     protected static cliArgs: ConfigCliArgs;
-    constructor(services: NexxusLoggerServices);
-    log(level: NexxusLoggerLevels, message: LoggableType, label?: string): void;
+    /**
+     * Private — use `WinstonNexxusLogger.create(...)` instead. Transport instances
+     * must be resolved (async, since custom ones are dynamically imported) before
+     * the Winston logger can be constructed; the factory owns that step.
+     */
+    private constructor();
+    /**
+     * Async factory. Custom transports are loaded via dynamic `import()` so
+     * initialization is unavoidably async. API/Worker bootstrap code should
+     * `await WinstonNexxusLogger.create(...)` in place of `new WinstonNexxusLogger(...)`.
+     */
+    static create(services: NexxusLoggerServices): Promise<WinstonNexxusLogger>;
+    /**
+     * Maps each transport config entry to a constructed Winston transport.
+     * Built-in types are instantiated synchronously; everything else falls
+     * through to `loadCustomTransport`, which dynamically imports the npm
+     * package named by `type`.
+     *
+     * If the config has no transports (undefined or empty array), defaults to
+     * a single Console transport so the logger is never silent.
+     */
+    private static resolveTransports;
+    /**
+     * Dynamically imports the npm package named by `transport.type` and instantiates
+     * its transport class. The class is resolved in priority order:
+     *   1. `mod[transport.export]` if `transport.export` is set in config
+     *   2. `mod.default` if it's a function/class (ESM default export)
+     *   3. The module itself if it's a function/class (CJS `module.exports = Cls`)
+     *
+     * On any failure (package missing, no resolvable class, constructor throws)
+     * we re-wrap as `InvalidConfigException` so the operator sees an actionable
+     * message rather than a raw module-resolution stack trace.
+     */
+    private static loadCustomTransport;
+    log(level: NexxusLoggerLevels, message: string, attributes?: LogAttributes, label?: string): void;
 }
 export {};