@scenarist/core 0.0.1 → 0.1.0

package/dist/schemas/scenario-definition.d.ts

@@ -0,0 +1,276 @@
+import { z } from 'zod';
+/**
+ * Zod schemas for scenario definitions.
+ * These schemas validate the structure of scenario data at trust boundaries.
+ *
+ * **IMPORTANT**: TypeScript types are inferred from these schemas to maintain
+ * a single source of truth. The schemas in this file are the canonical definition.
+ */
+export declare const HttpMethodSchema: z.ZodEnum<{
+    GET: "GET";
+    POST: "POST";
+    PUT: "PUT";
+    DELETE: "DELETE";
+    PATCH: "PATCH";
+    OPTIONS: "OPTIONS";
+    HEAD: "HEAD";
+}>;
+export type HttpMethod = z.infer<typeof HttpMethodSchema>;
+export declare const ScenaristResponseSchema: z.ZodObject<{
+    status: z.ZodNumber;
+    body: z.ZodOptional<z.ZodUnknown>;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    delay: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type ScenaristResponse = z.infer<typeof ScenaristResponseSchema>;
+/**
+ * Match value supports 6 matching strategies:
+ * - Plain string: exact match (backward compatible)
+ * - equals: explicit exact match
+ * - contains: substring match
+ * - startsWith: prefix match
+ * - endsWith: suffix match
+ * - regex: pattern match (serialized form)
+ * - Native RegExp: pattern match (native JavaScript RegExp object)
+ *
+ * Exactly ONE strategy must be defined when using object form.
+ */
+export declare const MatchValueSchema: z.ZodUnion<readonly [z.ZodString, z.ZodCustom<RegExp, RegExp>, z.ZodObject<{
+    equals: z.ZodOptional<z.ZodString>;
+    contains: z.ZodOptional<z.ZodString>;
+    startsWith: z.ZodOptional<z.ZodString>;
+    endsWith: z.ZodOptional<z.ZodString>;
+    regex: z.ZodOptional<z.ZodObject<{
+        source: z.ZodString;
+        flags: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>]>;
+export type MatchValue = z.infer<typeof MatchValueSchema>;
+export declare const ScenaristMatchSchema: z.ZodObject<{
+    url: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodCustom<RegExp, RegExp>, z.ZodObject<{
+        equals: z.ZodOptional<z.ZodString>;
+        contains: z.ZodOptional<z.ZodString>;
+        startsWith: z.ZodOptional<z.ZodString>;
+        endsWith: z.ZodOptional<z.ZodString>;
+        regex: z.ZodOptional<z.ZodObject<{
+            source: z.ZodString;
+            flags: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>]>>;
+    body: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodCustom<RegExp, RegExp>, z.ZodObject<{
+        equals: z.ZodOptional<z.ZodString>;
+        contains: z.ZodOptional<z.ZodString>;
+        startsWith: z.ZodOptional<z.ZodString>;
+        endsWith: z.ZodOptional<z.ZodString>;
+        regex: z.ZodOptional<z.ZodObject<{
+            source: z.ZodString;
+            flags: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>]>>>;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodCustom<RegExp, RegExp>, z.ZodObject<{
+        equals: z.ZodOptional<z.ZodString>;
+        contains: z.ZodOptional<z.ZodString>;
+        startsWith: z.ZodOptional<z.ZodString>;
+        endsWith: z.ZodOptional<z.ZodString>;
+        regex: z.ZodOptional<z.ZodObject<{
+            source: z.ZodString;
+            flags: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>]>>>;
+    query: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodCustom<RegExp, RegExp>, z.ZodObject<{
+        equals: z.ZodOptional<z.ZodString>;
+        contains: z.ZodOptional<z.ZodString>;
+        startsWith: z.ZodOptional<z.ZodString>;
+        endsWith: z.ZodOptional<z.ZodString>;
+        regex: z.ZodOptional<z.ZodObject<{
+            source: z.ZodString;
+            flags: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>]>>>;
+}, z.core.$strip>;
+export type ScenaristMatch = z.infer<typeof ScenaristMatchSchema>;
+export declare const RepeatModeSchema: z.ZodEnum<{
+    last: "last";
+    cycle: "cycle";
+    none: "none";
+}>;
+export type RepeatMode = z.infer<typeof RepeatModeSchema>;
+export declare const ScenaristSequenceSchema: z.ZodObject<{
+    responses: z.ZodArray<z.ZodObject<{
+        status: z.ZodNumber;
+        body: z.ZodOptional<z.ZodUnknown>;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        delay: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    repeat: z.ZodOptional<z.ZodEnum<{
+        last: "last";
+        cycle: "cycle";
+        none: "none";
+    }>>;
+}, z.core.$strip>;
+export type ScenaristSequence = z.infer<typeof ScenaristSequenceSchema>;
+export declare const ScenaristCaptureConfigSchema: z.ZodRecord<z.ZodString, z.ZodString>;
+export type ScenaristCaptureConfig = z.infer<typeof ScenaristCaptureConfigSchema>;
+/**
+ * URL pattern supports three forms:
+ * - String: exact match, path params (/users/:id), or glob (/api/*)
+ * - Native RegExp: pattern match (e.g., /\/users\/\d+/)
+ */
+export declare const ScenaristUrlPatternSchema: z.ZodUnion<readonly [z.ZodString, z.ZodCustom<RegExp, RegExp>]>;
+export type ScenaristUrlPattern = z.infer<typeof ScenaristUrlPatternSchema>;
+export declare const ScenaristMockSchema: z.ZodObject<{
+    method: z.ZodEnum<{
+        GET: "GET";
+        POST: "POST";
+        PUT: "PUT";
+        DELETE: "DELETE";
+        PATCH: "PATCH";
+        OPTIONS: "OPTIONS";
+        HEAD: "HEAD";
+    }>;
+    url: z.ZodUnion<readonly [z.ZodString, z.ZodCustom<RegExp, RegExp>]>;
+    match: z.ZodOptional<z.ZodObject<{
+        url: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodCustom<RegExp, RegExp>, z.ZodObject<{
+            equals: z.ZodOptional<z.ZodString>;
+            contains: z.ZodOptional<z.ZodString>;
+            startsWith: z.ZodOptional<z.ZodString>;
+            endsWith: z.ZodOptional<z.ZodString>;
+            regex: z.ZodOptional<z.ZodObject<{
+                source: z.ZodString;
+                flags: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>]>>;
+        body: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodCustom<RegExp, RegExp>, z.ZodObject<{
+            equals: z.ZodOptional<z.ZodString>;
+            contains: z.ZodOptional<z.ZodString>;
+            startsWith: z.ZodOptional<z.ZodString>;
+            endsWith: z.ZodOptional<z.ZodString>;
+            regex: z.ZodOptional<z.ZodObject<{
+                source: z.ZodString;
+                flags: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>]>>>;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodCustom<RegExp, RegExp>, z.ZodObject<{
+            equals: z.ZodOptional<z.ZodString>;
+            contains: z.ZodOptional<z.ZodString>;
+            startsWith: z.ZodOptional<z.ZodString>;
+            endsWith: z.ZodOptional<z.ZodString>;
+            regex: z.ZodOptional<z.ZodObject<{
+                source: z.ZodString;
+                flags: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>]>>>;
+        query: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodCustom<RegExp, RegExp>, z.ZodObject<{
+            equals: z.ZodOptional<z.ZodString>;
+            contains: z.ZodOptional<z.ZodString>;
+            startsWith: z.ZodOptional<z.ZodString>;
+            endsWith: z.ZodOptional<z.ZodString>;
+            regex: z.ZodOptional<z.ZodObject<{
+                source: z.ZodString;
+                flags: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>]>>>;
+    }, z.core.$strip>>;
+    response: z.ZodOptional<z.ZodObject<{
+        status: z.ZodNumber;
+        body: z.ZodOptional<z.ZodUnknown>;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        delay: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    sequence: z.ZodOptional<z.ZodObject<{
+        responses: z.ZodArray<z.ZodObject<{
+            status: z.ZodNumber;
+            body: z.ZodOptional<z.ZodUnknown>;
+            headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            delay: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+        repeat: z.ZodOptional<z.ZodEnum<{
+            last: "last";
+            cycle: "cycle";
+            none: "none";
+        }>>;
+    }, z.core.$strip>>;
+    captureState: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strip>;
+export type ScenaristMock = z.infer<typeof ScenaristMockSchema>;
+export declare const ScenaristScenarioSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodString;
+    mocks: z.ZodArray<z.ZodObject<{
+        method: z.ZodEnum<{
+            GET: "GET";
+            POST: "POST";
+            PUT: "PUT";
+            DELETE: "DELETE";
+            PATCH: "PATCH";
+            OPTIONS: "OPTIONS";
+            HEAD: "HEAD";
+        }>;
+        url: z.ZodUnion<readonly [z.ZodString, z.ZodCustom<RegExp, RegExp>]>;
+        match: z.ZodOptional<z.ZodObject<{
+            url: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodCustom<RegExp, RegExp>, z.ZodObject<{
+                equals: z.ZodOptional<z.ZodString>;
+                contains: z.ZodOptional<z.ZodString>;
+                startsWith: z.ZodOptional<z.ZodString>;
+                endsWith: z.ZodOptional<z.ZodString>;
+                regex: z.ZodOptional<z.ZodObject<{
+                    source: z.ZodString;
+                    flags: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>]>>;
+            body: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodCustom<RegExp, RegExp>, z.ZodObject<{
+                equals: z.ZodOptional<z.ZodString>;
+                contains: z.ZodOptional<z.ZodString>;
+                startsWith: z.ZodOptional<z.ZodString>;
+                endsWith: z.ZodOptional<z.ZodString>;
+                regex: z.ZodOptional<z.ZodObject<{
+                    source: z.ZodString;
+                    flags: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>]>>>;
+            headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodCustom<RegExp, RegExp>, z.ZodObject<{
+                equals: z.ZodOptional<z.ZodString>;
+                contains: z.ZodOptional<z.ZodString>;
+                startsWith: z.ZodOptional<z.ZodString>;
+                endsWith: z.ZodOptional<z.ZodString>;
+                regex: z.ZodOptional<z.ZodObject<{
+                    source: z.ZodString;
+                    flags: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>]>>>;
+            query: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodCustom<RegExp, RegExp>, z.ZodObject<{
+                equals: z.ZodOptional<z.ZodString>;
+                contains: z.ZodOptional<z.ZodString>;
+                startsWith: z.ZodOptional<z.ZodString>;
+                endsWith: z.ZodOptional<z.ZodString>;
+                regex: z.ZodOptional<z.ZodObject<{
+                    source: z.ZodString;
+                    flags: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>]>>>;
+        }, z.core.$strip>>;
+        response: z.ZodOptional<z.ZodObject<{
+            status: z.ZodNumber;
+            body: z.ZodOptional<z.ZodUnknown>;
+            headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            delay: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+        sequence: z.ZodOptional<z.ZodObject<{
+            responses: z.ZodArray<z.ZodObject<{
+                status: z.ZodNumber;
+                body: z.ZodOptional<z.ZodUnknown>;
+                headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+                delay: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>>;
+            repeat: z.ZodOptional<z.ZodEnum<{
+                last: "last";
+                cycle: "cycle";
+                none: "none";
+            }>>;
+        }, z.core.$strip>>;
+        captureState: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ScenaristScenario = z.infer<typeof ScenaristScenarioSchema>;
+//# sourceMappingURL=scenario-definition.d.ts.map

package/dist/schemas/scenario-definition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scenario-definition.d.ts","sourceRoot":"","sources":["../../src/schemas/scenario-definition.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;GAMG;AAEH,eAAO,MAAM,gBAAgB;;;;;;;;EAAuE,CAAC;AACrG,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,eAAO,MAAM,uBAAuB;;;;;iBAKlC,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;mBAiB3B,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAK/B,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE,eAAO,MAAM,gBAAgB;;;;EAAoC,CAAC;AAClE,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,eAAO,MAAM,uBAAuB;;;;;;;;;;;;iBAGlC,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE,eAAO,MAAM,4BAA4B,uCAAmC,CAAC;AAC7E,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAElF;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,iEAGpC,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAO9B,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAKlC,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC"}

package/dist/schemas/scenario-definition.js

@@ -0,0 +1,78 @@
+import { z } from 'zod';
+import { SerializedRegexSchema } from './match-criteria.js';
+/**
+ * Zod schemas for scenario definitions.
+ * These schemas validate the structure of scenario data at trust boundaries.
+ *
+ * **IMPORTANT**: TypeScript types are inferred from these schemas to maintain
+ * a single source of truth. The schemas in this file are the canonical definition.
+ */
+export const HttpMethodSchema = z.enum(['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'OPTIONS', 'HEAD']);
+export const ScenaristResponseSchema = z.object({
+    status: z.number().int().min(100).max(599),
+    body: z.unknown().optional(),
+    headers: z.record(z.string(), z.string()).optional(),
+    delay: z.number().nonnegative().optional(),
+});
+/**
+ * Match value supports 6 matching strategies:
+ * - Plain string: exact match (backward compatible)
+ * - equals: explicit exact match
+ * - contains: substring match
+ * - startsWith: prefix match
+ * - endsWith: suffix match
+ * - regex: pattern match (serialized form)
+ * - Native RegExp: pattern match (native JavaScript RegExp object)
+ *
+ * Exactly ONE strategy must be defined when using object form.
+ */
+export const MatchValueSchema = z.union([
+    z.string(),
+    z.instanceof(RegExp),
+    z.object({
+        equals: z.string().optional(),
+        contains: z.string().optional(),
+        startsWith: z.string().optional(),
+        endsWith: z.string().optional(),
+        regex: SerializedRegexSchema.optional(),
+    }).refine((obj) => {
+        const strategies = [obj.equals, obj.contains, obj.startsWith, obj.endsWith, obj.regex];
+        const defined = strategies.filter(s => s !== undefined);
+        return defined.length === 1;
+    }, { message: 'Exactly one matching strategy must be defined (equals, contains, startsWith, endsWith, or regex)' }),
+]);
+export const ScenaristMatchSchema = z.object({
+    url: MatchValueSchema.optional(),
+    body: z.record(z.string(), MatchValueSchema).optional(),
+    headers: z.record(z.string(), MatchValueSchema).optional(),
+    query: z.record(z.string(), MatchValueSchema).optional(),
+});
+export const RepeatModeSchema = z.enum(['last', 'cycle', 'none']);
+export const ScenaristSequenceSchema = z.object({
+    responses: z.array(ScenaristResponseSchema).min(1),
+    repeat: RepeatModeSchema.optional(),
+});
+export const ScenaristCaptureConfigSchema = z.record(z.string(), z.string());
+/**
+ * URL pattern supports three forms:
+ * - String: exact match, path params (/users/:id), or glob (/api/*)
+ * - Native RegExp: pattern match (e.g., /\/users\/\d+/)
+ */
+export const ScenaristUrlPatternSchema = z.union([
+    z.string().min(1),
+    z.instanceof(RegExp),
+]);
+export const ScenaristMockSchema = z.object({
+    method: HttpMethodSchema,
+    url: ScenaristUrlPatternSchema,
+    match: ScenaristMatchSchema.optional(),
+    response: ScenaristResponseSchema.optional(),
+    sequence: ScenaristSequenceSchema.optional(),
+    captureState: ScenaristCaptureConfigSchema.optional(),
+});
+export const ScenaristScenarioSchema = z.object({
+    id: z.string().min(1),
+    name: z.string().min(1),
+    description: z.string(),
+    mocks: z.array(ScenaristMockSchema),
+});

package/dist/schemas/scenario-requests.d.ts

@@ -0,0 +1,33 @@
+import { z } from 'zod';
+/**
+ * Schema for scenario switch request body.
+ *
+ * This schema defines the domain rules for what constitutes a valid
+ * scenario switch request. All framework adapters MUST use this schema
+ * to validate scenario switch requests at the trust boundary (HTTP request → domain).
+ *
+ * **Architectural Note:**
+ * - This is DOMAIN KNOWLEDGE (what makes a valid request)
+ * - Adapters apply this validation at TRUST BOUNDARIES
+ * - Single source of truth for scenario request validation
+ * - Never duplicate this schema in adapters
+ *
+ * @example
+ * ```typescript
+ * // In adapter endpoint handler:
+ * import { ScenarioRequestSchema } from '@scenarist/core';
+ *
+ * const { scenario } = ScenarioRequestSchema.parse(req.body);
+ * ```
+ */
+export declare const ScenarioRequestSchema: z.ZodObject<{
+    scenario: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Type derived from ScenarioRequestSchema.
+ * Represents a validated scenario switch request.
+ *
+ * **Usage:** Use this type for function parameters after validation has occurred.
+ */
+export type ScenarioRequest = z.infer<typeof ScenarioRequestSchema>;
+//# sourceMappingURL=scenario-requests.d.ts.map

package/dist/schemas/scenario-requests.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scenario-requests.d.ts","sourceRoot":"","sources":["../../src/schemas/scenario-requests.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,qBAAqB;;iBAMhC,CAAC;AAEH;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC"}

package/dist/schemas/scenario-requests.js

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+/**
+ * Schema for scenario switch request body.
+ *
+ * This schema defines the domain rules for what constitutes a valid
+ * scenario switch request. All framework adapters MUST use this schema
+ * to validate scenario switch requests at the trust boundary (HTTP request → domain).
+ *
+ * **Architectural Note:**
+ * - This is DOMAIN KNOWLEDGE (what makes a valid request)
+ * - Adapters apply this validation at TRUST BOUNDARIES
+ * - Single source of truth for scenario request validation
+ * - Never duplicate this schema in adapters
+ *
+ * @example
+ * ```typescript
+ * // In adapter endpoint handler:
+ * import { ScenarioRequestSchema } from '@scenarist/core';
+ *
+ * const { scenario } = ScenarioRequestSchema.parse(req.body);
+ * ```
+ */
+export const ScenarioRequestSchema = z.object({
+    /**
+     * Scenario ID to switch to.
+     * Must be a non-empty string matching a registered scenario ID.
+     */
+    scenario: z.string().min(1, 'Scenario ID must not be empty'),
+});

package/dist/schemas/scenarios-object.d.ts

@@ -0,0 +1,91 @@
+import { z } from 'zod';
+/**
+ * Validates that a scenarios object has a 'default' key.
+ *
+ * This enforces the convention that all scenario collections must
+ * include a 'default' scenario to serve as the baseline.
+ *
+ * **Trust Boundary:** Applied in buildConfig when user provides scenarios.
+ *
+ * Each value must be a valid ScenarioDefinition with proper structure.
+ */
+export declare const ScenariosObjectSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodString;
+    mocks: z.ZodArray<z.ZodObject<{
+        method: z.ZodEnum<{
+            GET: "GET";
+            POST: "POST";
+            PUT: "PUT";
+            DELETE: "DELETE";
+            PATCH: "PATCH";
+            OPTIONS: "OPTIONS";
+            HEAD: "HEAD";
+        }>;
+        url: z.ZodUnion<readonly [z.ZodString, z.ZodCustom<RegExp, RegExp>]>;
+        match: z.ZodOptional<z.ZodObject<{
+            url: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodCustom<RegExp, RegExp>, z.ZodObject<{
+                equals: z.ZodOptional<z.ZodString>;
+                contains: z.ZodOptional<z.ZodString>;
+                startsWith: z.ZodOptional<z.ZodString>;
+                endsWith: z.ZodOptional<z.ZodString>;
+                regex: z.ZodOptional<z.ZodObject<{
+                    source: z.ZodString;
+                    flags: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>]>>;
+            body: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodCustom<RegExp, RegExp>, z.ZodObject<{
+                equals: z.ZodOptional<z.ZodString>;
+                contains: z.ZodOptional<z.ZodString>;
+                startsWith: z.ZodOptional<z.ZodString>;
+                endsWith: z.ZodOptional<z.ZodString>;
+                regex: z.ZodOptional<z.ZodObject<{
+                    source: z.ZodString;
+                    flags: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>]>>>;
+            headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodCustom<RegExp, RegExp>, z.ZodObject<{
+                equals: z.ZodOptional<z.ZodString>;
+                contains: z.ZodOptional<z.ZodString>;
+                startsWith: z.ZodOptional<z.ZodString>;
+                endsWith: z.ZodOptional<z.ZodString>;
+                regex: z.ZodOptional<z.ZodObject<{
+                    source: z.ZodString;
+                    flags: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>]>>>;
+            query: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodCustom<RegExp, RegExp>, z.ZodObject<{
+                equals: z.ZodOptional<z.ZodString>;
+                contains: z.ZodOptional<z.ZodString>;
+                startsWith: z.ZodOptional<z.ZodString>;
+                endsWith: z.ZodOptional<z.ZodString>;
+                regex: z.ZodOptional<z.ZodObject<{
+                    source: z.ZodString;
+                    flags: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>]>>>;
+        }, z.core.$strip>>;
+        response: z.ZodOptional<z.ZodObject<{
+            status: z.ZodNumber;
+            body: z.ZodOptional<z.ZodUnknown>;
+            headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            delay: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+        sequence: z.ZodOptional<z.ZodObject<{
+            responses: z.ZodArray<z.ZodObject<{
+                status: z.ZodNumber;
+                body: z.ZodOptional<z.ZodUnknown>;
+                headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+                delay: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>>;
+            repeat: z.ZodOptional<z.ZodEnum<{
+                last: "last";
+                cycle: "cycle";
+                none: "none";
+            }>>;
+        }, z.core.$strip>>;
+        captureState: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>>;
+//# sourceMappingURL=scenarios-object.d.ts.map

package/dist/schemas/scenarios-object.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scenarios-object.d.ts","sourceRoot":"","sources":["../../src/schemas/scenarios-object.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAI9B,CAAC"}

package/dist/schemas/scenarios-object.js

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+import { ScenaristScenarioSchema } from './scenario-definition.js';
+/**
+ * Validates that a scenarios object has a 'default' key.
+ *
+ * This enforces the convention that all scenario collections must
+ * include a 'default' scenario to serve as the baseline.
+ *
+ * **Trust Boundary:** Applied in buildConfig when user provides scenarios.
+ *
+ * Each value must be a valid ScenarioDefinition with proper structure.
+ */
+export const ScenariosObjectSchema = z
+    .record(z.string(), ScenaristScenarioSchema)
+    .refine((scenarios) => 'default' in scenarios, {
+    message: "Scenarios object must have a 'default' key",
+});

package/dist/types/config.d.ts

@@ -0,0 +1,70 @@
+import type { ScenaristScenarios } from './scenario.js';
+/**
+ * Configuration for the scenario management system.
+ * All properties are readonly for immutability.
+ */
+export type ScenaristConfig = {
+    /**
+     * Whether mocking is enabled.
+     * For dynamic enabling (e.g., based on environment), evaluate before creating config:
+     * `enabled: process.env.NODE_ENV !== 'production'`
+     */
+    readonly enabled: boolean;
+    /**
+     * Whether to enforce strict mode for unmocked requests.
+     *
+     * - `true`: Unmocked requests return error responses (501 Not Implemented)
+     * - `false`: Unmocked requests passthrough to real APIs
+     *
+     * Default: false
+     *
+     * Strict mode is useful in tests to ensure all external API calls are explicitly mocked,
+     * preventing accidental calls to real services.
+     */
+    readonly strictMode: boolean;
+    /**
+     * HTTP endpoint paths for scenario control.
+     */
+    readonly endpoints: {
+        /** Endpoint to set/switch scenarios (default: '/__scenario__') */
+        readonly setScenario: string;
+        /** Endpoint to get current scenario (default: '/__scenario__') */
+        readonly getScenario: string;
+    };
+    /**
+     * The default test ID to use when no x-scenarist-test-id header is present.
+     */
+    readonly defaultTestId: string;
+};
+/**
+ * Partial config for user input - missing values will use defaults.
+ * All properties must be serializable (no functions).
+ */
+export type ScenaristConfigInput<T extends ScenaristScenarios = ScenaristScenarios> = {
+    readonly enabled: boolean;
+    readonly strictMode?: boolean;
+    readonly endpoints?: Partial<ScenaristConfig['endpoints']>;
+    /**
+     * All scenarios defined as a named object.
+     * Keys become scenario IDs that enable type-safe autocomplete.
+     *
+     * **REQUIRED:** Must include a 'default' key to serve as the baseline scenario.
+     *
+     * @example
+     * ```typescript
+     * const scenarios = {
+     *   default: { id: 'default', ... },      // Required!
+     *   cartWithState: { id: 'cartWithState', ... },
+     *   premiumUser: { id: 'premiumUser', ... },
+     * } as const satisfies ScenaristScenarios;
+     *
+     * createScenarist({
+     *   enabled: true,
+     *   scenarios,
+     * });
+     * ```
+     */
+    readonly scenarios: T;
+    readonly defaultTestId?: string;
+};
+//# sourceMappingURL=config.d.ts.map

package/dist/types/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/types/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAExD;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAE1B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAE7B;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE;QAClB,kEAAkE;QAClE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAC7B,kEAAkE;QAClE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;KAC9B,CAAC;IAEF;;OAEG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,oBAAoB,CAAC,CAAC,SAAS,kBAAkB,GAAG,kBAAkB,IAAI;IACpF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,WAAW,CAAC,CAAC,CAAC;IAC3D;;;;;;;;;;;;;;;;;;;OAmBG;IACH,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC;IACtB,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC,CAAC"}

package/dist/types/config.js

@@ -0,0 +1 @@
+export {};

package/dist/types/index.d.ts

@@ -0,0 +1,4 @@
+export type { HttpMethod, ScenaristResponse, ScenaristMock, ScenaristMatch, RepeatMode, ScenaristSequence, ScenaristCaptureConfig, ScenaristScenario, } from '../schemas/scenario-definition.js';
+export type { HttpRequestContext, ScenaristMockWithParams, ActiveScenario, ScenaristResult, ScenaristScenarios, ScenarioIds, } from './scenario.js';
+export type { ScenaristConfig, ScenaristConfigInput, } from './config.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AACA,YAAY,EACV,UAAU,EACV,iBAAiB,EACjB,aAAa,EACb,cAAc,EACd,UAAU,EACV,iBAAiB,EACjB,sBAAsB,EACtB,iBAAiB,GAClB,MAAM,mCAAmC,CAAC;AAG3C,YAAY,EACV,kBAAkB,EAClB,uBAAuB,EACvB,cAAc,EACd,eAAe,EACf,kBAAkB,EAClB,WAAW,GACZ,MAAM,eAAe,CAAC;AAEvB,YAAY,EACV,eAAe,EACf,oBAAoB,GACrB,MAAM,aAAa,CAAC"}

package/dist/types/index.js

@@ -0,0 +1 @@
+export {};