@tailor-platform/erp-kit 0.3.0 → 0.4.1

package/src/modules/audit/lib/permissions.generated.ts

@@ -0,0 +1,14 @@
+// @generated — do not edit
+import { definePermissions } from "@tailor-platform/erp-kit/module";
+
+export const { permissions, own, all } = definePermissions("audit", [
+  "activateAuditPolicy",
+  "createAuditPolicy",
+  "deactivateAuditPolicy",
+  "deleteAuditPolicy",
+  "logAuditEvent",
+  "reactivateAuditPolicy",
+  "registerAuditableEntity",
+  "replaceAuditPolicy",
+  "updateAuditPolicy",
+] as const);

package/src/modules/audit/lib/types.ts

@@ -0,0 +1,33 @@
+import type { DB } from "../generated/kysely-tailordb";
+import type {
+  InferSchema,
+  Selectable,
+  Insertable,
+  Updateable,
+} from "@tailor-platform/erp-kit/module";
+
+export type Schema = InferSchema<DB>;
+
+export type AuditEntry<T extends { AuditEntry: object }> = Selectable<T["AuditEntry"]>;
+export type AuditEntryCreate<T extends { AuditEntry: object }> = Insertable<T["AuditEntry"]>;
+
+export type AuditPolicy<T extends { AuditPolicy: object }> = Selectable<T["AuditPolicy"]>;
+export type AuditPolicyCreate<T extends { AuditPolicy: object }> = Insertable<T["AuditPolicy"]>;
+export type AuditPolicyUpdate<T extends { AuditPolicy: object }> = Updateable<T["AuditPolicy"]>;
+
+export type AuditableEntity<T extends { AuditableEntity: object }> = Selectable<
+  T["AuditableEntity"]
+>;
+export type AuditableEntityCreate<T extends { AuditableEntity: object }> = Insertable<
+  T["AuditableEntity"]
+>;
+
+export type ChangeDetail<T extends { ChangeDetail: object }> = Selectable<T["ChangeDetail"]>;
+export type ChangeDetailCreate<T extends { ChangeDetail: object }> = Insertable<T["ChangeDetail"]>;
+
+export type PolicyFieldRule<T extends { PolicyFieldRule: object }> = Selectable<
+  T["PolicyFieldRule"]
+>;
+export type PolicyFieldRuleCreate<T extends { PolicyFieldRule: object }> = Insertable<
+  T["PolicyFieldRule"]
+>;

package/src/modules/audit/module.ts

@@ -0,0 +1,57 @@
+import type { TailorAnyDBType } from "@tailor-platform/sdk";
+import { registerAuditableEntity } from "./command/registerAuditableEntity.generated";
+import { createAuditPolicy } from "./command/createAuditPolicy.generated";
+import { updateAuditPolicy } from "./command/updateAuditPolicy.generated";
+import { activateAuditPolicy } from "./command/activateAuditPolicy.generated";
+import { deactivateAuditPolicy } from "./command/deactivateAuditPolicy.generated";
+import { reactivateAuditPolicy } from "./command/reactivateAuditPolicy.generated";
+import { replaceAuditPolicy } from "./command/replaceAuditPolicy.generated";
+import { deleteAuditPolicy } from "./command/deleteAuditPolicy.generated";
+import { logAuditEvent } from "./command/logAuditEvent.generated";
+import { getAuditEntry } from "./query/getAuditEntry.generated";
+import { getAuditPolicy } from "./query/getAuditPolicy.generated";
+import { getAuditSummary } from "./query/getAuditSummary.generated";
+import { getChangeDetails } from "./query/getChangeDetails.generated";
+import { listAuditPolicies } from "./query/listAuditPolicies.generated";
+import { searchAuditEntries } from "./query/searchAuditEntries.generated";
+import { auditableEntity } from "./db/auditableEntity";
+import { createAuditPolicyType } from "./db/auditPolicy";
+import { policyFieldRule } from "./db/policyFieldRule";
+import { createAuditEntryType } from "./db/auditEntry";
+import { changeDetail } from "./db/changeDetail";
+
+export interface DefineModuleParams {
+  organization?: {
+    db: { company: TailorAnyDBType };
+  };
+}
+
+export const defineModule = (params?: DefineModuleParams) => {
+  const companyType = params?.organization?.db.company;
+
+  const auditPolicy = createAuditPolicyType({ companyType });
+  const auditEntry = createAuditEntryType({ companyType });
+
+  return {
+    db: { auditableEntity, auditPolicy, policyFieldRule, auditEntry, changeDetail },
+    commands: {
+      registerAuditableEntity: registerAuditableEntity(),
+      createAuditPolicy: createAuditPolicy(),
+      updateAuditPolicy: updateAuditPolicy(),
+      activateAuditPolicy: activateAuditPolicy(),
+      deactivateAuditPolicy: deactivateAuditPolicy(),
+      reactivateAuditPolicy: reactivateAuditPolicy(),
+      replaceAuditPolicy: replaceAuditPolicy(),
+      deleteAuditPolicy: deleteAuditPolicy(),
+      logAuditEvent: logAuditEvent(),
+    },
+    queries: {
+      getAuditEntry,
+      getAuditPolicy,
+      getAuditSummary,
+      getChangeDetails,
+      listAuditPolicies,
+      searchAuditEntries,
+    },
+  };
+};

