deepline 0.3.85 → 0.3.87

package/dist/bundling-sources/shared_libs/monitors/tracking-provider-guidance.ts

@@ -0,0 +1,73 @@
+import type { ProviderMonitorPostDeployGuidance } from '@deepline/monitors/provider-monitor-capability';
+
+// Client-safe provider setup metadata. Provider monitor definitions reference
+// these exact objects, while the integrations dialog reads them directly.
+export const VECTOR_POST_DEPLOY_GUIDANCE = {
+  title: 'Connect Vector to this monitor',
+  steps: [
+    'In Vector, open the segment named in this monitor setup.',
+    'Add a webhook endpoint using {{callback_url}}, then select contact.visited.',
+    'Enable the webhook action on the segment and send a Vector test event.',
+  ],
+  event_type: 'contact.visited',
+  documentation: [
+    {
+      label: 'Vector SiteID action integration guide',
+      url: 'https://learn.vector.co/articles/2260541690-building-an-action-integration-for-siteid',
+    },
+  ],
+  payload_example: {
+    type: 'contact.visited',
+    externalId: 'contact_123',
+    companyDomain: 'example.com',
+  },
+} as const satisfies ProviderMonitorPostDeployGuidance;
+
+export const RB2B_POST_DEPLOY_GUIDANCE = {
+  title: 'Connect RB2B to this monitor',
+  steps: [
+    'In RB2B, open Integrations and choose Webhook.',
+    'Paste {{callback_url}} as the single webhook URL and save.',
+    "Use RB2B's Send a Test Event action to verify the connection.",
+  ],
+  documentation: [
+    {
+      label: 'RB2B webhook setup guide',
+      url: 'https://support.rb2b.com/en/articles/8976614-setup-guide-webhook',
+    },
+  ],
+  payload_example: {
+    'LinkedIn URL': 'https://www.linkedin.com/in/example',
+    Website: 'https://example.com',
+  },
+} as const satisfies ProviderMonitorPostDeployGuidance;
+
+export const SNITCHER_POST_DEPLOY_GUIDANCE = {
+  title: 'Install Deepline Analytics',
+  steps: [
+    'Create the tracker code in Deepline, then paste it in your site’s document head.',
+    'Confirm cookie consent before persistent tracking when your privacy policy requires it.',
+  ],
+  documentation: [
+    {
+      label: 'Deepline Analytics setup guide',
+      url: 'https://docs.snitcher.com/powered-by-snitcher/radar/installation',
+    },
+  ],
+  payload_example: {
+    session_uuid: '00000000-0000-4000-8000-000000000001',
+    start_time: '2026-01-01T00:00:00.000Z',
+    last_activity: '2026-01-01T00:01:00.000Z',
+    engagement_time: 60,
+    user_properties: { $uuid: 'deepline-test-visitor' },
+    events: [
+      { event_name: '$pageview', created_at: '2026-01-01T00:00:00.000Z' },
+    ],
+  },
+} as const satisfies ProviderMonitorPostDeployGuidance;
+
+export const TRACKING_PROVIDER_POST_DEPLOY_GUIDANCE = {
+  vector: VECTOR_POST_DEPLOY_GUIDANCE,
+  rb2b: RB2B_POST_DEPLOY_GUIDANCE,
+  snitcher: SNITCHER_POST_DEPLOY_GUIDANCE,
+} as const;

package/dist/bundling-sources/shared_libs/monitors/tracking-provider-integrations.ts

