@treasuredata/tdx 0.9.7 → 0.10.0

package/dist/sdk/segment/push-workflow.d.ts

@@ -0,0 +1,953 @@
+/**
+ * Push workflow for child segments and journeys.
+ *
+ * This module provides types and helper functions for pushing child segments
+ * and journeys to Treasure Data. The complex execution logic with progress
+ * reporting remains in the command layer.
+ */
+/**
+ * Placeholder prefix for pending embedded segments.
+ * Used to mark segments that will be created after the journey exists.
+ */
+export declare const PENDING_SEGMENT_PREFIX = "__pending_";
+/**
+ * Placeholder prefix for pending embedded activations.
+ * Used to mark activations that will be created after the journey exists.
+ */
+export declare const PENDING_ACTIVATION_PREFIX = "__pending_act_";
+/**
+ * Create a pending segment placeholder ID
+ */
+export declare function createPendingSegmentId(name: string): string;
+/**
+ * Check if a segment ID is a pending placeholder
+ */
+export declare function isPendingSegmentId(segmentId: string): boolean;
+/**
+ * Extract the original name from a pending segment placeholder
+ */
+export declare function extractPendingSegmentName(segmentId: string): string;
+/**
+ * Create a pending activation placeholder ID
+ */
+export declare function createPendingActivationId(name: string): string;
+/**
+ * Check if an activation ID is a pending placeholder
+ */
+export declare function isPendingActivationId(activationId: string): boolean;
+/**
+ * Extract the original name from a pending activation placeholder
+ */
+export declare function extractPendingActivationName(activationId: string): string;
+/**
+ * Ensure required fields for CDP API journey requests.
+ * CDP API requires description and state fields to be set.
+ */
+export declare function ensureJourneyDefaults(attrs: Record<string, unknown>): void;
+/**
+ * Calculate TD folder path from local path, accounting for scoped push
+ *
+ * @param localFolderPath - Relative path from the source directory
+ * @param isScoped - Whether this is a scoped push (from subdirectory)
+ * @param scopedFolderPath - The scoped folder path (relative to config root)
+ * @returns The full TD folder path
+ */
+export declare function resolveTDFolderPath(localFolderPath: string, isScoped: boolean, scopedFolderPath: string): string;
+/**
+ * Add folders to create for a single folder path.
+ * Adds all parent folders that don't exist in the pathToId map.
+ *
+ * @param folderPath - The target folder path
+ * @param folderPathToId - Map of existing folder paths to IDs
+ * @param foldersToCreate - Set to add new folders to
+ */
+export declare function addFoldersToCreate(folderPath: string, folderPathToId: Map<string, string>, foldersToCreate: Set<string>): void;
+import type { ActivationResponse, CreateActivationRequest, SegmentResponse, Journey, SegmentFolder, JourneyListItem, JourneyActivationStep } from '../types/cdp.js';
+import type { SegmentDef, ActivationDef } from './types/segment-def.js';
+import { type JourneyDef, type JourneyResponseToDefContext } from './journey-yaml.js';
+import { type ActivationConversionContext } from './child-segment-yaml.js';
+export type { ActivationConversionContext };
+import type { RuleDef } from './types/segment-def.js';
+import type { SegmentSDK } from '../segment.js';
+import type { JourneySDK } from '../journey.js';
+import type { UserSDK } from '../user.js';
+import type { ConnectionSDK } from '../connection.js';
+import type { ProgressReporter } from '../types/progress.js';
+import { type ValidationResult } from './yaml-validator.js';
+/**
+ * Dependencies for the push workflow.
+ * These are the SDK instances needed for fetching and resolving data.
+ */
+export interface PushWorkflowDeps {
+    segment: SegmentSDK;
+    journey: JourneySDK;
+    user: UserSDK;
+    connection: ConnectionSDK;
+}
+/**
+ * Options for preparePushSegments.
+ */
+export interface PreparePushSegmentsOptions {
+    /** Source directory (defaults to resolving from tdx.json) */
+    sourceDir?: string;
+    /** Push only a single file */
+    singleFilePath?: string;
+    /** Only process journeys (skip segments) */
+    journeysOnly?: boolean;
+    /** Include deletion of server resources not in local YAML */
+    includeDelete?: boolean;
+    /** Progress callback */
+    onProgress?: (phase: string, detail?: string) => void;
+}
+/**
+ * Activation sync action during push
+ */
+export interface ActivationAction {
+    /** Action type: create, update, or delete */
+    type: 'create' | 'update' | 'delete';
+    /** Activation name */
+    name: string;
+    /** YAML activation definition (for create/update) */
+    yamlActivation?: ActivationDef;
+    /** Existing activation response (for update/delete) */
+    existingActivation?: ActivationResponse;
+    /** Formatted diff string */
+    diff?: string;
+    /** Pre-validated API request (set during planning to avoid re-validation during execution) */
+    validatedRequest?: CreateActivationRequest;
+}
+/**
+ * Segment file to be pushed
+ */
+export interface SegmentPushFile {
+    /** Path relative to source directory */
+    relativePath: string;
+    /** Absolute path on filesystem */
+    absolutePath: string;
+    /** Parsed YAML configuration */
+    yamlConfig: SegmentDef;
+    /** TD folder path (e.g., "marketing/campaigns") */
+    folderPath: string;
+    /** Existing segment if updating */
+    existingSegment?: SegmentResponse;
+    /** Existing activations for this segment */
+    existingActivations: ActivationResponse[];
+    /** Whether this is a new segment */
+    isNew: boolean;
+    /** Whether this segment has changes */
+    hasChanges: boolean;
+    /** Formatted diff string */
+    diff?: string;
+    /** Activation actions to perform */
+    activationActions: ActivationAction[];
+}
+/**
+ * Journey file to be pushed
+ */
+export interface JourneyPushFile {
+    /** Path relative to source directory */
+    relativePath: string;
+    /** Absolute path on filesystem */
+    absolutePath: string;
+    /** Parsed YAML configuration */
+    yamlConfig: JourneyDef;
+    /** TD folder path */
+    folderPath: string;
+    /** Existing journey if updating */
+    existingJourney?: Journey;
+    /** Whether this is a new journey */
+    isNew: boolean;
+    /** Whether this journey has changes */
+    hasChanges: boolean;
+    /** Formatted diff string */
+    diff?: string;
+}
+/**
+ * Result of push preparation (preview)
+ */
+export interface PushPrepareResult {
+    /** Resolved parent segment name */
+    parentName: string;
+    /** Parent segment ID */
+    parentId: string;
+    /** Source directory */
+    sourceDir: string;
+    /** Segment files to push */
+    segmentFiles: SegmentPushFile[];
+    /** Journey files to push */
+    journeyFiles: JourneyPushFile[];
+    /** Folders to create (paths) */
+    foldersToCreate: string[];
+    /** Segments to delete (if --delete flag) */
+    segmentsToDelete: SegmentResponse[];
+    /** Journeys to delete (if --delete flag) */
+    journeysToDelete: Journey[];
+    /** Summary counts */
+    counts: {
+        segments: {
+            new: number;
+            changed: number;
+            unchanged: number;
+        };
+        journeys: {
+            new: number;
+            changed: number;
+            unchanged: number;
+        };
+        activations: {
+            create: number;
+            update: number;
+            delete: number;
+        };
+        folders: number;
+        deletions: {
+            segments: number;
+            journeys: number;
+        };
+    };
+    /** Whether there are any changes to push */
+    hasChanges: boolean;
+    /** Pre-built execution context (to avoid re-fetching during execution) */
+    executionContext?: PushExecutionContext;
+}
+/**
+ * Execution context containing all resolved IDs and maps needed for push.
+ * This is built during preparation to avoid re-fetching during execution.
+ */
+export interface PushExecutionContext {
+    /** Root folder ID from parent segment */
+    rootFolderId?: string;
+    /** Folder path to ID map */
+    folderPathToId: Map<string, string>;
+    /** Folder ID to path map */
+    folderIdToPath: Map<string, string>;
+    /** Segment name to ID map */
+    segmentNameToId: Map<string, string>;
+    /** Activations indexed by segment ID */
+    activationsBySegmentId: Map<string, ActivationResponse[]>;
+    /** User email to ID map */
+    emailToIdMap: Map<string, number>;
+    /** User ID to email map */
+    idToEmailMap: Map<number, string>;
+    /** Connection name to ID map */
+    connectionNameToIdMap: Map<string, number>;
+    /** Connection ID to name map */
+    connectionIdToNameMap: Map<string, string>;
+    /** Connection name to type map */
+    connectionNameToTypeMap: Map<string, string>;
+}
+/**
+ * Progress event types during push operation
+ */
+export type PushProgressEvent = {
+    type: 'folder_creating';
+    folder: string;
+} | {
+    type: 'folder_created';
+    folder: string;
+    folderId: string;
+} | {
+    type: 'segment_creating';
+    name: string;
+} | {
+    type: 'segment_created';
+    name: string;
+    segmentId: string;
+} | {
+    type: 'segment_updating';
+    name: string;
+} | {
+    type: 'segment_updated';
+    name: string;
+} | {
+    type: 'segment_deleting';
+    name: string;
+} | {
+    type: 'segment_deleted';
+    name: string;
+} | {
+    type: 'activation_creating';
+    segmentName: string;
+    activationName: string;
+} | {
+    type: 'activation_created';
+    segmentName: string;
+    activationName: string;
+} | {
+    type: 'activation_updating';
+    segmentName: string;
+    activationName: string;
+} | {
+    type: 'activation_updated';
+    segmentName: string;
+    activationName: string;
+} | {
+    type: 'activation_deleting';
+    segmentName: string;
+    activationName: string;
+} | {
+    type: 'activation_deleted';
+    segmentName: string;
+    activationName: string;
+} | {
+    type: 'journey_creating';
+    name: string;
+} | {
+    type: 'journey_created';
+    name: string;
+    journeyId: string;
+} | {
+    type: 'journey_updating';
+    name: string;
+} | {
+    type: 'journey_updated';
+    name: string;
+} | {
+    type: 'journey_deleting';
+    name: string;
+} | {
+    type: 'journey_deleted';
+    name: string;
+} | {
+    type: 'embedded_segment_creating';
+    journeyName: string;
+    segmentName: string;
+} | {
+    type: 'embedded_segment_created';
+    journeyName: string;
+    segmentName: string;
+} | {
+    type: 'embedded_activation_creating';
+    journeyName: string;
+    activationName: string;
+} | {
+    type: 'embedded_activation_created';
+    journeyName: string;
+    activationName: string;
+};
+/**
+ * Result of a push operation (async task with progress)
+ */
+export interface PushTaskResult<T> {
+    data: T;
+}
+/**
+ * Callbacks for customizing push UI behavior.
+ * All callbacks are optional - defaults will be used if not provided.
+ */
+export interface PushUICallbacks {
+    /**
+     * Execute an async task with progress indication.
+     * This wraps operations like API calls that may take time.
+     * @param message - Description of the operation
+     * @param task - Async function to execute
+     * @returns Task result
+     */
+    withProgress: <T>(message: string, task: () => Promise<T>) => Promise<PushTaskResult<T>>;
+    /**
+     * Called when a progress event occurs during execution.
+     * @param event - The progress event
+     */
+    onProgress?: (event: PushProgressEvent) => void;
+    /**
+     * Display the push summary before confirmation.
+     * @param prepared - The prepared push result
+     * @param parentName - Parent segment name
+     * @param sourceDir - Source directory path
+     */
+    displaySummary?: (prepared: PushPrepareResult, parentName: string, sourceDir: string) => void;
+    /**
+     * Display diff for a changed item.
+     * @param type - Item type ('segment' | 'journey')
+     * @param name - Item name
+     * @param diff - Diff string (or undefined if no diff)
+     * @param isNew - Whether this is a new item
+     */
+    displayDiff?: (type: 'segment' | 'journey', name: string, diff: string | undefined, isNew: boolean) => void;
+    /**
+     * Ask for user confirmation before executing push.
+     * @param totalChanges - Number of total changes
+     * @returns true if confirmed, false to abort
+     */
+    confirm?: (totalChanges: number) => Promise<boolean>;
+    /**
+     * Log an info message (e.g., blue for folder creation).
+     * Reserved for future use.
+     */
+    logInfo?: (message: string) => void;
+    /**
+     * Log a success message (e.g., green for created/updated items).
+     */
+    logSuccess?: (message: string) => void;
+    /**
+     * Log a warning message (e.g., yellow for updates).
+     * Reserved for future use.
+     */
+    logWarning?: (message: string) => void;
+    /**
+     * Log a deleted item (e.g., red for deletions).
+     */
+    logDeleted?: (message: string) => void;
+}
+/**
+ * Prepare segment files for push by calculating diffs and activation actions.
+ *
+ * @param parsedSegments - Parsed segment YAML files
+ * @param context - Execution context with resolved maps
+ * @param activationContext - Context for activation validation
+ * @param isScoped - Whether this is a scoped push
+ * @param scopedFolderPath - The scoped folder path
+ * @returns Prepared segment files and folders to create
+ */
+export declare function prepareSegmentFiles(parsedSegments: ParsedSegmentFile[], context: {
+    segmentByFolderAndName: Map<string, SegmentResponse>;
+    activationsBySegmentId: Map<string, ActivationResponse[]>;
+    folderPathToId: Map<string, string>;
+    idToEmailMap: Map<number, string>;
+    connectionIdToNameMap: Map<string, string>;
+}, activationContext: ActivationConversionContext, isScoped: boolean, scopedFolderPath: string): Promise<{
+    segmentFiles: SegmentPushFile[];
+    foldersToCreate: Set<string>;
+}>;
+/**
+ * Info passed to fetchJourney callback for progress reporting
+ */
+export interface JourneyFetchInfo {
+    /** Journey ID to fetch */
+    journeyId: string;
+    /** Journey name (for display) */
+    journeyName: string;
+    /** Version number (for multi-version fetches) */
+    versionNumber?: number;
+    /** Whether this is a multi-version fetch */
+    isMultiVersion: boolean;
+}
+/**
+ * Context for journey preparation with fetch callbacks
+ */
+export interface JourneyPrepContext {
+    /** Fetch a single journey by ID (without spinner - progress is handled via reporter) */
+    fetchJourney: (info: JourneyFetchInfo) => Promise<Journey>;
+    /** Map from journey bundle lookup key to list of journey versions */
+    journeyBundlesByFolderAndName: Map<string, JourneyListItem[]>;
+    /** Map from folder path to folder ID */
+    folderPathToId: Map<string, string>;
+    /** Map from user ID to email */
+    idToEmailMap: Map<number, string>;
+    /** Map from connection ID to name */
+    connectionIdToNameMap: Map<string, string>;
+    /** Existing segments for context building */
+    existingSegments: SegmentResponse[];
+    /** Parent segment ID */
+    parentId: string;
+    /** SDK deps for context creation */
+    deps: PushWorkflowDeps;
+    /** Progress reporter for status updates */
+    progress?: ProgressReporter;
+    /** Pre-fetched journey details by ID (optimization to avoid individual getJourney calls) */
+    journeyById?: Map<string, Journey>;
+    /** Pre-fetched activation steps by ID (optimization to avoid individual getActivation calls) */
+    activationStepsById?: Map<string, JourneyActivationStep>;
+}
+/**
+ * Prepare journey files for push by calculating diffs.
+ *
+ * @param parsedJourneys - Parsed journey YAML files
+ * @param context - Context with fetch callbacks and maps
+ * @param isScoped - Whether this is a scoped push
+ * @param scopedFolderPath - The scoped folder path
+ * @returns Prepared journey files and folders to create
+ */
+export declare function prepareJourneyFiles(parsedJourneys: ParsedJourneyFile[], context: JourneyPrepContext, isScoped: boolean, scopedFolderPath: string): Promise<{
+    journeyFiles: JourneyPushFile[];
+    foldersToCreate: Set<string>;
+}>;
+/**
+ * Calculate activation actions (create/update/delete) by comparing YAML with existing.
+ * Matches activations by name within a segment.
+ */
+export declare function calculateActivationActions(yamlActivations: ActivationDef[], existingActivations: ActivationResponse[], idToEmailMap?: Map<number, string>, connectionIdToNameMap?: Map<string, string>): ActivationAction[];
+/**
+ * Result of segment diff calculation
+ */
+export interface SegmentDiffResult {
+    /** Whether this is a new segment */
+    isNew: boolean;
+    /** Whether there are changes */
+    hasChanges: boolean;
+    /** Formatted diff string (only if has changes or is new) */
+    diff?: string;
+}
+/**
+ * Calculate diff for a segment comparing local YAML with existing server state.
+ *
+ * @param yamlConfig - Local YAML segment configuration
+ * @param existingSegment - Existing segment from server (undefined if new)
+ * @param existingActivations - Existing activations for the segment
+ * @param idToEmailMap - Map of user IDs to emails for comparison
+ * @param connectionIdToNameMap - Map of connection IDs to names
+ * @returns Diff result with isNew, hasChanges, and formatted diff
+ */
+export declare function calculateSegmentDiff(yamlConfig: SegmentDef, existingSegment: SegmentResponse | undefined, existingActivations: ActivationResponse[], idToEmailMap?: Map<number, string>, connectionIdToNameMap?: Map<string, string>): SegmentDiffResult;
+/**
+ * Result of journey diff calculation
+ */
+export interface JourneyDiffResult {
+    /** Whether this is a new journey */
+    isNew: boolean;
+    /** Whether there are changes */
+    hasChanges: boolean;
+    /** Formatted diff string (only if has changes or is new) */
+    diff?: string;
+}
+/**
+ * Calculate diff for a journey comparing local YAML with server state.
+ *
+ * @param localYaml - Local YAML journey configuration
+ * @param existingYaml - Existing journey converted to YAML format (undefined if new)
+ * @returns Diff result with isNew, hasChanges, and formatted diff
+ */
+export declare function calculateJourneyDiff(localYaml: JourneyDef, existingYaml: JourneyDef | undefined): JourneyDiffResult;
+/**
+ * Find segments on server that are not in local YAML files.
+ * These are candidates for deletion.
+ *
+ * @param existingSegments - All segments from server
+ * @param localSegments - Local segment configs with folder paths
+ * @param folderIdToPath - Map of folder IDs to paths
+ * @param scopedFolderPath - Scoped folder path (if scoped push)
+ * @param isScoped - Whether this is a scoped push
+ * @returns Segments that exist on server but not in YAML
+ */
+export declare function findSegmentsToDelete(existingSegments: SegmentResponse[], localSegments: Array<{
+    yamlConfig: SegmentDef;
+    folderPath: string;
+}>, folderIdToPath: Map<string, string>, scopedFolderPath: string, isScoped: boolean): SegmentResponse[];
+/**
+ * Journey list item for deletion check
+ */
+export interface JourneyListItemForDeletion {
+    folderId?: string | null;
+    journeyBundleName: string;
+}
+/**
+ * Find journeys on server that are not in local YAML files.
+ * These are candidates for deletion.
+ *
+ * @param existingJourneys - All journeys from server
+ * @param localJourneys - Local journey configs with folder paths
+ * @param folderIdToPath - Map of folder IDs to paths
+ * @param scopedFolderPath - Scoped folder path (if scoped push)
+ * @param isScoped - Whether this is a scoped push
+ * @returns Journeys that exist on server but not in YAML
+ */
+export declare function findJourneysToDelete<T extends JourneyListItemForDeletion>(existingJourneys: T[], localJourneys: Array<{
+    yamlConfig: JourneyDef;
+    folderPath: string;
+}>, folderIdToPath: Map<string, string>, scopedFolderPath: string, isScoped: boolean): T[];
+/**
+ * Build a map from "folderPath:segmentName" to segment for lookup during push.
+ * This allows matching local segments to existing server segments by folder + name.
+ *
+ * @param segments - Array of existing segments from server
+ * @param folderIdToPath - Map from folder ID to folder path
+ * @returns Map keyed by "folderPath:segmentName"
+ */
+export declare function buildSegmentLookupMap(segments: SegmentResponse[], folderIdToPath: Map<string, string>): Map<string, SegmentResponse>;
+/**
+ * Build a map from segment name to segment ID.
+ * Used for journey segment reference resolution.
+ *
+ * @param segments - Array of existing segments from server
+ * @returns Map from segment name to ID
+ */
+export declare function buildSegmentNameToIdMap(segments: SegmentResponse[]): Map<string, string>;
+/**
+ * Journey list item with required fields for bundle grouping.
+ */
+export interface JourneyListItemForBundleMap {
+    id: string;
+    folderId?: string | null;
+    journeyBundleName: string;
+    versionNumber?: number | null;
+}
+/**
+ * Build a map from "folderPath:journeyBundleName" to journey versions.
+ * Groups all versions of a journey bundle together, sorted by version number.
+ *
+ * @param journeys - Array of existing journeys from server
+ * @param folderIdToPath - Map from folder ID to folder path
+ * @returns Map keyed by "folderPath:journeyBundleName", values are sorted by version
+ */
+export declare function buildJourneyBundleLookupMap<T extends JourneyListItemForBundleMap>(journeys: T[], folderIdToPath: Map<string, string>): Map<string, T[]>;
+/**
+ * Collect folders that need to be created for a set of folder paths.
+ * Returns all parent folders that don't exist in the folderPathToId map.
+ *
+ * @param folderPaths - Array of folder paths that need to exist
+ * @param folderPathToId - Map of existing folder paths to IDs
+ * @returns Set of folder paths that need to be created (in creation order)
+ */
+export declare function collectFoldersToCreate(folderPaths: string[], folderPathToId: Map<string, string>): Set<string>;
+/**
+ * Parsed local segment file with folder path
+ */
+export interface ParsedSegmentFile {
+    yamlConfig: SegmentDef;
+    folderPath: string;
+    sourcePath: string;
+}
+/**
+ * Parsed local journey file with folder path
+ */
+export interface ParsedJourneyFile {
+    yamlConfig: JourneyDef;
+    folderPath: string;
+    sourcePath: string;
+}
+/**
+ * Result of parsing and classifying local YAML files
+ */
+export interface ParsedLocalFiles {
+    segments: ParsedSegmentFile[];
+    journeys: ParsedJourneyFile[];
+}
+/**
+ * Parse and classify YAML files into segments and journeys.
+ * Segments are normalized to match server-converted YAML format.
+ *
+ * @param yamlFiles - Array of absolute paths to YAML files
+ * @param sourceDir - Source directory (for calculating relative paths)
+ * @param options - Options for parsing
+ * @returns Parsed and classified segments and journeys
+ * @throws Error if any file cannot be parsed
+ */
+export declare function parseAndClassifyYamlFiles(yamlFiles: string[], sourceDir: string, options?: {
+    skipSegments?: boolean;
+}): ParsedLocalFiles;
+/**
+ * File validation error with source information
+ */
+export interface FileValidationError {
+    filePath: string;
+    source: string;
+    result: ValidationResult;
+    isJourney: boolean;
+}
+/**
+ * Validate parsed YAML files for segment and journey definitions.
+ * Runs offline validation to catch syntax errors before pushing.
+ *
+ * @param parsed - Parsed segments and journeys from parseAndClassifyYamlFiles
+ * @param sourceDir - Source directory for relative paths in error messages
+ * @returns Array of validation errors (empty if all valid)
+ */
+export declare function validateParsedFiles(parsed: ParsedLocalFiles, sourceDir: string): FileValidationError[];
+/**
+ * Format validation errors for display.
+ * Returns formatted error messages suitable for CLI output.
+ */
+export declare function formatValidationErrors(errors: FileValidationError[]): string;
+/**
+ * Result of building local expanded rule mappings for journey comparison.
+ */
+export interface LocalExpandedRuleMappings {
+    /** Set of segment names defined in local YAML */
+    existingLocalSegmentNames: Set<string>;
+    /** Map from segment name to normalized rule */
+    localSegmentRules: Map<string, RuleDef>;
+    /** Map from expanded rule hash to local segment names ordered by usage */
+    localExpandedRuleToNames: Map<string, string[]>;
+}
+/**
+ * Build local expanded rule mappings for journey comparison.
+ * This allows matching server segments to local segments by expanded rule content.
+ *
+ * Key insight: Instead of matching by segment reference NAMES (which are unstable),
+ * we match by EXPANDED rule content. When a rule references another segment via
+ * include/exclude, we expand it to include the actual referenced rule's content.
+ *
+ * @param segments - Map of segment name to embedded segment definition from local YAML
+ * @returns Mappings for comparing server segments to local YAML
+ */
+export declare function buildLocalExpandedRuleMappings(journey: JourneyDef): LocalExpandedRuleMappings;
+/**
+ * Create a resolver function for segment names to IDs.
+ * Used when resolving include/exclude references in embedded segment rules.
+ *
+ * @param segmentNameToId - Map of segment names to IDs
+ * @param embeddedSegmentName - Name of the embedded segment containing the reference (for error messages)
+ * @returns Resolver function that throws SDKError if segment is not found
+ */
+export declare function createSegmentIdResolver(segmentNameToId: Map<string, string>, embeddedSegmentName: string): (segmentName: string) => Promise<string>;
+/**
+ * Extract root folder ID from parent segment response.
+ * Used as default folder for new journeys.
+ *
+ * @param parentSegment - Parent segment response with relationships
+ * @returns Root folder ID or undefined
+ */
+export declare function extractRootFolderId(parentSegment: {
+    relationships?: {
+        parentSegmentFolder?: {
+            data?: {
+                id?: string;
+            };
+        };
+        parentFolder?: {
+            data?: {
+                id?: string;
+            };
+        };
+    };
+}): string | undefined;
+/**
+ * Connection maps for resolving names/IDs in activations.
+ */
+export interface ConnectionMaps {
+    /** Map from connection name to ID */
+    nameToId: Map<string, number>;
+    /** Map from connection ID to name */
+    idToName: Map<string, string>;
+    /** Map from connection name to type */
+    nameToType: Map<string, string>;
+}
+/**
+ * Build connection maps from a list of connections.
+ *
+ * @param connections - Array of connections with id, name, and type
+ * @returns Connection maps for name/ID resolution
+ */
+export declare function buildConnectionMaps(connections: Array<{
+    id: string;
+    name: string;
+    type: string;
+}>): ConnectionMaps;
+/**
+ * Push statistics for segments, journeys, activations, and folders.
+ */
+export interface PushStats<TJourneyToDelete = JourneyListItemForDeletion> {
+    segments: {
+        new: SegmentPushFile[];
+        changed: SegmentPushFile[];
+        unchanged: SegmentPushFile[];
+        toDelete: SegmentResponse[];
+    };
+    journeys: {
+        new: JourneyPushFile[];
+        changed: JourneyPushFile[];
+        unchanged: JourneyPushFile[];
+        toDelete: TJourneyToDelete[];
+    };
+    activations: {
+        all: ActivationAction[];
+        toCreate: ActivationAction[];
+        toUpdate: ActivationAction[];
+        toDelete: ActivationAction[];
+    };
+    folders: {
+        toCreate: string[];
+    };
+    counts: {
+        segments: {
+            new: number;
+            changed: number;
+            unchanged: number;
+            toDelete: number;
+        };
+        journeys: {
+            new: number;
+            changed: number;
+            unchanged: number;
+            toDelete: number;
+        };
+        activations: {
+            create: number;
+            update: number;
+            delete: number;
+        };
+        folders: number;
+    };
+    hasChanges: boolean;
+}
+/**
+ * Calculate statistics for a push operation.
+ *
+ * @param segmentFiles - Segment files to push
+ * @param journeyFiles - Journey files to push
+ * @param foldersToCreate - Set of folders to create
+ * @param segmentsToDelete - Segments on server not in YAML
+ * @param journeysToDelete - Journeys on server not in YAML
+ * @param includeDelete - Whether to include deletions
+ * @param journeysOnly - Whether to skip segment stats
+ * @returns Push statistics
+ */
+export declare function calculatePushStats<TJourneyToDelete extends JourneyListItemForDeletion>(segmentFiles: SegmentPushFile[], journeyFiles: JourneyPushFile[], foldersToCreate: Set<string>, segmentsToDelete: SegmentResponse[], journeysToDelete: TJourneyToDelete[], includeDelete: boolean, journeysOnly: boolean): PushStats<TJourneyToDelete>;
+/**
+ * Build the execution context from dependencies.
+ * This fetches all the data needed for push execution and builds lookup maps.
+ *
+ * @param deps - SDK dependencies
+ * @param parentId - Resolved parent segment ID
+ * @param existingSegments - List of existing segments
+ * @param existingFolders - List of existing folders
+ * @param journeysOnly - Skip activation fetching when only processing journeys
+ * @returns The execution context with all resolved maps
+ */
+export declare function buildPushExecutionContext(deps: PushWorkflowDeps, parentId: string, parentSegment: {
+    relationships?: {
+        parentSegmentFolder?: {
+            data?: {
+                id?: string;
+            };
+        };
+        parentFolder?: {
+            data?: {
+                id?: string;
+            };
+        };
+    };
+}, existingSegments: SegmentResponse[], existingFolders: SegmentFolder[], journeysOnly: boolean): Promise<PushExecutionContext>;
+/**
+ * Create a YAML context factory for converting server journey state to comparable YAML.
+ *
+ * This is used during push to build a YAML representation of the server state that can
+ * be compared with the local YAML. The key difference from pull is that we need to match
+ * server segments to local segments by expanded rule content (not just name) to enable
+ * proper diff calculation.
+ *
+ * @param deps - SDK dependencies for fetching data
+ * @param parentId - Parent segment ID
+ * @param existingSegments - List of existing segments (for local cache lookup)
+ * @param localExpandedRuleMappings - Mappings from buildLocalExpandedRuleMappings()
+ * @param idToEmailMap - User ID to email mapping
+ * @param connectionIdToNameMap - Connection ID to name mapping
+ * @param prefetchedActivationSteps - Pre-fetched activation steps by ID (optional, for optimization)
+ * @param prefetchedJourneyById - Pre-fetched journey details by ID (optional, for jump target resolution)
+ * @returns Factory object with createYamlContext method
+ */
+export declare function createPushYamlContextForBundle(deps: PushWorkflowDeps, parentId: string, existingSegments: SegmentResponse[], localExpandedRuleMappings: LocalExpandedRuleMappings, idToEmailMap: Map<number, string>, connectionIdToNameMap: Map<string, string>, prefetchedActivationSteps?: Map<string, JourneyActivationStep>, prefetchedJourneyById?: Map<string, Journey>): {
+    createYamlContext: (journeyId: string) => JourneyResponseToDefContext;
+    prefetchJourneySegments: (journeyVersionIds: string[]) => Promise<void>;
+};
+/**
+ * Options for executePushSegments
+ */
+export interface ExecutePushSegmentsOptions {
+    /** Parent segment ID */
+    parentId: string;
+}
+/**
+ * Result of pushing segments
+ */
+export interface PushSegmentsResult {
+    /** Number of segments created */
+    created: number;
+    /** Number of segments updated */
+    updated: number;
+    /** Number of segments deleted */
+    deleted: number;
+    /** Map of segment name to ID (for newly created segments) */
+    createdSegmentIds: Map<string, string>;
+    /** Activation stats */
+    activations: {
+        created: number;
+        updated: number;
+        deleted: number;
+    };
+}
+/**
+ * Execute segment push operations.
+ *
+ * @param deps - SDK dependencies
+ * @param segmentFiles - Prepared segment files to push
+ * @param executionContext - Execution context with resolved maps
+ * @param options - Push options
+ * @param ui - UI callbacks for progress and logging
+ * @returns Push result with counts and created IDs
+ */
+export declare function executePushSegments(deps: PushWorkflowDeps, segmentFiles: SegmentPushFile[], executionContext: PushExecutionContext, options: ExecutePushSegmentsOptions, ui: PushUICallbacks): Promise<PushSegmentsResult>;
+/**
+ * Options for executePushFolders
+ */
+export interface ExecutePushFoldersOptions {
+    /** Parent segment ID */
+    parentId: string;
+}
+/**
+ * Execute folder creation operations.
+ *
+ * @param deps - SDK dependencies
+ * @param foldersToCreate - Array of folder paths to create
+ * @param folderPathToId - Existing folder path to ID map (will be updated)
+ * @param options - Push options
+ * @param ui - UI callbacks
+ * @returns Updated folder path to ID map
+ */
+export declare function executePushFolders(deps: PushWorkflowDeps, foldersToCreate: string[], folderPathToId: Map<string, string>, options: ExecutePushFoldersOptions, ui: PushUICallbacks): Promise<Map<string, string>>;
+/**
+ * Execute segment deletion operations.
+ *
+ * @param deps - SDK dependencies
+ * @param segmentsToDelete - Segments to delete
+ * @param ui - UI callbacks
+ * @returns Number of segments deleted
+ */
+export declare function executePushSegmentDeletions(deps: PushWorkflowDeps, segmentsToDelete: SegmentResponse[], ui: PushUICallbacks): Promise<number>;
+/**
+ * Options for executePushJourneys
+ */
+export interface ExecutePushJourneysOptions {
+    /** Parent segment ID */
+    parentId: string;
+    /** Root folder ID from parent segment */
+    rootFolderId?: string;
+    /** Whether to output verbose debug info */
+    verbose?: boolean;
+}
+/**
+ * Result of a single journey push operation
+ */
+export interface JourneyPushResult {
+    /** Action taken: created, updated, or unchanged */
+    action: 'created' | 'updated' | 'unchanged';
+    /** Journey name */
+    name: string;
+    /** Journey ID (if created or updated) */
+    journeyId?: string;
+}
+/**
+ * Result of pushing all journeys
+ */
+export interface PushJourneysResult {
+    /** Individual journey results */
+    results: JourneyPushResult[];
+    /** Number of journeys created */
+    created: number;
+    /** Number of journeys updated */
+    updated: number;
+    /** Map of embedded segment names to IDs (created during journey push) */
+    embeddedSegmentNameToId: Map<string, string>;
+}
+/**
+ * Context for journey push operations.
+ * Provides SDK dependencies and resolution maps.
+ */
+export interface JourneyPushExecutionContext extends PushExecutionContext {
+    /** Existing segments on server */
+    existingSegments: SegmentResponse[];
+    /** Activation context for creating activations */
+    activationContext: ActivationConversionContext;
+}
+/**
+ * Execute journey push operations.
+ *
+ * @param deps - SDK dependencies
+ * @param journeyFiles - Prepared journey files to push
+ * @param executionContext - Execution context with resolved maps
+ * @param options - Push options
+ * @param ui - UI callbacks for progress and logging
+ * @returns Push result with counts and created IDs
+ */
+export declare function executePushJourneys(deps: PushWorkflowDeps, journeyFiles: JourneyPushFile[], executionContext: JourneyPushExecutionContext, options: ExecutePushJourneysOptions, ui: PushUICallbacks): Promise<PushJourneysResult>;
+//# sourceMappingURL=push-workflow.d.ts.map