package/src/modules/audit/permissions.ts

@@ -0,0 +1,39 @@
+import { definePermissions } from "@tailor-platform/erp-kit/module";
+
+export const { permissions, own, all, aliases } = definePermissions(
+  "audit",
+  [
+    // Coarse query permissions
+    "viewAuditHistory",
+    "viewAuditSummary",
+    "manageAuditPolicies",
+    // Per-command permissions (included so aliases can map coarse → per-command)
+    "activateAuditPolicy",
+    "createAuditPolicy",
+    "deactivateAuditPolicy",
+    "deleteAuditPolicy",
+    "logAuditEvent",
+    "reactivateAuditPolicy",
+    "registerAuditableEntity",
+    "replaceAuditPolicy",
+    "updateAuditPolicy",
+  ] as const,
+  {
+    aliases: {
+      manageAuditPolicies: [
+        "manageAuditPolicies",
+        "activateAuditPolicy",
+        "createAuditPolicy",
+        "deactivateAuditPolicy",
+        "deleteAuditPolicy",
+        "reactivateAuditPolicy",
+        "registerAuditableEntity",
+        "replaceAuditPolicy",
+        "updateAuditPolicy",
+      ],
+      viewAuditHistory: ["viewAuditHistory"],
+      viewAuditSummary: ["viewAuditSummary"],
+      logAuditEvent: ["logAuditEvent"],
+    },
+  },
+);

package/src/modules/audit/query/getAuditEntry.generated.ts

@@ -0,0 +1,5 @@
+// @generated — do not edit
+import { run } from "./getAuditEntry";
+import { defineQuery } from "@tailor-platform/erp-kit/module";
+
+export const getAuditEntry = defineQuery(run);

package/src/modules/audit/query/getAuditEntry.test.ts

@@ -0,0 +1,123 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { DB } from "../generated/kysely-tailordb";
+import { UnauthorizedError } from "../lib/errors.generated";
+import { baseAuditEntry, globalAuditEntry } from "../testing/fixtures";
+import { run } from "./getAuditEntry";
+import { InsufficientPermissionError } from "@tailor-platform/erp-kit/module";
+import type { QueryContext } from "@tailor-platform/erp-kit/module";
+
+const ctx: QueryContext = {
+  actorId: "test-actor",
+  permissions: ["audit:viewAuditHistory"],
+};
+
+describe("getAuditEntry", () => {
+  it("returns audit entry when found by id", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(baseAuditEntry);
+
+    const result = await run(db, { id: "entry-1" }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.auditEntry).toEqual(baseAuditEntry);
+    }
+  });
+
+  it("returns null when audit entry not found", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(db, { id: "nonexistent" }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.auditEntry).toBeNull();
+    }
+  });
+
+  it("returns entry with all fields populated", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(globalAuditEntry);
+
+    const result = await run(db, { id: globalAuditEntry.id }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      const entry = result.value.auditEntry;
+      expect(entry).toEqual(globalAuditEntry);
+      expect(entry!.correlationId).toBe("corr-uuid-1");
+      expect(entry!.ipAddress).toBe("192.168.1.1");
+      expect(entry!.userAgent).toBe("AuditBot/1.0");
+      expect(entry!.sessionId).toBe("session-1");
+      expect(entry!.requestId).toBe("req-1");
+      expect(entry!.onBehalfOf).toBe("user-3");
+    }
+  });
+
+  it("returns company-scoped entry when caller has matching company permission", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(baseAuditEntry);
+    const companyScopedCtx: QueryContext = {
+      actorId: "test-actor",
+      permissions: ["audit:viewAuditHistory"],
+      companyId: "company-1",
+    };
+
+    const result = await run(db, { id: baseAuditEntry.id }, companyScopedCtx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.auditEntry).toEqual(baseAuditEntry);
+      expect(result.value.auditEntry!.companyId).toBe("company-1");
+    }
+  });
+
+  it("returns global entry when caller has global-scoped permission", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(globalAuditEntry);
+    const globalScopedCtx: QueryContext = {
+      actorId: "test-actor",
+      permissions: ["audit:viewAuditHistory"],
+      companyId: null,
+    };
+
+    const result = await run(db, { id: globalAuditEntry.id }, globalScopedCtx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.auditEntry).toEqual(globalAuditEntry);
+      expect(result.value.auditEntry!.companyId).toBeNull();
+    }
+  });
+
+  it("rejects when caller lacks viewAuditHistory permission", async () => {
+    const { db } = createMockDb<DB>();
+    const noPermsCtx: QueryContext = { actorId: "test-actor", permissions: [] };
+
+    const result = await run(db, { id: "entry-1" }, noPermsCtx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InsufficientPermissionError);
+    }
+  });
+
+  it("rejects when caller lacks permission for entry's company scope", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(baseAuditEntry); // entry with companyId: "company-1"
+    const scopedCtx: QueryContext = {
+      actorId: "test-actor",
+      permissions: ["audit:viewAuditHistory"],
+      companyId: "company-2", // different company
+    };
+
+    const result = await run(db, { id: baseAuditEntry.id }, scopedCtx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(UnauthorizedError);
+    }
+  });
+});

