deepline 0.3.88 → 0.3.90

package/dist/bundling-sources/shared_libs/monitors/billing/pricing.ts

@@ -0,0 +1,54 @@
+import { getUsdPerCustomerCredit } from '@deepline/billing/credit-pricing';
+
+export const MONITOR_BILLING_VERIFIED_AT = '2026-06-25';
+// Monitor / defineMonitor upstream markup, deliberately HIGHER than the general
+// tool path (1.4×, DEEPLINE_CREDIT_USD_MARKUP_MULTIPLIER): monitors are a premium,
+// always-on data pipe. Applied to the provider's per-event USD cost. Raised from
+// 3.0× to 5.0× to reprice monitor responses (findings / webhook events) now that
+// upstream-free monitors waive the base create fee and bill purely on responses.
+export const MONITOR_UPSTREAM_COST_MARKUP_MULTIPLIER = 5.0;
+// Flat creation/lifecycle fee in Deepline retail dollars. Providers do not
+// charge to create a monitor, so this is a pure platform fee; render it through
+// current credits rather than baking in a denomination.
+export const MONITOR_BASE_LIFECYCLE_USD = 0.5;
+export const MONITOR_PLAN_ENTITLEMENT_ALLOCATION_DIVISOR = 100;
+
+const MONITOR_CREDIT_PRECISION_FACTOR = 100;
+
+function roundUpMonitorCredits(value: number): number {
+  if (!Number.isFinite(value) || value <= 0) return 0;
+  return (
+    Math.ceil(Number((value * MONITOR_CREDIT_PRECISION_FACTOR).toFixed(9))) /
+    MONITOR_CREDIT_PRECISION_FACTOR
+  );
+}
+
+export function deeplineRetailUsdToCredits(amountUsd: number): number {
+  if (!Number.isFinite(amountUsd) || amountUsd <= 0) return 0;
+  return roundUpMonitorCredits(amountUsd / getUsdPerCustomerCredit());
+}
+
+export function planEntitlementCreateCredits(
+  minimumMonthlyPlanUsd: number,
+): number {
+  return deeplineRetailUsdToCredits(
+    minimumMonthlyPlanUsd / MONITOR_PLAN_ENTITLEMENT_ALLOCATION_DIVISOR,
+  );
+}
+
+export function monitorProviderUsdToRetailCredits(
+  providerCostUsd: number,
+  markupMultiplier = MONITOR_UPSTREAM_COST_MARKUP_MULTIPLIER,
+): number {
+  if (!Number.isFinite(providerCostUsd) || providerCostUsd <= 0) return 0;
+  if (!Number.isFinite(markupMultiplier) || markupMultiplier <= 0) {
+    throw new Error(`Invalid monitor markup multiplier: ${markupMultiplier}`);
+  }
+  const rawCredits =
+    (providerCostUsd * markupMultiplier) / getUsdPerCustomerCredit();
+  return roundUpMonitorCredits(rawCredits);
+}
+
+export const MONITOR_BASE_LIFECYCLE_CREDITS = deeplineRetailUsdToCredits(
+  MONITOR_BASE_LIFECYCLE_USD,
+);

package/dist/bundling-sources/shared_libs/monitors/billing/public-pricing.ts

