deepline 0.3.88 → 0.3.89

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

@@ -0,0 +1,246 @@
+import {
+  normalizeProductNotificationEmail,
+  normalizeProductNotificationEmailList,
+  type ProductNotificationDestinationSettings,
+} from './configuration';
+import {
+  workspaceAppUrl,
+  notificationSettingsUrl,
+  type NotificationWorkspace,
+} from './workspace';
+import { notificationText, type NotificationText } from './content';
+
+export {
+  normalizeProductNotificationEmail,
+  normalizeProductNotificationEmailList,
+};
+
+export type ProductNotificationEmailRequest = {
+  to: string[];
+  cc?: string[];
+  bcc?: string[];
+  headers?: Record<string, string>;
+  subject: string;
+  html: string;
+  text: string;
+};
+
+type ProductNotificationEmailContent = {
+  groupName: string;
+  title: string;
+  summary: NotificationText;
+  details: NotificationText[];
+  targetUrl?: string;
+};
+
+const MAX_RECIPIENTS = 50;
+
+export function productNotificationEmailAddressVersion(email: string): string {
+  const normalized = normalizeProductNotificationEmail(email);
+  if (!normalized) throw new Error('Notification email address is invalid.');
+  let hash = 0x811c9dc5;
+  for (const character of normalized) {
+    hash ^= character.charCodeAt(0);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return `email-v1-${(hash >>> 0).toString(36)}`;
+}
+
+function escapeHtml(value: string): string {
+  return value.replace(/[&<>"']/g, (character) => {
+    if (character === '&') return '&amp;';
+    if (character === '<') return '&lt;';
+    if (character === '>') return '&gt;';
+    if (character === '"') return '&quot;';
+    return '&#39;';
+  });
+}
+
+function unsubscribeUrl(value: string): string {
+  const url = new URL(value);
+  if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+    throw new Error('Notification unsubscribe URL must use HTTP(S).');
+  }
+  return url.toString();
+}
+
+function contentHtml(
+  content: NotificationText,
+  workspaceName?: string,
+): string {
+  if (typeof content === 'string') return escapeHtml(content);
+  return content
+    .map((part) => {
+      if (typeof part === 'string') return escapeHtml(part);
+      if ('strong' in part)
+        return `<strong>${escapeHtml(part.strong)}</strong>`;
+      return workspaceName
+        ? `workspace <strong>${escapeHtml(workspaceName)}</strong>`
+        : 'workspace';
+    })
+    .join('');
+}
+
+export function renderProductNotificationEmail(
+  input: NotificationWorkspace & {
+    groupKey: string;
+    content: ProductNotificationEmailContent;
+    settings: Extract<
+      ProductNotificationDestinationSettings,
+      { kind: 'email_addresses' }
+    >;
+    unsubscribeUrl?: string;
+    oneClickUnsubscribeUrl?: string;
+  },
+): ProductNotificationEmailRequest {
+  const to = normalizeProductNotificationEmailList(
+    input.settings.to,
+    'Email recipients',
+  );
+  const cc = normalizeProductNotificationEmailList(
+    input.settings.cc,
+    'Email CC',
+  );
+  const bcc = normalizeProductNotificationEmailList(
+    input.settings.bcc,
+    'Email BCC',
+  );
+  if (to.length === 0) throw new Error('Email delivery requires a recipient.');
+  if (to.length + cc.length + bcc.length > MAX_RECIPIENTS) {
+    throw new Error(
+      `Email delivery exceeds the ${MAX_RECIPIENTS}-recipient limit.`,
+    );
+  }
+
+  const targetUrl = input.content.targetUrl
+    ? workspaceAppUrl(input.appUrl, input.workspaceId, input.content.targetUrl)
+    : null;
+  const settingsUrl = notificationSettingsUrl(input, input.groupKey);
+  const logoUrl =
+    targetUrl ?? workspaceAppUrl(input.appUrl, input.workspaceId, '/dashboard');
+  const optOutUrl = input.unsubscribeUrl
+    ? unsubscribeUrl(input.unsubscribeUrl)
+    : null;
+  const oneClickOptOutUrl = input.oneClickUnsubscribeUrl
+    ? unsubscribeUrl(input.oneClickUnsubscribeUrl)
+    : optOutUrl;
+  const text = [
+    input.content.title,
+    `Notification group: ${input.content.groupName}`,
+    ...(targetUrl ? [`Open Deepline: ${targetUrl}`] : []),
+    '',
+    notificationText(input.content.summary, input.workspaceName),
+    ...input.content.details.map((detail) =>
+      notificationText(detail, input.workspaceName),
+    ),
+    '',
+    `Manage notifications: ${settingsUrl}`,
+    ...(optOutUrl
+      ? [`Unsubscribe from ${input.content.groupName} email: ${optOutUrl}`]
+      : []),
+  ].join('\n');
+  const html = [
+    '<table role="presentation" width="100%" cellspacing="0" cellpadding="0" style="background-color:#fff;color:#111827"><tr><td align="center" style="padding:32px 16px">',
+    '<table role="presentation" width="600" cellspacing="0" cellpadding="0" style="width:100%;max-width:600px"><tr><td style="font-family:Arial,Helvetica,sans-serif;font-size:16px;line-height:1.5;text-align:left">',
+    `<a href="${escapeHtml(logoUrl)}"><img src="https://code.deepline.com/brand/logo_full_dark.png" width="140" height="26" alt="Deepline" style="display:block;border:0;margin:0 0 32px"></a>`,
+    `<h1 style="font-size:24px;line-height:1.25;font-weight:600;letter-spacing:-0.02em;margin:0 0 4px">${escapeHtml(input.content.title)}</h1>`,
+    '<div style="padding-left:20px">',
+    `<p style="margin:0 0 4px"><strong>Notification group:</strong> ${escapeHtml(input.content.groupName)}</p>`,
+    ...(targetUrl
+      ? [
+          `<p style="margin:0"><a href="${escapeHtml(targetUrl)}" style="color:#1919ff">Open Deepline</a></p>`,
+        ]
+      : []),
+    '</div>',
+    '<div style="margin:24px 0;padding:20px;border:1px solid #1919ff;border-radius:8px;color:#111827;font-size:18px;line-height:1.5">',
+    `<p style="margin:0">${contentHtml(input.content.summary, input.workspaceName)}</p>`,
+    ...input.content.details.map(
+      (detail) =>
+        `<p style="margin:4px 0 0">${contentHtml(detail, input.workspaceName)}</p>`,
+    ),
+    '</div>',
+    '<hr style="border:0;border-top:1px solid #e5e7eb;margin:32px 0 24px">',
+    `<p style="color:#666;font-size:12px"><a href="${escapeHtml(settingsUrl)}" style="color:#666">Manage notifications</a></p>`,
+    ...(optOutUrl
+      ? [
+          `<p style="color:#666;font-size:12px"><a href="${escapeHtml(optOutUrl)}">Unsubscribe from ${escapeHtml(input.content.groupName)} email</a></p>`,
+        ]
+      : []),
+    '</td></tr></table></td></tr></table>',
+  ].join('');
+
+  return {
+    to,
+    ...(cc.length > 0 ? { cc } : {}),
+    ...(bcc.length > 0 ? { bcc } : {}),
+    ...(oneClickOptOutUrl
+      ? {
+          headers: {
+            'List-Unsubscribe': `<${oneClickOptOutUrl}>`,
+            'List-Unsubscribe-Post': 'List-Unsubscribe=One-Click',
+          },
+        }
+      : {}),
+    subject: input.workspaceName
+      ? `${input.content.title} — ${input.workspaceName}`
+      : input.content.title,
+    html,
+    text,
+  };
+}
+
+export function parseProductNotificationEmailRequest(
+  value: string,
+): ProductNotificationEmailRequest {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(value);
+  } catch {
+    throw new Error('Email delivery request is not valid JSON.');
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error('Email delivery request is invalid.');
+  }
+  const request = parsed as Partial<ProductNotificationEmailRequest>;
+  if (
+    !Array.isArray(request.to) ||
+    typeof request.subject !== 'string' ||
+    !request.subject.trim() ||
+    typeof request.html !== 'string' ||
+    !request.html ||
+    typeof request.text !== 'string' ||
+    !request.text
+  ) {
+    throw new Error('Email delivery request is incomplete.');
+  }
+  const to = normalizeProductNotificationEmailList(
+    request.to,
+    'Email recipients',
+  );
+  const cc = normalizeProductNotificationEmailList(request.cc, 'Email CC');
+  const bcc = normalizeProductNotificationEmailList(request.bcc, 'Email BCC');
+  const headers = request.headers;
+  if (
+    headers !== undefined &&
+    (!headers ||
+      typeof headers !== 'object' ||
+      Array.isArray(headers) ||
+      Object.entries(headers).some(
+        ([name, value]) => !name.trim() || typeof value !== 'string',
+      ))
+  ) {
+    throw new Error('Email delivery headers are invalid.');
+  }
+  if (to.length === 0 || to.length + cc.length + bcc.length > MAX_RECIPIENTS) {
+    throw new Error('Email delivery recipient count is invalid.');
+  }
+  return {
+    to,
+    ...(cc.length > 0 ? { cc } : {}),
+    ...(bcc.length > 0 ? { bcc } : {}),
+    ...(headers ? { headers } : {}),
+    subject: request.subject,
+    html: request.html,
+    text: request.text,
+  };
+}

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

