deepline 0.3.88 → 0.3.90

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

@@ -0,0 +1,260 @@
+import { monitorProviderUsdToRetailCredits } from '@deepline/monitors/billing/pricing';
+import type {
+  MonitorCommercialModel,
+  MonitorPayloadPricingEntry,
+  MonitorPayloadPricingMap,
+} from '@deepline/monitors/billing/types';
+import { publicMonitorPricingEntry } from '@deepline/monitors/billing/public-pricing';
+
+export const TAMRADAR_RADAR_TYPE_PRICING = {
+  company_job_openings: {
+    capability: 'company_radar',
+    label: 'Company job openings',
+    mode: 'monitor_usage',
+    providerCostUsd: 0.025,
+    unitLabel: 'finding',
+  },
+  company_promotions: {
+    capability: 'company_radar',
+    label: 'Company promotions',
+    mode: 'monitor_usage',
+    providerCostUsd: 0.035,
+    unitLabel: 'finding',
+  },
+  company_mentions: {
+    capability: 'company_radar',
+    label: 'Company mentions',
+    mode: 'monitor_usage',
+    providerCostUsd: 0.03,
+    unitLabel: 'finding',
+  },
+  // Source: TAMRadar per-update pricing (confidential/internal),
+  // https://tamradar.mintlify.app/api-reference/create-company-radar (new_hires).
+  company_new_hires: {
+    capability: 'company_radar',
+    label: 'Company new hires',
+    mode: 'monitor_usage',
+    providerCostUsd: 0.035,
+    unitLabel: 'finding',
+  },
+  // Source: TAMRadar per-update pricing (confidential/internal),
+  // https://tamradar.mintlify.app/api-reference/create-company-radar (reviews).
+  company_reviews: {
+    capability: 'company_radar',
+    label: 'Company reviews',
+    mode: 'monitor_usage',
+    providerCostUsd: 0.03,
+    unitLabel: 'finding',
+  },
+  // Source: TAMRadar per-update pricing (confidential/internal),
+  // https://tamradar.mintlify.app/api-reference/create-company-radar (social_posts).
+  company_social_posts: {
+    capability: 'company_radar',
+    label: 'Company social posts',
+    mode: 'monitor_usage',
+    providerCostUsd: 0.015,
+    unitLabel: 'finding',
+  },
+  // Source: TAMRadar per-update pricing (confidential/internal),
+  // https://tamradar.mintlify.app/api-reference/create-company-radar (social_engagements).
+  company_social_engagements: {
+    capability: 'company_radar',
+    label: 'Company social engagements',
+    mode: 'monitor_usage',
+    providerCostUsd: 0.025,
+    unitLabel: 'finding',
+  },
+  contact_job_changes: {
+    capability: 'contact_radar',
+    label: 'Contact job changes',
+    mode: 'monitor_subscription',
+    providerCostUsd: 0.07,
+    unitLabel: 'month',
+    periodDays: 30,
+  },
+  // Source: TAMRadar per-update pricing (confidential/internal),
+  // https://tamradar.mintlify.app/api-reference/create-contact-radar (social_posts).
+  contact_social_posts: {
+    capability: 'contact_radar',
+    label: 'Contact social posts',
+    mode: 'monitor_usage',
+    providerCostUsd: 0.03,
+    unitLabel: 'finding',
+  },
+  // Source: TAMRadar per-update pricing (confidential/internal),
+  // https://tamradar.mintlify.app/api-reference/create-contact-radar (social_engagements).
+  contact_social_engagements: {
+    capability: 'contact_radar',
+    label: 'Contact social engagements',
+    mode: 'monitor_usage',
+    providerCostUsd: 0.025,
+    unitLabel: 'finding',
+  },
+  industry_mentions: {
+    capability: 'industry_radar',
+    label: 'Industry mentions',
+    mode: 'monitor_usage',
+    providerCostUsd: 0.03,
+    unitLabel: 'finding',
+  },
+  // Source: TAMRadar per-update pricing (confidential/internal),
+  // https://tamradar.mintlify.app/api-reference/create-industry-radar (job_openings).
+  industry_job_openings: {
+    capability: 'industry_radar',
+    label: 'Industry job openings',
+    mode: 'monitor_usage',
+    providerCostUsd: 0.045,
+    unitLabel: 'finding',
+  },
+  // DORMANT (disabled from deployment — see TAMRADAR_DISABLED_RADAR_TYPES).
+  // Kept for reversibility: $150/mo resell-tier subscription pricing is retained
+  // so the type can be re-enabled per-partner by removing it from the disabled
+  // set. It is excluded from the deployable enum + public pricing surface.
+  industry_funding_rounds: {
+    capability: 'industry_radar',
+    label: 'Industry funding rounds',
+    mode: 'monitor_subscription',
+    providerCostUsd: 150,
+    unitLabel: 'month',
+    periodDays: 30,
+  },
+} as const;
+
+export type TamradarRadarType = keyof typeof TAMRADAR_RADAR_TYPE_PRICING;
+
+export function isTamradarRadarType(value: string): value is TamradarRadarType {
+  return value in TAMRADAR_RADAR_TYPE_PRICING;
+}
+
+// Explicit, documented off-switch for radar types that are modeled/priced but
+// intentionally NOT deployable. Each entry carries a one-line CUSTOMER-FACING
+// reason. Disabled types are EXCLUDED from every capability's deployable
+// `radar_type` enum (so they never appear in `monitors tools`/CLI and payload
+// validation rejects them) and from the public pricing surface — the deploy
+// path surfaces a clear "radar type not available for deployment" error rather
+// than a bare enum mismatch. Flipping a type back on is a one-line delete here
+// (the two resell-tier types below carry resell rights and may be enabled
+// per-partner).
+//
+// IMPORTANT (guardrail): these reason strings are CUSTOMER-VISIBLE — they flow
+// into the deploy-rejection `suggestion` via `tamradarDisabledRadarTypeReason`.
+// NEVER put provider spend, resell-tier prices, or any "$X/mo" figure here.
+// Internal price context belongs in the per-entry code comment below, not in
+// the returned string.
+export const TAMRADAR_DISABLED_RADAR_TYPES: Record<string, string> = {
+  company_social_posts_cxo:
+    'This Deepline radar type is not available for self-serve deploy.',
+  // Internal note (NOT customer-visible): $250/mo resell-tier subscription.
+  industry_new_companies:
+    'This Deepline radar type is not available for self-serve deploy.',
+  // Internal note (NOT customer-visible): $150/mo resell-tier subscription.
+  industry_funding_rounds:
+    'This Deepline radar type is not available for self-serve deploy.',
+};
+
+export function isTamradarDisabledRadarType(value: string): boolean {
+  return value in TAMRADAR_DISABLED_RADAR_TYPES;
+}
+
+export function tamradarDisabledRadarTypeReason(value: string): string | null {
+  return TAMRADAR_DISABLED_RADAR_TYPES[value] ?? null;
+}
+
+// Deployable radar types for a capability = priced under that capability MINUS
+// any disabled type. This is the single source the capability enum + public
+// pricing derive from, so disabling a type flips every surface at once.
+export function tamradarDeployableRadarTypesForCapability(
+  capability: string,
+): TamradarRadarType[] {
+  return (Object.keys(TAMRADAR_RADAR_TYPE_PRICING) as TamradarRadarType[])
+    .filter((radarType) => !isTamradarDisabledRadarType(radarType))
+    .filter(
+      (radarType) =>
+        TAMRADAR_RADAR_TYPE_PRICING[radarType].capability === capability,
+    );
+}
+
+export function tamradarProviderCostKey(input: {
+  capability: string;
+  radarType: string;
+}) {
+  return `deepline_native.${input.capability}.${input.radarType}`;
+}
+
+function entryForRadarType(
+  radarType: TamradarRadarType,
+): MonitorPayloadPricingEntry {
+  const config = TAMRADAR_RADAR_TYPE_PRICING[radarType];
+  return {
+    label: config.label,
+    mode: config.mode,
+    providerCostKey: tamradarProviderCostKey({
+      capability: config.capability,
+      radarType,
+    }),
+    providerCostUsd: config.providerCostUsd,
+    retailCredits: monitorProviderUsdToRetailCredits(config.providerCostUsd),
+    unitLabel: config.unitLabel,
+    ...(config.mode === 'monitor_subscription'
+      ? { periodDays: config.periodDays }
+      : {}),
+  };
+}
+
+export function tamradarPricingEntryForRadarType(
+  radarType: string | null | undefined,
+) {
+  if (!radarType || !isTamradarRadarType(radarType)) return null;
+  return entryForRadarType(radarType);
+}
+
+export function tamradarPayloadPricingForCapability(
+  capability: string,
+): MonitorPayloadPricingMap {
+  const entries = Object.fromEntries(
+    Object.keys(TAMRADAR_RADAR_TYPE_PRICING)
+      .filter(
+        (radarType): radarType is TamradarRadarType =>
+          TAMRADAR_RADAR_TYPE_PRICING[radarType as TamradarRadarType]
+            .capability === capability,
+      )
+      .map((radarType) => [radarType, entryForRadarType(radarType)]),
+  );
+  return {
+    discriminator: 'radar_type',
+    entries,
+  };
+}
+
+export function tamradarCommercialModelForCapability(
+  capability: string,
+): MonitorCommercialModel {
+  const pricing = tamradarPayloadPricingForCapability(capability);
+  return {
+    kind: 'provider_native_payload_map',
+    discriminator: pricing.discriminator,
+    entries: Object.fromEntries(
+      Object.entries(pricing.entries).map(([radarType, entry]) => [
+        radarType,
+        {
+          mode: entry.mode,
+          providerCostKey: entry.providerCostKey,
+        },
+      ]),
+    ),
+  };
+}
+
+export function tamradarPublicPricingByRadarType(capability: string) {
+  const pricing = tamradarPayloadPricingForCapability(capability);
+  return Object.fromEntries(
+    Object.entries(pricing.entries)
+      // Never expose disabled radar types on the public/capability pricing
+      // surface — they are not deployable (see TAMRADAR_DISABLED_RADAR_TYPES).
+      .filter(([radarType]) => !isTamradarDisabledRadarType(radarType))
+      .map(([radarType, entry]) => [
+        radarType,
+        publicMonitorPricingEntry(entry),
+      ]),
+  );
+}

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

