deepline 0.3.88 → 0.3.90

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

@@ -0,0 +1,122 @@
+/**
+ * The customer-visible state of a monitor. Provider work and audit evidence
+ * intentionally live on separate axes; neither may add a third value here.
+ */
+export type ProviderMonitorState = 'active' | 'inactive';
+
+declare const providerMonitorResourceIdBrand: unique symbol;
+
+/**
+ * A non-empty provider-owned resource handle.  This deliberately says
+ * nothing about the provider or its wire format: an adapter is the only
+ * layer that knows whether this happens to be a radar, subscription, etc.
+ */
+export type ProviderMonitorResourceId = string & {
+  readonly [providerMonitorResourceIdBrand]: 'ProviderMonitorResourceId';
+};
+
+/** Turn untrusted storage/API input into the proof used by active state. */
+export function providerMonitorResourceId(
+  value: string | null | undefined,
+): ProviderMonitorResourceId | null {
+  const normalized = typeof value === 'string' ? value.trim() : '';
+  return normalized === '' ? null : (normalized as ProviderMonitorResourceId);
+}
+
+/**
+ * A provider-neutral proof that this control record has an upstream
+ * counterpart. The identifier might be a radar id today and a different
+ * provider's resource id tomorrow; callers outside an adapter must never need
+ * to know which.
+ */
+export type ProviderMonitorResourceBinding =
+  | { kind: 'bound'; providerResourceId: ProviderMonitorResourceId }
+  | { kind: 'unbound'; providerResourceId: null };
+
+/**
+ * The state safe to show as a monitor's current operational state.
+ *
+ * An active intent without a resource is valid *work* (a create is pending or
+ * a historical record needs repair), but it is not an active monitor. The
+ * discriminated `active` branch therefore proves a non-empty provider id to
+ * TypeScript at every API/worker boundary that administers a live resource.
+ */
+export type OperationalProviderMonitorState =
+  | {
+      state: 'active';
+      desired: 'active';
+      providerResourceId: ProviderMonitorResourceId;
+      binding: 'bound';
+    }
+  | {
+      state: 'inactive';
+      desired: ProviderMonitorState;
+      providerResourceId: string | null;
+      binding: 'bound' | 'unbound';
+    };
+
+export type ActiveOperationalProviderMonitorState = Extract<
+  OperationalProviderMonitorState,
+  { state: 'active' }
+>;
+
+export function providerMonitorOperationalState(input: {
+  desired: ProviderMonitorState;
+  providerResourceId: string | null | undefined;
+}): OperationalProviderMonitorState {
+  const providerResourceId = providerMonitorResourceId(input.providerResourceId);
+  if (input.desired === 'active' && providerResourceId !== null) {
+    return {
+      state: 'active',
+      desired: 'active',
+      providerResourceId,
+      binding: 'bound',
+    };
+  }
+  return {
+    state: 'inactive',
+    desired: input.desired,
+    providerResourceId,
+    binding: providerResourceId === null ? 'unbound' : 'bound',
+  };
+}
+
+/**
+ * Runtime boundary for code that is about to publish or administer an active
+ * resource. Its return type is the same proof exposed to callers: an active
+ * record necessarily has a non-empty, provider-neutral resource id.
+ */
+export function requireActiveProviderMonitorBinding(input: {
+  providerResourceId: string | null | undefined;
+}): ActiveOperationalProviderMonitorState {
+  const operational = providerMonitorOperationalState({
+    desired: 'active',
+    providerResourceId: input.providerResourceId,
+  });
+  if (operational.state !== 'active') {
+    throw new Error(
+      'An active provider monitor requires a non-empty provider resource id. Keep it pending until upstream provisioning returns one.',
+    );
+  }
+  return operational;
+}
+
+/**
+ * Translate the historical control-record lifecycle label at the sole
+ * compatibility boundary. New code persists `desired` and returns this type;
+ * this mapping exists only while the online backfill drains existing rows.
+ */
+export function providerMonitorStateForLegacyStatus(
+  status: string | undefined,
+): ProviderMonitorState {
+  switch (status) {
+    case 'active':
+    case 'pending_create':
+    case 'replacement_pending':
+    case 'replacement_active_old_cleanup_pending':
+    case 'replacement_cleanup_failed':
+      return 'active';
+    default:
+      return 'inactive';
+  }
+}

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

