@tailor-platform/erp-kit 0.3.0 → 0.4.0

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

@@ -0,0 +1,164 @@
+import { ok, err, requirePermission, type ReadonlyDB, type QueryContext } from "../../../shared";
+import type { DB } from "../generated/kysely-tailordb";
+import {
+  ValidationErrorError,
+  InvalidScopeError,
+  UnauthorizedError,
+} from "../lib/errors.generated";
+
+const VALID_SCOPES = ["COMPANY", "GLOBAL", "ALL"];
+
+interface GroupBy {
+  entityType?: boolean;
+  operationType?: boolean;
+  actorType?: boolean;
+  timePeriod?: "DAY" | "WEEK" | "MONTH";
+}
+
+export interface GetAuditSummaryInput {
+  groupBy: GroupBy;
+  filters?: {
+    entityType?: string;
+    operationType?: string;
+    actorType?: string;
+    companyId?: string;
+    dateFrom?: Date;
+    dateTo?: Date;
+  };
+  scope?: string;
+}
+
+interface SummaryEntry {
+  entityType?: string;
+  operationType?: string;
+  actorType?: string;
+  timePeriod?: string;
+  count: number;
+}
+
+function formatTimePeriod(date: Date, period: "DAY" | "WEEK" | "MONTH"): string {
+  const d = new Date(date);
+  if (period === "DAY") {
+    return d.toISOString().slice(0, 10);
+  }
+  if (period === "WEEK") {
+    // Get Monday of the week
+    const day = d.getDay();
+    const diff = d.getDate() - day + (day === 0 ? -6 : 1);
+    const monday = new Date(d);
+    monday.setDate(diff);
+    return monday.toISOString().slice(0, 10);
+  }
+  // MONTH
+  return d.toISOString().slice(0, 7);
+}
+
+function buildGroupKey(entry: Record<string, unknown>, groupBy: GroupBy): string {
+  const parts: string[] = [];
+  if (groupBy.entityType) parts.push(`entityType:${String(entry.entityType)}`);
+  if (groupBy.operationType) parts.push(`operationType:${String(entry.operationType)}`);
+  if (groupBy.actorType) parts.push(`actorType:${String(entry.actorType)}`);
+  if (groupBy.timePeriod) {
+    const ts =
+      entry.timestamp instanceof Date ? entry.timestamp : new Date(entry.timestamp as string);
+    parts.push(`timePeriod:${formatTimePeriod(ts, groupBy.timePeriod)}`);
+  }
+  return parts.join("|");
+}
+
+function parseGroupKey(key: string, groupBy: GroupBy): Omit<SummaryEntry, "count"> {
+  const result: Omit<SummaryEntry, "count"> = {};
+  const parts = key.split("|");
+  for (const part of parts) {
+    const [field, value] = part.split(":");
+    if (field === "entityType" && groupBy.entityType) result.entityType = value;
+    if (field === "operationType" && groupBy.operationType) result.operationType = value;
+    if (field === "actorType" && groupBy.actorType) result.actorType = value;
+    if (field === "timePeriod" && groupBy.timePeriod) result.timePeriod = value;
+  }
+  return result;
+}
+
+export async function run(db: ReadonlyDB<DB>, input: GetAuditSummaryInput, ctx: QueryContext) {
+  const permCheck = requirePermission(ctx, "audit:viewAuditSummary");
+  if (!permCheck.ok) return permCheck;
+
+  const { groupBy } = input;
+
+  // Validate at least one grouping dimension
+  if (!groupBy.entityType && !groupBy.operationType && !groupBy.actorType && !groupBy.timePeriod) {
+    return err(new ValidationErrorError("at least one grouping dimension required"));
+  }
+
+  // Validate scope
+  if (input.scope && !VALID_SCOPES.includes(input.scope)) {
+    return err(new InvalidScopeError(input.scope));
+  }
+  if (input.scope === "COMPANY" && !input.filters?.companyId) {
+    return err(new ValidationErrorError("scope=COMPANY requires companyId"));
+  }
+
+  let query = db.selectFrom("AuditEntry").selectAll();
+
+  // Apply filters
+  if (input.filters?.entityType) query = query.where("entityType", "=", input.filters.entityType);
+  if (input.filters?.operationType)
+    query = query.where("operationType", "=", input.filters.operationType);
+  if (input.filters?.actorType) query = query.where("actorType", "=", input.filters.actorType);
+  if (input.filters?.dateFrom) query = query.where("timestamp", ">=", input.filters.dateFrom);
+  if (input.filters?.dateTo) query = query.where("timestamp", "<=", input.filters.dateTo);
+
+  // Apply company-scope restriction from context
+  if (ctx.companyId !== undefined) {
+    // Reject if caller requests a company they are not authorized for
+    if (
+      ctx.companyId !== null &&
+      input.filters?.companyId &&
+      input.filters.companyId !== ctx.companyId
+    ) {
+      return err(new UnauthorizedError(ctx.actorId));
+    }
+    if (ctx.companyId === null) {
+      // Global-scoped caller: cannot see company-scoped entries
+      if (input.scope === "COMPANY") {
+        return ok({ summary: [] as SummaryEntry[] });
+      }
+      query = query.where("companyId", "is", null);
+    } else {
+      // Company-scoped caller: cannot see global entries
+      if (input.scope === "GLOBAL") {
+        return ok({ summary: [] as SummaryEntry[] });
+      }
+      query = query.where("companyId", "=", ctx.companyId);
+    }
+  } else {
+    // No scope restriction from context; apply input scope filtering
+    if (input.scope === "COMPANY" || (!input.scope && input.filters?.companyId)) {
+      query = query.where("companyId", "=", input.filters!.companyId!);
+    } else if (input.scope === "GLOBAL" || (!input.scope && !input.filters?.companyId)) {
+      query = query.where("companyId", "is", null);
+    } else if (input.scope === "ALL" && input.filters?.companyId) {
+      // scope=ALL with companyId: return combined company + global results
+      query = query.where((eb) =>
+        eb.or([eb("companyId", "=", input.filters!.companyId!), eb("companyId", "is", null)]),
+      );
+    }
+    // scope=ALL without companyId: no companyId filter (return all scopes)
+  }
+
+  const entries = await query.execute();
+
+  // Aggregate in-memory
+  const groups = new Map<string, number>();
+  for (const entry of entries) {
+    const key = buildGroupKey(entry as unknown as Record<string, unknown>, groupBy);
+    groups.set(key, (groups.get(key) ?? 0) + 1);
+  }
+
+  const summary: SummaryEntry[] = Array.from(groups.entries()).map(([key, count]) => ({
+    ...parseGroupKey(key, groupBy),
+    count,
+  }));
+
+  return ok({ summary });
+}

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

