@echovisionlab/geul-telemetry 0.1.0

package/src/audit/integrations.ts

@@ -0,0 +1,207 @@
+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 IntegrationTarget =
+  | "mail_adapter"
+  | "email_suppression"
+  | "translation_settings"
+  | "translation_provider";
+type IntegrationAction = Extract<
+  (typeof AUDIT_ACTIONS)[number],
+  | "mail_adapter.created"
+  | "mail_adapter.updated"
+  | "mail_adapter.deleted"
+  | "email_suppression.updated"
+  | "translation_settings.updated"
+  | "translation_provider.created"
+  | "translation_provider.updated"
+  | "translation_provider.deleted"
+>;
+export type AdapterConfigField =
+  "active" | "config" | "name" | "priority" | "type";
+export type TranslationSettingsField = "default_locale" | "protected_terms";
+
+export const TRANSLATION_SETTINGS_FIELDS = [
+  "default_locale",
+  "protected_terms",
+] as const satisfies readonly TranslationSettingsField[];
+
+const targetTypes = new Set<IntegrationTarget>([
+  "mail_adapter",
+  "email_suppression",
+  "translation_settings",
+  "translation_provider",
+]);
+// Module ownership derives from the immutable catalog, not a duplicate map.
+const integrationActions = new Set<IntegrationAction>(
+  AUDIT_ACTIONS.filter((action) =>
+    targetTypes.has(AUDIT_CATALOG[action] as IntegrationTarget),
+  ) as IntegrationAction[],
+);
+const adapterConfigFields = new Set<AdapterConfigField>([
+  "active",
+  "config",
+  "name",
+  "priority",
+  "type",
+]);
+const translationSettingsFields = new Set<TranslationSettingsField>(
+  TRANSLATION_SETTINGS_FIELDS,
+);
+function buildIntegrationAuditRecord(
+  metadata: AuditMetadata,
+  action: IntegrationAction,
+  targetId: string,
+  attributes: Parameters<typeof buildAuditRecord>[2] = {},
+): AuditRecord {
+  return buildAuditRecord(
+    metadata,
+    { action, target_type: AUDIT_CATALOG[action], target_id: targetId },
+    attributes,
+  );
+}
+function requireFields(
+  record: AuditRecord,
+  allowed: ReadonlySet<string>,
+): void {
+  const fields = record.changed_fields;
+  if (
+    !fields?.length ||
+    fields.some(
+      (field, index) =>
+        !allowed.has(field) || (index > 0 && fields[index - 1] >= field),
+    )
+  )
+    throw new TypeError("invalid or non-canonical changed_fields");
+}
+function requireNoExtra(record: AuditRecord, allowed: readonly string[]): void {
+  assertOnlyAuditAttributes(record, allowed);
+}
+/** Returns true only for the reviewed Platform Integrations catalog actions. */
+export function validateIntegrationAuditRecord(record: AuditRecord): boolean {
+  if (!integrationActions.has(record.action as IntegrationAction)) return false;
+  requireCatalogTarget(record.action, record.target_type, record.target_id);
+  switch (record.action) {
+    case "mail_adapter.created":
+    case "mail_adapter.deleted":
+    case "translation_provider.created":
+    case "translation_provider.deleted":
+      requireNoExtra(record, []);
+      return true;
+    case "mail_adapter.updated":
+    case "translation_provider.updated":
+      requireFields(record, adapterConfigFields);
+      requireNoExtra(record, ["changed_fields"]);
+      return true;
+    case "email_suppression.updated":
+      if (
+        record.changed_fields?.length !== 1 ||
+        record.changed_fields[0] !== "status" ||
+        record.previous_state !== "active" ||
+        record.new_state !== "released"
+      )
+        throw new TypeError(
+          "email suppression requires active to released status",
+        );
+      requireNoExtra(record, ["changed_fields", "previous_state", "new_state"]);
+      return true;
+    case "translation_settings.updated":
+      if (record.target_id !== "1")
+        throw new TypeError("translation settings target must be 1");
+      requireFields(record, translationSettingsFields);
+      requireNoExtra(record, ["changed_fields"]);
+      return true;
+  }
+  /* v8 ignore next -- IntegrationAction is exhaustive above. */
+  throw new TypeError(`unsupported integration audit action ${record.action}`);
+}
+
+export function buildMailAdapterCreatedAuditRecord(
+  metadata: AuditMetadata,
+  id: string,
+): AuditRecord {
+  return buildIntegrationAuditRecord(metadata, "mail_adapter.created", id);
+}
+export function buildMailAdapterConfigUpdatedAuditRecord(
+  metadata: AuditMetadata,
+  id: string,
+  fields: readonly AdapterConfigField[],
+): AuditRecord {
+  return buildIntegrationAuditRecord(metadata, "mail_adapter.updated", id, {
+    changed_fields: canonicalAuditValues(fields),
+  });
+}
+export function buildMailAdapterDeletedAuditRecord(
+  metadata: AuditMetadata,
+  id: string,
+): AuditRecord {
+  return buildIntegrationAuditRecord(metadata, "mail_adapter.deleted", id);
+}
+export function buildEmailSuppressionReleasedAuditRecord(
+  metadata: AuditMetadata,
+  id: string,
+): AuditRecord {
+  return buildIntegrationAuditRecord(
+    metadata,
+    "email_suppression.updated",
+    id,
+    {
+      changed_fields: ["status"],
+      previous_state: "active",
+      new_state: "released",
+    },
+  );
+}
+export function buildTranslationSettingsUpdatedAuditRecord(
+  metadata: AuditMetadata,
+  fields: readonly TranslationSettingsField[],
+): AuditRecord {
+  return buildIntegrationAuditRecord(
+    metadata,
+    "translation_settings.updated",
+    "1",
+    { changed_fields: canonicalAuditValues(fields) },
+  );
+}
+export function buildTranslationProviderCreatedAuditRecord(
+  metadata: AuditMetadata,
+  id: string,
+): AuditRecord {
+  return buildIntegrationAuditRecord(
+    metadata,
+    "translation_provider.created",
+    id,
+  );
+}
+export function buildTranslationProviderConfigUpdatedAuditRecord(
+  metadata: AuditMetadata,
+  id: string,
+  fields: readonly AdapterConfigField[],
+): AuditRecord {
+  return buildIntegrationAuditRecord(
+    metadata,
+    "translation_provider.updated",
+    id,
+    { changed_fields: canonicalAuditValues(fields) },
+  );
+}
+export function buildTranslationProviderDeletedAuditRecord(
+  metadata: AuditMetadata,
+  id: string,
+): AuditRecord {
+  return buildIntegrationAuditRecord(
+    metadata,
+    "translation_provider.deleted",
+    id,
+  );
+}

