@walkeros/core 4.8.2 → 4.8.3-next-1793115089237

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,53 @@
1
1
  # @walkeros/core
2
2
 
3
+ ## 4.8.3-next-1793115089237
4
+
5
+ ### Patch Changes
6
+
7
+ - 34fd225: The mapping rule descriptions shown in property tables and
8
+ `package_get` now match the behaviour: a `condition` that returns false moves
9
+ on to the next rule, `batch` works only on a destination with `pushBatch`,
10
+ `extend` applies only in `@walkeros/transformer-ga4`'s `settings.mapping`, and
11
+ the `mappingKey` and batch `key` examples are `"product view"`.
12
+ - 5313635: A destination package can publish `examples.minimal` from
13
+ `src/examples/minimal.ts` (`MINIMAL_EXAMPLE_FILE`): the settings it needs to
14
+ deliver, credentials named as secrets. `composeQuickstart` from
15
+ `@walkeros/core/dev` turns it into the install line, the integrated code and a
16
+ complete flow reading each credential as `$secret`, and throws when they
17
+ cannot be built. `packageMetaOf` writes a package's `$meta`, a single platform
18
+ as a list.
19
+ - 5313635: Schema descriptions now match the behaviour: `setup` on destinations,
20
+ stores and flow steps runs only through `walkeros setup`; an event cache's
21
+ `stop` defaults to true on sources, and `update` changes only a source's
22
+ response, on HIT and MISS. They appear in the flow JSON Schema and in MCP.
23
+ - 5313635: The source config descriptions of `require`, `setup` and `ingest` now
24
+ match the behaviour: `require` delays only `on()` calls, not init or event
25
+ capture; `setup` runs only through `walkeros setup`; `ingest` resolves against
26
+ the normalized request scope of server sources.
27
+ - 5313635: `@walkeros/core/dev` exports `toSerializable`, which turns a value
28
+ into what `walkerOS.json` publishes: functions become `{ $code }` objects with
29
+ their source text, Zod schemas are left out, and everything else is copied.
30
+ The package build and the step example runner both use it, so tests run what
31
+ is published.
32
+ - 5313635: The sample events from `getEvent` now use the standard event names:
33
+ `checkout start` replaces `checkout view`, an order carries `tax` and `total`,
34
+ a promotion names its placement `slot`, and product events carry `currency`.
35
+ Order `value` is now the merchandise value: the `order complete` sample goes
36
+ from 555 to 462, and the gross amount charged is `total` (467.22). The
37
+ destination examples read `data.tax`, `data.slot` and the search keys
38
+ `data.term` and `data.results`, and gross fields such as Matomo `grandTotal`
39
+ read `data.total` first, then `data.value`. The CLI ships default event
40
+ contracts for common site types in `examples/contracts/`.
41
+ - 34fd225: The `PushResult.error` description now says when it is set: for a
42
+ rejected event or a failure before the destinations. A destination's failure
43
+ is reported in `failed`, under its id with a `reason`, and leaves `error`
44
+ unset.
45
+ - 5313635: `@walkeros/core` exports the `StepType` type, the kind of a step
46
+ package (`source`, `transformer`, `destination` or `store`), read from
47
+ `STEP_TYPES` on `@walkeros/core/dev`. `StepKind`, `FlowStepType` and `stepId`
48
+ use it, as do the step kinds `resolveExportName` in `@walkeros/cli` and the
49
+ simulate tool of `@walkeros/mcp` take, so the kinds are listed in one place.
50
+
3
51
  ## 4.8.2
4
52
 
5
53
  ### Patch Changes
@@ -758,9 +806,6 @@
758
806
  and `event.context` remain required.
759
807
  - Each source self-registers via TypeScript module augmentation of `SourceMap`
760
808
  in `@walkeros/core`.
761
- - App-side coordination (`/workspaces/developer/app`) is a follow-up plan, not
762
- part of this release. Telemetry from v4 CLI/MCP will not validate against
763
- the existing app schema until that follow-up ships.
764
809
  - `Mapping.Rule.skip` is renamed to `Mapping.Rule.silent`. Customer flow.json
765
810
  configs using `skip: true` in mapping rules must rename to `silent: true`.
766
811
  Hard cut: no legacy alias, the field is gone.