package/src/modules/audit/query/getAuditEntry.ts

@@ -0,0 +1,42 @@
+import type { DB } from "../generated/kysely-tailordb";
+import { UnauthorizedError } from "../lib/errors.generated";
+import {
+  ok,
+  err,
+  requirePermission,
+  type ReadonlyDB,
+  type QueryContext,
+} from "@tailor-platform/erp-kit/module";
+
+export interface GetAuditEntryInput {
+  id: string;
+}
+
+export async function run(db: ReadonlyDB<DB>, input: GetAuditEntryInput, ctx: QueryContext) {
+  const permCheck = requirePermission(ctx, "audit:viewAuditHistory");
+  if (!permCheck.ok) return permCheck;
+
+  const auditEntry = await db
+    .selectFrom("AuditEntry")
+    .selectAll()
+    .where("id", "=", input.id)
+    .executeTakeFirst();
+
+  if (auditEntry) {
+    const scopeErr = checkScopeAuthorization(auditEntry.companyId, ctx);
+    if (scopeErr) return scopeErr;
+  }
+
+  return ok({ auditEntry: auditEntry ?? null });
+}
+
+function checkScopeAuthorization(entityCompanyId: string | null, ctx: QueryContext) {
+  if (ctx.companyId === undefined) return null;
+  if (ctx.companyId === null && entityCompanyId !== null) {
+    return err(new UnauthorizedError(ctx.actorId));
+  }
+  if (ctx.companyId !== null && entityCompanyId !== ctx.companyId) {
+    return err(new UnauthorizedError(ctx.actorId));
+  }
+  return null;
+}

package/src/modules/audit/query/getAuditPolicy.generated.ts

@@ -0,0 +1,5 @@
+// @generated — do not edit
+import { run } from "./getAuditPolicy";
+import { defineQuery } from "@tailor-platform/erp-kit/module";
+
+export const getAuditPolicy = defineQuery(run);

package/src/modules/audit/query/getAuditPolicy.test.ts