@@ -0,0 +1,215 @@
+export type MonitorBillingPhase =
+  | 'create'
+  | 'reactivate'
+  | 'periodic_renewal'
+  | 'subscription_renewal'
+  | 'webhook_event'
+  | 'provider_execution'
+  | 'manual_update';
+
+export type MonitorBillingState =
+  | 'active'
+  | 'preflight_denied'
+  | 'billing_pending'
+  | 'billing_suspended'
+  | 'upstream_disable_pending'
+  | 'upstream_disable_failed'
+  | 'disabled';
+
+export type MonitorBillingEvidenceStatus = 'verified' | 'partially_unresolved';
+
+export type MonitorBillingSourceKind =
+  | 'official_provider_docs'
+  | 'official_pricing_page'
+  | 'official_api_reference'
+  | 'provider_account_truth'
+  | 'provider_contract_or_invoice';
+
+export type MonitorBillingSource = {
+  kind: MonitorBillingSourceKind;
+  label: string;
+  url: string;
+  verifiedAt: string;
+  notes?: string;
+};
+
+export type MonitorEconomicResponsibility =
+  | 'deepline_managed_upstream'
+  | 'runtime_upstream_account_owner'
+  | 'customer_owned_upstream';
+
+export type MonitorRetailChargeSource =
+  | 'plan_entitlement_formula'
+  | 'metered_monitor_default'
+  | 'configured_deepline_retail_fee'
+  | 'static_provider_unit_formula'
+  | 'provider_truth_markup';
+
+export type MonitorRetailChargeComponent =
+  | {
+      kind: 'fixed_deepline_credits';
+      credits: number;
+      source: MonitorRetailChargeSource;
+      customerLabel: string;
+      basis?: {
+        minimumMonthlyPlanUsd?: number;
+        allocationDivisor?: number;
+        usdPerDeeplineCredit?: number;
+      };
+    }
+  | {
+      kind: 'upstream_cost_markup';
+      multiplier: number;
+      source: 'static_provider_unit' | 'provider_truth';
+      customerLabel: string;
+      providerCostKey: string;
+      retailCredits?: number;
+    }
+  | {
+      kind: 'no_customer_charge';
+      reason:
+        | 'included_in_plan_entitlement'
+        | 'customer_paid_upstream'
+        | 'provider_documented_no_charge';
+      customerLabel: string;
+    };
+
+export type MonitorRetailCharge = {
+  phase: MonitorBillingPhase;
+  label: string;
+  components: readonly MonitorRetailChargeComponent[];
+};
+
+export type MonitorPayloadPricingMode =
+  | 'monitor_usage'
+  | 'monitor_subscription';
+
+export type MonitorPayloadPricingEntry = {
+  label: string;
+  mode: MonitorPayloadPricingMode;
+  providerCostKey: string;
+  providerCostUsd: number;
+  retailCredits: number;
+  unitLabel: string;
+  periodDays?: number;
+};
+
+export type MonitorPayloadPricingMap = {
+  discriminator: string;
+  entries: Record<string, MonitorPayloadPricingEntry>;
+};
+
+export type MonitorProviderTruthSource =
+  | 'provider_response'
+  | 'provider_webhook'
+  | 'provider_account_balance_delta'
+  | 'provider_billing_export'
+  | 'provider_ledger_api';
+
+export type MonitorProviderChargeComponent =
+  | {
+      kind: 'provider_documented_no_charge';
+      phase: MonitorBillingPhase;
+      scope: string;
+      sourceLabel: string;
+    }
+  | {
+      kind: 'provider_entitlement_cost';
+      phase: MonitorBillingPhase;
+      owner: MonitorEconomicResponsibility;
+      planName: string;
+      minimumMonthlyPlanUsd: number;
+      allocation: 'plan_entitlement_retail_formula' | 'customer_paid_directly';
+      usageIncluded: boolean;
+    }
+  | {
+      kind: 'provider_metered_static';
+      phase: MonitorBillingPhase;
+      providerCostKey: string;
+      unitName: string;
+      units: number | { min: number; max: number };
+      unitCostUsd: number;
+      retailCredits: number;
+      sourceLabel: string;
+    }
+  | {
+      kind: 'provider_metered_dynamic';
+      phase: MonitorBillingPhase;
+      truthSources: readonly MonitorProviderTruthSource[];
+      amountStatus: 'known_at_runtime';
+      sourceLabel: string;
+    }
+  | {
+      kind: 'provider_recurring_period';
+      phase: 'periodic_renewal';
+      periodDays: number;
+      amountStatus: 'known_at_runtime' | 'unresolved';
+      amountUsd?: number;
+      sourceLabel: string;
+    }
+  | {
+      kind: 'unresolved_deepline_paid_exposure';
+      phase: MonitorBillingPhase;
+      missing: readonly (
+        | 'exact_billing_mode'
+        | 'exact_usd_amount'
+        | 'provider_truth_source'
+      )[];
+      sourceLabel: string;
+      blocksPublicDeploy: true;
+    };
+
+export type MonitorBillingPolicy = {
+  provider: string;
+  capability: string;
+  providerCapability: string;
+  pricingMode:
+    | 'plan_entitlement'
+    | 'metered_static'
+    | 'metered_dynamic'
+    | 'mixed_provider_native'
+    | 'hybrid_unresolved';
+  evidenceStatus: MonitorBillingEvidenceStatus;
+  economicResponsibility: MonitorEconomicResponsibility;
+  sourceDocs: readonly MonitorBillingSource[];
+  upstreamMarkupMultiplier: number;
+  customerCreateCharge: MonitorRetailCharge;
+  customerReactivateCharge: MonitorRetailCharge;
+  customerUsageCharges: readonly MonitorRetailCharge[];
+  providerChargeComponents: readonly MonitorProviderChargeComponent[];
+  disableOnBillingFailure: boolean;
+  payloadPricing?: MonitorPayloadPricingMap;
+};
+
+export type MonitorBillingSession = {
+  key: string;
+  orgId: string;
+  monitorKey: string;
+  billingReason: MonitorBillingPhase;
+  providerEventIdOrPeriod: string;
+};
+
+export type MonitorCommercialModel =
+  | {
+      kind: 'wrapper_entitlement';
+      entitlementId: string;
+      limitId: string;
+    }
+  | {
+      kind: 'provider_native_usage';
+    }
+  | {
+      kind: 'provider_native_payload_map';
+      discriminator: string;
+      entries: Record<
+        string,
+        {
+          mode: MonitorPayloadPricingMode;
+          providerCostKey: string;
+        }
+      >;
+    }
+  | {
+      kind: 'unresolved_fail_closed';
+      reason: string;
+    };