deepline 0.3.88 → 0.3.89

package/dist/bundling-sources/shared_libs/monitors/billing/policy-builders.ts

@@ -0,0 +1,686 @@
+import { getUsdPerCustomerCredit } from '@deepline/billing/credit-pricing';
+import {
+  MONITOR_BASE_LIFECYCLE_CREDITS,
+  MONITOR_BILLING_VERIFIED_AT,
+  MONITOR_PLAN_ENTITLEMENT_ALLOCATION_DIVISOR,
+  MONITOR_UPSTREAM_COST_MARKUP_MULTIPLIER,
+  monitorProviderUsdToRetailCredits,
+  planEntitlementCreateCredits,
+} from '@deepline/monitors/billing/pricing';
+import type {
+  MonitorBillingPolicy,
+  MonitorBillingSource,
+  MonitorEconomicResponsibility,
+  MonitorPayloadPricingEntry,
+  MonitorPayloadPricingMap,
+  MonitorProviderChargeComponent,
+  MonitorRetailCharge,
+  MonitorRetailChargeComponent,
+} from '@deepline/monitors/billing/types';
+import { providerMonitorCapabilityId } from '@deepline/monitors/provider-monitor-capability';
+import { tamradarPayloadPricingForCapability } from '@deepline/monitors/billing/tamradar';
+
+export type MonitorBillingSourceInput = Omit<
+  MonitorBillingSource,
+  'verifiedAt'
+>;
+
+type FixedRetailChargeSource = Extract<
+  MonitorRetailChargeComponent,
+  { kind: 'fixed_deepline_credits' }
+>['source'];
+type NoCustomerChargeReason = Extract<
+  MonitorRetailChargeComponent,
+  { kind: 'no_customer_charge' }
+>['reason'];
+type UpstreamMarkupSource = Extract<
+  MonitorRetailChargeComponent,
+  { kind: 'upstream_cost_markup' }
+>['source'];
+
+function source(input: MonitorBillingSourceInput): MonitorBillingSource {
+  return {
+    ...input,
+    verifiedAt: MONITOR_BILLING_VERIFIED_AT,
+  };
+}
+
+function fixedCredits(
+  credits: number,
+  customerLabel: string,
+  sourceKind: FixedRetailChargeSource,
+  basis?: Extract<
+    MonitorRetailChargeComponent,
+    { kind: 'fixed_deepline_credits' }
+  >['basis'],
+): MonitorRetailChargeComponent {
+  return {
+    kind: 'fixed_deepline_credits',
+    credits,
+    source: sourceKind,
+    customerLabel,
+    ...(basis ? { basis } : {}),
+  };
+}
+
+function noCustomerCharge(
+  reason: NoCustomerChargeReason,
+  customerLabel: string,
+): MonitorRetailChargeComponent {
+  return {
+    kind: 'no_customer_charge',
+    reason,
+    customerLabel,
+  };
+}
+
+function upstreamMarkupCharge(input: {
+  customerLabel: string;
+  providerCostKey: string;
+  retailCredits?: number;
+  source: UpstreamMarkupSource;
+  multiplier?: number;
+}): MonitorRetailChargeComponent {
+  return {
+    kind: 'upstream_cost_markup',
+    multiplier: input.multiplier ?? MONITOR_UPSTREAM_COST_MARKUP_MULTIPLIER,
+    source: input.source,
+    customerLabel: input.customerLabel,
+    providerCostKey: input.providerCostKey,
+    ...(typeof input.retailCredits === 'number'
+      ? { retailCredits: input.retailCredits }
+      : {}),
+  };
+}
+
+function retailCharge(
+  input: Omit<MonitorRetailCharge, 'components'> & {
+    components: MonitorRetailChargeComponent[];
+  },
+): MonitorRetailCharge {
+  return input;
+}
+
+export function definePlanEntitlementMonitorBillingPolicy(input: {
+  provider: string;
+  capability: string;
+  planName: string;
+  minimumMonthlyPlanUsd: number;
+  sources: MonitorBillingSourceInput[];
+  eventDeliverySourceLabel: string;
+  economicResponsibility?: MonitorEconomicResponsibility;
+}): MonitorBillingPolicy {
+  const providerCapability = providerMonitorCapabilityId(input);
+  const createCredits = planEntitlementCreateCredits(
+    input.minimumMonthlyPlanUsd,
+  );
+  const basis = {
+    minimumMonthlyPlanUsd: input.minimumMonthlyPlanUsd,
+    allocationDivisor: MONITOR_PLAN_ENTITLEMENT_ALLOCATION_DIVISOR,
+    usdPerDeeplineCredit: getUsdPerCustomerCredit(),
+  };
+  const owner =
+    input.economicResponsibility ?? 'runtime_upstream_account_owner';
+  return {
+    provider: input.provider,
+    capability: input.capability,
+    providerCapability,
+    pricingMode: 'plan_entitlement',
+    evidenceStatus: 'verified',
+    economicResponsibility: owner,
+    sourceDocs: input.sources.map(source),
+    upstreamMarkupMultiplier: MONITOR_UPSTREAM_COST_MARKUP_MULTIPLIER,
+    customerCreateCharge: retailCharge({
+      phase: 'create',
+      label: 'Monitor create',
+      components: [
+        fixedCredits(
+          createCredits,
+          'Monitor create',
+          'plan_entitlement_formula',
+          basis,
+        ),
+      ],
+    }),
+    customerReactivateCharge: retailCharge({
+      phase: 'reactivate',
+      label: 'Monitor reactivate',
+      components: [
+        fixedCredits(
+          createCredits,
+          'Monitor reactivate',
+          'plan_entitlement_formula',
+          basis,
+        ),
+      ],
+    }),
+    customerUsageCharges: [
+      retailCharge({
+        phase: 'periodic_renewal',
+        label: 'Monitor renewal',
+        components: [
+          fixedCredits(
+            createCredits,
+            'Monitor renewal',
+            'plan_entitlement_formula',
+            basis,
+          ),
+        ],
+      }),
+      retailCharge({
+        phase: 'webhook_event',
+        label: 'Webhook event delivery',
+        components: [
+          noCustomerCharge(
+            'included_in_plan_entitlement',
+            'Usage included in monitor entitlement',
+          ),
+        ],
+      }),
+    ],
+    providerChargeComponents: [
+      {
+        kind: 'provider_entitlement_cost',
+        phase: 'create',
+        owner,
+        planName: input.planName,
+        minimumMonthlyPlanUsd: input.minimumMonthlyPlanUsd,
+        allocation:
+          owner === 'customer_owned_upstream'
+            ? 'customer_paid_directly'
+            : 'plan_entitlement_retail_formula',
+        usageIncluded: true,
+      },
+      {
+        kind: 'provider_entitlement_cost',
+        phase: 'periodic_renewal',
+        owner,
+        planName: input.planName,
+        minimumMonthlyPlanUsd: input.minimumMonthlyPlanUsd,
+        allocation:
+          owner === 'customer_owned_upstream'
+            ? 'customer_paid_directly'
+            : 'plan_entitlement_retail_formula',
+        usageIncluded: true,
+      },
+      {
+        kind: 'provider_entitlement_cost',
+        phase: 'webhook_event',
+        owner,
+        planName: input.planName,
+        minimumMonthlyPlanUsd: input.minimumMonthlyPlanUsd,
+        allocation:
+          owner === 'customer_owned_upstream'
+            ? 'customer_paid_directly'
+            : 'plan_entitlement_retail_formula',
+        usageIncluded: true,
+      },
+      {
+        kind: 'provider_documented_no_charge',
+        phase: 'webhook_event',
+        scope: 'Webhook event delivery inside the eligible plan entitlement',
+        sourceLabel: input.eventDeliverySourceLabel,
+      },
+    ],
+    disableOnBillingFailure: true,
+  };
+}
+
+export function defineWrapperEntitlementMonitorBillingPolicy(input: {
+  provider: string;
+  capability: string;
+  planName: string;
+  minimumMonthlyPlanUsd: number;
+  sources: MonitorBillingSourceInput[];
+  eventDeliverySourceLabel: string;
+  economicResponsibility?: MonitorEconomicResponsibility;
+}): MonitorBillingPolicy {
+  const policy = definePlanEntitlementMonitorBillingPolicy(input);
+  const noCharge = (phase: MonitorRetailCharge['phase']) =>
+    retailCharge({
+      phase,
+      label:
+        phase === 'webhook_event'
+          ? 'Webhook event delivery'
+          : phase === 'create'
+            ? 'Monitor create'
+            : 'Monitor reactivate',
+      components: [
+        noCustomerCharge(
+          'included_in_plan_entitlement',
+          'Included in Monitor Wrapper Pack entitlement',
+        ),
+      ],
+    });
+  return {
+    ...policy,
+    customerCreateCharge: noCharge('create'),
+    customerReactivateCharge: noCharge('reactivate'),
+    customerUsageCharges: policy.customerUsageCharges.map((charge) =>
+      noCharge(charge.phase),
+    ),
+  };
+}
+
+export function defineMeteredStaticMonitorBillingPolicy(input: {
+  provider: string;
+  capability: string;
+  customerMarkupMultiplier?: number;
+  sources: MonitorBillingSourceInput[];
+  createProviderComponents: MonitorProviderChargeComponent[];
+  usageCharges: {
+    label: string;
+    providerCostKey: string;
+    unitName: string;
+    units: number | { min: number; max: number };
+    unitCostUsd: number;
+    sourceLabel: string;
+  }[];
+}): MonitorBillingPolicy {
+  const providerCapability = providerMonitorCapabilityId(input);
+  const customerMarkupMultiplier =
+    input.customerMarkupMultiplier ?? MONITOR_UPSTREAM_COST_MARKUP_MULTIPLIER;
+  const usageRetailCharges = input.usageCharges.map((charge) => {
+    const units =
+      typeof charge.units === 'number' ? charge.units : charge.units.max;
+    const retailCredits = monitorProviderUsdToRetailCredits(
+      units * charge.unitCostUsd,
+      customerMarkupMultiplier,
+    );
+    return retailCharge({
+      phase: 'webhook_event',
+      label: charge.label,
+      components: [
+        upstreamMarkupCharge({
+          customerLabel: charge.label,
+          providerCostKey: charge.providerCostKey,
+          source: 'static_provider_unit',
+          retailCredits,
+          multiplier: customerMarkupMultiplier,
+        }),
+      ],
+    });
+  });
+  const upstreamCreateIsFree =
+    input.createProviderComponents.length > 0 &&
+    input.createProviderComponents.every(
+      (component) => component.kind === 'provider_documented_no_charge',
+    );
+  // create and reactivate share the same "waive base fee when upstream create is
+  // free, otherwise charge the base lifecycle credits" shape — differing only in
+  // phase + label. Build both from one helper so the waiver contract stays in
+  // lockstep across the two phases.
+  const baseLifecycleCharge = (
+    phase: 'create' | 'reactivate',
+    label: string,
+  ): MonitorRetailCharge =>
+    retailCharge({
+      phase,
+      label,
+      components: upstreamCreateIsFree
+        ? [
+            noCustomerCharge(
+              'provider_documented_no_charge',
+              'No Deepline base create fee — upstream creation is free; billed on responses',
+            ),
+          ]
+        : [
+            fixedCredits(
+              MONITOR_BASE_LIFECYCLE_CREDITS,
+              label,
+              'metered_monitor_default',
+            ),
+          ],
+    });
+  const createCharge = baseLifecycleCharge('create', 'Monitor create');
+  const reactivateCharge = baseLifecycleCharge(
+    'reactivate',
+    'Monitor reactivate',
+  );
+  return {
+    provider: input.provider,
+    capability: input.capability,
+    providerCapability,
+    pricingMode: 'metered_static',
+    evidenceStatus: 'verified',
+    economicResponsibility: 'deepline_managed_upstream',
+    sourceDocs: input.sources.map(source),
+    upstreamMarkupMultiplier: customerMarkupMultiplier,
+    customerCreateCharge: createCharge,
+    customerReactivateCharge: reactivateCharge,
+    customerUsageCharges: usageRetailCharges,
+    providerChargeComponents: [
+      ...input.createProviderComponents,
+      ...input.usageCharges.map((charge): MonitorProviderChargeComponent => {
+        const units =
+          typeof charge.units === 'number' ? charge.units : charge.units.max;
+        return {
+          kind: 'provider_metered_static',
+          phase: 'webhook_event',
+          providerCostKey: charge.providerCostKey,
+          unitName: charge.unitName,
+          units: charge.units,
+          unitCostUsd: charge.unitCostUsd,
+          retailCredits: monitorProviderUsdToRetailCredits(
+            units * charge.unitCostUsd,
+            customerMarkupMultiplier,
+          ),
+          sourceLabel: charge.sourceLabel,
+        };
+      }),
+    ],
+    disableOnBillingFailure: true,
+  };
+}
+
+export function defineTamradarUnresolvedMonitorBillingPolicy(
+  capability: string,
+): MonitorBillingPolicy {
+  const providerCapability = providerMonitorCapabilityId({
+    provider: 'deepline_native',
+    capability,
+  });
+  return {
+    provider: 'deepline_native',
+    capability,
+    providerCapability,
+    pricingMode: 'hybrid_unresolved',
+    evidenceStatus: 'partially_unresolved',
+    economicResponsibility: 'deepline_managed_upstream',
+    sourceDocs: [
+      source({
+        kind: 'official_provider_docs',
+        label: 'Deepline Balance and Pricing',
+        url: 'https://tamradar.mintlify.app/guides/balance-system-explained',
+      }),
+      source({
+        kind: 'official_provider_docs',
+        label: 'Deepline Monthly Subscription Billing',
+        url: 'https://tamradar.mintlify.app/guides/balance-monthly-subscription',
+      }),
+      source({
+        kind: 'official_provider_docs',
+        label: 'Deepline Update-Based Billing',
+        url: 'https://tamradar.mintlify.app/guides/balance-update-based',
+      }),
+      source({
+        kind: 'official_api_reference',
+        label: 'Deepline Account Summary',
+        url: 'https://tamradar.mintlify.app/api-reference/account',
+      }),
+      source({
+        kind: 'official_api_reference',
+        label: 'Deepline List Radars',
+        url: 'https://tamradar.mintlify.app/api-reference/list-radars',
+      }),
+    ],
+    upstreamMarkupMultiplier: MONITOR_UPSTREAM_COST_MARKUP_MULTIPLIER,
+    customerCreateCharge: retailCharge({
+      phase: 'create',
+      label: 'Monitor create',
+      components: [
+        fixedCredits(
+          MONITOR_BASE_LIFECYCLE_CREDITS,
+          'Monitor create',
+          'metered_monitor_default',
+        ),
+        upstreamMarkupCharge({
+          customerLabel: 'Provider setup charge, once known',
+          providerCostKey: `deepline_native.${capability}.create_or_period`,
+          source: 'provider_truth',
+        }),
+      ],
+    }),
+    customerReactivateCharge: retailCharge({
+      phase: 'reactivate',
+      label: 'Monitor reactivate',
+      components: [
+        fixedCredits(
+          MONITOR_BASE_LIFECYCLE_CREDITS,
+          'Monitor reactivate',
+          'metered_monitor_default',
+        ),
+        upstreamMarkupCharge({
+          customerLabel: 'Provider reactivation charge, once known',
+          providerCostKey: `deepline_native.${capability}.reactivate_or_period`,
+          source: 'provider_truth',
+        }),
+      ],
+    }),
+    customerUsageCharges: [
+      retailCharge({
+        phase: 'periodic_renewal',
+        label: 'Provider billing period',
+        components: [
+          upstreamMarkupCharge({
+            customerLabel: 'Provider billing period, once known',
+            providerCostKey: `deepline_native.${capability}.periodic_renewal`,
+            source: 'provider_truth',
+          }),
+        ],
+      }),
+      retailCharge({
+        phase: 'webhook_event',
+        label: 'Approved update or finding',
+        components: [
+          upstreamMarkupCharge({
+            customerLabel: 'Approved update or finding, once known',
+            providerCostKey: `deepline_native.${capability}.approved_update`,
+            source: 'provider_truth',
+          }),
+        ],
+      }),
+    ],
+    providerChargeComponents: [
+      {
+        kind: 'unresolved_deepline_paid_exposure',
+        phase: 'create',
+        missing: ['exact_billing_mode', 'exact_usd_amount'],
+        sourceLabel: 'Deepline Balance and Pricing',
+        blocksPublicDeploy: true,
+      },
+      {
+        kind: 'provider_recurring_period',
+        phase: 'periodic_renewal',
+        periodDays: 30,
+        amountStatus: 'unresolved',
+        sourceLabel: 'Deepline Monthly Subscription Billing',
+      },
+      {
+        kind: 'provider_metered_dynamic',
+        phase: 'webhook_event',
+        truthSources: [
+          'provider_webhook',
+          'provider_account_balance_delta',
+          'provider_ledger_api',
+        ],
+        amountStatus: 'known_at_runtime',
+        sourceLabel: 'Deepline Update-Based Billing',
+      },
+      {
+        kind: 'unresolved_deepline_paid_exposure',
+        phase: 'webhook_event',
+        missing: [
+          'exact_billing_mode',
+          'exact_usd_amount',
+          'provider_truth_source',
+        ],
+        sourceLabel: 'Deepline Update-Based Billing',
+        blocksPublicDeploy: true,
+      },
+    ],
+    disableOnBillingFailure: true,
+  };
+}
+
+function tamradarSourceDocs(): MonitorBillingSource[] {
+  return [
+    source({
+      kind: 'official_provider_docs',
+      label: 'Deepline Balance and Pricing',
+      url: 'https://tamradar.mintlify.app/guides/balance-system-explained',
+    }),
+    source({
+      kind: 'official_provider_docs',
+      label: 'Deepline Monthly Subscription Billing',
+      url: 'https://tamradar.mintlify.app/guides/balance-monthly-subscription',
+    }),
+    source({
+      kind: 'official_provider_docs',
+      label: 'Deepline Update-Based Billing',
+      url: 'https://tamradar.mintlify.app/guides/balance-update-based',
+    }),
+    source({
+      kind: 'official_api_reference',
+      label: 'Deepline Account Summary',
+      url: 'https://tamradar.mintlify.app/api-reference/account',
+    }),
+    source({
+      kind: 'official_api_reference',
+      label: 'Deepline List Radars',
+      url: 'https://tamradar.mintlify.app/api-reference/list-radars',
+    }),
+  ];
+}
+
+function payloadEntriesByMode(
+  pricing: MonitorPayloadPricingMap,
+  mode: MonitorPayloadPricingEntry['mode'],
+) {
+  return Object.entries(pricing.entries).filter(
+    (entry): entry is [string, MonitorPayloadPricingEntry] =>
+      entry[1].mode === mode,
+  );
+}
+
+function tamradarChargeForPayloadEntry(input: {
+  phase: MonitorRetailCharge['phase'];
+  entry: MonitorPayloadPricingEntry;
+}): MonitorRetailChargeComponent {
+  return upstreamMarkupCharge({
+    customerLabel: `${input.entry.label} ${input.entry.unitLabel}`,
+    providerCostKey: input.entry.providerCostKey,
+    source: 'static_provider_unit',
+    retailCredits: input.entry.retailCredits,
+  });
+}
+
+export function defineTamradarMonitorBillingPolicy(
+  capability: string,
+): MonitorBillingPolicy {
+  const providerCapability = providerMonitorCapabilityId({
+    provider: 'deepline_native',
+    capability,
+  });
+  const payloadPricing = tamradarPayloadPricingForCapability(capability);
+  const usageEntries = payloadEntriesByMode(payloadPricing, 'monitor_usage');
+  const subscriptionEntries = payloadEntriesByMode(
+    payloadPricing,
+    'monitor_subscription',
+  );
+  const subscriptionComponents = subscriptionEntries.map(([, entry]) =>
+    tamradarChargeForPayloadEntry({ phase: 'create', entry }),
+  );
+  const usageComponents = usageEntries.map(([, entry]) =>
+    tamradarChargeForPayloadEntry({ phase: 'webhook_event', entry }),
+  );
+  const noBaseCreateCharge = noCustomerCharge(
+    'provider_documented_no_charge',
+    'No Deepline base create charge',
+  );
+  const noBaseReactivateCharge = noCustomerCharge(
+    'provider_documented_no_charge',
+    'No Deepline base reactivate charge',
+  );
+  const customerUsageCharges: MonitorRetailCharge[] = [];
+  if (subscriptionEntries.length > 0) {
+    customerUsageCharges.push(
+      retailCharge({
+        phase: 'subscription_renewal',
+        label: 'Monitor subscription renewal',
+        components: subscriptionEntries.map(([, entry]) =>
+          tamradarChargeForPayloadEntry({
+            phase: 'subscription_renewal',
+            entry,
+          }),
+        ),
+      }),
+    );
+  }
+  if (usageEntries.length > 0) {
+    customerUsageCharges.push(
+      retailCharge({
+        phase: 'webhook_event',
+        label: 'Approved update or finding',
+        components: usageComponents,
+      }),
+    );
+  }
+
+  return {
+    provider: 'deepline_native',
+    capability,
+    providerCapability,
+    pricingMode: 'mixed_provider_native',
+    evidenceStatus: 'verified',
+    economicResponsibility: 'deepline_managed_upstream',
+    sourceDocs: tamradarSourceDocs(),
+    upstreamMarkupMultiplier: MONITOR_UPSTREAM_COST_MARKUP_MULTIPLIER,
+    customerCreateCharge: retailCharge({
+      phase: 'create',
+      label: 'Monitor create',
+      components: [noBaseCreateCharge, ...subscriptionComponents],
+    }),
+    customerReactivateCharge: retailCharge({
+      phase: 'reactivate',
+      label: 'Monitor reactivate',
+      components: [
+        noBaseReactivateCharge,
+        ...subscriptionEntries.map(([, entry]) =>
+          tamradarChargeForPayloadEntry({ phase: 'reactivate', entry }),
+        ),
+      ],
+    }),
+    customerUsageCharges,
+    providerChargeComponents: [
+      ...usageEntries.map(([, entry]): MonitorProviderChargeComponent => {
+        return {
+          kind: 'provider_metered_static',
+          phase: 'webhook_event',
+          providerCostKey: entry.providerCostKey,
+          unitName: entry.unitLabel,
+          units: 1,
+          unitCostUsd: entry.providerCostUsd,
+          retailCredits: entry.retailCredits,
+          sourceLabel: 'Deepline Update-Based Billing',
+        };
+      }),
+      ...subscriptionEntries.flatMap(([, entry]) => {
+        return [
+          {
+            kind: 'provider_metered_static',
+            phase: 'create',
+            providerCostKey: entry.providerCostKey,
+            unitName: entry.unitLabel,
+            units: 1,
+            unitCostUsd: entry.providerCostUsd,
+            retailCredits: entry.retailCredits,
+            sourceLabel: 'Deepline Monthly Subscription Billing',
+          },
+          {
+            kind: 'provider_metered_static',
+            phase: 'subscription_renewal',
+            providerCostKey: entry.providerCostKey,
+            unitName: entry.unitLabel,
+            units: 1,
+            unitCostUsd: entry.providerCostUsd,
+            retailCredits: entry.retailCredits,
+            sourceLabel: 'Deepline Monthly Subscription Billing',
+          },
+        ] satisfies MonitorProviderChargeComponent[];
+      }),
+    ],
+    disableOnBillingFailure: true,
+    payloadPricing,
+  };
+}