@whooshbang/contract-mock 1.0.0-rc.16

package/dist/types.d.ts

@@ -0,0 +1,203 @@
+import type { AccountProjection, ApiCredential, CustomerEndpoint, Environment, InteractionEvent, MachineClient, MachineCredential, MachineEventAckDisposition, Message, WhooshBangEventV1ContractDocument, Project, SubscriptionLink } from "@whooshbang/contracts";
+export type ContractMockScenarioName = "nominal" | "repeated-idempotent-message" | "idempotency-conflict" | "unbound-subscriber" | "retryable-provider-failure" | "terminal-provider-rejection" | "ambiguous-provider-outcome" | "cancellation-before-send" | "cancellation-too-late" | "interaction-confirm" | "interaction-select" | "interaction-input" | "interaction-duplicate" | "interaction-stale" | "interaction-expired" | "interaction-unauthorized" | "machine-event-replay" | "machine-cursor-contiguous" | "machine-poison-quarantine" | "cross-machine-rejection" | "cross-machine-answer-origin" | "signed-webhook-success" | "signed-webhook-retry" | "signed-webhook-terminal" | "rate-limited";
+export type ProjectScope = "subscriptions:write" | "subscriptions:read" | "messages:write" | "messages:read" | "machine-clients:write" | "machine-clients:read" | "capabilities:read";
+/**
+ * The account-level vocabulary, which only an OAuth grant or a human session
+ * can hold. A project credential lives inside one project environment and can
+ * never create or enumerate its siblings.
+ */
+export type AccountScope = "projects:write" | "projects:read";
+export type OAuthScope = AccountScope | ProjectScope;
+export type MachineScope = "machine-messages:write" | "machine-messages:read" | "machine-events:read" | "machine-events:ack";
+interface CredentialBase {
+    readonly accountId: string;
+    readonly environment: Environment;
+    readonly projectId: string;
+    readonly token: string;
+}
+export interface ContractMockHumanCredential {
+    readonly accountId: string;
+    readonly kind: "human";
+    readonly role: AccountProjection["membership"]["role"];
+    readonly token: string;
+}
+export interface ContractMockProjectCredential extends CredentialBase {
+    readonly credentialId?: ApiCredential["id"];
+    /**
+     * Environment identifier used in environment-scoped paths.
+     *
+     * Omission derives a deterministic identifier from the project and
+     * environment kind, which keeps existing fixture credentials valid.
+     */
+    readonly environmentId?: string;
+    readonly kind: "project";
+    readonly scopes: readonly ProjectScope[];
+}
+/**
+ * An account-scoped OAuth grant.
+ *
+ * It names an account and its scopes but never a project: a request names the
+ * project and environment in its path, and the mock checks that pair against
+ * this account exactly as the service checks it against the granting person's
+ * membership.
+ */
+export interface ContractMockGrantCredential {
+    readonly accountId: string;
+    readonly kind: "grant";
+    readonly scopes: readonly OAuthScope[];
+    readonly token: string;
+}
+export interface ContractMockMachineCredential extends CredentialBase {
+    readonly bindingId: string;
+    readonly credentialId?: string;
+    readonly kind: "machine";
+    readonly machineClientId: string;
+    readonly machineId: string;
+    readonly notifierId: string;
+    readonly scopes: readonly MachineScope[];
+    readonly status: "active" | "revoked";
+    readonly subscriberId: string;
+}
+export type ContractMockCredential = ContractMockHumanCredential | ContractMockGrantCredential | ContractMockProjectCredential | ContractMockMachineCredential;
+export interface ContractMockClock {
+    now(): Date;
+}
+export type ContractMockIdKind = "account" | "api_credential" | "binding" | "customer_endpoint" | "customer_endpoint_attempt" | "diagnostic" | "environment" | "event" | "interaction" | "machine_client" | "message" | "notifier" | "project" | "request" | "subscription_link";
+export type ContractMockIdGenerator = (kind: ContractMockIdKind) => string;
+export type ProviderOutcome = {
+    readonly kind: "accepted";
+} | {
+    readonly kind: "retryable";
+    readonly retryAfterSeconds?: number;
+} | {
+    readonly kind: "terminal";
+} | {
+    readonly kind: "ambiguous";
+};
+export interface ProviderAttemptContext {
+    readonly attempt: number;
+    readonly messageId: string;
+    readonly scenario: ContractMockScenarioName;
+}
+export type ProviderOutcomeScript = (context: ProviderAttemptContext) => ProviderOutcome | Promise<ProviderOutcome>;
+export interface MachineEventSeed {
+    readonly event: InteractionEvent;
+    readonly machineClientId: string;
+    readonly quarantinable?: boolean;
+    readonly signatureValid?: boolean;
+    readonly streamIdentityValid?: boolean;
+}
+export type MachineEventDeliveryScript = () => readonly MachineEventSeed[];
+export type WebhookReceiver = (request: Request) => Promise<Response>;
+export type InteractionPollWait = (delayMilliseconds: number, signal: AbortSignal) => Promise<void>;
+export interface WhooshBangContractMockOptions {
+    readonly clock?: ContractMockClock;
+    readonly credentials?: readonly ContractMockCredential[];
+    readonly currentSigningSecret?: string;
+    readonly idGenerator?: ContractMockIdGenerator;
+    readonly interactionPollWait?: InteractionPollWait;
+    readonly machineEventDeliveryScript?: MachineEventDeliveryScript;
+    readonly previousSigningSecret?: string;
+    readonly providerOutcomeScript?: ProviderOutcomeScript;
+    readonly scenario?: ContractMockScenarioName;
+    readonly webhookReceiver?: WebhookReceiver;
+}
+export interface ProviderAttemptSnapshot {
+    readonly attempt: number;
+    readonly at: string;
+    readonly messageId: string;
+    readonly outcome: ProviderOutcome["kind"];
+}
+export interface LogicalOperationSnapshot {
+    readonly idempotencyResult: "new" | "replayed" | "conflict";
+    readonly operation: string;
+    readonly resourceId?: string;
+}
+export interface LogicalEventSnapshot {
+    readonly eventId: string;
+    readonly resourceId?: string;
+    readonly type: WhooshBangEventV1ContractDocument["type"];
+}
+export interface CursorCommitSnapshot {
+    readonly committedCursor: string | null;
+    readonly disposition: MachineEventAckDisposition;
+    readonly eventId: string;
+    readonly machineClientId: string;
+}
+export interface WebhookAttemptSnapshot {
+    readonly action: "accepted" | "retry" | "terminal";
+    readonly attempt: number;
+    readonly eventId: string;
+    readonly reason: string;
+    readonly retryAfterSeconds?: number;
+    readonly signatureCount: number;
+    readonly status?: number;
+    readonly timestamp: number;
+}
+export interface DiagnosticSnapshot {
+    readonly environment?: Environment;
+    readonly idempotencyResult?: "new" | "replayed" | "conflict";
+    readonly operation: string;
+    readonly projectId?: string;
+    readonly requestId: string;
+    readonly resourceId?: string;
+    readonly scenario: ContractMockScenarioName;
+    readonly stateTransition?: string;
+}
+export interface ContractMockSnapshot {
+    readonly accounts: readonly AccountProjection[];
+    readonly apiCredentials: readonly ApiCredential[];
+    readonly contractVersion: "1.0.0-rc.13";
+    readonly cursorCommits: readonly CursorCommitSnapshot[];
+    readonly customerEndpoints: readonly CustomerEndpoint[];
+    readonly diagnostics: readonly DiagnosticSnapshot[];
+    readonly links: readonly SubscriptionLink[];
+    readonly logicalEvents: readonly LogicalEventSnapshot[];
+    readonly logicalOperations: readonly LogicalOperationSnapshot[];
+    readonly machineClients: readonly MachineClient[];
+    readonly machineCredentials: readonly MachineCredential[];
+    readonly messages: readonly Message[];
+    readonly providerAttempts: readonly ProviderAttemptSnapshot[];
+    readonly projects: readonly Project[];
+    readonly scenario: ContractMockScenarioName;
+    readonly scenarioVersion: "contract-mock-scenarios.v1";
+    readonly webhookAttempts: readonly WebhookAttemptSnapshot[];
+}
+export type InteractionControlOutcome = "authorized" | "duplicate" | "stale" | "expired" | "unauthorized";
+export interface InteractionControlInput {
+    readonly messageId: string;
+    readonly outcome?: InteractionControlOutcome;
+    readonly response: {
+        readonly type: "confirm";
+        readonly value: boolean;
+    } | {
+        readonly type: "select";
+        readonly value: string;
+    } | {
+        readonly type: "input";
+        readonly value: string;
+    };
+}
+export interface InteractionControlResult {
+    readonly eventCreated: boolean;
+    readonly outcome: InteractionControlOutcome;
+}
+export interface ContractMockControl {
+    enqueueMachineEvent(seed: MachineEventSeed): void;
+    reset(scenario?: ContractMockScenarioName): Promise<void>;
+    runPending(): Promise<void>;
+    setProviderOutcomes(outcomes: readonly ProviderOutcome[]): void;
+    setWebhookResponses(responses: readonly (number | "network_failure")[]): void;
+    submitInteraction(input: InteractionControlInput): Promise<InteractionControlResult>;
+}
+export interface WhooshBangContractMock {
+    readonly control: ContractMockControl;
+    fetch(request: Request): Promise<Response>;
+    inspect(): ContractMockSnapshot;
+}
+export interface ContractMockScenarioDescriptor {
+    readonly description: string;
+    readonly name: ContractMockScenarioName;
+    readonly version: "contract-mock-scenarios.v1";
+}
+export {};

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/worker.d.ts

