@cowliss/cli 0.1.0

package/dist/guest/journeys-CxuS-mHn.js

@@ -0,0 +1,571 @@
+import { z } from "zod";
+
+//#region ../../packages/shared/src/constants.ts
+/** The public docs site, for the mail and the pages that point people at it. */
+const DOCS_URL = "https://docs.cowliss.com";
+/**
+* Clerk ID prefix marking an organization-scoped subject. Ingestion API keys
+* must resolve to an org subject; user-scoped keys are rejected.
+*/
+const CLERK_ORG_SUBJECT_PREFIX = "org_";
+/**
+* The two fixed environments every org has (spec: Environments). An app
+* belongs to one, so the environment of every write is the app's;
+* profiles, identifiers, events, memberships, journey instances,
+* deliveries, violations, quarantine, the address ledger, and idempotency
+* keys are per environment, while the catalog, sending domains, the
+* suppression mirror, billing, and journey code are shared. A third
+* environment is a one-line change here plus the mirrored db enum.
+*/
+const ENVIRONMENTS = ["development", "production"];
+/**
+* Fixed consent purposes for the prototype. Consent is a per-purpose map on
+* the profile, checked at send-step execution time.
+*
+* The two names describe what the recipient agreed to, not the pipe it
+* arrives on: "emails I did not ask for individually" and "my data leaving
+* for somewhere else". Naming them after the channel (`email`, `webhook`)
+* said nothing a recipient could consent to, and transactional mail already
+* bypasses the email purpose, so it was only ever marketing consent.
+*/
+const CONSENT_PURPOSES = ["emailMarketing", "dataProcessing"];
+/**
+* The two classes of send, declared on the template rather than passed per
+* call so the class cannot drift between two sends of the same message.
+*
+* Marketing is everything a journey sends on the org's behalf: it carries
+* the RFC 8058 unsubscribe headers and runs the full gate list.
+* Transactional is the developer's own operational mail (a receipt, an
+* export-is-ready notice): it carries neither header and skips consent and
+* the per-user frequency cap, because an unsubscribe link on an invoice is
+* wrong and a receipt must not silently vanish for anyone who once left a
+* newsletter. Suppression, the quota, the sending pause, and the from-domain
+* check still apply to both: those bound cost and protect the shared SES
+* account, and none of them are about what the recipient asked for.
+*/
+const SEND_CLASSES = ["marketing", "transactional"];
+/** Per execution: capability calls, journal size, and captured `api.log` lines. */
+const EXECUTION_LIMITS = {
+	calls: 1e3,
+	journalBytes: 1048576,
+	logLines: 100,
+	logLineBytes: 1024
+};
+/** Per release: manifest counts, bundle size, and the source tarball. */
+const RELEASE_LIMITS = {
+	journeys: 100,
+	templates: 200,
+	bundleBytes: 2097152,
+	sourceBytes: 5242880
+};
+/**
+* Where the docs site serves the `cow.json` JSON Schema (the `$schema` a
+* project file points at). Generated from `cowConfigSchema` by the docs
+* generator; the path is stable because project files link to it.
+*/
+const COW_CONFIG_SCHEMA_PATH = "/schemas/cow.json";
+const COW_CONFIG_SCHEMA_URL = `${DOCS_URL}${COW_CONFIG_SCHEMA_PATH}`;
+
+//#endregion
+//#region ../../packages/shared/src/journeys-v2/config.ts
+/**
+* `cow.json` (spec: Project layout): the org id and nothing more. The
+* folder name is the project's local name, the environment is always a
+* flag, and auth never lives in the project. Strict, so a typo'd key is a
+* build error rather than a silently ignored setting.
+*/
+const cowConfigSchema = z.strictObject({
+	$schema: z.url().optional(),
+	orgId: z.string().startsWith(CLERK_ORG_SUBJECT_PREFIX, "orgId must be a Clerk org id"),
+	/** Overrides the API the CLI talks to; the hosted product needs none. */
+	apiUrl: z.url().optional()
+}).meta({
+	title: "cow.json",
+	description: "A cow project: the organization it deploys to."
+});
+
+//#endregion
+//#region ../../packages/shared/src/environments.ts
+/**
+* The environment on the wire: the source's `environment` field, the
+* `X-Cow-Environment` header admin calls select with, and the
+* `environment` column every per-environment DTO carries.
+*/
+const environmentSchema = z.enum(ENVIRONMENTS);
+/**
+* The environments a shared definition (a segment, a journey) declares it
+* works on: a non-empty list of distinct values. A definition declaring none
+* would be dead code with a row behind it, and a repeated value is a typo
+* rather than an intent, which is the rule `defineJourney` applies too.
+*/
+const environmentsSchema = z.array(environmentSchema).min(1, "at least one environment is required").refine((values) => new Set(values).size === values.length, { message: "environments must not repeat" });
+
+//#endregion
+//#region ../../packages/shared/src/journeys-v2/manifest.ts
+/**
+* The release manifest (spec: Build; Push and compile): what `cow build`
+* extracts from a project and `cow push` uploads with the bundles. The
+* server validates it with these schemas, compiles every bundle, and stores
+* the compiled form on the release row.
+*/
+/**
+* A journey or template key: the file basename under `journeys/` or
+* `emails/`, kebab-case and unique across the project. Becomes part of the
+* Temporal workflow id and travels in the journey chain, so it stays short.
+*/
+const JOURNEY_KEY_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const journeyKeySchema = z.string().max(64).regex(JOURNEY_KEY_PATTERN, "key must be kebab-case (a-z, 0-9, hyphens)");
+/**
+* An author's labels on a journey or a template: how the dashboard groups
+* and filters them, and the only grouping there is. Case is kept as
+* written, each entry is trimmed and non-empty, the list is deduplicated,
+* and both ceilings are low on purpose: tags are a handful of words, not a
+* taxonomy. Absent means `[]`.
+*
+* The count is capped on the list as written, before the deduplication, so
+* a 21st entry is an error even when it is a repeat: that keeps `maxItems`
+* in the generated JSON Schema, and an author who wrote 21 tags wants to
+* hear about it.
+*/
+const tagsSchema = z.array(z.string().trim().min(1).max(50, "a tag must be at most 50 characters")).max(20, "a journey or template takes at most 20 tags").default([]).transform((tags) => [...new Set(tags)]);
+/**
+* A matcher field: one pattern or a non-empty list of them, a list being a
+* disjunction. See `matchesPattern` in ../patterns for the dialect (`*`
+* only) and for why a pattern whose literal prefix is not `system.` never
+* reaches a system event.
+*/
+const onePatternSchema = z.string().min(1).max(200, "a pattern must be at most 200 characters");
+const patternSchema = z.union([onePatternSchema, z.array(onePatternSchema).min(1).max(20, "a matcher takes at most 20 patterns")]);
+/**
+* What starts a journey: an event (optionally narrowed to an app id or a
+* list of them) or a segment entry. The registry DTO in `../journeys`
+* reuses it.
+*
+* Both members are strict, so a journey holding the retired `source` key
+* fails to compile a release instead of silently triggering on every app.
+* There is deliberately no pipe filter: a trigger narrows by the app the
+* write is attributed to, the same token a segment definition names.
+*/
+const triggerSchema = z.union([z.strictObject({
+	event: patternSchema,
+	appId: patternSchema.optional()
+}), z.strictObject({ segment: z.string().min(1) })]);
+/** A content address: `sha256:` plus the lowercase hex digest. */
+const digestSchema = z.string().regex(/^sha256:[0-9a-f]{64}$/, "digest must be sha256:<64 hex>");
+/** The names of the capability calls a journey may make. */
+const COMMAND_NAMES = [
+	"sleep",
+	"waitForEvent",
+	"email.send",
+	"webhook.send",
+	"traits.set",
+	"traits.unset",
+	"profile.get",
+	"profiles.get",
+	"events.track",
+	"restart"
+];
+/**
+* One entry of the step spine `cow build` records by running `run` once
+* against a recording stub. Display only, never trusted: a journey's real
+* control flow is whatever its code does at runtime. `detail` names the
+* template, destination, event, or trait key when the call has one.
+*/
+const spineEntrySchema = z.object({
+	name: z.enum(COMMAND_NAMES),
+	detail: z.string().max(200).optional()
+});
+const manifestJourneySchema = z.object({
+	key: journeyKeySchema,
+	/** The author's labels; the dashboard's only grouping. */
+	tags: tagsSchema,
+	trigger: triggerSchema,
+	purpose: z.enum(CONSENT_PURPOSES),
+	/** The author's rollout gate: the journey is active only in these. */
+	environments: environmentsSchema,
+	spine: z.array(spineEntrySchema),
+	bundle: digestSchema
+});
+const manifestTemplateSchema = z.object({
+	key: journeyKeySchema,
+	/** The author's labels; the dashboard's only grouping. */
+	tags: tagsSchema,
+	sendClass: z.enum(SEND_CLASSES),
+	/** True asks the host to mint a signed `verifyUrl` prop at send time. */
+	verifyLink: z.boolean(),
+	/** JSON Schema of the template's `props`, converted by `cow build`. */
+	propsSchema: z.record(z.string(), z.unknown()),
+	bundle: digestSchema
+});
+function uniqueKeys(items, ctx, path) {
+	const seen = /* @__PURE__ */ new Set();
+	for (const [index, item] of items.entries()) {
+		if (seen.has(item.key)) ctx.addIssue({
+			code: "custom",
+			message: `duplicate ${path} key "${item.key}"`,
+			path: [
+				path,
+				index,
+				"key"
+			]
+		});
+		seen.add(item.key);
+	}
+}
+/** What `cow build` writes to `.cow/build/manifest.json` and `cow push` sends. */
+const manifestSchema = z.object({
+	protocol: z.literal(1),
+	/** The `@cowliss/cli` version the project was built with. */
+	sdk: z.string().min(1),
+	journeys: z.array(manifestJourneySchema).max(RELEASE_LIMITS.journeys),
+	templates: z.array(manifestTemplateSchema).max(RELEASE_LIMITS.templates),
+	/** Digest of the gzipped source tarball. */
+	source: digestSchema
+}).superRefine((manifest, ctx) => {
+	uniqueKeys(manifest.journeys, ctx, "journeys");
+	uniqueKeys(manifest.templates, ctx, "templates");
+});
+/**
+* The manifest as the release row stores it once compilation succeeded:
+* the pushed manifest plus the compiled module digest per key, and the
+* digest of the Javy engine plugin the toolchain that compiled them was
+* built from.
+*
+* Journeys and templates are keyed separately because they share a key
+* space: `welcome.ts` and `welcome.tsx` are one journey and the email it
+* sends in every example, and a flat map would let one overwrite the other.
+*
+* `plugin` is a toolchain record, not a linked artifact: modules are
+* statically linked, so the plugin bytes are inside each module. It says
+* which engine compiled the release, which is what a later bug report or a
+* reproducible rebuild needs.
+*/
+const compiledManifestSchema = manifestSchema.safeExtend({
+	modules: z.object({
+		journeys: z.record(journeyKeySchema, digestSchema),
+		templates: z.record(journeyKeySchema, digestSchema)
+	}),
+	plugin: digestSchema
+});
+
+//#endregion
+//#region ../../packages/shared/src/journeys-v2/guest.ts
+/**
+* The guest protocol (spec: Guest protocol): the JSON a compiled module
+* reads on stdin and writes on stdout. The sandbox worker parses every byte
+* a guest returns with these schemas before anything acts on it; the guest
+* SDK and the Node simulator produce and consume the same shapes.
+*/
+/** A duration as journey code writes it: an ms-style string ("2d") or milliseconds. */
+const durationSchema = z.union([z.string().min(1), z.number().int().nonnegative()]);
+/** The event a journey runs for, or waits on: name, properties, and when. */
+const guestEventSchema = z.object({
+	name: z.string().min(1),
+	properties: z.record(z.string(), z.unknown()),
+	/** Milliseconds since the epoch; the guest's clock starts here. */
+	timestamp: z.number().int().nonnegative()
+});
+const properties = z.record(z.string(), z.unknown());
+/**
+* One capability call as the guest suspends on it: the runner dispatches by
+* `name` and validates `args` with this schema before any activity sees
+* them. A name outside the union is rejected, never dispatched.
+*
+* Every `args` is strict, and that is the tenancy boundary made mechanical:
+* a module that returns an `orgId`, an `environment`, or any other field
+* beside the ones a capability takes fails the parse instead of having it
+* quietly dropped. Tenant context comes from the workflow input, never from
+* guest output, and this is where saying so becomes checkable.
+*/
+const commandSchema = z.discriminatedUnion("name", [
+	z.object({
+		name: z.literal("sleep"),
+		args: z.strictObject({ duration: durationSchema })
+	}),
+	z.object({
+		name: z.literal("waitForEvent"),
+		args: z.strictObject({
+			event: patternSchema,
+			timeout: durationSchema
+		})
+	}),
+	z.object({
+		name: z.literal("email.send"),
+		args: z.strictObject({
+			template: journeyKeySchema,
+			props: properties
+		})
+	}),
+	z.object({
+		name: z.literal("webhook.send"),
+		args: z.strictObject({
+			destination: z.string().min(1),
+			payload: properties
+		})
+	}),
+	z.object({
+		name: z.literal("traits.set"),
+		args: z.strictObject({
+			key: z.string().min(1),
+			value: z.unknown()
+		})
+	}),
+	z.object({
+		name: z.literal("traits.unset"),
+		args: z.strictObject({ key: z.string().min(1) })
+	}),
+	z.object({
+		name: z.literal("profile.get"),
+		args: z.strictObject({})
+	}),
+	z.object({
+		name: z.literal("profiles.get"),
+		args: z.strictObject({ id: z.string().min(1) })
+	}),
+	z.object({
+		name: z.literal("events.track"),
+		args: z.strictObject({
+			event: z.string().min(1),
+			properties
+		})
+	}),
+	z.object({
+		name: z.literal("restart"),
+		args: z.strictObject({ event: guestEventSchema.optional() })
+	})
+]);
+/** A journaled call's outcome: the value the capability returned, or why it threw. */
+const journalResultSchema = z.discriminatedUnion("ok", [z.object({
+	ok: z.literal(true),
+	value: z.unknown()
+}), z.object({
+	ok: z.literal(false),
+	error: z.object({
+		code: z.string().min(1),
+		message: z.string()
+	})
+})]);
+/**
+* One line of the journal the runner carries per execution. `at` is the
+* workflow time the result was recorded, in epoch milliseconds: it is what
+* `Date.now()` returns to journey code between this call and the next.
+*/
+const journalEntrySchema = z.object({
+	call: commandSchema,
+	result: journalResultSchema,
+	at: z.number().int().nonnegative()
+});
+const LOG_LEVELS = [
+	"debug",
+	"info",
+	"warn",
+	"error"
+];
+/** One `api.log` line, emitted during the step's new segment only. */
+const logLineSchema = z.object({
+	level: z.enum(LOG_LEVELS),
+	message: z.string().max(EXECUTION_LIMITS.logLineBytes)
+});
+/** The per-execution caps the guest is told about, so it can fail early. */
+const executionLimitsSchema = z.object({
+	calls: z.number().int().positive(),
+	journalBytes: z.number().int().positive(),
+	logLines: z.number().int().positive(),
+	logLineBytes: z.number().int().positive()
+});
+const journeyStepInputSchema = z.object({
+	protocol: z.literal(1),
+	kind: z.literal("journey"),
+	key: journeyKeySchema,
+	event: guestEventSchema,
+	/** Workflow time at the start of this step, epoch milliseconds. */
+	now: z.number().int().nonnegative(),
+	/** Seeds `Math.random()`; derived from the execution id. */
+	seed: z.string().min(1),
+	journal: z.array(journalEntrySchema).max(EXECUTION_LIMITS.calls),
+	limits: executionLimitsSchema
+});
+const logs = z.array(logLineSchema).max(EXECUTION_LIMITS.logLines).default([]);
+/** The error codes a guest itself reports; traps are mapped host-side. */
+const GUEST_ERROR_CODES = ["journey_error", "journey_nondeterministic"];
+const journeyStepOutputSchema = z.discriminatedUnion("status", [
+	z.object({
+		status: z.literal("suspend"),
+		call: commandSchema,
+		logs
+	}),
+	z.object({
+		status: z.literal("done"),
+		logs
+	}),
+	z.object({
+		status: z.literal("error"),
+		error: z.object({
+			code: z.enum(GUEST_ERROR_CODES),
+			message: z.string(),
+			stack: z.string().optional()
+		}),
+		/** Set when a replayed call diverged from the journal: both are named. */
+		nondeterministic: z.object({
+			expected: commandSchema,
+			actual: commandSchema
+		}).optional(),
+		logs
+	})
+]);
+const templateRenderInputSchema = z.object({
+	protocol: z.literal(1),
+	kind: z.literal("template"),
+	key: journeyKeySchema,
+	props: properties
+});
+const templateRenderOutputSchema = z.object({
+	subject: z.string(),
+	html: z.string(),
+	text: z.string()
+});
+/** Asks a module for its own config; the compile step checks it against the push. */
+const manifestInputSchema = z.object({ kind: z.literal("manifest") });
+/**
+* A module's self-report. The host knows which key it ran, so the report
+* carries the config only.
+*/
+const manifestOutputSchema = z.discriminatedUnion("kind", [manifestJourneySchema.pick({
+	trigger: true,
+	purpose: true,
+	environments: true,
+	tags: true
+}).extend({ kind: z.literal("journey") }), manifestTemplateSchema.pick({
+	sendClass: true,
+	verifyLink: true,
+	propsSchema: true,
+	tags: true
+}).extend({ kind: z.literal("template") })]);
+/** Everything a driver may be handed on stdin. */
+const guestInputSchema = z.discriminatedUnion("kind", [
+	journeyStepInputSchema,
+	templateRenderInputSchema,
+	manifestInputSchema
+]);
+/**
+* Execution lifecycle as the runner records it. `waiting` is a suspended
+* step (a timer or a signal wait); `cancelled` is the runner honouring a
+* release cancellation at its next step.
+*/
+const EXECUTION_STATUSES = [
+	"running",
+	"waiting",
+	"completed",
+	"failed",
+	"cancelled"
+];
+const executionStatusSchema = z.enum(EXECUTION_STATUSES);
+
+//#endregion
+//#region ../../packages/shared/src/journeys-v2/sandbox.ts
+/**
+* What the sandbox worker's activities return (spec: Sandbox worker). A
+* guest failure is a value, not a throw: the runner has to journal it and
+* record it on the execution, and a Temporal retry would only reproduce it.
+* Infrastructure failures (a missing binary, a spawn error, Postgres down)
+* throw and retry on the activity's bounded policy.
+*/
+/** Every way a guest invocation can fail, as the runner records it. */
+const SANDBOX_FAILURE_CODES = [
+	"journey_fuel_exceeded",
+	"journey_timeout",
+	"journey_memory_exceeded",
+	"journey_error",
+	"journey_output_invalid"
+];
+const sandboxFailureCodeSchema = z.enum(SANDBOX_FAILURE_CODES);
+
+//#endregion
+//#region ../../packages/shared/src/journeys-v2/scenario.ts
+/**
+* Scenario files for `cow test`: a journey run scripted as JSON and replayed
+* on a virtual clock, so a 2-day journey is asserted in seconds. The shape is deliberately small (a user, some later
+* events, the side effects the run must produce) because a scenario is meant
+* to be written by hand or by an agent, not generated.
+*
+* The schema lives here rather than in packages/journeys so the CLI can reject
+* a bad file before it boots a Temporal environment, and so the docs site can
+* render the format from one source.
+*/
+const journeyScenarioSchema = z.object({
+	/** The user the instance runs for; traits are what getProfile returns. */
+	user: z.object({
+		id: z.string().min(1),
+		traits: z.record(z.string(), z.unknown()).default({})
+	}).default({
+		id: "user_1",
+		traits: {}
+	}),
+	/**
+	* Later events, each at an offset from instance start: ms-style string
+	* ("1h", "2d") or milliseconds. The trigger event itself is delivered
+	* automatically at start, exactly as production does.
+	*/
+	events: z.array(z.object({
+		at: z.union([z.string().min(1), z.number().int().nonnegative()]),
+		event: z.string().min(1)
+	})).default([]),
+	/**
+	* Every side-effect activity call the run must make, in order. `input` is
+	* matched as a subset of the actual activity input, so a scenario asserts
+	* the fields it cares about and ignores the rest.
+	*/
+	expect: z.array(z.object({
+		activity: z.enum([
+			"sendEmail",
+			"sendWebhook",
+			"setTrait",
+			"unsetTrait",
+			"trackEvent",
+			"restart"
+		]),
+		input: z.record(z.string(), z.unknown()).optional()
+	}))
+});
+
+//#endregion
+//#region src/guest/journeys.ts
+/**
+* A capability that failed host-side (an unknown destination, invalid
+* props, a profile that is not there). The failure is journaled, so a
+* journey that catches it takes the same branch on every replay.
+*/
+var CapabilityError = class extends Error {
+	code;
+	constructor(code, message) {
+		super(message);
+		this.name = "CapabilityError";
+		this.code = code;
+	}
+};
+/**
+* The config half of a journey, validated with the same schema the release
+* manifest is validated with, so a bad trigger or an unknown purpose fails
+* at build time rather than at the first execution.
+*/
+const journeyConfigSchema = manifestJourneySchema.pick({
+	trigger: true,
+	purpose: true,
+	environments: true,
+	tags: true
+});
+/** Author a journey. Throws at definition time on an invalid config. */
+function defineJourney(input) {
+	return {
+		...journeyConfigSchema.parse({
+			trigger: input.trigger,
+			purpose: input.purpose,
+			environments: input.environments ?? [...ENVIRONMENTS],
+			tags: input.tags
+		}),
+		run: input.run
+	};
+}
+
+//#endregion
+export { manifestOutputSchema as a, journeyStepOutputSchema as i, defineJourney as n, templateRenderOutputSchema as o, guestInputSchema as r, CapabilityError as t };