@@ -0,0 +1,10 @@
+export type ProviderMonitorStatus =
+  | 'replacement_pending'
+  | 'replacement_active_old_cleanup_pending'
+  | 'replacement_cleanup_failed'
+  | 'active'
+  | 'disabled'
+  | 'deleted'
+  | 'deleting'
+  | 'error'
+  | 'pending_create';

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

@@ -0,0 +1,112 @@
+// Convex-safe provider monitor identity contract.
+//
+// This deliberately contains only declarative identity metadata and pure
+// normalization. Convex claim mutations import it directly, so it must not
+// pull in the Node-only provider registry, generated OpenAPI loaders, or any
+// deployment runtime. A monitor provider adds its account-unique identity here
+// and declares the same fields on its capability; registry validation keeps the
+// two declarations aligned.
+
+export type ProviderMonitorUpstreamIdentityValue = string | null;
+
+export type ProviderMonitorUpstreamIdentitySignature = {
+  tool: string;
+  key: Record<string, ProviderMonitorUpstreamIdentityValue>;
+};
+
+type ProviderMonitorUpstreamIdentityField = {
+  name: string;
+  // A provider runtime payload can use its upstream request name while the
+  // public monitor definition uses a clearer field name. Identity backfills
+  // use this declarative alias rather than provider-specific conditionals.
+  runtimePayloadAliases?: readonly string[];
+};
+
+const PROVIDER_MONITOR_UPSTREAM_IDENTITY_FIELDS = {
+  'deepline_native.company_radar': [{ name: 'radar_type' }, { name: 'domain' }],
+  'deepline_native.contact_radar': [
+    { name: 'radar_type' },
+    { name: 'profile_url' },
+  ],
+  'deepline_native.industry_radar': [
+    { name: 'radar_type' },
+    { name: 'industry', runtimePayloadAliases: ['keyword'] },
+  ],
+} as const satisfies Record<
+  string,
+  readonly ProviderMonitorUpstreamIdentityField[]
+>;
+
+function canonicalMonitorTool(tool: string) {
+  // Public TamRadar ids existed before the deepline_native hard cutover. Keep
+  // their legacy control records in the same claim namespace during migration.
+  return tool.startsWith('tamradar.')
+    ? `deepline_native.${tool.slice('tamradar.'.length)}`
+    : tool;
+}
+
+function stableJson(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(',')}]`;
+  if (value && typeof value === 'object') {
+    const entries = Object.entries(value as Record<string, unknown>)
+      .filter(([, entry]) => entry !== undefined)
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([key, entry]) => `${JSON.stringify(key)}:${stableJson(entry)}`);
+    return `{${entries.join(',')}}`;
+  }
+  return JSON.stringify(value) ?? 'null';
+}
+
+export function normalizeProviderMonitorUpstreamIdentityValue(
+  value: unknown,
+): ProviderMonitorUpstreamIdentityValue {
+  if (value === null || value === undefined) return null;
+  if (typeof value === 'string') {
+    const normalized = value.trim().toLowerCase();
+    return normalized || null;
+  }
+  if (typeof value === 'number' || typeof value === 'boolean') {
+    return String(value);
+  }
+  if (Array.isArray(value)) {
+    const normalized = value
+      .map(normalizeProviderMonitorUpstreamIdentityValue)
+      .filter((entry): entry is string => entry !== null)
+      .sort();
+    return normalized.length ? normalized.join(',') : null;
+  }
+  return stableJson(value).toLowerCase();
+}
+
+export function providerMonitorUpstreamIdentityFields(tool: string) {
+  const canonical = canonicalMonitorTool(tool);
+  return PROVIDER_MONITOR_UPSTREAM_IDENTITY_FIELDS[
+    canonical as keyof typeof PROVIDER_MONITOR_UPSTREAM_IDENTITY_FIELDS
+  ]?.map((field) => field.name);
+}
+
+export function providerMonitorUpstreamIdentitySignature(
+  tool: string,
+  payload: Record<string, unknown> | null | undefined,
+): ProviderMonitorUpstreamIdentitySignature | null {
+  const canonical = canonicalMonitorTool(tool);
+  const fields =
+    PROVIDER_MONITOR_UPSTREAM_IDENTITY_FIELDS[
+      canonical as keyof typeof PROVIDER_MONITOR_UPSTREAM_IDENTITY_FIELDS
+    ];
+  if (!fields?.length) return null;
+  const key: Record<string, ProviderMonitorUpstreamIdentityValue> = {};
+  for (const field of fields) {
+    const aliases =
+      'runtimePayloadAliases' in field
+        ? field.runtimePayloadAliases
+        : undefined;
+    const value =
+      payload?.[field.name] ??
+      aliases
+        ?.map((alias) => payload?.[alias])
+        .find((aliasValue) => aliasValue !== undefined);
+    key[field.name] = normalizeProviderMonitorUpstreamIdentityValue(value);
+  }
+  return { tool: canonical, key };
+}

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

@@ -0,0 +1,300 @@
+import { randomBytes } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import type { ProviderMonitorCapabilityDefinition } from '@deepline/monitors/provider-monitor-capability';
+import {
+  createProviderCallbackSecret,
+  MONITOR_CALLBACK_SECRET_HEADER,
+} from '@deepline/monitors/provider-callback-verification';
+
+type ProviderMonitorDefinitionLike = {
+  key: string;
+  name?: string;
+  payload?: Record<string, unknown>;
+};
+
+const DEFAULT_MONITOR_CALLBACK_BASE_URL = 'http://localhost:3000';
+const DEFAULT_PREVIEW_CALLBACK_URL_FILE =
+  '.cache/dev/plays-preview-callback-url';
+
+function readRecord(value: unknown): Record<string, unknown> {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+function readString(value: unknown) {
+  if (typeof value === 'number' && Number.isFinite(value)) return String(value);
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  return trimmed || null;
+}
+
+function firstString(...values: unknown[]) {
+  for (const value of values) {
+    const string = readString(value);
+    if (string) return string;
+  }
+  return null;
+}
+
+function isAbsoluteFilePath(value: string) {
+  return value.startsWith('/') || /^[a-zA-Z]:[\\/]/.test(value);
+}
+
+function cwdRelativePath(value: string) {
+  return isAbsoluteFilePath(value) ? value : `${process.cwd()}/${value}`;
+}
+
+function readPreviewCallbackUrlFile(
+  environment: NodeJS.ProcessEnv = process.env,
+) {
+  const configuredPath = environment.DEEPLINE_PREVIEW_CALLBACK_URL_FILE?.trim();
+  const filePath = cwdRelativePath(
+    configuredPath || DEFAULT_PREVIEW_CALLBACK_URL_FILE,
+  );
+  try {
+    if (!existsSync(filePath)) return null;
+    return readString(readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function readStringArray(value: unknown) {
+  if (!Array.isArray(value)) return [];
+  return value
+    .map((item) => readString(item))
+    .filter((item): item is string => Boolean(item));
+}
+
+function readNumberArray(value: unknown) {
+  if (!Array.isArray(value)) return [];
+  return value.filter(
+    (item): item is number =>
+      typeof item === 'number' && Number.isInteger(item),
+  );
+}
+
+function boundedName(value: string, maxLength: number) {
+  const normalized = value.replace(/\s+/g, ' ').trim();
+  if (normalized.length <= maxLength) return normalized;
+  return normalized.slice(0, maxLength).trim();
+}
+
+function managedWebhookName(input: {
+  definition: ProviderMonitorDefinitionLike;
+  provider: string;
+  maxLength?: number;
+}) {
+  const source = input.definition.name ?? input.definition.key;
+  const name = `Deepline ${input.provider} ${source}`;
+  return boundedName(name, input.maxLength ?? 80);
+}
+
+/**
+ * Resolve the externally reachable origin for provider callbacks and durable
+ * workers. Local Convex actions need the preview tunnel, not a loopback URL.
+ */
+export function resolveProviderMonitorCallbackBaseUrl(
+  explicit?: string | null,
+  environment: NodeJS.ProcessEnv = process.env,
+) {
+  const baseUrl =
+    explicit ||
+    environment.DEEPLINE_WORKER_CALLBACK_URL ||
+    readPreviewCallbackUrlFile(environment) ||
+    environment.WORKTREE_PUBLIC_APP_URL ||
+    environment.DEEPLINE_API_BASE_URL ||
+    environment.NEXT_PUBLIC_APP_URL ||
+    environment.APP_URL ||
+    environment.VERCEL_URL ||
+    DEFAULT_MONITOR_CALLBACK_BASE_URL;
+  return baseUrl.startsWith('http') ? baseUrl : `https://${baseUrl}`;
+}
+
+export function createProviderWebhookCallbackToken() {
+  return randomBytes(32).toString('hex');
+}
+
+export function providerWebhookCallbackPath(input: {
+  provider: string;
+  orgId: string;
+  token: string;
+}) {
+  return `/api/v2/monitors/provider-callbacks/webhook/${encodeURIComponent(
+    input.provider,
+  )}/${encodeURIComponent(input.orgId)}/${encodeURIComponent(input.token)}`;
+}
+
+export function buildProviderWebhookCallbackUrl(input: {
+  provider: string;
+  orgId: string;
+  token: string;
+  callbackBaseUrl?: string | null;
+}) {
+  const baseUrl = resolveProviderMonitorCallbackBaseUrl(input.callbackBaseUrl);
+  if (input.provider === 'snitcher') {
+    return `${baseUrl.replace(/\/$/, '')}/api/v2/monitors/provider-callbacks/deepline-analytics`;
+  }
+  return `${baseUrl.replace(/\/$/, '')}${providerWebhookCallbackPath(input)}`;
+}
+
+export function readProviderWebhookCallbackUrl(
+  payload: Record<string, unknown>,
+) {
+  const webhook = readRecord(payload.webhook);
+  return firstString(
+    payload.target_url,
+    payload.target_hook_url,
+    payload.webhook_url,
+    webhook.webhook_url,
+  );
+}
+
+export function extractProviderWebhookId(raw: unknown) {
+  const root = readRecord(raw);
+  const data = readRecord(root.data);
+  const result = readRecord(root.result);
+  const resultData = readRecord(result.data);
+  const webhook = readRecord(root.webhook);
+  const dataWebhook = readRecord(data.webhook);
+  const id = readRecord(root.id);
+  const dataId = readRecord(data.id);
+  const resultDataId = readRecord(resultData.id);
+  return firstString(
+    root.webhook_id,
+    root.webhookId,
+    root.hook_id,
+    root.hookId,
+    root.id,
+    root._id,
+    data.webhook_id,
+    data.webhookId,
+    data.hook_id,
+    data.hookId,
+    data.id,
+    data._id,
+    result.webhook_id,
+    result.webhookId,
+    result.hook_id,
+    result.hookId,
+    result.id,
+    result._id,
+    resultData.webhook_id,
+    resultData.webhookId,
+    resultData.hook_id,
+    resultData.hookId,
+    resultData.id,
+    resultData._id,
+    webhook.webhook_id,
+    webhook.id,
+    dataWebhook.webhook_id,
+    dataWebhook.id,
+    id.webhook_id,
+    dataId.webhook_id,
+    resultDataId.webhook_id,
+  );
+}
+
+export function buildProviderWebhookRuntimePayload(input: {
+  definition: ProviderMonitorDefinitionLike;
+  capability: ProviderMonitorCapabilityDefinition;
+  callbackUrl: string;
+}) {
+  const payload = input.definition.payload ?? {};
+  const provider = input.capability.provider;
+  switch (provider) {
+    case 'attio':
+      return {
+        target_url: input.callbackUrl,
+        subscriptions: readStringArray(payload.event_types).map(
+          (eventType) => ({
+            event_type: eventType,
+          }),
+        ),
+      };
+    case 'lemlist':
+      return {
+        target_url: input.callbackUrl,
+        type: readString(payload.event_type),
+        secret: createProviderCallbackSecret('lemlist'),
+        ...(readString(payload.campaign_id)
+          ? { campaign_id: readString(payload.campaign_id) }
+          : {}),
+      };
+    case 'instantly':
+      return {
+        target_hook_url: input.callbackUrl,
+        event_type: readString(payload.event_type),
+        headers: {
+          [MONITOR_CALLBACK_SECRET_HEADER]:
+            createProviderCallbackSecret('instantly'),
+        },
+        name: managedWebhookName({
+          definition: input.definition,
+          provider,
+        }),
+        ...(readString(payload.campaign_id)
+          ? { campaign: readString(payload.campaign_id) }
+          : {}),
+      };
+    case 'smartlead':
+      return {
+        campaign_id: payload.campaign_id,
+        webhook: {
+          id: null,
+          name: managedWebhookName({
+            definition: input.definition,
+            provider,
+          }),
+          webhook_url: input.callbackUrl,
+          event_types: readStringArray(payload.event_types),
+          ...(readStringArray(payload.categories).length
+            ? { categories: readStringArray(payload.categories) }
+            : {}),
+        },
+      };
+    case 'heyreach':
+      return {
+        webhook_name: managedWebhookName({
+          definition: input.definition,
+          provider,
+          maxLength: 25,
+        }),
+        webhook_url: input.callbackUrl,
+        event_type: readString(payload.event_type),
+        ...(readNumberArray(payload.campaign_ids).length
+          ? { campaign_ids: readNumberArray(payload.campaign_ids) }
+          : {}),
+      };
+    case 'vector':
+      // Vector's dashboard owns the webhook resource. This payload is durable
+      // setup evidence, not an upstream API request.
+      return {
+        callback_url: input.callbackUrl,
+        event_type: 'contact.visited',
+      };
+    case 'rb2b':
+      // RB2B's dashboard owns the single webhook connection. This payload is
+      // durable setup evidence, not an upstream API request.
+      return {
+        callback_url: input.callbackUrl,
+      };
+    case 'snitcher':
+      // Radar is configured at the operator level. The callback URL is durable
+      // evidence of the Deepline-owned receiver; the setup API creates the
+      // customer tracker and configures session delivery upstream.
+      return {
+        callback_url: input.callbackUrl,
+        domains: readStringArray(payload.domains),
+        form_tracking: payload.formTracking === true,
+        click_tracking: payload.clickTracking === true,
+        custom_events: payload.customEvents !== false,
+        wait_for_consent: payload.waitForConsent !== false,
+      };
+    default:
+      throw new Error(
+        `Provider webhook monitor payload builder is not implemented for ${provider}.`,
+      );
+  }
+}

package/dist/bundling-sources/shared_libs/monitors/quickstart-prompts.ts

@@ -0,0 +1,22 @@
+export type MonitorQuickstartPrompt = {
+  prompt: string;
+  icon: 'job-change' | 'new-hires' | 'hiring-signal';
+};
+
+export const MONITOR_QUICKSTART_PROMPTS: MonitorQuickstartPrompt[] = [
+  {
+    prompt:
+      '/deepline-gtm Monitor my target accounts for new VP Sales, Marketing, and Revenue hires.',
+    icon: 'new-hires',
+  },
+  {
+    prompt:
+      '/deepline-gtm Monitor when people at my target accounts change jobs.',
+    icon: 'job-change',
+  },
+  {
+    prompt:
+      '/deepline-gtm Monitor my target accounts for job openings in the roles I sell to.',
+    icon: 'hiring-signal',
+  },
+];