@@ -0,0 +1,81 @@
+import { TRACKING_PROVIDER_POST_DEPLOY_GUIDANCE } from '@deepline/monitors/tracking-provider-guidance';
+import {
+  ANALYTICS_INTEGRATION_SLUG,
+  ANALYTICS_PUBLIC_TOOL,
+} from '@/lib/analytics/public';
+
+export const TRACKING_PROVIDER_INTEGRATIONS = {
+  vector: {
+    provider: 'vector',
+    displayName: 'Vector',
+    tool: 'vector.visitor_events',
+    monitorKey: 'vector-high-intent-visitors',
+  },
+  rb2b: {
+    provider: 'rb2b',
+    displayName: 'RB2B',
+    tool: 'rb2b.visitor_events',
+    monitorKey: 'rb2b-website-visitors',
+  },
+  [ANALYTICS_INTEGRATION_SLUG]: {
+    provider: 'snitcher',
+    displayName: 'Deepline Analytics',
+    // Used only by the server-side monitor adapter to resolve upstream wiring.
+    tool: 'snitcher.website_sessions',
+    publicTool: ANALYTICS_PUBLIC_TOOL,
+    monitorKey: 'snitcher-website-sessions',
+  },
+} as const;
+
+export type TrackingProviderIntegration =
+  (typeof TRACKING_PROVIDER_INTEGRATIONS)[keyof typeof TRACKING_PROVIDER_INTEGRATIONS] & {
+    docsUrl: string;
+    docsLabel: string;
+  };
+
+export function getTrackingProviderIntegration(
+  provider: string,
+): TrackingProviderIntegration | null {
+  const integration =
+    TRACKING_PROVIDER_INTEGRATIONS[
+      provider as keyof typeof TRACKING_PROVIDER_INTEGRATIONS
+    ];
+  if (!integration) return null;
+  const docs =
+    TRACKING_PROVIDER_POST_DEPLOY_GUIDANCE[
+      integration.provider as keyof typeof TRACKING_PROVIDER_POST_DEPLOY_GUIDANCE
+    ]?.documentation[0];
+  if (!docs) return null;
+  return { ...integration, docsUrl: docs.url, docsLabel: docs.label };
+}
+
+export function trackingProviderWebhookSetup(
+  provider: string,
+  webhookEndpoint: string,
+): {
+  webhook_endpoint: string;
+  event_type?: 'contact.visited';
+  instructions: string[];
+} | null {
+  const integration = getTrackingProviderIntegration(
+    provider === 'snitcher' ? ANALYTICS_INTEGRATION_SLUG : provider,
+  );
+  const guidance = integration
+    ? TRACKING_PROVIDER_POST_DEPLOY_GUIDANCE[
+        integration.provider as keyof typeof TRACKING_PROVIDER_POST_DEPLOY_GUIDANCE
+      ]
+    : null;
+  if (!guidance) return null;
+  return {
+    webhook_endpoint: webhookEndpoint,
+    ...('event_type' in guidance && guidance.event_type === 'contact.visited'
+      ? { event_type: guidance.event_type }
+      : {}),
+    // The dialog shows the URL in a dedicated copy target, so retain its
+    // compact `webhook_endpoint` wording while deriving every step from the
+    // same metadata used by CLI/API guidance.
+    instructions: guidance.steps.map((step) =>
+      step.replaceAll('{{callback_url}}', 'webhook_endpoint'),
+    ),
+  };
+}

package/dist/bundling-sources/shared_libs/monitors/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "incremental": false,
+    "noEmit": true,
+    "types": ["node"]
+  },
+  "include": ["./**/*.ts"],
+  "exclude": ["node_modules"]
+}

package/dist/bundling-sources/shared_libs/play-runtime/runtime-env.ts

@@ -53,3 +53,9 @@ export function getRuntimeEnvInfo() {
     node_env: process.env.NODE_ENV ?? null,
   };
 }
+
+/** Test seams must never be reachable from a Vercel production deployment. */
+export function isTestOnlyRuntime(): boolean {
+  if (process.env.VERCEL_ENV === 'production') return false;
+  return process.env.VERCEL_ENV === 'preview' || getRuntimeEnv() !== 'prod';
+}

package/dist/bundling-sources/shared_libs/play-runtime/tool-http-errors.ts

