@treasuredata/tdx 0.9.7 → 0.10.0

package/dist/sdk/segment/journey-yaml.d.ts

@@ -3,430 +3,31 @@
  *
  * This module provides a human-friendly YAML format for journey configuration
  * and utilities to convert between YAML and API formats.
- */
-import { type YamlRule, type YamlActivation } from './child-segment-yaml.js';
-export type { YamlRule, YamlCondition, YamlOperator, YamlActivation } from './child-segment-yaml.js';
-/**
- * Reentry mode for journey
- */
-export type ReentryMode = 'no_reentry' | 'reentry_unless_goal_achieved' | 'reentry_always';
-/**
- * Journey state
- */
-export type JourneyState = 'draft' | 'simulation' | 'launched';
-/**
- * Wait step time unit
- */
-export type WaitUnit = 'day' | 'week';
+ *
+ * Transformation flow:
+ * - PULL: ApiModel → JourneyDef → YAML
+ * - PUSH: YAML → JourneyDef → (resolve refs) → ApiModel
+ */
+import { type ActivationDef } from './child-segment-yaml.js';
+import type { ResolutionContext, DereferenceContext } from '../types/resolution-context.js';
+import type { Journey } from '../types/cdp.js';
+import type { JourneyDef, JourneyEntryDef, StageDef, WaitStepDef, ActivationStepDef, DecisionPointStepDef, AbTestStepDef, JumpStepDef, CriteriaDef, EmbeddedSegmentDef, JourneyStateType, ReentryModeType, WaitUnitType } from './types/journey-def.js';
+export type { JourneyDef, JourneyEntryDef, StageDef, StepDef, StepBaseDef, WaitStepDef, WaitStepParamsDef, WaitConditionDef, ActivationStepDef, ActivationStepParamsDef, DecisionPointStepDef, DecisionPointStepParamsDef, DecisionBranchDef, AbTestStepDef, AbTestStepParamsDef, AbTestVariantDef, MergeStepDef, JumpStepDef, JumpStepParamsDef, JumpTargetDef, EndStepDef, CriteriaDef, EmbeddedSegmentDef, JourneyStateType, ReentryModeType, WaitUnitType, } from './types/journey-def.js';
+export type { RuleDef, ActivationDef } from './child-segment-yaml.js';
+/** Alias for WaitUnitType */
+export type WaitUnit = WaitUnitType;
+/** Alias for ReentryModeType */
+export type ReentryMode = ReentryModeType;
 /**
  * Normalize wait unit to singular form for API compatibility.
  * Accepts both singular (day, week) and plural (days, weeks) forms.
  * @internal Exported for testing
  */
 export declare function normalizeWaitUnit(unit: string): WaitUnit;