@@ -0,0 +1,5 @@
+// @generated — do not edit
+import { defineQuery } from "../../../shared";
+import { run } from "./getChangeDetails";
+
+export const getChangeDetails = defineQuery(run);

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

@@ -0,0 +1,195 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { QueryContext } from "../../../shared";
+import { InsufficientPermissionError } from "../../../shared";
+import type { DB } from "../generated/kysely-tailordb";
+import { AuditEntryNotFoundError, UnauthorizedError } from "../lib/errors.generated";
+import {
+  baseAuditEntry,
+  globalAuditEntry,
+  baseChangeDetail,
+  maskedChangeDetail,
+  excludedChangeDetail,
+  createChangeDetail,
+} from "../testing/fixtures";
+import { run } from "./getChangeDetails";
+
+const ctx: QueryContext = {
+  actorId: "test-actor",
+  permissions: ["audit:viewAuditHistory"],
+};
+
+describe("getChangeDetails", () => {
+  it("returns all change details for an audit entry", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(baseAuditEntry);
+    spies.select.mockReturnValueOnce([baseChangeDetail, maskedChangeDetail]);
+
+    const result = await run(db, { auditEntryId: "entry-1" }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.changeDetails).toEqual([baseChangeDetail, maskedChangeDetail]);
+      expect(result.value.changeDetails).toHaveLength(2);
+    }
+  });
+
+  it("returns empty list when audit entry has no change details", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(baseAuditEntry);
+    spies.select.mockReturnValueOnce([]);
+
+    const result = await run(db, { auditEntryId: "entry-1" }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.changeDetails).toEqual([]);
+    }
+  });
+
+  it("returns change details with masked values for MASK sensitivity mode", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(baseAuditEntry);
+    spies.select.mockReturnValueOnce([maskedChangeDetail]);
+
+    const result = await run(db, { auditEntryId: "entry-1" }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      const detail = result.value.changeDetails[0];
+      expect(detail.oldValue).toBe("***");
+      expect(detail.newValue).toBe("***");
+    }
+  });
+
+  it("returns change details with hashed values for HASH sensitivity mode", async () => {
+    const hashedDetail = {
+      id: "detail-hash",
+      auditEntryId: "entry-1",
+      fieldName: "status",
+      oldValue: "sha256:abc123",
+      newValue: "sha256:def456",
+      createdAt: new Date("2024-01-15T10:30:00.000Z"),
+      updatedAt: null,
+    };
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(baseAuditEntry);
+    spies.select.mockReturnValueOnce([hashedDetail]);
+
+    const result = await run(db, { auditEntryId: "entry-1" }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      const detail = result.value.changeDetails[0];
+      expect(detail.oldValue).toBe("sha256:abc123");
+      expect(detail.newValue).toBe("sha256:def456");
+    }
+  });
+
+  it("returns change details with null values for EXCLUDE sensitivity mode", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(baseAuditEntry);
+    spies.select.mockReturnValueOnce([excludedChangeDetail]);
+
+    const result = await run(db, { auditEntryId: "entry-1" }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      const detail = result.value.changeDetails[0];
+      expect(detail.oldValue).toBeNull();
+      expect(detail.newValue).toBeNull();
+    }
+  });
+
+  it("returns change details with raw values for CAPTURE sensitivity mode", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(baseAuditEntry);
+    spies.select.mockReturnValueOnce([baseChangeDetail]);
+
+    const result = await run(db, { auditEntryId: "entry-1" }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      const detail = result.value.changeDetails[0];
+      expect(detail.oldValue).toBe("100.00");
+      expect(detail.newValue).toBe("95.00");
+    }
+  });
+
+  it("returns change details for company-scoped entry when caller has matching company permission", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(baseAuditEntry);
+    spies.select.mockReturnValueOnce([baseChangeDetail]);
+    const companyScopedCtx: QueryContext = {
+      actorId: "test-actor",
+      permissions: ["audit:viewAuditHistory"],
+      companyId: "company-1",
+    };
+
+    const result = await run(db, { auditEntryId: baseAuditEntry.id }, companyScopedCtx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.changeDetails).toEqual([baseChangeDetail]);
+    }
+  });
+
+  it("returns change details for global entry when caller has global-scoped permission", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(globalAuditEntry);
+    spies.select.mockReturnValueOnce([createChangeDetail]);
+    const globalScopedCtx: QueryContext = {
+      actorId: "test-actor",
+      permissions: ["audit:viewAuditHistory"],
+      companyId: null,
+    };
+
+    const result = await run(db, { auditEntryId: globalAuditEntry.id }, globalScopedCtx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.changeDetails).toEqual([createChangeDetail]);
+    }
+  });
+
+  it("returns error when audit entry does not exist", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(db, { auditEntryId: "nonexistent" }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(AuditEntryNotFoundError);
+    }
+  });
+
+  it("rejects when caller lacks permission for entry's company scope", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(baseAuditEntry); // companyId: "company-1"
+    const scopedCtx: QueryContext = {
+      actorId: "test-actor",
+      permissions: ["audit:viewAuditHistory"],
+      companyId: "company-2",
+    };
+
+    const result = await run(db, { auditEntryId: baseAuditEntry.id }, scopedCtx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(UnauthorizedError);
+    }
+  });
+
+  it("rejects when caller lacks viewAuditHistory permission", async () => {
+    const { db } = createMockDb<DB>();
+    const noPermsCtx: QueryContext = { actorId: "test-actor", permissions: [] };
+
+    const result = await run(db, { auditEntryId: "entry-1" }, noPermsCtx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InsufficientPermissionError);
+    }
+  });
+});

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