@@ -186,7 +186,7 @@ function isInsufficientCreditsBilling(
  * credit/cap denial: a funded org is temporarily blocked because our billing
  * store hiccuped, so it must be repairable on the next run rather than cached as
  * a terminal failure. See `billingUnavailableResponse` in
- * src/lib/integrations/execute-billing.ts. This class is the exact incident
+ * packages/integrations/execute-billing.ts. This class is the exact incident
  * poison closed by issues #2561/#2706: without this carve-out a billing-plane
  * outage classifies every affected tool call as `hard_billing_error` ->
  * `terminal` and the next run replays the cached failure instead of retrying.

package/dist/bundling-sources/shared_libs/play-runtime/tool-result.ts

@@ -206,7 +206,7 @@ function adaptV2ExecuteResponseToToolResult(data: Record<string, unknown>): {
  *
  * Boundary note: provider-specific redaction (wiza/apify/bettercontact billing
  * fields) happens server-side in
- * `src/lib/integrations/execute-result-normalization.ts` BEFORE the response
+ * `packages/integrations/execute-result-normalization.ts` BEFORE the response
  * leaves the API. This module only ever sees the already-redacted public
  * response — do not move redaction here, it would leak provider internals
  * into the shared runtime bundles.

package/dist/bundling-sources/shared_libs/plays/authoring-contract.ts

@@ -276,6 +276,308 @@ export function normalizeAdmittedSqlListenerWhere(
   }
   return normalized;
 }
+export type PlaySqlListenerValidationIssue = {
+  severity: 'error' | 'warning';
+  code: string;
+  path: string;
+  message: string;
+  expected?: unknown;
+  received?: unknown;
+  suggestion?: string;
+  entity_type?:
+    | 'monitor'
+    | 'action'
+    | 'trigger'
+    | 'bundle'
+    | 'play'
+    | 'listener'
+    | 'table'
+    | 'tool'
+    | 'workflow';
+  entity_key?: string;
+  docs_ref?: string;
+};
+
+function sqlListenerIssue(
+  issue: Omit<PlaySqlListenerValidationIssue, 'severity'> & {
+    severity?: PlaySqlListenerValidationIssue['severity'];
+  },
+): PlaySqlListenerValidationIssue {
+  return { severity: issue.severity ?? 'error', ...issue };
+}
+
+const PLAY_SQL_LISTENER_OPERATIONS = new Set<string>([
+  'INSERT',
+  'UPDATE',
+  'DELETE',
+]);
+
+function validateAdmittedSqlListenerWhere(
+  input: { where: unknown; path: string; listenerKey: string },
+  issues: PlaySqlListenerValidationIssue[],
+): void {
+  if (input.where === undefined) return;
+  if (!isPlainRecord(input.where)) {
+    issues.push(
+      sqlListenerIssue({
+        code: 'invalid_sql_listener_filter_shape',
+        path: input.path,
+        message:
+          'SQL listener where must be a literal object with before and/or after filters.',
+        expected:
+          '{ before?: Record<string, operators>, after?: Record<string, operators> }',
+        received: input.where,
+        entity_type: 'listener',
+        entity_key: input.listenerKey,
+        docs_ref: 'docs/monitor-sdk-architecture-plan.html#v2',
+      }),
+    );
+    return;
+  }
+  for (const [scope, scopeValue] of Object.entries(input.where)) {
+    const scopePath = `${input.path}.${scope}`;
+    if (scope !== 'before' && scope !== 'after') {
+      issues.push(
+        sqlListenerIssue({
+          code: 'unsupported_sql_listener_filter_scope',
+          path: scopePath,
+          message: 'SQL listener filters only support before and after scopes.',
+          expected: ['before', 'after'],
+          received: scope,
+          entity_type: 'listener',
+          entity_key: input.listenerKey,
+          docs_ref: 'docs/monitor-sdk-architecture-plan.html#v2',
+        }),
+      );
+      continue;
+    }
+    if (!isPlainRecord(scopeValue)) {
+      issues.push(
+        sqlListenerIssue({
+          code: 'invalid_sql_listener_filter_scope',
+          path: scopePath,
+          message: `SQL listener where.${scope} must be an object keyed by top-level row field.`,
+          expected: 'Record<field, operators>',
+          received: scopeValue,
+          entity_type: 'listener',
+          entity_key: input.listenerKey,
+          docs_ref: 'docs/monitor-sdk-architecture-plan.html#v2',
+        }),
+      );
+      continue;
+    }
+    for (const [field, operators] of Object.entries(scopeValue)) {
+      const fieldPath = `${scopePath}.${field}`;
+      if (!PLAY_SQL_LISTENER_FIELD_PATTERN.test(field)) {
+        issues.push(
+          sqlListenerIssue({
+            code: 'invalid_sql_listener_filter_field',
+            path: fieldPath,
+            message:
+              'SQL listener filters only support top-level row fields with plain identifier names.',
+            expected: PLAY_SQL_LISTENER_FIELD_PATTERN.source,
+            received: field,
+            suggestion:
+              'Use a top-level column key such as "country" instead of a path expression.',
+            entity_type: 'listener',
+            entity_key: input.listenerKey,
+            docs_ref: 'docs/monitor-sdk-architecture-plan.html#v2',
+          }),
+        );
+      }
+      if (!isPlainRecord(operators)) {
+        issues.push(
+          sqlListenerIssue({
+            code: 'invalid_sql_listener_filter_condition',
+            path: fieldPath,
+            message:
+              'SQL listener field filters must be an object keyed by a supported operator, e.g. { eq: <value> } — got a bare value.',
+            expected: PLAY_SQL_LISTENER_WHERE_OPERATORS,
+            received: operators,
+            entity_type: 'listener',
+            entity_key: input.listenerKey,
+            docs_ref: 'docs/monitor-sdk-architecture-plan.html#v2',
+          }),
+        );
+        continue;
+      }
+      if (Object.keys(operators).length === 0) {
+        issues.push(
+          sqlListenerIssue({
+            code: 'empty_sql_listener_filter_condition',
+            path: fieldPath,
+            message:
+              'SQL listener field filters must contain at least one operator.',
+            expected: PLAY_SQL_LISTENER_WHERE_OPERATORS,
+            received: operators,
+            entity_type: 'listener',
+            entity_key: input.listenerKey,
+            docs_ref: 'docs/monitor-sdk-architecture-plan.html#v2',
+          }),
+        );
+      }
+      for (const [operator, value] of Object.entries(operators)) {
+        const operatorPath = `${fieldPath}.${operator}`;
+        if (!PLAY_SQL_LISTENER_WHERE_OPERATOR_SET.has(operator)) {
+          issues.push(
+            sqlListenerIssue({
+              code: 'unsupported_sql_listener_filter_operator',
+              path: operatorPath,
+              message: `SQL listener filter operator "${operator}" is not supported.`,
+              expected: PLAY_SQL_LISTENER_WHERE_OPERATORS,
+              received: operator,
+              suggestion: `Use ${PLAY_SQL_LISTENER_WHERE_OPERATORS.slice(0, -1).join(', ')}, or ${PLAY_SQL_LISTENER_WHERE_OPERATORS.at(-1)}.`,
+              entity_type: 'listener',
+              entity_key: input.listenerKey,
+              docs_ref: 'docs/monitor-sdk-architecture-plan.html#v2',
+            }),
+          );
+          continue;
+        }
+        const valid =
+          ((operator === 'in' || operator === 'notIn') &&
+            Array.isArray(value) &&
+            value.length > 0 &&
+            value.every(isPlaySqlListenerFilterScalar)) ||
+          ((operator === 'isNull' || operator === 'isNotNull') &&
+            value === true) ||
+          (operator === 'ilike' &&
+            typeof value === 'string' &&
+            value.length > 0) ||
+          ((operator === 'eq' || operator === 'neq') &&
+            isPlaySqlListenerFilterScalar(value));
+        if (!valid) {
+          issues.push(
+            sqlListenerIssue({
+              code: 'invalid_sql_listener_filter_value',
+              path: operatorPath,
+              message: `SQL listener filter operator "${operator}" has an invalid value.`,
+              received: value,
+              entity_type: 'listener',
+              entity_key: input.listenerKey,
+              docs_ref: 'docs/monitor-sdk-architecture-plan.html#v2',
+            }),
+          );
+        }
+      }
+    }
+  }
+}
+
+/** Validate only a stored binding snapshot that already crossed admission. */
+export function validateAdmittedSqlListenerBindings(
+  bindings: PlayAuthoringAstBindings | null | undefined,
+  input: { playName?: string; pathPrefix?: string } = {},
+): PlaySqlListenerValidationIssue[] {
+  const issues: PlaySqlListenerValidationIssue[] = [];
+  const listeners = bindings?.sqlListeners;
+  if (!listeners) return issues;
+  const seen = new Set<string>();
+  listeners.forEach((listener, index) => {
+    const path = `${input.pathPrefix ?? 'sqlListeners'}[${index}]`;
+    const listenerKey = input.playName
+      ? `${input.playName}.${listener.id}`
+      : listener.id;
+    if (!listener.id || !PLAY_SQL_LISTENER_ID_PATTERN.test(listener.id)) {
+      issues.push(
+        sqlListenerIssue({
+          code: 'invalid_sql_listener_id',
+          path: `${path}.id`,
+          message:
+            'SQL listener id must start with a letter and contain only letters, numbers, underscores, or hyphens.',
+          expected: PLAY_SQL_LISTENER_ID_PATTERN.source,
+          received: listener.id,
+          entity_type: 'listener',
+          entity_key: listenerKey,
+        }),
+      );
+    }
+    if (seen.has(listener.id)) {
+      issues.push(
+        sqlListenerIssue({
+          code: 'duplicate_sql_listener_id',
+          path: `${path}.id`,
+          message: `SQL listener id "${listener.id}" is already used in this play.`,
+          received: listener.id,
+          entity_type: 'listener',
+          entity_key: listenerKey,
+        }),
+      );
+    }
+    seen.add(listener.id);
+    if (!listener.tool || !PLAY_SQL_LISTENER_TOOL_PATTERN.test(listener.tool)) {
+      issues.push(
+        sqlListenerIssue({
+          code: listener.tool
+            ? 'invalid_sql_listener_tool'
+            : 'missing_sql_listener_tool',
+          path: `${path}.tool`,
+          message: 'SQL listener tool must use provider.tool syntax.',
+          expected: PLAY_SQL_LISTENER_TOOL_PATTERN.source,
+          received: listener.tool,
+          entity_type: 'tool',
+          entity_key: listener.tool || listenerKey,
+        }),
+      );
+    }
+    if (
+      !listener.stream ||
+      !PLAY_SQL_LISTENER_ID_PATTERN.test(listener.stream)
+    ) {
+      issues.push(
+        sqlListenerIssue({
+          code: listener.stream
+            ? 'invalid_sql_listener_stream'
+            : 'missing_sql_listener_stream',
+          path: `${path}.stream`,
+          message:
+            'SQL listener stream keys must start with a letter and contain only letters, numbers, underscores, or hyphens.',
+          expected: PLAY_SQL_LISTENER_ID_PATTERN.source,
+          received: listener.stream,
+          entity_type: 'listener',
+          entity_key: listenerKey,
+        }),
+      );
+    }
+    validateAdmittedSqlListenerWhere(
+      { where: listener.where, path: `${path}.where`, listenerKey },
+      issues,
+    );
+    if (
+      !Array.isArray(listener.operations) ||
+      listener.operations.length === 0
+    ) {
+      issues.push(
+        sqlListenerIssue({
+          code: 'empty_sql_listener_operations',
+          path: `${path}.operations`,
+          message: 'SQL listener operations must not be empty.',
+          expected: [...PLAY_SQL_LISTENER_OPERATIONS],
+          received: listener.operations,
+          entity_type: 'listener',
+          entity_key: listenerKey,
+        }),
+      );
+    } else if (
+      listener.operations.some(
+        (operation) => !PLAY_SQL_LISTENER_OPERATIONS.has(operation),
+      )
+    ) {
+      issues.push(
+        sqlListenerIssue({
+          code: 'invalid_sql_listener_operation',
+          path: `${path}.operations`,
+          message: 'SQL listener operations must be INSERT, UPDATE, or DELETE.',
+          expected: [...PLAY_SQL_LISTENER_OPERATIONS],
+          received: listener.operations,
+          entity_type: 'listener',
+          entity_key: listenerKey,
+        }),
+      );
+    }
+  });
+  return issues;
+}
 export type PlaySqlListenerDeclaration = {
   id: string;
   tool: string;

package/dist/bundling-sources/shared_libs/plays/email-status.ts

@@ -91,7 +91,7 @@ export type EmailStatusBuildInput = {
 
 // There is intentionally NO shared default status map. Each provider must
 // declare its own `statusMap` / `rules` for the raw status strings it emits
-// (see the provider registries under src/lib/integrations/**). A coarse global
+// (see the provider registries under packages/integrations/**). A coarse global
 // map silently coerced provider-specific strings ("deliverable", "accept_all",
 // etc.) into canonical verdicts and let validators depend on guesses instead of
 // documented behavior. With it gone, an unmapped raw status falls through to

package/dist/bundling-sources/shared_libs/plays/tool-category-descriptions.ts

@@ -1,10 +1,10 @@
 // One-line definitions for the tool categories surfaced by `deepline tools list`.
 //
 // Tool categories are free-form strings that each provider tool declares in the
-// generated catalog (see `src/lib/integrations/**`), not a single closed enum.
+// generated catalog (see `packages/integrations/**`), not a single closed enum.
 // The canonical set of well-known category slugs lives next to this file in
 // `DEEPLINE_TOOL_CATEGORIES` (bootstrap-routes.ts) and in the richer
-// `IntegrationCatalogTag` enum (src/lib/integrations/catalog-tags.ts). This map
+// `IntegrationCatalogTag` enum (packages/integrations/catalog-tags.ts). This map
 // MUST track the categories that actually appear on live tools. The CLI derives
 // the category enumeration from the live catalog, so a new category slug shows
 // up automatically; only its human-readable definition comes from here. When a

package/dist/bundling-sources/shared_libs/runtime-env.ts

@@ -53,3 +53,9 @@ export function getRuntimeEnvInfo() {
     node_env: process.env.NODE_ENV ?? null,
   };
 }
+
+/** Test seams must never be reachable from a Vercel production deployment. */
+export function isTestOnlyRuntime(): boolean {
+  if (process.env.VERCEL_ENV === 'production') return false;
+  return process.env.VERCEL_ENV === 'preview' || getRuntimeEnv() !== 'prod';
+}

package/dist/bundling-sources/shared_libs/security/header-safe-env.ts

@@ -0,0 +1,28 @@
+/**
+ * Guards for env-derived secrets that are sent as HTTP header values.
+ *
+ * fetch() validates header values and may echo invalid raw values in its
+ * error. Validate secrets before constructing headers so failures identify
+ * the environment variable without leaking its contents.
+ */
+
+const HEADER_UNSAFE_CHAR_PATTERN = /[^\t\u0020-\u007e\u0080-\u00ff]/;
+
+export function isHeaderSafeValue(value: string): boolean {
+  return !HEADER_UNSAFE_CHAR_PATTERN.test(value);
+}
+
+export function assertHeaderSafeEnvValue(input: {
+  envVar: string;
+  value: string;
+}): string {
+  if (!isHeaderSafeValue(input.value)) {
+    throw new Error(
+      `Environment variable ${input.envVar} contains a character that is invalid in an HTTP header value ` +
+        `(typically an embedded newline from a multi-line paste). ` +
+        `Re-set ${input.envVar} as a single-line value. ` +
+        `The raw value is not echoed to avoid leaking a secret.`,
+    );
+  }
+  return input.value;
+}