-/**
- * Step type enumeration
- */
-export type StepType = 'wait' | 'activation' | 'decision_point' | 'ab_test' | 'merge' | 'jump' | 'end';
-/**
- * Reference to a child segment (by name or ID)
- * @deprecated Use segment name directly in criteria/branches
- */
-export interface YamlSegmentRef {
-    /** Segment name (resolved to ID during push) */
-    segment?: string;
-    /** Segment ID (used directly) - internal only, not in user-facing YAML */
-    segment_id?: string;
-}
-/**
- * Embedded segment definition for journey-local segments.
- * These segments are created when the journey is launched and are scoped to the journey.
- *
- * Segment names should be kebab-case identifiers (e.g., "high-value-customers").
- */
-export interface YamlEmbeddedSegment {
-    /** Segment description */
-    description?: string;
-    /** Filtering rule that defines the segment criteria */
-    rule: YamlRule;
-}
-/**
- * Journey goal/milestone/criteria definition
- */
-export interface YamlJourneyCriteria {
-    /** Display name */
-    name: string;
-    /** Description */
-    description?: string;
-    /**
-     * Segment reference - can be:
-     * - Name of embedded segment (defined in journey's `segments` section)
-     * - "ref:Segment Name" to reference an existing child segment
-     * - Segment ID (internal, for API compatibility)
-     */
-    segment: string;
-    /** Optional jump target when criteria is met */
-    target?: YamlJumpTarget;
-}
-/**
- * Jump target to another journey/stage
- */
-export interface YamlJumpTarget {
-    /** Target journey name or ID */
-    journey: string;
-    /** Target stage name */
-    stage: string;
-    /** Journey bundle ID (optional, for versioned journeys) */
-    bundle_id?: string;
-}
-/**
- * Base step interface.
- * Follows GitHub Actions-like format where type-specific parameters are nested under 'with'.
- */
-export interface YamlStepBase {
-    /** Step type - always comes first */
-    type: StepType;
-    /** Step name - used as identifier (human-readable) */
-    name: string;
-    /** UUID for step (internal, used during API conversion) */
-    uuid?: string;
-    /** Next step name or UUID (omitted for 'end' type) */
-    next?: string;
-}
-/**
- * Wait step parameters (nested under 'with')
- */
-export interface YamlWaitStepParams {
-    /** Duration to wait */
-    duration?: number;
-    /** Time unit (day or week) */
-    unit?: WaitUnit;
-    /** Wait until specific date */
-    wait_until?: string;
-    /** Wait until condition is met */
-    condition?: {
-        segment: string;
-        timeout?: {
-            duration: number;
-            unit: WaitUnit;
-        };
-    };
-    /** Days of the week to wait for */
-    days_of_week?: string[];
-}
-/**
- * Wait step - pause execution
- */
-export interface YamlWaitStep extends YamlStepBase {
-    type: 'wait';
-    /** Step-specific parameters */
-    with: YamlWaitStepParams;
-}
-/**
- * Activation step parameters (nested under 'with')
- */
-export interface YamlActivationStepParams {
-    /** Activation name (resolved to ID during push) */
-    activation: string;
-}
-/**
- * Activation step - send to external system
- */
-export interface YamlActivationStep extends YamlStepBase {
-    type: 'activation';
-    /** Step-specific parameters */
-    with: YamlActivationStepParams;
-}
-/**
- * Decision point branch
- */
-export interface YamlDecisionBranch {
-    /** Branch name */
-    name: string;
-    /**
-     * Segment reference - can be:
-     * - Name of embedded segment (defined in journey's `segments` section)
-     * - "ref:Segment Name" to reference an existing child segment
-     * - Segment ID (internal, for API compatibility)
-     */
-    segment?: string;
-    /**
-     * Segment ID (alternative to segment name)
-     * @deprecated Use `segment` name instead - IDs are internal only
-     * @internal
-     */
-    segment_id?: string;
-    /** Is this the excluded/else path? */
-    excluded?: boolean;
-    /** Next step for this branch */
-    next?: string;
-}
-/**
- * Decision point step parameters (nested under 'with')
- */
-export interface YamlDecisionPointStepParams {
-    /** Branches for the decision */
-    branches: YamlDecisionBranch[];
-}
-/**
- * Decision point step - branch based on segment
- */
-export interface YamlDecisionPointStep extends YamlStepBase {
-    type: 'decision_point';
-    /** Step-specific parameters */
-    with: YamlDecisionPointStepParams;
-}
-/**
- * A/B test variant
- */
-export interface YamlAbTestVariant {
-    /** Variant ID */
-    id?: string;
-    /** Variant name */
-    name: string;
-    /** Percentage of traffic (0-100) */
-    percentage: number;
-    /** Next step for this variant */
-    next?: string;
-}
-/**
- * A/B test step parameters (nested under 'with')
- */
-export interface YamlAbTestStepParams {
-    /** Use custom split percentages (vs equal distribution) */
-    customized_split?: boolean;
-    /** Unique ID for the test */
-    unique_id?: string;
-    /** Test variants */
-    variants: YamlAbTestVariant[];
-}
-/**
- * A/B test step - split traffic for testing
- */
-export interface YamlAbTestStep extends YamlStepBase {
-    type: 'ab_test';
-    /** Step-specific parameters */
-    with: YamlAbTestStepParams;
-}
-/**
- * Merge step - rejoin branched paths (no additional parameters)
- */
-export interface YamlMergeStep extends YamlStepBase {
-    type: 'merge';
-}
-/**
- * Jump step parameters (nested under 'with')
- */
-export interface YamlJumpStepParams {
-    /** Jump target */
-    target: YamlJumpTarget;
-}
-/**
- * Jump step - go to another journey/stage
- */
-export interface YamlJumpStep extends YamlStepBase {
-    type: 'jump';
-    /** Step-specific parameters */
-    with: YamlJumpStepParams;
-}
-/**
- * End step - exit the stage (no next, no additional parameters)
- */
-export interface YamlEndStep extends YamlStepBase {
-    type: 'end';
-}
 /**
  * Helper type to check if a step has 'with' params
  */