@@ -0,0 +1,72 @@
+import type {
+  MonitorBillingPolicy,
+  MonitorPayloadPricingEntry,
+  MonitorPayloadPricingMode,
+} from '@deepline/monitors/billing/types';
+
+export type PublicMonitorPricing = {
+  mode: MonitorPayloadPricingMode;
+  billing_basis: 'per_accepted_event' | 'recurring';
+  deepline_credits: number;
+  unit: string;
+  charge_timing: string;
+  period_days?: number;
+  display: string;
+};
+
+export type PublicResolvedMonitorPricing = PublicMonitorPricing & {
+  discriminator: string;
+  selection: string;
+};
+
+function formatCredits(credits: number) {
+  return `${credits.toLocaleString('en')} Deepline ${
+    credits === 1 ? 'credit' : 'credits'
+  }`;
+}
+
+/** Customer-safe pricing semantics for one payload-priced monitor option. */
+export function publicMonitorPricingEntry(
+  entry: MonitorPayloadPricingEntry,
+): PublicMonitorPricing {
+  const credits = formatCredits(entry.retailCredits);
+  if (entry.mode === 'monitor_subscription') {
+    const periodDays = entry.periodDays ?? 30;
+    return {
+      mode: entry.mode,
+      billing_basis: 'recurring',
+      deepline_credits: entry.retailCredits,
+      unit: entry.unitLabel,
+      charge_timing: `on deploy or reactivation and every ${periodDays} days while active`,
+      period_days: periodDays,
+      display: `${credits} on deploy or reactivation and every ${periodDays} days while active; no additional per-event charge.`,
+    };
+  }
+  return {
+    mode: entry.mode,
+    billing_basis: 'per_accepted_event',
+    deepline_credits: entry.retailCredits,
+    unit: entry.unitLabel,
+    charge_timing: 'for each accepted provider event',
+    display: `${credits} per accepted ${entry.unitLabel} event.`,
+  };
+}
+
+/** Resolve the selected payload price without exposing provider cost inputs. */
+export function resolvePublicMonitorPricing(input: {
+  policy: MonitorBillingPolicy | null | undefined;
+  payload: Record<string, unknown> | null | undefined;
+}): PublicResolvedMonitorPricing | undefined {
+  const pricing = input.policy?.payloadPricing;
+  if (!pricing || !input.payload) return undefined;
+  const rawSelection = input.payload[pricing.discriminator];
+  if (typeof rawSelection !== 'string') return undefined;
+  const selection = rawSelection.trim();
+  const entry = pricing.entries[selection];
+  if (!selection || !entry) return undefined;
+  return {
+    discriminator: pricing.discriminator,
+    selection,
+    ...publicMonitorPricingEntry(entry),
+  };
+}

package/dist/bundling-sources/shared_libs/monitors/billing/session.ts

@@ -0,0 +1,45 @@
+import type {
+  MonitorBillingPhase,
+  MonitorBillingSession,
+} from '@deepline/monitors/billing/types';
+
+function requireNonEmpty(value: string, label: string) {
+  const trimmed = value.trim();
+  if (!trimmed) {
+    throw new Error(`Monitor billing session ${label} is required.`);
+  }
+  return trimmed;
+}
+
+function segment(value: string) {
+  return encodeURIComponent(value);
+}
+
+export function monitorBillingSessionKey(input: {
+  orgId: string;
+  monitorKey: string;
+  billingReason: MonitorBillingPhase;
+  providerEventIdOrPeriod?: string | null;
+}): MonitorBillingSession {
+  const orgId = requireNonEmpty(input.orgId, 'orgId');
+  const monitorKey = requireNonEmpty(input.monitorKey, 'monitorKey');
+  const billingReason = requireNonEmpty(
+    input.billingReason,
+    'billingReason',
+  ) as MonitorBillingPhase;
+  const providerEventIdOrPeriod =
+    input.providerEventIdOrPeriod?.trim() || 'lifecycle';
+  return {
+    key: [
+      'monitor',
+      segment(orgId),
+      segment(monitorKey),
+      segment(billingReason),
+      segment(providerEventIdOrPeriod),
+    ].join(':'),
+    orgId,
+    monitorKey,
+    billingReason,
+    providerEventIdOrPeriod,
+  };
+}

package/dist/bundling-sources/shared_libs/monitors/billing/state.ts

