deepline 0.3.88 → 0.3.90

package/dist/bundling-sources/shared_libs/product-notifications/configuration.ts

@@ -0,0 +1,566 @@
+export type ProductNotificationFactValue = string | number | boolean;
+export type ProductNotificationFacts = Record<
+  string,
+  ProductNotificationFactValue
+>;
+
+const PRODUCT_NOTIFICATION_EMAIL_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+/** Normalize an email destination consistently across API, CLI, and delivery. */
+export function normalizeProductNotificationEmail(
+  value: unknown,
+): string | null {
+  const email = typeof value === 'string' ? value.trim().toLowerCase() : '';
+  return email &&
+    email.length <= 320 &&
+    PRODUCT_NOTIFICATION_EMAIL_PATTERN.test(email)
+    ? email
+    : null;
+}
+
+export function normalizeProductNotificationEmailList(
+  values: readonly string[] | undefined,
+  label: string,
+  maximum = 50,
+) {
+  const normalized = (values ?? []).map((value) => {
+    const email = normalizeProductNotificationEmail(value);
+    if (!email) throw new Error(`${label} contains an invalid email address.`);
+    return email;
+  });
+  if (new Set(normalized).size !== normalized.length) {
+    throw new Error(`${label} contains a duplicate email address.`);
+  }
+  if (normalized.length > maximum) {
+    throw new Error(`${label} exceeds ${maximum} recipients.`);
+  }
+  return normalized;
+}
+
+export type ProductNotificationDestinationSettings =
+  | {
+      kind: 'slack';
+      targetKind: 'channel' | 'member';
+      targetId: string;
+      targetName: string;
+      oauthConnectionId: string;
+    }
+  | {
+      kind: 'email_addresses';
+      to: string[];
+      cc?: string[];
+      bcc?: string[];
+    }
+  | { kind: 'email_roles'; roles: string[] };
+
+export type ProductNotificationTrigger =
+  | { kind: 'each_match' }
+  | { kind: 'state_transition'; targetState: string; reasonCode?: string }
+  | {
+      kind: 'threshold_crossing';
+      direction: 'above' | 'below' | 'at_or_above';
+      threshold: number;
+      unit?: string;
+    }
+  | {
+      kind: 'consecutive_outcomes';
+      count: number;
+      outcome: string;
+      maxLookback: number;
+    };
+
+export type ProductNotificationDeliveryTiming =
+  | { mode: 'immediate' }
+  | {
+      mode: 'immediate_first' | 'digest_only' | 'rolling_limit';
+      windowMs: number;
+    };
+
+export const DEFAULT_PRODUCT_NOTIFICATION_DELIVERY_TIMING: ProductNotificationDeliveryTiming =
+  {
+    mode: 'rolling_limit',
+    windowMs: 3_600_000,
+  };
+
+export type ProductNotificationRepeatMode = 'on_enter' | 'every_match';
+
+export type ProductNotificationDefaultPolicy = {
+  version: number;
+  groups: ProductNotificationDefaultGroup[];
+  destinations: ProductNotificationDefaultDestination[];
+  rules: ProductNotificationDefaultRule[];
+};
+
+export type ProductNotificationDefaultGroup = {
+  groupKey: string;
+  name: string;
+  enabled: boolean;
+  /** Omitted only by stored compatibility rows; effective groups are normalized. */
+  deliveryTiming?: ProductNotificationDeliveryTiming;
+};
+
+export type ProductNotificationDefaultDestination = {
+  destinationKey: string;
+  groupKey: string;
+  name: string;
+  enabled: boolean;
+  settings: ProductNotificationDestinationSettings;
+};
+
+export type ProductNotificationDefaultRule = {
+  ruleKey: string;
+  groupKey: string;
+  enabled: boolean;
+  notificationType: string;
+  eventName: string;
+  eventFilter: ProductNotificationFacts;
+  trigger: ProductNotificationTrigger;
+  /** Omitted only by stored compatibility rows; effective rules are normalized. */
+  repeatMode?: ProductNotificationRepeatMode;
+  /** Omitted only by stored compatibility rows; effective rules are normalized. */
+  conditionGeneration?: number;
+};
+
+export type ProductNotificationConfigMode =
+  | 'custom'
+  | 'replace_default'
+  | 'disable_default';
+
+type WorkspaceOverride = {
+  configMode: ProductNotificationConfigMode;
+  defaultKey?: string;
+};
+
+export type ProductNotificationWorkspaceGroup =
+  ProductNotificationDefaultGroup & WorkspaceOverride & { version: number };
+
+export type ProductNotificationWorkspaceDestination =
+  ProductNotificationDefaultDestination &
+    WorkspaceOverride & {
+      version: number;
+      status: string;
+    };
+
+export type ProductNotificationWorkspaceRule = ProductNotificationDefaultRule &
+  WorkspaceOverride & { version: number };
+
+/** The provider-neutral state edited by UI and CLI clients for one group. */
+export type ProductNotificationGroupDraft = {
+  group: EffectiveProductNotificationGroup;
+  destinations: EffectiveProductNotificationDestination[];
+  rules: EffectiveProductNotificationRule[];
+};
+
+/** Public configuration intent. Convex alone derives sparse override writes. */
+export type ProductNotificationConfigurationChange =
+  | { kind: 'save_group'; draft: ProductNotificationGroupDraft }
+  | { kind: 'delete_group'; groupKey: string };
+
+export type EffectiveProductNotificationGroup = Omit<
+  ProductNotificationDefaultGroup,
+  'deliveryTiming'
+> & {
+  deliveryTiming: ProductNotificationDeliveryTiming;
+  source: 'default' | 'workspace';
+  configMode: 'default' | ProductNotificationConfigMode;
+  defaultKey?: string;
+  version: number;
+};
+
+export type EffectiveProductNotificationDestination =
+  ProductNotificationDefaultDestination & {
+    source: 'default' | 'workspace';
+    configMode: 'default' | ProductNotificationConfigMode;
+    defaultKey?: string;
+    version: number;
+    status: string;
+  };
+
+export type EffectiveProductNotificationRule = Omit<
+  ProductNotificationDefaultRule,
+  'repeatMode' | 'conditionGeneration'
+> & {
+  repeatMode: ProductNotificationRepeatMode;
+  conditionGeneration: number;
+  source: 'default' | 'workspace';
+  configMode: 'default' | ProductNotificationConfigMode;
+  defaultKey?: string;
+  version: number;
+};
+
+export function normalizeProductNotificationRepeatMode(
+  value: ProductNotificationRepeatMode | undefined,
+): ProductNotificationRepeatMode {
+  return value ?? 'on_enter';
+}
+
+export function normalizeProductNotificationDeliveryTiming(
+  value: ProductNotificationDeliveryTiming | undefined,
+): ProductNotificationDeliveryTiming {
+  return value ?? { mode: 'immediate' };
+}
+
+export function validateProductNotificationDeliveryTiming(
+  timing: ProductNotificationDeliveryTiming,
+) {
+  if (timing.mode === 'immediate') return timing;
+  if (
+    !Number.isInteger(timing.windowMs) ||
+    timing.windowMs < 1_000 ||
+    timing.windowMs > 86_400_000
+  ) {
+    throw new Error('Notification digest window is outside its bounds.');
+  }
+  return timing;
+}
+
+export function normalizeProductNotificationConditionGeneration(
+  value: number | undefined,
+): number {
+  return value ?? 1;
+}
+
+function withoutLegacyRuleEmission(value: ProductNotificationDefaultRule) {
+  const { emission: _legacyEmission, ...rule } =
+    value as ProductNotificationDefaultRule & { emission?: unknown };
+  return rule;
+}
+
+export type EffectiveProductNotificationConfiguration = {
+  /** Exact policy used to materialize this effective configuration. */
+  defaultPolicy: ProductNotificationDefaultPolicy | null;
+  workspaceVersion: number;
+  groups: EffectiveProductNotificationGroup[];
+  destinations: EffectiveProductNotificationDestination[];
+  rules: EffectiveProductNotificationRule[];
+};
+
+type KeyedDefault = { [key: string]: unknown };
+type KeyedOverride = WorkspaceOverride & { [key: string]: unknown };
+
+export function productNotificationValuesEqual(
+  left: unknown,
+  right: unknown,
+): boolean {
+  if (Object.is(left, right)) return true;
+  if (Array.isArray(left) || Array.isArray(right)) {
+    return (
+      Array.isArray(left) &&
+      Array.isArray(right) &&
+      left.length === right.length &&
+      left.every((value, index) =>
+        productNotificationValuesEqual(value, right[index]),
+      )
+    );
+  }
+  if (
+    typeof left !== 'object' ||
+    left === null ||
+    typeof right !== 'object' ||
+    right === null
+  ) {
+    return false;
+  }
+  const leftRecord = left as Record<string, unknown>;
+  const rightRecord = right as Record<string, unknown>;
+  const leftKeys = Object.keys(leftRecord).filter(
+    (key) => leftRecord[key] !== undefined,
+  );
+  const rightKeys = Object.keys(rightRecord).filter(
+    (key) => rightRecord[key] !== undefined,
+  );
+  return (
+    leftKeys.length === rightKeys.length &&
+    leftKeys.every(
+      (key) =>
+        Object.prototype.hasOwnProperty.call(rightRecord, key) &&
+        productNotificationValuesEqual(leftRecord[key], rightRecord[key]),
+    )
+  );
+}
+
+function assertUniqueKeys<T extends KeyedDefault>(
+  values: readonly T[],
+  keyName: keyof T & string,
+  label: string,
+) {
+  const seen = new Set<string>();
+  for (const value of values) {
+    const key = value[keyName];
+    if (typeof key !== 'string' || key.length === 0) {
+      throw new Error(`${label} has an empty ${keyName}.`);
+    }
+    if (seen.has(key)) throw new Error(`Duplicate ${label} key: ${key}.`);
+    seen.add(key);
+  }
+}
+
+function overlayDefaults<
+  TDefault extends KeyedDefault,
+  TOverride extends KeyedOverride,
+  TEffective,
+>(input: {
+  defaults: readonly TDefault[];
+  overrides: readonly TOverride[];
+  keyName: keyof TDefault & keyof TOverride & string;
+  label: string;
+  defaultVersion: number;
+  fromDefault: (value: TDefault, version: number) => TEffective;
+  fromWorkspace: (value: TOverride) => TEffective;
+}) {
+  assertUniqueKeys(input.defaults, input.keyName, `default ${input.label}`);
+  assertUniqueKeys(input.overrides, input.keyName, `workspace ${input.label}`);
+
+  const defaultKeys = new Set(
+    input.defaults.map((value) => value[input.keyName] as string),
+  );
+  const effective = new Map<string, TEffective>();
+  for (const value of input.defaults) {
+    effective.set(
+      value[input.keyName] as string,
+      input.fromDefault(value, input.defaultVersion),
+    );
+  }
+
+  for (const value of input.overrides) {
+    const key = value[input.keyName] as string;
+    if (value.configMode === 'custom') {
+      if (value.defaultKey !== undefined) {
+        throw new Error(`Custom ${input.label} ${key} cannot name a default.`);
+      }
+      if (defaultKeys.has(key)) {
+        throw new Error(
+          `Custom ${input.label} ${key} conflicts with a default key.`,
+        );
+      }
+      effective.set(key, input.fromWorkspace(value));
+      continue;
+    }
+
+    if (!value.defaultKey || value.defaultKey !== key) {
+      throw new Error(
+        `${input.label} ${key} must use its own key as defaultKey.`,
+      );
+    }
+    if (value.configMode === 'disable_default') {
+      effective.delete(key);
+    } else {
+      effective.set(key, input.fromWorkspace(value));
+    }
+  }
+
+  return [...effective.values()];
+}
+
+/**
+ * Materialize the one effective configuration shared by settings surfaces and
+ * asynchronous event processing. The function is deliberately pure so copy-
+ * on-write behavior can be tested without starting notification delivery.
+ */
+export function resolveEffectiveProductNotificationConfiguration(input: {
+  policy: ProductNotificationDefaultPolicy;
+  workspaceVersion?: number;
+  groups: readonly ProductNotificationWorkspaceGroup[];
+  destinations: readonly ProductNotificationWorkspaceDestination[];
+  rules: readonly ProductNotificationWorkspaceRule[];
+}): EffectiveProductNotificationConfiguration {
+  const workspaceVersion = input.workspaceVersion ?? 0;
+  const defaultGroupKeys = new Set(
+    input.policy.groups.map((group) => group.groupKey),
+  );
+  const defaultDestinationGroups = new Map(
+    input.policy.destinations.map((destination) => [
+      destination.destinationKey,
+      destination.groupKey,
+    ]),
+  );
+  const destinationOverrides = new Map(
+    input.destinations.map((destination) => [
+      destination.destinationKey,
+      destination,
+    ]),
+  );
+  const defaultRuleGroups = new Map(
+    input.policy.rules.map((rule) => [rule.ruleKey, rule.groupKey]),
+  );
+  const ruleOverrides = new Map(
+    input.rules.map((rule) => [rule.ruleKey, rule]),
+  );
+  const replacedDefaultGroupKeys = new Set(
+    input.groups
+      .filter((group) => group.configMode === 'replace_default')
+      .map((group) => group.groupKey),
+  );
+  for (const destination of input.policy.destinations) {
+    if (!defaultGroupKeys.has(destination.groupKey)) {
+      throw new Error(
+        `Default destination ${destination.destinationKey} references missing group ${destination.groupKey}.`,
+      );
+    }
+  }
+  for (const rule of input.policy.rules) {
+    if (!defaultGroupKeys.has(rule.groupKey)) {
+      throw new Error(
+        `Default rule ${rule.ruleKey} references missing group ${rule.groupKey}.`,
+      );
+    }
+  }
+
+  const groups = overlayDefaults<
+    ProductNotificationDefaultGroup,
+    ProductNotificationWorkspaceGroup,
+    EffectiveProductNotificationGroup
+  >({
+    defaults: input.policy.groups,
+    overrides: input.groups,
+    keyName: 'groupKey',
+    label: 'group',
+    defaultVersion: input.policy.version,
+    fromDefault: (value, version) => ({
+      ...value,
+      deliveryTiming: normalizeProductNotificationDeliveryTiming(
+        value.deliveryTiming,
+      ),
+      source: 'default' as const,
+      configMode: 'default' as const,
+      version,
+    }),
+    fromWorkspace: (value) => ({
+      groupKey: value.groupKey,
+      name: value.name,
+      enabled: value.enabled,
+      deliveryTiming: normalizeProductNotificationDeliveryTiming(
+        value.deliveryTiming,
+      ),
+      source: 'workspace' as const,
+      configMode: value.configMode,
+      defaultKey: value.defaultKey,
+      version: value.version,
+    }),
+  });
+  const groupKeys = new Set(groups.map((group) => group.groupKey));
+
+  const destinations = overlayDefaults<
+    ProductNotificationDefaultDestination,
+    ProductNotificationWorkspaceDestination,
+    EffectiveProductNotificationDestination
+  >({
+    defaults: input.policy.destinations.filter(
+      (destination) =>
+        !replacedDefaultGroupKeys.has(destination.groupKey) ||
+        destinationOverrides.has(destination.destinationKey),
+    ),
+    overrides: input.destinations,
+    keyName: 'destinationKey',
+    label: 'destination',
+    defaultVersion: input.policy.version,
+    fromDefault: (value, version) => ({
+      ...value,
+      source: 'default' as const,
+      configMode: 'default' as const,
+      version,
+      status: 'active',
+    }),
+    fromWorkspace: (value) => ({
+      destinationKey: value.destinationKey,
+      groupKey: value.groupKey,
+      name: value.name,
+      enabled: value.enabled,
+      settings: value.settings,
+      status: value.status,
+      source: 'workspace' as const,
+      configMode: value.configMode,
+      defaultKey: value.defaultKey,
+      version: value.version,
+    }),
+  }).filter((destination) => {
+    if (groupKeys.has(destination.groupKey)) return true;
+    const override = destinationOverrides.get(destination.destinationKey);
+    const isInheritedChild =
+      destination.source === 'default' ||
+      (override?.configMode === 'replace_default' &&
+        defaultDestinationGroups.get(destination.destinationKey) ===
+          destination.groupKey);
+    if (isInheritedChild && defaultGroupKeys.has(destination.groupKey)) {
+      return false;
+    }
+    throw new Error(
+      `${destination.source === 'default' ? 'Default' : 'Workspace'} destination ${destination.destinationKey} references missing group ${destination.groupKey}.`,
+    );
+  });
+
+  const rules = overlayDefaults<
+    ProductNotificationDefaultRule,
+    ProductNotificationWorkspaceRule,
+    EffectiveProductNotificationRule
+  >({
+    defaults: input.policy.rules.filter(
+      (rule) =>
+        !replacedDefaultGroupKeys.has(rule.groupKey) ||
+        ruleOverrides.has(rule.ruleKey),
+    ),
+    overrides: input.rules,
+    keyName: 'ruleKey',
+    label: 'rule',
+    defaultVersion: input.policy.version,
+    fromDefault: (value, version) => ({
+      ...withoutLegacyRuleEmission(value),
+      repeatMode: normalizeProductNotificationRepeatMode(value.repeatMode),
+      conditionGeneration: normalizeProductNotificationConditionGeneration(
+        value.conditionGeneration,
+      ),
+      source: 'default' as const,
+      configMode: 'default' as const,
+      version,
+    }),
+    fromWorkspace: (value) => ({
+      ruleKey: value.ruleKey,
+      groupKey: value.groupKey,
+      enabled: value.enabled,
+      notificationType: value.notificationType,
+      eventName: value.eventName,
+      eventFilter: value.eventFilter,
+      trigger: value.trigger,
+      repeatMode: normalizeProductNotificationRepeatMode(value.repeatMode),
+      conditionGeneration: normalizeProductNotificationConditionGeneration(
+        value.conditionGeneration,
+      ),
+      source: 'workspace' as const,
+      configMode: value.configMode,
+      defaultKey: value.defaultKey,
+      version: value.version,
+    }),
+  }).filter((rule) => {
+    if (groupKeys.has(rule.groupKey)) return true;
+    const override = ruleOverrides.get(rule.ruleKey);
+    const isInheritedChild =
+      rule.source === 'default' ||
+      (override?.configMode === 'replace_default' &&
+        defaultRuleGroups.get(rule.ruleKey) === rule.groupKey);
+    if (isInheritedChild && defaultGroupKeys.has(rule.groupKey)) {
+      return false;
+    }
+    throw new Error(
+      `${rule.source === 'default' ? 'Default' : 'Workspace'} rule ${rule.ruleKey} references missing group ${rule.groupKey}.`,
+    );
+  });
+
+  return {
+    defaultPolicy: {
+      version: input.policy.version,
+      groups: input.policy.groups,
+      destinations: input.policy.destinations,
+      rules: input.policy.rules.map((rule) => ({
+        ...rule,
+        repeatMode: normalizeProductNotificationRepeatMode(rule.repeatMode),
+        conditionGeneration: normalizeProductNotificationConditionGeneration(
+          rule.conditionGeneration,
+        ),
+      })),
+    },
+    workspaceVersion,
+    groups,
+    destinations,
+    rules,
+  };
+}

