deepline 0.2.13 → 0.2.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (34) hide show
  1. package/dist/bundling-sources/sdk/src/index.ts +3 -0
  2. package/dist/bundling-sources/sdk/src/play.ts +150 -691
  3. package/dist/bundling-sources/sdk/src/release.ts +1 -1
  4. package/dist/bundling-sources/shared_libs/play-runtime/child-execution-strategy.ts +7 -1
  5. package/dist/bundling-sources/shared_libs/play-runtime/context.ts +249 -51
  6. package/dist/bundling-sources/shared_libs/play-runtime/csv-rename.ts +10 -6
  7. package/dist/bundling-sources/shared_libs/play-runtime/ctx-types.ts +32 -51
  8. package/dist/bundling-sources/shared_libs/play-runtime/durable-call-cache.ts +11 -22
  9. package/dist/bundling-sources/shared_libs/play-runtime/durable-call-policy.ts +34 -0
  10. package/dist/bundling-sources/shared_libs/play-runtime/play-call-execution.ts +2 -1
  11. package/dist/bundling-sources/shared_libs/play-runtime/run-ledger-projection-contract.ts +95 -0
  12. package/dist/bundling-sources/shared_libs/play-runtime/secret-capability.ts +23 -15
  13. package/dist/bundling-sources/shared_libs/plays/artifact-types.ts +3 -0
  14. package/dist/bundling-sources/shared_libs/plays/authoring-contract.ts +2222 -0
  15. package/dist/bundling-sources/shared_libs/plays/bundling/index.ts +3 -2
  16. package/dist/bundling-sources/shared_libs/plays/compiler-manifest.ts +2 -0
  17. package/dist/bundling-sources/shared_libs/plays/contracts.ts +16 -0
  18. package/dist/bundling-sources/shared_libs/plays/input-contract-definition.ts +28 -0
  19. package/dist/bundling-sources/shared_libs/plays/input-contract.ts +3 -3
  20. package/dist/cli/index.js +5074 -829
  21. package/dist/cli/index.mjs +5019 -759
  22. package/dist/compiler-manifest-xFkbJX2B.d.mts +2517 -0
  23. package/dist/compiler-manifest-xFkbJX2B.d.ts +2517 -0
  24. package/dist/index.d.mts +36 -1011
  25. package/dist/index.d.ts +36 -1011
  26. package/dist/index.js +25 -7
  27. package/dist/index.mjs +25 -7
  28. package/dist/plays/bundle-play-file.d.mts +5 -8
  29. package/dist/plays/bundle-play-file.d.ts +5 -8
  30. package/dist/plays/bundle-play-file.mjs +3844 -3
  31. package/package.json +1 -1
  32. package/dist/bundling-sources/shared_libs/plays/source-metadata.ts +0 -240
  33. package/dist/tool-execution-error-4-rhemLQ.d.mts +0 -446
  34. package/dist/tool-execution-error-4-rhemLQ.d.ts +0 -446
package/dist/index.d.ts CHANGED
@@ -1,5 +1,6 @@
1
- import { c as PlayRuntimeBackendId, a as PlayCompilerManifest, D as DeeplineError, d as ToolExecutionError, e as ToolExecutionErrorOptions, T as ToolExecutionErrorSchemaVersion } from './tool-execution-error-4-rhemLQ.js';
2
- export { f as ProviderTransientError, g as ProviderTransientErrorCategory, h as ToolExecutionErrorCategory, i as ToolExecutionErrorOrigin, j as ToolExecutionFailureV1, k as ToolExecutionNetworkKind, l as ToolExecutionNetworkScope } from './tool-execution-error-4-rhemLQ.js';
1
+ import { e as PlayRuntimeBackendId, c as PlayCompilerManifest, D as DeeplineError, f as ToolExecutionError, g as ToolExecutionErrorOptions, h as PlayAuthoringColumnMap, i as PlayAuthoringColumnResolver, j as PlayAuthoringRuntimeContext, k as PlayAuthoringConditionalStepResolver, l as PlayAuthoringCsvInput, m as PlayAuthoringCsvOptions, n as PlayAuthoringDatasetBuilder, o as PlayAuthoringDatasetColumnDefinition, p as PlayAuthoringDatasetColumnRunInput, q as ToolExecuteResult, r as PlayAuthoringReferenceLike, s as PlayReturnObject$1, t as PlayAuthoringDefineConfig, u as PlayAuthoringDefinedPlay, v as PlayAuthoringFetchOptions, w as PlayAuthoringFileInput, x as PlayAuthoringBindings, y as PlayAuthoringCallExecution, z as PlayAuthoringCallOptions, A as PlayAuthoringFetchResponse, B as PlayAuthoringInputContract, C as PlayAuthoringStepProgramStep, E as PlayAuthoringRuntimeStepOptions, F as PlaySqlListenerDeclaration, G as PlaySqlListenerEvent, H as PlaySqlListenerOperation, I as PlaySqlQuery, J as PlayAuthoringStepOptions, K as PlayAuthoringStepProgram, L as PlayAuthoringStepProgramResolver, M as PlayAuthoringStepResolver, N as PlayToolExecutionRequest } from './compiler-manifest-xFkbJX2B.js';
2
+ export { O as DEEPLINE_EXTRACTOR_TARGETS, Q as DEEPLINE_EXTRACTOR_TARGET_DEFINITIONS, R as DeeplineEmailStatusGetterValue, S as DeeplineExtractorTarget, U as DeeplineGetterValue, V as DeeplineGetterValueMap, W as JOB_CHANGE_STATUS_VALUES, X as JobChangeStatus, Y as PHONE_STATUS_VALUES, Z as PhoneStatus, _ as PlayDataset, $ as PlayDatasetInput, a0 as PreviousCell, a1 as ProviderTransientError, a2 as ProviderTransientErrorCategory, a3 as ToolExecutionErrorCategory, a4 as ToolExecutionErrorOrigin, a5 as ToolExecutionFailureV1, a6 as ToolExecutionNetworkKind, a7 as ToolExecutionNetworkScope, a8 as isDeeplineExtractorTarget } from './compiler-manifest-xFkbJX2B.js';
3
+ import '@sinclair/typebox';
3
4
 
