@cullet/erp-core 1.0.1 → 1.0.3

package/package.json

@@ -1,64 +1,64 @@
 {
-  "name": "@cullet/erp-core",
-  "version": "1.0.1",
-  "description": "Core ERP with clean architecture, temporality, policies, and rule sets",
-  "type": "module",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/fabiano-eduardo/cullet.git",
-    "directory": "packages/erp-core"
-  },
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+    "name": "@cullet/erp-core",
+    "version": "1.0.3",
+    "description": "Core ERP with clean architecture, temporality, policies, and rule sets",
+    "type": "module",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/fabiano-eduardo/cullet.git",
+        "directory": "packages/erp-core"
     },
-    "./errors": {
-      "types": "./dist/errors/index.d.ts",
-      "import": "./dist/errors/index.js"
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js"
+        },
+        "./errors": {
+            "types": "./dist/errors/index.d.ts",
+            "import": "./dist/errors/index.js"
+        },
+        "./policies": {
+            "types": "./dist/policies/index.d.ts",
+            "import": "./dist/policies/index.js"
+        },
+        "./policies/engines": {
+            "types": "./dist/policies/engines/index.d.ts",
+            "import": "./dist/policies/engines/index.js"
+        },
+        "./policies/engines/v1/gate": {
+            "types": "./dist/policies/engines/v1/gate/index.d.ts",
+            "import": "./dist/policies/engines/v1/gate/index.js"
+        },
+        "./exceptions/validation-field": {
+            "types": "./dist/exceptions/validation-field.d.ts",
+            "import": "./dist/exceptions/validation-field.js"
+        },
+        "./package.json": "./package.json"
     },