package/dist/bundling-sources/shared_libs/product-notifications/content.ts

@@ -0,0 +1,28 @@
+/** Type-owned content, independent of email markup and persisted audit strings. */
+export type NotificationText =
+  | string
+  | readonly (string | { strong: string } | { workspace: true })[];
+
+export function notificationText(
+  content: NotificationText,
+  workspaceName?: string,
+): string {
+  if (typeof content === 'string') return content;
+  return content
+    .map((part) => {
+      if (typeof part === 'string') return part;
+      if ('strong' in part) return part.strong;
+      return workspaceName ? `workspace ${workspaceName}` : 'workspace';
+    })
+    .join('');
+}
+
+export function joinNotificationText(
+  contents: NotificationText[],
+  separator: string,
+): NotificationText {
+  return contents.flatMap((content, index) => [
+    ...(index ? [separator] : []),
+    ...(typeof content === 'string' ? [content] : content),
+  ]);
+}

package/dist/bundling-sources/shared_libs/product-notifications/default-policy.ts

@@ -0,0 +1,60 @@
+import {
+  PRODUCT_NOTIFICATION_DEFAULT_RULES,
+  validateProductNotificationRuleDefinition,
+} from './catalog';
+import {
+  DEFAULT_PRODUCT_NOTIFICATION_DELIVERY_TIMING,
+  resolveEffectiveProductNotificationConfiguration,
+  validateProductNotificationDeliveryTiming,
+  type ProductNotificationDefaultPolicy,
+} from './configuration';
+
+/**
+ * Product defaults stay in code. Workspaces see these rows synthetically until
+ * they create sparse copy-on-write overrides.
+ */
+export const CURRENT_PRODUCT_NOTIFICATION_DEFAULT_POLICY = {
+  version: 5,
+  groups: [
+    {
+      groupKey: 'default',
+      name: 'Default Notifications',
+      enabled: true,
+      deliveryTiming: DEFAULT_PRODUCT_NOTIFICATION_DELIVERY_TIMING,
+    },
+  ],
+  destinations: [
+    {
+      destinationKey: 'default.roles',
+      groupKey: 'default',
+      name: 'Workspace owners',
+      enabled: true,
+      settings: { kind: 'email_roles', roles: ['owner'] },
+    },
+  ],
+  rules: PRODUCT_NOTIFICATION_DEFAULT_RULES,
+} satisfies ProductNotificationDefaultPolicy;
+
+/** Validate the complete code-owned policy. */
+export function validateProductNotificationDefaultPolicy(
+  policy: ProductNotificationDefaultPolicy,
+) {
+  if (!Number.isInteger(policy.version) || policy.version < 1) {
+    throw new Error('Notification default policy version must be positive.');
+  }
+  resolveEffectiveProductNotificationConfiguration({
+    policy,
+    groups: [],
+    destinations: [],
+    rules: [],
+  });
+  for (const rule of policy.rules) {
+    validateProductNotificationRuleDefinition(rule);
+  }
+  for (const group of policy.groups) {
+    validateProductNotificationDeliveryTiming(
+      group.deliveryTiming ?? { mode: 'immediate' },
+    );
+  }
+  return policy;
+}