@@ -0,0 +1,42 @@
+import { ok, err, requirePermission, type ReadonlyDB, type QueryContext } from "../../../shared";
+import type { DB } from "../generated/kysely-tailordb";
+import { AuditEntryNotFoundError, UnauthorizedError } from "../lib/errors.generated";
+
+export interface GetChangeDetailsInput {
+  auditEntryId: string;
+}
+
+export async function run(db: ReadonlyDB<DB>, input: GetChangeDetailsInput, ctx: QueryContext) {
+  const permCheck = requirePermission(ctx, "audit:viewAuditHistory");
+  if (!permCheck.ok) return permCheck;
+
+  const entry = await db
+    .selectFrom("AuditEntry")
+    .selectAll()
+    .where("id", "=", input.auditEntryId)
+    .executeTakeFirst();
+
+  if (!entry) return err(new AuditEntryNotFoundError(input.auditEntryId));
+
+  const scopeErr = checkScopeAuthorization(entry.companyId, ctx);
+  if (scopeErr) return scopeErr;
+
+  const changeDetails = await db
+    .selectFrom("ChangeDetail")
+    .selectAll()
+    .where("auditEntryId", "=", input.auditEntryId)
+    .execute();
+
+  return ok({ changeDetails });
+}
+
+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/listAuditPolicies.generated.ts

