@echovisionlab/geul-telemetry 0.1.0

package/src/audit/email-authoring.ts

@@ -0,0 +1,220 @@
+import type { AuditRecord } from "../records.ts";
+import {
+  assertOnlyAuditAttributes,
+  canonicalAuditValues,
+} from "./attributes.ts";
+import { buildAuditRecord } from "./builder.ts";
+import {
+  AUDIT_ACTIONS,
+  AUDIT_CATALOG,
+  requireCatalogTarget,
+} from "./catalog.ts";
+import type { AuditMetadata } from "./types.ts";
+
+type EmailAuthoringAction = Extract<
+  (typeof AUDIT_ACTIONS)[number],
+  | "email_template.created"
+  | "email_template.updated"
+  | "email_template.deleted"
+  | "email_layout.created"
+  | "email_layout.updated"
+  | "email_layout.deleted"
+  | "email_event_mapping.updated"
+>;
+export type EmailTemplateMetadataField =
+  "active" | "description" | "key" | "name";
+export type EmailLayoutMetadataField = "key" | "name";
+
+const actions = new Set<EmailAuthoringAction>([
+  "email_template.created",
+  "email_template.updated",
+  "email_template.deleted",
+  "email_layout.created",
+  "email_layout.updated",
+  "email_layout.deleted",
+  "email_event_mapping.updated",
+]);
+const templateMetadataFields = new Set<EmailTemplateMetadataField>([
+  "active",
+  "description",
+  "key",
+  "name",
+]);
+const layoutMetadataFields = new Set<EmailLayoutMetadataField>(["key", "name"]);
+function buildEmailAuthoringAuditRecord(
+  metadata: AuditMetadata,
+  action: EmailAuthoringAction,
+  targetId: string,
+  attributes: Parameters<typeof buildAuditRecord>[2] = {},
+): AuditRecord {
+  return buildAuditRecord(
+    metadata,
+    { action, target_type: AUDIT_CATALOG[action], target_id: targetId },
+    attributes,
+  );
+}
+function requireNoExtra(record: AuditRecord, allowed: readonly string[]): void {
+  assertOnlyAuditAttributes(record, allowed);
+}
+function requireIdentifier(name: string, value: string | undefined): void {
+  if (!value || value.length > 255 || value.trim() !== value)
+    throw new TypeError(`${name} requires an identifier`);
+}
+function requireFields(
+  record: AuditRecord,
+  allowed: ReadonlySet<string>,
+): void {
+  const fields = record.changed_fields;
+  if (
+    !fields?.length ||
+    fields.some(
+      (field, i) => !allowed.has(field) || (i > 0 && fields[i - 1] >= field),
+    )
+  )
+    throw new TypeError("invalid or non-canonical changed_fields");
+}
+function requireRelation(record: AuditRecord, includeEventName = false): void {
+  const previous = record.previous_item_id ?? "";
+  const next = record.item_id ?? "";
+  if (previous === next) throw new TypeError("relation no-op");
+  if (previous !== "") requireIdentifier("previous_item_id", previous);
+  if (next !== "") requireIdentifier("item_id", next);
+  requireNoExtra(record, [
+    "changed_fields",
+    "previous_item_id",
+    "item_id",
+    ...(includeEventName ? ["event_name"] : []),
+  ]);
+}
+function isEmailEventKey(value: string | undefined): boolean {
+  return value !== undefined && /^[a-z0-9_]{1,64}$/.test(value);
+}
+function validateTemplateUpdate(record: AuditRecord): void {
+  if (
+    record.changed_fields?.length === 1 &&
+    record.changed_fields[0] === "layout"
+  )
+    return requireRelation(record);
+  requireMemberActor(record);
+  requireFields(record, templateMetadataFields);
+  requireNoExtra(record, ["changed_fields"]);
+}
+function validateLayoutUpdate(record: AuditRecord): void {
+  requireMemberActor(record);
+  requireFields(record, layoutMetadataFields);
+  requireNoExtra(record, ["changed_fields"]);
+}
+function validateMappingUpdate(record: AuditRecord): void {
+  requireMemberActor(record);
+  if (
+    record.changed_fields?.length !== 1 ||
+    record.changed_fields[0] !== "template" ||
+    !isEmailEventKey(record.event_name)
+  )
+    throw new TypeError("event mapping requires event_name and template");
+  requireRelation(record, true);
+}
+function requireMemberActor(record: AuditRecord): void {
+  if (record.actor_kind !== "member")
+    throw new TypeError("email authoring mutation requires member actor");
+}
+
+/** Returns true only for the seven reviewed Email Authoring audit actions. */
+export function validateEmailAuthoringAuditRecord(
+  record: AuditRecord,
+): boolean {
+  if (!actions.has(record.action as EmailAuthoringAction)) return false;
+  requireCatalogTarget(record.action, record.target_type, record.target_id);
+  if (!record.action.endsWith(".updated")) {
+    requireMemberActor(record);
+    requireNoExtra(record, []);
+    return true;
+  }
+  if (record.action === "email_template.updated")
+    validateTemplateUpdate(record);
+  else if (record.action === "email_layout.updated")
+    validateLayoutUpdate(record);
+  else validateMappingUpdate(record);
+  return true;
+}
+export function buildEmailTemplateCreatedAuditRecord(
+  metadata: AuditMetadata,
+  id: string,
+): AuditRecord {
+  return buildEmailAuthoringAuditRecord(metadata, "email_template.created", id);
+}
+export function buildEmailTemplateDeletedAuditRecord(
+  metadata: AuditMetadata,
+  id: string,
+): AuditRecord {
+  return buildEmailAuthoringAuditRecord(metadata, "email_template.deleted", id);
+}
+export function buildEmailTemplateMetadataAuditRecord(
+  metadata: AuditMetadata,
+  id: string,
+  fields: readonly EmailTemplateMetadataField[],
+): AuditRecord {
+  return buildEmailAuthoringAuditRecord(
+    metadata,
+    "email_template.updated",
+    id,
+    { changed_fields: canonicalAuditValues(fields) },
+  );
+}
+export function buildEmailTemplateLayoutRelationAuditRecord(
+  metadata: AuditMetadata,
+  id: string,
+  previousLayoutId: string,
+  layoutId: string,
+): AuditRecord {
+  return buildEmailAuthoringAuditRecord(
+    metadata,
+    "email_template.updated",
+    id,
+    {
+      changed_fields: ["layout"],
+      previous_item_id: previousLayoutId === "" ? undefined : previousLayoutId,
+      item_id: layoutId === "" ? undefined : layoutId,
+    },
+  );
+}
+export function buildEmailLayoutCreatedAuditRecord(
+  metadata: AuditMetadata,
+  id: string,
+): AuditRecord {
+  return buildEmailAuthoringAuditRecord(metadata, "email_layout.created", id);
+}
+export function buildEmailLayoutDeletedAuditRecord(
+  metadata: AuditMetadata,
+  id: string,
+): AuditRecord {
+  return buildEmailAuthoringAuditRecord(metadata, "email_layout.deleted", id);
+}
+export function buildEmailLayoutMetadataAuditRecord(
+  metadata: AuditMetadata,
+  id: string,
+  fields: readonly EmailLayoutMetadataField[],
+): AuditRecord {
+  return buildEmailAuthoringAuditRecord(metadata, "email_layout.updated", id, {
+    changed_fields: canonicalAuditValues(fields),
+  });
+}
+export function buildEmailEventMappingTemplateAuditRecord(
+  metadata: AuditMetadata,
+  eventName: string,
+  previousTemplateId: string,
+  templateId: string,
+): AuditRecord {
+  return buildEmailAuthoringAuditRecord(
+    metadata,
+    "email_event_mapping.updated",
+    eventName,
+    {
+      changed_fields: ["template"],
+      event_name: eventName,
+      previous_item_id:
+        previousTemplateId === "" ? undefined : previousTemplateId,
+      item_id: templateId === "" ? undefined : templateId,
+    },
+  );
+}