package/src/audit/locale-code.ts

@@ -0,0 +1,6 @@
+export function isCanonicalAuditLocale(value: string | undefined): boolean {
+  const code = value ?? "";
+  return (
+    code.length <= 64 && /^[A-Za-z0-9]{1,8}(-[A-Za-z0-9]{1,8})*$/.test(code)
+  );
+}

package/src/audit/locale-content.ts

@@ -0,0 +1,358 @@
+import type {
+  AuditAction,
+  AuditItemOperation,
+  AuditRecord,
+} from "../records.ts";
+import { assertOnlyAuditAttributes } from "./attributes.ts";
+import { buildAuditRecord } from "./builder.ts";
+import { AUDIT_CATALOG, requireCatalogTarget } from "./catalog.ts";
+import { isCanonicalAuditLocale } from "./locale-code.ts";
+import type { AuditMetadata } from "./types.ts";
+
+type LocaleContentAction = Extract<
+  AuditAction,
+  | "post.updated"
+  | "page.updated"
+  | "work.updated"
+  | "post_series.updated"
+  | "program_event.updated"
+  | "release.updated"
+  | "artist.updated"
+  | "label.updated"
+  | "menu.updated"
+  | "campaign.updated"
+  | "form.updated"
+  | "email_template.updated"
+  | "email_layout.updated"
+  | "legal_policy.updated"
+>;
+
+const localeContentActions = new Set<LocaleContentAction>([
+  "post.updated",
+  "page.updated",
+  "work.updated",
+  "post_series.updated",
+  "program_event.updated",
+  "release.updated",
+  "artist.updated",
+  "label.updated",
+  "menu.updated",
+  "campaign.updated",
+  "form.updated",
+  "email_template.updated",
+  "email_layout.updated",
+  "legal_policy.updated",
+]);
+
+/** Recognizes exactly one locale-document create, update, or delete. */
+export function validateLocaleContentAuditRecord(record: AuditRecord): boolean {
+  if (
+    record.changed_fields?.length !== 1 ||
+    record.changed_fields[0] !== "locale_content"
+  )
+    return false;
+  if (!localeContentActions.has(record.action as LocaleContentAction))
+    throw new TypeError(
+      `audit action ${record.action} does not support locale_content`,
+    );
+  requireCatalogTarget(record.action, record.target_type, record.target_id);
+  if (record.actor_kind !== "member")
+    throw new TypeError("locale_content requires a member actor");
+  if (!isCanonicalAuditLocale(record.locale))
+    throw new TypeError("locale_content requires a bounded locale");
+  if (
+    record.item_operation !== "created" &&
+    record.item_operation !== "updated" &&
+    record.item_operation !== "deleted"
+  )
+    throw new TypeError(
+      "locale_content requires created, updated, or deleted item operation",
+    );
+  const allowed = ["changed_fields", "locale", "item_operation"];
+  if (record.action === "legal_policy.updated") {
+    if (
+      (record.policy_type !== "terms" && record.policy_type !== "privacy") ||
+      record.version_number === undefined ||
+      !Number.isSafeInteger(record.version_number) ||
+      record.version_number < 1
+    )
+      throw new TypeError(
+        "legal policy requires policy_type and version_number",
+      );
+    allowed.push("policy_type", "version_number");
+  }
+  assertOnlyAuditAttributes(record, allowed);
+  return true;
+}
+
+function buildLocaleContentAuditRecord(
+  metadata: AuditMetadata,
+  action: Exclude<LocaleContentAction, "legal_policy.updated">,
+  id: string,
+  locale: string,
+  operation: AuditItemOperation,
+): AuditRecord {
+  return buildAuditRecord(
+    metadata,
+    { action, target_type: AUDIT_CATALOG[action], target_id: id },
+    {
+      changed_fields: ["locale_content"],
+      locale,
+      item_operation: operation,
+    },
+  );
+}
+
+export function buildPostLocaleContentAuditRecord(
+  m: AuditMetadata,
+  id: string,
+  locale: string,
+  operation: AuditItemOperation,
+): AuditRecord {
+  return buildLocaleContentAuditRecord(
+    m,
+    "post.updated",
+    id,
+    locale,
+    operation,
+  );
+}
+
+export function buildPageLocaleContentAuditRecord(
+  m: AuditMetadata,
+  id: string,
+  locale: string,
+  operation: AuditItemOperation,
+): AuditRecord {
+  return buildLocaleContentAuditRecord(
+    m,
+    "page.updated",
+    id,
+    locale,
+    operation,
+  );
+}
+
+export function buildWorkLocaleContentAuditRecord(
+  m: AuditMetadata,
+  id: string,
+  locale: string,
+  operation: AuditItemOperation,
+): AuditRecord {
+  return buildLocaleContentAuditRecord(
+    m,
+    "work.updated",
+    id,
+    locale,
+    operation,
+  );
+}
+
+export function buildPostSeriesLocaleContentAuditRecord(
+  m: AuditMetadata,
+  id: string,
+  locale: string,
+  operation: AuditItemOperation,
+): AuditRecord {
+  return buildLocaleContentAuditRecord(
+    m,
+    "post_series.updated",
+    id,
+    locale,
+    operation,
+  );
+}
+
+export function buildProgramEventLocaleContentAuditRecord(
+  m: AuditMetadata,
+  id: string,
+  locale: string,
+  operation: AuditItemOperation,
+): AuditRecord {
+  return buildLocaleContentAuditRecord(
+    m,
+    "program_event.updated",
+    id,
+    locale,
+    operation,
+  );
+}
+
+export function buildReleaseLocaleContentAuditRecord(
+  m: AuditMetadata,
+  id: string,
+  locale: string,
+  operation: AuditItemOperation,
+): AuditRecord {
+  return buildLocaleContentAuditRecord(
+    m,
+    "release.updated",
+    id,
+    locale,
+    operation,
+  );
+}
+
+export function buildArtistLocaleContentAuditRecord(
+  m: AuditMetadata,
+  id: string,
+  locale: string,
+  operation: AuditItemOperation,
+): AuditRecord {
+  return buildLocaleContentAuditRecord(
+    m,
+    "artist.updated",
+    id,
+    locale,
+    operation,
+  );
+}
+
+export function buildLabelLocaleContentAuditRecord(
+  m: AuditMetadata,
+  id: string,
+  locale: string,
+  operation: AuditItemOperation,
+): AuditRecord {
+  return buildLocaleContentAuditRecord(
+    m,
+    "label.updated",
+    id,
+    locale,
+    operation,
+  );
+}
+
+export function buildMenuLocaleContentAuditRecord(
+  m: AuditMetadata,
+  id: string,
+  locale: string,
+  operation: AuditItemOperation,
+): AuditRecord {
+  return buildLocaleContentAuditRecord(
+    m,
+    "menu.updated",
+    id,
+    locale,
+    operation,
+  );
+}
+
+export function buildCampaignLocaleContentAuditRecord(
+  m: AuditMetadata,
+  id: string,
+  locale: string,
+  operation: AuditItemOperation,
+): AuditRecord {
+  return buildLocaleContentAuditRecord(
+    m,
+    "campaign.updated",
+    id,
+    locale,
+    operation,
+  );
+}
+
+export function buildFormLocaleContentAuditRecord(
+  m: AuditMetadata,
+  id: string,
+  locale: string,
+  operation: AuditItemOperation,
+): AuditRecord {
+  return buildLocaleContentAuditRecord(
+    m,
+    "form.updated",
+    id,
+    locale,
+    operation,
+  );
+}
+
+export function buildEmailTemplateLocaleContentAuditRecord(
+  m: AuditMetadata,
+  id: string,
+  locale: string,
+  operation: AuditItemOperation,
+): AuditRecord {
+  return buildLocaleContentAuditRecord(
+    m,
+    "email_template.updated",
+    id,
+    locale,
+    operation,
+  );
+}
+
+export function buildEmailLayoutLocaleContentAuditRecord(
+  m: AuditMetadata,
+  id: string,
+  locale: string,
+  operation: AuditItemOperation,
+): AuditRecord {
+  return buildLocaleContentAuditRecord(
+    m,
+    "email_layout.updated",
+    id,
+    locale,
+    operation,
+  );
+}
+
+function buildLegalPolicyLocaleContentAuditRecord(
+  metadata: AuditMetadata,
+  id: string,
+  policyType: "terms" | "privacy",
+  versionNumber: number,
+  locale: string,
+  operation: AuditItemOperation,
+): AuditRecord {
+  return buildAuditRecord(
+    metadata,
+    {
+      action: "legal_policy.updated",
+      target_type: AUDIT_CATALOG["legal_policy.updated"],
+      target_id: id,
+    },
+    {
+      policy_type: policyType,
+      version_number: versionNumber,
+      changed_fields: ["locale_content"],
+      locale,
+      item_operation: operation,
+    },
+  );
+}
+
+export function buildPrivacyLocaleContentAuditRecord(
+  m: AuditMetadata,
+  id: string,
+  versionNumber: number,
+  locale: string,
+  operation: AuditItemOperation,
+): AuditRecord {
+  return buildLegalPolicyLocaleContentAuditRecord(
+    m,
+    id,
+    "privacy",
+    versionNumber,
+    locale,
+    operation,
+  );
+}
+
+export function buildTermsLocaleContentAuditRecord(
+  m: AuditMetadata,
+  id: string,
+  versionNumber: number,
+  locale: string,
+  operation: AuditItemOperation,
+): AuditRecord {
+  return buildLegalPolicyLocaleContentAuditRecord(
+    m,
+    id,
+    "terms",
+    versionNumber,
+    locale,
+    operation,
+  );
+}