deepline 0.1.271 → 0.1.273

package/dist/index.d.mts

@@ -1363,6 +1363,92 @@ interface UpdateSharePageRequest {
     seoIndexing?: 'index' | 'noindex';
 }
 
+/**
+ * Monitor authoring and typing for the Deepline SDK.
+ *
+ * A **monitor** is a Deepline-native signal feed. A deployed monitor writes
+ * events into a Customer DB table (one row per finding). Plays react to those
+ * rows through `sqlListeners` bindings (see {@link definePlay}). This module is
+ * the code-first authoring surface for monitors — the same product model the
+ * `deepline monitors` CLI drives, expressed as typed SDK code.
+ *
+ * Use {@link defineMonitor} to author a typed monitor definition, then deploy or
+ * validate it with the monitors namespace:
+ *
+ * ```typescript
+ * import { DeeplineClient, defineMonitor } from 'deepline';
+ *
+ * const monitor = defineMonitor({
+ *   key: 'stripe-job-openings',
+ *   tool: 'deepline_native.company_radar',
+ *   name: 'Stripe job openings',
+ *   payload: { domain: 'stripe.com', radar_type: 'company_job_openings' },
+ * });
+ *
+ * const client = new DeeplineClient();
+ * const plan = await client.monitors.check(monitor); // validate, no spend
+ * await client.monitors.deploy(monitor);             // deploy for real
+ * ```
+ *
+ * @module
+ */
+/**
+ * A monitor definition: the exact object accepted by
+ * `client.monitors.check(...)` and `client.monitors.deploy(...)` and by the
+ * `/api/v2/monitors/{check,deploy}` endpoints the CLI uses.
+ *
+ * @typeParam TPayload - Provider-specific monitor payload shape (defaults to a
+ *   loose record). Pass a concrete shape to `defineMonitor<TPayload>(...)` for
+ *   compile-time checking of the payload fields.
+ */
+type MonitorDefinition<TPayload extends MonitorPayload = MonitorPayload> = {
+    /** Stable public key for this monitor, unique within the workspace. */
+    key: string;
+    /** Monitor tool id, e.g. `"deepline_native.company_radar"`. */
+    tool: string;
+    /** Optional human-readable name shown in listings and detail views. */
+    name?: string;
+    /** Provider-specific monitor payload (e.g. domain + radar_type). */
+    payload: TPayload;
+    /** Optional Deepline lifecycle metadata (deploy/reuse controls). */
+    controls?: MonitorControls;
+};
+/** Provider-specific monitor payload. Keys and value types depend on the tool. */
+type MonitorPayload = Record<string, unknown>;
+/**
+ * Deepline lifecycle metadata attached to a monitor definition. These are
+ * Deepline-side deploy/reuse controls, not provider payload fields. The set is
+ * intentionally open (server-owned) so newer controls do not require an SDK
+ * bump; known controls are typed for discoverability.
+ */
+type MonitorControls = {
+    [key: string]: unknown;
+};
+/**
+ * Define a typed monitor definition.
+ *
+ * Mirrors {@link definePlay} as the code-first authoring entrypoint: it gives
+ * compile-time type safety on the definition object and returns it verbatim for
+ * passing to `client.monitors.check(...)` / `client.monitors.deploy(...)`. It
+ * performs the same lightweight local invariants the server enforces (non-empty
+ * `key` and `tool`, object `payload`) so authoring mistakes fail before a
+ * network round-trip.
+ *
+ * @typeParam TPayload - Provider payload shape.
+ * @param definition - The monitor definition.
+ * @returns The validated definition object.
+ *
+ * @example
+ * ```typescript
+ * const monitor = defineMonitor({
+ *   key: 'job-openings',
+ *   tool: 'deepline_native.company_radar',
+ *   payload: { domain: 'stripe.com', radar_type: 'company_job_openings' },
+ * });
+ * ```
+ */
+declare function defineMonitor<TPayload extends MonitorPayload = MonitorPayload>(definition: MonitorDefinition<TPayload>): MonitorDefinition<TPayload>;
+
 interface PlayStagedFileRef {
     storageKind: 'r2';
     storageKey: string;
@@ -1669,6 +1755,137 @@ type DbNamespace = {
         maxRows?: number;
     }) => Promise<CustomerDbQueryResult>;
 };
