deepline 0.3.88 → 0.3.89

package/dist/bundling-sources/shared_libs/monitors/provider-monitor-identity-claims.ts

@@ -0,0 +1,535 @@
+import { randomUUID } from 'node:crypto';
+import {
+  PriorityMonitorExecutionLimitError,
+  ProviderMonitorCapacityBackfillInProgressError,
+  ProviderMonitorCapacityCleanupRequiredError,
+  ProviderMonitorIdentityBackfillInProgressError,
+  ProviderMonitorEntityLimitExceededError,
+  ProviderMonitorOrgLimitExceededError,
+} from '@deepline/monitors/provider-monitor-errors';
+import { MAX_PRIORITY_MONITORS_PER_ORG } from '@deepline/monitors/provider-monitor-priority-execution';
+import { internal } from '@convex/_generated/api';
+import { getRequiredInternalConvexClient } from '@/lib/convex/internal-client';
+import {
+  providerMonitorUpstreamIdentitySignature,
+  type ProviderMonitorUpstreamIdentitySignature,
+} from '@deepline/monitors/provider-monitor-upstream-identity';
+
+export type ProviderMonitorIdentityClaim = {
+  tool: string;
+  identityKey: string;
+  identity: Record<string, string | null>;
+};
+
+type OrgAuthContext = { orgId: string };
+
+/**
+ * The durable control-plane release operation needs only the opaque claim
+ * locator. Keep the display identity out of this boundary: Convex validates
+ * release arguments strictly so a rich conflict claim cannot turn a completed
+ * upstream delete into a failed local transition.
+ */
+export type ProviderMonitorIdentityClaimReference = Pick<
+  ProviderMonitorIdentityClaim,
+  'tool' | 'identityKey'
+>;
+
+export function providerMonitorIdentityClaimReference(
+  claim: ProviderMonitorIdentityClaim | null | undefined,
+): ProviderMonitorIdentityClaimReference | null {
+  return claim ? { tool: claim.tool, identityKey: claim.identityKey } : null;
+}
+
+export type ProviderMonitorIdentityReservation =
+  | {
+      kind: 'acquired';
+      claim: ProviderMonitorIdentityClaim;
+      restoredState: 'release' | 'active';
+      operationId: string;
+    }
+  | {
+      kind: 'occupied';
+      claim: ProviderMonitorIdentityClaim;
+      monitorKey: string;
+      state: 'provisioning' | 'active' | 'migration_conflict';
+      conflictingMonitorKeys?: string[];
+    }
+  | {
+      kind: 'in_progress';
+      claim: ProviderMonitorIdentityClaim;
+      monitorKey: string;
+      retryAt: number;
+    };
+
+/**
+ * An exact, per-monitor-key fence around an upstream lifecycle request.
+ * Unlike an identity claim, this applies even when a provider does not expose
+ * an account-unique identity.
+ */
+export type ProviderMonitorLifecycleReservation =
+  | {
+      kind: 'acquired';
+      state: 'provisioning' | 'deleting';
+      operationId: string;
+    }
+  | {
+      kind: 'in_progress';
+      state: 'provisioning' | 'deleting';
+      retryAt: number;
+    }
+  | {
+      kind: 'deleting';
+      state: 'deleting';
+      retryAt: number;
+    }
+  | {
+      kind: 'not_eligible';
+    };
+
+function record(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+function finiteNumber(value: unknown): number | null {
+  return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+
+/** Convex owns lifecycle admission and validates every durable result. */
+export function normalizeProviderMonitorLifecycleReservation(input: {
+  result: unknown;
+  state: 'provisioning' | 'deleting';
+  operationId: string;
+}): ProviderMonitorLifecycleReservation {
+  const result = record(input.result);
+  if (!result || typeof result.kind !== 'string') {
+    throw new Error(
+      'Provider monitor lifecycle admission returned an invalid control-plane result.',
+    );
+  }
+  if (result.kind === 'acquired') {
+    return {
+      kind: 'acquired',
+      state: input.state,
+      operationId: input.operationId,
+    };
+  }
+  if (result.kind === 'not_eligible') {
+    return { kind: 'not_eligible' };
+  }
+  if (
+    (result.kind !== 'in_progress' && result.kind !== 'deleting') ||
+    (result.state !== 'provisioning' && result.state !== 'deleting') ||
+    finiteNumber(result.retryAt) === null
+  ) {
+    throw new Error(
+      'Provider monitor lifecycle admission returned an unknown control-plane result.',
+    );
+  }
+  if (result.kind === 'deleting' && result.state !== 'deleting') {
+    throw new Error(
+      'Provider monitor lifecycle deletion admission returned an invalid operation state.',
+    );
+  }
+  if (result.kind === 'in_progress') {
+    return {
+      kind: 'in_progress',
+      state: result.state as 'provisioning' | 'deleting',
+      retryAt: result.retryAt as number,
+    };
+  }
+  return {
+    kind: 'deleting',
+    state: 'deleting',
+    retryAt: result.retryAt as number,
+  };
+}
+
+function claimFromSignature(
+  signature: ProviderMonitorUpstreamIdentitySignature,
+): ProviderMonitorIdentityClaim {
+  const identity = Object.fromEntries(
+    Object.entries(signature.key).sort(([a], [b]) => a.localeCompare(b)),
+  );
+  return {
+    tool: signature.tool,
+    identityKey: JSON.stringify(identity),
+    identity,
+  };
+}
+
+export function providerMonitorIdentityClaim(input: {
+  tool: string;
+  payload: Record<string, unknown> | null | undefined;
+}) {
+  // Claims protect provider resources, including legacy rows whose public
+  // capability id was later retired. The Convex-safe identity contract owns
+  // those aliases; the live capability registry intentionally does not.
+  const signature = providerMonitorUpstreamIdentitySignature(
+    input.tool,
+    input.payload,
+  );
+  return signature ? claimFromSignature(signature) : null;
+}
+
+/**
+ * Makes a legacy Convex org safe for indexed identity admission. A new org
+ * gets one bounded page inline so normal small workspaces stay transparent;
+ * a larger org continues in a durable, no-provider-side-effect Convex job and
+ * receives a retryable response rather than scanning tens of thousands of
+ * legacy definitions synchronously. Later calls are a single complete-marker
+ * read.
+ */
+export async function ensureProviderMonitorIdentityBackfill(input: {
+  auth: OrgAuthContext;
+}) {
+  const client = getRequiredInternalConvexClient();
+  const globallyComplete = await client.query(
+    internal.providerMonitorIdentityClaims.globalBackfillComplete,
+    {},
+  );
+  if (globallyComplete) return;
+  const state = await client.query(
+    internal.providerMonitorIdentityClaims.backfillStatus,
+    { orgId: input.auth.orgId },
+  );
+  if (state === 'complete') return;
+
+  if (state === 'not_started') {
+    // The marker/fence is committed before the first page reads the legacy
+    // index. Therefore every caller, including a rolling pre-claim app
+    // process, reaches the current Convex upsert and cannot slip an unclaimed
+    // identity behind this cursor.
+    await client.mutation(
+      internal.providerMonitorIdentityClaims.startBackfill,
+      { orgId: input.auth.orgId, schedule: false },
+    );
+    const initialPage = await client.mutation(
+      internal.providerMonitorIdentityClaims.backfillNextPage,
+      { orgId: input.auth.orgId },
+    );
+    if (initialPage.complete) return;
+  }
+
+  const started = await client.mutation(
+    internal.providerMonitorIdentityClaims.startBackfill,
+    { orgId: input.auth.orgId },
+  );
+  if (started.state === 'complete') return;
+  throw new ProviderMonitorIdentityBackfillInProgressError();
+}
+
+export async function getProviderMonitorIdentityOwner(input: {
+  auth: OrgAuthContext;
+  claim: ProviderMonitorIdentityClaim;
+}) {
+  return getRequiredInternalConvexClient().query(
+    internal.providerMonitorIdentityClaims.get,
+    {
+      orgId: input.auth.orgId,
+      tool: input.claim.tool,
+      identityKey: input.claim.identityKey,
+    },
+  );
+}
+
+export function providerMonitorIdentityProvisioningForMonitor(input: {
+  auth: OrgAuthContext;
+  monitorKey: string;
+}) {
+  return getRequiredInternalConvexClient().query(
+    internal.providerMonitorIdentityClaims.provisioningForMonitor,
+    { orgId: input.auth.orgId, monitorKey: input.monitorKey },
+  );
+}
+
+export function priorityMonitorExecutionLimitFromLifecycleError(
+  error: unknown,
+) {
+  if (
+    error instanceof Error &&
+    error.message.includes('PRIORITY_MONITOR_LIMIT_EXCEEDED')
+  ) {
+    return new PriorityMonitorExecutionLimitError(
+      MAX_PRIORITY_MONITORS_PER_ORG,
+    );
+  }
+  return null;
+}
+
+// Convex retries mutations itself. This is the bounded outer retry for the
+// rare case in which that budget is exhausted while the short capacity-fold
+// mutation is updating the same organization fence. Lifecycle admission is
+// still pre-provider and reuses one operation id, so replaying it cannot make
+// an upstream monitor, charge, or fence duplicate.
+const LIFECYCLE_ADMISSION_WRITE_CONFLICT =
+  /write conflict|optimisticconcurrencycontrolfailure|documents read from or written to .* changed while this mutation was being run/i;
+const MAX_LIFECYCLE_ADMISSION_RETRIES = 3;
+
+function lifecycleAdmissionWriteConflict(error: unknown) {
+  const message =
+    error instanceof Error
+      ? error.message
+      : typeof error === 'string'
+        ? error
+        : '';
+  return LIFECYCLE_ADMISSION_WRITE_CONFLICT.test(message);
+}
+
+async function sleep(ms: number) {
+  await new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export async function retryProviderMonitorLifecycleAdmission<T>(
+  operation: () => Promise<T>,
+): Promise<T> {
+  for (
+    let attempt = 0;
+    attempt <= MAX_LIFECYCLE_ADMISSION_RETRIES;
+    attempt += 1
+  ) {
+    try {
+      return await operation();
+    } catch (error) {
+      if (
+        !lifecycleAdmissionWriteConflict(error) ||
+        attempt === MAX_LIFECYCLE_ADMISSION_RETRIES
+      ) {
+        throw error;
+      }
+      await sleep(25 * 2 ** attempt);
+    }
+  }
+  throw new Error('Provider monitor lifecycle admission retry exhausted.');
+}
+
+export async function beginProviderMonitorLifecycleReservation(input: {
+  auth: OrgAuthContext;
+  monitorKey: string;
+  /**
+   * A durable bulk operation supplies its stable item attempt id.  The
+   * ordinary scalar path intentionally leaves this unset and mints a fresh
+   * UUID.  Reusing the same id lets a reclaimed batch refresh its own fence
+   * without ever turning an already-recorded provider intent into a second
+   * create.
+   */
+  operationId?: string;
+  /** Tool and payload of the monitor being provisioned, so capacity can be
+   *  counted against the account it watches rather than against the row. */
+  entityKey?: string | null;
+  state: 'provisioning' | 'deleting';
+  priorityExecutionSlots?: number;
+  expectedControlStateRevision?: number;
+  requiredMonitorStatus?: 'active';
+}): Promise<ProviderMonitorLifecycleReservation> {
+  const operationId = input.operationId ?? randomUUID();
+  const action =
+    input.state === 'provisioning'
+      ? internal.providerMonitorIdentityClaims.beginLifecycleProvisioning
+      : internal.providerMonitorIdentityClaims.beginLifecycleDeletion;
+  const request = () =>
+    getRequiredInternalConvexClient().mutation(action, {
+      orgId: input.auth.orgId,
+      monitorKey: input.monitorKey,
+      operationId,
+      ...(input.entityKey ? { entityKey: input.entityKey } : {}),
+      ...(input.priorityExecutionSlots === 1
+        ? { priorityExecutionSlots: 1 }
+        : {}),
+      ...(typeof input.expectedControlStateRevision === 'number'
+        ? { expectedControlStateRevision: input.expectedControlStateRevision }
+        : {}),
+      ...(input.requiredMonitorStatus
+        ? { requiredMonitorStatus: input.requiredMonitorStatus }
+        : {}),
+    });
+  // A priority-slot refusal arrives as a thrown lifecycle error, while the
+  // capacity outcomes below arrive as a returned kind. Both paths have to work
+  // on the same call, and the backfill retry has to re-run the same request.
+  const attempt = async () => {
+    try {
+      return await request();
+    } catch (error) {
+      const priorityLimit =
+        priorityMonitorExecutionLimitFromLifecycleError(error);
+      if (priorityLimit) throw priorityLimit;
+      throw error;
+    }
+  };
+  let result = await retryProviderMonitorLifecycleAdmission(attempt);
+  if (result.kind === 'backfill_required') {
+    await ensureProviderMonitorCapacityBackfill({ auth: input.auth });
+    result = await retryProviderMonitorLifecycleAdmission(attempt);
+  }
+  if (result.kind === 'limit_exceeded') {
+    throw new ProviderMonitorOrgLimitExceededError(result.capacity);
+  }
+  if (result.kind === 'entity_limit_exceeded') {
+    throw new ProviderMonitorEntityLimitExceededError(
+      result.entityKey,
+      result.capacity.monitors_per_entity,
+    );
+  }
+  if (result.kind === 'cleanup_blocked') {
+    throw new ProviderMonitorCapacityCleanupRequiredError(input.monitorKey);
+  }
+  if (result.kind === 'backfill_required') {
+    throw new ProviderMonitorCapacityBackfillInProgressError();
+  }
+  return normalizeProviderMonitorLifecycleReservation({
+    result,
+    state: input.state,
+    operationId,
+  });
+}
+
+async function ensureProviderMonitorCapacityBackfill(input: {
+  auth: OrgAuthContext;
+}) {
+  const client = getRequiredInternalConvexClient();
+  const state = await client.query(
+    internal.providerMonitorCapacity.backfillStatus,
+    { orgId: input.auth.orgId },
+  );
+  if (state === 'complete') return;
+
+  if (state === 'not_started') {
+    await client.mutation(internal.providerMonitorCapacity.startBackfill, {
+      orgId: input.auth.orgId,
+      schedule: false,
+    });
+    const initialPage = await client.mutation(
+      internal.providerMonitorCapacity.backfillNextPage,
+      { orgId: input.auth.orgId },
+    );
+    if (initialPage.complete) return;
+  }
+
+  const started = await client.mutation(
+    internal.providerMonitorCapacity.startBackfill,
+    { orgId: input.auth.orgId },
+  );
+  if (started.state === 'complete') return;
+  throw new ProviderMonitorCapacityBackfillInProgressError();
+}
+
+export function failProviderMonitorLifecycleReservation(input: {
+  auth: OrgAuthContext;
+  monitorKey: string;
+  reservation: Extract<
+    ProviderMonitorLifecycleReservation,
+    { kind: 'acquired' }
+  >;
+}) {
+  return getRequiredInternalConvexClient().mutation(
+    internal.providerMonitorIdentityClaims.failLifecycleOperation,
+    {
+      orgId: input.auth.orgId,
+      monitorKey: input.monitorKey,
+      state: input.reservation.state,
+      operationId: input.reservation.operationId,
+    },
+  );
+}
+
+export async function beginProviderMonitorIdentityReservation(input: {
+  auth: OrgAuthContext;
+  monitorKey: string;
+  tool: string;
+  payload: Record<string, unknown> | null | undefined;
+  /**
+   * Resume rather than wait when THIS monitor key already holds a provisioning
+   * claim. Only for callers that serialise their own passes for a member -
+   * see `reclaimSelfProvisioning` on the mutation.
+   */
+  reclaimSelfProvisioning?: boolean;
+}): Promise<ProviderMonitorIdentityReservation | null> {
+  const claim = providerMonitorIdentityClaim(input);
+  if (!claim) return null;
+  await ensureProviderMonitorIdentityBackfill({ auth: input.auth });
+  const operationId = randomUUID();
+  const result = await getRequiredInternalConvexClient().mutation(
+    internal.providerMonitorIdentityClaims.begin,
+    {
+      orgId: input.auth.orgId,
+      tool: claim.tool,
+      identityKey: claim.identityKey,
+      monitorKey: input.monitorKey,
+      operationId,
+      ...(input.reclaimSelfProvisioning
+        ? { reclaimSelfProvisioning: true }
+        : {}),
+    },
+  );
+  if (result.kind === 'acquired') {
+    return {
+      kind: 'acquired',
+      claim,
+      restoredState: result.restoredState,
+      operationId,
+    };
+  }
+  if (result.kind === 'occupied') {
+    return { ...result, claim };
+  }
+  return { ...result, claim };
+}
+
+async function mutateClaim(
+  action: 'activate' | 'release',
+  input: {
+    auth: OrgAuthContext;
+    monitorKey: string;
+    claim: ProviderMonitorIdentityClaim;
+    operationId?: string;
+  },
+) {
+  return getRequiredInternalConvexClient().mutation(
+    internal.providerMonitorIdentityClaims[action],
+    {
+      orgId: input.auth.orgId,
+      tool: input.claim.tool,
+      identityKey: input.claim.identityKey,
+      monitorKey: input.monitorKey,
+      ...(input.operationId ? { operationId: input.operationId } : {}),
+    },
+  );
+}
+
+export function activateProviderMonitorIdentityReservation(input: {
+  auth: OrgAuthContext;
+  monitorKey: string;
+  claim: ProviderMonitorIdentityClaim;
+  operationId: string;
+}) {
+  return mutateClaim('activate', input);
+}
+
+export function releaseProviderMonitorIdentityClaim(input: {
+  auth: OrgAuthContext;
+  monitorKey: string;
+  claim: ProviderMonitorIdentityClaim;
+}) {
+  return mutateClaim('release', input);
+}
+
+export function failProviderMonitorIdentityReservation(input: {
+  auth: OrgAuthContext;
+  monitorKey: string;
+  reservation: Extract<
+    ProviderMonitorIdentityReservation,
+    { kind: 'acquired' }
+  >;
+}) {
+  return getRequiredInternalConvexClient().mutation(
+    internal.providerMonitorIdentityClaims.fail,
+    {
+      orgId: input.auth.orgId,
+      tool: input.reservation.claim.tool,
+      identityKey: input.reservation.claim.identityKey,
+      monitorKey: input.monitorKey,
+      operationId: input.reservation.operationId,
+    },
+  );
+}

package/dist/bundling-sources/shared_libs/monitors/provider-monitor-legacy-aliases.ts

@@ -0,0 +1,16 @@
+const LEGACY_STORED_PROVIDER_MONITOR_CAPABILITY_ALIASES: Readonly<
+  Record<string, string>
+> = {
+  'tamradar.company_radar': 'deepline_native.company_radar',
+  'tamradar.contact_radar': 'deepline_native.contact_radar',
+  'tamradar.industry_radar': 'deepline_native.industry_radar',
+};
+
+export function canonicalizeStoredProviderMonitorCapabilityId(
+  providerCapability: string,
+): string {
+  return (
+    LEGACY_STORED_PROVIDER_MONITOR_CAPABILITY_ALIASES[providerCapability] ??
+    providerCapability
+  );
+}

package/dist/bundling-sources/shared_libs/monitors/provider-monitor-priority-execution.ts

@@ -0,0 +1,56 @@
+import type { ProviderMonitorCapabilityDefinition } from '@deepline/monitors/provider-monitor-capability';
+import type { ProviderMonitorStatus } from './provider-monitor-status';
+
+export const PRIORITY_MONITOR_EXECUTION_TYPE = 'priority' as const;
+export const MAX_PRIORITY_MONITORS_PER_ORG = 10;
+
+export const PRIORITY_MONITOR_SLOT_STATUSES = [
+  'active',
+  // A billing suspension writes disabled before upstream deprovisioning. Keep
+  // the slot occupied until that delete confirms success and clears the
+  // projection; a failed cleanup can leave the priority radar live.
+  'disabled',
+  'deleting',
+  'error',
+  'deleted',
+  // A fleet monitor holds its priority reservation from the commit that
+  // records the desired state, not from the provider create that follows it.
+  'pending_create',
+] as const satisfies readonly ProviderMonitorStatus[];
+
+const PRIORITY_MONITOR_SLOT_STATUS_SET = new Set<ProviderMonitorStatus>(
+  PRIORITY_MONITOR_SLOT_STATUSES,
+);
+
+export function requestedPriorityMonitorExecution(definition: {
+  controls?: Record<string, unknown>;
+}) {
+  return (
+    definition.controls?.execution_type === PRIORITY_MONITOR_EXECUTION_TYPE
+  );
+}
+
+export function priorityMonitorExecutionIsSupported(
+  capability: ProviderMonitorCapabilityDefinition,
+) {
+  return capability.provider === 'deepline_native';
+}
+
+export function priorityMonitorConsumesSlot(input: {
+  priorityExecution: boolean;
+  status: ProviderMonitorStatus;
+}) {
+  return (
+    input.priorityExecution &&
+    PRIORITY_MONITOR_SLOT_STATUS_SET.has(input.status)
+  );
+}
+
+export function priorityMonitorReservedSlotCount(input: {
+  priorityExecution: boolean;
+  status: ProviderMonitorStatus;
+  priorityExecutionSlots?: number;
+}) {
+  if (!priorityMonitorConsumesSlot(input)) return 0;
+  return input.priorityExecutionSlots === 2 ? 2 : 1;
+}

package/dist/bundling-sources/shared_libs/monitors/provider-monitor-public-aliases.ts

@@ -0,0 +1,28 @@
+import {
+  ANALYTICS_INTEGRATION_SLUG,
+  ANALYTICS_PUBLIC_PROVIDER,
+  ANALYTICS_PUBLIC_TOOL,
+} from '@/lib/analytics/public';
+
+export const ANALYTICS_MONITOR_KEY = ANALYTICS_INTEGRATION_SLUG;
+export const ANALYTICS_INTERNAL_MONITOR_KEY = 'snitcher-website-sessions';
+export const ANALYTICS_INTERNAL_TOOL = 'snitcher.website_sessions';
+
+export function canonicalProviderMonitorKey(key: string) {
+  return key === ANALYTICS_MONITOR_KEY ? ANALYTICS_INTERNAL_MONITOR_KEY : key;
+}
+
+/** Convert a customer-facing monitor tool id to its internal registry id. */
+export function canonicalProviderMonitorTool(tool: string) {
+  return tool === ANALYTICS_PUBLIC_TOOL ? ANALYTICS_INTERNAL_TOOL : tool;
+}
+
+/** Convert an internal registry id to the stable customer-facing tool id. */
+export function publicProviderMonitorTool(tool: string) {
+  return tool === ANALYTICS_INTERNAL_TOOL ? ANALYTICS_PUBLIC_TOOL : tool;
+}
+
+/** Convert an internal provider name to the stable customer-facing name. */
+export function publicProviderMonitorProvider(provider: string) {
+  return provider === 'snitcher' ? ANALYTICS_PUBLIC_PROVIDER : provider;
+}

package/dist/bundling-sources/shared_libs/monitors/provider-monitor-runtime-read-eligibility.ts

@@ -0,0 +1,38 @@
+type ProviderMonitorCallbackRuntimeRow = {
+  status: string;
+  billing_state: unknown;
+};
+
+function billingStateKind(value: unknown) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  const state = (value as Record<string, unknown>).state;
+  return typeof state === 'string' && state.trim() ? state.trim() : null;
+}
+
+/** True when an admitted callback is allowed to write an event for this monitor. */
+export function isProviderMonitorCallbackWriteEnabled(
+  row: Pick<ProviderMonitorCallbackRuntimeRow, 'status'>,
+) {
+  return row.status === 'active';
+}
+
+/**
+ * Matches the Customer DB callback lookup predicate for a row that has already
+ * been selected from the Convex callback-token projection.
+ */
+export function isProviderMonitorCallbackRuntimeEligible(
+  row: ProviderMonitorCallbackRuntimeRow,
+) {
+  if (isProviderMonitorCallbackWriteEnabled(row)) {
+    return true;
+  }
+  return (
+    row.status === 'disabled' &&
+    (billingStateKind(row.billing_state) === 'upstream_disable_pending' ||
+      billingStateKind(row.billing_state) === 'upstream_disable_failed' ||
+      // A credit suspension turns the provider resource off but does not turn
+      // off receipt capture. The inbound processor stores raw provenance and
+      // returns its explicit billing-suspended outcome without typed writes.
+      billingStateKind(row.billing_state) === 'billing_suspended')
+  );
+}