deepline 0.3.87 → 0.3.88

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

@@ -1,686 +0,0 @@
-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,
-  };
-}