@@ -0,0 +1,169 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { DB } from "../generated/kysely-tailordb";
+import { UnauthorizedError } from "../lib/errors.generated";
+import {
+  draftPolicy,
+  activePolicy,
+  inactivePolicy,
+  globalActivePolicy,
+  captureFieldRule,
+  maskFieldRule,
+} from "../testing/fixtures";
+import { run } from "./getAuditPolicy";
+import { InsufficientPermissionError } from "@tailor-platform/erp-kit/module";
+import type { QueryContext } from "@tailor-platform/erp-kit/module";
+
+const ctx: QueryContext = {
+  actorId: "test-actor",
+  permissions: ["audit:manageAuditPolicies"],
+};
+
+describe("getAuditPolicy", () => {
+  it("returns audit policy when found by id", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(activePolicy);
+    spies.select.mockReturnValueOnce([captureFieldRule, maskFieldRule]);
+
+    const result = await run(db, { id: activePolicy.id }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.policy).toEqual(activePolicy);
+    }
+  });
+
+  it("returns null when audit policy not found", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(db, { id: "nonexistent" }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.policy).toBeNull();
+      expect(result.value.fieldRules).toEqual([]);
+    }
+  });
+
+  it("returns DRAFT policy", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(draftPolicy);
+    spies.select.mockReturnValueOnce([]);
+
+    const result = await run(db, { id: draftPolicy.id }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.policy).toEqual(draftPolicy);
+      expect(result.value.policy!.status).toBe("DRAFT");
+    }
+  });
+
+  it("returns ACTIVE policy", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(activePolicy);
+    spies.select.mockReturnValueOnce([captureFieldRule]);
+
+    const result = await run(db, { id: activePolicy.id }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.policy).toEqual(activePolicy);
+      expect(result.value.policy!.status).toBe("ACTIVE");
+    }
+  });
+
+  it("returns INACTIVE policy", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(inactivePolicy);
+    spies.select.mockReturnValueOnce([]);
+
+    const result = await run(db, { id: inactivePolicy.id }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.policy).toEqual(inactivePolicy);
+      expect(result.value.policy!.status).toBe("INACTIVE");
+    }
+  });
+
+  it("includes associated PolicyFieldRules in response", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(activePolicy);
+    spies.select.mockReturnValueOnce([captureFieldRule, maskFieldRule]);
+
+    const result = await run(db, { id: activePolicy.id }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.fieldRules).toEqual([captureFieldRule, maskFieldRule]);
+      expect(result.value.fieldRules).toHaveLength(2);
+    }
+  });
+
+  it("returns global policy when caller has global-scoped permission", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(globalActivePolicy);
+    spies.select.mockReturnValueOnce([]);
+    const globalScopedCtx: QueryContext = {
+      actorId: "test-actor",
+      permissions: ["audit:manageAuditPolicies"],
+      companyId: null,
+    };
+
+    const result = await run(db, { id: globalActivePolicy.id }, globalScopedCtx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.policy).toEqual(globalActivePolicy);
+      expect(result.value.policy!.companyId).toBeNull();
+    }
+  });
+
+  it("rejects when caller lacks manageAuditPolicies permission", async () => {
+    const { db } = createMockDb<DB>();
+    const noPermsCtx: QueryContext = { actorId: "test-actor", permissions: [] };
+
+    const result = await run(db, { id: activePolicy.id }, noPermsCtx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InsufficientPermissionError);
+    }
+  });
+
+  it("rejects when caller lacks permission for policy's company scope", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(activePolicy); // companyId: "company-1"
+    const scopedCtx: QueryContext = {
+      actorId: "test-actor",
+      permissions: ["audit:manageAuditPolicies"],
+      companyId: "company-2",
+    };
+
+    const result = await run(db, { id: activePolicy.id }, scopedCtx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(UnauthorizedError);
+    }
+  });
+
+  it("rejects when global-scoped caller retrieves company-scoped policy", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(activePolicy); // companyId: "company-1"
+    const globalCtx: QueryContext = {
+      actorId: "test-actor",
+      permissions: ["audit:manageAuditPolicies"],
+      companyId: null,
+    };
+
+    const result = await run(db, { id: activePolicy.id }, globalCtx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(UnauthorizedError);
+    }
+  });
+});

package/src/modules/audit/query/getAuditPolicy.ts

@@ -0,0 +1,48 @@
+import type { DB } from "../generated/kysely-tailordb";
+import { UnauthorizedError } from "../lib/errors.generated";
+import {
+  ok,
+  err,
+  requirePermission,
+  type ReadonlyDB,
+  type QueryContext,
+} from "@tailor-platform/erp-kit/module";
+
+export interface GetAuditPolicyInput {
+  id: string;
+}
+
+export async function run(db: ReadonlyDB<DB>, input: GetAuditPolicyInput, ctx: QueryContext) {
+  const permCheck = requirePermission(ctx, "audit:manageAuditPolicies");
+  if (!permCheck.ok) return permCheck;
+
+  const policy = await db
+    .selectFrom("AuditPolicy")
+    .selectAll()
+    .where("id", "=", input.id)
+    .executeTakeFirst();
+
+  if (!policy) return ok({ policy: null, fieldRules: [] });
+
+  const scopeErr = checkScopeAuthorization(policy.companyId, ctx);
+  if (scopeErr) return scopeErr;
+
+  const fieldRules = await db
+    .selectFrom("PolicyFieldRule")
+    .selectAll()
+    .where("auditPolicyId", "=", policy.id)
+    .execute();
+
+  return ok({ policy, fieldRules });
+}
+
+function checkScopeAuthorization(entityCompanyId: string | null, ctx: QueryContext) {
+  if (ctx.companyId === undefined) return null;
+  if (ctx.companyId === null && entityCompanyId !== null) {
+    return err(new UnauthorizedError(ctx.actorId));
+  }
+  if (ctx.companyId !== null && entityCompanyId !== ctx.companyId) {
+    return err(new UnauthorizedError(ctx.actorId));
+  }
+  return null;
+}

package/src/modules/audit/query/getAuditSummary.generated.ts

@@ -0,0 +1,5 @@
+// @generated — do not edit
+import { run } from "./getAuditSummary";
+import { defineQuery } from "@tailor-platform/erp-kit/module";
+
+export const getAuditSummary = defineQuery(run);