package/dist/guest/journeys.d.ts

@@ -0,0 +1,127 @@
+import { n as Duration, r as GuestEvent, t as Trigger } from "./index-heC1gFE_.js";
+import { n as Environment, t as ConsentPurpose } from "./constants-OZrYz4I2.js";
+//#region src/guest/journeys.d.ts
+/** The event a journey runs for, or the one a `waitForEvent` resolved with. */
+type Event = GuestEvent;
+/**
+ * A profile as the capability layer hands it back: the recipient of this
+ * execution (`api.profile.get()`) or another profile in the same org and
+ * environment (`api.profiles.get(id)`). A fresh read on every call.
+ */
+type Profile = {
+  /** The Cowliss-generated profile id (`usr_`). */
+  id: string;
+  traits: Record<string, unknown>;
+  /** Consent state per purpose; the send gates read it host-side too. */
+  consent: Record<ConsentPurpose, boolean>;
+  identifiers: Record<string, string>;
+  /** Names of the segments the profile is currently in. */
+  segments: string[];
+};
+/** What `api.email.send` resolves to once the host accepted the send. */
+type EmailSendResult = {
+  deliveryId: string;
+  status: string;
+};
+/**
+ * A capability that failed host-side (an unknown destination, invalid
+ * props, a profile that is not there). The failure is journaled, so a
+ * journey that catches it takes the same branch on every replay.
+ */
+declare class CapabilityError extends Error {
+  readonly code: string;
+  constructor(code: string, message: string);
+}
+/**
+ * The project's templates, keyed by template key. `cow build` writes the
+ * real interface into `.cow/types.d.ts` and TypeScript merges it into this
+ * one, which is what types `api.email.send`. Empty here on purpose: a
+ * project that has not built yet still compiles, with string keys.
+ */
+interface CowTemplates {}
+type TemplateKey = keyof CowTemplates extends never ? string : keyof CowTemplates;
+type TemplateProps<Key> = Key extends keyof CowTemplates ? CowTemplates[Key] : Record<string, unknown>;
+/**
+ * The capability object a journey's `run` receives. Every method is async
+ * and journaled (except `log`), which is what makes a replay reproduce the
+ * run exactly: the SDK compares each call against the journal and returns
+ * the recorded result instead of doing the work again.
+ */
+type Api = {
+  /** Durable wait; the runner turns it into a Temporal timer. */
+  sleep(duration: Duration): Promise<void>;
+  /**
+   * The next event matching this pattern, or `null` once the timeout
+   * elapses. `*` matches any run of characters, a list of patterns is a
+   * disjunction, and the resolved event carries its own `name`, so a wait on
+   * a list can branch on which one arrived. A pattern whose literal prefix
+   * is not `system.` never resolves with an event Cowliss wrote itself.
+   */
+  waitForEvent(pattern: string | string[], options: {
+    timeout: Duration;
+  }): Promise<Event | null>;
+  email: {
+    send<Key extends TemplateKey>(args: {
+      template: Key;
+      props: TemplateProps<Key>;
+    }): Promise<EmailSendResult>;
+  };
+  webhook: {
+    send(args: {
+      destination: string;
+      payload: Record<string, unknown>;
+    }): Promise<void>;
+  };
+  traits: {
+    /** A `null` value deletes the key (RFC 7386 merge, as identify does). */
+    set(key: string, value: unknown): Promise<void>;
+    unset(key: string): Promise<void>;
+  };
+  profile: {
+    get(): Promise<Profile>;
+  };
+  profiles: {
+    get(id: string): Promise<Profile>;
+  };
+  /**
+   * Writes an event on the recipient's timeline; may trigger other journeys.
+   * The name may not start with `system.`, which Cowliss reserves for its
+   * own events: that call throws a CapabilityError instead of writing.
+   */
+  events: {
+    track(name: string, properties: Record<string, unknown>): Promise<void>;
+  };
+  /** Not journaled; captured per execution and shown on the execution. */
+  log(...args: unknown[]): void;
+  /**
+   * Ends this execution and starts a fresh one under the same workflow id
+   * with an empty journal. Never resolves: the execution is over.
+   */
+  restart(args?: {
+    event?: Event;
+  }): Promise<never>;
+};
+/**
+ * A journey as `defineJourney` returns it: the validated config plus `run`.
+ * The manifest path reports the config back to the host, which compares it
+ * with what `cow push` uploaded.
+ */
+type JourneyConfig = {
+  trigger: Trigger;
+  purpose: ConsentPurpose;
+  /** The author's rollout gate; defaults to every environment. */
+  environments: Environment[];
+  /** The author's labels; the dashboard's only grouping. Defaults to none. */
+  tags: string[];
+};
+type Journey = JourneyConfig & {
+  run: (event: Event, api: Api) => Promise<void>;
+};
+/** Author a journey. Throws at definition time on an invalid config. */
+declare function defineJourney(input: Omit<JourneyConfig, "environments" | "tags"> & {
+  environments?: Environment[];
+  tags?: string[];
+  run: (event: Event, api: Api) => Promise<void>;
+}): Journey;
+//#endregion
+export { Api, CapabilityError, CowTemplates, type Duration, EmailSendResult, Event, Journey, JourneyConfig, Profile, type Trigger, defineJourney };

package/dist/guest/journeys.js

@@ -0,0 +1,3 @@
+import { n as defineJourney, t as CapabilityError } from "./journeys-CxuS-mHn.js";
+
+export { CapabilityError, defineJourney };