deepline 0.1.83 → 0.1.85

package/dist/index.d.mts

@@ -46,7 +46,7 @@ interface PlaySheetContractSnapshot {
     tableNamespace: string;
     columns: PlaySheetColumnContractSnapshot[];
 }
-type PlayStaticColumnProducerKindSnapshot = 'tool' | 'waterfall' | 'stepProgram' | 'playCall' | 'transform';
+type PlayStaticColumnProducerKindSnapshot = 'tool' | 'waterfall' | 'stepProgram' | 'playCall' | 'controlFlow' | 'transform';
 interface PlayStaticColumnProducerSnapshot {
     id: string;
     kind: PlayStaticColumnProducerKindSnapshot;
@@ -148,6 +148,15 @@ type PlayStaticSubstepSnapshot = PlayStaticSubstepMetadataSnapshot & ({
     sourceRange?: PlayStaticSourceRangeSnapshot;
     callDepth?: number;
     callPath?: string[];
+} | {
+    type: 'control_flow';
+    kind: 'conditional' | 'loop';
+    field: string;
+    steps: PlayStaticSubstepSnapshot[];
+    description?: string;
+    sourceRange?: PlayStaticSourceRangeSnapshot;
+    callDepth?: number;
+    callPath?: string[];
 } | {
     type: 'run_javascript';
     alias: string;
@@ -646,6 +655,10 @@ interface PlayRunListItem {
     closeTime: string | null;
     /** Duration string (e.g. `'2.5s'`). */
     executionTime: string | null;
+    /** Total Deepline credits charged for the run, when available. */
+    billingTotalCredits?: number;
+    /** Configured per-run Deepline credit cap, when available. */
+    billingMaxCreditsPerRun?: number | null;
     /** Metadata attached to the workflow. */
     memo: {
         /** Organization that owns this run. */
@@ -2036,6 +2049,35 @@ interface PlayDataset<T> extends AsyncIterable<T> {
 
 type EmailStatusVerdict = 'send' | 'send_with_caution' | 'verify_next' | 'hold' | 'drop';
 type EmailStatusValue = 'valid' | 'invalid' | 'catch_all' | 'valid_catch_all' | 'unknown' | 'do_not_mail' | 'spamtrap' | 'abuse' | 'disposable';
+type EmailDeliverability = 'high' | 'medium' | 'low' | 'unknown';
+type EmailMxClass = 'consumer_mailbox' | 'workspace_mailbox' | 'security_gateway' | 'on_prem' | 'unknown';
+type EmailStatus = {
+    verdict: EmailStatusVerdict;
+    status: EmailStatusValue;
+    verified: boolean;
+    confidence: number | null;
+    reasons: string[];
+    signals: {
+        catch_all: boolean | null;
+        deliverability: EmailDeliverability;
+        mx_class: EmailMxClass;
+        mx_provider: string | null;
+        mx_record: string | null;
+        fraud_score: number | null;
+        disposable: boolean | null;
+        role_based: boolean | null;
+        free_email: boolean | null;
+        abuse: boolean | null;
+        spamtrap: boolean | null;
+        suspect: boolean | null;
+        valid: boolean | null;
+    };
+    provider: {
+        name: string;
+        raw_status: string | boolean | number | null;
+        raw_score: number | null;
+    };
+};
 type EmailStatusMapEntry = {
     status: EmailStatusValue;
     verdict?: EmailStatusVerdict;
@@ -2065,6 +2107,153 @@ type EmailStatusExtractorConfig = {
     rules?: EmailStatusRule[];
 };
 
+declare const JOB_CHANGE_STATUS_VALUES: readonly ["moved", "no_change", "left_company", "unknown", "profile_unavailable", "no_new_company"];
+type JobChangeStatus = (typeof JOB_CHANGE_STATUS_VALUES)[number];
+type JobChangeGetterValue = {
+    status: JobChangeStatus;
+    date: string | null;
+    new_company: string | null;
+    new_title: string | null;
+};
+declare const PHONE_STATUS_VALUES: readonly ["valid", "invalid", "unknown"];
+type PhoneStatus = (typeof PHONE_STATUS_VALUES)[number];
+declare const DEEPLINE_EXTRACTOR_TARGET_DEFINITIONS: {
+    readonly id: {
+        readonly identity: true;
+        readonly valueKind: "string";
+    };
+    readonly name: {
+        readonly identity: true;
+        readonly valueKind: "string";
+    };
+    readonly email: {
+        readonly identity: true;
+        readonly valueKind: "string";
+    };
+    readonly personal_email: {
+        readonly identity: true;
+        readonly valueKind: "string";
+    };
+    readonly phone: {
+        readonly identity: true;
+        readonly valueKind: "string";
+    };
+    readonly linkedin: {
+        readonly identity: true;
+        readonly valueKind: "string";
+    };
+    readonly linkedin_url: {
+        readonly identity: true;
+        readonly valueKind: "string";
+    };
+    readonly domain: {
+        readonly identity: true;
+        readonly valueKind: "string";
+    };
+    readonly website: {
+        readonly identity: true;
+        readonly valueKind: "string";
+    };
+    readonly first_name: {
+        readonly identity: true;
+        readonly valueKind: "string";
+    };
+    readonly last_name: {
+        readonly identity: true;
+        readonly valueKind: "string";
+    };
+    readonly full_name: {
+        readonly identity: true;
+        readonly valueKind: "string";
+    };
+    readonly company: {
+        readonly identity: true;
+        readonly valueKind: "string";
+    };
+    readonly company_name: {
+        readonly identity: true;
+        readonly valueKind: "string";
+    };
+    readonly organization_name: {
+        readonly identity: true;
+        readonly valueKind: "string";
+    };
+    readonly company_domain: {
+        readonly identity: true;
+        readonly valueKind: "string";
+    };
+    readonly company_website: {
+        readonly identity: true;
+        readonly valueKind: "string";
+    };
+    readonly company_linkedin_url: {
+        readonly identity: true;
+        readonly valueKind: "string";
+    };
+    readonly title: {
+        readonly identity: false;
+        readonly valueKind: "string";
+    };
+    readonly industry: {
+        readonly identity: false;
+        readonly valueKind: "string";
+    };
+    readonly status: {
+        readonly identity: false;
+        readonly valueKind: "string";
+    };
+    readonly job_change: {
+        readonly identity: false;
+        readonly valueKind: "job_change";
+    };
+    readonly job_change_status: {
+        readonly identity: false;
+        readonly valueKind: "job_change_status";
+        readonly enum: readonly ["moved", "no_change", "left_company", "unknown", "profile_unavailable", "no_new_company"];
+    };
+    readonly email_status: {
+        readonly identity: false;
+        readonly valueKind: "email_status";
+    };
+    readonly phone_status: {
+        readonly identity: false;
+        readonly valueKind: "phone_status";
+        readonly enum: readonly ["valid", "invalid", "unknown"];
+    };
+};
+type DeeplineExtractorTarget = keyof typeof DEEPLINE_EXTRACTOR_TARGET_DEFINITIONS;
+declare const DEEPLINE_EXTRACTOR_TARGETS: DeeplineExtractorTarget[];
+type DeeplineEmailStatusGetterValue = EmailStatus | EmailStatusValue;
+type DeeplineGetterValueMap = {
+    id: string;
+    name: string;
+    email: string;
+    personal_email: string;
+    phone: string;
+    linkedin: string;
+    linkedin_url: string;
+    domain: string;
+    website: string;
+    first_name: string;
+    last_name: string;
+    full_name: string;
+    company: string;
+    company_name: string;
+    organization_name: string;
+    company_domain: string;
+    company_website: string;
+    company_linkedin_url: string;
+    title: string;
+    industry: string;
+    status: string;
+    job_change: JobChangeGetterValue;
+    job_change_status: JobChangeStatus;
+    email_status: DeeplineEmailStatusGetterValue;
+    phone_status: PhoneStatus;
+};
+type DeeplineGetterValue<TTarget extends DeeplineExtractorTarget = DeeplineExtractorTarget> = DeeplineGetterValueMap[TTarget];
+declare function isDeeplineExtractorTarget(value: string): value is DeeplineExtractorTarget;
+
 type ToolResultExecutionMetadata = {
     idempotent: true;
     cached: boolean;
@@ -2128,7 +2317,7 @@ type ToolExecuteResultBase<TResult = unknown, TMeta = Record<string, unknown>> =
         }>;
     };
 };
-type ToolExecuteResultAccessors<TExtracted extends Record<string, unknown> = Record<string, unknown>, TLists extends Record<string, Record<string, unknown>> = Record<string, Record<string, unknown>>> = {
+type ToolExecuteResultAccessors<TExtracted extends Record<string, unknown> = Partial<DeeplineGetterValueMap>, TLists extends Record<string, Record<string, unknown>> = Record<string, Record<string, unknown>>> = {
     extractedValues: {
         [K in keyof TExtracted]: ToolResultTargetAccessor<TExtracted[K]>;
     };
@@ -2149,7 +2338,16 @@ type ToolExecuteResultAccessors<TExtracted extends Record<string, unknown> = Rec
  * `toolResponse.raw` when you need provider-specific fields or when debugging
  * from persisted run rows.
  */
-type ToolExecuteResult<TResult = unknown, TMeta = Record<string, unknown>, TExtracted extends Record<string, unknown> = Record<string, unknown>, TLists extends Record<string, Record<string, unknown>> = Record<string, Record<string, unknown>>> = ToolExecuteResultBase<TResult, TMeta> & ToolExecuteResultAccessors<TExtracted, TLists>;
+type ToolExecuteResult<TResult = unknown, TMeta = Record<string, unknown>, TExtracted extends Record<string, unknown> = Partial<DeeplineGetterValueMap>, TLists extends Record<string, Record<string, unknown>> = Record<string, Record<string, unknown>>> = ToolExecuteResultBase<TResult, TMeta> & ToolExecuteResultAccessors<TExtracted, TLists>;
+
+type StaleAfterSecondsResolver<Value = unknown> = (value: Value) => number | null;
+type AuthoredStaleAfterSeconds<Value = unknown> = number | StaleAfterSecondsResolver<Value>;
+type PreviousCell<Value = unknown> = {
+    value: Value;
+    completedAt?: number;
+    staleAt?: number | null;
+    staleAfterSeconds?: number;
+};
 
 /**
  * Optional trigger bindings for a play.
@@ -2247,7 +2445,25 @@ type ToolExecutionRequest = {
     description?: string;
     staleAfterSeconds?: number;
 };
-type StepResolver<Row, Value> = (row: Row, ctx: DeeplinePlayRuntimeContext, index: number) => Value | Promise<Value>;
+type StaleAfterSeconds<Value = unknown> = AuthoredStaleAfterSeconds<Value>;
+type StepResolver<Row, Value> = (row: Row, ctx: DeeplinePlayRuntimeContext, index: number, previousCell?: PreviousCell<Value>) => Value | Promise<Value>;
+type DatasetColumnRunInput<Row, Value> = {
+    row: Row;
+    ctx: DeeplinePlayRuntimeContext;
+    index: number;
+    /**
+     * The prior stored value for this exact row+column when the runtime has
+     * decided the cell is due to run again. `previousCell.value` is the same type
+     * this column returns; metadata such as `completedAt` and `staleAt` lives
+     * beside it and is not mixed into the value.
+     */
+    previousCell?: PreviousCell<Value>;
+};
+type DatasetColumnDefinition<Row, Value> = {
+    run: (input: DatasetColumnRunInput<Row, Value>) => Value | Promise<Value>;
+    readonly runIf?: (row: Row, index: number) => boolean | Promise<boolean>;
+    readonly staleAfterSeconds?: StaleAfterSeconds<Value>;
+};
 type ConditionalStepResolver<Row, Value, Else = null> = {
     readonly kind: 'conditional';
     readonly when: (row: Row, index: number) => boolean | Promise<boolean>;
@@ -2255,9 +2471,9 @@ type ConditionalStepResolver<Row, Value, Else = null> = {
     readonly elseValue: Else;
     else<ValueElse>(value: ValueElse): ConditionalStepResolver<Row, Value, ValueElse>;
 };
-type StepOptions<Row> = {
+type StepOptions<Row, Value = unknown> = {
     readonly runIf?: (row: Row, index: number) => boolean | Promise<boolean>;
-    readonly staleAfterSeconds?: number;
+    readonly staleAfterSeconds?: StaleAfterSeconds<Value>;
 };
 type StepProgram<Input, Output, Return = Output> = {
     readonly kind: 'steps';
@@ -2265,7 +2481,7 @@ type StepProgram<Input, Output, Return = Output> = {
     readonly returnResolver?: StepResolver<Output, Return>;
     readonly __inputType?: (input: Input) => void;
     step<Name extends string, Value>(name: Name, resolver: StepResolver<Output, Value> | ConditionalStepResolver<Output, Value> | StepProgramResolver<Output, Value>): StepProgram<Input, Output & Record<Name, Value>, Return>;
-    step<Name extends string, Value>(name: Name, resolver: StepResolver<Output, Value> | StepProgramResolver<Output, Value>, options: StepOptions<Output>): StepProgram<Input, Output & Record<Name, Value | null>, Return>;
+    step<Name extends string, Value>(name: Name, resolver: StepResolver<Output, Value> | StepProgramResolver<Output, Value>, options: StepOptions<Output, Value>): StepProgram<Input, Output & Record<Name, Value | null>, Return>;
     return<Value>(resolver: StepResolver<Output, Value>): StepProgram<Input, Output, Value>;
 };
 type StepProgramResolver<Input, Return> = {
@@ -2276,7 +2492,7 @@ type StepProgramResolver<Input, Return> = {
 };
 type PlayStepProgramStep = {
     readonly name: string;
-    readonly staleAfterSeconds?: number;
+    readonly staleAfterSeconds?: StaleAfterSeconds;
     readonly resolver: StepResolver<Record<string, unknown>, unknown> | ConditionalStepResolver<Record<string, unknown>, unknown> | StepProgramResolver<Record<string, unknown>, unknown>;
 };
 type ColumnResolver<Row, Value> = StepResolver<Row, Value> | ConditionalStepResolver<Row, Value> | StepProgramResolver<Row, Value>;
@@ -2296,7 +2512,11 @@ type DatasetBuilder<InputRow extends object, OutputRow extends object> = {
      * @returns The same dataset builder with the new column type.
      */
     withColumn<Name extends string, Value>(name: Name, resolver: ColumnResolver<OutputRow, Value>): DatasetBuilder<InputRow, OutputRow & Record<Name, Value>>;
-    withColumn<Name extends string, Value>(name: Name, resolver: StepResolver<OutputRow, Value> | StepProgramResolver<OutputRow, Value>, options: StepOptions<OutputRow>): DatasetBuilder<InputRow, OutputRow & Record<Name, Value | null>>;
+    withColumn<Name extends string, Value>(name: Name, definition: DatasetColumnDefinition<OutputRow, Value> & {
+        readonly runIf: (row: OutputRow, index: number) => boolean | Promise<boolean>;
+    }): DatasetBuilder<InputRow, OutputRow & Record<Name, Value | null>>;
+    withColumn<Name extends string, Value>(name: Name, definition: DatasetColumnDefinition<OutputRow, Value>): DatasetBuilder<InputRow, OutputRow & Record<Name, Value>>;
+    withColumn<Name extends string, Value>(name: Name, resolver: StepResolver<OutputRow, Value> | StepProgramResolver<OutputRow, Value>, options: StepOptions<OutputRow, Value>): DatasetBuilder<InputRow, OutputRow & Record<Name, Value | null>>;
     withColumns<Program extends StepProgram<OutputRow, object, unknown>>(program: Program): DatasetBuilder<InputRow, StepProgramOutput<Program>>;
     /** @deprecated Dataset `.step(...)` was replaced by `.withColumn(...)`. */
     step<Name extends string, Value>(name: Name, resolver: ColumnResolver<OutputRow, Value>): never;
@@ -3189,4 +3409,4 @@ declare function writeCsvOutputFile(rows: Array<Record<string, unknown>>, stem:
  */
 declare function extractSummaryFields(payload: unknown): Record<string, Scalar>;
 
-export { AuthError, type ClearPlayHistoryRequest, type ClearPlayHistoryResult, type ColumnMap, type ColumnResolver, type ConditionalStepResolver, ConfigError, type CsvInput, DEEPLINE_TOOL_CATEGORIES, type DatasetBuilder, Deepline, DeeplineClient, type DeeplineClientOptions, DeeplineContext, DeeplineError, type DeeplineNamedPlay, type DeeplinePlayRuntimeContext, type DeeplineToolCategory, type DefinePlayConfig, type DefinedPlay, type FileInput, type LiveEventEnvelope, 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 PlayBindings, type PlayBootstrapEntityKind, type PlayBootstrapFinderKind, type PlayDataset, type PlayDatasetInput, type PlayInputContract, type PlayJob, type PlayListItem, type PlayLiveEvent, type PlayRevisionSummary, type PlayRunResult, type PlayRunStart, type PlayStatus, type PlayStepProgramStep, type PrebuiltPlayRef, type PublishPlayVersionRequest, type PublishPlayVersionResult, RateLimitError, type ResolvedConfig, SDK_API_CONTRACT, SDK_VERSION, type StartPlayRunRequest, type StepProgram, type StepProgramResolver, type StepResolver, type ToolDefinition, type ToolExecuteResult, type ToolExecution, type ToolMetadata, defineInput, definePlay, defineWorkflow, extractSummaryFields, formatPlayBootstrapFinderKinds, formatPlayBootstrapFinderKindsForSentence, formatPlayBootstrapTemplates, getDefinedPlayMetadata, isPlayBootstrapFinderKind, isPlayBootstrapTemplate, resolveConfig, runIf, steps, tryConvertToList, writeCsvOutputFile, writeJsonOutputFile };
+export { AuthError, type ClearPlayHistoryRequest, type ClearPlayHistoryResult, type ColumnMap, type ColumnResolver, type ConditionalStepResolver, ConfigError, type CsvInput, DEEPLINE_EXTRACTOR_TARGETS, DEEPLINE_EXTRACTOR_TARGET_DEFINITIONS, DEEPLINE_TOOL_CATEGORIES, type DatasetBuilder, Deepline, DeeplineClient, type DeeplineClientOptions, DeeplineContext, type DeeplineEmailStatusGetterValue, DeeplineError, type DeeplineExtractorTarget, type DeeplineGetterValue, type DeeplineGetterValueMap, type DeeplineNamedPlay, type DeeplinePlayRuntimeContext, type DeeplineToolCategory, type DefinePlayConfig, type DefinedPlay, type FileInput, 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 PlayDataset, type PlayDatasetInput, type PlayInputContract, type PlayJob, type PlayListItem, type PlayLiveEvent, type PlayRevisionSummary, type PlayRunResult, type PlayRunStart, type PlayStatus, type PlayStepProgramStep, type PrebuiltPlayRef, type PublishPlayVersionRequest, type PublishPlayVersionResult, RateLimitError, type ResolvedConfig, SDK_API_CONTRACT, SDK_VERSION, type StartPlayRunRequest, type StepProgram, type StepProgramResolver, type StepResolver, type ToolDefinition, type ToolExecuteResult, type ToolExecution, type ToolMetadata, defineInput, definePlay, defineWorkflow, extractSummaryFields, formatPlayBootstrapFinderKinds, formatPlayBootstrapFinderKindsForSentence, formatPlayBootstrapTemplates, getDefinedPlayMetadata, isDeeplineExtractorTarget, isPlayBootstrapFinderKind, isPlayBootstrapTemplate, resolveConfig, runIf, steps, tryConvertToList, writeCsvOutputFile, writeJsonOutputFile };

package/dist/index.d.ts

@@ -46,7 +46,7 @@ interface PlaySheetContractSnapshot {
     tableNamespace: string;
     columns: PlaySheetColumnContractSnapshot[];
 }
-type PlayStaticColumnProducerKindSnapshot = 'tool' | 'waterfall' | 'stepProgram' | 'playCall' | 'transform';
+type PlayStaticColumnProducerKindSnapshot = 'tool' | 'waterfall' | 'stepProgram' | 'playCall' | 'controlFlow' | 'transform';
 interface PlayStaticColumnProducerSnapshot {
     id: string;
     kind: PlayStaticColumnProducerKindSnapshot;
@@ -148,6 +148,15 @@ type PlayStaticSubstepSnapshot = PlayStaticSubstepMetadataSnapshot & ({
     sourceRange?: PlayStaticSourceRangeSnapshot;
     callDepth?: number;
     callPath?: string[];
+} | {
+    type: 'control_flow';
+    kind: 'conditional' | 'loop';
+    field: string;
+    steps: PlayStaticSubstepSnapshot[];
+    description?: string;
+    sourceRange?: PlayStaticSourceRangeSnapshot;
+    callDepth?: number;
+    callPath?: string[];
 } | {
     type: 'run_javascript';
     alias: string;
@@ -646,6 +655,10 @@ interface PlayRunListItem {
     closeTime: string | null;
     /** Duration string (e.g. `'2.5s'`). */
     executionTime: string | null;
+    /** Total Deepline credits charged for the run, when available. */
+    billingTotalCredits?: number;
+    /** Configured per-run Deepline credit cap, when available. */
+    billingMaxCreditsPerRun?: number | null;
     /** Metadata attached to the workflow. */
     memo: {
         /** Organization that owns this run. */
@@ -2036,6 +2049,35 @@ interface PlayDataset<T> extends AsyncIterable<T> {
 
 type EmailStatusVerdict = 'send' | 'send_with_caution' | 'verify_next' | 'hold' | 'drop';
 type EmailStatusValue = 'valid' | 'invalid' | 'catch_all' | 'valid_catch_all' | 'unknown' | 'do_not_mail' | 'spamtrap' | 'abuse' | 'disposable';
+type EmailDeliverability = 'high' | 'medium' | 'low' | 'unknown';
+type EmailMxClass = 'consumer_mailbox' | 'workspace_mailbox' | 'security_gateway' | 'on_prem' | 'unknown';
+type EmailStatus = {
+    verdict: EmailStatusVerdict;
+    status: EmailStatusValue;
+    verified: boolean;
+    confidence: number | null;
+    reasons: string[];
+    signals: {
+        catch_all: boolean | null;
+        deliverability: EmailDeliverability;
+        mx_class: EmailMxClass;
+        mx_provider: string | null;
+        mx_record: string | null;
+        fraud_score: number | null;
+        disposable: boolean | null;
+        role_based: boolean | null;
+        free_email: boolean | null;
+        abuse: boolean | null;
+        spamtrap: boolean | null;
+        suspect: boolean | null;
+        valid: boolean | null;
+    };
+    provider: {
+        name: string;
+        raw_status: string | boolean | number | null;
+        raw_score: number | null;
+    };
+};
 type EmailStatusMapEntry = {
     status: EmailStatusValue;
     verdict?: EmailStatusVerdict;
@@ -2065,6 +2107,153 @@ type EmailStatusExtractorConfig = {
     rules?: EmailStatusRule[];
 };
 
+declare const JOB_CHANGE_STATUS_VALUES: readonly ["moved", "no_change", "left_company", "unknown", "profile_unavailable", "no_new_company"];
+type JobChangeStatus = (typeof JOB_CHANGE_STATUS_VALUES)[number];
+type JobChangeGetterValue = {
+    status: JobChangeStatus;
+    date: string | null;
+    new_company: string | null;
+    new_title: string | null;
+};
+declare const PHONE_STATUS_VALUES: readonly ["valid", "invalid", "unknown"];
+type PhoneStatus = (typeof PHONE_STATUS_VALUES)[number];
+declare const DEEPLINE_EXTRACTOR_TARGET_DEFINITIONS: {
+    readonly id: {
+        readonly identity: true;
+        readonly valueKind: "string";
+    };
+    readonly name: {
+        readonly identity: true;
+        readonly valueKind: "string";
+    };
+    readonly email: {
+        readonly identity: true;
+        readonly valueKind: "string";
+    };
+    readonly personal_email: {
+        readonly identity: true;
+        readonly valueKind: "string";
+    };
+    readonly phone: {
+        readonly identity: true;
+        readonly valueKind: "string";
+    };
+    readonly linkedin: {
+        readonly identity: true;
+        readonly valueKind: "string";
+    };
+    readonly linkedin_url: {
+        readonly identity: true;
+        readonly valueKind: "string";
+    };
+    readonly domain: {
+        readonly identity: true;
+        readonly valueKind: "string";
+    };
+    readonly website: {
+        readonly identity: true;
+        readonly valueKind: "string";
+    };
+    readonly first_name: {
+        readonly identity: true;
+        readonly valueKind: "string";
+    };
+    readonly last_name: {
+        readonly identity: true;
+        readonly valueKind: "string";
+    };
+    readonly full_name: {
+        readonly identity: true;
+        readonly valueKind: "string";
+    };
+    readonly company: {
+        readonly identity: true;
+        readonly valueKind: "string";
+    };
+    readonly company_name: {
+        readonly identity: true;
+        readonly valueKind: "string";
+    };
+    readonly organization_name: {
+        readonly identity: true;
+        readonly valueKind: "string";
+    };
+    readonly company_domain: {
+        readonly identity: true;
+        readonly valueKind: "string";
+    };
+    readonly company_website: {
+        readonly identity: true;
+        readonly valueKind: "string";
+    };
+    readonly company_linkedin_url: {
+        readonly identity: true;
+        readonly valueKind: "string";
+    };
+    readonly title: {
+        readonly identity: false;
+        readonly valueKind: "string";
+    };
+    readonly industry: {
+        readonly identity: false;
+        readonly valueKind: "string";
+    };
+    readonly status: {
+        readonly identity: false;
+        readonly valueKind: "string";
+    };
+    readonly job_change: {
+        readonly identity: false;
+        readonly valueKind: "job_change";
+    };
+    readonly job_change_status: {
+        readonly identity: false;
+        readonly valueKind: "job_change_status";
+        readonly enum: readonly ["moved", "no_change", "left_company", "unknown", "profile_unavailable", "no_new_company"];
+    };
+    readonly email_status: {
+        readonly identity: false;
+        readonly valueKind: "email_status";
+    };
+    readonly phone_status: {
+        readonly identity: false;
+        readonly valueKind: "phone_status";
+        readonly enum: readonly ["valid", "invalid", "unknown"];
+    };
+};
+type DeeplineExtractorTarget = keyof typeof DEEPLINE_EXTRACTOR_TARGET_DEFINITIONS;
+declare const DEEPLINE_EXTRACTOR_TARGETS: DeeplineExtractorTarget[];
+type DeeplineEmailStatusGetterValue = EmailStatus | EmailStatusValue;
+type DeeplineGetterValueMap = {
+    id: string;
+    name: string;
+    email: string;
+    personal_email: string;
+    phone: string;
+    linkedin: string;
+    linkedin_url: string;
+    domain: string;
+    website: string;
+    first_name: string;
+    last_name: string;
+    full_name: string;
+    company: string;
+    company_name: string;
+    organization_name: string;
+    company_domain: string;
+    company_website: string;
+    company_linkedin_url: string;
+    title: string;
+    industry: string;
+    status: string;
+    job_change: JobChangeGetterValue;
+    job_change_status: JobChangeStatus;
+    email_status: DeeplineEmailStatusGetterValue;
+    phone_status: PhoneStatus;
+};
+type DeeplineGetterValue<TTarget extends DeeplineExtractorTarget = DeeplineExtractorTarget> = DeeplineGetterValueMap[TTarget];
+declare function isDeeplineExtractorTarget(value: string): value is DeeplineExtractorTarget;
+
 type ToolResultExecutionMetadata = {
     idempotent: true;
     cached: boolean;
@@ -2128,7 +2317,7 @@ type ToolExecuteResultBase<TResult = unknown, TMeta = Record<string, unknown>> =
         }>;
     };
 };
-type ToolExecuteResultAccessors<TExtracted extends Record<string, unknown> = Record<string, unknown>, TLists extends Record<string, Record<string, unknown>> = Record<string, Record<string, unknown>>> = {
+type ToolExecuteResultAccessors<TExtracted extends Record<string, unknown> = Partial<DeeplineGetterValueMap>, TLists extends Record<string, Record<string, unknown>> = Record<string, Record<string, unknown>>> = {
     extractedValues: {
         [K in keyof TExtracted]: ToolResultTargetAccessor<TExtracted[K]>;
     };
@@ -2149,7 +2338,16 @@ type ToolExecuteResultAccessors<TExtracted extends Record<string, unknown> = Rec
  * `toolResponse.raw` when you need provider-specific fields or when debugging
  * from persisted run rows.
  */
-type ToolExecuteResult<TResult = unknown, TMeta = Record<string, unknown>, TExtracted extends Record<string, unknown> = Record<string, unknown>, TLists extends Record<string, Record<string, unknown>> = Record<string, Record<string, unknown>>> = ToolExecuteResultBase<TResult, TMeta> & ToolExecuteResultAccessors<TExtracted, TLists>;
+type ToolExecuteResult<TResult = unknown, TMeta = Record<string, unknown>, TExtracted extends Record<string, unknown> = Partial<DeeplineGetterValueMap>, TLists extends Record<string, Record<string, unknown>> = Record<string, Record<string, unknown>>> = ToolExecuteResultBase<TResult, TMeta> & ToolExecuteResultAccessors<TExtracted, TLists>;
+
+type StaleAfterSecondsResolver<Value = unknown> = (value: Value) => number | null;
+type AuthoredStaleAfterSeconds<Value = unknown> = number | StaleAfterSecondsResolver<Value>;
+type PreviousCell<Value = unknown> = {
+    value: Value;
+    completedAt?: number;
+    staleAt?: number | null;
+    staleAfterSeconds?: number;
+};
 
 /**
  * Optional trigger bindings for a play.
@@ -2247,7 +2445,25 @@ type ToolExecutionRequest = {
     description?: string;
     staleAfterSeconds?: number;
 };
-type StepResolver<Row, Value> = (row: Row, ctx: DeeplinePlayRuntimeContext, index: number) => Value | Promise<Value>;
+type StaleAfterSeconds<Value = unknown> = AuthoredStaleAfterSeconds<Value>;
+type StepResolver<Row, Value> = (row: Row, ctx: DeeplinePlayRuntimeContext, index: number, previousCell?: PreviousCell<Value>) => Value | Promise<Value>;
+type DatasetColumnRunInput<Row, Value> = {
+    row: Row;
+    ctx: DeeplinePlayRuntimeContext;
+    index: number;
+    /**
+     * The prior stored value for this exact row+column when the runtime has
+     * decided the cell is due to run again. `previousCell.value` is the same type
+     * this column returns; metadata such as `completedAt` and `staleAt` lives
+     * beside it and is not mixed into the value.
+     */
+    previousCell?: PreviousCell<Value>;
+};
+type DatasetColumnDefinition<Row, Value> = {
+    run: (input: DatasetColumnRunInput<Row, Value>) => Value | Promise<Value>;
+    readonly runIf?: (row: Row, index: number) => boolean | Promise<boolean>;
+    readonly staleAfterSeconds?: StaleAfterSeconds<Value>;
+};
 type ConditionalStepResolver<Row, Value, Else = null> = {
     readonly kind: 'conditional';
     readonly when: (row: Row, index: number) => boolean | Promise<boolean>;
@@ -2255,9 +2471,9 @@ type ConditionalStepResolver<Row, Value, Else = null> = {
     readonly elseValue: Else;
     else<ValueElse>(value: ValueElse): ConditionalStepResolver<Row, Value, ValueElse>;
 };
-type StepOptions<Row> = {
+type StepOptions<Row, Value = unknown> = {
     readonly runIf?: (row: Row, index: number) => boolean | Promise<boolean>;
-    readonly staleAfterSeconds?: number;
+    readonly staleAfterSeconds?: StaleAfterSeconds<Value>;
 };
 type StepProgram<Input, Output, Return = Output> = {
     readonly kind: 'steps';
@@ -2265,7 +2481,7 @@ type StepProgram<Input, Output, Return = Output> = {
     readonly returnResolver?: StepResolver<Output, Return>;
     readonly __inputType?: (input: Input) => void;
     step<Name extends string, Value>(name: Name, resolver: StepResolver<Output, Value> | ConditionalStepResolver<Output, Value> | StepProgramResolver<Output, Value>): StepProgram<Input, Output & Record<Name, Value>, Return>;
-    step<Name extends string, Value>(name: Name, resolver: StepResolver<Output, Value> | StepProgramResolver<Output, Value>, options: StepOptions<Output>): StepProgram<Input, Output & Record<Name, Value | null>, Return>;
+    step<Name extends string, Value>(name: Name, resolver: StepResolver<Output, Value> | StepProgramResolver<Output, Value>, options: StepOptions<Output, Value>): StepProgram<Input, Output & Record<Name, Value | null>, Return>;
     return<Value>(resolver: StepResolver<Output, Value>): StepProgram<Input, Output, Value>;
 };
 type StepProgramResolver<Input, Return> = {
@@ -2276,7 +2492,7 @@ type StepProgramResolver<Input, Return> = {
 };
 type PlayStepProgramStep = {
     readonly name: string;
-    readonly staleAfterSeconds?: number;
+    readonly staleAfterSeconds?: StaleAfterSeconds;
     readonly resolver: StepResolver<Record<string, unknown>, unknown> | ConditionalStepResolver<Record<string, unknown>, unknown> | StepProgramResolver<Record<string, unknown>, unknown>;
 };
 type ColumnResolver<Row, Value> = StepResolver<Row, Value> | ConditionalStepResolver<Row, Value> | StepProgramResolver<Row, Value>;
@@ -2296,7 +2512,11 @@ type DatasetBuilder<InputRow extends object, OutputRow extends object> = {
      * @returns The same dataset builder with the new column type.
      */
     withColumn<Name extends string, Value>(name: Name, resolver: ColumnResolver<OutputRow, Value>): DatasetBuilder<InputRow, OutputRow & Record<Name, Value>>;
-    withColumn<Name extends string, Value>(name: Name, resolver: StepResolver<OutputRow, Value> | StepProgramResolver<OutputRow, Value>, options: StepOptions<OutputRow>): DatasetBuilder<InputRow, OutputRow & Record<Name, Value | null>>;
+    withColumn<Name extends string, Value>(name: Name, definition: DatasetColumnDefinition<OutputRow, Value> & {
+        readonly runIf: (row: OutputRow, index: number) => boolean | Promise<boolean>;
+    }): DatasetBuilder<InputRow, OutputRow & Record<Name, Value | null>>;
+    withColumn<Name extends string, Value>(name: Name, definition: DatasetColumnDefinition<OutputRow, Value>): DatasetBuilder<InputRow, OutputRow & Record<Name, Value>>;
+    withColumn<Name extends string, Value>(name: Name, resolver: StepResolver<OutputRow, Value> | StepProgramResolver<OutputRow, Value>, options: StepOptions<OutputRow, Value>): DatasetBuilder<InputRow, OutputRow & Record<Name, Value | null>>;
     withColumns<Program extends StepProgram<OutputRow, object, unknown>>(program: Program): DatasetBuilder<InputRow, StepProgramOutput<Program>>;
     /** @deprecated Dataset `.step(...)` was replaced by `.withColumn(...)`. */
     step<Name extends string, Value>(name: Name, resolver: ColumnResolver<OutputRow, Value>): never;
@@ -3189,4 +3409,4 @@ declare function writeCsvOutputFile(rows: Array<Record<string, unknown>>, stem:
  */
 declare function extractSummaryFields(payload: unknown): Record<string, Scalar>;
 
-export { AuthError, type ClearPlayHistoryRequest, type ClearPlayHistoryResult, type ColumnMap, type ColumnResolver, type ConditionalStepResolver, ConfigError, type CsvInput, DEEPLINE_TOOL_CATEGORIES, type DatasetBuilder, Deepline, DeeplineClient, type DeeplineClientOptions, DeeplineContext, DeeplineError, type DeeplineNamedPlay, type DeeplinePlayRuntimeContext, type DeeplineToolCategory, type DefinePlayConfig, type DefinedPlay, type FileInput, type LiveEventEnvelope, 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 PlayBindings, type PlayBootstrapEntityKind, type PlayBootstrapFinderKind, type PlayDataset, type PlayDatasetInput, type PlayInputContract, type PlayJob, type PlayListItem, type PlayLiveEvent, type PlayRevisionSummary, type PlayRunResult, type PlayRunStart, type PlayStatus, type PlayStepProgramStep, type PrebuiltPlayRef, type PublishPlayVersionRequest, type PublishPlayVersionResult, RateLimitError, type ResolvedConfig, SDK_API_CONTRACT, SDK_VERSION, type StartPlayRunRequest, type StepProgram, type StepProgramResolver, type StepResolver, type ToolDefinition, type ToolExecuteResult, type ToolExecution, type ToolMetadata, defineInput, definePlay, defineWorkflow, extractSummaryFields, formatPlayBootstrapFinderKinds, formatPlayBootstrapFinderKindsForSentence, formatPlayBootstrapTemplates, getDefinedPlayMetadata, isPlayBootstrapFinderKind, isPlayBootstrapTemplate, resolveConfig, runIf, steps, tryConvertToList, writeCsvOutputFile, writeJsonOutputFile };
+export { AuthError, type ClearPlayHistoryRequest, type ClearPlayHistoryResult, type ColumnMap, type ColumnResolver, type ConditionalStepResolver, ConfigError, type CsvInput, DEEPLINE_EXTRACTOR_TARGETS, DEEPLINE_EXTRACTOR_TARGET_DEFINITIONS, DEEPLINE_TOOL_CATEGORIES, type DatasetBuilder, Deepline, DeeplineClient, type DeeplineClientOptions, DeeplineContext, type DeeplineEmailStatusGetterValue, DeeplineError, type DeeplineExtractorTarget, type DeeplineGetterValue, type DeeplineGetterValueMap, type DeeplineNamedPlay, type DeeplinePlayRuntimeContext, type DeeplineToolCategory, type DefinePlayConfig, type DefinedPlay, type FileInput, 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 PlayDataset, type PlayDatasetInput, type PlayInputContract, type PlayJob, type PlayListItem, type PlayLiveEvent, type PlayRevisionSummary, type PlayRunResult, type PlayRunStart, type PlayStatus, type PlayStepProgramStep, type PrebuiltPlayRef, type PublishPlayVersionRequest, type PublishPlayVersionResult, RateLimitError, type ResolvedConfig, SDK_API_CONTRACT, SDK_VERSION, type StartPlayRunRequest, type StepProgram, type StepProgramResolver, type StepResolver, type ToolDefinition, type ToolExecuteResult, type ToolExecution, type ToolMetadata, defineInput, definePlay, defineWorkflow, extractSummaryFields, formatPlayBootstrapFinderKinds, formatPlayBootstrapFinderKindsForSentence, formatPlayBootstrapTemplates, getDefinedPlayMetadata, isDeeplineExtractorTarget, isPlayBootstrapFinderKind, isPlayBootstrapTemplate, resolveConfig, runIf, steps, tryConvertToList, writeCsvOutputFile, writeJsonOutputFile };