@tailor-platform/erp-kit 0.3.0 → 0.4.1

package/src/generator/stub-templates.ts

@@ -0,0 +1,145 @@
+function toPascal(name: string): string {
+  return name.charAt(0).toUpperCase() + name.slice(1);
+}
+
+const templates = {
+  command: {
+    render: (name: string) => {
+      const inputType = `${toPascal(name)}Input`;
+      return `import type { Transaction } from "../generated/kysely-tailordb";
+import { ok, type CommandContext } from "@tailor-platform/erp-kit/module";
+
+export interface ${inputType} {
+  // TODO: define input fields
+}
+
+export async function run(db: Transaction, input: ${inputType}, ctx: CommandContext) {
+  // TODO: implement
+  return ok({});
+}
+`;
+    },
+  },
+  commandTest: {
+    render: (name: string) => {
+      const pascal = toPascal(name);
+      return `import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import { run, ${pascal}Input } from "./${name}";
+import type { CommandContext } from "@tailor-platform/erp-kit/module";
+
+describe("${name} - test scenario", () => {
+  const ctx: CommandContext = {
+    actorId: "test-actor",
+    permissions: ["TODO:${name}"],
+  };
+
+  it("should be implemented", async () => {
+    const { db } = createMockDb<Transaction>();
+    const result = await run(db, {} as ${pascal}Input, ctx);
+    expect(result.ok).toBe(true);
+  });
+});
+`;
+    },
+  },
+  query: {
+    render: (name: string) => {
+      const inputType = `${toPascal(name)}Input`;
+      return `import type { DB } from "../generated/kysely-tailordb";
+import type { ReadonlyDB } from "@tailor-platform/erp-kit/module";
+
+export interface ${inputType} {
+  // TODO: define input fields
+}
+
+export async function run(db: ReadonlyDB<DB>, input: ${inputType}) {
+  // TODO: implement
+  return {};
+}
+`;
+    },
+  },
+  queryTest: {
+    render: (name: string) => {
+      const pascal = toPascal(name);
+      const inputType = `${pascal}Input`;
+      return `import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { DB } from "../generated/kysely-tailordb";
+import { run, type ${inputType} } from "./${name}";
+
+describe("${name}", () => {
+  it("should be implemented", async () => {
+    const { db } = createMockDb<DB>();
+    const result = await run(db, {} as ${inputType});
+    expect(result).toBeDefined();
+  });
+});
+`;
+    },
+  },
+  db: {
+    render: (name: string) => {
+      return `import { db, unsafeAllowAllGqlPermission, unsafeAllowAllTypePermission } from "@tailor-platform/sdk";
+
+export const ${name} = db
+  .type("${toPascal(name)}", {
+    // TODO: define fields
+    ...db.fields.timestamps(),
+  })
+  .permission(unsafeAllowAllTypePermission)
+  .gqlPermission(unsafeAllowAllGqlPermission);
+`;
+    },
+  },
+  resolver: {
+    render: (name: string) => {
+      return `import { createResolver, t } from "@tailor-platform/sdk";
+import { createContext } from "@tailor-platform/erp-kit/app";
+import { getDB } from "@/generated/kysely-tailordb";
+
+export default createResolver({
+  name: "${name}",
+  operation: "mutation",
+  input: {
+    // TODO: define input fields
+  },
+  body: async (context) => {
+    const db = getDB("main-db");
+    return db.transaction().execute(async (trx) => {
+      // TODO: implement
+      return {};
+    });
+  },
+  output: t
+    .object({
+      // TODO: define output fields
+    })
+    .description("${toPascal(name)} response"),
+});
+`;
+    },
+  },
+  resolverTest: {
+    render: (name: string) => {
+      return `import { describe, expect, it } from "vitest";
+
+describe("${name}", () => {
+  it("should be implemented", async () => {
+    const resolver = await import("./${name}");
+    expect(resolver.default).toBeDefined();
+    expect(resolver.default.name).toBe("${name}");
+  });
+});
+`;
+    },
+  },
+} as const;
+
+export type StubType = keyof typeof templates;
+
+export function renderStub(type: StubType, name: string): string {
+  return templates[type].render(name);
+}

package/src/module.ts

@@ -1,5 +1,6 @@
 // shared
 export { defineCommand, type Command } from "./shared/defineCommand";
+export { ok, err, type Result, type ValueOf, type ErrorOf } from "./shared/result";
 export { defineQuery, type Query } from "./shared/defineQuery";
 export { definePermissions } from "./shared/definePermissions";
 export { requirePermission } from "./shared/requirePermission";
@@ -11,12 +12,14 @@ export type {
   PaginationInput,
   PaginatedResult,
 } from "./shared/types";
