deepline 0.3.88 → 0.3.90

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

@@ -0,0 +1,433 @@
+import type {
+  ProductNotificationFacts,
+  ProductNotificationTrigger,
+} from './configuration';
+import type {
+  ProductNotificationObservation,
+  ProductNotificationOutcomeFact,
+} from './evaluation';
+
+export const PRODUCT_NOTIFICATION_EVENT_SCHEMA_VERSION = 1 as const;
+export const PRODUCT_NOTIFICATION_MAX_EVENT_BYTES = 16_000;
+export const PRODUCT_NOTIFICATION_MAX_EVENT_FACTS = 20;
+export const PRODUCT_NOTIFICATION_MAX_EVENT_AGE_MS = 30 * 24 * 60 * 60 * 1_000;
+export const PRODUCT_NOTIFICATION_MAX_SOURCE_CLOCK_SKEW_MS = 5 * 60 * 1_000;
+
+export const ProductNotificationEvent = {
+  CreditsBalanceChanged: 'credits.balance.changed',
+  CreditsUsageRecorded: 'credits.usage.recorded',
+  MonitorLifecycleChanged: 'monitor.lifecycle.changed',
+  PlayLifecycleChanged: 'play.lifecycle.changed',
+  PlayRunCompleted: 'play.run.completed',
+  WebhookDeliveryCompleted: 'webhook.delivery.completed',
+  PlayCronSucceeded: 'play.cron.succeeded',
+  PlayCronFailed: 'play.cron.failed',
+  PlayWebhookSucceeded: 'play.webhook.succeeded',
+  PlayWebhookFailed: 'play.webhook.failed',
+} as const;
+
+export type ProductNotificationEvent =
+  (typeof ProductNotificationEvent)[keyof typeof ProductNotificationEvent];
+
+export const ProductNotificationProducerKey = {
+  BillingCredits: 'billing.credits',
+  BillingUsage: 'billing.usage',
+  MonitorsLifecycle: 'monitors.lifecycle',
+  PlaysLifecycle: 'plays.lifecycle',
+  PlaysRuns: 'plays.runs',
+  WebhooksDelivery: 'webhooks.delivery',
+  LegacyProductNotifications: 'legacy.product_notifications',
+} as const;
+
+export type ProductNotificationProducerKey =
+  (typeof ProductNotificationProducerKey)[keyof typeof ProductNotificationProducerKey];
+
+export const ProductNotificationTargetPath = {
+  Billing: '/dashboard/billing',
+} as const;
+
+export const PRODUCT_NOTIFICATION_EVENT_NAMES = [
+  ProductNotificationEvent.CreditsBalanceChanged,
+  ProductNotificationEvent.MonitorLifecycleChanged,
+  ProductNotificationEvent.PlayLifecycleChanged,
+  ProductNotificationEvent.PlayRunCompleted,
+  ProductNotificationEvent.WebhookDeliveryCompleted,
+  ProductNotificationEvent.CreditsUsageRecorded,
+] as const;
+
+export const PRODUCT_NOTIFICATION_COMPATIBILITY_EVENT_NAMES = [
+  ProductNotificationEvent.PlayCronSucceeded,
+  ProductNotificationEvent.PlayCronFailed,
+  ProductNotificationEvent.PlayWebhookSucceeded,
+  ProductNotificationEvent.PlayWebhookFailed,
+] as const;
+
+export type ProductNotificationEventName =
+  | (typeof PRODUCT_NOTIFICATION_EVENT_NAMES)[number]
+  | (typeof PRODUCT_NOTIFICATION_COMPATIBILITY_EVENT_NAMES)[number];
+
+export type ProductNotificationCanonicalEvent = {
+  orgId: string;
+  producerKey: ProductNotificationProducerKey;
+  sourceEventId: string;
+  eventName: ProductNotificationEventName;
+  eventSchemaVersion: typeof PRODUCT_NOTIFICATION_EVENT_SCHEMA_VERSION;
+  occurredAt: number;
+  admittedAt: number;
+  payload: ProductNotificationFacts;
+};
+
+type FactType = 'string' | 'number' | 'boolean';
+export type ProductNotificationEventDefinition = {
+  eventName: ProductNotificationEventName;
+  producerKey: ProductNotificationProducerKey;
+  requiredFacts: Record<string, FactType>;
+  optionalFacts?: Record<string, FactType>;
+  orderingSubjectFact: string;
+  allowedTriggers: ProductNotificationTrigger['kind'][];
+  allowedThresholdUnits?: string[];
+};
+
+export const PRODUCT_NOTIFICATION_EVENT_DEFINITIONS: readonly ProductNotificationEventDefinition[] =
+  [
+    {
+      eventName: ProductNotificationEvent.CreditsBalanceChanged,
+      producerKey: ProductNotificationProducerKey.BillingCredits,
+      requiredFacts: {
+        accountId: 'string',
+        previousCredits: 'number',
+        currentCredits: 'number',
+        targetUrl: 'string',
+      },
+      orderingSubjectFact: 'accountId',
+      allowedTriggers: ['threshold_crossing'],
+      allowedThresholdUnits: ['credits'],
+    },
+    {
+      eventName: ProductNotificationEvent.MonitorLifecycleChanged,
+      producerKey: ProductNotificationProducerKey.MonitorsLifecycle,
+      requiredFacts: {
+        monitorId: 'string',
+        monitorName: 'string',
+        previousState: 'string',
+        currentState: 'string',
+        reasonCode: 'string',
+        targetUrl: 'string',
+      },
+      orderingSubjectFact: 'monitorId',
+      optionalFacts: { previousReasonCode: 'string' },
+      allowedTriggers: ['state_transition'],
+    },
+    {
+      eventName: ProductNotificationEvent.PlayLifecycleChanged,
+      producerKey: ProductNotificationProducerKey.PlaysLifecycle,
+      requiredFacts: {
+        playId: 'string',
+        playName: 'string',
+        previousState: 'string',
+        currentState: 'string',
+        reasonCode: 'string',
+        targetUrl: 'string',
+      },
+      orderingSubjectFact: 'playId',
+      optionalFacts: { previousReasonCode: 'string' },
+      allowedTriggers: ['state_transition'],
+    },
+    {
+      eventName: ProductNotificationEvent.PlayRunCompleted,
+      producerKey: ProductNotificationProducerKey.PlaysRuns,
+      requiredFacts: {
+        playId: 'string',
+        playName: 'string',
+        runId: 'string',
+        outcome: 'string',
+        targetUrl: 'string',
+      },
+      optionalFacts: {
+        triggerKind: 'string',
+      },
+      orderingSubjectFact: 'playId',
+      allowedTriggers: ['each_match', 'consecutive_outcomes'],
+    },
+    {
+      eventName: ProductNotificationEvent.WebhookDeliveryCompleted,
+      producerKey: ProductNotificationProducerKey.WebhooksDelivery,
+      requiredFacts: {
+        endpointId: 'string',
+        endpointName: 'string',
+        deliveryId: 'string',
+        outcome: 'string',
+        targetUrl: 'string',
+      },
+      orderingSubjectFact: 'endpointId',
+      allowedTriggers: ['each_match', 'consecutive_outcomes'],
+    },
+    {
+      eventName: ProductNotificationEvent.CreditsUsageRecorded,
+      producerKey: ProductNotificationProducerKey.BillingUsage,
+      requiredFacts: {
+        accountId: 'string',
+        creditsUsed: 'number',
+        limitDenied: 'boolean',
+        targetUrl: 'string',
+      },
+      orderingSubjectFact: 'accountId',
+      allowedTriggers: ['threshold_crossing'],
+      allowedThresholdUnits: ['percent', 'usage'],
+    },
+    ...PRODUCT_NOTIFICATION_COMPATIBILITY_EVENT_NAMES.map((eventName) => ({
+      eventName,
+      producerKey: ProductNotificationProducerKey.LegacyProductNotifications,
+      requiredFacts: {
+        playId: 'string' as const,
+        playName: 'string' as const,
+        targetUrl: 'string' as const,
+      },
+      optionalFacts: {
+        runId: 'string' as const,
+        reasonCode: 'string' as const,
+        reason: 'string' as const,
+      },
+      orderingSubjectFact: 'playId',
+      allowedTriggers: ['each_match' as const],
+    })),
+  ];
+
+export function getProductNotificationEventDefinition(
+  eventName: string,
+): ProductNotificationEventDefinition {
+  const definition = PRODUCT_NOTIFICATION_EVENT_DEFINITIONS.find(
+    (candidate) => candidate.eventName === eventName,
+  );
+  if (!definition) throw new Error(`Unknown notification event ${eventName}.`);
+  return definition;
+}
+
+function requiredString(value: unknown, field: string) {
+  if (typeof value !== 'string' || !value.trim()) {
+    throw new Error(`${field} must be a non-empty string.`);
+  }
+  if (value.length > 512) throw new Error(`${field} is too long.`);
+}
+
+function requireInternalTargetPath(value: unknown) {
+  requiredString(value, 'targetUrl');
+  if (
+    typeof value !== 'string' ||
+    !value.startsWith('/') ||
+    value.startsWith('//') ||
+    value.includes('\\') ||
+    /[\u0000-\u001f\u007f]/.test(value)
+  ) {
+    throw new Error('targetUrl must be a safe internal path.');
+  }
+}
+
+/** Validate the semantic event contract after the producer transaction commits. */
+export function validateProductNotificationEvent(
+  event: ProductNotificationCanonicalEvent,
+  now: number,
+) {
+  const definition = getProductNotificationEventDefinition(event.eventName);
+  requiredString(event.orgId, 'orgId');
+  requiredString(event.producerKey, 'producerKey');
+  requiredString(event.sourceEventId, 'sourceEventId');
+  if (event.producerKey !== definition.producerKey) {
+    throw new Error(`${event.producerKey} cannot produce ${event.eventName}.`);
+  }
+  if (event.eventSchemaVersion !== PRODUCT_NOTIFICATION_EVENT_SCHEMA_VERSION) {
+    throw new Error(
+      `Unsupported ${event.eventName} schema version ${event.eventSchemaVersion}.`,
+    );
+  }
+  if (
+    !Number.isFinite(event.occurredAt) ||
+    !Number.isFinite(event.admittedAt) ||
+    !Number.isFinite(now)
+  ) {
+    throw new Error('Event timestamps must be finite.');
+  }
+  if (event.occurredAt < now - PRODUCT_NOTIFICATION_MAX_EVENT_AGE_MS) {
+    throw new Error('Notification event is older than 30 days.');
+  }
+  if (event.admittedAt > now) {
+    throw new Error('Notification admission time is in the future.');
+  }
+  if (
+    event.occurredAt >
+    event.admittedAt + PRODUCT_NOTIFICATION_MAX_SOURCE_CLOCK_SKEW_MS
+  ) {
+    throw new Error(
+      'Notification event exceeds the allowed source clock skew.',
+    );
+  }
+  const allowedFacts = {
+    ...definition.requiredFacts,
+    ...definition.optionalFacts,
+  };
+  const entries = Object.entries(event.payload);
+  if (entries.length > PRODUCT_NOTIFICATION_MAX_EVENT_FACTS) {
+    throw new Error('Notification event contains too many facts.');
+  }
+  for (const [fact, expectedType] of Object.entries(definition.requiredFacts)) {
+    const value = event.payload[fact];
+    if (typeof value !== expectedType) {
+      throw new Error(`${event.eventName}.${fact} must be ${expectedType}.`);
+    }
+    if (expectedType === 'string') requiredString(value, fact);
+    if (expectedType === 'number' && !Number.isFinite(value)) {
+      throw new Error(`${event.eventName}.${fact} must be finite.`);
+    }
+  }
+  for (const [fact, value] of entries) {
+    const expectedType = allowedFacts[fact];
+    if (!expectedType) {
+      throw new Error(`${event.eventName} does not accept fact ${fact}.`);
+    }
+    if (typeof value !== expectedType) {
+      throw new Error(`${event.eventName}.${fact} must be ${expectedType}.`);
+    }
+    if (expectedType === 'string') requiredString(value, fact);
+    if (expectedType === 'number' && !Number.isFinite(value)) {
+      throw new Error(`${event.eventName}.${fact} must be finite.`);
+    }
+  }
+  requireInternalTargetPath(event.payload.targetUrl);
+  if (
+    new TextEncoder().encode(JSON.stringify(event)).byteLength >
+    PRODUCT_NOTIFICATION_MAX_EVENT_BYTES
+  ) {
+    throw new Error('Notification event exceeds its byte bound.');
+  }
+  return definition;
+}
+
+export function productNotificationOrderingKey(
+  event: ProductNotificationCanonicalEvent,
+) {
+  const definition = getProductNotificationEventDefinition(event.eventName);
+  return `${event.eventName}/${String(
+    event.payload[definition.orderingSubjectFact],
+  )}`;
+}
+
+export function compareProductNotificationOrder(
+  left: { occurredAt: number; sourceEventId: string },
+  right: { occurredAt: number; sourceEventId: string },
+) {
+  return (
+    left.occurredAt - right.occurredAt ||
+    left.sourceEventId.localeCompare(right.sourceEventId)
+  );
+}
+
+export function productNotificationCanonicalOrder(
+  event: Pick<
+    ProductNotificationCanonicalEvent,
+    'occurredAt' | 'sourceEventId'
+  >,
+) {
+  return [event.occurredAt, event.sourceEventId] as const;
+}
+
+export function productNotificationTriggerIsAllowed(
+  eventName: ProductNotificationEventName,
+  trigger: ProductNotificationTrigger,
+) {
+  const definition = getProductNotificationEventDefinition(eventName);
+  if (!definition.allowedTriggers.includes(trigger.kind)) return false;
+  return (
+    trigger.kind !== 'threshold_crossing' ||
+    trigger.unit === undefined ||
+    definition.allowedThresholdUnits?.includes(trigger.unit) === true
+  );
+}
+
+/** Convert a registered event into the generic observation a trigger consumes. */
+export function adaptProductNotificationObservation(input: {
+  event: ProductNotificationCanonicalEvent;
+  trigger: ProductNotificationTrigger;
+  outcomeHistory?: ProductNotificationOutcomeFact[];
+}): ProductNotificationObservation {
+  const { event, trigger } = input;
+  if (!productNotificationTriggerIsAllowed(event.eventName, trigger)) {
+    throw new Error(`${trigger.kind} is not allowed for ${event.eventName}.`);
+  }
+  if (trigger.kind === 'each_match') return { kind: 'match' };
+  if (trigger.kind === 'state_transition') {
+    return {
+      kind: 'state_transition',
+      previousState: String(event.payload.previousState),
+      currentState: String(event.payload.currentState),
+      previousReasonCode:
+        typeof event.payload.previousReasonCode === 'string'
+          ? event.payload.previousReasonCode
+          : undefined,
+      currentReasonCode: String(event.payload.reasonCode),
+      reasonCode: String(event.payload.reasonCode),
+    };
+  }
+  if (trigger.kind === 'consecutive_outcomes') {
+    if (!input.outcomeHistory) {
+      throw new Error(`${event.eventName} requires bounded outcome history.`);
+    }
+    const current = input.outcomeHistory[0];
+    const orderingKey = productNotificationOrderingKey(event);
+    if (
+      !current ||
+      input.outcomeHistory.some(
+        (outcome) => outcome.orderingKey !== orderingKey,
+      ) ||
+      current.sourceEventId !== event.sourceEventId ||
+      current.occurredAt !== event.occurredAt ||
+      current.outcome !== event.payload.outcome
+    ) {
+      throw new Error(
+        `${event.eventName} outcome history must begin with the current event.`,
+      );
+    }
+    return { kind: 'outcome_history', outcomes: input.outcomeHistory };
+  }
+  if (event.eventName === ProductNotificationEvent.CreditsBalanceChanged) {
+    return {
+      kind: 'threshold_crossing',
+      previousValue: Number(event.payload.previousCredits),
+      currentValue: Number(event.payload.currentCredits),
+      unit: 'credits',
+    };
+  }
+  const limit = Number(event.payload.limit);
+  if (event.eventName === ProductNotificationEvent.CreditsUsageRecorded) {
+    if (!(limit > 0)) throw new Error('Monthly usage limit must be positive.');
+    return {
+      kind: 'threshold_state',
+      currentValue: (Number(event.payload.currentUsage) / limit) * 100,
+      unit: 'percent',
+    };
+  }
+  throw new Error(`${event.eventName} has no threshold observation adapter.`);
+}
+
+/** Fingerprint identity excludes admission time so forwarding retries are equal. */
+export async function productNotificationEventFingerprint(
+  event: ProductNotificationCanonicalEvent,
+) {
+  const canonical = JSON.stringify({
+    orgId: event.orgId,
+    producerKey: event.producerKey,
+    sourceEventId: event.sourceEventId,
+    eventName: event.eventName,
+    eventSchemaVersion: event.eventSchemaVersion,
+    occurredAt: event.occurredAt,
+    payload: Object.fromEntries(
+      Object.entries(event.payload).sort(([left], [right]) =>
+        left.localeCompare(right),
+      ),
+    ),
+  });
+  const bytes = new TextEncoder().encode(canonical);
+  const digest = await crypto.subtle.digest('SHA-256', bytes);
+  return [...new Uint8Array(digest)]
+    .map((value) => value.toString(16).padStart(2, '0'))
+    .join('');
+}

