@walkeros/core 4.8.2 → 4.8.3-next-1793115089237

package/dist/index.d.mts

@@ -378,7 +378,7 @@ declare function observeFromEnv(env: Record<string, string | undefined>): Observ
  * for inEvent/outEvent).
  */
 type FlowStatePhase = 'init' | 'in' | 'out' | 'error' | 'skip' | 'flush';
-type FlowStepType = 'source' | 'transformer' | 'collector' | 'destination' | 'store';
+type FlowStepType = StepKind;
 interface FlowStateBatch {
     size: number;
     index: number;
@@ -505,8 +505,17 @@ declare function createCauseLog(logger: CauseLogger, options?: CauseLogOptions):
  */
 declare function reportCause(collector: Instance$6 | undefined, logger: CauseLogger, key: CauseKey, message: string, context: Record<string, unknown>, level?: 'error' | 'warn'): void;
 
+/**
+ * The types of a step package (`walkerOS.type` in its package.json). A step
+ * package publishes an exports list, empty when it declares none, and a
+ * settings schema; the build checks both.
+ */
+declare const STEP_TYPES: readonly ["source", "transformer", "destination", "store"];
+
+/** The kind of a step package: one of `STEP_TYPES`. */
+type StepType = (typeof STEP_TYPES)[number];
 /** Identifies which kind of step a stepId belongs to. */
-type StepKind = 'collector' | 'source' | 'transformer' | 'destination' | 'store';
+type StepKind = 'collector' | StepType;
 /**
  * Build a stepId for use as a key in `Status.dropped` /
  * `Status.connectionErrors` (and future status maps). The collector-level
@@ -517,7 +526,7 @@ type StepKind = 'collector' | 'source' | 'transformer' | 'destination' | 'store'
  * log messages ("collector.queue overflow", "destination.dlq overflow").
  */
 declare function stepId(kind: 'collector'): 'collector';
-declare function stepId(kind: 'source' | 'transformer' | 'destination' | 'store', id: string): string;
+declare function stepId(kind: StepType, id: string): string;
 /**
  * Drop counters at a single step. Each buffer is optional: a step kind
  * may have only `queue` (collector), only `dlq`, both (destinations
@@ -959,9 +968,10 @@ type collector_SourceStatus = SourceStatus;
 type collector_Sources = Sources;
 type collector_Status = Status;
 type collector_StepKind = StepKind;
+type collector_StepType = StepType;
 declare const collector_stepId: typeof stepId;
 declare namespace collector {
-  export { type collector_BreakerState as BreakerState, type collector_Cascade as Cascade, type collector_CommandFn as CommandFn, type collector_CommandType as CommandType, type Config$6 as Config, type collector_DestinationStatus as DestinationStatus, type Destinations$1 as Destinations, type collector_DroppedCounters as DroppedCounters, type collector_InitConfig as InitConfig, type collector_InitConfigOf as InitConfigOf, type Instance$6 as Instance, type PushFn$1 as PushFn, type collector_PushOptions as PushOptions, type collector_SessionData as SessionData, type collector_SourceStatus as SourceStatus, type collector_Sources as Sources, type collector_Status as Status, type collector_StepKind as StepKind, type Stores$1 as Stores, type Transformers$1 as Transformers, collector_stepId as stepId };
+  export { type collector_BreakerState as BreakerState, type collector_Cascade as Cascade, type collector_CommandFn as CommandFn, type collector_CommandType as CommandType, type Config$6 as Config, type collector_DestinationStatus as DestinationStatus, type Destinations$1 as Destinations, type collector_DroppedCounters as DroppedCounters, type collector_InitConfig as InitConfig, type collector_InitConfigOf as InitConfigOf, type Instance$6 as Instance, type PushFn$1 as PushFn, type collector_PushOptions as PushOptions, type collector_SessionData as SessionData, type collector_SourceStatus as SourceStatus, type collector_Sources as Sources, type collector_Status as Status, type collector_StepKind as StepKind, type collector_StepType as StepType, type Stores$1 as Stores, type Transformers$1 as Transformers, collector_stepId as stepId };
 }
 
 /**
@@ -1699,7 +1709,11 @@ interface PushResult {
     dropped?: boolean;
     /** Event was rejected as invalid input: a client/producer fault, not a pipeline failure. */
     invalid?: boolean;
-    /** Human-readable failure reason when ok is false. */
+    /**
+     * Human-readable message when the event was rejected or a step before the
+     * destinations failed. A destination's own failure is in `failed`, under
+     * its id with a `reason`, and leaves this unset.
+     */
     error?: string;
     /**
      * Why the push failed when `ok` is false without a `failed` entry: a full
@@ -2491,7 +2505,8 @@ declare namespace Flow {
          * Name of the transformer to execute after this source captures an event.
          * Creates a pre-collector transformer chain. Chain ends at the collector.
          * If omitted, events route directly to the collector.
-         * Can be an array for explicit chain control (bypasses transformer.next resolution).
+         * Can be an array: its members run in order, and each member's own `next`
+         * runs right after that member.
          */
         next?: Route;
         /** Cache configuration for this source. */
@@ -2801,12 +2816,15 @@ declare namespace Flow {
     interface StepPageSession {
         /** Page globals merged over an examples env's `push` (the document). */
         globals: Record<string, unknown>;
-        /** Scripts added since `open`, with and without the loadVendor marker. */
+        /**
+         * Scripts added since `open`, with and without the loadVendor marker.
+         * A marked script loads (`load`, once) unless `failScripts` fails it.
+         */
         scripts(): {
             marked: number;
             unmarked: number;
         };
-        /** Fire `error` on every marked script (kit item 2, vendor-global). */
+        /** Fire `error` on every marked script, loaded or not (kit item 2, vendor-global). */
         failScripts(): void;
         /** Restore the stubs and remove the scripts added since `open`. */
         close(): void;
@@ -2828,7 +2846,10 @@ declare namespace Flow {
          * Whether this example is meant for public consumption (docs, UI, MCP default output).
          * Defaults to `true`. Set to `false` for test-only fixtures that should stay out of
          * user-facing surfaces but still run in test suites and remain available to
-         * `flow_simulate` / CLI `--simulate`.
+         * `flow_simulate` / CLI `--simulate`. A failure example (`public: false`
+         * with an `outcome`) is still listed on the docs page under "When it
+         * fails", by its title, description and outcome; its fixture `in` is
+         * never shown.
          */
         public?: boolean;
         in?: unknown;
@@ -2850,7 +2871,10 @@ declare namespace Flow {
         /**
          * The reported outcome of a failure or queue example (`public: false`):
          * the step's status in the push result and its reason code. Absent means
-         * the step must not fail.
+         * the step must not fail. The docs page lists every example with an
+         * outcome under "When it fails" by title, description and outcome, so it
+         * needs a reader-facing `description` (the docs build fails without one);
+         * its fixture `in` is never shown.
          */
         outcome?: StepOutcome;
         /** What the boundary answers for this example (a failure fixture). */
@@ -2873,6 +2897,64 @@ declare namespace Flow {
     }
     /** Named step examples keyed by scenario name. */
     type StepExamples = Record<string, StepExample>;
+    /**
+     * The settings a package needs to deliver, published as `examples.minimal`
+     * (for a package with several exports, as `exportExamples.<export>.minimal`).
+     * `composeQuickstart` turns it into the install line, the integrated code
+     * and a complete flow; the conformance kit runs it.
+     */
+    interface MinimalExample {
+        /**
+         * Only the settings the schema requires, plus any that `init` refuses to
+         * start without under `config`. A secret holds a placeholder value that
+         * satisfies the schema; generated code never shows it.
+         */
+        settings: Record<string, unknown>;
+        /**
+         * Server destinations: settings keys that hold credentials, mapped to the
+         * secret name the reader sets (`A-Z`, `0-9` and `_`), for example
+         * `{ accessToken: 'META_ACCESS_TOKEN' }`. Generated code reads them as
+         * `process.env.<NAME>` (integrated) and `$secret.<NAME>` (flow). A web
+         * destination holds no secret.
+         */
+        secrets?: Record<string, string>;
+        /**
+         * Destination config the package needs to deliver beyond its settings:
+         * `loadScript` for a web destination that loads its vendor script only
+         * when asked to.
+         */
+        config?: Pick<Config$5, 'loadScript'>;
+    }
+    /** The `$meta` of a package's walkerOS.json, as its build writes it. */
+    interface PackageMeta {
+        package: string;
+        version: string;
+        /** Step type: `source`, `transformer`, `destination` or `store`. */
+        type?: string;
+        platform?: string[];
+        renderer?: string;
+        /** Declared exports, export name to description. */
+        exports?: Record<string, string>;
+        docs?: string;
+        source?: string;
+    }
+    /** A package's quickstart, composed from its `$meta` and minimal example. */
+    interface Quickstart {
+        /** The install command. */
+        install: string;
+        /** TypeScript source that starts a flow with the package. */
+        integrated: string;
+        /** A complete flow with the package as its only step of its type. */
+        flow: Json;
+        /**
+         * What the conformance kit runs with: the settings (secrets as their
+         * placeholders) and the minimal example's config.
+         */
+        run: {
+            settings: Record<string, unknown>;
+            config?: Pick<Config$5, 'loadScript'>;
+        };
+    }
 }
 
 type AnyFunction$1<P extends unknown[] = never[], R = unknown> = (...args: P) => R;
@@ -3240,7 +3322,7 @@ interface Config$1<T extends TypesGeneric$1 = Types$1> extends Config$7<Mapping<
     async?: boolean | Record<string, boolean>;
     /** Mark as primary source; its push function becomes the exported `elb` from startFlow. */
     primary?: boolean;
-    /** Defer source initialization until these collector events fire (e.g., `['consent']`). */
+    /** Collector events (e.g., `['consent']`) that must fire before the source receives on() calls; init and event capture are not delayed. */
     require?: string[];
     /**
      * Provisioning options for `walkeros setup`. `boolean | object`.
@@ -4541,7 +4623,7 @@ declare function deepMerge<T extends Record<string, unknown>>(target: T, source:
  * Names `getEvent` knows: the standard events plus the generic default
  * `entity action`. Any other name does not compile.
  */
-type StandardEventName = 'entity action' | 'cart view' | 'checkout view' | 'order complete' | 'page view' | 'product add' | 'product view' | 'product visible' | 'promotion visible' | 'session start';
+type StandardEventName = 'entity action' | 'cart view' | 'checkout start' | 'order complete' | 'page view' | 'product add' | 'product view' | 'product visible' | 'promotion visible' | 'session start';
 /**
  * Creates a complete event with default values.
  * Used for testing and debugging.
@@ -5685,11 +5767,9 @@ interface ExampleSummary {
     name: string;
     description?: string;
 }
-interface WalkerOSPackageMeta {
+interface WalkerOSPackageMeta extends Pick<Flow.PackageMeta, 'version' | 'type'> {
     packageName: string;
-    version: string;
     description?: string;
-    type?: string;
     platform?: string | string[];
 }
 interface WalkerOSPackageInfo {
@@ -5727,6 +5807,11 @@ declare function fetchPackage(packageName: string, options?: {
     baseUrl?: string;
     client?: string;
 }): Promise<WalkerOSPackage>;
+/**
+ * The walkerOS metadata of a package, parsed from its walkerOS.json the same
+ * way for every source: a CDN release or a local package on disk.
+ */
+declare function parseWalkerOSJson(walkerOSJson: Record<string, unknown>): Omit<WalkerOSPackage, 'packageName' | 'version' | 'description'>;
 /**
  * @deprecated Use fetchPackage instead.
  * Still used by: entry.ts (validator), package-schemas.ts (MCP resource).
@@ -6626,4 +6711,4 @@ declare const REF_CODE_PREFIX = "$code:";
  */
 declare function scanFlowRefs(value: unknown, into?: Set<string>): Set<string>;
 
-export { type Acknowledgement, type ActivationGrant, type AssembleJourneysOptions, type BatchResponse, type BatchedPosterOptions, type BreakerState, type BuildFlag, CLOCK_SKEW_MS, CONTRACT_RULE_KEYS, cache as Cache, type CacheEnvelope, type CacheResult, type CauseKey, type CauseLog, type CauseLogOptions, type CauseLogger, type ChainContinuation, type ChainFrame, type ChainStep, type ClickIdEntry, collector as Collector, type CompiledCache, Const, context as Context, type Credential, DEFAULT_DESTINATION_TIMEOUT_MS, type Debounced, destination as Destination, type DestroyContext, type DestroyFn, type DroppedCounters, ENV_MARKER_PREFIX, EVENT_NOT_PROCESSED, elb as Elb, type EmitFn, type EventOutcome, type ExampleSummary, type FailureReason, FatalError, Flow, type FlowConfigResolver, FlowCycleError, FlowReferenceError, type FlowState, type FlowStateBatch, type FlowStatePhase, type FlowStepType, type GetStore, hint as Hint, hooks as Hooks, INTERNAL_SERVER_ERROR, type Ingest, type IngestEnvelope, type IngestMeta, InvalidEventError, type Journey, type JourneyAssembly, type JourneyBranch, type JourneyCorrelation, type JourneyEntry, type JourneyGap, type JourneyHop, type JourneyHopStatus, type JourneyPlatform, type JourneyStatus, type JourneyTopology, type JourneyTopologyNode, type JourneyUnattributed, type JsonSchema, Level, lifecycle as Lifecycle, type LifecycleContext, logger as Logger, MAPPING_NO_OPS, MAX_SESSION_MS, MOIN_PARAM, MOIN_PRODUCTION, mapping as Mapping, type MappingPosition, type MarketingParameters, matcher as Matcher, type MockLogger, type MoinTarget, type NextSteps, type NodeLikeRequest, OBSERVE_ENV_KEY, OBSERVE_STORAGE_KEY, type Observe, type ObserveCredential, type ObserveServer, type ObserveSlot, type ObserveWeb, type ObservedEnv, type ObserverFn, on as On, type ParsedGrant, type ParsedTraceparent, type PosterFetch, type PosterResponse, type PreviewCrypto, type PreviewFailure, type PreviewKey, type PreviewSubtle, type QueueReason, type QueuedReason, REF_CODE_PREFIX, REF_CONTRACT, REF_ENV, REF_FLOW, REF_FLOW_INLINE, REF_FLOW_NAME, REF_SECRET, REF_STORE, REF_VAR_FULL, REF_VAR_INLINE, RESERVED_WINDOW_GLOBALS, request as Request, type ResolveContractsOptions, type ResolveOptions, type RespondFn, type RespondOptions, type RouteContinuation, type RouteDecision, type RouteGraphNode, type RouteLabel, SECRET_MARKER_PREFIX, STEP_FIELD_ROLES, STEP_FUNCTION_KEYS, STEP_OPERATIVE_FIELDS, type ScheduleOptions, type SendDataValue, type SendHeaders, type SendResponse, type ServiceAccount, type SetupFn, simulation as Simulation, source as Source, type StandardEventName, type State, type StepEntryErrorCode, type StepEntryValidation, StepError, type StepErrorOptions, type StepField, type StepFieldRole, type StepFunctionKey, type StepKind, type StorageType, store as Store, type TelemetryLevel, type TelemetryOptions, type TelemetryOptionsSupplier, type Timer, transformer as Transformer, type TransformerMappingEntry, trigger as Trigger, URL_WINDOW_MS, type ValidateEvents, type VerifyParams, type VerifyResult, walkeros as WalkerOS, type WalkerOSPackage, type WalkerOSPackageInfo, type WalkerOSPackageMeta, type WindowCollectorCheck, acknowledge, advanceChain, anonymizeIP, applyState, applyUpdate, assembleJourneys, assign, batchResponse, branch, buildScopeFromNodeRequest, castToProperty, castValue, checkCache, checkWindowCollector, clone, compileCache, compileMatcher, compileState, createBatchedPoster, createCauseLog, createDestination, createEvent, createIngest, createLogger, createMappingRoot, createMockContext, createMockLogger, createRespond, createTelemetryObserver, createTimer, debounce, deepMerge, defaultClickIds, deleteByPath, deriveSpanId, emitStep, fetchPackage, fetchPackageSchema, filterValues, flattenIncludeSections, formatOut, getBrowser, getBrowserVersion, getByPath, getDeviceType, getErrorMessage, getEvent, getFlowSettings, getGrantedConsent, getHeaders, getId, getMappingEvent, getMappingKeyPaths, getMappingNoOpMessage, getMappingNoOpPaths, getMappingValue, getMarketingParameters, getNextSteps, getOS, getOSVersion, getPlatform, getRouteGraph, getSpanId, getStepFieldRole, getStepRuntimeProps, getTraceId, getTraceUntil, getTransformerMapping, getTransformerMappingWarnings, getUnknownStepKeys, isArguments, isArray, isBatchBody, isBoolean, isChainContinuation, isCommand, isDefined, isEnvObserve, isFunction, isNumber, isObject, isPathStepEntry, isPropertyType, isRouteArray, isRouteConfigEntry, isRouteContinuation, isSameType, isSampled, isScope, isStoreValue, isString, isThenable, mcpError, mcpResult, mergeContractSchemas, mergeMappingRule, mockEnv, networkErrorMessage, normalizeBody, normalizeHeaders, normalizeQuery, observeEnv, observeFromEnv, packageNameToVariable, parseCallPath, parseGrant, parseObserveCredential, parseTraceparent, parseUserAgent, processEventMapping, pushResultToOutcome, readCacheEnvelope, reportCause, requestToData, requestToParameter, resolveContracts, resolveDestinationTimeout, resolveSetup, resolveTelemetryOptions, scanFlowRefs, setByPath, setTraceUntil, startChain, stepCall, stepId, storeCache, throttle, throwError, toEventList, toFailureReason, transformData, traverseEnv, trim, tryCatch, tryCatchAsync, useHooks, validateStepEntry, verifyActivation, walkPath, wrapCacheEnvelope, wrapCondition, wrapFn, wrapValidate };
+export { type Acknowledgement, type ActivationGrant, type AssembleJourneysOptions, type BatchResponse, type BatchedPosterOptions, type BreakerState, type BuildFlag, CLOCK_SKEW_MS, CONTRACT_RULE_KEYS, cache as Cache, type CacheEnvelope, type CacheResult, type CauseKey, type CauseLog, type CauseLogOptions, type CauseLogger, type ChainContinuation, type ChainFrame, type ChainStep, type ClickIdEntry, collector as Collector, type CompiledCache, Const, context as Context, type Credential, DEFAULT_DESTINATION_TIMEOUT_MS, type Debounced, destination as Destination, type DestroyContext, type DestroyFn, type DroppedCounters, ENV_MARKER_PREFIX, EVENT_NOT_PROCESSED, elb as Elb, type EmitFn, type EventOutcome, type ExampleSummary, type FailureReason, FatalError, Flow, type FlowConfigResolver, FlowCycleError, FlowReferenceError, type FlowState, type FlowStateBatch, type FlowStatePhase, type FlowStepType, type GetStore, hint as Hint, hooks as Hooks, INTERNAL_SERVER_ERROR, type Ingest, type IngestEnvelope, type IngestMeta, InvalidEventError, type Journey, type JourneyAssembly, type JourneyBranch, type JourneyCorrelation, type JourneyEntry, type JourneyGap, type JourneyHop, type JourneyHopStatus, type JourneyPlatform, type JourneyStatus, type JourneyTopology, type JourneyTopologyNode, type JourneyUnattributed, type JsonSchema, Level, lifecycle as Lifecycle, type LifecycleContext, logger as Logger, MAPPING_NO_OPS, MAX_SESSION_MS, MOIN_PARAM, MOIN_PRODUCTION, mapping as Mapping, type MappingPosition, type MarketingParameters, matcher as Matcher, type MockLogger, type MoinTarget, type NextSteps, type NodeLikeRequest, OBSERVE_ENV_KEY, OBSERVE_STORAGE_KEY, type Observe, type ObserveCredential, type ObserveServer, type ObserveSlot, type ObserveWeb, type ObservedEnv, type ObserverFn, on as On, type ParsedGrant, type ParsedTraceparent, type PosterFetch, type PosterResponse, type PreviewCrypto, type PreviewFailure, type PreviewKey, type PreviewSubtle, type QueueReason, type QueuedReason, REF_CODE_PREFIX, REF_CONTRACT, REF_ENV, REF_FLOW, REF_FLOW_INLINE, REF_FLOW_NAME, REF_SECRET, REF_STORE, REF_VAR_FULL, REF_VAR_INLINE, RESERVED_WINDOW_GLOBALS, request as Request, type ResolveContractsOptions, type ResolveOptions, type RespondFn, type RespondOptions, type RouteContinuation, type RouteDecision, type RouteGraphNode, type RouteLabel, SECRET_MARKER_PREFIX, STEP_FIELD_ROLES, STEP_FUNCTION_KEYS, STEP_OPERATIVE_FIELDS, type ScheduleOptions, type SendDataValue, type SendHeaders, type SendResponse, type ServiceAccount, type SetupFn, simulation as Simulation, source as Source, type StandardEventName, type State, type StepEntryErrorCode, type StepEntryValidation, StepError, type StepErrorOptions, type StepField, type StepFieldRole, type StepFunctionKey, type StepKind, type StepType, type StorageType, store as Store, type TelemetryLevel, type TelemetryOptions, type TelemetryOptionsSupplier, type Timer, transformer as Transformer, type TransformerMappingEntry, trigger as Trigger, URL_WINDOW_MS, type ValidateEvents, type VerifyParams, type VerifyResult, walkeros as WalkerOS, type WalkerOSPackage, type WalkerOSPackageInfo, type WalkerOSPackageMeta, type WindowCollectorCheck, acknowledge, advanceChain, anonymizeIP, applyState, applyUpdate, assembleJourneys, assign, batchResponse, branch, buildScopeFromNodeRequest, castToProperty, castValue, checkCache, checkWindowCollector, clone, compileCache, compileMatcher, compileState, createBatchedPoster, createCauseLog, createDestination, createEvent, createIngest, createLogger, createMappingRoot, createMockContext, createMockLogger, createRespond, createTelemetryObserver, createTimer, debounce, deepMerge, defaultClickIds, deleteByPath, deriveSpanId, emitStep, fetchPackage, fetchPackageSchema, filterValues, flattenIncludeSections, formatOut, getBrowser, getBrowserVersion, getByPath, getDeviceType, getErrorMessage, getEvent, getFlowSettings, getGrantedConsent, getHeaders, getId, getMappingEvent, getMappingKeyPaths, getMappingNoOpMessage, getMappingNoOpPaths, getMappingValue, getMarketingParameters, getNextSteps, getOS, getOSVersion, getPlatform, getRouteGraph, getSpanId, getStepFieldRole, getStepRuntimeProps, getTraceId, getTraceUntil, getTransformerMapping, getTransformerMappingWarnings, getUnknownStepKeys, isArguments, isArray, isBatchBody, isBoolean, isChainContinuation, isCommand, isDefined, isEnvObserve, isFunction, isNumber, isObject, isPathStepEntry, isPropertyType, isRouteArray, isRouteConfigEntry, isRouteContinuation, isSameType, isSampled, isScope, isStoreValue, isString, isThenable, mcpError, mcpResult, mergeContractSchemas, mergeMappingRule, mockEnv, networkErrorMessage, normalizeBody, normalizeHeaders, normalizeQuery, observeEnv, observeFromEnv, packageNameToVariable, parseCallPath, parseGrant, parseObserveCredential, parseTraceparent, parseUserAgent, parseWalkerOSJson, processEventMapping, pushResultToOutcome, readCacheEnvelope, reportCause, requestToData, requestToParameter, resolveContracts, resolveDestinationTimeout, resolveSetup, resolveTelemetryOptions, scanFlowRefs, setByPath, setTraceUntil, startChain, stepCall, stepId, storeCache, throttle, throwError, toEventList, toFailureReason, transformData, traverseEnv, trim, tryCatch, tryCatchAsync, useHooks, validateStepEntry, verifyActivation, walkPath, wrapCacheEnvelope, wrapCondition, wrapFn, wrapValidate };

package/dist/index.d.ts

@@ -378,7 +378,7 @@ declare function observeFromEnv(env: Record<string, string | undefined>): Observ
  * for inEvent/outEvent).
  */
 type FlowStatePhase = 'init' | 'in' | 'out' | 'error' | 'skip' | 'flush';
-type FlowStepType = 'source' | 'transformer' | 'collector' | 'destination' | 'store';
+type FlowStepType = StepKind;
 interface FlowStateBatch {
     size: number;
     index: number;
@@ -505,8 +505,17 @@ declare function createCauseLog(logger: CauseLogger, options?: CauseLogOptions):
  */
 declare function reportCause(collector: Instance$6 | undefined, logger: CauseLogger, key: CauseKey, message: string, context: Record<string, unknown>, level?: 'error' | 'warn'): void;
 
+/**
+ * The types of a step package (`walkerOS.type` in its package.json). A step
+ * package publishes an exports list, empty when it declares none, and a
+ * settings schema; the build checks both.
+ */
+declare const STEP_TYPES: readonly ["source", "transformer", "destination", "store"];
+
+/** The kind of a step package: one of `STEP_TYPES`. */
+type StepType = (typeof STEP_TYPES)[number];
 /** Identifies which kind of step a stepId belongs to. */
-type StepKind = 'collector' | 'source' | 'transformer' | 'destination' | 'store';
+type StepKind = 'collector' | StepType;
 /**
  * Build a stepId for use as a key in `Status.dropped` /
  * `Status.connectionErrors` (and future status maps). The collector-level
@@ -517,7 +526,7 @@ type StepKind = 'collector' | 'source' | 'transformer' | 'destination' | 'store'
  * log messages ("collector.queue overflow", "destination.dlq overflow").
  */
 declare function stepId(kind: 'collector'): 'collector';
-declare function stepId(kind: 'source' | 'transformer' | 'destination' | 'store', id: string): string;
+declare function stepId(kind: StepType, id: string): string;
 /**
  * Drop counters at a single step. Each buffer is optional: a step kind
  * may have only `queue` (collector), only `dlq`, both (destinations
@@ -959,9 +968,10 @@ type collector_SourceStatus = SourceStatus;
 type collector_Sources = Sources;
 type collector_Status = Status;
 type collector_StepKind = StepKind;
+type collector_StepType = StepType;
 declare const collector_stepId: typeof stepId;
 declare namespace collector {
-  export { type collector_BreakerState as BreakerState, type collector_Cascade as Cascade, type collector_CommandFn as CommandFn, type collector_CommandType as CommandType, type Config$6 as Config, type collector_DestinationStatus as DestinationStatus, type Destinations$1 as Destinations, type collector_DroppedCounters as DroppedCounters, type collector_InitConfig as InitConfig, type collector_InitConfigOf as InitConfigOf, type Instance$6 as Instance, type PushFn$1 as PushFn, type collector_PushOptions as PushOptions, type collector_SessionData as SessionData, type collector_SourceStatus as SourceStatus, type collector_Sources as Sources, type collector_Status as Status, type collector_StepKind as StepKind, type Stores$1 as Stores, type Transformers$1 as Transformers, collector_stepId as stepId };
+  export { type collector_BreakerState as BreakerState, type collector_Cascade as Cascade, type collector_CommandFn as CommandFn, type collector_CommandType as CommandType, type Config$6 as Config, type collector_DestinationStatus as DestinationStatus, type Destinations$1 as Destinations, type collector_DroppedCounters as DroppedCounters, type collector_InitConfig as InitConfig, type collector_InitConfigOf as InitConfigOf, type Instance$6 as Instance, type PushFn$1 as PushFn, type collector_PushOptions as PushOptions, type collector_SessionData as SessionData, type collector_SourceStatus as SourceStatus, type collector_Sources as Sources, type collector_Status as Status, type collector_StepKind as StepKind, type collector_StepType as StepType, type Stores$1 as Stores, type Transformers$1 as Transformers, collector_stepId as stepId };
 }
 
 /**
@@ -1699,7 +1709,11 @@ interface PushResult {
     dropped?: boolean;
     /** Event was rejected as invalid input: a client/producer fault, not a pipeline failure. */
     invalid?: boolean;
-    /** Human-readable failure reason when ok is false. */
+    /**
+     * Human-readable message when the event was rejected or a step before the
+     * destinations failed. A destination's own failure is in `failed`, under
+     * its id with a `reason`, and leaves this unset.
+     */
     error?: string;
     /**
      * Why the push failed when `ok` is false without a `failed` entry: a full
@@ -2491,7 +2505,8 @@ declare namespace Flow {
          * Name of the transformer to execute after this source captures an event.
          * Creates a pre-collector transformer chain. Chain ends at the collector.
          * If omitted, events route directly to the collector.
-         * Can be an array for explicit chain control (bypasses transformer.next resolution).
+         * Can be an array: its members run in order, and each member's own `next`
+         * runs right after that member.
          */
         next?: Route;
         /** Cache configuration for this source. */
@@ -2801,12 +2816,15 @@ declare namespace Flow {
     interface StepPageSession {
         /** Page globals merged over an examples env's `push` (the document). */
         globals: Record<string, unknown>;
-        /** Scripts added since `open`, with and without the loadVendor marker. */
+        /**
+         * Scripts added since `open`, with and without the loadVendor marker.
+         * A marked script loads (`load`, once) unless `failScripts` fails it.
+         */
         scripts(): {
             marked: number;
             unmarked: number;
         };
-        /** Fire `error` on every marked script (kit item 2, vendor-global). */
+        /** Fire `error` on every marked script, loaded or not (kit item 2, vendor-global). */
         failScripts(): void;
         /** Restore the stubs and remove the scripts added since `open`. */
         close(): void;
@@ -2828,7 +2846,10 @@ declare namespace Flow {
          * Whether this example is meant for public consumption (docs, UI, MCP default output).
          * Defaults to `true`. Set to `false` for test-only fixtures that should stay out of
          * user-facing surfaces but still run in test suites and remain available to
-         * `flow_simulate` / CLI `--simulate`.
+         * `flow_simulate` / CLI `--simulate`. A failure example (`public: false`
+         * with an `outcome`) is still listed on the docs page under "When it
+         * fails", by its title, description and outcome; its fixture `in` is
+         * never shown.
          */
         public?: boolean;
         in?: unknown;
@@ -2850,7 +2871,10 @@ declare namespace Flow {
         /**
          * The reported outcome of a failure or queue example (`public: false`):
          * the step's status in the push result and its reason code. Absent means
-         * the step must not fail.
+         * the step must not fail. The docs page lists every example with an
+         * outcome under "When it fails" by title, description and outcome, so it
+         * needs a reader-facing `description` (the docs build fails without one);
+         * its fixture `in` is never shown.
          */
         outcome?: StepOutcome;
         /** What the boundary answers for this example (a failure fixture). */
@@ -2873,6 +2897,64 @@ declare namespace Flow {
     }
     /** Named step examples keyed by scenario name. */
     type StepExamples = Record<string, StepExample>;
+    /**
+     * The settings a package needs to deliver, published as `examples.minimal`
+     * (for a package with several exports, as `exportExamples.<export>.minimal`).
+     * `composeQuickstart` turns it into the install line, the integrated code
+     * and a complete flow; the conformance kit runs it.
+     */
+    interface MinimalExample {
+        /**
+         * Only the settings the schema requires, plus any that `init` refuses to
+         * start without under `config`. A secret holds a placeholder value that
+         * satisfies the schema; generated code never shows it.
+         */
+        settings: Record<string, unknown>;
+        /**
+         * Server destinations: settings keys that hold credentials, mapped to the
+         * secret name the reader sets (`A-Z`, `0-9` and `_`), for example
+         * `{ accessToken: 'META_ACCESS_TOKEN' }`. Generated code reads them as
+         * `process.env.<NAME>` (integrated) and `$secret.<NAME>` (flow). A web
+         * destination holds no secret.
+         */
+        secrets?: Record<string, string>;
+        /**
+         * Destination config the package needs to deliver beyond its settings:
+         * `loadScript` for a web destination that loads its vendor script only
+         * when asked to.
+         */
+        config?: Pick<Config$5, 'loadScript'>;
+    }
+    /** The `$meta` of a package's walkerOS.json, as its build writes it. */
+    interface PackageMeta {
+        package: string;
+        version: string;
+        /** Step type: `source`, `transformer`, `destination` or `store`. */
+        type?: string;
+        platform?: string[];
+        renderer?: string;
+        /** Declared exports, export name to description. */
+        exports?: Record<string, string>;
+        docs?: string;
+        source?: string;
+    }
+    /** A package's quickstart, composed from its `$meta` and minimal example. */
+    interface Quickstart {
+        /** The install command. */
+        install: string;
+        /** TypeScript source that starts a flow with the package. */
+        integrated: string;
+        /** A complete flow with the package as its only step of its type. */
+        flow: Json;
+        /**
+         * What the conformance kit runs with: the settings (secrets as their
+         * placeholders) and the minimal example's config.
+         */
+        run: {
+            settings: Record<string, unknown>;
+            config?: Pick<Config$5, 'loadScript'>;
+        };
+    }
 }
 
 type AnyFunction$1<P extends unknown[] = never[], R = unknown> = (...args: P) => R;
@@ -3240,7 +3322,7 @@ interface Config$1<T extends TypesGeneric$1 = Types$1> extends Config$7<Mapping<
     async?: boolean | Record<string, boolean>;
     /** Mark as primary source; its push function becomes the exported `elb` from startFlow. */
     primary?: boolean;
-    /** Defer source initialization until these collector events fire (e.g., `['consent']`). */
+    /** Collector events (e.g., `['consent']`) that must fire before the source receives on() calls; init and event capture are not delayed. */
     require?: string[];
     /**
      * Provisioning options for `walkeros setup`. `boolean | object`.
@@ -4541,7 +4623,7 @@ declare function deepMerge<T extends Record<string, unknown>>(target: T, source:
  * Names `getEvent` knows: the standard events plus the generic default
  * `entity action`. Any other name does not compile.
  */
-type StandardEventName = 'entity action' | 'cart view' | 'checkout view' | 'order complete' | 'page view' | 'product add' | 'product view' | 'product visible' | 'promotion visible' | 'session start';
+type StandardEventName = 'entity action' | 'cart view' | 'checkout start' | 'order complete' | 'page view' | 'product add' | 'product view' | 'product visible' | 'promotion visible' | 'session start';
 /**
  * Creates a complete event with default values.
  * Used for testing and debugging.
@@ -5685,11 +5767,9 @@ interface ExampleSummary {
     name: string;
     description?: string;
 }
-interface WalkerOSPackageMeta {
+interface WalkerOSPackageMeta extends Pick<Flow.PackageMeta, 'version' | 'type'> {
     packageName: string;
-    version: string;
     description?: string;
-    type?: string;
     platform?: string | string[];
 }
 interface WalkerOSPackageInfo {
@@ -5727,6 +5807,11 @@ declare function fetchPackage(packageName: string, options?: {
     baseUrl?: string;
     client?: string;
 }): Promise<WalkerOSPackage>;
+/**
+ * The walkerOS metadata of a package, parsed from its walkerOS.json the same
+ * way for every source: a CDN release or a local package on disk.
+ */
+declare function parseWalkerOSJson(walkerOSJson: Record<string, unknown>): Omit<WalkerOSPackage, 'packageName' | 'version' | 'description'>;
 /**
  * @deprecated Use fetchPackage instead.
  * Still used by: entry.ts (validator), package-schemas.ts (MCP resource).
@@ -6626,4 +6711,4 @@ declare const REF_CODE_PREFIX = "$code:";
  */
 declare function scanFlowRefs(value: unknown, into?: Set<string>): Set<string>;
 
-export { type Acknowledgement, type ActivationGrant, type AssembleJourneysOptions, type BatchResponse, type BatchedPosterOptions, type BreakerState, type BuildFlag, CLOCK_SKEW_MS, CONTRACT_RULE_KEYS, cache as Cache, type CacheEnvelope, type CacheResult, type CauseKey, type CauseLog, type CauseLogOptions, type CauseLogger, type ChainContinuation, type ChainFrame, type ChainStep, type ClickIdEntry, collector as Collector, type CompiledCache, Const, context as Context, type Credential, DEFAULT_DESTINATION_TIMEOUT_MS, type Debounced, destination as Destination, type DestroyContext, type DestroyFn, type DroppedCounters, ENV_MARKER_PREFIX, EVENT_NOT_PROCESSED, elb as Elb, type EmitFn, type EventOutcome, type ExampleSummary, type FailureReason, FatalError, Flow, type FlowConfigResolver, FlowCycleError, FlowReferenceError, type FlowState, type FlowStateBatch, type FlowStatePhase, type FlowStepType, type GetStore, hint as Hint, hooks as Hooks, INTERNAL_SERVER_ERROR, type Ingest, type IngestEnvelope, type IngestMeta, InvalidEventError, type Journey, type JourneyAssembly, type JourneyBranch, type JourneyCorrelation, type JourneyEntry, type JourneyGap, type JourneyHop, type JourneyHopStatus, type JourneyPlatform, type JourneyStatus, type JourneyTopology, type JourneyTopologyNode, type JourneyUnattributed, type JsonSchema, Level, lifecycle as Lifecycle, type LifecycleContext, logger as Logger, MAPPING_NO_OPS, MAX_SESSION_MS, MOIN_PARAM, MOIN_PRODUCTION, mapping as Mapping, type MappingPosition, type MarketingParameters, matcher as Matcher, type MockLogger, type MoinTarget, type NextSteps, type NodeLikeRequest, OBSERVE_ENV_KEY, OBSERVE_STORAGE_KEY, type Observe, type ObserveCredential, type ObserveServer, type ObserveSlot, type ObserveWeb, type ObservedEnv, type ObserverFn, on as On, type ParsedGrant, type ParsedTraceparent, type PosterFetch, type PosterResponse, type PreviewCrypto, type PreviewFailure, type PreviewKey, type PreviewSubtle, type QueueReason, type QueuedReason, REF_CODE_PREFIX, REF_CONTRACT, REF_ENV, REF_FLOW, REF_FLOW_INLINE, REF_FLOW_NAME, REF_SECRET, REF_STORE, REF_VAR_FULL, REF_VAR_INLINE, RESERVED_WINDOW_GLOBALS, request as Request, type ResolveContractsOptions, type ResolveOptions, type RespondFn, type RespondOptions, type RouteContinuation, type RouteDecision, type RouteGraphNode, type RouteLabel, SECRET_MARKER_PREFIX, STEP_FIELD_ROLES, STEP_FUNCTION_KEYS, STEP_OPERATIVE_FIELDS, type ScheduleOptions, type SendDataValue, type SendHeaders, type SendResponse, type ServiceAccount, type SetupFn, simulation as Simulation, source as Source, type StandardEventName, type State, type StepEntryErrorCode, type StepEntryValidation, StepError, type StepErrorOptions, type StepField, type StepFieldRole, type StepFunctionKey, type StepKind, type StorageType, store as Store, type TelemetryLevel, type TelemetryOptions, type TelemetryOptionsSupplier, type Timer, transformer as Transformer, type TransformerMappingEntry, trigger as Trigger, URL_WINDOW_MS, type ValidateEvents, type VerifyParams, type VerifyResult, walkeros as WalkerOS, type WalkerOSPackage, type WalkerOSPackageInfo, type WalkerOSPackageMeta, type WindowCollectorCheck, acknowledge, advanceChain, anonymizeIP, applyState, applyUpdate, assembleJourneys, assign, batchResponse, branch, buildScopeFromNodeRequest, castToProperty, castValue, checkCache, checkWindowCollector, clone, compileCache, compileMatcher, compileState, createBatchedPoster, createCauseLog, createDestination, createEvent, createIngest, createLogger, createMappingRoot, createMockContext, createMockLogger, createRespond, createTelemetryObserver, createTimer, debounce, deepMerge, defaultClickIds, deleteByPath, deriveSpanId, emitStep, fetchPackage, fetchPackageSchema, filterValues, flattenIncludeSections, formatOut, getBrowser, getBrowserVersion, getByPath, getDeviceType, getErrorMessage, getEvent, getFlowSettings, getGrantedConsent, getHeaders, getId, getMappingEvent, getMappingKeyPaths, getMappingNoOpMessage, getMappingNoOpPaths, getMappingValue, getMarketingParameters, getNextSteps, getOS, getOSVersion, getPlatform, getRouteGraph, getSpanId, getStepFieldRole, getStepRuntimeProps, getTraceId, getTraceUntil, getTransformerMapping, getTransformerMappingWarnings, getUnknownStepKeys, isArguments, isArray, isBatchBody, isBoolean, isChainContinuation, isCommand, isDefined, isEnvObserve, isFunction, isNumber, isObject, isPathStepEntry, isPropertyType, isRouteArray, isRouteConfigEntry, isRouteContinuation, isSameType, isSampled, isScope, isStoreValue, isString, isThenable, mcpError, mcpResult, mergeContractSchemas, mergeMappingRule, mockEnv, networkErrorMessage, normalizeBody, normalizeHeaders, normalizeQuery, observeEnv, observeFromEnv, packageNameToVariable, parseCallPath, parseGrant, parseObserveCredential, parseTraceparent, parseUserAgent, processEventMapping, pushResultToOutcome, readCacheEnvelope, reportCause, requestToData, requestToParameter, resolveContracts, resolveDestinationTimeout, resolveSetup, resolveTelemetryOptions, scanFlowRefs, setByPath, setTraceUntil, startChain, stepCall, stepId, storeCache, throttle, throwError, toEventList, toFailureReason, transformData, traverseEnv, trim, tryCatch, tryCatchAsync, useHooks, validateStepEntry, verifyActivation, walkPath, wrapCacheEnvelope, wrapCondition, wrapFn, wrapValidate };
+export { type Acknowledgement, type ActivationGrant, type AssembleJourneysOptions, type BatchResponse, type BatchedPosterOptions, type BreakerState, type BuildFlag, CLOCK_SKEW_MS, CONTRACT_RULE_KEYS, cache as Cache, type CacheEnvelope, type CacheResult, type CauseKey, type CauseLog, type CauseLogOptions, type CauseLogger, type ChainContinuation, type ChainFrame, type ChainStep, type ClickIdEntry, collector as Collector, type CompiledCache, Const, context as Context, type Credential, DEFAULT_DESTINATION_TIMEOUT_MS, type Debounced, destination as Destination, type DestroyContext, type DestroyFn, type DroppedCounters, ENV_MARKER_PREFIX, EVENT_NOT_PROCESSED, elb as Elb, type EmitFn, type EventOutcome, type ExampleSummary, type FailureReason, FatalError, Flow, type FlowConfigResolver, FlowCycleError, FlowReferenceError, type FlowState, type FlowStateBatch, type FlowStatePhase, type FlowStepType, type GetStore, hint as Hint, hooks as Hooks, INTERNAL_SERVER_ERROR, type Ingest, type IngestEnvelope, type IngestMeta, InvalidEventError, type Journey, type JourneyAssembly, type JourneyBranch, type JourneyCorrelation, type JourneyEntry, type JourneyGap, type JourneyHop, type JourneyHopStatus, type JourneyPlatform, type JourneyStatus, type JourneyTopology, type JourneyTopologyNode, type JourneyUnattributed, type JsonSchema, Level, lifecycle as Lifecycle, type LifecycleContext, logger as Logger, MAPPING_NO_OPS, MAX_SESSION_MS, MOIN_PARAM, MOIN_PRODUCTION, mapping as Mapping, type MappingPosition, type MarketingParameters, matcher as Matcher, type MockLogger, type MoinTarget, type NextSteps, type NodeLikeRequest, OBSERVE_ENV_KEY, OBSERVE_STORAGE_KEY, type Observe, type ObserveCredential, type ObserveServer, type ObserveSlot, type ObserveWeb, type ObservedEnv, type ObserverFn, on as On, type ParsedGrant, type ParsedTraceparent, type PosterFetch, type PosterResponse, type PreviewCrypto, type PreviewFailure, type PreviewKey, type PreviewSubtle, type QueueReason, type QueuedReason, REF_CODE_PREFIX, REF_CONTRACT, REF_ENV, REF_FLOW, REF_FLOW_INLINE, REF_FLOW_NAME, REF_SECRET, REF_STORE, REF_VAR_FULL, REF_VAR_INLINE, RESERVED_WINDOW_GLOBALS, request as Request, type ResolveContractsOptions, type ResolveOptions, type RespondFn, type RespondOptions, type RouteContinuation, type RouteDecision, type RouteGraphNode, type RouteLabel, SECRET_MARKER_PREFIX, STEP_FIELD_ROLES, STEP_FUNCTION_KEYS, STEP_OPERATIVE_FIELDS, type ScheduleOptions, type SendDataValue, type SendHeaders, type SendResponse, type ServiceAccount, type SetupFn, simulation as Simulation, source as Source, type StandardEventName, type State, type StepEntryErrorCode, type StepEntryValidation, StepError, type StepErrorOptions, type StepField, type StepFieldRole, type StepFunctionKey, type StepKind, type StepType, type StorageType, store as Store, type TelemetryLevel, type TelemetryOptions, type TelemetryOptionsSupplier, type Timer, transformer as Transformer, type TransformerMappingEntry, trigger as Trigger, URL_WINDOW_MS, type ValidateEvents, type VerifyParams, type VerifyResult, walkeros as WalkerOS, type WalkerOSPackage, type WalkerOSPackageInfo, type WalkerOSPackageMeta, type WindowCollectorCheck, acknowledge, advanceChain, anonymizeIP, applyState, applyUpdate, assembleJourneys, assign, batchResponse, branch, buildScopeFromNodeRequest, castToProperty, castValue, checkCache, checkWindowCollector, clone, compileCache, compileMatcher, compileState, createBatchedPoster, createCauseLog, createDestination, createEvent, createIngest, createLogger, createMappingRoot, createMockContext, createMockLogger, createRespond, createTelemetryObserver, createTimer, debounce, deepMerge, defaultClickIds, deleteByPath, deriveSpanId, emitStep, fetchPackage, fetchPackageSchema, filterValues, flattenIncludeSections, formatOut, getBrowser, getBrowserVersion, getByPath, getDeviceType, getErrorMessage, getEvent, getFlowSettings, getGrantedConsent, getHeaders, getId, getMappingEvent, getMappingKeyPaths, getMappingNoOpMessage, getMappingNoOpPaths, getMappingValue, getMarketingParameters, getNextSteps, getOS, getOSVersion, getPlatform, getRouteGraph, getSpanId, getStepFieldRole, getStepRuntimeProps, getTraceId, getTraceUntil, getTransformerMapping, getTransformerMappingWarnings, getUnknownStepKeys, isArguments, isArray, isBatchBody, isBoolean, isChainContinuation, isCommand, isDefined, isEnvObserve, isFunction, isNumber, isObject, isPathStepEntry, isPropertyType, isRouteArray, isRouteConfigEntry, isRouteContinuation, isSameType, isSampled, isScope, isStoreValue, isString, isThenable, mcpError, mcpResult, mergeContractSchemas, mergeMappingRule, mockEnv, networkErrorMessage, normalizeBody, normalizeHeaders, normalizeQuery, observeEnv, observeFromEnv, packageNameToVariable, parseCallPath, parseGrant, parseObserveCredential, parseTraceparent, parseUserAgent, parseWalkerOSJson, processEventMapping, pushResultToOutcome, readCacheEnvelope, reportCause, requestToData, requestToParameter, resolveContracts, resolveDestinationTimeout, resolveSetup, resolveTelemetryOptions, scanFlowRefs, setByPath, setTraceUntil, startChain, stepCall, stepId, storeCache, throttle, throwError, toEventList, toFailureReason, transformData, traverseEnv, trim, tryCatch, tryCatchAsync, useHooks, validateStepEntry, verifyActivation, walkPath, wrapCacheEnvelope, wrapCondition, wrapFn, wrapValidate };