deepline 0.3.88 → 0.3.89

package/dist/bundling-sources/sdk/src/client.ts

@@ -37,6 +37,13 @@ import { resolveConfig } from './config.js';
 import { DeeplineError } from './errors.js';
 import { HttpClient } from './http.js';
 import { PRODUCT_NOTIFICATION_SLACK_OAUTH_SCOPES } from '../../shared_libs/product-notifications/contract.js';
+import { normalizeProductNotificationEmail } from '../../shared_libs/product-notifications/configuration.js';
+import {
+  type ProductNotificationConfigurationChange,
+  type EffectiveProductNotificationDestination,
+  type EffectiveProductNotificationGroup,
+  type ProductNotificationGroupDraft,
+} from '../../shared_libs/product-notifications/configuration.js';
 import {
   STREAM_HEALTHY_CONNECTION_MS,
   isTransientPlayStreamError,
@@ -60,6 +67,7 @@ import type {
   PlayLiveEvent,
   PlayListItem,
   ProductNotificationSettings,
+  ProductNotificationConfigurationResponse,
   PlayDescription,
   StopPlayRunResult,
   StopAllPlayRunsResult,
@@ -88,11 +96,11 @@ import type { PlayStagedFileRef } from './plays/local-file-discovery.js';
 import type { PlayCompilerManifest } from '../../shared_libs/plays/compiler-manifest.js';
 import type { EnrichCompiledConfig } from './cli/enrich-play-compiler.js';
 import { RUNTIME_ENVIRONMENT_TOKEN_HEADER } from '../../shared_libs/play-runtime/coordinator-headers.js';
-import { resolveTheirstackClientTimeoutMs } from '../../shared_libs/integrations/theirstack-execution-policy.js';
+import { resolveTheirstackClientTimeoutMs } from '../../shared_libs/integration-contracts/theirstack/execution-policy.js';
 import {
   BETTERCONTACT_LAUNCHER_CLIENT_TIMEOUT_MS,
   usesExtendedBetterContactLauncherBudget,
-} from '../../shared_libs/integrations/bettercontact-execution-policy.js';
+} from '../../shared_libs/integration-contracts/bettercontact/execution-policy.js';
 import {
   normalizePlayRuntimeEnvironment,
   normalizePlayRuntimeNamespace,
@@ -124,6 +132,76 @@ export type UpdateNotificationInput =
   | { enabled: boolean }
   | ({ name: string; eventTypes: string[] } & SlackNotificationTarget);
 
+export type CreateNotificationGroupInput = {
+  name: string;
+  targets: string[];
+  legacyEvents?: string[];
+  dryRun?: boolean;
+};
+
+export type CreateNotificationGroupResult =
+  | {
+      mode: 'dry_run';
+      compatibilityMode: boolean;
+      name: string;
+      targets: string[];
+      legacyEvents: string[];
+    }
+  | { mode: 'legacy'; notification: unknown }
+  | {
+      mode: 'native';
+      groupKey: string;
+      targets: string[];
+      group: EffectiveProductNotificationGroup;
+      destinations: EffectiveProductNotificationDestination[];
+    };
+
+type ParsedNotificationGroupTarget =
+  | { kind: 'email'; email: string }
+  | { kind: 'slack'; channel: string }
+  | { kind: 'slack'; memberId: string };
+
+const MAX_NOTIFICATION_GROUP_CREATE_TARGETS = 50;
+
+function parseNotificationGroupTarget(
+  value: string,
+): ParsedNotificationGroupTarget {
+  const normalized = value.trim();
+  if (normalized.toLowerCase().startsWith('email:')) {
+    const email = normalizeProductNotificationEmail(normalized.slice(6));
+    if (!email) {
+      throw new Error(
+        `Invalid email notification target "${value}". Use --to email:name@example.com.`,
+      );
+    }
+    return { kind: 'email', email };
+  }
+  const slack = /^slack:(.+)$/i.exec(normalized)?.[1]?.trim();
+  if (!slack) {
+    const provider = normalized.split(':', 1)[0] || normalized;
+    throw new Error(
+      `Unsupported notification destination "${provider}". Use email: or slack:.`,
+    );
+  }
+  const member = /^member:([UW][A-Z0-9]{8,})$/i.exec(slack);
+  if (member?.[1]) {
+    return { kind: 'slack', memberId: member[1].toUpperCase() };
+  }
+  if (slack.toLowerCase().startsWith('member:')) {
+    throw new Error(
+      'Slack member IDs must look like slack:member:U0123456789.',
+    );
+  }
+  if (!slack.replace(/^#/, '').trim()) {
+    throw new Error('Use --to slack:#channel.');
+  }
+  return { kind: 'slack', channel: slack };
+}
+
+function notificationObjectKey(kind: 'group' | 'destination') {
+  return `${kind}.${globalThis.crypto.randomUUID()}`;
+}
+
 const TERMINAL_PLAY_STATUSES = new Set(['completed', 'failed', 'cancelled']);
 const INCLUDE_TOOL_METADATA_HEADER = 'x-deepline-include-tool-metadata';
 const EXECUTE_RESPONSE_CONTRACT_HEADER = 'x-deepline-execute-response-contract';
@@ -645,6 +723,14 @@ export type PlaySecretMetadata = {
   lastUsedAt?: number;
 };
 
+export type PlaySecretCheck = {
+  ok: boolean;
+  name: string;
+  playName: string | null;
+  reason: 'active' | 'missing' | 'disabled' | 'empty' | 'invalid_version';
+  secret: PlaySecretMetadata | null;
+};
+
 /**
  * Public runs namespace exposed as `client.runs`.
  *
@@ -930,6 +1016,62 @@ export type MonitorFleetWaitOptions = {
   until?: 'converged' | 'deactivated';
 };
 
+/** A durable monitor batch can name a small key set, a query target, or one Fleet. */
+export type MonitorBatchScope =
+  | { kind: 'keys'; monitorKeys: string[] }
+  | {
+      kind: 'target';
+      target: 'all' | 'all-active' | 'billing-suspended' | 'needs-repair';
+    }
+  | { kind: 'fleet'; fleetId: string };
+
+export type MonitorBatchExistingSubmitOptions = {
+  kind: 'audit' | 'deactivate' | 'reactivate' | 'repair';
+  scope: MonitorBatchScope;
+  dryRun?: boolean;
+  /** Required for deactivate; it is the declared reason shown by health/UI. */
+  deactivationReason?: string;
+  /** Stable retry key. Reusing it joins the original durable operation. */
+  idempotencyKey: string;
+};
+
+/** Complete definitions, one JSON object per line; uploaded as bounded shards. */
+export type MonitorBatchDeploySubmitOptions = {
+  kind: 'deploy';
+  manifestNdjson: string;
+  dryRun?: boolean;
+  /** Stable retry key. Reusing it joins the same content-addressed manifest. */
+  idempotencyKey: string;
+};
+
+export type MonitorBatchSubmitOptions =
+  | MonitorBatchExistingSubmitOptions
+  | MonitorBatchDeploySubmitOptions;
+
+export type MonitorBatchOperationResult = {
+  ok?: boolean;
+  rejoined?: boolean;
+  operation: {
+    runId: string;
+    kind: 'audit' | 'deactivate' | 'reactivate' | 'deploy' | 'repair';
+    state: 'running' | 'retry_scheduled' | 'completed' | 'failed';
+    dryRun: boolean;
+    scope: unknown;
+    submittedAt: number;
+    updatedAt: number;
+    deactivationReason?: string;
+    nextAttemptAt?: number;
+    completedAt?: number;
+    summary?: Record<string, unknown>;
+    lastError?: string;
+  };
+  results?: {
+    page: Array<Record<string, unknown>>;
+    isDone: boolean;
+    continueCursor: string;
+  };
+};
+
 export type MonitorFleetsNamespace = {
   /**
    * Create, update, or re-plan a fleet. Pass a definition to admit new source
@@ -963,6 +1105,16 @@ export type MonitorFleetsNamespace = {
   ) => Promise<MonitorFleetResult>;
 };
 
+export type MonitorBatchNamespace = {
+  submit: (
+    options: MonitorBatchSubmitOptions,
+  ) => Promise<MonitorBatchOperationResult>;
+  get: (
+    operationId: string,
+    options?: { cursor?: string | null },
+  ) => Promise<MonitorBatchOperationResult>;
+};
+
 /**
  * Delivery and convergence health for a scope, from
  * `GET /api/v2/monitors/health`.
@@ -977,6 +1129,16 @@ export type MonitorsHealth = {
   scanned: number;
   /** True when the scope was larger than one bounded read; counts are partial. */
   truncated: boolean;
+  /**
+   * A durable whole-scope snapshot is rebuilding. Counts remain intentionally
+   * partial until it completes; older servers omit this additive field.
+   */
+  refresh?: {
+    state: 'running' | 'completed';
+    started_at: number;
+    updated_at: number;
+    completed_at: number | null;
+  };
   desired: { active: number; inactive: number; unset: number };
   observed: {
     active: number;
@@ -1003,6 +1165,15 @@ export type MonitorsHealth = {
     observed_at: number | null;
     provider_resource_id: string | null;
   }>;
+  /** Bounded current durable monitor work, if the server supports it. */
+  batch_operations?: Array<{
+    run_id: string;
+    kind: 'audit' | 'deactivate' | 'reactivate' | 'repair' | 'deploy';
+    state: 'running' | 'retry_scheduled';
+    updated_at: number;
+    next_attempt_at?: number;
+    summary?: Record<string, unknown>;
+  }>;
 };
 
 /** One bounded audit pass, from `POST /api/v2/monitors/audit`. */
@@ -1137,6 +1308,8 @@ export type MonitorsNamespace = {
   }) => Promise<MonitorsRepairResult>;
   /** Delivery and convergence health for the workspace or one fleet. */
   health: (options?: { fleetId?: string }) => Promise<MonitorsHealth>;
+  /** Durable bulk audit/deactivation/reactivation/repair with retained progress. */
+  batch: MonitorBatchNamespace;
   /** Define, reconcile, and control table-backed monitor fleets. */
   fleets: MonitorFleetsNamespace;
 };
@@ -1293,7 +1466,12 @@ export type TargetBillingMutationResult = {
 export type TargetBillingPlanTransitionOptions =
   | {
       action: 'start_or_change';
-      targetPlanSku: 'payg-v1' | 'builder-v1' | 'team-v1';
+      targetPlanSku:
+        | 'payg-v1'
+        | 'builder-v1'
+        | 'growth-v1'
+        | 'growth-canary-v1'
+        | 'team-v1';
       idempotencyKey: string;
     }
   | {
@@ -1379,7 +1557,12 @@ export type WorkspaceCreateResult = {
   org_name: string;
   org_slug: string;
   plan_sku: 'payg-v1';
-  rate_policy_ref: 'payg-rates-v2';
+  /**
+   * The PAYG rate policy the workspace was provisioned onto, taken from the
+   * catalog revision its operation pinned: v4 bound payg-rates-v2, v5 binds
+   * the flat payg-rates-v3.
+   */
+  rate_policy_ref: 'payg-rates-v2' | 'payg-rates-v3';
   operation: {
     id: string;
     state: 'completed';
@@ -2059,6 +2242,11 @@ export class DeeplineClient {
       audit: (options) => this.auditMonitors(options),
       repair: (options) => this.repairMonitors(options),
       health: (options) => this.readMonitorsHealth(options),
+      batch: {
+        submit: (options) => this.submitMonitorBatch(options),
+        get: (operationId, options) =>
+          this.getMonitorBatch(operationId, options),
+      },
       fleets: {
         sync: (definitionOrId, options) =>
           this.syncMonitorFleet(definitionOrId, options),
@@ -2271,6 +2459,20 @@ export class DeeplineClient {
     );
   }
 
+  /** Check effective scope and active-version health without reading the value.
+   * Without playName, checks the organization-scoped secret only. With a Play
+   * name, an active Play secret takes precedence; a deleted/disabled Play
+   * secret falls back to the organization-scoped secret.
+   */
+  async inspectSecret(
+    name: string,
+    options: { playName?: string } = {},
+  ): Promise<PlaySecretCheck> {
+    const params = new URLSearchParams({ name: name.trim().toUpperCase() });
+    if (options.playName !== undefined) params.set('play', options.playName);
+    return this.http.get(`/api/v2/secrets?${params.toString()}`);
+  }
+
   // ——————————————————————————————————————————————————————————
   // Tools
   // ——————————————————————————————————————————————————————————
@@ -2376,6 +2578,10 @@ export class DeeplineClient {
       `/api/v2/integrations/${encodeURIComponent(toolId)}/get`,
       {
         method: 'GET',
+        // Tool metadata is a read-only catalog lookup. Keep the metadata
+        // header while opting into the same transient edge-response retries as
+        // other GET catalog methods such as searchTools().
+        retryApiErrors: true,
         headers: {
           'x-deepline-tool-meta-only': '1',
         },
@@ -4342,6 +4548,244 @@ export class DeeplineClient {
     return this.http.get('/api/v2/notifications');
   }
 
+  /** Read the group-based product-notification configuration and rule catalog. */
+  async getNotificationConfiguration(): Promise<ProductNotificationConfigurationResponse> {
+    return this.http.get('/api/v2/notifications/configuration');
+  }
+
+  /** Atomically apply one retry-safe desired configuration change. */
+  async changeNotificationConfiguration(
+    expectedWorkspaceVersion: number,
+    change: ProductNotificationConfigurationChange,
+  ): Promise<Pick<ProductNotificationConfigurationResponse, 'configuration'>> {
+    return this.http.put('/api/v2/notifications/configuration', {
+      expectedWorkspaceVersion,
+      change,
+    });
+  }
+
+  /** Create one notification group and its destinations as a retry-safe unit. */
+  async createNotificationGroup(
+    input: CreateNotificationGroupInput,
+  ): Promise<CreateNotificationGroupResult> {
+    const name = input.name.trim().replace(/\s+/g, ' ');
+    if (!name) throw new Error('Notification group name is required.');
+    if (
+      input.targets.length < 1 ||
+      input.targets.length > MAX_NOTIFICATION_GROUP_CREATE_TARGETS
+    ) {
+      throw new Error(
+        `Choose between 1 and ${MAX_NOTIFICATION_GROUP_CREATE_TARGETS} notification targets.`,
+      );
+    }
+
+    const targets = input.targets.map(parseNotificationGroupTarget);
+    const legacyEvents = input.legacyEvents ?? [];
+    const legacyTarget =
+      targets.length === 1 &&
+      targets[0]?.kind === 'slack' &&
+      legacyEvents.length > 0
+        ? targets[0]
+        : null;
+    if (legacyEvents.length > 0 && !legacyTarget) {
+      throw new Error(
+        '--for is supported only by the legacy one-Slack-target form. Create the group first, then add rules in notification configuration.',
+      );
+    }
+
+    if (!legacyTarget && name.toLowerCase() === 'default') {
+      throw new Error(
+        'Default is reserved for the workspace default notification group.',
+      );
+    }
+
+    const normalizedTargets = targets.map((target) =>
+      target.kind === 'email'
+        ? `email:${target.email}`
+        : 'memberId' in target
+          ? `slack:member:${target.memberId}`
+          : `slack:${target.channel}`,
+    );
+    if (input.dryRun) {
+      return {
+        mode: 'dry_run' as const,
+        compatibilityMode: legacyTarget !== null,
+        name: legacyTarget ? input.name : name,
+        targets: normalizedTargets,
+        legacyEvents,
+      };
+    }
+
+    if (legacyTarget) {
+      const notification = await this.createNotification({
+        name: input.name,
+        provider: 'slack',
+        ...('channel' in legacyTarget
+          ? { channel: legacyTarget.channel }
+          : { memberId: legacyTarget.memberId }),
+        eventTypes: legacyEvents,
+      });
+      return { mode: 'legacy' as const, notification };
+    }
+
+    const current = await this.getNotificationConfiguration();
+    const existingGroup = current.configuration.groups.find(
+      (candidate) => candidate.name.toLowerCase() === name.toLowerCase(),
+    );
+    const groupKey = existingGroup?.groupKey ?? notificationObjectKey('group');
+    const group: EffectiveProductNotificationGroup = existingGroup ?? {
+      groupKey,
+      name,
+      enabled: true,
+      deliveryTiming: { mode: 'immediate' },
+      source: 'workspace',
+      configMode: 'custom',
+      version: 0,
+    };
+    const destinations = current.configuration.destinations.filter(
+      (destination) => destination.groupKey === groupKey,
+    );
+
+    const emails = [
+      ...new Set(
+        targets.flatMap((target) =>
+          target.kind === 'email' ? [target.email] : [],
+        ),
+      ),
+    ].sort();
+    const existingEmails = new Set(
+      destinations.flatMap((destination) =>
+        destination.settings.kind === 'email_addresses'
+          ? destination.settings.to
+          : [],
+      ),
+    );
+    const newEmails = emails.filter((email) => !existingEmails.has(email));
+    if (newEmails.length > 0) {
+      destinations.push({
+        destinationKey: notificationObjectKey('destination'),
+        groupKey,
+        name: 'Email recipients',
+        enabled: true,
+        source: 'workspace',
+        configMode: 'custom',
+        version: 0,
+        status: 'active',
+        settings: { kind: 'email_addresses', to: newEmails },
+      });
+    }
+
+    const slackTargets = new Map<
+      string,
+      Extract<ParsedNotificationGroupTarget, { kind: 'slack' }>
+    >();
+    for (const target of targets) {
+      if (target.kind !== 'slack') continue;
+      const targetKey =
+        'memberId' in target
+          ? `member:${target.memberId}`
+          : `channel:${target.channel.replace(/^#/, '').toLowerCase()}`;
+      slackTargets.set(targetKey, target);
+    }
+    const connectionId = current.slackConnection.connectionId;
+    if (slackTargets.size > 0 && !connectionId) {
+      throw new Error(
+        'Slack is not connected to this workspace. Connect it in Dashboard → Integrations, then retry.',
+      );
+    }
+    const resolvedSlackTargets = await Promise.all(
+      [...slackTargets.values()].map(async (target) => {
+        if ('memberId' in target) {
+          return {
+            targetKind: 'member' as const,
+            targetId: target.memberId,
+            targetName: target.memberId,
+          };
+        }
+        const channel = target.channel;
+        const requested = channel.replace(/^#/, '');
+        const response = await this.listNotificationChannels(channel);
+        const matches = response.channels.filter(
+          (candidate) =>
+            candidate.id === requested ||
+            candidate.name.toLowerCase() === requested.toLowerCase(),
+        );
+        if (matches.length !== 1) {
+          throw new Error(
+            matches.length === 0
+              ? `Slack channel ${channel} was not found or is not visible to the Deepline app.`
+              : `Slack channel ${channel} is ambiguous. Use its channel ID.`,
+          );
+        }
+        return {
+          targetKind: 'channel' as const,
+          targetId: matches[0]!.id,
+          targetName: matches[0]!.name,
+        };
+      }),
+    );
+    const uniqueSlackTargets = new Map(
+      resolvedSlackTargets.map((target) => [
+        `${target.targetKind}:${target.targetId}`,
+        target,
+      ]),
+    );
+    for (const target of uniqueSlackTargets.values()) {
+      if (
+        destinations.some(
+          (destination) =>
+            destination.settings.kind === 'slack' &&
+            destination.settings.targetKind === target.targetKind &&
+            destination.settings.targetId === target.targetId,
+        )
+      ) {
+        continue;
+      }
+      destinations.push({
+        destinationKey: notificationObjectKey('destination'),
+        groupKey,
+        name: `${target.targetKind === 'channel' ? '#' : '@'}${target.targetName}`,
+        enabled: true,
+        source: 'workspace',
+        configMode: 'custom',
+        version: 0,
+        status: 'pending_verification',
+        settings: {
+          kind: 'slack',
+          ...target,
+          oauthConnectionId: connectionId!,
+        },
+      });
+    }
+
+    const draft: ProductNotificationGroupDraft = {
+      group,
+      destinations,
+      rules: current.configuration.rules.filter(
+        (rule) => rule.groupKey === groupKey,
+      ),
+    };
+    const result = await this.changeNotificationConfiguration(
+      current.configuration.workspaceVersion,
+      { kind: 'save_group', draft },
+    );
+    const storedGroup = result.configuration.groups.find(
+      (candidate) => candidate.groupKey === groupKey,
+    );
+    if (!storedGroup) {
+      throw new Error('Notification group creation returned no saved group.');
+    }
+    return {
+      mode: 'native' as const,
+      groupKey,
+      targets: normalizedTargets,
+      group: storedGroup,
+      destinations: result.configuration.destinations.filter(
+        (destination) => destination.groupKey === groupKey,
+      ),
+    };
+  }
+
   /** List Slack channels available to an already-connected Slack integration. */
   async listNotificationChannels(query?: string): Promise<{
     identity: { teamId: string; teamName?: string };
@@ -5049,6 +5493,92 @@ export class DeeplineClient {
     );
   }
 
+  /** Submit durable monitor work; transport retries use the same idempotency key. */
+  async submitMonitorBatch(
+    options: MonitorBatchSubmitOptions,
+  ): Promise<MonitorBatchOperationResult> {
+    const idempotencyKey = options.idempotencyKey.trim();
+    if (!idempotencyKey) {
+      throw new DeeplineError(
+        'Monitor batch idempotencyKey is required.',
+        undefined,
+        'INVALID_MONITOR_BATCH_IDEMPOTENCY_KEY',
+      );
+    }
+    if (options.kind === 'deploy') {
+      if (!options.manifestNdjson.trim()) {
+        throw new DeeplineError(
+          'Monitor batch deploy requires a non-empty NDJSON manifest.',
+          undefined,
+          'INVALID_MONITOR_BATCH_MANIFEST',
+        );
+      }
+      return this.http.request<MonitorBatchOperationResult>(
+        '/api/v2/monitors/batch',
+        {
+          method: 'POST',
+          body: {
+            kind: 'deploy',
+            manifest_ndjson: options.manifestNdjson,
+            dry_run: options.dryRun === true,
+            idempotency_key: idempotencyKey,
+          },
+          headers: { 'Idempotency-Key': idempotencyKey },
+          maxRetries: 0,
+          exactUrlOnly: true,
+        },
+      );
+    }
+    const scope =
+      options.scope.kind === 'keys'
+        ? { kind: 'keys', monitor_keys: options.scope.monitorKeys }
+        : options.scope.kind === 'fleet'
+          ? { kind: 'fleet', fleet_id: options.scope.fleetId }
+          : { kind: 'target', target: options.scope.target };
+    return this.http.request<MonitorBatchOperationResult>(
+      '/api/v2/monitors/batch',
+      {
+        method: 'POST',
+        body: {
+          kind: options.kind,
+          scope,
+          dry_run: options.dryRun === true,
+          idempotency_key: idempotencyKey,
+          ...(options.deactivationReason === undefined
+            ? {}
+            : { deactivation_reason: options.deactivationReason }),
+        },
+        headers: { 'Idempotency-Key': idempotencyKey },
+        // Durable submission is itself idempotent, but an ambiguous local retry
+        // must retain the exact key and never turn a CLI attempt into two runs.
+        maxRetries: 0,
+        exactUrlOnly: true,
+      },
+    );
+  }
+
+  /** Get durable batch progress and a bounded retained evidence page. */
+  async getMonitorBatch(
+    operationId: string,
+    options?: { cursor?: string | null },
+  ): Promise<MonitorBatchOperationResult> {
+    const runId = operationId.trim();
+    if (!runId) {
+      throw new DeeplineError(
+        'Monitor batch operation id is required.',
+        undefined,
+        'INVALID_MONITOR_BATCH_OPERATION_ID',
+      );
+    }
+    const params = new URLSearchParams();
+    if (options?.cursor) params.set('cursor', options.cursor);
+    const suffix = params.size > 0 ? `?${params}` : '';
+    return this.http.request<MonitorBatchOperationResult>(
+      `/api/v2/monitors/batch/${encodeURIComponent(runId)}${suffix}`,
+      { method: 'GET' },
+    );
+  }
+
   /**
    * The deployable monitor tools catalog. Pass a tool id (positional or
    * `{ tool }`) to describe one tool's full payload/stream contract, or no tool