@@ -0,0 +1,454 @@
+import type {
+  MonitorBillingPhase,
+  MonitorBillingState,
+  MonitorBillingPolicy,
+} from '@deepline/monitors/billing/types';
+import type { PublicMonitorCustomerChargeSummary } from '@deepline/monitors/billing/charges';
+
+export type StoredMonitorBillingState = {
+  state: MonitorBillingState;
+  lifecycle_charge_credits: number;
+  // How much of the CURRENT lifecycle charge has already been refunded (via
+  // radar_failure). Caps cumulative refunds at what the customer actually paid,
+  // so multiple distinct failure events can total at most 1x the charge. A fresh
+  // create/renewal charge resets this to 0 by omission — `monitorBillingState-
+  // ForSuccessfulCharge` rebuilds the state without it.
+  lifecycle_refunded_credits?: number;
+  usage_charge_pending: boolean;
+  reactivation_required: boolean;
+  suspension_reason?: string;
+  last_billing_error?: string;
+  last_charge_session_key?: string;
+  last_charged_at?: string;
+  next_renewal_at?: string | null;
+  provider_next_charge_at?: string | null;
+  cancel_before_at?: string | null;
+  catalog_snapshot?: Record<string, unknown>;
+  commercial_snapshot?: Record<string, unknown>;
+};
+
+const SUBSCRIPTION_RENEWAL_GUARD_MS = 24 * 60 * 60 * 1000;
+
+export type PublicMonitorBillingSummary = Pick<
+  StoredMonitorBillingState,
+  | 'state'
+  | 'lifecycle_charge_credits'
+  | 'usage_charge_pending'
+  | 'reactivation_required'
+  | 'suspension_reason'
+  | 'next_renewal_at'
+> & {
+  create_charge?: PublicMonitorCustomerChargeSummary;
+  reactivate_charge?: PublicMonitorCustomerChargeSummary;
+};
+
+function readRecord(value: unknown): Record<string, unknown> {
+  if (value && typeof value === 'object' && !Array.isArray(value)) {
+    return value as Record<string, unknown>;
+  }
+  if (typeof value === 'string' && value.trim()) {
+    try {
+      const parsed = JSON.parse(value) as unknown;
+      return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+        ? (parsed as Record<string, unknown>)
+        : {};
+    } catch {
+      return {};
+    }
+  }
+  return {};
+}
+
+function readString(value: unknown) {
+  return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+
+function readNumber(value: unknown) {
+  return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+
+function readBoolean(value: unknown) {
+  return typeof value === 'boolean' ? value : null;
+}
+
+function readBillingState(value: unknown): MonitorBillingState {
+  const state = readString(value);
+  switch (state) {
+    case 'active':
+    case 'preflight_denied':
+    case 'billing_pending':
+    case 'billing_suspended':
+    case 'upstream_disable_pending':
+    case 'upstream_disable_failed':
+    case 'disabled':
+      return state;
+    default:
+      return 'billing_pending';
+  }
+}
+
+export function parseStoredMonitorBillingState(
+  value: unknown,
+): StoredMonitorBillingState {
+  const record = readRecord(value);
+  return {
+    state: readBillingState(record.state),
+    lifecycle_charge_credits: Math.max(
+      0,
+      readNumber(record.lifecycle_charge_credits) ?? 0,
+    ),
+    ...(readNumber(record.lifecycle_refunded_credits)
+      ? {
+          lifecycle_refunded_credits: Math.max(
+            0,
+            readNumber(record.lifecycle_refunded_credits)!,
+          ),
+        }
+      : {}),
+    usage_charge_pending:
+      readBoolean(record.usage_charge_pending) ??
+      readBillingState(record.state) === 'billing_pending',
+    reactivation_required:
+      readBoolean(record.reactivation_required) ??
+      readBillingState(record.state) !== 'active',
+    ...(readString(record.suspension_reason)
+      ? { suspension_reason: readString(record.suspension_reason)! }
+      : {}),
+    ...(readString(record.last_billing_error)
+      ? { last_billing_error: readString(record.last_billing_error)! }
+      : {}),
+    ...(readString(record.last_charge_session_key)
+      ? { last_charge_session_key: readString(record.last_charge_session_key)! }
+      : {}),
+    ...(readString(record.last_charged_at)
+      ? { last_charged_at: readString(record.last_charged_at)! }
+      : {}),
+    ...(record.next_renewal_at === null
+      ? { next_renewal_at: null }
+      : readString(record.next_renewal_at)
+        ? { next_renewal_at: readString(record.next_renewal_at)! }
+        : {}),
+    ...(record.provider_next_charge_at === null
+      ? { provider_next_charge_at: null }
+      : readString(record.provider_next_charge_at)
+        ? {
+            provider_next_charge_at: readString(
+              record.provider_next_charge_at,
+            )!,
+          }
+        : {}),
+    ...(record.cancel_before_at === null
+      ? { cancel_before_at: null }
+      : readString(record.cancel_before_at)
+        ? { cancel_before_at: readString(record.cancel_before_at)! }
+        : {}),
+    ...(record.catalog_snapshot &&
+    typeof record.catalog_snapshot === 'object' &&
+    !Array.isArray(record.catalog_snapshot)
+      ? { catalog_snapshot: record.catalog_snapshot as Record<string, unknown> }
+      : {}),
+    ...(record.commercial_snapshot &&
+    typeof record.commercial_snapshot === 'object' &&
+    !Array.isArray(record.commercial_snapshot)
+      ? {
+          commercial_snapshot: record.commercial_snapshot as Record<
+            string,
+            unknown
+          >,
+        }
+      : {}),
+  };
+}
+
+export function publicMonitorBillingSummary(
+  state: StoredMonitorBillingState,
+  charges?: {
+    create_charge?: PublicMonitorCustomerChargeSummary;
+    reactivate_charge?: PublicMonitorCustomerChargeSummary;
+  },
+): PublicMonitorBillingSummary {
+  return {
+    state: state.state,
+    lifecycle_charge_credits: state.lifecycle_charge_credits,
+    usage_charge_pending: state.usage_charge_pending,
+    reactivation_required: state.reactivation_required,
+    ...(charges?.create_charge ? { create_charge: charges.create_charge } : {}),
+    ...(charges?.reactivate_charge
+      ? { reactivate_charge: charges.reactivate_charge }
+      : {}),
+    ...(state.suspension_reason
+      ? { suspension_reason: state.suspension_reason }
+      : {}),
+    ...(state.next_renewal_at !== undefined
+      ? { next_renewal_at: state.next_renewal_at }
+      : {}),
+  };
+}
+
+function providerRenewalFields(
+  providerNextChargeAt: string | null | undefined,
+): Pick<
+  StoredMonitorBillingState,
+  'provider_next_charge_at' | 'cancel_before_at'
+> {
+  if (providerNextChargeAt === undefined) return {};
+  if (providerNextChargeAt === null) {
+    return {
+      provider_next_charge_at: null,
+      cancel_before_at: null,
+    };
+  }
+  const parsed = Date.parse(providerNextChargeAt);
+  if (!Number.isFinite(parsed)) {
+    throw new Error(
+      `Provider next charge timestamp is invalid: ${providerNextChargeAt}.`,
+    );
+  }
+  return {
+    provider_next_charge_at: new Date(parsed).toISOString(),
+    cancel_before_at: new Date(
+      parsed - SUBSCRIPTION_RENEWAL_GUARD_MS,
+    ).toISOString(),
+  };
+}
+
+export function monitorBillingStateWithProviderRenewal(input: {
+  previous: StoredMonitorBillingState;
+  providerNextChargeAt: string | null;
+}): StoredMonitorBillingState {
+  return {
+    ...input.previous,
+    ...providerRenewalFields(input.providerNextChargeAt),
+  };
+}
+
+export function defaultMonitorBillingState(): StoredMonitorBillingState {
+  return {
+    state: 'billing_pending',
+    lifecycle_charge_credits: 0,
+    usage_charge_pending: false,
+    reactivation_required: false,
+  };
+}
+
+export function monitorBillingStateForSuccessfulCharge(input: {
+  policy: MonitorBillingPolicy;
+  phase: MonitorBillingPhase;
+  chargedCredits: number;
+  pendingProviderCostKeys: readonly string[];
+  sessionKey?: string;
+  chargedAt?: Date;
+  catalogSnapshot?: Record<string, unknown>;
+  commercialSnapshot?: Record<string, unknown>;
+  providerNextChargeAt?: string | null;
+}): StoredMonitorBillingState {
+  return {
+    state:
+      input.pendingProviderCostKeys.length > 0 ? 'billing_pending' : 'active',
+    lifecycle_charge_credits: input.chargedCredits,
+    usage_charge_pending: input.pendingProviderCostKeys.length > 0,
+    reactivation_required: false,
+    ...(input.sessionKey ? { last_charge_session_key: input.sessionKey } : {}),
+    last_charged_at: (input.chargedAt ?? new Date()).toISOString(),
+    next_renewal_at: nextRenewalAtForPolicy(input.policy, input.chargedAt),
+    ...providerRenewalFields(input.providerNextChargeAt),
+    ...(input.catalogSnapshot
+      ? { catalog_snapshot: input.catalogSnapshot }
+      : {}),
+    ...(input.commercialSnapshot
+      ? { commercial_snapshot: input.commercialSnapshot }
+      : {}),
+  };
+}
+
+export function monitorBillingStateForWrapperEntitlement(input: {
+  commercialSnapshot: Record<string, unknown>;
+}): StoredMonitorBillingState {
+  return {
+    state: 'active',
+    lifecycle_charge_credits: 0,
+    usage_charge_pending: false,
+    reactivation_required: false,
+    commercial_snapshot: input.commercialSnapshot,
+  };
+}
+
+export function monitorBillingStateForDisabled(input: {
+  previous?: StoredMonitorBillingState | null;
+  reason: string;
+}): StoredMonitorBillingState {
+  return {
+    ...(input.previous ?? defaultMonitorBillingState()),
+    state: 'disabled',
+    usage_charge_pending: false,
+    reactivation_required: true,
+    suspension_reason: input.reason,
+    // THE PAID-THROUGH ANCHOR SURVIVES A DISABLE.
+    //
+    // These three used to be nulled here, and that is what made a suspended
+    // monitor cost twice. The customer bought a month of this slot; turning the
+    // monitor off - by policy or by their own hand - does not give that month
+    // back, and TamRadar has no activate endpoint, so coming back is a CREATE
+    // that would open a second charge for coverage already paid for.
+    //
+    // Erasing the anchor here also meant a correct check on the way back up
+    // would have had nothing to read. The record of what was paid for, and
+    // until when, is the thing that has to outlive the disable.
+    //
+    // Renewals do NOT keep running off it: `listRenewalCandidates` ranges
+    // `by_org_status_next_renewal` on `status: 'active'`, and a disabled
+    // monitor is not active. The anchor is a receipt, not a schedule.
+  };
+}
+
+/**
+ * Whether a subscription charge is admitted, or already paid for.
+ *
+ * THE SLOT-MONTH INVARIANT: an organization pays once per (monitor key,
+ * coverage period). Inside a period it has already bought, re-creating that
+ * monitor is free - however it came to be gone. Policy suspended it and a
+ * top-up revived it; an operator ran the revive verb; the customer deleted it
+ * on Tuesday and wanted it back on Wednesday. All the same slot, all the same
+ * month, one charge.
+ *
+ * Deliberately blind to WHY the monitor went away. Charging a customer twice
+ * for one slot-month is the same wrong answer whether Deepline or the customer
+ * caused the gap, and a rule that had to know the cause would need the cause to
+ * be recorded correctly on every path that can delete a monitor.
+ *
+ * THE ONE GUARD: the incoming charge may not exceed what was actually paid.
+ * Without it, deleting a cheap monitor and re-creating an expensive one under
+ * the same key inside the period would take the expensive tier for the cheap
+ * price. An upgrade therefore pays in full and opens a fresh period - the
+ * conservative answer, because the alternative is pro-rating, which is a
+ * pricing rule this system does not have and should not grow by accident.
+ */
+export function monitorPaidThroughAdmission(input: {
+  previous?: StoredMonitorBillingState | null;
+  /** What this lifecycle phase would charge if nothing were already paid. */
+  quotedCredits: number;
+  now?: Date;
+}): {
+  /** True when the customer must pay: no open period covers this charge. */
+  chargeAdmitted: boolean;
+  /** The period the surviving anchor covers, when one does. */
+  paidThrough: string | null;
+  /** The provider's own period end, when the provider bills recurringly. */
+  providerPaidThrough: string | null;
+  reason:
+    | 'no_previous_period'
+    | 'period_elapsed'
+    | 'charge_exceeds_paid'
+    | 'inside_paid_period';
+} {
+  const previous = input.previous;
+  const now = input.now ?? new Date();
+  // TamRadar subscriptions have a provider-owned period. `next_renewal_at`
+  // deliberately remains null for those mixed policies so the generic renewal
+  // scheduler cannot also claim the provider's subscription renewal. Its
+  // `provider_next_charge_at` is nevertheless a durable paid-through receipt
+  // for admission after a disable/recreate.
+  const paidThrough = previous?.next_renewal_at ?? null;
+  const providerPaidThrough = previous?.provider_next_charge_at ?? null;
+  const base = { paidThrough, providerPaidThrough };
+  const effectivePaidThrough = paidThrough ?? providerPaidThrough;
+
+  if (input.quotedCredits <= 0) {
+    // Nothing to admit. Free phases are free for their own reasons.
+    return { ...base, chargeAdmitted: false, reason: 'inside_paid_period' };
+  }
+  if (!effectivePaidThrough) {
+    return { ...base, chargeAdmitted: true, reason: 'no_previous_period' };
+  }
+  const paidThroughMs = Date.parse(effectivePaidThrough);
+  if (!Number.isFinite(paidThroughMs) || now.getTime() >= paidThroughMs) {
+    // An unparseable anchor charges rather than granting free coverage off a
+    // value nobody can read.
+    return { ...base, chargeAdmitted: true, reason: 'period_elapsed' };
+  }
+  const alreadyPaid = previous?.lifecycle_charge_credits ?? 0;
+  if (input.quotedCredits > alreadyPaid) {
+    return { ...base, chargeAdmitted: true, reason: 'charge_exceeds_paid' };
+  }
+  return { ...base, chargeAdmitted: false, reason: 'inside_paid_period' };
+}
+
+export function monitorBillingStateForSuspension(input: {
+  previous?: StoredMonitorBillingState | null;
+  reason: string;
+  error?: string;
+  disablePending?: boolean;
+}): StoredMonitorBillingState {
+  return {
+    ...(input.previous ?? defaultMonitorBillingState()),
+    state: input.disablePending
+      ? 'upstream_disable_pending'
+      : 'billing_suspended',
+    usage_charge_pending: false,
+    reactivation_required: true,
+    suspension_reason: input.reason,
+    ...(input.error ? { last_billing_error: input.error } : {}),
+    next_renewal_at: null,
+    provider_next_charge_at: null,
+    cancel_before_at: null,
+  };
+}
+
+export function monitorBillingStateForUpstreamDisableFailed(input: {
+  previous?: StoredMonitorBillingState | null;
+  error: string;
+}): StoredMonitorBillingState {
+  return {
+    ...(input.previous ?? defaultMonitorBillingState()),
+    state: 'upstream_disable_failed',
+    usage_charge_pending: false,
+    reactivation_required: true,
+    suspension_reason: 'billing_failure_upstream_disable_failed',
+    last_billing_error: input.error,
+    next_renewal_at: null,
+    provider_next_charge_at: null,
+    cancel_before_at: null,
+  };
+}
+
+/**
+ * Whether this policy bills in periods at all.
+ *
+ * Only a policy that opens a renewal period can leave a paid-through anchor
+ * behind, so only one of those can make the slot-month rule matter. An
+ * update-priced monitor charges per change and has nothing to reuse, which
+ * means the charge path can skip reading its previous state entirely - and
+ * that read is on a batch create path that runs once per member.
+ */
+export function policyOpensRenewalPeriod(
+  policy: MonitorBillingPolicy,
+): boolean {
+  return nextRenewalAtForPolicy(policy) !== null;
+}
+
+function nextRenewalAtForPolicy(
+  policy: MonitorBillingPolicy,
+  chargedAt?: Date,
+): string | null {
+  const recurring = policy.providerChargeComponents.find(
+    (component) => component.kind === 'provider_recurring_period',
+  );
+  if (recurring?.kind === 'provider_recurring_period') {
+    const base = chargedAt ?? new Date();
+    return new Date(
+      base.getTime() + recurring.periodDays * 24 * 60 * 60 * 1000,
+    ).toISOString();
+  }
+
+  const hasMonthlyPlanRenewal = policy.providerChargeComponents.some(
+    (component) =>
+      component.kind === 'provider_entitlement_cost' &&
+      component.phase === 'periodic_renewal',
+  );
+  if (!hasMonthlyPlanRenewal) {
+    return null;
+  }
+
+  const base = chargedAt ?? new Date();
+  return new Date(base.getTime() + 30 * 24 * 60 * 60 * 1000).toISOString();
+}