package/src/audit/file.ts

@@ -0,0 +1,168 @@
+import type { AuditRecord } from "../records.ts";
+import { assertOnlyAuditAttributes } from "./attributes.ts";
+import { buildAuditRecord } from "./builder.ts";
+import { AUDIT_CATALOG, requireCatalogTarget } from "./catalog.ts";
+import type { AuditMetadata } from "./types.ts";
+
+type FileAction =
+  | "file.created"
+  | "file.updated"
+  | "file.deleted"
+  | "file_folder.created"
+  | "file_folder.updated"
+  | "file_folder.deleted";
+const fileUpdateFields = new Set(["file_name", "folder_id"]);
+const folderUpdateFields = new Set(["name", "parent_id"]);
+function buildFileAuditRecord(
+  metadata: AuditMetadata,
+  action: FileAction,
+  targetId: string,
+  attributes: Parameters<typeof buildAuditRecord>[2] = {},
+): AuditRecord {
+  // The reviewed catalog, not string construction, owns this target mapping.
+  return buildAuditRecord(
+    metadata,
+    { action, target_type: AUDIT_CATALOG[action], target_id: targetId },
+    attributes,
+  );
+}
+
+function requireFields(
+  record: AuditRecord,
+  allowed: ReadonlySet<string>,
+): readonly string[] {
+  const fields = record.changed_fields;
+  if (
+    !fields?.length ||
+    fields.some(
+      (value, index) =>
+        !allowed.has(value) || (index > 0 && fields[index - 1] >= value),
+    )
+  )
+    throw new TypeError("invalid or non-canonical changed_fields");
+  return fields;
+}
+function requireNoExtra(record: AuditRecord, allowed: readonly string[]): void {
+  assertOnlyAuditAttributes(record, allowed);
+}
+function requireMove(
+  record: AuditRecord,
+  field: "folder_id" | "parent_id",
+  changedFields: readonly string[],
+): void {
+  const hasMove = changedFields.includes(field);
+  if (hasMove && record.previous_parent_id === record.new_parent_id)
+    throw new TypeError(`${field} requires a distinct parent transition`);
+  if (
+    !hasMove &&
+    (record.previous_parent_id !== undefined ||
+      record.new_parent_id !== undefined)
+  )
+    throw new TypeError(`parent IDs require changed_fields ${field}`);
+}
+
+/** Returns true only for the reviewed File and File Folder catalog actions. */
+export function validateFileAuditRecord(record: AuditRecord): boolean {
+  if (
+    record.action !== "file.created" &&
+    record.action !== "file.updated" &&
+    record.action !== "file.deleted" &&
+    record.action !== "file_folder.created" &&
+    record.action !== "file_folder.updated" &&
+    record.action !== "file_folder.deleted"
+  )
+    return false;
+  requireCatalogTarget(record.action, record.target_type, record.target_id);
+  if (
+    record.action === "file.created" ||
+    record.action === "file.deleted" ||
+    record.action === "file_folder.created" ||
+    record.action === "file_folder.deleted"
+  ) {
+    requireNoExtra(record, []);
+    return true;
+  }
+  if (record.action === "file_folder.updated") {
+    const changedFields = requireFields(record, folderUpdateFields);
+    requireMove(record, "parent_id", changedFields);
+    requireNoExtra(record, [
+      "changed_fields",
+      "previous_parent_id",
+      "new_parent_id",
+    ]);
+    return true;
+  }
+  const changedFields = requireFields(record, fileUpdateFields);
+  requireMove(record, "folder_id", changedFields);
+  requireNoExtra(record, [
+    "changed_fields",
+    "previous_parent_id",
+    "new_parent_id",
+  ]);
+  return true;
+}
+
+export function buildFileCreatedAuditRecord(
+  metadata: AuditMetadata,
+  fileId: string,
+): AuditRecord {
+  return buildFileAuditRecord(metadata, "file.created", fileId);
+}
+export function buildFileDeletedAuditRecord(
+  metadata: AuditMetadata,
+  fileId: string,
+): AuditRecord {
+  return buildFileAuditRecord(metadata, "file.deleted", fileId);
+}
+export function buildFileRenamedAuditRecord(
+  metadata: AuditMetadata,
+  fileId: string,
+): AuditRecord {
+  return buildFileAuditRecord(metadata, "file.updated", fileId, {
+    changed_fields: ["file_name"],
+  });
+}
+export function buildFileMovedAuditRecord(
+  metadata: AuditMetadata,
+  fileId: string,
+  previousParentId: string,
+  newParentId: string,
+): AuditRecord {
+  return buildFileAuditRecord(metadata, "file.updated", fileId, {
+    changed_fields: ["folder_id"],
+    previous_parent_id: previousParentId === "" ? undefined : previousParentId,
+    new_parent_id: newParentId === "" ? undefined : newParentId,
+  });
+}
+export function buildFileFolderCreatedAuditRecord(
+  metadata: AuditMetadata,
+  folderId: string,
+): AuditRecord {
+  return buildFileAuditRecord(metadata, "file_folder.created", folderId);
+}
+export function buildFileFolderDeletedAuditRecord(
+  metadata: AuditMetadata,
+  folderId: string,
+): AuditRecord {
+  return buildFileAuditRecord(metadata, "file_folder.deleted", folderId);
+}
+export function buildFileFolderRenamedAuditRecord(
+  metadata: AuditMetadata,
+  folderId: string,
+): AuditRecord {
+  return buildFileAuditRecord(metadata, "file_folder.updated", folderId, {
+    changed_fields: ["name"],
+  });
+}
+export function buildFileFolderMovedAuditRecord(
+  metadata: AuditMetadata,
+  folderId: string,
+  previousParentId: string,
+  newParentId: string,
+): AuditRecord {
+  return buildFileAuditRecord(metadata, "file_folder.updated", folderId, {
+    changed_fields: ["parent_id"],
+    previous_parent_id: previousParentId === "" ? undefined : previousParentId,
+    new_parent_id: newParentId === "" ? undefined : newParentId,
+  });
+}