package/dist/bundling-sources/shared_libs/product-notifications/legacy-slack.ts

@@ -0,0 +1,80 @@
+import type {
+  ProductNotificationDefaultGroup,
+  ProductNotificationDefaultRule,
+} from './configuration';
+import {
+  PRODUCT_NOTIFICATION_EVENT_CATALOG,
+  type ProductNotificationEventType,
+} from './contract';
+
+const TYPE_BY_LEGACY_EVENT = {
+  'play.cron.succeeded': 'compat.play.cron.succeeded',
+  'play.cron.failed': 'compat.play.cron.failed',
+  'play.webhook.succeeded': 'compat.play.webhook.succeeded',
+  'play.webhook.failed': 'compat.play.webhook.failed',
+} as const;
+
+export function legacySlackNotificationType(
+  eventType: ProductNotificationEventType,
+) {
+  return TYPE_BY_LEGACY_EVENT[eventType];
+}
+
+export function legacySlackNotificationTypeMetadata(notificationType: string) {
+  const event = PRODUCT_NOTIFICATION_EVENT_CATALOG.find(
+    ({ id }) => TYPE_BY_LEGACY_EVENT[id] === notificationType,
+  );
+  return event
+    ? { name: event.label, description: event.description }
+    : undefined;
+}
+
+function legacyPrefix(destinationId: string) {
+  if (!destinationId)
+    throw new Error('Legacy Slack destination ID is required.');
+  return `legacy.slack.${destinationId}`;
+}
+
+export function isLegacySlackCompatibilityKey(value: string) {
+  return value.startsWith('legacy.slack.');
+}
+
+export function legacySlackGroupKey(destinationId: string) {
+  return `${legacyPrefix(destinationId)}.group`;
+}
+
+export function legacySlackTargetConfiguration(input: {
+  destinationId: string;
+  destinationName: string;
+  subscriptions: readonly {
+    eventType: ProductNotificationEventType;
+    enabled: boolean;
+  }[];
+}): {
+  group: ProductNotificationDefaultGroup;
+  rules: ProductNotificationDefaultRule[];
+} {
+  const prefix = legacyPrefix(input.destinationId);
+  return {
+    group: {
+      groupKey: legacySlackGroupKey(input.destinationId),
+      name: input.destinationName,
+      enabled: true,
+      deliveryTiming: { mode: 'immediate' },
+    },
+    rules: input.subscriptions.map((subscription) => ({
+      ruleKey: `${prefix}.${subscription.eventType}`,
+      groupKey: legacySlackGroupKey(input.destinationId),
+      enabled: subscription.enabled,
+      notificationType: legacySlackNotificationType(subscription.eventType),
+      eventName: subscription.eventType,
+      eventFilter: {},
+      trigger: { kind: 'each_match' },
+      repeatMode: 'every_match',
+    })),
+  };
+}
+
+export function legacySlackDestinationKey(destinationId: string) {
+  return `${legacyPrefix(destinationId)}.destination`;
+}

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