4
5
  type PlayRuntimeSelection = {
5
6
  environment: 'preview';
@@ -3453,446 +3454,11 @@ declare const PROD_URL = "https://code.deepline.com";
3453
3454
  */
3454
3455
  declare function resolveConfig(options?: DeeplineClientOptions): ResolvedConfig;
3455
3456
 
3456
- type EmailStatusVerdict = 'send' | 'send_with_caution' | 'verify_next' | 'hold' | 'drop';
3457
- type EmailStatusValue = 'valid' | 'invalid' | 'catch_all' | 'valid_catch_all' | 'unknown' | 'do_not_mail' | 'spamtrap' | 'abuse' | 'disposable';
3458
- type EmailDeliverability = 'high' | 'medium' | 'low' | 'unknown';
3459
- type EmailMxClass = 'consumer_mailbox' | 'workspace_mailbox' | 'security_gateway' | 'on_prem' | 'unknown';
3460
- type EmailStatus = {
3461
- verdict: EmailStatusVerdict;
3462
- status: EmailStatusValue;
3463
- verified: boolean;
3464
- confidence: number | null;
3465
- reasons: string[];
3466
- signals: {
3467
- catch_all: boolean | null;
3468
- deliverability: EmailDeliverability;
3469
- mx_class: EmailMxClass;
3470
- mx_provider: string | null;
3471
- mx_record: string | null;
3472
- fraud_score: number | null;
3473
- disposable: boolean | null;
3474
- role_based: boolean | null;
3475
- free_email: boolean | null;
3476
- abuse: boolean | null;
3477
- spamtrap: boolean | null;
3478
- suspect: boolean | null;
3479
- valid: boolean | null;
3480
- };
3481
- provider: {
3482
- name: string;
3483
- raw_status: string | boolean | number | null;
3484
- raw_score: number | null;
3485
- };
3486
- };
3487
- type EmailStatusMapEntry = {
3488
- status: EmailStatusValue;
3489
- verdict?: EmailStatusVerdict;
3490
- verified?: boolean;
3491
- reason?: string;
3492
- };
3493
- type EmailStatusRule = EmailStatusMapEntry & {
3494
- when: Record<string, string | number | boolean | null>;
3495
- };
3496
- type EmailStatusExtractorConfig = {
3497
- provider: string;
3498
- rawStatus?: string[];
3499
- rawScore?: string[];
3500
- valid?: string[];
3501
- deliverability?: string[];
3502
- catchAll?: string[];
3503
- mxProvider?: string[];
3504
- mxRecord?: string[];
3505
- fraudScore?: string[];
3506
- disposable?: string[];
3507
- roleBased?: string[];
3508
- freeEmail?: string[];
3509
- abuse?: string[];
3510
- spamtrap?: string[];
3511
- suspect?: string[];
3512
- statusMap?: Record<string, EmailStatusMapEntry>;
3513
- rules?: EmailStatusRule[];
3514
- };
3515
-
3516
- declare const JOB_CHANGE_STATUS_VALUES: readonly ["moved", "no_change", "left_company", "unknown", "profile_unavailable", "no_new_company"];
3517
- type JobChangeStatus = (typeof JOB_CHANGE_STATUS_VALUES)[number];
3518
- type JobChangeGetterValue = {
3519
- status: JobChangeStatus;
3520
- date: string | null;
3521
- new_company: string | null;
3522
- new_title: string | null;
3523
- };
3524
- declare const PHONE_STATUS_VALUES: readonly ["valid", "invalid", "unknown"];
3525
- type PhoneStatus = (typeof PHONE_STATUS_VALUES)[number];
3526
- declare const DEEPLINE_EXTRACTOR_TARGET_DEFINITIONS: {
3527
- readonly id: {
3528
- readonly identity: true;
3529
- readonly valueKind: "string";
3530
- };
3531
- readonly name: {
3532
- readonly identity: true;
3533
- readonly valueKind: "string";
3534
- };
3535
- readonly email: {
3536
- readonly identity: true;
3537
- readonly valueKind: "string";
3538
- };
3539
- readonly personal_email: {
3540
- readonly identity: true;
3541
- readonly valueKind: "string";
3542
- };
3543
- readonly phone: {
3544
- readonly identity: true;
3545
- readonly valueKind: "string";
3546
- };
3547
- readonly linkedin: {
3548
- readonly identity: true;
3549
- readonly valueKind: "string";
3550
- };
3551
- readonly linkedin_url: {
3552
- readonly identity: true;
3553
- readonly valueKind: "string";
3554
- };
3555
- readonly domain: {
3556
- readonly identity: true;
3557
- readonly valueKind: "string";
3558
- };
3559
- readonly website: {
3560
- readonly identity: true;
3561
- readonly valueKind: "string";
3562
- };
3563
- readonly first_name: {
3564
- readonly identity: true;
3565
- readonly valueKind: "string";
3566
- };
3567
- readonly last_name: {
3568
- readonly identity: true;
3569
- readonly valueKind: "string";
3570
- };
3571
- readonly full_name: {
3572
- readonly identity: true;
3573
- readonly valueKind: "string";
3574
- };
3575
- readonly company: {
3576
- readonly identity: true;
3577
- readonly valueKind: "string";
3578
- };
3579
- readonly company_name: {
3580
- readonly identity: true;
3581
- readonly valueKind: "string";
3582
- };
3583
- readonly organization_name: {
3584
- readonly identity: true;
3585
- readonly valueKind: "string";
3586
- };
3587
- readonly company_domain: {
3588
- readonly identity: true;
3589
- readonly valueKind: "string";
3590
- };
3591
- readonly company_website: {
3592
- readonly identity: true;
3593
- readonly valueKind: "string";
3594
- };
3595
- readonly company_linkedin_url: {
3596
- readonly identity: true;
3597
- readonly valueKind: "string";
3598
- };
3599
- readonly title: {
3600
- readonly identity: false;
3601
- readonly valueKind: "string";
3602
- };
3603
- readonly industry: {
3604
- readonly identity: false;
3605
- readonly valueKind: "string";
3606
- };
3607
- readonly status: {
3608
- readonly identity: false;
3609
- readonly valueKind: "string";
3610
- };
3611
- readonly job_change: {
3612
- readonly identity: false;
3613
- readonly valueKind: "job_change";
3614
- };
3615
- readonly job_change_status: {
3616
- readonly identity: false;
3617
- readonly valueKind: "job_change_status";
3618
- readonly enum: readonly ["moved", "no_change", "left_company", "unknown", "profile_unavailable", "no_new_company"];
3619
- };
3620
- readonly email_status: {
3621
- readonly identity: false;
3622
- readonly valueKind: "email_status";
3623
- };
3624
- readonly phone_status: {
3625
- readonly identity: false;
3626
- readonly valueKind: "phone_status";
3627
- readonly enum: readonly ["valid", "invalid", "unknown"];
3628
- };
3629
- };
3630
- type DeeplineExtractorTarget = keyof typeof DEEPLINE_EXTRACTOR_TARGET_DEFINITIONS;
3631
- declare const DEEPLINE_EXTRACTOR_TARGETS: DeeplineExtractorTarget[];
3632
- type DeeplineEmailStatusGetterValue = EmailStatus;
3633
- type DeeplineGetterValueMap = {
3634
- id: string;
3635
- name: string;
3636
- email: string;
3637
- personal_email: string;
3638
- phone: string;
3639
- linkedin: string;
3640
- linkedin_url: string;
3641
- domain: string;
3642
- website: string;
3643
- first_name: string;
3644
- last_name: string;
3645
- full_name: string;
3646
- company: string;
3647
- company_name: string;
3648
- organization_name: string;
3649
- company_domain: string;
3650
- company_website: string;
3651
- company_linkedin_url: string;
3652
- title: string;
3653
- industry: string;
3654
- status: string;
3655
- job_change: JobChangeGetterValue;
3656
- job_change_status: JobChangeStatus;
3657
- email_status: EmailStatus;
3658
- phone_status: PhoneStatus;
3659
- };
3660
- type DeeplineGetterValue<TTarget extends DeeplineExtractorTarget = DeeplineExtractorTarget> = DeeplineGetterValueMap[TTarget];
3661
- declare function isDeeplineExtractorTarget(value: string): value is DeeplineExtractorTarget;
3662
-
3663
- interface PlayR2FileRef {
3664
- storageKind: 'r2';
3665
- storageKey: string;
3666
- logicalPath: string;
3667
- fileName: string;
3668
- contentHash: string;
3669
- contentType: string;
3670
- bytes: number;
3671
- }
3672
- type PlayExecutionFileRef = PlayR2FileRef;
3673
-
3674
- declare const PLAY_DATASET_BRAND: unique symbol;
3675
- type PlayDatasetKind = 'csv' | 'map';
3676
- type PlayDatasetBacking = {
3677
- storage: 'neon_sheet';
3678
- sheet: {
3679
- playName: string;
3680
- tableNamespace: string;
3681
- };
3682
- } | {
3683
- storage: 'r2_file';
3684
- file: PlayExecutionFileRef;
3685
- };
3686
- type PlayDatasetWorkProgressSummary = {
3687
- total: number;
3688
- executed: number;
3689
- reused: number;
3690
- skipped: number;
3691
- pending: number;
3692
- failed: number;
3693
- degraded?: boolean;
3694
- duplicates?: {
3695
- exact?: number;
3696
- semantic?: number;
3697
- rejected?: number;
3698
- };
3699
- };
3700
- type PlayDatasetInput<T> = ReadonlyArray<T> | Iterable<T> | AsyncIterable<T> | PlayDataset<T>;
3701
- type PlayDatasetRow<TInput> = TInput extends PlayDataset<infer Row> ? Row : TInput extends ReadonlyArray<infer Row> ? Row : TInput extends Iterable<infer Row> ? Row : TInput extends AsyncIterable<infer Row> ? Row : never;
3702
- type PlayDatasetTransformOptions = {
3703
- key?: string;
3704
- sourceLabel?: string | null;
3705
- };
3706
- /**
3707
- * Durable handle for rows produced by `ctx.csv(...)` or `ctx.dataset(...).run()`.
3708
- *
3709
- * A `PlayDataset` is not a normal in-memory array. It points at runtime-managed
3710
- * rows, usually backed by persisted sheet storage, and carries metadata such as
3711
- * dataset kind, dataset id, table namespace, count, and preview rows.
3712
- *
3713
- * Pass dataset handles directly into later `ctx.dataset(...)` stages by default so
3714
- * Deepline keeps row progress, retries, memory use, and table output under
3715
- * runtime control. Use `count()` and `peek()` for bounded inspection. Use
3716
- * `materialize(limit)` or async iteration only when the dataset is intentionally
3717
- * small and bounded. `PlayDataset` intentionally does not expose `.rows`,
3718
- * `.toArray()`, `.length`, numeric indexing, spread, or synchronous iteration;
3719
- * those hide the runtime cost of loading persisted rows into memory or make
3720
- * behavior depend on whether rows happen to be resident.
3721
- *
3722
- * @sdkReference runtime 190
3723
- */
3724
- interface PlayDataset<T> extends AsyncIterable<T> {
3725
- readonly [PLAY_DATASET_BRAND]: true;
3726
- /** Dataset kind. */
3727
- readonly datasetKind: PlayDatasetKind;
3728
- /** Dataset id. */
3729
- readonly datasetId: string;
3730
- /** Backing store info. */
3731
- readonly backing?: PlayDatasetBacking;
3732
- /** Display label. */
3733
- readonly sourceLabel?: string | null;
3734
- /** Runtime table name. */
3735
- readonly tableNamespace?: string | null;
3736
- /** Row count. */
3737
- count(): Promise<number>;
3738
- /** Preview rows. */
3739
- peek(limit?: number): Promise<T[]>;
3740
- /** First row, loading it asynchronously when necessary. */
3741
- first(): Promise<T | undefined>;
3742
- /** Row at an array-style index, loading it asynchronously when necessary. */
3743
- at(index: number): Promise<T | undefined>;
3744
- map<U>(mapper: (row: T, index: number) => U | Promise<U>, options?: PlayDatasetTransformOptions): PlayDataset<U>;
3745
- filter(predicate: (row: T, index: number) => boolean | Promise<boolean>, options?: PlayDatasetTransformOptions): PlayDataset<T>;
3746
- slice(start?: number, end?: number, options?: PlayDatasetTransformOptions): PlayDataset<T>;
3747
- take(limit: number, options?: PlayDatasetTransformOptions): PlayDataset<T>;
3748
- /**
3749
- * Explicit escape hatch for bounded result sets.
3750
- * Large datasets should flow by handle through Neon-backed storage, not
3751
- * through worker memory as giant arrays.
3752
- */
3753
- materialize(options?: number | PlayDatasetMaterializeOptions): Promise<T[]>;
3754
- toJSON(): {
3755
- kind: 'dataset';
3756
- datasetKind: PlayDatasetKind;
3757
- datasetId: string;
3758
- count: number;
3759
- backing?: PlayDatasetBacking;
3760
- sourceLabel?: string | null;
3761
- tableNamespace?: string | null;
3762
- columns?: string[];
3763
- _metadata?: {
3764
- workProgress?: PlayDatasetWorkProgressSummary;
3765
- };
3766
- preview: T[];
3767
- };
3768
- }
3769
- type PlayDatasetMaterializeScope = 'result' | 'full_persisted_dataset';
3770
- type PlayDatasetMaterializeOptions = {
3771
- /** Rows returned by this operation, or every current row in its persisted dataset. */
3772
- scope?: PlayDatasetMaterializeScope;
3773
- /** Maximum number of rows to load into memory. */
3774
- limit?: number;
3775
- };
3776
-
3777
- type ToolResultExecutionMetadata = {
3778
- idempotent: true;
3779
- cached: boolean;
3780
- source: 'live' | 'checkpoint' | 'cache' | 'in_flight';
3781
- cacheKey?: string;
3782
- receiptRole?: 'owner' | 'follower';
3783
- receiptKey?: string;
3784
- attachedToReceiptKey?: string;
3785
- };
3786
- type ToolResultTargetMetadata = {
3787
- value: unknown;
3788
- path: string;
3789
- };
3790
- type ToolResultListMetadata = {
3791
- path: string;
3792
- count: number | null;
3793
- keys: Record<string, string>;
3794
- };
3795
- type ToolResultExtractorDescriptor = {
3796
- paths: readonly string[];
3797
- transforms?: readonly string[];
3798
- enum?: readonly string[];
3799
- overrides?: readonly ToolResultExtractorOverride[];
3800
- emailStatus?: EmailStatusExtractorConfig;
3801
- };
3802
- type ToolResultExtractorOverride = {
3803
- paths: readonly string[];
3804
- equals?: string | number | boolean | null;
3805
- value: string | number | boolean | null;
3806
- };
3807
- type ToolResultTargetAccessor<T = unknown> = ToolResultTargetMetadata & {
3808
- get(): T | null;
3809
- };
3810
- type ToolResultListAccessor<T = Record<string, unknown>, TKey extends string = string> = Omit<ToolResultListMetadata, 'keys'> & {
3811
- keys: Partial<Record<TKey, string>> & Record<string, string>;
3812
- get(): PlayDataset<T>;
3813
- };
3814
- type ToolResponseEnvelope<TData = unknown, TMeta = Record<string, unknown>> = {
3815
- raw: TData;
3816
- meta?: TMeta;
3817
- };
3818
- type ToolExecuteResultBase<TResult = unknown, TMeta = Record<string, unknown>> = {
3819
- status: string;
3820
- job_id?: string;
3821
- /** Deepline-owned execution/result metadata. */
3822
- meta?: Record<string, unknown>;
3823
- toolResponse: ToolResponseEnvelope<TResult, TMeta>;
3824
- extractedValues: Record<string, ToolResultTargetAccessor>;
3825
- extractedLists: Record<string, ToolResultListAccessor>;
3826
- /** Convenience alias for play code. Serialized output uses toolResponse. */
3827
- toolOutput: ToolResponseEnvelope<TResult, TMeta>;
3828
- _metadata: {
3829
- toolId: string;
3830
- execution: ToolResultExecutionMetadata;
3831
- targets: Record<string, {
3832
- value: unknown;
3833
- path: string;
3834
- }>;
3835
- extractors?: Record<string, ToolResultExtractorDescriptor>;
3836
- lists: Record<string, {
3837
- path: string;
3838
- count: number | null;
3839
- keys: Record<string, string>;
3840
- }>;
3841
- /** Original declarations preserve semantic accessor names across replay. */
3842
- listExtractorPaths?: readonly string[];
3843
- };
3844
- };
3845
- type ToolExecuteResultAccessors<TExtracted extends Record<string, unknown> = Partial<DeeplineGetterValueMap>, TLists extends Record<string, Record<string, unknown>> = Record<string, Record<string, unknown>>> = {
3846
- extractedValues: {
3847
- [K in keyof TExtracted]: ToolResultTargetAccessor<TExtracted[K]>;
3848
- };
3849
- extractedLists: {
3850
- [K in keyof TLists]: ToolResultListAccessor<TLists[K]>;
3851
- };
3852
- };
3853
- /**
3854
- * Canonical result returned by Deepline tool execution.
3855
- *
3856
- * The top-level object is Deepline-owned execution metadata and semantic
3857
- * extraction state. Raw tool/provider data lives under `toolResponse.raw`;
3858
- * response metadata lives under `toolResponse.meta`. Semantic single-value
3859
- * getters live under `extractedValues.<name>.get()`, and list getters live
3860
- * under `extractedLists.<name>.get()`.
3861
- *
3862
- * Use extractors first when a tool contract exposes them. Use list getters for
3863
- * row-shaped data. Drop to `toolResponse.raw` only for provider-specific scalar
3864
- * fields or bounded debugging context; persisted rows may clip declared lists to
3865
- * previews.
3866
- *
3867
- * @sdkReference runtime 200
3868
- */
3869
- 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>;
3870
-
3871
- /**
3872
- * Previous durable cell value passed to object-column resolvers.
3873
- *
3874
- * The runtime supplies this when a row+column is being recomputed after a
3875
- * previous value existed. `value` has the same type that the column returns;
3876
- * freshness metadata lives beside it.
3877
- *
3878
- * @sdkReference runtime 120
3879
- */
3880
- type PreviousCell<Value = unknown> = {
3881
- /** Previous completed value for this row+column. */
3882
- value: Value;
3883
- /** Millisecond timestamp when the previous value completed. */
3884
- completedAt?: number;
3885
- /** Millisecond timestamp when the previous value becomes stale; `null` means no expiry. */
3886
- staleAt?: number | null;
3887
- /** Resolved numeric TTL in seconds for the previous value, when present. */
3888
- staleAfterSeconds?: number;
3889
- };
3890
-
3891
- type PlayCallExecution = 'inline' | 'child-workflow';
3892
- interface PlayCallOptions {
3893
- description: string;
3894
- execution?: PlayCallExecution;
3895
- }
3457
+ type PlayCallExecution = PlayAuthoringCallExecution;
3458
+ type PlayCallOptions = PlayAuthoringCallOptions;
3459
+ type RuntimeStepOptions = PlayAuthoringRuntimeStepOptions;
3460
+ type FetchOptions = PlayAuthoringFetchOptions;
3461
+ type PlayFetchResponse = PlayAuthoringFetchResponse;
3896
3462
  /**
3897
3463
  * Optional trigger bindings for a play.
3898
3464
  *
@@ -3943,134 +3509,12 @@ interface PlayCallOptions {
3943
3509
  *
3944
3510
  * @sdkReference runtime 030
3945
3511
  */
3946
- type PlayBindings = {
3947
- /**
3948
- * Human-readable one-line description of what this play does.
3949
- *
3950
- * New SDK-authored file workflows require this in `plays check`, `plays run
3951
- * --file`, and `plays publish <file>`. The server API keeps it optional so
3952
- * older clients can continue to register revisions during the migration.
3953
- */
3954
- description?: string;
3955
- /**
3956
- * Public behavior that must remain pinned for this play artifact.
3957
- *
3958
- * New plays default to typed tool errors (`1`). Set `toolErrorSchemaVersion`
3959
- * to `0` only while migrating code that depends on legacy error names,
3960
- * messages, or classes.
3961
- */
3962
- compatibility?: {
3963
- toolErrorSchemaVersion: ToolExecutionErrorSchemaVersion;
3964
- };
3965
- /** Allow compilers to bundle this named handler directly without a child run. */
3966
- inline?: boolean;
3967
- /** Optional per-run billing controls enforced by the runtime. */
3968
- billing?: {
3969
- /** Stop the run before a billed action would push total run credits above this cap. */
3970
- maxCreditsPerRun?: number;
3971
- };
3972
- /** Requested prebuilt sandbox and runtime deadline. */
3973
- runtime?: {
3974
- /** Duration such as `"90m"` or `"2h"`. */
3975
- timeout?: string;
3976
- /** Deepline-managed prebuilt sandbox size. */
3977
- size?: 'standard';
3978
- };
3979
- /** Webhook trigger with optional HMAC signature verification. */
3980
- webhook?: {
3981
- hmac?: {
3982
- /** Hash algorithm. Currently only `'sha256'` is supported. */
3983
- algorithm?: 'sha256';
3984
- /** HTTP header containing the signature (e.g. `'X-Hub-Signature-256'`). */
3985
- header?: string;
3986
- /** Environment variable name holding the HMAC secret. */
3987
- secretEnv: string;
3988
- };
3989
- };
3990
- /** Cron schedule trigger. */
3991
- cron?: {
3992
- /** Cron expression (e.g. `'0 9 * * *'` for daily at 9am). */
3993
- schedule: string;
3994
- /** IANA timezone (e.g. `'America/New_York'`). Defaults to UTC. */
3995
- timezone?: string;
3996
- };
3997
- /** Customer DB row-change listeners that wake this play when published. */
3998
- sqlListeners?: SqlListenerDeclaration[];
3999
- /**
4000
- * Customer-authored play secrets this play is allowed to use at runtime.
4001
- * Values are never bundled or exposed by the SDK; access them with
4002
- * `ctx.secrets.get("NAME")` and approved helpers such as
4003
- * `ctx.secrets.bearer(handle)`. Secret-authenticated `ctx.fetch` calls
4004
- * require an https:// URL so customer secrets never leave Deepline over
4005
- * plaintext HTTP.
4006
- */
4007
- secrets?: readonly string[];
4008
- };
4009
- type SqlListenerOperation = 'INSERT' | 'UPDATE' | 'DELETE';
4010
- type SqlListenerFilterScalar = string | number | boolean | null;
4011
- type SqlListenerFilterOperator = {
4012
- eq?: SqlListenerFilterScalar;
4013
- neq?: SqlListenerFilterScalar;
4014
- in?: SqlListenerFilterScalar[];
4015
- notIn?: SqlListenerFilterScalar[];
4016
- isNull?: true;
4017
- isNotNull?: true;
4018
- ilike?: string;
4019
- };
4020
- type SqlListenerWhere = {
4021
- before?: Record<string, SqlListenerFilterOperator>;
4022
- after?: Record<string, SqlListenerFilterOperator>;
4023
- };
4024
- type SqlListenerDeclaration = {
4025
- /** Short id unique inside this play. Deepline stores it as playName.id. */
4026
- id: string;
4027
- /** Modeled monitor tool id, for example "deepline_native.company_radar". */
4028
- tool: string;
4029
- /** Stream key exposed by the modeled monitor tool, for example "company_job_openings". */
4030
- stream: string;
4031
- /** Row operations that should wake this play. Defaults to INSERT and UPDATE. */
4032
- operations?: SqlListenerOperation[];
4033
- /** Optional DB-side row filter over top-level before/after fields. */
4034
- where?: SqlListenerWhere;
4035
- };
4036
- type SqlListenerEvent<T extends object = Record<string, unknown>> = {
4037
- tool: string;
4038
- stream: string;
4039
- operation: SqlListenerOperation;
4040
- before: T | null;
4041
- after: T | null;
4042
- changedAt: string;
4043
- metadata: {
4044
- outboxId: string;
4045
- listenerId: string;
4046
- table: string;
4047
- };
4048
- };
4049
- type SqlQuery = {
4050
- readonly kind: 'sql.query';
4051
- readonly text: string;
4052
- readonly values: readonly unknown[];
4053
- };
4054
- declare const SECRET_HANDLE_BRAND: unique symbol;
4055
- type SecretHandle = {
4056
- readonly [SECRET_HANDLE_BRAND]: never;
4057
- readonly name: string;
4058
- toString(): string;
4059
- toJSON(): never;
4060
- };
4061
- type SecretAuth = {
4062
- readonly kind: 'bearer' | 'header';
4063
- readonly secret: SecretHandle;
4064
- readonly header?: string;
4065
- };
4066
- type SecretAwareRequestInit = Omit<RequestInit, 'headers'> & {
4067
- headers?: HeadersInit;
4068
- auth?: SecretAuth;
4069
- };
4070
- type LoosePlayObject = {
4071
- [key: string]: LoosePlayObject;
4072
- };
4073
-
3512
+ type PlayBindings = PlayAuthoringBindings;
3513
+ type SqlListenerOperation = PlaySqlListenerOperation;
3514
+ type SqlListenerDeclaration = PlaySqlListenerDeclaration;
3515
+ type SqlListenerEvent<T extends object = Record<string, unknown>> = PlaySqlListenerEvent<T>;
3516
+ /** @deprecated Pass a SQL string directly to ctx.customerDb.query. */
3517
+ type SqlQuery = PlaySqlQuery;
4074
3518
  /**
4075
3519
  * Keyword-style request object for `ctx.tools.execute(...)`.
4076
3520
  *
@@ -4081,45 +3525,14 @@ type LoosePlayObject = {
4081
3525
  *
4082
3526
  * @sdkReference runtime 160
4083
3527
  */
4084
- type ToolExecutionRequest = {
4085
- /** Stable logical id for logs, metadata, and receipt attachment. */
4086
- id: string;
4087
- /** Current tool id from `deepline tools search` / `deepline tools describe`. */
4088
- tool: string;
4089
- /** JSON-serializable provider/tool input object. */
4090
- input: Record<string, unknown>;
4091
- /** Human-readable description for logs and run inspection. */
4092
- description?: string;
4093
- /** Recompute this tool call instead of reusing a durable receipt/checkpoint. */
4094
- force?: boolean;
4095
- /** Numeric TTL in seconds for this tool checkpoint. */
4096
- staleAfterSeconds?: number;
4097
- /** Runtime transport timeout in milliseconds. This is not sent to the provider. */
4098
- timeoutMs?: number;
4099
- /** Follower wait budget in milliseconds before a running receipt is reclaimable. */
4100
- receiptWaitMs?: number;
4101
- };
4102
- type StepResolver<Row, Value> = (row: Row, ctx: DeeplinePlayRuntimeContext, index: number, previousCell?: PreviousCell<Value>) => Value | Promise<Value>;
3528
+ type ToolExecutionRequest = PlayToolExecutionRequest;
3529
+ type StepResolver<Row, Value> = PlayAuthoringStepResolver<Row, Value, DeeplinePlayRuntimeContext>;
4103
3530
  /**
4104
3531
  * Input object passed to an object-column `run` resolver.
4105
3532
  *
4106
3533
  * @sdkReference runtime 090
4107
3534
  */
4108
- type DatasetColumnRunInput<Row, Value> = {
4109
- /** Current row, including previously computed columns. */
4110
- row: Row;
4111
- /** Runtime context for tool/play/fetch/log calls. */
4112
- ctx: DeeplinePlayRuntimeContext;
4113
- /** Zero-based row index for this dataset run. */
4114
- index: number;
4115
- /**
4116
- * The prior stored value for this exact row+column when the runtime has
4117
- * decided the cell is due to run again. `previousCell.value` is the same type
4118
- * this column returns; metadata such as `completedAt` and `staleAt` lives
4119
- * beside it and is not mixed into the value.
4120
- */
4121
- previousCell?: PreviousCell<Value>;
4122
- };
3535
+ type DatasetColumnRunInput<Row, Value> = PlayAuthoringDatasetColumnRunInput<Row, Value, DeeplinePlayRuntimeContext>;
4123
3536
  /**
4124
3537
  * Object-column form for `.withColumn(...)`.
4125
3538
  *
@@ -4127,143 +3540,29 @@ type DatasetColumnRunInput<Row, Value> = {
4127
3540
  *
4128
3541
  * @sdkReference runtime 100
4129
3542
  */
4130
- type DatasetColumnDefinition<Row, Value> = {
4131
- /** Compute one cell value. Receives the previous stored value when rerunning. */
4132
- run: (input: DatasetColumnRunInput<Row, Value>) => Value | Promise<Value>;
4133
- /** Optional row-level gate. Skipped rows produce `null` for this column. */
4134
- readonly runIf?: (row: Row, index: number) => boolean | Promise<boolean>;
4135
- };
4136
- type ConditionalStepResolver<Row, Value, Else = null> = {
4137
- readonly kind: 'conditional';
4138
- readonly when: (row: Row, index: number) => boolean | Promise<boolean>;
4139
- readonly run: StepResolver<Row, Value>;
4140
- readonly elseValue: Else;
4141
- else<ValueElse>(value: ValueElse): ConditionalStepResolver<Row, Value, ValueElse>;
4142
- };
3543
+ type DatasetColumnDefinition<Row, Value> = PlayAuthoringDatasetColumnDefinition<Row, Value, DeeplinePlayRuntimeContext>;
3544
+ type ConditionalStepResolver<Row, Value, Else = null> = PlayAuthoringConditionalStepResolver<Row, Value, DeeplinePlayRuntimeContext, Else>;
4143
3545
  /**
4144
3546
  * Options for row-level `.withColumn(...)` and `steps().step(...)` entries.
4145
3547
  *
4146
3548
  * @sdkReference runtime 110
4147
3549
  */
4148
- type StepOptions<Row, Value = unknown> = {
4149
- /** Optional row-level gate. Skipped rows produce `null` for this column. */
4150
- readonly runIf?: (row: Row, index: number) => boolean | Promise<boolean>;
4151
- /**
4152
- * Legacy dataset-column recompute flag accepted for older authored plays.
4153
- *
4154
- * Prefer putting freshness on the actual reusable call
4155
- * (`ctx.tools.execute`, `ctx.step`, or `ctx.fetch`).
4156
- */
4157
- readonly recompute?: boolean;
4158
- /** Legacy error-recompute flag accepted for older authored plays. */
4159
- readonly recomputeOnError?: boolean;
4160
- /** Legacy cell staleness metadata accepted for older authored plays. */
4161
- readonly staleAfterSeconds?: number;
4162
- };
4163
- type StepProgram<Input, Output, Return = Output> = {
4164
- readonly kind: 'steps';
4165
- readonly steps: readonly PlayStepProgramStep[];
4166
- readonly returnResolver?: StepResolver<Output, Return>;
4167
- readonly __inputType?: (input: Input) => void;
4168
- step<Name extends string, Value>(name: Name, resolver: StepResolver<Output, Value> | ConditionalStepResolver<Output, Value> | StepProgramResolver<Output, Value>): StepProgram<Input, Output & Record<Name, Value>, Return>;
4169
- 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>;
4170
- return<Value>(resolver: StepResolver<Output, Value>): StepProgram<Input, Output, Value>;
4171
- };
4172
- type StepProgramResolver<Input, Return> = {
4173
- readonly kind: 'steps';
4174
- readonly steps: readonly PlayStepProgramStep[];
4175
- readonly returnResolver?: StepResolver<never, Return>;
4176
- readonly __inputType?: (input: Input) => void;
4177
- };
4178
- type PlayStepProgramStep = {
4179
- readonly name: string;
4180
- readonly recompute?: boolean;
4181
- readonly recomputeOnError?: boolean;
4182
- readonly staleAfterSeconds?: number;
4183
- readonly resolver: StepResolver<Record<string, unknown>, unknown> | ConditionalStepResolver<Record<string, unknown>, unknown> | StepProgramResolver<Record<string, unknown>, unknown>;
4184
- };
4185
- type ColumnResolver<Row, Value> = StepResolver<Row, Value> | ConditionalStepResolver<Row, Value> | StepProgramResolver<Row, Value>;
4186
- type StepProgramOutput<TProgram> = TProgram extends StepProgram<unknown, infer Output, unknown> ? Output : never;
4187
- type RunnableStepProgram<TInput, TOutput> = Pick<StepProgram<TInput, never, TOutput>, 'kind' | 'steps' | 'returnResolver' | '__inputType'>;
3550
+ type StepOptions<Row, Value = unknown> = PlayAuthoringStepOptions<Row, Value>;
3551
+ type StepProgram<Input, Output, Return = Output> = PlayAuthoringStepProgram<Input, Output, DeeplinePlayRuntimeContext, Return>;
3552
+ type StepProgramResolver<Input, Return> = PlayAuthoringStepProgramResolver<Input, Return, DeeplinePlayRuntimeContext>;
3553
+ type PlayStepProgramStep = PlayAuthoringStepProgramStep<DeeplinePlayRuntimeContext>;
3554
+ type ColumnResolver<Row, Value> = PlayAuthoringColumnResolver<Row, Value, DeeplinePlayRuntimeContext>;
4188
3555
  /**
4189
3556
  * Builder returned by `ctx.dataset(...)` for row-level durable columns.
4190
3557
  *
4191
3558
  * @sdkReference runtime 070 .dataset(...).withColumn(name, resolver).run(options)
4192
3559
  */
4193
- type DatasetBuilder<InputRow extends object, OutputRow extends object> = {
4194
- /**
4195
- * Define one output column for every row in this dataset.
4196
- *
4197
- * The `name` becomes a field on each output row. For example,
4198
- * `.withColumn('contact', ...)` creates `row.contact` in later column resolvers; it does
4199
- * not spread returned object fields such as `contact.email` into `row.email`.
4200
- * Add a later column resolver when you want a top-level export field:
4201
- * `.withColumn('email', row => row.contact?.email ?? null)`.
4202
- *
4203
- * @param name - Output column name.
4204
- * @param resolver - Computes the value for one row.
4205
- * @returns The same dataset builder with the new column type.
4206
- */
4207
- withColumn<Name extends string, Value>(name: Name, resolver: ColumnResolver<OutputRow, Value>): DatasetBuilder<InputRow, OutputRow & Record<Name, Value>>;
4208
- /**
4209
- * Define one output column with object-column authoring and a row gate.
4210
- *
4211
- * @param name - Output column name.
4212
- * @param definition - Object-column definition with required `runIf`.
4213
- * @returns The same dataset builder with a nullable column type for skipped rows.
4214
- */
4215
- withColumn<Name extends string, Value>(name: Name, definition: DatasetColumnDefinition<OutputRow, Value> & {
4216
- readonly runIf: (row: OutputRow, index: number) => boolean | Promise<boolean>;
4217
- }): DatasetBuilder<InputRow, OutputRow & Record<Name, Value | null>>;
4218
- /**
4219
- * Define one output column with object-column authoring.
4220
- *
4221
- * Use this form for typed `previousCell` access.
4222
- *
4223
- * @param name - Output column name.
4224
- * @param definition - Object-column definition.
4225
- * @returns The same dataset builder with the new column type.
4226
- */
4227
- withColumn<Name extends string, Value>(name: Name, definition: DatasetColumnDefinition<OutputRow, Value>): DatasetBuilder<InputRow, OutputRow & Record<Name, Value>>;
4228
- /**
4229
- * Define one output column with a resolver plus row-level options.
4230
- *
4231
- * @param name - Output column name.
4232
- * @param resolver - Computes the value for one row.
4233
- * @param options - Row gate options.
4234
- * @returns The same dataset builder with a nullable column type for skipped rows.
4235
- */
4236
- 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>>;
4237
- withColumns<Program extends StepProgram<OutputRow, object, unknown>>(program: Program): DatasetBuilder<InputRow, StepProgramOutput<Program>>;
4238
- /** @deprecated Dataset `.step(...)` was replaced by `.withColumn(...)`. */
4239
- step<Name extends string, Value>(name: Name, resolver: ColumnResolver<OutputRow, Value>): never;
4240
- /**
4241
- * Execute the row-column program and return a durable dataset handle.
4242
- *
4243
- * The returned {@link PlayDataset} preserves one output row per input row,
4244
- * with original fields merged with the columns produced by `.withColumn(...)`.
4245
- *
4246
- * @param options - Run options.
4247
- * @returns Output rows as a dataset handle.
4248
- */
4249
- run(options?: {
4250
- description?: string;
4251
- /**
4252
- * `upsert` (default) returns every input row, reusing persisted work for
4253
- * existing keys. `net_new` atomically inserts and returns only unseen keys.
4254
- */
4255
- mode?: 'upsert' | 'net_new';
4256
- key?: (keyof InputRow & string) | readonly (keyof InputRow & string)[] | ((row: InputRow, index: number) => string | number | readonly unknown[]);
4257
- }): Promise<PlayDataset<OutputRow>>;
4258
- };
4259
- type CsvRenameMap = Record<string, string | readonly string[]>;
3560
+ type DatasetBuilder<InputRow extends object, OutputRow extends object> = PlayAuthoringDatasetBuilder<InputRow, OutputRow, DeeplinePlayRuntimeContext>;
4260
3561
  /**
4261
3562
  * Runtime file-like input. At runtime this is the staged file path/reference
4262
3563
  * string. The type parameter carries static metadata for describe/CLI tooling.
4263
3564
  */
4264
- type FileInput<TMetadata = unknown> = string & {
4265
- readonly __deeplineFileInputMetadata?: TMetadata;
4266
- };
3565
+ type FileInput<TMetadata = unknown> = PlayAuthoringFileInput<TMetadata>;
4267
3566
  /**
4268
3567
  * CSV file input whose rows are described by `TRow`.
4269
3568
  *
@@ -4271,26 +3570,14 @@ type FileInput<TMetadata = unknown> = string & {
4271
3570
  * stage local paths passed to that flag, and use `TRow` for row-contract
4272
3571
  * discovery.
4273
3572
  */
4274
- type CsvInput<TRow extends object = Record<string, unknown>> = FileInput<{
4275
- readonly kind: 'csv';
4276
- readonly row: TRow;
4277
- }>;
4278
- type ColumnMap<TRow extends object> = Partial<Record<Extract<keyof TRow, string>, string | readonly string[]>>;
3573
+ type CsvInput<TRow extends object = Record<string, unknown>> = PlayAuthoringCsvInput<TRow>;
3574
+ type ColumnMap<TRow extends object> = PlayAuthoringColumnMap<TRow>;
4279
3575
  /**
4280
3576
  * Options for loading a staged CSV with `ctx.csv(...)`.
4281
3577
  *
4282
3578
  * @sdkReference runtime 050
4283
3579
  */
4284
- type CsvOptions = {
4285
- /** Human-readable description for runtime logs and inspection. */
4286
- description?: string;
4287
- /** Canonical field-to-header aliases, e.g. `{ domain: ['domain', 'Company Domain'] }`. */
4288
- columns?: CsvRenameMap;
4289
- /** Header rename map; use `columns` for new code. */
4290
- rename?: CsvRenameMap;
4291
- /** Canonical fields that must be present after header normalization. */
4292
- required?: readonly string[];
4293
- };
3580
+ type CsvOptions = PlayAuthoringCsvOptions;
4294
3581
  /**
4295
3582
  * Runtime context available inside a play function.
4296
3583
  *
@@ -4336,235 +3623,7 @@ type CsvOptions = {
4336
3623
  * });
4337
3624
  * ```
4338
3625
  */
4339
- interface DeeplinePlayRuntimeContext {
4340
- /**
4341
- * Load a staged CSV file as a durable dataset handle.
4342
- *
4343
- * Use this when a play receives a CSV path from the CLI or API and row work
4344
- * should continue through {@link DeeplinePlayRuntimeContext.dataset}. The path is
4345
- * normally an input field such as `input.csv`, populated by
4346
- * `deepline plays run my.play.ts --csv rows.csv`. Prefer `input.csv` for row
4347
- * data so the CLI can run strict CSV preflight before starting a run.
4348
- * Pass-through flags can also target non-reserved field names. If a play
4349
- * intentionally calls `ctx.csv(input.file)`, use `--input
4350
- * '{"file":"rows.csv"}'` because `--file` is reserved for the play source
4351
- * path.
4352
- *
4353
- * Each CSV row becomes an object keyed by canonical column names. Use
4354
- * `options.columns` / `options.rename` to map user headers such as
4355
- * `"Company Domain"` to stable code fields such as `domain`.
4356
- *
4357
- * @typeParam T - Row type (defaults to `Record<string, unknown>`)
4358
- * @param path - Staged CSV path.
4359
- * @param options - CSV load options.
4360
- *
4361
- * @returns A {@link PlayDataset} whose rows should usually flow directly into `ctx.dataset(...)`.
4362
- *
4363
- * @sdkReference runtime 040 ctx.csv(path, options)
4364
- */
4365
- csv<T = Record<string, unknown>>(path: string, options?: CsvOptions): Promise<PlayDataset<T>>;
4366
- /**
4367
- * Create a persisted row dataset/table from input rows.
4368
- *
4369
- * `ctx.dataset` is Deepline's row-work primitive. It records row identity,
4370
- * progress, retries, table output, and idempotency for a collection of rows.
4371
- * Use `.withColumn(name, resolver)` on the returned builder to define output
4372
- * columns, then `.run(...)` to execute the row program.
4373
- *
4374
- * The `key` identifies the logical dataset/table. Renaming it is a persistence
4375
- * migration: existing rows may no longer be reused. Row identity is derived
4376
- * automatically from input row content unless `.run({ key: ... })` overrides
4377
- * it with stable business fields such as `domain`, `email`, or `linkedin_url`.
4378
- *
4379
- * By default, `ctx.dataset` is row-preserving: one input row produces one output
4380
- * row, with original fields merged with the columns produced by
4381
- * `.withColumn(...)`. If one input entity must become many output rows, use the
4382
- * documented expand/flatten recipe instead of assuming `ctx.dataset` changes
4383
- * row cardinality.
4384
- *
4385
- * @typeParam T - Row type
4386
- * @param key - Dataset/table name.
4387
- * @param items - Input rows.
4388
- * @returns A builder. Calling `.run()` returns a `PlayDataset` of rows plus computed columns.
4389
- *
4390
- * @example Single tool per row
4391
- * ```typescript
4392
- * const results = await ctx
4393
- * .dataset('companies', leads)
4394
- * .withColumn('company', (row, ctx) =>
4395
- * ctx.tools.execute({
4396
- * id: 'company_search',
4397
- * tool: 'test_company_search',
4398
- * input: { domain: row.domain },
4399
- * description: 'Look up company details by domain.',
4400
- * }))
4401
- * .run({ description: 'Look up companies.' });
4402
- * // [{ domain: 'stripe.com', company: { name: 'Stripe', ... } }, ...]
4403
- * ```
4404
- *
4405
- * @example Multiple columns with pre/post logic
4406
- * ```typescript
4407
- * const results = await ctx
4408
- * .dataset('leads', leads)
4409
- * .withColumn('company', (row, ctx) =>
4410
- * ctx.tools.execute({
4411
- * id: 'company_search',
4412
- * tool: 'test_company_search',
4413
- * input: { domain: row.domain },
4414
- * description: 'Look up company details by domain.',
4415
- * }))
4416
- * .withColumn('score', (row) =>
4417
- * row.company?.employeeCount > 100 ? 'enterprise' : 'smb')
4418
- * .run({ description: 'Enrich leads.' });
4419
- * ```
4420
- *
4421
- * @sdkReference runtime 060 ctx.dataset(key, items)
4422
- */
4423
- dataset<TSource extends PlayDatasetInput<object>>(key: string, items: TSource): DatasetBuilder<PlayDatasetRow<TSource> & object, PlayDatasetRow<TSource> & object>;
4424
- /**
4425
- * @deprecated `ctx.map(...)` was replaced by `ctx.dataset(...)`.
4426
- */
4427
- map<TSource extends PlayDatasetInput<object>>(key: string, items: TSource): never;
4428
- /** Tool execution namespace. */
4429
- tools: {
4430
- /**
4431
- * Execute a single tool with a keyword-style request object.
4432
- *
4433
- * @param request - Tool call request.
4434
- * @returns Tool execution result.
4435
- *
4436
- * @sdkReference runtime 150 ctx.tools.execute(request)
4437
- */
4438
- execute<TOutput = LoosePlayObject>(request: ToolExecutionRequest): Promise<ToolExecuteResult<TOutput>>;
4439
- };
4440
- /** Customer DB query namespace for play handlers. */
4441
- customerDb: {
4442
- query<TRow extends object = Record<string, unknown>>(statement: SqlQuery | string, options?: {
4443
- maxRows?: number;
4444
- timeoutMs?: number;
4445
- }): Promise<TRow[]>;
4446
- };
4447
- /**
4448
- * Execute a single tool by stable step key and tool ID.
4449
- *
4450
- * Shorthand for `ctx.tools.execute(...)`; this is the preferred spelling in
4451
- * row-level step programs.
4452
- */
4453
- tool<TOutput = LoosePlayObject>(key: string, toolId: string, input: Record<string, unknown>, options?: {
4454
- description?: string;
4455
- }): Promise<ToolExecuteResult<TOutput>>;
4456
- /**
4457
- * Run a reusable step program against one scalar input object.
4458
- *
4459
- * `steps().step(...)` is a composable mini-pipeline. Use `ctx.runSteps(...)`
4460
- * when that mini-pipeline should execute outside a row dataset. Inside a
4461
- * `ctx.dataset` column resolver, pass the step program directly to
4462
- * `.withColumn(name, program)` instead.
4463
- *
4464
- * @param program - Step program.
4465
- * @param input - Program input.
4466
- * @param options - Run options.
4467
- * @returns Program output.
4468
- *
4469
- * @sdkReference runtime 180 ctx.runSteps(program, input, options)
4470
- */
4471
- runSteps<TInput extends Record<string, unknown>, TOutput>(program: RunnableStepProgram<TInput, TOutput>, input: TInput, options?: {
4472
- description?: string;
4473
- }): Promise<TOutput>;
4474
- /**
4475
- * Create one scalar checkpoint for the whole play run.
4476
- *
4477
- * Use `ctx.step` when a value is nondeterministic, expensive, external, or
4478
- * useful to inspect as a named boundary. The first execution stores the
4479
- * JSON-serializable output under `id`; replay and retries return the stored
4480
- * value instead of running `run` again.
4481
- *
4482
- * Plain deterministic assignment does not need `ctx.step`. Use
4483
- * `ctx.dataset(...).withColumn(...)`, not `ctx.step`, when the value should become a
4484
- * field on each exported row.
4485
- *
4486
- * @param id - Checkpoint id.
4487
- * @param run - Computes the value once.
4488
- * @param options - Checkpoint options.
4489
- * @returns Checkpoint value.
4490
- *
4491
- * @sdkReference runtime 130 ctx.step(id, fn)
4492
- */
4493
- step<T>(id: string, run: () => T | Promise<T>, options?: {
4494
- staleAfterSeconds?: number;
4495
- }): Promise<T>;
4496
- /**
4497
- * Durable HTTP fetch.
4498
- *
4499
- * Use this for non-provider HTTP calls that must replay safely. The response
4500
- * is recorded under `key` so workflow replay sees the same value. Prefer
4501
- * `ctx.tools.execute(...)` for Deepline-managed provider APIs because tools
4502
- * handle auth, retries, rate limits, extraction metadata, and spend tracking.
4503
- * If `init.auth` comes from `ctx.secrets`, `url` must be https://.
4504
- *
4505
- * @param key - Checkpoint id.
4506
- * @param url - URL to fetch.
4507
- * @param init - Fetch options.
4508
- * @returns Recorded response.
4509
- *
4510
- * @sdkReference runtime 170 ctx.fetch(key, url, init)
4511
- */
4512
- fetch(key: string, url: string | URL, init?: SecretAwareRequestInit, options?: {
4513
- staleAfterSeconds?: number;
4514
- }): Promise<{
4515
- ok: boolean;
4516
- status: number;
4517
- statusText: string;
4518
- url: string;
4519
- headers: Record<string, string>;
4520
- bodyText: string;
4521
- json: unknown | null;
4522
- }>;
4523
- secrets: {
4524
- get(name: string): SecretHandle;
4525
- bearer(secret: SecretHandle): SecretAuth;
4526
- header(header: string, secret: SecretHandle): SecretAuth;
4527
- };
4528
- /**
4529
- * Invoke another registered or file-backed play as a child workflow.
4530
- *
4531
- * Use this for real composition boundaries, especially when a fitting
4532
- * scalar prebuilt play already encodes provider order, fallbacks,
4533
- * normalization, and no-result behavior. Do not invoke plays through
4534
- * `ctx.tools.execute`; tools and plays are separate namespaces.
4535
- *
4536
- * `key` is the stable child-call identity for idempotency and traceability.
4537
- *
4538
- * @param key - Stable child-call key.
4539
- * @param playRef - Registered play name, play handle, or file-backed play reference.
4540
- * @param input - Input object passed to the child play.
4541
- * @param options - Child play options.
4542
- * @returns Child play output.
4543
- *
4544
- * @sdkReference runtime 140 ctx.runPlay(key, playRef, input, options)
4545
- */
4546
- runPlay<TOutput = unknown>(key: string, playRef: string | PlayReferenceLike, input: Record<string, unknown>, options?: PlayCallOptions): Promise<TOutput>;
4547
- /**
4548
- * Emit a log line visible in `play tail` and the play's progress logs.
4549
- *
4550
- * @param message - Log message (plain text)
4551
- */
4552
- log(message: string): void;
4553
- /**
4554
- * Pause play execution for the specified duration.
4555
- *
4556
- * Uses Temporal's durable timer — safe across worker restarts.
4557
- *
4558
- * @param ms - Duration in milliseconds
4559
- */
4560
- sleep(ms: number): Promise<void>;
4561
- /**
4562
- * @deprecated Read submitted play input from the handler's second argument:
4563
- * `definePlay('example', async (ctx, input) => ...)`. This legacy field is
4564
- * not the supported V2 play input API.
4565
- */
4566
- readonly input: Record<string, unknown>;
4567
- }
3626
+ type DeeplinePlayRuntimeContext = PlayAuthoringRuntimeContext;
4568
3627
  /**
4569
3628
  * Handle to a running play execution.
4570
3629
  *
@@ -4755,18 +3814,10 @@ type PrebuiltPlayRef = {
4755
3814
  readonly playName: string;
4756
3815
  readonly name: string;
4757
3816
  };
4758
- type PlayReferenceLike = {
4759
- readonly playName?: string;
4760
- readonly name?: string;
4761
- };
3817
+ type PlayReferenceLike = PlayAuthoringReferenceLike;
4762
3818
 
4763
- type PlayReturnObject = Record<string, unknown> & {
4764
- readonly _metadata?: never;
4765
- };
4766
- type PlayInputContract<TInput> = {
4767
- readonly schema: Record<string, unknown>;
4768
- readonly __inputType?: TInput;
4769
- };
3819
+ type PlayReturnObject = PlayReturnObject$1;
3820
+ type PlayInputContract<TInput> = PlayAuthoringInputContract<TInput>;
4770
3821
  /**
4771
3822
  * Object-form play definition accepted by `definePlay(config)`.
4772
3823
  *
@@ -4777,24 +3828,7 @@ type PlayInputContract<TInput> = {
4777
3828
  *
4778
3829
  * @sdkReference runtime 020
4779
3830
  */
4780
- type DefinePlayConfig<TInput, TOutput extends PlayReturnObject> = {
4781
- /** Play id/name. */
4782
- id: string;
4783
- /** Human-readable one-line description of what this play does. */
4784
- description?: string;
4785
- /** Input schema. */
4786
- input: PlayInputContract<TInput>;
4787
- /** Play function. */
4788
- run: (ctx: DeeplinePlayRuntimeContext, input: TInput) => Promise<TOutput>;
4789
- /** Trigger bindings. */
4790
- bindings?: PlayBindings;
4791
- /** Billing options. */
4792
- billing?: PlayBindings['billing'];
4793
- /** Requested prebuilt sandbox and runtime deadline. */
4794
- runtime?: PlayBindings['runtime'];
4795
- /** Runtime compatibility override. Omit for the current typed contract. */
4796
- compatibility?: PlayBindings['compatibility'];
4797
- };
3831
+ type DefinePlayConfig<TInput, TOutput extends PlayReturnObject> = PlayAuthoringDefineConfig<TInput, TOutput, DeeplinePlayRuntimeContext>;
4798
3832
  declare function steps<TInput>(): StepProgram<TInput, TInput, TInput>;
4799
3833
  declare function runIf<Row, Value>(predicate: (row: Row, index: number) => boolean | Promise<boolean>, resolver: StepResolver<Row, Value>): ConditionalStepResolver<Row, Value, null>;
4800
3834
  /**
@@ -4831,16 +3865,7 @@ declare function runIf<Row, Value>(predicate: (row: Row, index: number) => boole
4831
3865
  * console.log(myPlay.bindings); // undefined (no cron/webhook)
4832
3866
  * ```
4833
3867
  */
4834
- type DefinedPlay<TInput, TOutput extends PlayReturnObject> = ((ctx: DeeplinePlayRuntimeContext, input: TInput) => Promise<TOutput>) & DeeplineNamedPlay<TInput, TOutput> & {
4835
- /** Optional trigger bindings (cron, webhook). */
4836
- readonly bindings?: PlayBindings;
4837
- /** Requested prebuilt sandbox and runtime deadline. */
4838
- readonly runtime?: PlayBindings['runtime'];
4839
- /** Runtime compatibility explicitly selected by the author. */
4840
- readonly compatibility?: PlayBindings['compatibility'];
4841
- /** The play's name (same as `.name`). */
4842
- readonly playName: string;
4843
- };
3868
+ type DefinedPlay<TInput, TOutput extends PlayReturnObject> = PlayAuthoringDefinedPlay<TInput, TOutput, DeeplinePlayRuntimeContext, DeeplineNamedPlay<TInput, TOutput>>;
4844
3869
  type PlayMetadata = {
4845
3870
  name: string;
4846
3871
  description?: string;
@@ -5244,4 +4269,4 @@ declare function writeCsvOutputFile(rows: Array<Record<string, unknown>>, stem:
5244
4269
  */
5245
4270
  declare function extractSummaryFields(payload: unknown): Record<string, Scalar>;
5246
4271
 
5247
- 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 MonitorUpdateChangeSummary, 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 PlayActivityObservation, type PlayActivityState, type PlayActivityTarget, 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 PlayRunActivityProjection, 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, ToolExecutionError, ToolExecutionErrorOptions, type ToolExecutionRequest, type ToolMetadata, ToolRateLimitError, type ToolSearchOptions, type ToolSearchResult, defineInput, defineMonitor, definePlay, defineWorkflow, extractSummaryFields, formatPlayBootstrapFinderKinds, formatPlayBootstrapFinderKindsForSentence, formatPlayBootstrapTemplates, getDefinedPlayMetadata, isDeeplineExtractorTarget, isPlayBootstrapFinderKind, isPlayBootstrapTemplate, resolveConfig, runIf, steps, tryConvertToList, writeCsvOutputFile, writeJsonOutputFile };
4272
+ 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_TOOL_CATEGORIES, type DatasetBuilder, type DatasetColumnDefinition, type DatasetColumnRunInput, type DbNamespace, Deepline, DeeplineClient, type DeeplineClientOptions, DeeplineContext, DeeplineError, type DeeplineNamedPlay, type DeeplinePlayRuntimeContext, type DeeplinePlaysNamespace, type DeeplineToolCategory, type DeeplineToolsNamespace, type DefinePlayConfig, type DefinedPlay, type FetchOptions, type FileInput, type IngestionStorageRepairResult, type LiveEventEnvelope, type MonitorCheckResult, type MonitorControls, type MonitorDefinition, type MonitorDeleteResult, type MonitorDependents, type MonitorDeployResult, type MonitorDetail, type MonitorListEntry, type MonitorPayload, type MonitorReactivateResult, type MonitorUpdateChangeSummary, type MonitorUpdateResult, type MonitorsAccessStatus, type MonitorsAvailableOptions, type MonitorsAvailableResult, type MonitorsListOptions, type MonitorsListResult, type MonitorsNamespace, 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 PlayActivityObservation, type PlayActivityState, type PlayActivityTarget, type PlayBindings, type PlayBootstrapEntityKind, type PlayBootstrapFinderKind, type PlayCallExecution, type PlayCallOptions, type PlayFetchResponse, type PlayInputContract, type PlayJob, type PlayListItem, type PlayLiveEvent, type PlayRevisionSummary, type PlayRunActionPackage, type PlayRunActivityProjection, type PlayRunDatasetActions, type PlayRunPackage, type PlayRunResult, type PlayRunStart, type PlaySheetRow, type PlaySheetRowsResult, type PlayStatus, type PlayStepProgramStep, type PrebuiltPlayRef, type PublishPlayVersionRequest, type PublishPlayVersionResult, RateLimitError, type ResolvedConfig, RunObserveTransportUnavailableError, type RunsListOptions, type RunsLogsOptions, type RunsLogsResult, type RunsNamespace, type RunsTailOptions, type RuntimeStepOptions, 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, ToolExecuteResult, type ToolExecution, ToolExecutionError, ToolExecutionErrorOptions, type ToolExecutionRequest, type ToolMetadata, ToolRateLimitError, type ToolSearchOptions, type ToolSearchResult, defineInput, defineMonitor, definePlay, defineWorkflow, extractSummaryFields, formatPlayBootstrapFinderKinds, formatPlayBootstrapFinderKindsForSentence, formatPlayBootstrapTemplates, getDefinedPlayMetadata, isPlayBootstrapFinderKind, isPlayBootstrapTemplate, resolveConfig, runIf, steps, tryConvertToList, writeCsvOutputFile, writeJsonOutputFile };