+/**
+ * Whether the current workspace can use Deepline Monitors, from
+ * `GET /api/v2/monitors/access`. Reachable without monitor access (requires
+ * only an authenticated session/API key); a denial is a normal 200 body, not a
+ * 403.
+ */
+type MonitorsAccessStatus = {
+    has_access: boolean;
+    reason?: string;
+};
+/**
+ * The monitor tools catalog (deployable monitor TYPES), from
+ * `GET /api/v2/monitors/tools`. Server-owned shape: describing one tool returns
+ * the full payload/stream contract, while list mode returns the compact
+ * inventory. Kept as an open record so the SDK does not have to bump when the
+ * server enriches the catalog.
+ */
+type MonitorsAvailableResult = {
+    tools?: Array<Record<string, unknown>>;
+    total?: number;
+    returned?: number;
+    is_truncated?: boolean;
+    [key: string]: unknown;
+};
+/** Options for `client.monitors.available(...)` (list or describe mode). */
+type MonitorsAvailableOptions = {
+    provider?: string;
+    search?: string;
+    limit?: number | string;
+    /**
+     * Request the full catalog contract in LIST mode (payload schemas + streams).
+     * List mode is compact by default; ignored when describing a single tool.
+     */
+    full?: boolean;
+    /** Ask the server for high-signal fields only. */
+    compact?: boolean;
+};
+/** One deployed monitor row returned by `client.monitors.list(...)`. */
+type MonitorListEntry = {
+    key?: string;
+    monitor_key?: string;
+    status?: string;
+    tool?: string;
+    name?: string;
+    [key: string]: unknown;
+};
+/**
+ * Deployed-monitor registry page from `GET /api/v2/monitors/deployed`. `total`
+ * is the TRUE registry count for the status filter, not this page's size; page
+ * past a truncated result with `next_cursor`.
+ */
+type MonitorsListResult = {
+    monitors?: MonitorListEntry[];
+    total?: number;
+    returned?: number;
+    is_truncated?: boolean;
+    next_cursor?: string | null;
+    status_filter_applied?: string;
+    [key: string]: unknown;
+};
+/** Options for `client.monitors.list(...)`. */
+type MonitorsListOptions = {
+    /** active (default), disabled, or all. */
+    status?: string;
+    limit?: number | string;
+    /** Page past a truncated result using a prior response's `next_cursor`. */
+    cursor?: string;
+    compact?: boolean;
+};
+/**
+ * Server-owned monitor payload shapes returned by the deploy/check/get/mutation
+ * endpoints. Kept as open records because the render layer and the endpoints
+ * own the exact field set (output contracts, pricing, reuse candidates, delete
+ * plans, dependents) and it must not require an SDK bump to evolve.
+ */
+type MonitorCheckResult = Record<string, unknown>;
+type MonitorDeployResult = Record<string, unknown>;
+type MonitorDetail = Record<string, unknown>;
+type MonitorDependents = Record<string, unknown>;
+type MonitorUpdateResult = Record<string, unknown>;
+type MonitorDeleteResult = Record<string, unknown>;
+type MonitorReactivateResult = Record<string, unknown>;
+/**
+ * Public monitors namespace exposed as `client.monitors`.
+ *
+ * Mirrors the /api/v2/monitors resource family so the monitors CLI and
+ * programmatic callers share one product surface — every `deepline monitors`
+ * verb maps to a method here. Monitors are fully expressible as SDK code: author
+ * a definition with {@link defineMonitor}, then check/deploy/list/get/update/
+ * delete/reactivate through this namespace.
+ *
+ * @sdkReference client 040 client.monitors
+ */
+type MonitorsNamespace = {
+    /** Whether the current workspace can use monitors (`{ has_access, reason }`). */
+    status: () => Promise<MonitorsAccessStatus>;
+    /**
+     * The deployable monitor tools catalog. Call with no tool id for the list, or
+     * with a tool id (positional or `{ tool }`) to describe one tool's full
+     * payload/stream contract.
+     */
+    available: (toolIdOrOptions?: string | (MonitorsAvailableOptions & {
+        tool?: string;
+    }), options?: MonitorsAvailableOptions) => Promise<MonitorsAvailableResult>;
+    /** Validate a monitor definition without deploying it (no spend). */
+    check: (definition: MonitorDefinition) => Promise<MonitorCheckResult>;
+    /** Deploy a monitor from a definition. May spend Deepline credits. */
+    deploy: (definition: MonitorDefinition, options?: {
+        dryRun?: boolean;
+    }) => Promise<MonitorDeployResult>;
+    /** List deployed monitors (active by default). */
+    list: (options?: MonitorsListOptions) => Promise<MonitorsListResult>;
+    /** Fetch one deployed monitor by public key (without dependents). */
+    get: (key: string) => Promise<MonitorDetail>;
+    /** List the published plays depending on one monitor's output streams. */
+    dependents: (key: string) => Promise<MonitorDependents>;
+    /** Update a deployed monitor by public key. */
+    update: (key: string, patch: Record<string, unknown>) => Promise<MonitorUpdateResult>;
+    /**
+     * Delete a deployed monitor by public key. Deprovisions the upstream provider
+     * resource unless `localOnly` is set. `dryRun` returns the delete plan.
+     */
+    delete: (key: string, options?: {
+        localOnly?: boolean;
+        dryRun?: boolean;
+    }) => Promise<MonitorDeleteResult>;
+    /** Reactivate a disabled monitor. `dryRun` returns the reactivation cost. */
+    reactivate: (key: string, options?: {
+        dryRun?: boolean;
+    }) => Promise<MonitorReactivateResult>;
+};
 /** One credit grant pool reported by the billing subscription status endpoint. */
 type BillingCreditPool = {
     pool: string;
@@ -1887,6 +2104,8 @@ declare class DeeplineClient {
     readonly db: DbNamespace;
     /** Billing namespace: subscription status/cancel and invoice history. */
     readonly billing: BillingNamespace;
+    /** Monitors namespace: access, catalog, deploy/check, and lifecycle. */
+    readonly monitors: MonitorsNamespace;
     /**
      * Create a low-level SDK client.
      *
@@ -2747,6 +2966,54 @@ declare class DeeplineClient {
     listBillingInvoices(options?: {
         limit?: number;
     }): Promise<BillingInvoicesResult>;
+    /**
+     * Whether the current workspace can use Deepline Monitors. Reachable without
+     * monitor access; a denial is a normal 200 body, not a 403. Prefer
+     * `client.monitors.status()`.
+     */
+    getMonitorsAccess(): Promise<MonitorsAccessStatus>;
+    /**
+     * The deployable monitor tools catalog. Pass a tool id (positional or
+     * `{ tool }`) to describe one tool's full payload/stream contract, or no tool
+     * id for the compact inventory. Prefer `client.monitors.available(...)`.
+     */
+    getMonitorsAvailable(toolIdOrOptions?: string | (MonitorsAvailableOptions & {
+        tool?: string;
+    }), maybeOptions?: MonitorsAvailableOptions): Promise<MonitorsAvailableResult>;
+    /** Validate a monitor definition without deploying it. Prefer `client.monitors.check(...)`. */
+    checkMonitor(definition: MonitorDefinition): Promise<MonitorCheckResult>;
+    /**
+     * Deploy a monitor from a definition. `dryRun` validates via the check
+     * endpoint and returns the plan without deploying. Prefer
+     * `client.monitors.deploy(...)`.
+     */
+    deployMonitor(definition: MonitorDefinition, options?: {
+        dryRun?: boolean;
+    }): Promise<MonitorDeployResult>;
+    /** List deployed monitors. Prefer `client.monitors.list(...)`. */
+    listMonitors(options?: MonitorsListOptions): Promise<MonitorsListResult>;
+    /** Fetch one deployed monitor by public key. Prefer `client.monitors.get(...)`. */
+    getMonitor(key: string): Promise<MonitorDetail>;
+    /** Published plays depending on one monitor. Prefer `client.monitors.dependents(...)`. */
+    getMonitorDependents(key: string): Promise<MonitorDependents>;
+    /** Update a deployed monitor by public key. Prefer `client.monitors.update(...)`. */
+    updateMonitor(key: string, patch: Record<string, unknown>): Promise<MonitorUpdateResult>;
+    /**
+     * Delete a deployed monitor by public key. Deprovisions the upstream provider
+     * resource unless `localOnly`; `dryRun` returns the delete plan. Prefer
+     * `client.monitors.delete(...)`.
+     */
+    deleteMonitor(key: string, options?: {
+        localOnly?: boolean;
+        dryRun?: boolean;
+    }): Promise<MonitorDeleteResult>;
+    /**
+     * Reactivate a disabled monitor. `dryRun` returns the reactivation cost.
+     * Prefer `client.monitors.reactivate(...)`.
+     */
+    reactivateMonitor(key: string, options?: {
+        dryRun?: boolean;
+    }): Promise<MonitorReactivateResult>;
     /**
      * Check API connectivity and server health.
      *
@@ -3328,7 +3595,7 @@ type PreviousCell<Value = unknown> = {
 
 type PlayCallExecution = 'inline' | 'child-workflow';
 interface PlayCallOptions {
-    description?: string;
+    description: string;
     execution?: PlayCallExecution;
 }
 /**
@@ -3964,7 +4231,7 @@ interface DeeplinePlayRuntimeContext {
      *
      * @sdkReference runtime 140 ctx.runPlay(key, playRef, input, options)
      */
-    runPlay<TOutput = unknown>(key: string, playRef: string | PlayReferenceLike, input: Record<string, unknown>, options?: PlayCallOptions): Promise<TOutput>;
+    runPlay<TOutput = unknown>(key: string, playRef: string | PlayReferenceLike, input: Record<string, unknown>, options: PlayCallOptions): Promise<TOutput>;
     /**
      * Emit a log line visible in `play tail` and the play's progress logs.
      *
@@ -4655,4 +4922,4 @@ declare function writeCsvOutputFile(rows: Array<Record<string, unknown>>, stem:
  */
 declare function extractSummaryFields(payload: unknown): Record<string, Scalar>;
 
-export { AuthError, type BillingCreditPool, type BillingInvoiceEntry, type BillingInvoicesResult, type BillingNamespace, type BillingPaymentMethodSummary, type BillingSubscriptionCancelResult, type BillingSubscriptionStatus, type BillingTopUpResult, type ClearPlayHistoryRequest, type ClearPlayHistoryResult, type ColumnMap, type ColumnResolver, type ConditionalStepResolver, ConfigError, type CsvInput, type CsvOptions, type CustomerDbQueryResult, DEEPLINE_EXTRACTOR_TARGETS, DEEPLINE_EXTRACTOR_TARGET_DEFINITIONS, DEEPLINE_TOOL_CATEGORIES, type DatasetBuilder, type DatasetColumnDefinition, type DatasetColumnRunInput, type DbNamespace, Deepline, DeeplineClient, type DeeplineClientOptions, DeeplineContext, type DeeplineEmailStatusGetterValue, DeeplineError, type DeeplineExtractorTarget, type DeeplineGetterValue, type DeeplineGetterValueMap, type DeeplineNamedPlay, type DeeplinePlayRuntimeContext, type DeeplinePlaysNamespace, type DeeplineToolCategory, type DeeplineToolsNamespace, type DefinePlayConfig, type DefinedPlay, type FileInput, type IngestionStorageRepairResult, JOB_CHANGE_STATUS_VALUES, type JobChangeStatus, type LiveEventEnvelope, PHONE_STATUS_VALUES, PLAY_BOOTSTRAP_COMPANY_FIELDS, PLAY_BOOTSTRAP_COMPANY_PROVIDER_CATEGORY, PLAY_BOOTSTRAP_CONTACT_FIELDS, PLAY_BOOTSTRAP_FINDER_KINDS, PLAY_BOOTSTRAP_OUTPUT_FIELD_BY_FINDER, PLAY_BOOTSTRAP_PEOPLE_PROVIDER_CATEGORY, PLAY_BOOTSTRAP_PROVIDER_CATEGORY_BY_FINDER, PLAY_BOOTSTRAP_SOURCE_KINDS, PLAY_BOOTSTRAP_STAGE_KINDS, PLAY_BOOTSTRAP_TEMPLATES, PROD_URL, type PhoneStatus, type PlayBindings, type PlayBootstrapEntityKind, type PlayBootstrapFinderKind, type PlayCallExecution, type PlayCallOptions, type PlayDataset, type PlayDatasetInput, type PlayInputContract, type PlayJob, type PlayListItem, type PlayLiveEvent, type PlayRevisionSummary, type PlayRunActionPackage, type PlayRunDatasetActions, type PlayRunPackage, type PlayRunResult, type PlayRunStart, type PlaySheetRow, type PlaySheetRowsResult, type PlayStatus, type PlayStepProgramStep, type PrebuiltPlayRef, type PreviousCell, type PublishPlayVersionRequest, type PublishPlayVersionResult, RateLimitError, type ResolvedConfig, RunObserveTransportUnavailableError, type RunsListOptions, type RunsLogsOptions, type RunsLogsResult, type RunsNamespace, type RunsTailOptions, SDK_API_CONTRACT, SDK_VERSION, type SqlListenerDeclaration, type SqlListenerEvent, type SqlListenerOperation, type SqlQuery, type StartPlayRunRequest, type StepOptions, type StepProgram, type StepProgramResolver, type StepResolver, type StopPlayRunResult, type ToolDefinition, type ToolExecuteResult, type ToolExecution, type ToolExecutionRequest, type ToolMetadata, type ToolSearchOptions, type ToolSearchResult, defineInput, definePlay, defineWorkflow, extractSummaryFields, formatPlayBootstrapFinderKinds, formatPlayBootstrapFinderKindsForSentence, formatPlayBootstrapTemplates, getDefinedPlayMetadata, isDeeplineExtractorTarget, isPlayBootstrapFinderKind, isPlayBootstrapTemplate, resolveConfig, runIf, steps, tryConvertToList, writeCsvOutputFile, writeJsonOutputFile };
+export { AuthError, type BillingCreditPool, type BillingInvoiceEntry, type BillingInvoicesResult, type BillingNamespace, type BillingPaymentMethodSummary, type BillingSubscriptionCancelResult, type BillingSubscriptionStatus, type BillingTopUpResult, type ClearPlayHistoryRequest, type ClearPlayHistoryResult, type ColumnMap, type ColumnResolver, type ConditionalStepResolver, ConfigError, type CsvInput, type CsvOptions, type CustomerDbQueryResult, DEEPLINE_EXTRACTOR_TARGETS, DEEPLINE_EXTRACTOR_TARGET_DEFINITIONS, DEEPLINE_TOOL_CATEGORIES, type DatasetBuilder, type DatasetColumnDefinition, type DatasetColumnRunInput, type DbNamespace, Deepline, DeeplineClient, type DeeplineClientOptions, DeeplineContext, type DeeplineEmailStatusGetterValue, DeeplineError, type DeeplineExtractorTarget, type DeeplineGetterValue, type DeeplineGetterValueMap, type DeeplineNamedPlay, type DeeplinePlayRuntimeContext, type DeeplinePlaysNamespace, type DeeplineToolCategory, type DeeplineToolsNamespace, type DefinePlayConfig, type DefinedPlay, type FileInput, type IngestionStorageRepairResult, JOB_CHANGE_STATUS_VALUES, type JobChangeStatus, type LiveEventEnvelope, type MonitorCheckResult, type MonitorControls, type MonitorDefinition, type MonitorDeleteResult, type MonitorDependents, type MonitorDeployResult, type MonitorDetail, type MonitorListEntry, type MonitorPayload, type MonitorReactivateResult, type MonitorUpdateResult, type MonitorsAccessStatus, type MonitorsAvailableOptions, type MonitorsAvailableResult, type MonitorsListOptions, type MonitorsListResult, type MonitorsNamespace, PHONE_STATUS_VALUES, PLAY_BOOTSTRAP_COMPANY_FIELDS, PLAY_BOOTSTRAP_COMPANY_PROVIDER_CATEGORY, PLAY_BOOTSTRAP_CONTACT_FIELDS, PLAY_BOOTSTRAP_FINDER_KINDS, PLAY_BOOTSTRAP_OUTPUT_FIELD_BY_FINDER, PLAY_BOOTSTRAP_PEOPLE_PROVIDER_CATEGORY, PLAY_BOOTSTRAP_PROVIDER_CATEGORY_BY_FINDER, PLAY_BOOTSTRAP_SOURCE_KINDS, PLAY_BOOTSTRAP_STAGE_KINDS, PLAY_BOOTSTRAP_TEMPLATES, PROD_URL, type PhoneStatus, type PlayBindings, type PlayBootstrapEntityKind, type PlayBootstrapFinderKind, type PlayCallExecution, type PlayCallOptions, type PlayDataset, type PlayDatasetInput, type PlayInputContract, type PlayJob, type PlayListItem, type PlayLiveEvent, type PlayRevisionSummary, type PlayRunActionPackage, type PlayRunDatasetActions, type PlayRunPackage, type PlayRunResult, type PlayRunStart, type PlaySheetRow, type PlaySheetRowsResult, type PlayStatus, type PlayStepProgramStep, type PrebuiltPlayRef, type PreviousCell, type PublishPlayVersionRequest, type PublishPlayVersionResult, RateLimitError, type ResolvedConfig, RunObserveTransportUnavailableError, type RunsListOptions, type RunsLogsOptions, type RunsLogsResult, type RunsNamespace, type RunsTailOptions, SDK_API_CONTRACT, SDK_VERSION, type SqlListenerDeclaration, type SqlListenerEvent, type SqlListenerOperation, type SqlQuery, type StartPlayRunRequest, type StepOptions, type StepProgram, type StepProgramResolver, type StepResolver, type StopPlayRunResult, type ToolDefinition, type ToolExecuteResult, type ToolExecution, type ToolExecutionRequest, type ToolMetadata, type ToolSearchOptions, type ToolSearchResult, defineInput, defineMonitor, definePlay, defineWorkflow, extractSummaryFields, formatPlayBootstrapFinderKinds, formatPlayBootstrapFinderKindsForSentence, formatPlayBootstrapTemplates, getDefinedPlayMetadata, isDeeplineExtractorTarget, isPlayBootstrapFinderKind, isPlayBootstrapTemplate, resolveConfig, runIf, steps, tryConvertToList, writeCsvOutputFile, writeJsonOutputFile };

package/dist/index.d.ts

@@ -1363,6 +1363,92 @@ interface UpdateSharePageRequest {
     seoIndexing?: 'index' | 'noindex';
 }
 
+/**
+ * Monitor authoring and typing for the Deepline SDK.
+ *
+ * A **monitor** is a Deepline-native signal feed. A deployed monitor writes
+ * events into a Customer DB table (one row per finding). Plays react to those
+ * rows through `sqlListeners` bindings (see {@link definePlay}). This module is
+ * the code-first authoring surface for monitors — the same product model the
+ * `deepline monitors` CLI drives, expressed as typed SDK code.
+ *
+ * Use {@link defineMonitor} to author a typed monitor definition, then deploy or
+ * validate it with the monitors namespace:
+ *
+ * ```typescript
+ * import { DeeplineClient, defineMonitor } from 'deepline';
+ *
+ * const monitor = defineMonitor({
+ *   key: 'stripe-job-openings',
+ *   tool: 'deepline_native.company_radar',
+ *   name: 'Stripe job openings',
+ *   payload: { domain: 'stripe.com', radar_type: 'company_job_openings' },
+ * });
+ *
+ * const client = new DeeplineClient();
+ * const plan = await client.monitors.check(monitor); // validate, no spend
+ * await client.monitors.deploy(monitor);             // deploy for real
+ * ```
+ *
+ * @module
+ */
+/**
+ * A monitor definition: the exact object accepted by
+ * `client.monitors.check(...)` and `client.monitors.deploy(...)` and by the
+ * `/api/v2/monitors/{check,deploy}` endpoints the CLI uses.
+ *
+ * @typeParam TPayload - Provider-specific monitor payload shape (defaults to a
+ *   loose record). Pass a concrete shape to `defineMonitor<TPayload>(...)` for
+ *   compile-time checking of the payload fields.
+ */
+type MonitorDefinition<TPayload extends MonitorPayload = MonitorPayload> = {
+    /** Stable public key for this monitor, unique within the workspace. */
+    key: string;
+    /** Monitor tool id, e.g. `"deepline_native.company_radar"`. */
+    tool: string;
+    /** Optional human-readable name shown in listings and detail views. */
+    name?: string;
+    /** Provider-specific monitor payload (e.g. domain + radar_type). */
+    payload: TPayload;
+    /** Optional Deepline lifecycle metadata (deploy/reuse controls). */
+    controls?: MonitorControls;
+};
+/** Provider-specific monitor payload. Keys and value types depend on the tool. */
+type MonitorPayload = Record<string, unknown>;
+/**
+ * Deepline lifecycle metadata attached to a monitor definition. These are
+ * Deepline-side deploy/reuse controls, not provider payload fields. The set is
+ * intentionally open (server-owned) so newer controls do not require an SDK
+ * bump; known controls are typed for discoverability.
+ */
+type MonitorControls = {
+    [key: string]: unknown;
+};
+/**
+ * Define a typed monitor definition.
+ *
+ * Mirrors {@link definePlay} as the code-first authoring entrypoint: it gives
+ * compile-time type safety on the definition object and returns it verbatim for
+ * passing to `client.monitors.check(...)` / `client.monitors.deploy(...)`. It
+ * performs the same lightweight local invariants the server enforces (non-empty
+ * `key` and `tool`, object `payload`) so authoring mistakes fail before a
+ * network round-trip.
+ *
+ * @typeParam TPayload - Provider payload shape.
+ * @param definition - The monitor definition.
+ * @returns The validated definition object.
+ *
+ * @example
+ * ```typescript
+ * const monitor = defineMonitor({
+ *   key: 'job-openings',
+ *   tool: 'deepline_native.company_radar',
+ *   payload: { domain: 'stripe.com', radar_type: 'company_job_openings' },
+ * });
+ * ```
+ */
+declare function defineMonitor<TPayload extends MonitorPayload = MonitorPayload>(definition: MonitorDefinition<TPayload>): MonitorDefinition<TPayload>;
+
 interface PlayStagedFileRef {
     storageKind: 'r2';
     storageKey: string;
@@ -1669,6 +1755,137 @@ type DbNamespace = {
         maxRows?: number;
     }) => Promise<CustomerDbQueryResult>;
 };
+/**
+ * Whether the current workspace can use Deepline Monitors, from
+ * `GET /api/v2/monitors/access`. Reachable without monitor access (requires
+ * only an authenticated session/API key); a denial is a normal 200 body, not a
+ * 403.
+ */
+type MonitorsAccessStatus = {
+    has_access: boolean;
+    reason?: string;
+};
+/**
+ * The monitor tools catalog (deployable monitor TYPES), from
+ * `GET /api/v2/monitors/tools`. Server-owned shape: describing one tool returns
+ * the full payload/stream contract, while list mode returns the compact
+ * inventory. Kept as an open record so the SDK does not have to bump when the
+ * server enriches the catalog.
+ */
+type MonitorsAvailableResult = {
+    tools?: Array<Record<string, unknown>>;
+    total?: number;
+    returned?: number;
+    is_truncated?: boolean;
+    [key: string]: unknown;
+};
+/** Options for `client.monitors.available(...)` (list or describe mode). */
+type MonitorsAvailableOptions = {
+    provider?: string;
+    search?: string;
+    limit?: number | string;
+    /**
+     * Request the full catalog contract in LIST mode (payload schemas + streams).
+     * List mode is compact by default; ignored when describing a single tool.
+     */
+    full?: boolean;
+    /** Ask the server for high-signal fields only. */
+    compact?: boolean;
+};
+/** One deployed monitor row returned by `client.monitors.list(...)`. */
+type MonitorListEntry = {
+    key?: string;
+    monitor_key?: string;
+    status?: string;
+    tool?: string;
+    name?: string;
+    [key: string]: unknown;
+};
+/**
+ * Deployed-monitor registry page from `GET /api/v2/monitors/deployed`. `total`
+ * is the TRUE registry count for the status filter, not this page's size; page
+ * past a truncated result with `next_cursor`.
+ */
+type MonitorsListResult = {
+    monitors?: MonitorListEntry[];
+    total?: number;
+    returned?: number;
+    is_truncated?: boolean;
+    next_cursor?: string | null;
+    status_filter_applied?: string;
+    [key: string]: unknown;
+};
+/** Options for `client.monitors.list(...)`. */
+type MonitorsListOptions = {
+    /** active (default), disabled, or all. */
+    status?: string;
+    limit?: number | string;
+    /** Page past a truncated result using a prior response's `next_cursor`. */
+    cursor?: string;
+    compact?: boolean;
+};
+/**
+ * Server-owned monitor payload shapes returned by the deploy/check/get/mutation
+ * endpoints. Kept as open records because the render layer and the endpoints
+ * own the exact field set (output contracts, pricing, reuse candidates, delete
+ * plans, dependents) and it must not require an SDK bump to evolve.
+ */
+type MonitorCheckResult = Record<string, unknown>;
+type MonitorDeployResult = Record<string, unknown>;
+type MonitorDetail = Record<string, unknown>;
+type MonitorDependents = Record<string, unknown>;
+type MonitorUpdateResult = Record<string, unknown>;
+type MonitorDeleteResult = Record<string, unknown>;
+type MonitorReactivateResult = Record<string, unknown>;
+/**
+ * Public monitors namespace exposed as `client.monitors`.
+ *
+ * Mirrors the /api/v2/monitors resource family so the monitors CLI and
+ * programmatic callers share one product surface — every `deepline monitors`
+ * verb maps to a method here. Monitors are fully expressible as SDK code: author
+ * a definition with {@link defineMonitor}, then check/deploy/list/get/update/
+ * delete/reactivate through this namespace.
+ *
+ * @sdkReference client 040 client.monitors
+ */
+type MonitorsNamespace = {
+    /** Whether the current workspace can use monitors (`{ has_access, reason }`). */
+    status: () => Promise<MonitorsAccessStatus>;
+    /**
+     * The deployable monitor tools catalog. Call with no tool id for the list, or
+     * with a tool id (positional or `{ tool }`) to describe one tool's full
+     * payload/stream contract.
+     */
+    available: (toolIdOrOptions?: string | (MonitorsAvailableOptions & {
+        tool?: string;
+    }), options?: MonitorsAvailableOptions) => Promise<MonitorsAvailableResult>;
+    /** Validate a monitor definition without deploying it (no spend). */
+    check: (definition: MonitorDefinition) => Promise<MonitorCheckResult>;
+    /** Deploy a monitor from a definition. May spend Deepline credits. */
+    deploy: (definition: MonitorDefinition, options?: {
+        dryRun?: boolean;
+    }) => Promise<MonitorDeployResult>;
+    /** List deployed monitors (active by default). */
+    list: (options?: MonitorsListOptions) => Promise<MonitorsListResult>;
+    /** Fetch one deployed monitor by public key (without dependents). */
+    get: (key: string) => Promise<MonitorDetail>;
+    /** List the published plays depending on one monitor's output streams. */
+    dependents: (key: string) => Promise<MonitorDependents>;
+    /** Update a deployed monitor by public key. */
+    update: (key: string, patch: Record<string, unknown>) => Promise<MonitorUpdateResult>;
+    /**
+     * Delete a deployed monitor by public key. Deprovisions the upstream provider
+     * resource unless `localOnly` is set. `dryRun` returns the delete plan.
+     */
+    delete: (key: string, options?: {
+        localOnly?: boolean;
+        dryRun?: boolean;
+    }) => Promise<MonitorDeleteResult>;
+    /** Reactivate a disabled monitor. `dryRun` returns the reactivation cost. */
+    reactivate: (key: string, options?: {
+        dryRun?: boolean;
+    }) => Promise<MonitorReactivateResult>;
+};
 /** One credit grant pool reported by the billing subscription status endpoint. */
 type BillingCreditPool = {
     pool: string;
@@ -1887,6 +2104,8 @@ declare class DeeplineClient {
     readonly db: DbNamespace;
     /** Billing namespace: subscription status/cancel and invoice history. */
     readonly billing: BillingNamespace;
+    /** Monitors namespace: access, catalog, deploy/check, and lifecycle. */
+    readonly monitors: MonitorsNamespace;
     /**
      * Create a low-level SDK client.
      *
@@ -2747,6 +2966,54 @@ declare class DeeplineClient {
     listBillingInvoices(options?: {
         limit?: number;
     }): Promise<BillingInvoicesResult>;
+    /**
+     * Whether the current workspace can use Deepline Monitors. Reachable without
+     * monitor access; a denial is a normal 200 body, not a 403. Prefer
+     * `client.monitors.status()`.
+     */
+    getMonitorsAccess(): Promise<MonitorsAccessStatus>;
+    /**
+     * The deployable monitor tools catalog. Pass a tool id (positional or
+     * `{ tool }`) to describe one tool's full payload/stream contract, or no tool
+     * id for the compact inventory. Prefer `client.monitors.available(...)`.
+     */
+    getMonitorsAvailable(toolIdOrOptions?: string | (MonitorsAvailableOptions & {
+        tool?: string;
+    }), maybeOptions?: MonitorsAvailableOptions): Promise<MonitorsAvailableResult>;
+    /** Validate a monitor definition without deploying it. Prefer `client.monitors.check(...)`. */
+    checkMonitor(definition: MonitorDefinition): Promise<MonitorCheckResult>;
+    /**
+     * Deploy a monitor from a definition. `dryRun` validates via the check
+     * endpoint and returns the plan without deploying. Prefer
+     * `client.monitors.deploy(...)`.
+     */
+    deployMonitor(definition: MonitorDefinition, options?: {
+        dryRun?: boolean;
+    }): Promise<MonitorDeployResult>;
+    /** List deployed monitors. Prefer `client.monitors.list(...)`. */
+    listMonitors(options?: MonitorsListOptions): Promise<MonitorsListResult>;
+    /** Fetch one deployed monitor by public key. Prefer `client.monitors.get(...)`. */
+    getMonitor(key: string): Promise<MonitorDetail>;
+    /** Published plays depending on one monitor. Prefer `client.monitors.dependents(...)`. */
+    getMonitorDependents(key: string): Promise<MonitorDependents>;
+    /** Update a deployed monitor by public key. Prefer `client.monitors.update(...)`. */
+    updateMonitor(key: string, patch: Record<string, unknown>): Promise<MonitorUpdateResult>;
+    /**
+     * Delete a deployed monitor by public key. Deprovisions the upstream provider
+     * resource unless `localOnly`; `dryRun` returns the delete plan. Prefer
+     * `client.monitors.delete(...)`.
+     */
+    deleteMonitor(key: string, options?: {
+        localOnly?: boolean;
+        dryRun?: boolean;
+    }): Promise<MonitorDeleteResult>;
+    /**
+     * Reactivate a disabled monitor. `dryRun` returns the reactivation cost.
+     * Prefer `client.monitors.reactivate(...)`.
+     */
+    reactivateMonitor(key: string, options?: {
+        dryRun?: boolean;
+    }): Promise<MonitorReactivateResult>;
     /**
      * Check API connectivity and server health.
      *
@@ -3328,7 +3595,7 @@ type PreviousCell<Value = unknown> = {
 
 type PlayCallExecution = 'inline' | 'child-workflow';
 interface PlayCallOptions {
-    description?: string;
+    description: string;
     execution?: PlayCallExecution;
 }
 /**
@@ -3964,7 +4231,7 @@ interface DeeplinePlayRuntimeContext {
      *
      * @sdkReference runtime 140 ctx.runPlay(key, playRef, input, options)
      */
-    runPlay<TOutput = unknown>(key: string, playRef: string | PlayReferenceLike, input: Record<string, unknown>, options?: PlayCallOptions): Promise<TOutput>;
+    runPlay<TOutput = unknown>(key: string, playRef: string | PlayReferenceLike, input: Record<string, unknown>, options: PlayCallOptions): Promise<TOutput>;
     /**
      * Emit a log line visible in `play tail` and the play's progress logs.
      *
@@ -4655,4 +4922,4 @@ declare function writeCsvOutputFile(rows: Array<Record<string, unknown>>, stem:
  */
 declare function extractSummaryFields(payload: unknown): Record<string, Scalar>;
 
-export { AuthError, type BillingCreditPool, type BillingInvoiceEntry, type BillingInvoicesResult, type BillingNamespace, type BillingPaymentMethodSummary, type BillingSubscriptionCancelResult, type BillingSubscriptionStatus, type BillingTopUpResult, type ClearPlayHistoryRequest, type ClearPlayHistoryResult, type ColumnMap, type ColumnResolver, type ConditionalStepResolver, ConfigError, type CsvInput, type CsvOptions, type CustomerDbQueryResult, DEEPLINE_EXTRACTOR_TARGETS, DEEPLINE_EXTRACTOR_TARGET_DEFINITIONS, DEEPLINE_TOOL_CATEGORIES, type DatasetBuilder, type DatasetColumnDefinition, type DatasetColumnRunInput, type DbNamespace, Deepline, DeeplineClient, type DeeplineClientOptions, DeeplineContext, type DeeplineEmailStatusGetterValue, DeeplineError, type DeeplineExtractorTarget, type DeeplineGetterValue, type DeeplineGetterValueMap, type DeeplineNamedPlay, type DeeplinePlayRuntimeContext, type DeeplinePlaysNamespace, type DeeplineToolCategory, type DeeplineToolsNamespace, type DefinePlayConfig, type DefinedPlay, type FileInput, type IngestionStorageRepairResult, JOB_CHANGE_STATUS_VALUES, type JobChangeStatus, type LiveEventEnvelope, PHONE_STATUS_VALUES, PLAY_BOOTSTRAP_COMPANY_FIELDS, PLAY_BOOTSTRAP_COMPANY_PROVIDER_CATEGORY, PLAY_BOOTSTRAP_CONTACT_FIELDS, PLAY_BOOTSTRAP_FINDER_KINDS, PLAY_BOOTSTRAP_OUTPUT_FIELD_BY_FINDER, PLAY_BOOTSTRAP_PEOPLE_PROVIDER_CATEGORY, PLAY_BOOTSTRAP_PROVIDER_CATEGORY_BY_FINDER, PLAY_BOOTSTRAP_SOURCE_KINDS, PLAY_BOOTSTRAP_STAGE_KINDS, PLAY_BOOTSTRAP_TEMPLATES, PROD_URL, type PhoneStatus, type PlayBindings, type PlayBootstrapEntityKind, type PlayBootstrapFinderKind, type PlayCallExecution, type PlayCallOptions, type PlayDataset, type PlayDatasetInput, type PlayInputContract, type PlayJob, type PlayListItem, type PlayLiveEvent, type PlayRevisionSummary, type PlayRunActionPackage, type PlayRunDatasetActions, type PlayRunPackage, type PlayRunResult, type PlayRunStart, type PlaySheetRow, type PlaySheetRowsResult, type PlayStatus, type PlayStepProgramStep, type PrebuiltPlayRef, type PreviousCell, type PublishPlayVersionRequest, type PublishPlayVersionResult, RateLimitError, type ResolvedConfig, RunObserveTransportUnavailableError, type RunsListOptions, type RunsLogsOptions, type RunsLogsResult, type RunsNamespace, type RunsTailOptions, SDK_API_CONTRACT, SDK_VERSION, type SqlListenerDeclaration, type SqlListenerEvent, type SqlListenerOperation, type SqlQuery, type StartPlayRunRequest, type StepOptions, type StepProgram, type StepProgramResolver, type StepResolver, type StopPlayRunResult, type ToolDefinition, type ToolExecuteResult, type ToolExecution, type ToolExecutionRequest, type ToolMetadata, type ToolSearchOptions, type ToolSearchResult, defineInput, definePlay, defineWorkflow, extractSummaryFields, formatPlayBootstrapFinderKinds, formatPlayBootstrapFinderKindsForSentence, formatPlayBootstrapTemplates, getDefinedPlayMetadata, isDeeplineExtractorTarget, isPlayBootstrapFinderKind, isPlayBootstrapTemplate, resolveConfig, runIf, steps, tryConvertToList, writeCsvOutputFile, writeJsonOutputFile };
+export { AuthError, type BillingCreditPool, type BillingInvoiceEntry, type BillingInvoicesResult, type BillingNamespace, type BillingPaymentMethodSummary, type BillingSubscriptionCancelResult, type BillingSubscriptionStatus, type BillingTopUpResult, type ClearPlayHistoryRequest, type ClearPlayHistoryResult, type ColumnMap, type ColumnResolver, type ConditionalStepResolver, ConfigError, type CsvInput, type CsvOptions, type CustomerDbQueryResult, DEEPLINE_EXTRACTOR_TARGETS, DEEPLINE_EXTRACTOR_TARGET_DEFINITIONS, DEEPLINE_TOOL_CATEGORIES, type DatasetBuilder, type DatasetColumnDefinition, type DatasetColumnRunInput, type DbNamespace, Deepline, DeeplineClient, type DeeplineClientOptions, DeeplineContext, type DeeplineEmailStatusGetterValue, DeeplineError, type DeeplineExtractorTarget, type DeeplineGetterValue, type DeeplineGetterValueMap, type DeeplineNamedPlay, type DeeplinePlayRuntimeContext, type DeeplinePlaysNamespace, type DeeplineToolCategory, type DeeplineToolsNamespace, type DefinePlayConfig, type DefinedPlay, type FileInput, type IngestionStorageRepairResult, JOB_CHANGE_STATUS_VALUES, type JobChangeStatus, type LiveEventEnvelope, type MonitorCheckResult, type MonitorControls, type MonitorDefinition, type MonitorDeleteResult, type MonitorDependents, type MonitorDeployResult, type MonitorDetail, type MonitorListEntry, type MonitorPayload, type MonitorReactivateResult, type MonitorUpdateResult, type MonitorsAccessStatus, type MonitorsAvailableOptions, type MonitorsAvailableResult, type MonitorsListOptions, type MonitorsListResult, type MonitorsNamespace, PHONE_STATUS_VALUES, PLAY_BOOTSTRAP_COMPANY_FIELDS, PLAY_BOOTSTRAP_COMPANY_PROVIDER_CATEGORY, PLAY_BOOTSTRAP_CONTACT_FIELDS, PLAY_BOOTSTRAP_FINDER_KINDS, PLAY_BOOTSTRAP_OUTPUT_FIELD_BY_FINDER, PLAY_BOOTSTRAP_PEOPLE_PROVIDER_CATEGORY, PLAY_BOOTSTRAP_PROVIDER_CATEGORY_BY_FINDER, PLAY_BOOTSTRAP_SOURCE_KINDS, PLAY_BOOTSTRAP_STAGE_KINDS, PLAY_BOOTSTRAP_TEMPLATES, PROD_URL, type PhoneStatus, type PlayBindings, type PlayBootstrapEntityKind, type PlayBootstrapFinderKind, type PlayCallExecution, type PlayCallOptions, type PlayDataset, type PlayDatasetInput, type PlayInputContract, type PlayJob, type PlayListItem, type PlayLiveEvent, type PlayRevisionSummary, type PlayRunActionPackage, type PlayRunDatasetActions, type PlayRunPackage, type PlayRunResult, type PlayRunStart, type PlaySheetRow, type PlaySheetRowsResult, type PlayStatus, type PlayStepProgramStep, type PrebuiltPlayRef, type PreviousCell, type PublishPlayVersionRequest, type PublishPlayVersionResult, RateLimitError, type ResolvedConfig, RunObserveTransportUnavailableError, type RunsListOptions, type RunsLogsOptions, type RunsLogsResult, type RunsNamespace, type RunsTailOptions, SDK_API_CONTRACT, SDK_VERSION, type SqlListenerDeclaration, type SqlListenerEvent, type SqlListenerOperation, type SqlQuery, type StartPlayRunRequest, type StepOptions, type StepProgram, type StepProgramResolver, type StepResolver, type StopPlayRunResult, type ToolDefinition, type ToolExecuteResult, type ToolExecution, type ToolExecutionRequest, type ToolMetadata, type ToolSearchOptions, type ToolSearchResult, defineInput, defineMonitor, definePlay, defineWorkflow, extractSummaryFields, formatPlayBootstrapFinderKinds, formatPlayBootstrapFinderKindsForSentence, formatPlayBootstrapTemplates, getDefinedPlayMetadata, isDeeplineExtractorTarget, isPlayBootstrapFinderKind, isPlayBootstrapTemplate, resolveConfig, runIf, steps, tryConvertToList, writeCsvOutputFile, writeJsonOutputFile };