@@ -0,0 +1,280 @@
+import type {
+  ProductNotificationFacts,
+  ProductNotificationTrigger,
+} from './configuration';
+
+export const PRODUCT_NOTIFICATION_DECISION_HORIZON_MS =
+  30 * 24 * 60 * 60 * 1_000;
+
+export type ProductNotificationOutcomeFact = {
+  orderingKey: string;
+  outcome: string;
+  occurredAt: number;
+  sourceEventId: string;
+};
+
+export type ProductNotificationObservation =
+  | { kind: 'match' }
+  | {
+      kind: 'state_transition';
+      previousState?: string;
+      currentState: string;
+      previousReasonCode?: string;
+      currentReasonCode?: string;
+      /** Compatibility alias for currentReasonCode. */
+      reasonCode?: string;
+    }
+  | {
+      kind: 'threshold_crossing';
+      previousValue: number;
+      currentValue: number;
+      unit?: string;
+    }
+  | { kind: 'threshold_state'; currentValue: number; unit?: string }
+  | {
+      kind: 'outcome_history';
+      /** Canonical newest-first history, beginning with the current event. */
+      outcomes: ProductNotificationOutcomeFact[];
+    };
+
+export type ProductNotificationTriggerDecision = {
+  fires: boolean;
+  reason:
+    | 'each_match'
+    | 'entered_state'
+    | 'crossed_threshold'
+    | 'condition_active'
+    | 'completed_streak'
+    | 'observation_mismatch'
+    | 'reason_mismatch'
+    | 'unit_mismatch'
+    | 'not_a_transition'
+    | 'not_a_crossing'
+    | 'insufficient_history'
+    | 'streak_already_active';
+};
+
+export function productNotificationFactsMatch(
+  filter: ProductNotificationFacts,
+  facts: ProductNotificationFacts,
+): boolean {
+  return Object.entries(filter).every(([key, value]) => facts[key] === value);
+}
+
+function compareCanonicalOrder(
+  left: ProductNotificationOutcomeFact,
+  right: ProductNotificationOutcomeFact,
+) {
+  return (
+    left.occurredAt - right.occurredAt ||
+    left.sourceEventId.localeCompare(right.sourceEventId)
+  );
+}
+
+function validateOutcomeHistory(
+  outcomes: ProductNotificationOutcomeFact[],
+  maximum: number,
+) {
+  if (outcomes.length > maximum) {
+    throw new Error(`Outcome history exceeds the ${maximum}-row bound.`);
+  }
+  const orderingKey = outcomes[0]?.orderingKey;
+  for (let index = 0; index < outcomes.length; index += 1) {
+    const outcome = outcomes[index]!;
+    if (
+      !outcome.orderingKey ||
+      outcome.orderingKey !== orderingKey ||
+      !outcome.outcome ||
+      !outcome.sourceEventId ||
+      !Number.isFinite(outcome.occurredAt)
+    ) {
+      throw new Error(
+        'Outcome history contains an invalid or cross-stream fact.',
+      );
+    }
+    const next = outcomes[index + 1];
+    if (next && compareCanonicalOrder(outcome, next) <= 0) {
+      throw new Error(
+        'Outcome history must be in canonical newest-first order.',
+      );
+    }
+  }
+}
+
+function decision(
+  fires: boolean,
+  reason: ProductNotificationTriggerDecision['reason'],
+): ProductNotificationTriggerDecision {
+  return { fires, reason };
+}
+
+export type ProductNotificationCondition = {
+  previousActive?: boolean;
+  currentActive: boolean;
+};
+
+function thresholdIsActive(
+  trigger: Extract<ProductNotificationTrigger, { kind: 'threshold_crossing' }>,
+  value: number,
+) {
+  return trigger.direction === 'below'
+    ? value < trigger.threshold
+    : trigger.direction === 'at_or_above'
+      ? value >= trigger.threshold
+      : value > trigger.threshold;
+}
+
+/** Map an observation to the one shared condition shape when it has durable state. */
+export function productNotificationCondition(input: {
+  trigger: ProductNotificationTrigger;
+  observation: ProductNotificationObservation;
+}): ProductNotificationCondition | null {
+  const { trigger, observation } = input;
+  if (trigger.kind === 'state_transition') {
+    if (observation.kind !== 'state_transition') return null;
+    const matches = (state: string, reasonCode: string | undefined) =>
+      state === trigger.targetState &&
+      (trigger.reasonCode === undefined || reasonCode === trigger.reasonCode);
+    const currentReasonCode =
+      observation.currentReasonCode ?? observation.reasonCode;
+    const previousReasonCode =
+      observation.previousReasonCode ??
+      (observation.previousState === observation.currentState
+        ? currentReasonCode
+        : undefined);
+    return {
+      previousActive:
+        observation.previousState === undefined
+          ? undefined
+          : matches(observation.previousState, previousReasonCode),
+      currentActive: matches(observation.currentState, currentReasonCode),
+    };
+  }
+  if (trigger.kind === 'threshold_crossing') {
+    if (
+      observation.kind !== 'threshold_crossing' &&
+      observation.kind !== 'threshold_state'
+    ) {
+      return null;
+    }
+    if (trigger.unit !== undefined && observation.unit !== trigger.unit) {
+      return null;
+    }
+    if (observation.kind === 'threshold_state') {
+      return {
+        currentActive: thresholdIsActive(trigger, observation.currentValue),
+      };
+    }
+    return {
+      previousActive: thresholdIsActive(trigger, observation.previousValue),
+      currentActive: thresholdIsActive(trigger, observation.currentValue),
+    };
+  }
+  if (trigger.kind !== 'consecutive_outcomes') return null;
+  if (observation.kind !== 'outcome_history') return null;
+  validateOutcomeHistory(observation.outcomes, trigger.maxLookback + 1);
+  const currentOccurredAt = observation.outcomes[0]?.occurredAt;
+  const outcomes =
+    currentOccurredAt === undefined
+      ? []
+      : observation.outcomes.filter(
+          (outcome) =>
+            outcome.occurredAt >=
+            currentOccurredAt - PRODUCT_NOTIFICATION_DECISION_HORIZON_MS,
+        );
+  const active = (offset: number) => {
+    const streak = outcomes.slice(offset, offset + trigger.count);
+    return (
+      streak.length === trigger.count &&
+      streak.every((outcome) => outcome.outcome === trigger.outcome)
+    );
+  };
+  return {
+    previousActive: active(1),
+    currentActive: active(0),
+  };
+}
+
+/** Deterministic provider-independent evaluation for the four V1 policies. */
+export function evaluateProductNotificationTrigger(input: {
+  trigger: ProductNotificationTrigger;
+  observation: ProductNotificationObservation;
+  occurredAt: number;
+}): ProductNotificationTriggerDecision {
+  const { trigger, observation, occurredAt } = input;
+  if (!Number.isFinite(occurredAt)) {
+    throw new Error('occurredAt must be finite.');
+  }
+  if (trigger.kind === 'each_match') return decision(true, 'each_match');
+
+  if (trigger.kind === 'state_transition') {
+    if (observation.kind !== 'state_transition') {
+      return decision(false, 'observation_mismatch');
+    }
+    const condition = productNotificationCondition({ trigger, observation });
+    const currentReasonCode =
+      observation.currentReasonCode ?? observation.reasonCode;
+    if (
+      trigger.reasonCode !== undefined &&
+      currentReasonCode !== trigger.reasonCode
+    ) {
+      return decision(false, 'reason_mismatch');
+    }
+    const fires =
+      condition?.previousActive === false && condition.currentActive === true;
+    return decision(fires, fires ? 'entered_state' : 'not_a_transition');
+  }
+
+  if (trigger.kind === 'threshold_crossing') {
+    if (
+      observation.kind !== 'threshold_crossing' &&
+      observation.kind !== 'threshold_state'
+    ) {
+      return decision(false, 'observation_mismatch');
+    }
+    const condition = productNotificationCondition({ trigger, observation });
+    if (!condition) {
+      return decision(false, 'unit_mismatch');
+    }
+    if (observation.kind === 'threshold_state') {
+      return decision(
+        condition.currentActive,
+        condition.currentActive ? 'condition_active' : 'not_a_crossing',
+      );
+    }
+    const fires =
+      condition.previousActive === false && condition.currentActive === true;
+    return decision(fires, fires ? 'crossed_threshold' : 'not_a_crossing');
+  }
+
+  if (observation.kind !== 'outcome_history') {
+    return decision(false, 'observation_mismatch');
+  }
+  if (
+    !Number.isInteger(trigger.count) ||
+    trigger.count < 1 ||
+    !Number.isInteger(trigger.maxLookback) ||
+    trigger.maxLookback < trigger.count ||
+    trigger.maxLookback > 100
+  ) {
+    throw new Error('Consecutive-outcome bounds are invalid.');
+  }
+  validateOutcomeHistory(observation.outcomes, trigger.maxLookback + 1);
+  const withinHorizon = observation.outcomes.filter(
+    (outcome) =>
+      outcome.occurredAt <= occurredAt &&
+      outcome.occurredAt >=
+        occurredAt - PRODUCT_NOTIFICATION_DECISION_HORIZON_MS,
+  );
+  const streak = withinHorizon.slice(0, trigger.count);
+  if (
+    streak.length < trigger.count ||
+    streak.some((outcome) => outcome.outcome !== trigger.outcome)
+  ) {
+    return decision(false, 'insufficient_history');
+  }
+  if (withinHorizon[trigger.count]?.outcome === trigger.outcome) {
+    return decision(false, 'streak_already_active');
+  }
+  return decision(true, 'completed_streak');
+}