-export type YamlStepWithParams = YamlWaitStep | YamlActivationStep | YamlDecisionPointStep | YamlAbTestStep | YamlJumpStep;
-/**
- * Union of all step types
- */
-export type YamlStep = YamlWaitStep | YamlActivationStep | YamlDecisionPointStep | YamlAbTestStep | YamlMergeStep | YamlJumpStep | YamlEndStep;
-/**
- * Journey stage definition
- */
-export interface YamlJourneyStage {
-    /** Stage name */
-    name: string;
-    /** Stage description */
-    description?: string;
-    /**
-     * Stage ID (from API, used for updates)
-     * @internal Not included in user-facing YAML output
-     */
-    id?: string;
-    /** Entry criteria - who enters this stage */
-    entry_criteria?: YamlJourneyCriteria;
-    /** Exit criteria - when to remove from stage */
-    exit_criteria?: YamlJourneyCriteria[];
-    /** Milestone - tracking point */
-    milestone?: YamlJourneyCriteria;
-    /** Root step UUID (entry point) */
-    root_step?: string;
-    /** Steps in this stage */
-    steps?: YamlStep[];
-}
-/**
- * Resource type discriminator for YAML files
- */
-export type YamlResourceType = 'segment' | 'journey';
-/**
- * Journey version definition for multi-version YAML files.
- * Each version has its own stages but shares segment definitions with other versions.
- * @deprecated Use YamlJourneyEntry with the 'journeys' array format instead
- */
-export interface YamlJourneyVersion {
-    /** Version name (e.g., "v1", "v2") */
-    name: string;
-    /** Version state */
-    state: 'draft' | 'launched';
-    /**
-     * Whether this is the currently active (latest) version.
-     * Only one version should have latest=true.
-     * Default: false (omit if false)
-     */
-    latest?: boolean;
-    /** Version-specific stages (1-8) */
-    stages: YamlJourneyStage[];
-    /**
-     * Journey ID for this version (from API, used for updates)
-     * @internal Not included in user-facing YAML output
-     */
-    id?: string;
-    /** Version number */
-    version_number?: number;
-}
-/**
- * Journey entry definition for the unified 'journeys' array format.
- * Each entry represents a version of the journey with its own stages.
- * Shared properties (goal, reentry, segments) can be inherited from top-level
- * or overridden per-entry.
- */
-export interface YamlJourneyEntry {
-    /**
-     * Version identifier (e.g., "v1", "v2").
-     * Optional - defaults to "v1" for single-version journeys.
-     */
-    version?: string;
-    /** Version state */
-    state?: 'draft' | 'launched';
-    /**
-     * Whether this is the currently active (latest) version.
-     * Only one entry should have latest=true.
-     * Default: false (omit if false)
-     */
-    latest?: boolean;
-    /** Version-specific stages (1-8) */
-    stages: YamlJourneyStage[];
-    /**
-     * Journey ID for this entry (from API, used for updates)
-     * @internal Not included in user-facing YAML output
-     */
-    id?: string;
-    /** Version number from API */
-    version_number?: number;
-    /** Override goal for this version */
-    goal?: YamlJourneyCriteria;
-    /** Override reentry mode for this version */
-    reentry?: ReentryMode;
-}
-/**
- * Complete journey YAML configuration.
- *
- * Supports three modes (in order of preference):
- * 1. **Unified format (recommended)**: Use `journeys` array - each entry is a version
- * 2. Legacy multi-version mode: Use `versions` array (deprecated)
- * 3. Legacy single-version mode: Use `stages` at top level (deprecated)
- *
- * The unified format (`journeys` array) is the recommended format for new journeys.
- * Legacy formats are supported for backward compatibility during push.
- *
- * Folder is NOT stored in YAML - it's inferred from the local file path structure.
- */
-export interface JourneyYaml {
-    /** Resource type - must be 'journey' to distinguish from segments */
-    type: 'journey';
-    /** Journey name (the actual journey name, same as bundle_name) */
-    name: string;
-    /** Journey description */
-    description?: string;
-    /**
-     * Embedded segment definitions local to this journey.
-     * These segments are created when the journey is launched.
-     *
-     * Keys are segment names (kebab-case, e.g., "high-value-customers").
-     * Reference these names in criteria/branches using the segment field.
-     * To reference an existing child segment, use "ref:Segment Name" prefix.
-     */
-    segments?: Record<string, YamlEmbeddedSegment>;
-    /**
-     * Embedded activation definitions local to this journey.
-     * These activations are created/updated when the journey is launched.
-     *
-     * Keys are activation names used in activation steps.
-     * Reference these names in steps using the activation field.
-     * To reference an existing activation, use "ref:Activation Name" prefix.
-     */
-    activations?: Record<string, YamlActivation>;
-    /** Journey goal (shared across all versions, can be overridden per-version in journeys array) */
-    goal?: YamlJourneyCriteria;
-    /** Reentry mode (shared across all versions, can be overridden per-version in journeys array) */
-    reentry?: ReentryMode;
-    /**
-     * Journey versions using unified format.
-     * Each entry has `version` (optional, defaults to "v1"), `state`, `stages`,
-     * and optionally `goal`/`reentry` overrides.
-     *
-     * This is the recommended format for all journeys (single or multi-version).
-     */
-    journeys?: YamlJourneyEntry[];
-    /**
-     * Journey stages for legacy single-version mode (1-8).
-     * @deprecated Use `journeys` array instead
-     */
-    stages?: YamlJourneyStage[];
-    /**
-     * Journey versions for legacy multi-version mode.
-     * @deprecated Use `journeys` array instead
-     */
-    versions?: YamlJourneyVersion[];
-    /**
-     * Journey ID (from API, used for updates)
-     * @internal Not included in user-facing YAML output
-     */
-    id?: string;
-    /**
-     * Version name (e.g., "v11") - the API name field
-     * @internal Used for single-version mode API compatibility
-     */
-    version?: string;
-    /**
-     * Version number
-     * @internal Used for single-version mode API compatibility
-     */
-    version_number?: number;
-    /**
-     * Folder ID (from API)
-     * @internal Folder is inferred from file path, not stored in YAML
-     */
-    folder_id?: string;
-    /**
-     * Journey bundle ID (for versioned journeys)
-     * @internal Not included in user-facing YAML output
-     */
-    bundle_id?: string;
-    /**
-     * Bundle name (same as name, kept for compatibility)
-     * @internal Not included in user-facing YAML output
-     */
-    bundle_name?: string;
-    /**
-     * Allow reentry (legacy, use reentry instead)
-     * @deprecated Use `reentry` instead
-     */
-    allow_reentry?: boolean;
-}
+export type StepWithParams = WaitStepDef | ActivationStepDef | DecisionPointStepDef | AbTestStepDef | JumpStepDef;
 /**
  * Jump target from API (used in jump steps and exit criteria)
  * Format of journeyName: "Stage Name (Journey Name/Subfolder/Root folders)"
@@ -451,6 +52,24 @@ export interface ApiJourneyCriteria {
     segmentId: string;
     target?: ApiJumpTarget;
 }
+/**
+ * Wait step condition from API (for Condition type wait steps)
+ */
+export interface ApiWaitStepCondition {
+    id?: string;
+    /** Segment ID for the condition (only for matched path) */
+    segmentId?: string;
+    /** True for timeout path, false for matched path */
+    timedOutPath: boolean;
+    /** Next step UUID */
+    next?: string;
+    /** Name of the condition path */
+    name?: string;
+    /** Duration for timeout path (moveAfter in API) */
+    moveAfter?: number;
+    /** Time unit for timeout */
+    unit?: 'day' | 'week';
+}
 /**
  * Journey step from API (keyed by UUID)
  */