package/src/audit/form.ts

@@ -0,0 +1,229 @@
+import type {
+  AuditCollectionOperation,
+  AuditItemOperation,
+  AuditItemScope,
+  AuditRecord,
+  AuditState,
+} from "../records.ts";
+import {
+  assertOnlyAuditAttributes,
+  canonicalAuditValues,
+} from "./attributes.ts";
+import { buildAuditRecord } from "./builder.ts";
+import { AUDIT_CATALOG, requireCatalogTarget } from "./catalog.ts";
+import type { AuditMetadata } from "./types.ts";
+
+type FormSettingsField =
+  | "access_period"
+  | "auth_required"
+  | "direct_public"
+  | "duplicate_policy"
+  | "limit"
+  | "password"
+  | "required_role"
+  | "slug";
+type FormLifecycleState = Extract<AuditState, "draft" | "published">;
+
+const formSettingsFields = new Set<FormSettingsField>([
+  "access_period",
+  "auth_required",
+  "direct_public",
+  "duplicate_policy",
+  "limit",
+  "password",
+  "required_role",
+  "slug",
+]);
+const formActions = new Set([
+  "form.created",
+  "form.updated",
+  "form.deleted",
+  "form_submission.created",
+  "form_submission.deleted",
+] as const);
+function buildFormAuditRecord(
+  metadata: AuditMetadata,
+  action: typeof formActions extends Set<infer T> ? T : never,
+  targetId: string,
+  attributes: Parameters<typeof buildAuditRecord>[2] = {},
+): AuditRecord {
+  return buildAuditRecord(
+    metadata,
+    { action, target_type: AUDIT_CATALOG[action], target_id: targetId },
+    attributes,
+  );
+}
+function requireNoExtra(record: AuditRecord, allowed: readonly string[]): void {
+  assertOnlyAuditAttributes(record, allowed);
+}
+function requireIdentifier(name: string, value: string | undefined): void {
+  if (!value || value.length > 255 || value.trim() !== value)
+    throw new TypeError(`${name} requires an identifier`);
+}
+function requireFields(
+  record: AuditRecord,
+  allowed: ReadonlySet<string>,
+): void {
+  const fields = record.changed_fields;
+  if (
+    !fields?.length ||
+    fields.some(
+      (field, i) => !allowed.has(field) || (i > 0 && fields[i - 1] >= field),
+    )
+  )
+    throw new TypeError("invalid or non-canonical changed_fields");
+}
+function validateFormUpdate(record: AuditRecord): void {
+  if (record.changed_fields?.length !== 1) {
+    requireFields(record, formSettingsFields);
+    return requireNoExtra(record, ["changed_fields"]);
+  }
+  switch (record.changed_fields[0]) {
+    case "status":
+      if (
+        !(["draft", "published"] as const).includes(
+          record.previous_state as FormLifecycleState,
+        ) ||
+        !(["draft", "published"] as const).includes(
+          record.new_state as FormLifecycleState,
+        ) ||
+        record.previous_state === record.new_state
+      )
+        throw new TypeError(
+          "form status requires a distinct draft/published transition",
+        );
+      return requireNoExtra(record, [
+        "changed_fields",
+        "previous_state",
+        "new_state",
+      ]);
+    case "featured_image":
+      if (
+        (record.collection_operation !== "added" &&
+          record.collection_operation !== "removed") ||
+        !record.file_id
+      )
+        throw new TypeError(
+          "featured_image requires collection operation and file_id",
+        );
+      requireIdentifier("file_id", record.file_id);
+      return requireNoExtra(record, [
+        "changed_fields",
+        "collection_operation",
+        "file_id",
+      ]);
+    case "share_links":
+      if (
+        (record.item_operation !== "created" &&
+          record.item_operation !== "deleted") ||
+        (record.item_scope !== "form" && record.item_scope !== "dashboard")
+      )
+        throw new TypeError(
+          "form share_links requires form/dashboard scope and created/deleted operation",
+        );
+      requireIdentifier("item_id", record.item_id);
+      return requireNoExtra(record, [
+        "changed_fields",
+        "item_operation",
+        "item_scope",
+        "item_id",
+      ]);
+    default:
+      requireFields(record, formSettingsFields);
+      return requireNoExtra(record, ["changed_fields"]);
+  }
+}
+
+/** Returns true only for the five reviewed Form and Submission actions. */
+export function validateFormAuditRecord(record: AuditRecord): boolean {
+  if (!formActions.has(record.action as never)) return false;
+  requireCatalogTarget(record.action, record.target_type, record.target_id);
+  if (record.action === "form_submission.created") {
+    requireIdentifier("parent_id", record.parent_id);
+    requireNoExtra(record, ["parent_id"]);
+  } else if (record.action === "form.updated") validateFormUpdate(record);
+  else requireNoExtra(record, []);
+  return true;
+}
+
+export function buildFormCreatedAuditRecord(
+  metadata: AuditMetadata,
+  formId: string,
+): AuditRecord {
+  return buildFormAuditRecord(metadata, "form.created", formId);
+}
+export function buildFormDeletedAuditRecord(
+  metadata: AuditMetadata,
+  formId: string,
+): AuditRecord {
+  return buildFormAuditRecord(metadata, "form.deleted", formId);
+}
+export function buildFormSettingsAuditRecord(
+  metadata: AuditMetadata,
+  formId: string,
+  changedFields: readonly FormSettingsField[],
+): AuditRecord {
+  return buildFormAuditRecord(metadata, "form.updated", formId, {
+    changed_fields: canonicalAuditValues(changedFields),
+  });
+}
+export function buildFormLifecycleAuditRecord(
+  metadata: AuditMetadata,
+  formId: string,
+  previousState: FormLifecycleState,
+  newState: FormLifecycleState,
+): AuditRecord {
+  return buildFormAuditRecord(metadata, "form.updated", formId, {
+    changed_fields: ["status"],
+    previous_state: previousState,
+    new_state: newState,
+  });
+}
+export function buildFormFeaturedImageAuditRecord(
+  metadata: AuditMetadata,
+  formId: string,
+  fileId: string,
+  collectionOperation: AuditCollectionOperation,
+): AuditRecord {
+  return buildFormAuditRecord(metadata, "form.updated", formId, {
+    changed_fields: ["featured_image"],
+    file_id: fileId,
+    collection_operation: collectionOperation,
+  });
+}
+export function buildFormShareLinkAuditRecord(
+  metadata: AuditMetadata,
+  formId: string,
+  itemId: string,
+  itemScope: AuditItemScope,
+  itemOperation: Extract<AuditItemOperation, "created" | "deleted">,
+): AuditRecord {
+  return buildFormAuditRecord(metadata, "form.updated", formId, {
+    changed_fields: ["share_links"],
+    item_id: itemId,
+    item_scope: itemScope,
+    item_operation: itemOperation,
+  });
+}
+export function buildFormSubmissionCreatedAuditRecord(
+  metadata: AuditMetadata,
+  submissionId: string,
+  formId: string,
+): AuditRecord {
+  return buildFormAuditRecord(
+    metadata,
+    "form_submission.created",
+    submissionId,
+    { parent_id: formId },
+  );
+}
+export function buildFormSubmissionDeletedAuditRecord(
+  metadata: AuditMetadata,
+  submissionId: string,
+): AuditRecord {
+  return buildFormAuditRecord(
+    metadata,
+    "form_submission.deleted",
+    submissionId,
+  );
+}