@@ -0,0 +1,5 @@
+// @generated — do not edit
+import { defineQuery } from "../../../shared";
+import { run } from "./listAuditPolicies";
+
+export const listAuditPolicies = defineQuery(run);

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

@@ -0,0 +1,239 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { QueryContext } from "../../../shared";
+import type { DB } from "../generated/kysely-tailordb";
+import { InsufficientPermissionError } from "../../../shared";
+import { UnauthorizedError } from "../lib/errors.generated";
+import {
+  activePolicy,
+  draftPolicy,
+  inactivePolicy,
+  globalActivePolicy,
+  globalDraftPolicy,
+} from "../testing/fixtures";
+import { run } from "./listAuditPolicies";
+
+const ctx: QueryContext = {
+  actorId: "test-actor",
+  permissions: ["audit:manageAuditPolicies"],
+};
+
+describe("listAuditPolicies", () => {
+  it("returns all policies when no filters applied", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue([activePolicy, draftPolicy, globalActivePolicy]);
+
+    const result = await run(db, {}, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.items).toHaveLength(3);
+    }
+  });
+
+  it("returns policies filtered by entityName", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue([activePolicy, draftPolicy]);
+
+    const result = await run(db, { entityName: "SalesOrder" }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.items).toHaveLength(2);
+      for (const item of result.value.items) {
+        expect(item.policy.entityName).toBe("SalesOrder");
+      }
+    }
+  });
+
+  it("returns policies filtered by status", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue([activePolicy, globalActivePolicy]);
+
+    const result = await run(db, { status: "ACTIVE" }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.items).toHaveLength(2);
+      for (const item of result.value.items) {
+        expect(item.policy.status).toBe("ACTIVE");
+      }
+    }
+  });
+
+  it("returns policies filtered by companyId", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue([activePolicy, draftPolicy, inactivePolicy]);
+
+    const result = await run(db, { companyId: "company-1" }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.items).toHaveLength(3);
+      for (const item of result.value.items) {
+        expect(item.policy.companyId).toBe("company-1");
+      }
+    }
+  });
+
+  it("returns only global policies when companyId filter is explicitly null", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue([globalActivePolicy, globalDraftPolicy]);
+
+    const result = await run(db, { companyId: null }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.items).toHaveLength(2);
+      for (const item of result.value.items) {
+        expect(item.policy.companyId).toBeNull();
+      }
+    }
+  });
+
+  it("returns policies filtered by operationType", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue([activePolicy]);
+
+    const result = await run(db, { operationType: "UPDATE" }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.items).toHaveLength(1);
+      expect(result.value.items[0].policy.operationType).toBe("UPDATE");
+    }
+  });
+
+  it("combines multiple filter criteria", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue([activePolicy]);
+
+    const result = await run(
+      db,
+      {
+        entityName: "SalesOrder",
+        status: "ACTIVE",
+        companyId: "company-1",
+        operationType: "UPDATE",
+      },
+      ctx,
+    );
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.items).toHaveLength(1);
+    }
+  });
+
+  it("returns policy objects with expected fields", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue([activePolicy]);
+
+    const result = await run(db, { status: "ACTIVE" }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      const item = result.value.items[0];
+      expect(item).toHaveProperty("policy");
+      expect(item).toHaveProperty("fieldRules");
+      expect(item.policy).toHaveProperty("id");
+      expect(item.policy).toHaveProperty("entityName");
+      expect(item.policy).toHaveProperty("companyId");
+      expect(item.policy).toHaveProperty("operationType");
+      expect(item.policy).toHaveProperty("status");
+    }
+  });
+
+  it("returns empty list when no policies match", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue([]);
+
+    const result = await run(db, { entityName: "NonExistent" }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.items).toHaveLength(0);
+      expect(result.value.hasNextPage).toBe(false);
+    }
+  });
+
+  it("paginates results correctly", async () => {
+    const { db, spies } = createMockDb<DB>();
+    const manyPolicies = Array.from({ length: 3 }, (_, i) => ({
+      ...activePolicy,
+      id: `policy-${i}`,
+    }));
+    spies.select.mockReturnValue(manyPolicies);
+
+    const result = await run(db, { limit: 2 }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.items).toHaveLength(2);
+      expect(result.value.hasNextPage).toBe(true);
+    }
+  });
+
+  it("rejects when caller lacks manageAuditPolicies permission", async () => {
+    const { db } = createMockDb<DB>();
+    const noPermsCtx: QueryContext = { actorId: "test-actor", permissions: [] };
+
+    const result = await run(db, {}, noPermsCtx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InsufficientPermissionError);
+    }
+  });
+
+  it("rejects when caller with company-scoped permission requests policies for a different company", async () => {
+    const { db } = createMockDb<DB>();
+    const scopedCtx: QueryContext = {
+      actorId: "test-actor",
+      permissions: ["audit:manageAuditPolicies"],
+      companyId: "company-1",
+    };
+
+    const result = await run(db, { companyId: "company-2" }, scopedCtx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(UnauthorizedError);
+    }
+  });
+
+  it("returns only global policies when caller has global-scoped permission", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue([globalActivePolicy, globalDraftPolicy]);
+    const globalCtx: QueryContext = {
+      actorId: "test-actor",
+      permissions: ["audit:manageAuditPolicies"],
+      companyId: null,
+    };
+
+    const result = await run(db, {}, globalCtx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      for (const item of result.value.items) {
+        expect(item.policy.companyId).toBeNull();
+      }
+    }
+  });
+
+  it("rejects when global-scoped caller requests company-scoped policies", async () => {
+    const { db } = createMockDb<DB>();
+    const globalCtx: QueryContext = {
+      actorId: "test-actor",
+      permissions: ["audit:manageAuditPolicies"],
+      companyId: null,
+    };
+
+    const result = await run(db, { companyId: "company-1" }, globalCtx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(UnauthorizedError);
+    }
+  });
+});