@@ -0,0 +1,9 @@
+import type { WhooshBangContractMockOptions } from "./types.js";
+export interface WhooshBangContractMockWorker {
+    fetch(request: Request): Promise<Response>;
+}
+/**
+ * Fetch-only compatibility entry point. It does not import the Node listener
+ * or the token-authenticated HTTP control router and never exposes control.
+ */
+export declare function createWhooshBangContractMockWorker(options?: WhooshBangContractMockOptions): WhooshBangContractMockWorker;

package/dist/worker.js

@@ -0,0 +1,10 @@
+import { createWhooshBangContractMockCore } from "./core.js";
+/**
+ * Fetch-only compatibility entry point. It does not import the Node listener
+ * or the token-authenticated HTTP control router and never exposes control.
+ */
+export function createWhooshBangContractMockWorker(options = {}) {
+    const mock = createWhooshBangContractMockCore(options);
+    return { fetch: (request) => mock.fetch(request) };
+}
+//# sourceMappingURL=worker.js.map

package/dist/worker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.js","sourceRoot":"","sources":["../src/worker.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gCAAgC,EAAE,MAAM,WAAW,CAAC;AAQ7D;;;GAGG;AACH,MAAM,UAAU,kCAAkC,CAChD,UAAyC,EAAE;IAE3C,MAAM,IAAI,GAAG,gCAAgC,CAAC,OAAO,CAAC,CAAC;IACvD,OAAO,EAAE,KAAK,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;AACrD,CAAC"}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@whooshbang/contract-mock",
+  "version": "1.0.0-rc.16",
+  "description": "Deterministic local executable mock for WhooshBang V1",
+  "private": false,
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "homepage": "https://whooshbang.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/flowxo/whooshbang.git",
+    "directory": "apps/contract-mock"
+  },
+  "keywords": [
+    "whooshbang",
+    "notifications",
+    "telegram",
+    "mock",
+    "cli"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "tag": "next"
+  },
+  "bin": {
+    "whooshbang-contract-mock": "dist/cli.js"
+  },
+  "files": [
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md",
+    "dist",
+    "scenarios"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./worker": {
+      "types": "./dist/worker.d.ts",
+      "import": "./dist/worker.js",
+      "default": "./dist/worker.js"
+    },
+    "./scenarios/v1/manifest.json": "./scenarios/v1/manifest.json",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsx scripts/clean-dist.ts && tsc -p tsconfig.build.json",
+    "lint": "eslint scripts src test --max-warnings=0",
+    "test": "vitest run --no-file-parallelism",
+    "type-check": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@whooshbang/contracts": "1.0.0-rc.13",
+    "hono": "4.12.34"
+  },
+  "devDependencies": {
+    "@whooshbang/mcp": "1.0.0-rc.4",
+    "@whooshbang/sdk": "1.0.0-rc.14"
+  },
+  "engines": {
+    "node": ">=22.13.0 <23"
+  }
+}

package/scenarios/v1/manifest.json

@@ -0,0 +1,31 @@
+{
+  "schema": "contract-mock-scenarios.v1",
+  "contract_version": "1.0.0-rc.13",
+  "scenarios": [
+    "nominal",
+    "repeated-idempotent-message",
+    "idempotency-conflict",
+    "unbound-subscriber",
+    "retryable-provider-failure",
+    "terminal-provider-rejection",
+    "ambiguous-provider-outcome",
+    "cancellation-before-send",
+    "cancellation-too-late",
+    "interaction-confirm",
+    "interaction-select",
+    "interaction-input",
+    "interaction-duplicate",
+    "interaction-stale",
+    "interaction-expired",
+    "interaction-unauthorized",
+    "machine-event-replay",
+    "machine-cursor-contiguous",
+    "machine-poison-quarantine",
+    "cross-machine-rejection",
+    "cross-machine-answer-origin",
+    "signed-webhook-success",
+    "signed-webhook-retry",
+    "signed-webhook-terminal",
+    "rate-limited"
+  ]
+}