@@ -462,6 +81,7 @@ export interface ApiJourneyStep {
     waitStepUnit?: 'day' | 'week';
     waitUntilDate?: string;
     daysOfWeek?: string[];
+    conditions?: ApiWaitStepCondition[];
     conditionSegmentId?: string;
     conditionTimeoutDuration?: number;
     conditionTimeoutUnit?: 'day' | 'week';
@@ -497,16 +117,16 @@ export interface ApiJourneyStage {
     steps?: Record<string, ApiJourneyStep>;
 }
 /**
- * Full journey from API
+ * Full journey response from API
  */
-export interface ApiJourney {
+export interface JourneyResponse {
     id: string;
     type: 'journey';
     attributes: {
         name: string;
         description?: string;
         audienceId: string;
-        state: JourneyState;
+        state: JourneyStateType;
         goal?: ApiJourneyCriteria;
         allowReentry?: boolean;
         reentryMode?: ReentryMode;
@@ -544,7 +164,7 @@ export interface ResolvedSegment {
     /** Whether this is a journey-local segment (true) or external child segment (false) */
     isJourneyLocal: boolean;
     /** Segment rule definition (only for journey-local segments) */
-    definition?: YamlEmbeddedSegment;
+    definition?: EmbeddedSegmentDef;
 }
 /**
  * Result of resolving an activation ID during API to YAML conversion
@@ -555,7 +175,7 @@ export interface ResolvedActivation {
     /** Whether this activation should be embedded in the journey YAML */
     isJourneyLocal: boolean;
     /** Full activation definition (for embedding) */
-    definition?: YamlActivation;
+    definition?: ActivationDef;
 }
 /**
  * Resolved jump target information
@@ -567,35 +187,26 @@ export interface ResolvedJumpTarget {
     stageName: string;
 }
 /**
- * Context for resolving IDs to names during API → YAML conversion (pull).
+ * Context for converting API response to portable definition (pull).
  *
- * When pulling from API, references are stored as IDs. To make YAML human-readable,
- * these IDs can be resolved to names using the context functions.
+ * When pulling from API, references are stored as IDs. To make the definition
+ * human-readable, these IDs can be resolved to names using the context functions.
  *
- * If no context is provided, IDs are stored as-is in the YAML output.
+ * If no context is provided, IDs are stored as-is in the output.
  */
-export interface ApiToYamlContext {
+export interface JourneyResponseToDefContext extends DereferenceContext {
     /**
      * Resolve segment ID to its definition and metadata.
      * Returns name and whether it's journey-local or an external ref.
      * For journey-local segments, also returns the rule definition for embedding.
      */
     resolveSegment?: (id: string) => Promise<ResolvedSegment>;
-    /**
-     * Resolve segment ID to name (simple version, for backward compatibility)
-     * @deprecated Use resolveSegment for full segment resolution
-     */
-    resolveSegmentName?: (id: string) => Promise<string>;
     /**
      * Resolve activation ID to its definition and metadata.
-     * Returns name and whether it should be embedded in the journey YAML.
+     * Returns name and whether it should be embedded in the journey definition.
      * For journey-local activations, also returns the full definition for embedding.
      */
     resolveActivation?: (id: string) => Promise<ResolvedActivation>;
-    /** Resolve activation ID to name (simple version, for backward compatibility) */
-    resolveActivationName?: (id: string) => Promise<string>;
-    /** Resolve journey ID to name */
-    resolveJourneyName?: (id: string) => Promise<string>;
     /**
      * Resolve jump target IDs (journey ID and stage ID) to their names.
      * Used for human-readable jump step targets.
@@ -610,7 +221,7 @@ export interface ApiToYamlContext {
  *
  * @internal Use apiToYamlAsync for user-facing YAML
  */
-export declare function apiToYaml(api: ApiJourney): JourneyYaml;
+export declare function journeyResponseToDefSync(api: JourneyResponse): JourneyDef;
 /**
  * Convert API journey to YAML format with segment resolution.
  *
@@ -621,17 +232,11 @@ export declare function apiToYaml(api: ApiJourney): JourneyYaml;
  * @param context - Resolution context for IDs to names
  * @returns Journey YAML with embedded segments and name references
  */
-export declare function apiToYamlAsync(api: ApiJourney, context?: ApiToYamlContext): Promise<JourneyYaml>;
+export declare function journeyResponseToDef(api: JourneyResponse, context?: JourneyResponseToDefContext): Promise<JourneyDef>;
 /**
- * Context for resolving references during YAML → API conversion
+ * Context for converting portable definition to API request (push).
  */
-export interface YamlToApiContext {
-    /** Resolve segment name to ID */
-    resolveSegmentId?: (name: string) => Promise<string>;
-    /** Resolve activation name to ID */
-    resolveActivationId?: (name: string) => Promise<string>;
-    /** Resolve journey name to ID */
-    resolveJourneyId?: (name: string) => Promise<string>;
+export interface JourneyDefToRequestContext extends ResolutionContext {
     /**
      * Resolve stage name to ID within a journey.
      * Used for jump step target stage resolution.
@@ -644,12 +249,12 @@ export interface YamlToApiContext {
      * Resolve embedded segment definition to ID.
      * Used when an embedded segment needs to be created/matched in the API.
      */
-    resolveEmbeddedSegmentId?: (name: string, definition: YamlEmbeddedSegment) => Promise<string>;
+    resolveEmbeddedSegmentId?: (name: string, definition: EmbeddedSegmentDef) => Promise<string>;
     /**
      * Resolve embedded activation definition to ID.
      * Used when an embedded activation needs to be created/matched in the API.
      */
-    resolveEmbeddedActivationId?: (name: string, definition: YamlActivation) => Promise<string>;
+    resolveEmbeddedActivationId?: (name: string, definition: ActivationDef) => Promise<string>;
 }
 /**
  * API request format for creating/updating a journey
@@ -682,12 +287,12 @@ export interface ApiJourneyRequest {
  * @param audienceId - Parent segment ID (from context, not stored in YAML)
  * @param context - Resolution context for references
  */
-export declare function yamlToApi(yamlConfig: JourneyYaml, audienceId: string, context?: YamlToApiContext): Promise<ApiJourneyRequest>;
+export declare function journeyDefToRequest(yamlConfig: JourneyDef, audienceId: string, context?: JourneyDefToRequestContext): Promise<ApiJourneyRequest>;
 /**
  * Serialize journey config to YAML string.
  * Strips internal fields (IDs, folder_id, etc.) from output for clean, portable YAML.
  */
-export declare function toYamlString(config: JourneyYaml): string;
+export declare function toYamlString(config: JourneyDef): string;
 /**
  * Parse YAML string to journey config.
  * Supports three formats:
@@ -695,11 +300,11 @@ export declare function toYamlString(config: JourneyYaml): string;
  * 2. Legacy single-version mode: stages at top level
  * 3. Legacy multi-version mode: versions array
  */
-export declare function parseYamlString(yamlString: string): JourneyYaml;
+export declare function parseYamlString(yamlString: string): JourneyDef;
 /**
  * Check if a YAML object represents a journey (vs segment)
  */
-export declare function isJourneyYaml(parsed: unknown): parsed is JourneyYaml;
+export declare function isJourneyDef(parsed: unknown): parsed is JourneyDef;
 /**
  * Generate a sample YAML template for a new journey
  */
@@ -733,31 +338,31 @@ export declare function isExternalSegmentRef(ref: string): boolean;
  * Check if a journey YAML uses the unified 'journeys' array format.
  * This is the recommended format for all journeys.
  */
-export declare function isJourneysArrayMode(config: JourneyYaml): boolean;
+export declare function isJourneysArrayMode(config: JourneyDef): boolean;
 /**
  * Check if a journey YAML is in legacy multi-version mode (using 'versions' array).
  * @deprecated Use isJourneysArrayMode instead
  */
-export declare function isMultiVersionMode(config: JourneyYaml): boolean;
+export declare function isMultiVersionMode(config: JourneyDef): boolean;
 /**
  * Check if a journey YAML is in legacy single-version mode (using 'stages' at top level).
  * @deprecated Use isJourneysArrayMode instead
  */
-export declare function isSingleVersionMode(config: JourneyYaml): boolean;
+export declare function isSingleVersionMode(config: JourneyDef): boolean;
 /**
  * Check if a journey YAML has multiple versions defined (in any format).
  * Works with unified journeys array, legacy versions array, or legacy single-version mode.
  */
-export declare function hasMultipleVersions(config: JourneyYaml): boolean;
+export declare function hasMultipleVersions(config: JourneyDef): boolean;
 /**
  * Normalize a journey YAML config to the unified journeys array format.
  * This is useful for comparing journeys across different format versions.
  * Converts legacy single-version (stages at top) and multi-version (versions array)
  * formats to the unified journeys array format.
  */
-export declare function normalizeToJourneysFormat(config: JourneyYaml): JourneyYaml;
+export declare function normalizeToJourneysFormat(config: JourneyDef): JourneyDef;
 /**
- * Normalize a JourneyYaml to have consistent field ordering.
+ * Normalize a JourneyDef to have consistent field ordering.
  * This ensures that local YAML files and server-converted YAML have the same field order,
  * avoiding spurious diffs in `tdx journey push` that are just reordering changes.
  *
@@ -767,7 +372,7 @@ export declare function normalizeToJourneysFormat(config: JourneyYaml): JourneyY
  * - Stage: name, description, entry_criteria, exit_criteria, milestone, steps
  * - Step: type, name, next, with
  */
-export declare function normalizeJourneyYaml(config: JourneyYaml, existingYaml?: JourneyYaml): JourneyYaml;
+export declare function normalizeJourneyDef(config: JourneyDef, existingYaml?: JourneyDef): JourneyDef;
 /**
  * Get all stages from a journey YAML, regardless of mode.
  * Returns stages from the latest/active version.
@@ -777,7 +382,7 @@ export declare function normalizeJourneyYaml(config: JourneyYaml, existingYaml?:
  * 2. stages (legacy single-version) - returns stages directly
  * 3. versions (legacy multi-version) - returns stages from latest version
  */
-export declare function getActiveStages(config: JourneyYaml): YamlJourneyStage[];
+export declare function getActiveStages(config: JourneyDef): StageDef[];
 /**
  * Get the latest/active journey entry from a journey YAML.
  * Works with all three formats (unified, legacy multi-version, legacy single-version).
@@ -785,7 +390,7 @@ export declare function getActiveStages(config: JourneyYaml): YamlJourneyStage[]
  * Returns the entry/version marked with `latest: true`, or the first one as fallback.
  * For legacy single-version mode, returns a synthetic entry created from top-level fields.
  */
-export declare function getLatestJourneyEntry(config: JourneyYaml): YamlJourneyEntry | undefined;
+export declare function getLatestJourneyEntry(config: JourneyDef): JourneyEntryDef | undefined;
 /**
  * Get the latest/active version from a legacy multi-version journey.
  * Returns the version marked with `latest: true`, or the first version as fallback.
@@ -793,25 +398,36 @@ export declare function getLatestJourneyEntry(config: JourneyYaml): YamlJourneyE
  *
  * @deprecated Use getLatestJourneyEntry instead
  */
-export declare function getLatestVersion(config: JourneyYaml): YamlJourneyVersion | undefined;
+export declare function getLatestVersion(config: JourneyDef): JourneyEntryDef | undefined;
 /**
  * Get effective goal for a journey, considering per-version overrides.
  * For unified format, checks the active journey entry first, then falls back to top-level.
  */
-export declare function getEffectiveGoal(config: JourneyYaml): YamlJourneyCriteria | undefined;
+export declare function getEffectiveGoal(config: JourneyDef): CriteriaDef | undefined;
 /**
  * Get effective reentry mode for a journey, considering per-version overrides.
  * For unified format, checks the active journey entry first, then falls back to top-level.
  */
-export declare function getEffectiveReentry(config: JourneyYaml): ReentryMode | undefined;
+export declare function getEffectiveReentry(config: JourneyDef): ReentryMode | undefined;
 /**
  * Collect all segment references from a journey YAML.
  * Returns a set of unique segment reference strings.
  */
-export declare function collectSegmentRefs(config: JourneyYaml): Set<string>;
+export declare function collectSegmentRefs(config: JourneyDef): Set<string>;
 /**
  * Validate that all segment references in a journey YAML are resolvable.
  * Returns an array of validation errors (empty if all valid).
  */
-export declare function validateSegmentRefs(config: JourneyYaml): string[];
+export declare function validateSegmentRefs(config: JourneyDef): string[];
+/**
+ * Collect segment IDs referenced in a Journey API response.
+ * This is the API-format counterpart to collectSegmentIdsFromJourney (which works with JourneyDef).
+ *
+ * Used during push operations to understand which segments are referenced by a journey
+ * for determining expanded rule comparisons and segment ordering.
+ *
+ * @param journey - Journey API response object
+ * @returns Set of segment IDs referenced in the journey
+ */
+export declare function collectSegmentIdsFromJourneyApi(journey: Journey): Set<string>;
 //# sourceMappingURL=journey-yaml.d.ts.map