+export { buildPaginatedResult, DEFAULT_PAGE_SIZE } from "./shared/pagination";
 export type {
   InferSchema,
   Selectable,
   Insertable,
   Updateable,
   FieldsToInsertable,
+  EmptyFields,
 } from "./shared/entityTypes";
 
 // primitives

package/src/modules/audit/README.md

@@ -0,0 +1,46 @@
+# README
+
+## Overview
+
+The Audit module provides a centralized, append-only audit trail for tracking data changes across all ERP modules. It records who or what performed an action, when it occurred, and what data changed — capturing both the old and new values at the field level. The module is designed as cross-cutting infrastructure: other modules emit structured audit events that the Audit module stores, indexes, and exposes for query. All audit entries are append-only and immutable once written, ensuring that stored records cannot be retroactively altered or deleted. Note: because ingestion is eventually consistent and decoupled from the emitting module's transaction, the module provides best-effort delivery — it does not guarantee that every mutation is captured (see [Audit Event Logging](docs/features/audit-event-logging.md) for the ingestion contract and failure semantics).
+
+The module supports both company-scoped entities (e.g., sales orders, invoices) and global entities (e.g., user accounts, currencies) — entries for global entities omit companyId and are queryable without company scope.
+
+Access to audit data and policy management is controlled by explicit permissions. Because audit entries can contain sensitive before/after values, viewing and administering the audit trail requires dedicated privileges separate from the permissions on the audited entities themselves. The module defines four coarse permissions: `viewAuditHistory` (query audit entries and change details), `viewAuditSummary` (view aggregated audit summaries without field-level details), `manageAuditPolicies` (create, update, activate, deactivate, delete audit policies, query policies, and register auditable entities), and `logAuditEvent` (ingest audit events from emitting modules). At runtime, command shells enforce per-command permission keys (e.g., `audit:createAuditPolicy`, `audit:registerAuditableEntity`), and policy query endpoints (`getAuditPolicy`, `listAuditPolicies`) require the coarse `audit:manageAuditPolicies` key directly. The `manageAuditPolicies` alias (defined in `permissions.ts`) expands to both the coarse `manageAuditPolicies` key itself and all per-command keys; the application's RBAC layer should use this alias when populating `ctx.permissions` to ensure both command and query authorization work correctly. Each permission is company-scoped — holders can only access entries and policies for their assigned companies — or global-scoped for company-unscoped entries and policies. The audit module does not define its own roles; it exposes permissions that the application's role-based access control system assigns to roles as needed.
+
+## Key Features
+
+- **Audit Event Logging** — Captures create, update, and delete operations as immutable audit entries with unique eventId, optional correlationId for operation grouping, actor identity (actorType + actorId), timestamp, entity reference, and operation type
+- **Field-Level Change Tracking** — Records old and new values for each changed field within an audit entry, with configurable sensitivity modes (capture, mask, hash, exclude) to protect sensitive data
+- **Audit Policy Configuration** — Allows administrators to define which entities, fields, and operation types are audited, controlling granularity, sensitivity handling, and performance impact
+
+## Module Scope
+
+### In Scope
+
+- Immutable storage of audit log entries (append-only, no update or delete)
+- Field-level change detail recording (old value / new value pairs) with sensitivity-aware value processing
+- Configurable audit policies at entity and field granularity with sensitivity modes
+- Query and filtering of audit logs by actor, entity, record, operation type, and date range
+- Record-level change history retrieval
+- Actor identity capture supporting multiple actor types (USER, SYSTEM, SERVICE) with optional delegation (onBehalfOf)
+- Company-scoped and global (company-unscoped) audit entries
+- Permission-based access control for audit viewing and policy administration
+
+### Out of Scope
+
+- User authentication and session tracking (owned by user-management / infrastructure layer)
+- Compliance framework mapping and automated evidence collection (application-level concern)
+- Anomaly detection, alerting, and real-time notifications
+- Log archival, long-term retention policies, and storage tiering
+- Dashboard visualizations and audit analytics
+
+### Scope Decision Rationale
+
+The module focuses on the foundational audit trail capabilities that all ERP deployments require: capturing changes, storing them immutably once written, and making them queryable. The ingestion contract is best-effort — applications that require guaranteed delivery for strict compliance scenarios should layer an outbox or replay mechanism on top of this module. Authentication logging is excluded because it belongs to the identity/infrastructure layer, not the domain data change layer. Compliance framework mapping, anomaly detection, and retention management are excluded as application-level or operational concerns that can be layered on top of the core audit trail. This separation keeps the module focused, testable, and reusable across different compliance contexts.
+
+## Module Dependencies
+
+- **user-management** — References userId as one type of actorId on audit entries (data reference only; no domain logic dependency)
+- **organization** — References companyId for multi-company scoping of company-bound audit entries (data reference only; companyId is optional for global entities)
+- **all emitting modules** (reverse dependency) — The audit module is cross-cutting: other modules depend on it, not the other way around. Emitting modules register their auditable entities (name, scope, field list) at initialization time and submit structured audit event payloads (including a unique `eventId` for idempotency) after committing their own transactions. The ingestion contract is idempotent on `eventId` for safe retries, and the audit module does not participate in the emitting module's transaction (eventually consistent). See the [Audit Event Logging](docs/features/audit-event-logging.md) feature documentation for the full ingestion contract.