-    "./policies": {
-      "types": "./dist/policies/index.d.ts",
-      "import": "./dist/policies/index.js"
+    "scripts": {
+        "build": "tsdown --config tsdown.config.ts",
+        "dev": "tsdown --config tsdown.config.ts --watch"
     },
-    "./policies/engines": {
-      "types": "./dist/policies/engines/index.d.ts",
-      "import": "./dist/policies/engines/index.js"
+    "files": [
+        "dist",
+        "src",
+        "!src/**/*.spec.ts",
+        "!src/**/*.test.ts",
+        "meta.json",
+        "KIT_CONTEXT.md",
+        "README.md"
+    ],
+    "sideEffects": false,
+    "engines": {
+        "node": ">=18.17"
     },
-    "./policies/engines/v1/gate": {
-      "types": "./dist/policies/engines/v1/gate/index.d.ts",
-      "import": "./dist/policies/engines/v1/gate/index.js"
+    "peerDependencies": {
+        "zod": ">=3.22.0 <5"
     },
-    "./exceptions/validation-field": {
-      "types": "./dist/exceptions/validation-field.d.ts",
-      "import": "./dist/exceptions/validation-field.js"
+    "publishConfig": {
+        "access": "public"
     },
-    "./package.json": "./package.json"
-  },
-  "scripts": {
-    "build": "tsdown --config tsdown.config.ts",
-    "dev": "tsdown --config tsdown.config.ts --watch"
-  },
-  "files": [
-    "dist",
-    "src",
-    "!src/**/*.spec.ts",
-    "!src/**/*.test.ts",
-    "meta.json",
-    "KIT_CONTEXT.md",
-    "README.md"
-  ],
-  "sideEffects": false,
-  "engines": {
-    "node": ">=18.17"
-  },
-  "peerDependencies": {
-    "zod": ">=3.22.0 <5"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "license": "MIT"
+    "license": "MIT"
 }

package/src/core/application/commands/command.ts

@@ -5,7 +5,7 @@ import type { Result } from "../../result/result";
 import { RequestedBy } from "./requested-by";
 
 interface CommandInput {
-  readonly requestedBy: RequestedBy;
+    readonly requestedBy: RequestedBy;
 }
 
 /**
@@ -20,8 +20,8 @@ interface CommandInput {
  */
 @version("1.0")
 abstract class Command<
-  Input extends CommandInput,
-  Output extends Result<unknown, unknown> = Result<void, never>,
+    Input extends CommandInput,
+    Output extends Result<unknown, unknown> = Result<void, never>,
 > extends UseCase<Input, Output> {}
 
 export type { CommandInput };

package/src/core/application/commands/requested-by.ts

@@ -16,81 +16,81 @@ type RequestedByKind = "user" | "system";
 const REQUESTED_BY_FIELD = ValidationField.of("requestedBy");
 
 const UUID_PATTERN =
-  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+    /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
 // system:<job> where <job> starts with a lowercase letter and may have hyphens between segments
 const SYSTEM_IDENTITY_PATTERN = /^system:[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
 
 class RequestedBy {
-  readonly kind: RequestedByKind;
-  readonly raw: string;
-
-  private constructor(kind: RequestedByKind, raw: string) {
-    this.kind = kind;
-    this.raw = raw;
-    Object.freeze(this);
-  }
-
-  /** Builds from a human user ID (must be a UUID). */
-  static fromUser(userId: string): RequestedBy {
-    if (!UUID_PATTERN.test(userId)) {
-      throw new InvalidValueException(
-        REQUESTED_BY_FIELD,
-        ValidationCode.INVALID_FORMAT,
-        `requestedBy: user identity must be a UUID, got "${userId}"`,
-      );
-    }
+    readonly kind: RequestedByKind;
+    readonly raw: string;
 
-    return new RequestedBy("user", userId);
-  }
-
-  /**
-   * Builds from a system identity.
-   * Only accepts the format "system:<job>", where <job> matches [a-z][a-z0-9]*(-[a-z0-9]+)*.
-   */
-  static fromSystem(systemIdentity: string): RequestedBy {
-    if (!SYSTEM_IDENTITY_PATTERN.test(systemIdentity)) {
-      throw new InvalidValueException(
-        REQUESTED_BY_FIELD,
-        ValidationCode.INVALID_FORMAT,
-        `requestedBy: system identity must match "system:<job>" (e.g. "system:late-fee-job"), got "${systemIdentity}"`,
-      );
+    private constructor(kind: RequestedByKind, raw: string) {
+        this.kind = kind;
+        this.raw = raw;
+        Object.freeze(this);
     }
 
-    return new RequestedBy("system", systemIdentity);
-  }
-
-  /**
-   * Infers the kind from the raw value.
-   * Use when the origin (user vs system) is not known at the call-site.
-   */
-  static parse(raw: string): RequestedBy {
-    if (UUID_PATTERN.test(raw)) {
-      return new RequestedBy("user", raw);
+    /** Builds from a human user ID (must be a UUID). */
+    static fromUser(userId: string): RequestedBy {
+        if (!UUID_PATTERN.test(userId)) {
+            throw new InvalidValueException(
+                REQUESTED_BY_FIELD,
+                ValidationCode.INVALID_FORMAT,
+                `requestedBy: user identity must be a UUID, got "${userId}"`,
+            );
+        }
+
+        return new RequestedBy("user", userId);
     }
 
-    if (SYSTEM_IDENTITY_PATTERN.test(raw)) {
-      return new RequestedBy("system", raw);
+    /**
+     * Builds from a system identity.
+     * Only accepts the format "system:<job>", where <job> matches [a-z][a-z0-9]*(-[a-z0-9]+)*.
+     */
+    static fromSystem(systemIdentity: string): RequestedBy {
+        if (!SYSTEM_IDENTITY_PATTERN.test(systemIdentity)) {
+            throw new InvalidValueException(
+                REQUESTED_BY_FIELD,
+                ValidationCode.INVALID_FORMAT,
+                `requestedBy: system identity must match "system:<job>" (e.g. "system:late-fee-job"), got "${systemIdentity}"`,
+            );
+        }
+
+        return new RequestedBy("system", systemIdentity);
     }
 
-    throw new InvalidValueException(
-      REQUESTED_BY_FIELD,
-      ValidationCode.INVALID_FORMAT,
-      `requestedBy must be a UUID (user) or "system:<job>" (system), got "${raw}"`,
-    );
-  }
+    /**
+     * Infers the kind from the raw value.
+     * Use when the origin (user vs system) is not known at the call-site.
+     */
+    static parse(raw: string): RequestedBy {
+        if (UUID_PATTERN.test(raw)) {
+            return new RequestedBy("user", raw);
+        }
+
+        if (SYSTEM_IDENTITY_PATTERN.test(raw)) {
+            return new RequestedBy("system", raw);
+        }
+
+        throw new InvalidValueException(
+            REQUESTED_BY_FIELD,
+            ValidationCode.INVALID_FORMAT,
+            `requestedBy must be a UUID (user) or "system:<job>" (system), got "${raw}"`,
+        );
+    }
 
-  get isUser(): boolean {
-    return this.kind === "user";
-  }
+    get isUser(): boolean {
+        return this.kind === "user";
+    }
 
-  get isSystem(): boolean {
-    return this.kind === "system";
-  }
+    get isSystem(): boolean {
+        return this.kind === "system";
+    }
 
-  toString(): string {
-    return this.raw;
-  }
+    toString(): string {
+        return this.raw;
+    }
 }
 
 export type { RequestedByKind };

package/src/core/application/index.ts

@@ -1,31 +1,31 @@
 export type { CommandInput } from "./commands";
 export { Command } from "./commands";
 export type {
-  LogPayload,
-  LoggerPort,
-  MetricLabels,
-  MetricsPort,
-  PolicyEvaluationError,
-  PolicyEvaluationInput,
-  PolicyEvaluationOutput,
-  PolicyPort,
-  Repository,
-  TraceAttributeValue,
-  TraceSpan,
-  TracerPort,
-  TemporalHistory,
-  TemporalRepository,
+    LogPayload,
+    LoggerPort,
+    MetricLabels,
+    MetricsPort,
+    PolicyEvaluationError,
+    PolicyEvaluationInput,
+    PolicyEvaluationOutput,
+    PolicyPort,
+    Repository,
+    TraceAttributeValue,
+    TraceSpan,
+    TracerPort,
+    TemporalHistory,
+    TemporalRepository,
 } from "./ports";
 export { mapPolicyEvaluationError } from "./policy-error-mapper";
 export type { CacheStrategy, Page } from "./queries";
 export { Query } from "./queries";
 export {
-  assertTemporalContext,
-  createTemporalContext,
-  type CreateTemporalContextInput,
-  type TemporalContext,
-  type TemporalizedContextSeed,
-  TemporalUseCase,
-  type TemporalUseCaseInput,
+    assertTemporalContext,
+    createTemporalContext,
+    type CreateTemporalContextInput,
+    type TemporalContext,
+    type TemporalizedContextSeed,
+    TemporalUseCase,
+    type TemporalUseCaseInput,
 } from "./temporal";
 export { type MaybePromise, UseCase } from "./use-case";

package/src/core/application/policy-error-mapper.ts

@@ -1,60 +1,60 @@
 import {
-  type AppError,
-  BusinessRuleViolationError,
-  NotFoundError,
-  UnexpectedError,
+    type AppError,
+    BusinessRuleViolationError,
+    NotFoundError,
+    UnexpectedError,
 } from "../errors";
 import type { PolicyEvaluationError } from "../policies";
 
 export function mapPolicyEvaluationError(err: PolicyEvaluationError): AppError {
-  switch (err.kind) {
-    case "INVALID_CONTEXT":
-      return new BusinessRuleViolationError(
-        `policy.${err.stage.toLowerCase()}`,
-        err.message,
-        { policyKey: err.policyKey, stage: err.stage },
-        { cause: err.cause },
-      );
-    case "INVALID_POLICY_KEY":
-      return new BusinessRuleViolationError(
-        "policy.invalid_key",
-        err.message,
-        { rawPolicyKey: err.rawPolicyKey },
-        { cause: err.cause },
-      );
-    case "POLICY_NOT_FOUND":
-      return new NotFoundError(
-        "Policy",
-        { policyKey: err.policyKey },
-        { cause: err.cause },
-      );
-    case "POLICY_DEFINITION_NOT_FOUND":
-      return new NotFoundError(
-        "PolicyDefinition",
-        {
-          policyKey: err.policyKey,
-          contextVersion: err.contextVersion,
-          asOf: err.asOf.toISOString(),
-        },
-        { cause: err.cause },
-      );
-    case "POLICY_VARIANT_NOT_FOUND":
-      return new NotFoundError(
-        "PolicyVariant",
-        {
-          policyKey: err.policyKey,
-          policyKind: err.policyKind,
-          payloadSchemaVersion: err.payloadSchemaVersion,
-        },
-        { cause: err.cause },
-      );
-    case "ENGINE_FAILURE":
-      return new UnexpectedError(err.message, err.cause, {
-        metadata: {
-          policyKey: err.policyKey,
-          engine: err.engine,
-          engineVersion: err.engineVersion,
-        },
-      });
-  }
+    switch (err.kind) {
+        case "INVALID_CONTEXT":
+            return new BusinessRuleViolationError(
+                `policy.${err.stage.toLowerCase()}`,
+                err.message,
+                { policyKey: err.policyKey, stage: err.stage },
+                { cause: err.cause },
+            );
+        case "INVALID_POLICY_KEY":
+            return new BusinessRuleViolationError(
+                "policy.invalid_key",
+                err.message,
+                { rawPolicyKey: err.rawPolicyKey },
+                { cause: err.cause },
+            );
+        case "POLICY_NOT_FOUND":
+            return new NotFoundError(
+                "Policy",
+                { policyKey: err.policyKey },
+                { cause: err.cause },
+            );
+        case "POLICY_DEFINITION_NOT_FOUND":
+            return new NotFoundError(
+                "PolicyDefinition",
+                {
+                    policyKey: err.policyKey,
+                    contextVersion: err.contextVersion,
+                    asOf: err.asOf.toISOString(),
+                },
+                { cause: err.cause },
+            );
+        case "POLICY_VARIANT_NOT_FOUND":
+            return new NotFoundError(
+                "PolicyVariant",
+                {
+                    policyKey: err.policyKey,
+                    policyKind: err.policyKind,
+                    payloadSchemaVersion: err.payloadSchemaVersion,
+                },
+                { cause: err.cause },
+            );
+        case "ENGINE_FAILURE":
+            return new UnexpectedError(err.message, err.cause, {
+                metadata: {
+                    policyKey: err.policyKey,
+                    engine: err.engine,
+                    engineVersion: err.engineVersion,
+                },
+            });
+    }
 }

package/src/core/application/ports/index.ts

@@ -1,14 +1,14 @@
 export type { LogPayload, LoggerPort } from "./logger.port";
 export type { MetricLabels, MetricsPort } from "./metrics.port";
 export type {
-  PolicyEvaluationError,
-  PolicyEvaluationInput,
-  PolicyEvaluationOutput,
-  PolicyPort,
+    PolicyEvaluationError,
+    PolicyEvaluationInput,
+    PolicyEvaluationOutput,
+    PolicyPort,
 } from "./policy-port";
 export type { Repository } from "./repository.port";
 export type {
-  TemporalHistory,
-  TemporalRepository,
+    TemporalHistory,
+    TemporalRepository,
 } from "./temporal-repository.port";
 export type { TraceAttributeValue, TraceSpan, TracerPort } from "./tracer.port";

package/src/core/application/ports/logger.port.ts

@@ -1,10 +1,10 @@
 type LogPayload = Record<string, unknown>;
 
 interface LoggerPort {
-  debug(message: string, payload?: LogPayload): void;
-  info(message: string, payload?: LogPayload): void;
-  warn(message: string, payload?: LogPayload): void;
-  error(message: string, payload?: LogPayload): void;
+    debug(message: string, payload?: LogPayload): void;
+    info(message: string, payload?: LogPayload): void;
+    warn(message: string, payload?: LogPayload): void;
+    error(message: string, payload?: LogPayload): void;
 }
 
 export type { LogPayload, LoggerPort };

package/src/core/application/ports/metrics.port.ts

@@ -1,9 +1,9 @@
 type MetricLabels = Readonly<Record<string, string | number | boolean>>;
 
 interface MetricsPort {
-  counter(name: string, value: number, labels?: MetricLabels): void;
-  gauge(name: string, value: number, labels?: MetricLabels): void;
-  histogram(name: string, value: number, labels?: MetricLabels): void;
+    counter(name: string, value: number, labels?: MetricLabels): void;
+    gauge(name: string, value: number, labels?: MetricLabels): void;
+    histogram(name: string, value: number, labels?: MetricLabels): void;
 }
 
 export type { MetricLabels, MetricsPort };

package/src/core/application/ports/policy-port.ts

@@ -7,14 +7,14 @@ type PolicyEvaluationOutput = PolicyEvaluationResult;
 type PolicyEvaluationError = AppError;
 
 interface PolicyPort {
-  evaluate(
-    input: PolicyEvaluationInput,
-  ): Promise<Result<PolicyEvaluationOutput, PolicyEvaluationError>>;
+    evaluate(
+        input: PolicyEvaluationInput,
+    ): Promise<Result<PolicyEvaluationOutput, PolicyEvaluationError>>;
 }
 
 export type {
-  PolicyEvaluationError,
-  PolicyEvaluationInput,
-  PolicyEvaluationOutput,
-  PolicyPort,
+    PolicyEvaluationError,
+    PolicyEvaluationInput,
+    PolicyEvaluationOutput,
+    PolicyPort,
 };

package/src/core/application/ports/repository.port.ts

@@ -1,7 +1,7 @@
 interface Repository<TEntity, TId> {
-  findById(id: TId): Promise<TEntity | null>;
-  save(entity: TEntity): Promise<void>;
-  delete(id: TId): Promise<void>;
+    findById(id: TId): Promise<TEntity | null>;
+    save(entity: TEntity): Promise<void>;
+    delete(id: TId): Promise<void>;
 }
 
 export type { Repository };

package/src/core/application/ports/temporal-repository.port.ts

@@ -5,10 +5,10 @@ import type { Repository } from "./repository.port";
 type TemporalHistory<TEntity> = readonly TemporalSnapshot<TEntity>[];
 
 interface TemporalRepository<TEntity, TId> extends Repository<TEntity, TId> {
-  findAsOf(id: TId, asOf: Date): Promise<TEntity | null>;
-  findAtTransaction(id: TId, txTime: Date): Promise<TEntity | null>;
-  findHistory(id: TId): Promise<TemporalHistory<TEntity>>;
-  save(entity: TEntity, validFrom?: Date): Promise<void>;
+    findAsOf(id: TId, asOf: Date): Promise<TEntity | null>;
+    findAtTransaction(id: TId, txTime: Date): Promise<TEntity | null>;
+    findHistory(id: TId): Promise<TemporalHistory<TEntity>>;
+    save(entity: TEntity, validFrom?: Date): Promise<void>;
 }
 
 export type { TemporalHistory, TemporalRepository };

package/src/core/application/ports/tracer.port.ts

@@ -1,16 +1,16 @@
 type TraceAttributeValue = string | number | boolean;
 
 interface TraceSpan {
-  setAttribute(key: string, value: TraceAttributeValue): void;
-  recordException(error: unknown): void;
-  end(): void;
+    setAttribute(key: string, value: TraceAttributeValue): void;
+    recordException(error: unknown): void;
+    end(): void;
 }
 
 interface TracerPort {
-  startSpan(
-    name: string,
-    attributes?: Record<string, TraceAttributeValue>,
-  ): TraceSpan;
+    startSpan(
+        name: string,
+        attributes?: Record<string, TraceAttributeValue>,
+    ): TraceSpan;
 }
 
 export type { TraceAttributeValue, TraceSpan, TracerPort };

package/src/core/application/queries/query.ts

@@ -8,10 +8,10 @@ import type { Result } from "../../result/result";
  * Use as `Output` when the query returns a collection with pagination metadata.
  */
 interface Page<T> {
-  readonly items: readonly T[];
-  readonly total: number;
-  readonly page: number;
-  readonly pageSize: number;
+    readonly items: readonly T[];
+    readonly total: number;
+    readonly page: number;
+    readonly pageSize: number;
 }
 
 /**
@@ -19,9 +19,9 @@ interface Page<T> {
  * Infrastructure reads this value to decide whether and how to cache the result.
  */
 type CacheStrategy =
-  | { readonly kind: "NO_CACHE" }
-  | { readonly kind: "TIME_TO_LIVE"; readonly ttlMs: number }
-  | { readonly kind: "STALE_WHILE_REVALIDATE"; readonly ttlMs: number };
+    | { readonly kind: "NO_CACHE" }
+    | { readonly kind: "TIME_TO_LIVE"; readonly ttlMs: number }
+    | { readonly kind: "STALE_WHILE_REVALIDATE"; readonly ttlMs: number };
 
 type QueryOutput = object | string | number | boolean | bigint | symbol | null;
 
@@ -40,13 +40,13 @@ type QueryOutput = object | string | number | boolean | bigint | symbol | null;
  */
 @version("1.0")
 abstract class Query<
-  Input = void,
-  Data extends QueryOutput = never,
-  Failure = AppError,
+    Input = void,
+    Data extends QueryOutput = never,
+    Failure = AppError,
 > extends UseCase<Input, Result<Data, Failure>> {
-  protected cacheStrategy(): CacheStrategy {
-    return { kind: "NO_CACHE" };
-  }
+    protected cacheStrategy(): CacheStrategy {
+        return { kind: "NO_CACHE" };
+    }
 }
 
 export type { CacheStrategy, Page, QueryOutput };

package/src/core/application/temporal/index.ts

@@ -1,11 +1,11 @@
 export {
-  assertTemporalContext,
-  createTemporalContext,
-  type CreateTemporalContextInput,
-  type TemporalContext,
+    assertTemporalContext,
+    createTemporalContext,
+    type CreateTemporalContextInput,
+    type TemporalContext,
 } from "./temporal-context";
 export {
-  type TemporalUseCaseInput,
-  type TemporalizedContextSeed,
-  TemporalUseCase,
+    type TemporalUseCaseInput,
+    type TemporalizedContextSeed,
+    TemporalUseCase,
 } from "./temporal-use-case";