@@ -0,0 +1,18 @@
+export const NOTIFICATION_GROUP_WINDOW_MS = 60 * 60_000;
+export const NOTIFICATION_GROUP_HOURLY_LIMIT = 10;
+const DIGEST_ITEM_LIMIT = 100;
+// Bound the whole preview so 100 entries fit within a Convex document.
+const DIGEST_PREVIEW_CHARACTERS = 1_000;
+
+type OverflowItem = { ruleKey: string; summary: string };
+
+export function appendGroupOverflowItem(
+  previous: readonly OverflowItem[],
+  item: OverflowItem,
+): OverflowItem[] {
+  const summary =
+    item.summary.length <= DIGEST_PREVIEW_CHARACTERS
+      ? item.summary
+      : `${item.summary.slice(0, DIGEST_PREVIEW_CHARACTERS - 1)}…`;
+  return [...previous, { ...item, summary }].slice(-DIGEST_ITEM_LIMIT);
+}

package/dist/bundling-sources/shared_libs/product-notifications/rolling-limit.ts

@@ -0,0 +1,24 @@
+export const NOTIFICATION_RULE_IMMEDIATE_LIMIT = 10;
+
+/** Admit below the rolling limit; otherwise anchor the digest to its oldest admission. */
+export function admitRollingNotification(
+  admittedAt: readonly number[],
+  now: number,
+  windowMs: number,
+  limit: number,
+): { admittedAt: number[]; digestAt: number | null } {
+  const history = [...admittedAt].sort((left, right) => left - right);
+  const inWindow = history.filter((time) => time > now - windowMs);
+  if (inWindow.length >= limit) {
+    return {
+      admittedAt: history,
+      digestAt: inWindow[inWindow.length - limit]! + windowMs,
+    };
+  }
+  return {
+    admittedAt: [...history, now]
+      .sort((left, right) => left - right)
+      .slice(-limit),
+    digestAt: null,
+  };
+}