package/src/modules/audit/command/activateAuditPolicy.generated.ts

@@ -0,0 +1,6 @@
+// @generated — do not edit
+import { permissions } from "../lib/permissions.generated";
+import { run } from "./activateAuditPolicy";
+import { defineCommand } from "@tailor-platform/erp-kit/module";
+
+export const activateAuditPolicy = defineCommand(permissions.activateAuditPolicy, run);

package/src/modules/audit/command/activateAuditPolicy.test.ts

@@ -0,0 +1,186 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  PolicyNotFoundError,
+  InvalidStateError,
+  IncompletePolicyError,
+  ConflictingActivePolicyError,
+  EntityTypeNotRegisteredError,
+  UnauthorizedError,
+} from "../lib/errors.generated";
+import { draftPolicy, activePolicy, inactivePolicy, companyBoundEntity } from "../testing/fixtures";
+import { run } from "./activateAuditPolicy";
+import { activateAuditPolicy } from "./activateAuditPolicy.generated";
+import { type CommandContext, InsufficientPermissionError } from "@tailor-platform/erp-kit/module";
+
+const ctx: CommandContext = {
+  actorId: "test-actor",
+  permissions: ["audit:activateAuditPolicy"],
+};
+
+describe("activateAuditPolicy", () => {
+  it("activates DRAFT policy to ACTIVE", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(draftPolicy); // policy lookup
+    spies.select.mockReturnValueOnce(companyBoundEntity); // entity registration check
+    spies.select.mockReturnValueOnce(undefined); // no conflicting policy
+    spies.update.mockReturnValue({ ...draftPolicy, status: "ACTIVE" });
+
+    const result = await run(db, { policyId: "policy-1" }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.policy.status).toBe("ACTIVE");
+    }
+  });
+
+  it("begins audit capture after activation", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(draftPolicy);
+    spies.select.mockReturnValueOnce(companyBoundEntity); // entity registration check
+    spies.select.mockReturnValueOnce(undefined);
+    spies.update.mockReturnValue({ ...draftPolicy, status: "ACTIVE" });
+
+    const result = await run(db, { policyId: "policy-1" }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.policy.status).toBe("ACTIVE");
+    }
+    // Verify that the DB update sets status to ACTIVE, which is the gate for logAuditEvent to capture events
+    expect(spies.set).toHaveBeenCalledWith(expect.objectContaining({ status: "ACTIVE" }));
+    expect(spies.update).toHaveBeenCalledTimes(1);
+  });
+
+  it("rejects activation of ACTIVE policy", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(activePolicy);
+
+    const result = await run(db, { policyId: activePolicy.id }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidStateError);
+    }
+  });
+
+  it("rejects activation of INACTIVE policy", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(inactivePolicy);
+
+    const result = await run(db, { policyId: inactivePolicy.id }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidStateError);
+    }
+  });
+
+  it("rejects activation when conflicting ACTIVE policy exists", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(draftPolicy); // policy lookup
+    spies.select.mockReturnValueOnce(companyBoundEntity); // entity registration check
+    spies.select.mockReturnValueOnce(activePolicy); // conflicting policy
+
+    const result = await run(db, { policyId: "policy-1" }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(ConflictingActivePolicyError);
+    }
+  });
+
+  it("rejects activation when entity name is missing", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const policyNoEntity = { ...draftPolicy, entityName: "" };
+    spies.select.mockReturnValueOnce(policyNoEntity);
+
+    const result = await run(db, { policyId: "policy-1" }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(IncompletePolicyError);
+    }
+  });
+
+  it("rejects activation when operation type is missing", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const policyNoOp = { ...draftPolicy, operationType: "" };
+    spies.select.mockReturnValueOnce(policyNoOp);
+
+    const result = await run(db, { policyId: "policy-1" }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(IncompletePolicyError);
+    }
+  });
+
+  it("rejects when policy does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(db, { policyId: "nonexistent" }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(PolicyNotFoundError);
+    }
+  });
+
+  it("rejects when caller lacks manageAuditPolicies permission", async () => {
+    const { db } = createMockDb<Transaction>();
+    const command = activateAuditPolicy();
+    const noPermCtx: CommandContext = {
+      actorId: "test-actor",
+      permissions: [],
+    };
+
+    const result = await command(db, { policyId: "policy-1" }, noPermCtx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InsufficientPermissionError);
+    }
+  });
+
+  it("rejects when company-scoped caller activates policy for a different company", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(draftPolicy); // policy with companyId: "company-1"
+    const scopedCtx = { ...ctx, companyId: "company-2" };
+
+    const result = await run(db, { policyId: "policy-1" }, scopedCtx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(UnauthorizedError);
+    }
+  });
+
+  it("rejects when global-scoped caller activates company-scoped policy", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(draftPolicy); // policy with companyId: "company-1"
+    const globalCtx = { ...ctx, companyId: null };
+
+    const result = await run(db, { policyId: "policy-1" }, globalCtx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(UnauthorizedError);
+    }
+  });
+
+  it("rejects when target entity is no longer registered", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(draftPolicy); // policy lookup
+    spies.select.mockReturnValueOnce(undefined); // entity not found
+
+    const result = await run(db, { policyId: "policy-1" }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(EntityTypeNotRegisteredError);
+    }
+  });
+});

