@crvouga/mockingbird-service-junction 0.3.0 → 0.4.0

package/dist/cli.js

@@ -4,7 +4,7 @@ import {
   runCli,
   serveCommand,
   serveTarget
-} from "./chunk-KLBGX23P.js";
+} from "./chunk-CR35KYXY.js";
 import {
   DEFAULT_JUNCTION_BASE_URL,
   createRuntime,
@@ -12,7 +12,7 @@ import {
   isSandboxKey,
   pullCorpus,
   verifyAgainstReal
-} from "./chunk-NFWUEPW4.js";
+} from "./chunk-ICINEQ7D.js";
 import {
   defaultCorpus
 } from "./chunk-C2UGIPPM.js";

package/dist/index.d.ts

@@ -98,7 +98,12 @@ type FaultRule = {
      * rules added through `POST /__admin/faults` default to the calling namespace.
      */
     namespace?: string;
-    status: number;
+    /**
+     * Status of the injected response. Omit for a rule that only delays (`delayMs` /
+     * `latencyMs`), only drops the connection (`drop`), or only switches on an `effect`:
+     * the request then still reaches the service.
+     */
+    status?: number;
     /** Response body, serialized as JSON. A string is sent as-is. */
     body?: unknown;
     headers?: Record<string, string>;
@@ -108,6 +113,34 @@ type FaultRule = {
     rate?: number;
     /** Hold the response back this long, to exercise timeouts. */
     delayMs?: number;
+    /** Alias of `delayMs`. */
+    latencyMs?: number;
+    /**
+     * Drop the connection instead of answering: an in-process `fetch` rejects with a
+     * `TypeError`, and a served mock destroys the socket. Models "unknown outcome" failures.
+     */
+    drop?: boolean;
+    /**
+     * A named service behaviour to switch on for the matching request instead of (or
+     * before) a canned response, e.g. `created_but_500` or `numeric_tracking_id`. Services
+     * read it with `faultEffects(request)`.
+     */
+    effect?: string;
+    /** Parameters for `effect`. */
+    params?: Record<string, unknown>;
+    /** From the preset this rule was expanded from, if any. */
+    preset?: string;
+};
+/** A fault that fired for one request. */
+type FaultHit = {
+    id: string;
+    /** The injected response; absent when the rule only delays, drops, or sets an effect. */
+    response?: Response;
+    drop?: boolean;
+    effect?: {
+        name: string;
+        params: Record<string, unknown>;
+    };
 };
 /** What a request looks like to the fault matcher. */
 type FaultCandidate = {
@@ -125,13 +158,11 @@ type FaultRegistry = {
     remove(id: string): boolean;
     clear(): void;
     /**
-     * The fault this request should get, or `undefined` to let it through.
-     * Consumes one of the matching rule's remaining uses.
+     * Every fault this request should get, in rule order, stopping at the first that answers
+     * or drops (effect-only and delay-only rules let later rules match too). Consumes one of
+     * each matching rule's remaining uses.
      */
-    take(candidate: FaultCandidate): Promise<{
-        id: string;
-        response: Response;
-    } | undefined>;
+    take(candidate: FaultCandidate): Promise<FaultHit[]>;
 };
 
 /** One handled request, as the structured log sees it. */
@@ -220,6 +251,18 @@ type NamespaceSnapshot = {
     }[];
 };
 
+/** Credential → namespace mapping behind `PUT /__admin/credentials`. */
+type CredentialRegistry = {
+    set(credential: string, namespace: string): void;
+    get(credential: string): string | undefined;
+    remove(credential: string): boolean;
+    clear(): void;
+    entries(): {
+        credential: string;
+        namespace: string;
+    }[];
+};
+
 /**
  * Anything that can answer a Fetch `Request` with a `Response`.
  *
@@ -230,6 +273,82 @@ interface FetchAPI$1 {
     fetch(request: Request): Promise<Response>;
 }
 
+type WebhookEndpoint$1 = {
+    /** Stable id; generated when omitted. */
+    id?: string;
+    url: string;
+    secret?: string;
+    /** Event types to deliver; omit or include `"*"` for every type. */
+    events?: string[];
+    /** Deliver only messages whose tags include all of these (e.g. `{ account: "mso" }`). */
+    tags?: Record<string, string>;
+    /** The public URL the receiver verifies signatures against (Twilio), when it differs. */
+    signUrl?: string;
+    headers?: Record<string, string>;
+};
+type WebhookMessage = {
+    id: string;
+    namespace: string;
+    type: string;
+    body: string;
+    contentType: string;
+    tags: Record<string, string>;
+    /** Wall-clock ISO-8601 time of publication. */
+    publishedAt: string;
+};
+type WebhookAttempt$1 = {
+    attempt: number;
+    at: string;
+    status: number | null;
+    error: string | null;
+    durationMs: number;
+};
+type WebhookDelivery$1 = {
+    id: string;
+    messageId: string;
+    namespace: string;
+    type: string;
+    endpointId: string;
+    url: string;
+    state: "pending" | "delivered" | "failed" | "dropped";
+    attempts: WebhookAttempt$1[];
+};
+/** A delivery-level fault: what happens to the next `count` messages in a namespace. */
+type WebhookFault = {
+    mode: "duplicate" | "reorder" | "drop";
+    /** Messages affected; default 1. */
+    count?: number;
+};
+type PublishInput = {
+    namespace: string;
+    type: string;
+    /** Exact body; objects are JSON-encoded. */
+    body: string | Record<string, unknown> | unknown[];
+    /** Default `application/json`, or form-encoded when `form` is given. */
+    contentType?: string;
+    /** Form parameters, when the vendor posts `application/x-www-form-urlencoded`. */
+    form?: Record<string, string>;
+    tags?: Record<string, string>;
+    /** Message id; generated when omitted. */
+    id?: string;
+};
+type WebhookHub = {
+    publish(input: PublishInput): WebhookMessage;
+    /** Replace a namespace's own endpoints (`PUT /__admin/webhook-endpoints`). */
+    setEndpoints(namespace: string, endpoints: WebhookEndpoint$1[]): WebhookEndpoint$1[];
+    /** The endpoints a namespace delivers to: its own, plus the global ones. */
+    endpoints(namespace: string): WebhookEndpoint$1[];
+    messages(namespace?: string): WebhookMessage[];
+    deliveries(namespace?: string): WebhookDelivery$1[];
+    replay(deliveryId: string): Promise<WebhookDelivery$1 | undefined>;
+    /** Run every pending retry (and release held reordered messages) now. */
+    flush(): Promise<void>;
+    /** Resolve once nothing is in flight. */
+    idle(): Promise<void>;
+    fault(namespace: string, fault: WebhookFault): void;
+    clear(namespace?: string): void;
+};
+
 /** What the runtime needs from a service: a Fetch handler it can reset. */
 type ServiceInstance = FetchAPI$1 & {
     reset(): Promise<void>;
@@ -242,6 +361,11 @@ type ServiceRuntime<T extends ServiceInstance> = FetchAPI$1 & {
     readonly metrics: Metrics;
     readonly journal: Journal;
     readonly rng: Rng;
+    readonly credentials: CredentialRegistry;
+    /** The webhook hub, when the service has outbound webhooks. */
+    readonly webhooks: WebhookHub | undefined;
+    /** Expand a named preset into fault rules (and webhook faults) for `namespace`. */
+    applyPreset(name: string, namespace?: string, overrides?: Partial<FaultRule>): FaultRule[];
     /** The instance behind `namespace` (the default one when omitted), created on first use. */
     instance(namespace?: string): T;
     /** Public names of every namespace created so far. */

package/dist/index.js

@@ -50,7 +50,7 @@ import {
   supportedOperationIds,
   verifyAgainstReal,
   verifySvix
-} from "./chunk-NFWUEPW4.js";
+} from "./chunk-ICINEQ7D.js";
 import {
   SEALED_CORPUS_VERSION,
   SUPPORTED_SEALED_CORPUS_VERSIONS,

package/dist/server.d.ts

@@ -99,7 +99,12 @@ type FaultRule$1 = {
      * rules added through `POST /__admin/faults` default to the calling namespace.
      */
     namespace?: string;
-    status: number;
+    /**
+     * Status of the injected response. Omit for a rule that only delays (`delayMs` /
+     * `latencyMs`), only drops the connection (`drop`), or only switches on an `effect`:
+     * the request then still reaches the service.
+     */
+    status?: number;
     /** Response body, serialized as JSON. A string is sent as-is. */
     body?: unknown;
     headers?: Record<string, string>;
@@ -109,6 +114,34 @@ type FaultRule$1 = {
     rate?: number;
     /** Hold the response back this long, to exercise timeouts. */
     delayMs?: number;
+    /** Alias of `delayMs`. */
+    latencyMs?: number;
+    /**
+     * Drop the connection instead of answering: an in-process `fetch` rejects with a
+     * `TypeError`, and a served mock destroys the socket. Models "unknown outcome" failures.
+     */
+    drop?: boolean;
+    /**
+     * A named service behaviour to switch on for the matching request instead of (or
+     * before) a canned response, e.g. `created_but_500` or `numeric_tracking_id`. Services
+     * read it with `faultEffects(request)`.
+     */
+    effect?: string;
+    /** Parameters for `effect`. */
+    params?: Record<string, unknown>;
+    /** From the preset this rule was expanded from, if any. */
+    preset?: string;
+};
+/** A fault that fired for one request. */
+type FaultHit$1 = {
+    id: string;
+    /** The injected response; absent when the rule only delays, drops, or sets an effect. */
+    response?: Response;
+    drop?: boolean;
+    effect?: {
+        name: string;
+        params: Record<string, unknown>;
+    };
 };
 /** What a request looks like to the fault matcher. */
 type FaultCandidate$1 = {
@@ -126,13 +159,11 @@ type FaultRegistry$1 = {
     remove(id: string): boolean;
     clear(): void;
     /**
-     * The fault this request should get, or `undefined` to let it through.
-     * Consumes one of the matching rule's remaining uses.
+     * Every fault this request should get, in rule order, stopping at the first that answers
+     * or drops (effect-only and delay-only rules let later rules match too). Consumes one of
+     * each matching rule's remaining uses.
      */
-    take(candidate: FaultCandidate$1): Promise<{
-        id: string;
-        response: Response;
-    } | undefined>;
+    take(candidate: FaultCandidate$1): Promise<FaultHit$1[]>;
 };
 
 /** One handled request, as the structured log sees it. */
@@ -221,6 +252,18 @@ type NamespaceSnapshot$1 = {
     }[];
 };
 
+/** Credential → namespace mapping behind `PUT /__admin/credentials`. */
+type CredentialRegistry$1 = {
+    set(credential: string, namespace: string): void;
+    get(credential: string): string | undefined;
+    remove(credential: string): boolean;
+    clear(): void;
+    entries(): {
+        credential: string;
+        namespace: string;
+    }[];
+};
+
 /**
  * Anything that can answer a Fetch `Request` with a `Response`.
  *
@@ -231,6 +274,82 @@ interface FetchAPI$2 {
     fetch(request: Request): Promise<Response>;
 }
 
+type WebhookEndpoint$2 = {
+    /** Stable id; generated when omitted. */
+    id?: string;
+    url: string;
+    secret?: string;
+    /** Event types to deliver; omit or include `"*"` for every type. */
+    events?: string[];
+    /** Deliver only messages whose tags include all of these (e.g. `{ account: "mso" }`). */
+    tags?: Record<string, string>;
+    /** The public URL the receiver verifies signatures against (Twilio), when it differs. */
+    signUrl?: string;
+    headers?: Record<string, string>;
+};
+type WebhookMessage$1 = {
+    id: string;
+    namespace: string;
+    type: string;
+    body: string;
+    contentType: string;
+    tags: Record<string, string>;
+    /** Wall-clock ISO-8601 time of publication. */
+    publishedAt: string;
+};
+type WebhookAttempt$2 = {
+    attempt: number;
+    at: string;
+    status: number | null;
+    error: string | null;
+    durationMs: number;
+};
+type WebhookDelivery$2 = {
+    id: string;
+    messageId: string;
+    namespace: string;
+    type: string;
+    endpointId: string;
+    url: string;
+    state: "pending" | "delivered" | "failed" | "dropped";
+    attempts: WebhookAttempt$2[];
+};
+/** A delivery-level fault: what happens to the next `count` messages in a namespace. */
+type WebhookFault$1 = {
+    mode: "duplicate" | "reorder" | "drop";
+    /** Messages affected; default 1. */
+    count?: number;
+};
+type PublishInput$1 = {
+    namespace: string;
+    type: string;
+    /** Exact body; objects are JSON-encoded. */
+    body: string | Record<string, unknown> | unknown[];
+    /** Default `application/json`, or form-encoded when `form` is given. */
+    contentType?: string;
+    /** Form parameters, when the vendor posts `application/x-www-form-urlencoded`. */
+    form?: Record<string, string>;
+    tags?: Record<string, string>;
+    /** Message id; generated when omitted. */
+    id?: string;
+};
+type WebhookHub$1 = {
+    publish(input: PublishInput$1): WebhookMessage$1;
+    /** Replace a namespace's own endpoints (`PUT /__admin/webhook-endpoints`). */
+    setEndpoints(namespace: string, endpoints: WebhookEndpoint$2[]): WebhookEndpoint$2[];
+    /** The endpoints a namespace delivers to: its own, plus the global ones. */
+    endpoints(namespace: string): WebhookEndpoint$2[];
+    messages(namespace?: string): WebhookMessage$1[];
+    deliveries(namespace?: string): WebhookDelivery$2[];
+    replay(deliveryId: string): Promise<WebhookDelivery$2 | undefined>;
+    /** Run every pending retry (and release held reordered messages) now. */
+    flush(): Promise<void>;
+    /** Resolve once nothing is in flight. */
+    idle(): Promise<void>;
+    fault(namespace: string, fault: WebhookFault$1): void;
+    clear(namespace?: string): void;
+};
+
 /** What the runtime needs from a service: a Fetch handler it can reset. */
 type ServiceInstance$1 = FetchAPI$2 & {
     reset(): Promise<void>;
@@ -243,6 +362,11 @@ type ServiceRuntime$1<T extends ServiceInstance$1> = FetchAPI$2 & {
     readonly metrics: Metrics$1;
     readonly journal: Journal$1;
     readonly rng: Rng$1;
+    readonly credentials: CredentialRegistry$1;
+    /** The webhook hub, when the service has outbound webhooks. */
+    readonly webhooks: WebhookHub$1 | undefined;
+    /** Expand a named preset into fault rules (and webhook faults) for `namespace`. */
+    applyPreset(name: string, namespace?: string, overrides?: Partial<FaultRule$1>): FaultRule$1[];
     /** The instance behind `namespace` (the default one when omitted), created on first use. */
     instance(namespace?: string): T;
     /** Public names of every namespace created so far. */
@@ -388,7 +512,12 @@ type FaultRule = {
      * rules added through `POST /__admin/faults` default to the calling namespace.
      */
     namespace?: string;
-    status: number;
+    /**
+     * Status of the injected response. Omit for a rule that only delays (`delayMs` /
+     * `latencyMs`), only drops the connection (`drop`), or only switches on an `effect`:
+     * the request then still reaches the service.
+     */
+    status?: number;
     /** Response body, serialized as JSON. A string is sent as-is. */
     body?: unknown;
     headers?: Record<string, string>;
@@ -398,6 +527,34 @@ type FaultRule = {
     rate?: number;
     /** Hold the response back this long, to exercise timeouts. */
     delayMs?: number;
+    /** Alias of `delayMs`. */
+    latencyMs?: number;
+    /**
+     * Drop the connection instead of answering: an in-process `fetch` rejects with a
+     * `TypeError`, and a served mock destroys the socket. Models "unknown outcome" failures.
+     */
+    drop?: boolean;
+    /**
+     * A named service behaviour to switch on for the matching request instead of (or
+     * before) a canned response, e.g. `created_but_500` or `numeric_tracking_id`. Services
+     * read it with `faultEffects(request)`.
+     */
+    effect?: string;
+    /** Parameters for `effect`. */
+    params?: Record<string, unknown>;
+    /** From the preset this rule was expanded from, if any. */
+    preset?: string;
+};
+/** A fault that fired for one request. */
+type FaultHit = {
+    id: string;
+    /** The injected response; absent when the rule only delays, drops, or sets an effect. */
+    response?: Response;
+    drop?: boolean;
+    effect?: {
+        name: string;
+        params: Record<string, unknown>;
+    };
 };
 /** What a request looks like to the fault matcher. */
 type FaultCandidate = {
@@ -415,13 +572,11 @@ type FaultRegistry = {
     remove(id: string): boolean;
     clear(): void;
     /**
-     * The fault this request should get, or `undefined` to let it through.
-     * Consumes one of the matching rule's remaining uses.
+     * Every fault this request should get, in rule order, stopping at the first that answers
+     * or drops (effect-only and delay-only rules let later rules match too). Consumes one of
+     * each matching rule's remaining uses.
      */
-    take(candidate: FaultCandidate): Promise<{
-        id: string;
-        response: Response;
-    } | undefined>;
+    take(candidate: FaultCandidate): Promise<FaultHit[]>;
 };
 
 /** One handled request, as the structured log sees it. */
@@ -510,6 +665,18 @@ type NamespaceSnapshot = {
     }[];
 };
 
+/** Credential → namespace mapping behind `PUT /__admin/credentials`. */
+type CredentialRegistry = {
+    set(credential: string, namespace: string): void;
+    get(credential: string): string | undefined;
+    remove(credential: string): boolean;
+    clear(): void;
+    entries(): {
+        credential: string;
+        namespace: string;
+    }[];
+};
+
 /**
  * Anything that can answer a Fetch `Request` with a `Response`.
  *
@@ -520,6 +687,82 @@ interface FetchAPI$1 {
     fetch(request: Request): Promise<Response>;
 }
 
+type WebhookEndpoint$1 = {
+    /** Stable id; generated when omitted. */
+    id?: string;
+    url: string;
+    secret?: string;
+    /** Event types to deliver; omit or include `"*"` for every type. */
+    events?: string[];
+    /** Deliver only messages whose tags include all of these (e.g. `{ account: "mso" }`). */
+    tags?: Record<string, string>;
+    /** The public URL the receiver verifies signatures against (Twilio), when it differs. */
+    signUrl?: string;
+    headers?: Record<string, string>;
+};
+type WebhookMessage = {
+    id: string;
+    namespace: string;
+    type: string;
+    body: string;
+    contentType: string;
+    tags: Record<string, string>;
+    /** Wall-clock ISO-8601 time of publication. */
+    publishedAt: string;
+};
+type WebhookAttempt$1 = {
+    attempt: number;
+    at: string;
+    status: number | null;
+    error: string | null;
+    durationMs: number;
+};
+type WebhookDelivery$1 = {
+    id: string;
+    messageId: string;
+    namespace: string;
+    type: string;
+    endpointId: string;
+    url: string;
+    state: "pending" | "delivered" | "failed" | "dropped";
+    attempts: WebhookAttempt$1[];
+};
+/** A delivery-level fault: what happens to the next `count` messages in a namespace. */
+type WebhookFault = {
+    mode: "duplicate" | "reorder" | "drop";
+    /** Messages affected; default 1. */
+    count?: number;
+};
+type PublishInput = {
+    namespace: string;
+    type: string;
+    /** Exact body; objects are JSON-encoded. */
+    body: string | Record<string, unknown> | unknown[];
+    /** Default `application/json`, or form-encoded when `form` is given. */
+    contentType?: string;
+    /** Form parameters, when the vendor posts `application/x-www-form-urlencoded`. */
+    form?: Record<string, string>;
+    tags?: Record<string, string>;
+    /** Message id; generated when omitted. */
+    id?: string;
+};
+type WebhookHub = {
+    publish(input: PublishInput): WebhookMessage;
+    /** Replace a namespace's own endpoints (`PUT /__admin/webhook-endpoints`). */
+    setEndpoints(namespace: string, endpoints: WebhookEndpoint$1[]): WebhookEndpoint$1[];
+    /** The endpoints a namespace delivers to: its own, plus the global ones. */
+    endpoints(namespace: string): WebhookEndpoint$1[];
+    messages(namespace?: string): WebhookMessage[];
+    deliveries(namespace?: string): WebhookDelivery$1[];
+    replay(deliveryId: string): Promise<WebhookDelivery$1 | undefined>;
+    /** Run every pending retry (and release held reordered messages) now. */
+    flush(): Promise<void>;
+    /** Resolve once nothing is in flight. */
+    idle(): Promise<void>;
+    fault(namespace: string, fault: WebhookFault): void;
+    clear(namespace?: string): void;
+};
+
 /** What the runtime needs from a service: a Fetch handler it can reset. */
 type ServiceInstance = FetchAPI$1 & {
     reset(): Promise<void>;
@@ -532,6 +775,11 @@ type ServiceRuntime<T extends ServiceInstance> = FetchAPI$1 & {
     readonly metrics: Metrics;
     readonly journal: Journal;
     readonly rng: Rng;
+    readonly credentials: CredentialRegistry;
+    /** The webhook hub, when the service has outbound webhooks. */
+    readonly webhooks: WebhookHub | undefined;
+    /** Expand a named preset into fault rules (and webhook faults) for `namespace`. */
+    applyPreset(name: string, namespace?: string, overrides?: Partial<FaultRule>): FaultRule[];
     /** The instance behind `namespace` (the default one when omitted), created on first use. */
     instance(namespace?: string): T;
     /** Public names of every namespace created so far. */

package/dist/server.js

@@ -3,8 +3,8 @@ import {
   createServer,
   loadCorpus,
   serveTarget
-} from "./chunk-KLBGX23P.js";
-import "./chunk-NFWUEPW4.js";
+} from "./chunk-CR35KYXY.js";
+import "./chunk-ICINEQ7D.js";
 import "./chunk-C2UGIPPM.js";
 import "./chunk-ISDNA2TU.js";
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crvouga/mockingbird-service-junction",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Stateful mock of the Junction (Vital) user API driven by its OpenAPI contract and verified by differential property tests against the Junction sandbox.",
   "license": "MIT",
   "type": "module",