package/dist/dev.d.mts CHANGED
@@ -7695,7 +7695,7 @@ declare namespace utilities {
7695
7695
  * - match: MatchExpression — omit for always-match.
7696
7696
  * - key: array of dot-path strings used to compose the cache key from event fields.
7697
7697
  * - ttl: time-to-live in seconds (positive).
7698
- * - update: optional record of response mutations applied on cache hit.
7698
+ * - update: optional record of source response mutations, applied on HIT and MISS.
7699
7699
  */
7700
7700
  declare const EventCacheRuleSchema: z.ZodObject<{
7701
7701
  match: z.ZodOptional<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
@@ -8593,7 +8593,7 @@ interface ObserveSlot {
8593
8593
  * for inEvent/outEvent).
8594
8594
  */
8595
8595
  type FlowStatePhase = 'init' | 'in' | 'out' | 'error' | 'skip' | 'flush';
8596
- type FlowStepType = 'source' | 'transformer' | 'collector' | 'destination' | 'store';
8596
+ type FlowStepType = StepKind;
8597
8597
  interface FlowStateBatch {
8598
8598
  size: number;
8599
8599
  index: number;
@@ -8697,6 +8697,32 @@ interface CauseLog {
8697
8697
  size(): number;
8698
8698
  }
8699
8699
 
8700
+ /**
8701
+ * The types of a step package (`walkerOS.type` in its package.json). A step
8702
+ * package publishes an exports list, empty when it declares none, and a
8703
+ * settings schema; the build checks both.
8704
+ */
8705
+ declare const STEP_TYPES: readonly ["source", "transformer", "destination", "store"];
8706
+ /**
8707
+ * Where a destination package keeps its minimal example, relative to `src`
8708
+ * (per export: `src/<export>/examples/minimal.ts`). A package with the file
8709
+ * renders a quickstart on its docs page; its conformance test runs it.
8710
+ */
8711
+ declare const MINIMAL_EXAMPLE_FILE = "examples/minimal.ts";
8712
+ /**
8713
+ * The `$meta` a package publishes in its walkerOS.json, from its
8714
+ * package.json: its name and version, the `walkerOS` block (type, platform
8715
+ * as a list, renderer, exports, docs) and the source URL its repository
8716
+ * directory gives. A step package without declared exports publishes an
8717
+ * empty list, so a reader can tell it from an older package that published
8718
+ * none. The build writes it; the conformance kit composes from it.
8719
+ */
8720
+ declare function packageMetaOf(packageJson: unknown): Flow.PackageMeta;
8721
+
8722
+ /** The kind of a step package: one of `STEP_TYPES`. */
8723
+ type StepType = (typeof STEP_TYPES)[number];
8724
+ /** Identifies which kind of step a stepId belongs to. */
8725
+ type StepKind = 'collector' | StepType;
8700
8726
  /**
8701
8727
  * Drop counters at a single step. Each buffer is optional: a step kind
8702
8728
  * may have only `queue` (collector), only `dlq`, both (destinations
@@ -9573,7 +9599,11 @@ interface PushResult {
9573
9599
  dropped?: boolean;
9574
9600
  /** Event was rejected as invalid input: a client/producer fault, not a pipeline failure. */
9575
9601
  invalid?: boolean;
9576
- /** Human-readable failure reason when ok is false. */
9602
+ /**
9603
+ * Human-readable message when the event was rejected or a step before the
9604
+ * destinations failed. A destination's own failure is in `failed`, under
9605
+ * its id with a `reason`, and leaves this unset.
9606
+ */
9577
9607
  error?: string;
9578
9608
  /**
9579
9609
  * Why the push failed when `ok` is false without a `failed` entry: a full
@@ -10098,7 +10128,7 @@ interface Config$1<T extends TypesGeneric$1 = Types$1> extends Config$7<Mapping<
10098
10128
  async?: boolean | Record<string, boolean>;
10099
10129
  /** Mark as primary source; its push function becomes the exported `elb` from startFlow. */
10100
10130
  primary?: boolean;
10101
- /** Defer source initialization until these collector events fire (e.g., `['consent']`). */
10131
+ /** Collector events (e.g., `['consent']`) that must fire before the source receives on() calls; init and event capture are not delayed. */
10102
10132
  require?: string[];
10103
10133
  /**
10104
10134
  * Provisioning options for `walkeros setup`. `boolean | object`.
@@ -10914,7 +10944,8 @@ declare namespace Flow {
10914
10944
  * Name of the transformer to execute after this source captures an event.
10915
10945
  * Creates a pre-collector transformer chain. Chain ends at the collector.
10916
10946
  * If omitted, events route directly to the collector.
10917
- * Can be an array for explicit chain control (bypasses transformer.next resolution).
10947
+ * Can be an array: its members run in order, and each member's own `next`
10948
+ * runs right after that member.
10918
10949
  */
10919
10950
  next?: Route;
10920
10951
  /** Cache configuration for this source. */
@@ -11224,12 +11255,15 @@ declare namespace Flow {
11224
11255
  interface StepPageSession {
11225
11256
  /** Page globals merged over an examples env's `push` (the document). */
11226
11257
  globals: Record<string, unknown>;
11227
- /** Scripts added since `open`, with and without the loadVendor marker. */
11258
+ /**
11259
+ * Scripts added since `open`, with and without the loadVendor marker.
11260
+ * A marked script loads (`load`, once) unless `failScripts` fails it.
11261
+ */
11228
11262
  scripts(): {
11229
11263
  marked: number;
11230
11264
  unmarked: number;
11231
11265
  };
11232
- /** Fire `error` on every marked script (kit item 2, vendor-global). */
11266
+ /** Fire `error` on every marked script, loaded or not (kit item 2, vendor-global). */
11233
11267
  failScripts(): void;
11234
11268
  /** Restore the stubs and remove the scripts added since `open`. */
11235
11269
  close(): void;
@@ -11251,7 +11285,10 @@ declare namespace Flow {
11251
11285
  * Whether this example is meant for public consumption (docs, UI, MCP default output).
11252
11286
  * Defaults to `true`. Set to `false` for test-only fixtures that should stay out of
11253
11287
  * user-facing surfaces but still run in test suites and remain available to
11254
- * `flow_simulate` / CLI `--simulate`.
11288
+ * `flow_simulate` / CLI `--simulate`. A failure example (`public: false`
11289
+ * with an `outcome`) is still listed on the docs page under "When it
11290
+ * fails", by its title, description and outcome; its fixture `in` is
11291
+ * never shown.
11255
11292
  */
11256
11293
  public?: boolean;
11257
11294
  in?: unknown;
@@ -11273,7 +11310,10 @@ declare namespace Flow {
11273
11310
  /**
11274
11311
  * The reported outcome of a failure or queue example (`public: false`):
11275
11312
  * the step's status in the push result and its reason code. Absent means
11276
- * the step must not fail.
11313
+ * the step must not fail. The docs page lists every example with an
11314
+ * outcome under "When it fails" by title, description and outcome, so it
11315
+ * needs a reader-facing `description` (the docs build fails without one);
11316
+ * its fixture `in` is never shown.
11277
11317
  */
11278
11318
  outcome?: StepOutcome;
11279
11319
  /** What the boundary answers for this example (a failure fixture). */
@@ -11296,6 +11336,64 @@ declare namespace Flow {
11296
11336
  }
11297
11337
  /** Named step examples keyed by scenario name. */
11298
11338
  type StepExamples = Record<string, StepExample>;
11339
+ /**
11340
+ * The settings a package needs to deliver, published as `examples.minimal`
11341
+ * (for a package with several exports, as `exportExamples.<export>.minimal`).
11342
+ * `composeQuickstart` turns it into the install line, the integrated code
11343
+ * and a complete flow; the conformance kit runs it.
11344
+ */
11345
+ interface MinimalExample {
11346
+ /**
11347
+ * Only the settings the schema requires, plus any that `init` refuses to
11348
+ * start without under `config`. A secret holds a placeholder value that
11349
+ * satisfies the schema; generated code never shows it.
11350
+ */
11351
+ settings: Record<string, unknown>;
11352
+ /**
11353
+ * Server destinations: settings keys that hold credentials, mapped to the
11354
+ * secret name the reader sets (`A-Z`, `0-9` and `_`), for example
11355
+ * `{ accessToken: 'META_ACCESS_TOKEN' }`. Generated code reads them as
11356
+ * `process.env.<NAME>` (integrated) and `$secret.<NAME>` (flow). A web
11357
+ * destination holds no secret.
11358
+ */
11359
+ secrets?: Record<string, string>;
11360
+ /**
11361
+ * Destination config the package needs to deliver beyond its settings:
11362
+ * `loadScript` for a web destination that loads its vendor script only
11363
+ * when asked to.
11364
+ */
11365
+ config?: Pick<Config$5, 'loadScript'>;
11366
+ }
11367
+ /** The `$meta` of a package's walkerOS.json, as its build writes it. */
11368
+ interface PackageMeta {
11369
+ package: string;
11370
+ version: string;
11371
+ /** Step type: `source`, `transformer`, `destination` or `store`. */
11372
+ type?: string;
11373
+ platform?: string[];
11374
+ renderer?: string;
11375
+ /** Declared exports, export name to description. */
11376
+ exports?: Record<string, string>;
11377
+ docs?: string;
11378
+ source?: string;
11379
+ }
11380
+ /** A package's quickstart, composed from its `$meta` and minimal example. */
11381
+ interface Quickstart {
11382
+ /** The install command. */
11383
+ install: string;
11384
+ /** TypeScript source that starts a flow with the package. */
11385
+ integrated: string;
11386
+ /** A complete flow with the package as its only step of its type. */
11387
+ flow: Json;
11388
+ /**
11389
+ * What the conformance kit runs with: the settings (secrets as their
11390
+ * placeholders) and the minimal example's config.
11391
+ */
11392
+ run: {
11393
+ settings: Record<string, unknown>;
11394
+ config?: Pick<Config$5, 'loadScript'>;
11395
+ };
11396
+ }
11299
11397
  }
11300
11398
 
11301
11399
  type StepOut = Flow.StepOut;
@@ -11315,6 +11413,28 @@ type StepOut = Flow.StepOut;
11315
11413
  */
11316
11414
  declare function formatOut(out: StepOut): string;
11317
11415
 
11416
+ /**
11417
+ * Deep-clone a value for JSON serialization, as dist/walkerOS.json publishes
11418
+ * it. The one definition: the build writes walkerOS.json with it, and the
11419
+ * step-example runner of @walkeros/collector/dev runs examples through it.
11420
+ *
11421
+ * Conventions:
11422
+ * - Functions → { $code: fn.toString() }, the function's source text
11423
+ * - Zod instances → filtered out (returns undefined)
11424
+ * - Everything else → recursively passed through
11425
+ */
11426
+ declare function toSerializable(value: unknown): unknown;
11427
+
11428
+ /**
11429
+ * Compose a destination package's quickstart from its `$meta` and its
11430
+ * minimal example: the install line, the integrated code, a complete v4 flow
11431
+ * and the settings the conformance kit runs with. A package with several
11432
+ * exports names the export the minimal example belongs to. Throws when the
11433
+ * inputs do not resolve to one runnable setup, so a docs build that renders
11434
+ * it fails instead of showing a broken snippet.
11435
+ */
11436
+ declare function composeQuickstart(meta: Flow.PackageMeta, minimal: Flow.MinimalExample, exportName?: string): Flow.Quickstart;
11437
+
11318
11438
  /**
11319
11439
  * Test helper for a step package's dev examples env: every declared
11320
11440
  * `simulation` path must resolve against the package's own `push` mock env,
@@ -11467,4 +11587,4 @@ declare function validateComponentNames(components: Record<string, unknown>, sec
11467
11587
  */
11468
11588
  declare function validateStoreReferences(flowSettings: Flow, storeIds: Set<string>): void;
11469
11589
 
11470
- export { ClickIdEntrySchema, Flow, type JSONSchema, type ValidateResult, type ValidateResultType, type ValidationError, type ValidationType, type ValidationWarning, checkStepKeys, expectSimulationResolves, formatOut, mergeConfigSchema, resolveBaseSchema, routeCases$1 as routeCases, index as schemas, validateComponentNames, validateFlowStructure, validateReference, validateStoreReferences, zodToSchema };
11590
+ export { ClickIdEntrySchema, Flow, type JSONSchema, MINIMAL_EXAMPLE_FILE, STEP_TYPES, type ValidateResult, type ValidateResultType, type ValidationError, type ValidationType, type ValidationWarning, checkStepKeys, composeQuickstart, expectSimulationResolves, formatOut, mergeConfigSchema, packageMetaOf, resolveBaseSchema, routeCases$1 as routeCases, index as schemas, toSerializable, validateComponentNames, validateFlowStructure, validateReference, validateStoreReferences, zodToSchema };
package/dist/dev.d.ts CHANGED
@@ -7695,7 +7695,7 @@ declare namespace utilities {
7695
7695
  * - match: MatchExpression — omit for always-match.
7696
7696
  * - key: array of dot-path strings used to compose the cache key from event fields.
7697
7697
  * - ttl: time-to-live in seconds (positive).
7698
- * - update: optional record of response mutations applied on cache hit.
7698
+ * - update: optional record of source response mutations, applied on HIT and MISS.
7699
7699
  */
7700
7700
  declare const EventCacheRuleSchema: z.ZodObject<{
7701
7701
  match: z.ZodOptional<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
@@ -8593,7 +8593,7 @@ interface ObserveSlot {
8593
8593
  * for inEvent/outEvent).
8594
8594
  */
8595
8595
  type FlowStatePhase = 'init' | 'in' | 'out' | 'error' | 'skip' | 'flush';
8596
- type FlowStepType = 'source' | 'transformer' | 'collector' | 'destination' | 'store';
8596
+ type FlowStepType = StepKind;
8597
8597
  interface FlowStateBatch {
8598
8598
  size: number;
8599
8599
  index: number;
@@ -8697,6 +8697,32 @@ interface CauseLog {
8697
8697
  size(): number;
8698
8698
  }
8699
8699
 
8700
+ /**
8701
+ * The types of a step package (`walkerOS.type` in its package.json). A step
8702
+ * package publishes an exports list, empty when it declares none, and a
8703
+ * settings schema; the build checks both.
8704
+ */
8705
+ declare const STEP_TYPES: readonly ["source", "transformer", "destination", "store"];
8706
+ /**
8707
+ * Where a destination package keeps its minimal example, relative to `src`
8708
+ * (per export: `src/<export>/examples/minimal.ts`). A package with the file
8709
+ * renders a quickstart on its docs page; its conformance test runs it.
8710
+ */
8711
+ declare const MINIMAL_EXAMPLE_FILE = "examples/minimal.ts";
8712
+ /**
8713
+ * The `$meta` a package publishes in its walkerOS.json, from its
8714
+ * package.json: its name and version, the `walkerOS` block (type, platform
8715
+ * as a list, renderer, exports, docs) and the source URL its repository
8716
+ * directory gives. A step package without declared exports publishes an
8717
+ * empty list, so a reader can tell it from an older package that published
8718
+ * none. The build writes it; the conformance kit composes from it.
8719
+ */
8720
+ declare function packageMetaOf(packageJson: unknown): Flow.PackageMeta;
8721
+
8722
+ /** The kind of a step package: one of `STEP_TYPES`. */
8723
+ type StepType = (typeof STEP_TYPES)[number];
8724
+ /** Identifies which kind of step a stepId belongs to. */
8725
+ type StepKind = 'collector' | StepType;
8700
8726
  /**
8701
8727
  * Drop counters at a single step. Each buffer is optional: a step kind
8702
8728
  * may have only `queue` (collector), only `dlq`, both (destinations
@@ -9573,7 +9599,11 @@ interface PushResult {
9573
9599
  dropped?: boolean;
9574
9600
  /** Event was rejected as invalid input: a client/producer fault, not a pipeline failure. */
9575
9601
  invalid?: boolean;
9576
- /** Human-readable failure reason when ok is false. */
9602
+ /**
9603
+ * Human-readable message when the event was rejected or a step before the
9604
+ * destinations failed. A destination's own failure is in `failed`, under
9605
+ * its id with a `reason`, and leaves this unset.
9606
+ */
9577
9607
  error?: string;
9578
9608
  /**
9579
9609
  * Why the push failed when `ok` is false without a `failed` entry: a full
@@ -10098,7 +10128,7 @@ interface Config$1<T extends TypesGeneric$1 = Types$1> extends Config$7<Mapping<
10098
10128
  async?: boolean | Record<string, boolean>;
10099
10129
  /** Mark as primary source; its push function becomes the exported `elb` from startFlow. */
10100
10130
  primary?: boolean;
10101
- /** Defer source initialization until these collector events fire (e.g., `['consent']`). */
10131
+ /** Collector events (e.g., `['consent']`) that must fire before the source receives on() calls; init and event capture are not delayed. */
10102
10132
  require?: string[];
10103
10133
  /**
10104
10134
  * Provisioning options for `walkeros setup`. `boolean | object`.
@@ -10914,7 +10944,8 @@ declare namespace Flow {
10914
10944
  * Name of the transformer to execute after this source captures an event.
10915
10945
  * Creates a pre-collector transformer chain. Chain ends at the collector.
10916
10946
  * If omitted, events route directly to the collector.
10917
- * Can be an array for explicit chain control (bypasses transformer.next resolution).
10947
+ * Can be an array: its members run in order, and each member's own `next`
10948
+ * runs right after that member.
10918
10949
  */
10919
10950
  next?: Route;
10920
10951
  /** Cache configuration for this source. */
@@ -11224,12 +11255,15 @@ declare namespace Flow {
11224
11255
  interface StepPageSession {
11225
11256
  /** Page globals merged over an examples env's `push` (the document). */
11226
11257
  globals: Record<string, unknown>;
11227
- /** Scripts added since `open`, with and without the loadVendor marker. */
11258
+ /**
11259
+ * Scripts added since `open`, with and without the loadVendor marker.
11260
+ * A marked script loads (`load`, once) unless `failScripts` fails it.
11261
+ */
11228
11262
  scripts(): {
11229
11263
  marked: number;
11230
11264
  unmarked: number;
11231
11265
  };
11232
- /** Fire `error` on every marked script (kit item 2, vendor-global). */
11266
+ /** Fire `error` on every marked script, loaded or not (kit item 2, vendor-global). */
11233
11267
  failScripts(): void;
11234
11268
  /** Restore the stubs and remove the scripts added since `open`. */
11235
11269
  close(): void;
@@ -11251,7 +11285,10 @@ declare namespace Flow {
11251
11285
  * Whether this example is meant for public consumption (docs, UI, MCP default output).
11252
11286
  * Defaults to `true`. Set to `false` for test-only fixtures that should stay out of
11253
11287
  * user-facing surfaces but still run in test suites and remain available to
11254
- * `flow_simulate` / CLI `--simulate`.
11288
+ * `flow_simulate` / CLI `--simulate`. A failure example (`public: false`
11289
+ * with an `outcome`) is still listed on the docs page under "When it
11290
+ * fails", by its title, description and outcome; its fixture `in` is
11291
+ * never shown.
11255
11292
  */
11256
11293
  public?: boolean;
11257
11294
  in?: unknown;
@@ -11273,7 +11310,10 @@ declare namespace Flow {
11273
11310
  /**
11274
11311
  * The reported outcome of a failure or queue example (`public: false`):
11275
11312
  * the step's status in the push result and its reason code. Absent means
11276
- * the step must not fail.
11313
+ * the step must not fail. The docs page lists every example with an
11314
+ * outcome under "When it fails" by title, description and outcome, so it
11315
+ * needs a reader-facing `description` (the docs build fails without one);
11316
+ * its fixture `in` is never shown.
11277
11317
  */
11278
11318
  outcome?: StepOutcome;
11279
11319
  /** What the boundary answers for this example (a failure fixture). */
@@ -11296,6 +11336,64 @@ declare namespace Flow {
11296
11336
  }
11297
11337
  /** Named step examples keyed by scenario name. */
11298
11338
  type StepExamples = Record<string, StepExample>;
11339
+ /**
11340
+ * The settings a package needs to deliver, published as `examples.minimal`
11341
+ * (for a package with several exports, as `exportExamples.<export>.minimal`).
11342
+ * `composeQuickstart` turns it into the install line, the integrated code
11343
+ * and a complete flow; the conformance kit runs it.
11344
+ */
11345
+ interface MinimalExample {
11346
+ /**
11347
+ * Only the settings the schema requires, plus any that `init` refuses to
11348
+ * start without under `config`. A secret holds a placeholder value that
11349
+ * satisfies the schema; generated code never shows it.
11350
+ */
11351
+ settings: Record<string, unknown>;
11352
+ /**
11353
+ * Server destinations: settings keys that hold credentials, mapped to the
11354
+ * secret name the reader sets (`A-Z`, `0-9` and `_`), for example
11355
+ * `{ accessToken: 'META_ACCESS_TOKEN' }`. Generated code reads them as
11356
+ * `process.env.<NAME>` (integrated) and `$secret.<NAME>` (flow). A web
11357
+ * destination holds no secret.
11358
+ */
11359
+ secrets?: Record<string, string>;
11360
+ /**
11361
+ * Destination config the package needs to deliver beyond its settings:
11362
+ * `loadScript` for a web destination that loads its vendor script only
11363
+ * when asked to.
11364
+ */
11365
+ config?: Pick<Config$5, 'loadScript'>;
11366
+ }
11367
+ /** The `$meta` of a package's walkerOS.json, as its build writes it. */
11368
+ interface PackageMeta {
11369
+ package: string;
11370
+ version: string;
11371
+ /** Step type: `source`, `transformer`, `destination` or `store`. */
11372
+ type?: string;
11373
+ platform?: string[];
11374
+ renderer?: string;
11375
+ /** Declared exports, export name to description. */
11376
+ exports?: Record<string, string>;
11377
+ docs?: string;
11378
+ source?: string;
11379
+ }
11380
+ /** A package's quickstart, composed from its `$meta` and minimal example. */
11381
+ interface Quickstart {
11382
+ /** The install command. */
11383
+ install: string;
11384
+ /** TypeScript source that starts a flow with the package. */
11385
+ integrated: string;
11386
+ /** A complete flow with the package as its only step of its type. */
11387
+ flow: Json;
11388
+ /**
11389
+ * What the conformance kit runs with: the settings (secrets as their
11390
+ * placeholders) and the minimal example's config.
11391
+ */
11392
+ run: {
11393
+ settings: Record<string, unknown>;
11394
+ config?: Pick<Config$5, 'loadScript'>;
11395
+ };
11396
+ }
11299
11397
  }
11300
11398
 
11301
11399
  type StepOut = Flow.StepOut;
@@ -11315,6 +11413,28 @@ type StepOut = Flow.StepOut;
11315
11413
  */
11316
11414
  declare function formatOut(out: StepOut): string;
11317
11415
 
11416
+ /**
11417
+ * Deep-clone a value for JSON serialization, as dist/walkerOS.json publishes
11418
+ * it. The one definition: the build writes walkerOS.json with it, and the
11419
+ * step-example runner of @walkeros/collector/dev runs examples through it.
11420
+ *
11421
+ * Conventions:
11422
+ * - Functions → { $code: fn.toString() }, the function's source text
11423
+ * - Zod instances → filtered out (returns undefined)
11424
+ * - Everything else → recursively passed through
11425
+ */
11426
+ declare function toSerializable(value: unknown): unknown;
11427
+
11428
+ /**
11429
+ * Compose a destination package's quickstart from its `$meta` and its
11430
+ * minimal example: the install line, the integrated code, a complete v4 flow
11431
+ * and the settings the conformance kit runs with. A package with several
11432
+ * exports names the export the minimal example belongs to. Throws when the
11433
+ * inputs do not resolve to one runnable setup, so a docs build that renders
11434
+ * it fails instead of showing a broken snippet.
11435
+ */
11436
+ declare function composeQuickstart(meta: Flow.PackageMeta, minimal: Flow.MinimalExample, exportName?: string): Flow.Quickstart;
11437
+
11318
11438
  /**
11319
11439
  * Test helper for a step package's dev examples env: every declared
11320
11440
  * `simulation` path must resolve against the package's own `push` mock env,
@@ -11467,4 +11587,4 @@ declare function validateComponentNames(components: Record<string, unknown>, sec
11467
11587
  */
11468
11588
  declare function validateStoreReferences(flowSettings: Flow, storeIds: Set<string>): void;
11469
11589
 
11470
- export { ClickIdEntrySchema, Flow, type JSONSchema, type ValidateResult, type ValidateResultType, type ValidationError, type ValidationType, type ValidationWarning, checkStepKeys, expectSimulationResolves, formatOut, mergeConfigSchema, resolveBaseSchema, routeCases$1 as routeCases, index as schemas, validateComponentNames, validateFlowStructure, validateReference, validateStoreReferences, zodToSchema };
11590
+ export { ClickIdEntrySchema, Flow, type JSONSchema, MINIMAL_EXAMPLE_FILE, STEP_TYPES, type ValidateResult, type ValidateResultType, type ValidationError, type ValidationType, type ValidationWarning, checkStepKeys, composeQuickstart, expectSimulationResolves, formatOut, mergeConfigSchema, packageMetaOf, resolveBaseSchema, routeCases$1 as routeCases, index as schemas, toSerializable, validateComponentNames, validateFlowStructure, validateReference, validateStoreReferences, zodToSchema };