deepline 0.3.55 → 0.3.56

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

@@ -83,6 +83,7 @@ import type {
   InferenceQuote,
 } from './types.js';
 import type { MonitorDefinition } from './monitors.js';
+import type { MonitorFleetDefinition } from './monitor-fleets.js';
 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';
@@ -848,6 +849,90 @@ export type MonitorReactivateResult = Record<string, unknown>;
 export type MonitorTestResult = Record<string, unknown>;
 export type MonitorValidateResult = Record<string, unknown>;
 
+/**
+ * Server-owned fleet response envelope.
+ *
+ * The server computes `status` (`converging` | `converged` | `degraded` |
+ * `deactivating` | `deactivated`) and the SDK never recomputes it: a client
+ * that derives its own verdict from counts drifts from the control plane the
+ * moment the server changes what "converged" means.
+ */
+export type MonitorFleetResult = Record<string, unknown>;
+
+/** Server-computed fleet verdict. Never derived client-side. */
+export type MonitorFleetStatus =
+  | 'converging'
+  | 'converged'
+  | 'degraded'
+  | 'deactivating'
+  | 'deactivated';
+
+export type MonitorFleetSyncOptions = {
+  /** Return the plan without changing fleet state (`dry_run: true`). */
+  dryRun?: boolean;
+  /** Optimistic concurrency: refuse the write unless the fleet is at this generation. */
+  expectedGeneration?: number;
+  /** Stable retry key; generated by the caller when omitted. */
+  idempotencyKey?: string;
+};
+
+export type MonitorFleetGetOptions = {
+  /** Include bounded per-member drift rows. */
+  drift?: boolean;
+  /** Maximum drift rows to return. */
+  limit?: number;
+};
+
+export type MonitorFleetDeactivateOptions = {
+  /** Return the blast radius without deactivating anything. */
+  dryRun?: boolean;
+  idempotencyKey?: string;
+};
+
+export type MonitorFleetWaitOptions = {
+  /** Give up after this long. Default 10 minutes. */
+  timeoutMs?: number;
+  /** Poll cadence. Default 2 seconds. */
+  pollIntervalMs?: number;
+  /** Called with every polled snapshot, including the terminal one. */
+  onProgress?: (payload: MonitorFleetResult) => void;
+  /**
+   * Which terminal state ends the wait. `converged` (default) also stops on
+   * `degraded` and `deactivated`; `deactivated` stops on `deactivated` and
+   * `degraded`. A timeout is not an error: the last snapshot is returned and
+   * the caller reads `status` to decide the verdict.
+   */
+  until?: 'converged' | 'deactivated';
+};
+
+export type MonitorFleetsNamespace = {
+  /**
+   * Create, update, or re-plan a fleet. Pass a definition to admit new source
+   * of truth; pass a fleet id to re-plan from the stored definition.
+   */
+  sync: (
+    definitionOrId: string | MonitorFleetDefinition,
+    options?: MonitorFleetSyncOptions,
+  ) => Promise<MonitorFleetResult>;
+  /** One fleet by id, or every fleet in the workspace when the id is omitted. */
+  get: (
+    fleetId?: string,
+    options?: MonitorFleetGetOptions,
+  ) => Promise<MonitorFleetResult>;
+  /** Every fleet in the workspace. */
+  list: () => Promise<MonitorFleetResult>;
+  /** Deactivate a fleet and the monitors it owns. */
+  deactivate: (
+    fleetId: string,
+    options?: MonitorFleetDeactivateOptions,
+  ) => Promise<MonitorFleetResult>;
+  /** Poll the fleet until the server reports a terminal status (or the timeout elapses). */
+  waitForConvergence: (
+    fleetId: string,
+    options?: MonitorFleetWaitOptions,
+  ) => Promise<MonitorFleetResult>;
+};
+
 /**
  * Public monitors namespace exposed as `client.monitors`.
  *
@@ -909,6 +994,8 @@ export type MonitorsNamespace = {
     key: string,
     options?: { dryRun?: boolean },
   ) => Promise<MonitorReactivateResult>;
+  /** Define, reconcile, and control table-backed monitor fleets. */
+  fleets: MonitorFleetsNamespace;
 };
 
 /** One credit grant pool reported by the billing subscription status endpoint. */