package/src/modules/audit/command/activateAuditPolicy.ts

@@ -0,0 +1,97 @@
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  PolicyNotFoundError,
+  InvalidStateError,
+  IncompletePolicyError,
+  ConflictingActivePolicyError,
+  EntityTypeNotRegisteredError,
+  UnauthorizedError,
+} from "../lib/errors.generated";
+import { ok, err, type CommandContext } from "@tailor-platform/erp-kit/module";
+
+export interface ActivateAuditPolicyInput {
+  policyId: string;
+}
+
+/**
+ * Function: activateAuditPolicy
+ *
+ * Transitions an audit policy from DRAFT to ACTIVE status, enabling audit
+ * capture for the specified entity, operation type, and scope. Activation is
+ * rejected if a conflicting ACTIVE policy already exists for the same
+ * (entityName, companyId, operationType) combination.
+ */
+export async function run(db: Transaction, input: ActivateAuditPolicyInput, ctx: CommandContext) {
+  const { policyId } = input;
+
+  // 1. Find policy with forUpdate
+  const existing = await db
+    .selectFrom("AuditPolicy")
+    .selectAll()
+    .where("id", "=", policyId)
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (!existing) {
+    return err(new PolicyNotFoundError(policyId));
+  }
+
+  // 2. Scope authorization
+  if (ctx.companyId !== undefined) {
+    if (ctx.companyId !== null && existing.companyId !== ctx.companyId) {
+      return err(new UnauthorizedError(ctx.actorId));
+    }
+    if (ctx.companyId === null && existing.companyId !== null) {
+      return err(new UnauthorizedError(ctx.actorId));
+    }
+  }
+
+  // 3. Must be DRAFT
+  if (existing.status !== "DRAFT") {
+    return err(new InvalidStateError(policyId));
+  }
+
+  // 4. Check required fields
+  if (!existing.entityName || !existing.operationType) {
+    return err(new IncompletePolicyError(policyId));
+  }
+
+  // 5. Verify entity is still registered
+  const entity = await db
+    .selectFrom("AuditableEntity")
+    .selectAll()
+    .where("entityName", "=", existing.entityName)
+    .executeTakeFirst();
+
+  if (!entity) {
+    return err(new EntityTypeNotRegisteredError(existing.entityName));
+  }
+
+  // 6. Check for conflicting ACTIVE policy (forUpdate to prevent concurrent activations)
+  const conflicting = await db
+    .selectFrom("AuditPolicy")
+    .selectAll()
+    .where("entityName", "=", existing.entityName)
+    .where("companyId", existing.companyId ? "=" : "is", existing.companyId)
+    .where("operationType", "=", existing.operationType)
+    .where("status", "=", "ACTIVE")
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (conflicting) {
+    return err(new ConflictingActivePolicyError(policyId));
+  }
+
+  // 5. Set status ACTIVE
+  const policy = await db
+    .updateTable("AuditPolicy")
+    .set({
+      status: "ACTIVE",
+      updatedAt: new Date(),
+    })
+    .where("id", "=", policyId)
+    .returningAll()
+    .executeTakeFirst();
+
+  return ok({ policy: policy! });
+}

package/src/modules/audit/command/createAuditPolicy.generated.ts

@@ -0,0 +1,6 @@
+// @generated — do not edit
+import { permissions } from "../lib/permissions.generated";
+import { run } from "./createAuditPolicy";
+import { defineCommand } from "@tailor-platform/erp-kit/module";
+
+export const createAuditPolicy = defineCommand(permissions.createAuditPolicy, run);