@@ -1801,6 +1888,19 @@ export class DeeplineClient {
       update: (key, patch) => this.updateMonitor(key, patch),
       delete: (key, options) => this.deleteMonitor(key, options),
       reactivate: (key, options) => this.reactivateMonitor(key, options),
+      fleets: {
+        sync: (definitionOrId, options) =>
+          this.syncMonitorFleet(definitionOrId, options),
+        get: (fleetId, options) =>
+          fleetId === undefined
+            ? this.listMonitorFleets()
+            : this.getMonitorFleet(fleetId, options),
+        list: () => this.listMonitorFleets(),
+        deactivate: (fleetId, options) =>
+          this.deactivateMonitorFleet(fleetId, options),
+        waitForConvergence: (fleetId, options) =>
+          this.waitForMonitorFleetConvergence(fleetId, options),
+      },
     };
   }
 
@@ -4915,6 +5015,138 @@ export class DeeplineClient {
     );
   }
 
+  // ——————————————————————————————————————————————————————————
+  // Monitor Fleets
+  // ——————————————————————————————————————————————————————————
+
+  private monitorFleetIdempotencyKey(operation: string): string {
+    const uuid = globalThis.crypto?.randomUUID?.();
+    return `monitor-fleet-${operation}-${uuid ?? `${Date.now()}-${Math.random().toString(36).slice(2)}`}`;
+  }
+
+  private monitorFleetHeaders(
+    operation: string,
+    idempotencyKey?: string,
+  ): Record<string, string> {
+    return {
+      'Idempotency-Key':
+        idempotencyKey?.trim() || this.monitorFleetIdempotencyKey(operation),
+    };
+  }
+
+  private monitorFleetPath(fleetId: string): string {
+    return `/api/v2/monitors/fleets/${encodeURIComponent(fleetId)}`;
+  }
+
+  /**
+   * Create, update, or re-plan one fleet.
+   *
+   * The fleet id is always the resource path, so the same definition PUT twice
+   * is the same operation and the server can answer `replayed: true` instead of
+   * building a second set of monitors. Re-planning an existing fleet from its
+   * stored definition sends an EMPTY body: there is no second definition to
+   * send, and an empty body cannot be mistaken for "replace the definition with
+   * nothing".
+   */
+  async syncMonitorFleet(
+    definitionOrId: string | MonitorFleetDefinition,
+    options?: MonitorFleetSyncOptions,
+  ): Promise<MonitorFleetResult> {
+    const fleetId =
+      typeof definitionOrId === 'string' ? definitionOrId : definitionOrId.id;
+    const body: Record<string, unknown> = {
+      ...(typeof definitionOrId === 'string'
+        ? {}
+        : { definition: definitionOrId }),
+      ...(options?.dryRun ? { dry_run: true } : {}),
+      ...(options?.expectedGeneration !== undefined
+        ? { expected_generation: options.expectedGeneration }
+        : {}),
+    };
+    return this.http.request<MonitorFleetResult>(
+      this.monitorFleetPath(fleetId),
+      {
+        method: 'PUT',
+        body,
+        headers: this.monitorFleetHeaders('sync', options?.idempotencyKey),
+        maxRetries: 0,
+        exactUrlOnly: true,
+      },
+    );
+  }
+
+  async listMonitorFleets(): Promise<MonitorFleetResult> {
+    return this.http.request<MonitorFleetResult>('/api/v2/monitors/fleets', {
+      method: 'GET',
+    });
+  }
+
+  async getMonitorFleet(
+    fleetId: string,
+    options?: MonitorFleetGetOptions,
+  ): Promise<MonitorFleetResult> {
+    const params = new URLSearchParams();
+    if (options?.drift) params.set('drift', '1');
+    if (options?.limit !== undefined)
+      params.set('limit', String(options.limit));
+    const query = params.toString();
+    return this.http.request<MonitorFleetResult>(
+      `${this.monitorFleetPath(fleetId)}${query ? `?${query}` : ''}`,
+      { method: 'GET' },
+    );
+  }
+
+  async deactivateMonitorFleet(
+    fleetId: string,
+    options?: MonitorFleetDeactivateOptions,
+  ): Promise<MonitorFleetResult> {
+    return this.http.request<MonitorFleetResult>(
+      this.monitorFleetPath(fleetId),
+      {
+        method: 'DELETE',
+        body: options?.dryRun ? { dry_run: true } : {},
+        headers: this.monitorFleetHeaders(
+          'deactivate',
+          options?.idempotencyKey,
+        ),
+        maxRetries: 0,
+        exactUrlOnly: true,
+      },
+    );
+  }
+
+  /**
+   * Poll one fleet until the server reports a terminal status.
+   *
+   * Convergence is the server's verdict, read from `status`. The timeout is not
+   * a failure and does not throw: a fleet still `converging` after ten minutes
+   * is healthy and slow, not broken, so the caller gets the last snapshot and
+   * decides what that means. Throwing here would have made "still working" look
+   * identical to "the request failed".
+   */
+  async waitForMonitorFleetConvergence(
+    fleetId: string,
+    options?: MonitorFleetWaitOptions,
+  ): Promise<MonitorFleetResult> {
+    const timeoutMs = Math.max(1, options?.timeoutMs ?? 10 * 60_000);
+    const pollIntervalMs = Math.max(1, options?.pollIntervalMs ?? 2_000);
+    const terminal: ReadonlySet<string> =
+      options?.until === 'deactivated'
+        ? new Set(['deactivated', 'degraded'])
+        : new Set(['converged', 'degraded', 'deactivated']);
+    const startedAt = Date.now();
+    let latest = await this.getMonitorFleet(fleetId);
+    while (true) {
+      options?.onProgress?.(latest);
+      const status =
+        typeof latest.status === 'string' ? latest.status : undefined;
+      if (status && terminal.has(status)) return latest;
+      if (Date.now() - startedAt >= timeoutMs) return latest;
+      await sleep(pollIntervalMs);
+      latest = await this.getMonitorFleet(fleetId);
+    }
+  }
+
   /**
    * Check API connectivity and server health.
    *

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

@@ -84,6 +84,13 @@ export type {
   MonitorUpdateResult,
   MonitorDeleteResult,
   MonitorReactivateResult,
+  MonitorFleetDeactivateOptions,
+  MonitorFleetGetOptions,
+  MonitorFleetSyncOptions,
+  MonitorFleetStatus,
+  MonitorFleetWaitOptions,
+  MonitorFleetResult,
+  MonitorFleetsNamespace,
   IngestionStorageRepairResult,
   PlayStatus,
   PlaySheetRow,
@@ -103,6 +110,28 @@ export type {
   MonitorPayload,
   MonitorControls,
 } from './monitors.js';
+export {
+  admitMonitorFleetAuthoringContract,
+  MONITOR_FLEET_AUTHORING_CONTRACT_CHANGELOG,
+  MONITOR_FLEET_AUTHORING_CONTRACT_EDITION,
+  MONITOR_FLEET_DOCUMENTATION,
+  MONITOR_FLEET_FRONTIER_MAX_ROWS,
+  MONITOR_FLEET_MAX_MEMBERS,
+  defineMonitorFleet,
+  fleetColumn,
+  fleetKey,
+  validateMonitorFleetDefinition,
+} from './monitor-fleets.js';
+export type {
+  AdmittedMonitorFleetAuthoringContract,
+  MonitorFleetAuthoringContractEdition,
+  MonitorFleetAuthoringContractResult,
+  MonitorFleetColumn,
+  MonitorFleetContractIssue,
+  MonitorFleetDefinition,
+  MonitorFleetExpression,
+  MonitorFleetTemplate,
+} from './monitor-fleets.js';
 export { SDK_API_CONTRACT, SDK_VERSION } from './version.js';
 export {
   DEEPLINE_TOOL_CATEGORIES,