@whooshbang/contract-mock 2.4.0 → 2.5.0

package/CHANGELOG.md

@@ -5,6 +5,13 @@ recorded here.
 
 ## Unreleased
 
+## 2.5.0
+
+- Accept the published project configuration scopes while retaining organization and tenant boundaries (FXO-3028).
+- Accept developer-friendly message and question shorthands, optional idempotency keys, inferred types and setup defaults from contracts 2.6.0.
+- Create active webhook endpoints without the retired echo handshake, and expose credential-scoped flat endpoint routes.
+- Preserve explicit request forms, replay semantics, consent evidence and optimistic group updates.
+
 ## 2.4.0
 
 - Use contracts 2.5.0 and serve the billing promotion routes, including the approved-price refusal for credit packs (FXO-2994).

package/README.md

@@ -1,10 +1,10 @@
 # `@whooshbang/contract-mock`
 
 Deterministic, in-memory WhooshBang V1 mock for local contract tests.
-It implements the WhooshBang-owned release candidate without a cloud
+It implements the published WhooshBang contract without a cloud
 organization, network service, database, or production provider.
 
-Run the current release candidate directly from the public npm registry:
+Run the current release directly from the public npm registry:
 
 ```sh
 npx @whooshbang/contract-mock --port 8787
@@ -31,7 +31,7 @@ const response = await mock.fetch(
 );
 ```
 
-Install contracts, SDK and mock from the same published candidate batch.
+Install compatible published contracts, SDK and mock versions.
 The tenant rename has no old-route or old-field aliases.
 
 The mock also executes the organization-scoped administration contract. Use
@@ -42,50 +42,33 @@ The mock also executes the organization-scoped administration contract. Use
 
 ## Billing consumer tests
 
-The mock executes the public wallet, recurring Checkout, billing portal,
-automatic top-up settings/card setup, project slot and attribution routes. Organization administrators may use a
-human session; OAuth grants also need explicit `billing:read` or
-`billing:write`. Project, organization API and machine credentials cannot
-perform financial operations. Attribution uses the organization-level
-`projects:read` and `projects:write` scopes, with administrator membership for
-changes. The MCP tools retain their own scope and action-confirmation checks.
-
-Each account starts with the once-only $2 starter credit and one project slot.
-The fixture project already occupies that slot. Multi-project consumer tests
-must purchase extra slots through recurring Checkout or release the old slot
-with `assignBillingProjectSlots` before creating its replacement. Old projects
-retain their data and recorded test access; new live sends require an active
-slot. The default recurring catalog contains the $5 attribution and project
-add-ons. Team/Agency prices and allowances are not invented: pass synthetic
-offers through `billing.offers` when a consumer test needs a base plan.
-
-Wallet purchases use the approved $5/$10/$25/$50/$100 packs and
-$5/$10/$30/$65/$150 total core credit. Purchased and bonus funds remain
-separate. One accepted live notification debits $0.003 for core delivery;
-shared email adds $0.001 from purchased or starter credit. Paid allowances are
-used first. Tests, provider retries, later failures and answers do not create
-extra charges. Payment replay cannot fund the same Checkout twice.
-
-These are synthetic payments. Creating Checkout returns a local fixture URL;
-reconciliation applies the fixture's payment outcome, not a query parameter
-or caller-supplied `paid` flag. No Stripe request, card charge or webhook proof
-occurs. Set `billing.checkoutOutcome` to a callback returning `paid`, `unpaid`
-or `expired` to exercise recovery. `billing.accounts` may seed exact decimal
-balances for boundary tests. State resets with `control.reset()`.
-
-Automatic top-up starts disabled and requires a confirmed pack, threshold and
-gross monthly cap covering that pack. The mock's card setup is synthetic:
-`billing.autoTopUpSetupOutcome` returns `ready`, `unpaid` or `expired`. It models
-owned setup recovery and rejects stale completion after settings change; it
-does not run a bank charge or a scheduled automatic-purchase engine. Saving a
-card does not grant delivery credit. Actual automatic payment capture, pending
-reservations and gross monthly cap enforcement are tested against the owned
-storage and Stripe SDK boundaries.
+The mock implements saved-card setup, credit purchases, subscription changes,
+automatic top-up settings, project slots and attribution. Use a synthetic human
+session for organization administration; OAuth grants also need `billing:read`
+or `billing:write`. Project and machine credentials cannot perform financial
+operations.
+
+Each organization starts with $2 of welcome credit and one project slot. The fixture
+project already occupies that slot. Assign slots with `assignBillingProjectSlots`
+when testing multiple projects. Test access remains available without a live slot.
+The default recurring catalog contains the $5 attribution and project add-ons.
+Pass synthetic `billing.offers` when a test needs Team or Agency allowances.
+
+Wallet purchases use the $5/$10/$25/$50/$100 packs, granting
+$5/$10/$30/$65/$150 total credit. Purchased and bonus funds stay separate. One
+accepted live message costs $0.003 for core delivery; shared email adds $0.001
+from purchased or welcome credit. Paid allowances are used first. Test sends,
+provider retries, later delivery failures and answers add no charges.
+
+These are synthetic payments. `billing.cardOutcome` returns `ready`, `open` or
+`expired`; `billing.chargeOutcome` returns `paid`, `declined` or `requires_action`.
+No Stripe request or real card charge occurs. Seed decimal balances with
+`billing.accounts` for boundary tests. `control.reset()` clears state.
 
 ```ts
 const mock = createWhooshBangContractMock({
   billing: {
-    checkoutOutcome: () => "unpaid",
+    chargeOutcome: () => "declined",
     accounts: [{
       organizationId: "organization_synthetic",
       starterCreditUsd: "0.003000",
@@ -94,30 +77,18 @@ const mock = createWhooshBangContractMock({
 });
 ```
 
-Paid add-on reconciliation enables the server-enforced attribution preference
-until its paid boundary. Restoring the preference restores visible attribution;
-expiry preserves the preference but removes its paid effect. Paid wallet
-purchases or current recurring periods select 90-day content retention;
-starter-only accounts select seven days. The mock projects that entitlement;
-it does not simulate the storage purge jobs or prove real recipient rendering.
-
-Promotions (`GET /v1/billing/promotions`, `POST /v1/billing/promotions/redeem`)
-are modeled honestly but simply. Every mock offers one synthetic code,
-`MOCK-CREDIT`, worth $10 of message credit for 30 days; seed your own with
-`billing.promotionCodes`
-(`{ code, name, benefit, benefit_days }`, where `benefit` is a
-`message_credit`, `shared_emails` or `branding` grant; `[]` offers none).
-Codes ignore case, spaces, hyphens and underscores. Redemption adds a
-`source: "code"` grant to that organization only, updates the summary totals
-and `branding_removed_until`, and replays by `Idempotency-Key` (201, then 200).
-A second redemption of a code by the same organization and every unknown code
-get the same 404 `resource_not_found`; five refusals in a row answer 429
-`rate_limited` until `control.reset()`. Grants expire at their end time. The
-mock does not spend promotional credit on sends, apply discounts, or model
-operator-created offers.
-
-Each project has one webhook endpoint across its environments. Paused and
-unverified endpoints still occupy it; disabling one releases it. Only a
+Automatic top-up starts disabled. Enabling it requires a confirmed pack,
+threshold, saved card and monthly cap. Saving a card alone grants no credit.
+The mock does not run an automatic-purchase scheduler or prove bank settlement.
+
+Attribution preferences take effect while the paid entitlement is active.
+Expiry preserves the preference but restores branding. A paid wallet purchase
+or current recurring period selects 90-day content retention; welcome-credit-only
+accounts select seven days. The mock projects the entitlement without simulating
+storage purge jobs or proving recipient rendering.
+
+Each project has one webhook endpoint across its environments. Active and
+paused endpoints still occupy it; disabling one releases it. Only a
 terminal failed automatic cycle can receive the one included manual replay.
 `control.runPending()` executes that cycle using the same eight-attempt bound.
 The original cycle and manual recovery together cannot exceed 16 attempts.
@@ -133,7 +104,7 @@ values are local fixtures, not production credential material.
 It can also configure the project recipient experience, upload a bounded PNG
 logo, and manage sparse recipient-copy overrides. The mock normalizes the logo
 before storing it, atomically replaces the prior asset, projects its ID and the
-ten owner-voiced panel values into recipient sessions, and serves the PNG only
+ten customer-editable panel values into recipient sessions, and serves the PNG only
 to that session's exact configured origin. System-owned safety, refusal, pause,
 unavailable, and unsubscribe copy is rejected just as it is by the service.
 
@@ -157,8 +128,9 @@ customer-managed provider resource that still needs manual retirement.
 
 Project credentials also execute the customer-endpoint lifecycle under
 `/v1/projects/{project_id}/environments/{environment_id}/customer-endpoints`:
-create with a one-time secret reveal, verify, bounded-overlap rotation, pause,
-resume, disable, and attempt inspection. Environment-scoped paths need an
+create with a one-time secret reveal, signed diagnostic ping, bounded-overlap rotation, pause,
+resume, disable, and attempt inspection. Endpoints are active immediately; no challenge echo is needed.
+Flat `/v1/customer-endpoints` routes derive scope from a project credential. Environment-scoped paths need an
 environment identifier the bearer does not carry, so
 `CONTRACT_MOCK_FIXTURE_ENVIRONMENTS` publishes the synthetic project and
 environment identifiers the fixture credentials authenticate against. A path
@@ -166,7 +138,7 @@ naming another project or environment is refused as `resource_not_found`.
 
 The same credentials execute the Channel Connections surface under
 `/v1/projects/{project_id}/environments/{environment_id}/connection-providers`
-and `.../channel-connections`: read the catalogue of providers and the
+and `.../channel-connections`: read the catalog of providers and the
 WhooshBang-owned identities an environment may select, then create a
 connection in `pending`, read it, list it, rename or disable it under the
 `row_version` that was read, and archive it. Archiving is terminal, so a
@@ -174,7 +146,7 @@ second archive or an edit to an archived connection is refused. Credential
 material and every reference to one are absent from these responses, including
 for the shared identity WhooshBang operates.
 
-The catalogue presents hosted Slack first as
+The catalog presents hosted Slack first as
 `WhooshBang for Slack — Recommended`. Creating that arm returns a durable
 `authorization_setup`; fetching its mock authorization URL completes the
 provider browser round trip and returns to the Dashboard with the same
@@ -184,7 +156,7 @@ verification/delivery timestamps. `.../{connection_id}/reauthorize` repeats
 the flow on the exact connection, health verifies it, archive is repeat-safe,
 and purge is refused because the tenant does not own the platform installation.
 
-When the owner enables Slack in N17 and exactly one eligible Slack connection
+When Slack is enabled and exactly one eligible Slack connection
 is attached to the notifier, a recipient session offers Slack. Its provider
 handoff binds that exact connection; ambiguity or a lifecycle change fails
 closed. Environment-scoped agent sends may include `connection_id`, and the

package/dist/core.js

@@ -1,3 +1,6 @@
+import schema from "@whooshbang/contracts/schemas/whooshbang-v1.schema.json" with { type: "json" };
+const CUSTOMER_EVENT_TYPES = schema.$defs.CustomerEventType.enum;
+import { normalizeMessageEnvelope, normalizeCreateMessageRequest, } from "@whooshbang/contracts";
 import { resolveInteractionExpiry, resolveInteractionRequest, } from "@whooshbang/contracts";
 import { contractVersion, validateAssertEmailConsentRequest, validateBindingSummary, validateMessageListPage, validateMessageDeliveryHistory, validateMessageNotificationImage, validateInteractionTimeline, validateCustomerEventDeliveryHistory, validateCustomerEventDeliveryAttempt, validateDeliveryHolds, validateMachineClientOperationsList, validateRecipientCopyCatalogue, validateUpdateEmailSenderRequest, validateCreateConnectionTestRequest, validateConnectionTest, validateConnectionTestCollection, } from "@whooshbang/contracts";
 import { Hono } from "hono";
@@ -437,6 +440,8 @@ function codePointLength(value) {
     return Array.from(value).length;
 }
 const projectScopes = [
+    "projects:read",
+    "projects:write",
     "subscriptions:write",
     "subscriptions:read",
     "messages:write",
@@ -458,7 +463,7 @@ const organizationCredentialScopes = [
     ...projectScopes,
 ];
 /** Every scope an OAuth grant may carry: organization-level, then project-level. */
-const oauthScopes = [...organizationScopes, ...projectScopes];
+const oauthScopes = [...new Set([...organizationScopes, ...projectScopes])];
 /**
  * The synthetic project and environment identifiers the fixture project
  * credentials authenticate against.
@@ -1287,9 +1292,9 @@ function problem(code, status, diagnosticId, overrides = {}) {
             title: "Idempotency conflict",
         },
         idempotency_key_required: {
-            detail: "Provide an Idempotency-Key containing 8 to 255 visible ASCII characters.",
+            detail: "Idempotency-Key must be 8 to 255 visible ASCII characters.",
             retryable: false,
-            title: "Idempotency key required",
+            title: "Invalid idempotency key",
         },
         preferred_binding_unavailable: {
             detail: "The selected binding is unavailable; choose another active binding explicitly.",
@@ -2037,13 +2042,14 @@ function recordDiagnostic(state, identity, operation, details = {}) {
 function normalizeLinkRequest(request) {
     return {
         ...request,
+        channels: request.channels ?? ["telegram"],
         expires_in_seconds: request.expires_in_seconds ?? 43_200,
         notifier_id: request.notifier_id ?? "default",
     };
 }
 function normalizeMessageRequest(request) {
     return {
-        ...request,
+        ...normalizeCreateMessageRequest(request),
         notifier_id: request.notifier_id ?? "default",
     };
 }
@@ -2140,7 +2146,7 @@ function connectionBinding(state, credential, subscriberId, notifierId, connecti
 }
 function messageTemporalInputIsValid(request, acceptedAt) {
     const acceptedAtMilliseconds = Date.parse(acceptedAt);
-    const latestMilliseconds = acceptedAtMilliseconds + 24 * 60 * 60 * 1000;
+    const latestMilliseconds = 253_402_300_799_999;
     if (request.expires_at !== undefined) {
         const expiresAtMilliseconds = Date.parse(request.expires_at);
         if (expiresAtMilliseconds <= acceptedAtMilliseconds ||
@@ -2221,11 +2227,8 @@ function transitionMessage(record, state, options, nextState) {
     });
 }
 function requireIdempotency(request, state) {
-    const key = request.headers.get("idempotency-key");
-    if (key === null ||
-        key.length < 8 ||
-        key.length > 255 ||
-        !/^[\u0021-\u007e]+$/u.test(key)) {
+    const key = request.headers.get("idempotency-key") ?? crypto.randomUUID();
+    if (key.length < 8 || key.length > 255 || !/^[\u0021-\u007e]+$/u.test(key)) {
         return {
             response: problemResponse(problem("idempotency_key_required", 400, state.idGenerator("diagnostic"))),
         };
@@ -4566,11 +4569,22 @@ function addPublicRoutes(app, getState, options) {
             : parsed.value.consented_at);
         if (!Number.isFinite(consentedAt.getTime()) || consentedAt > new Date(now))
             return problemResponse(problem("request_invalid", 400, state.idGenerator("diagnostic")));
+        const candidates = (options.emailConsentAuthorities ?? []).filter((c) => c.organizationId === identity.credential.organizationId &&
+            c.projectId === identity.credential.projectId &&
+            c.environment === identity.credential.environment &&
+            c.mode === "customer_managed" &&
+            (parsed.value.connection_id === undefined ||
+                c.connectionId === parsed.value.connection_id));
+        const chosen = candidates.length === 1 ? candidates[0] : undefined;
+        if (!chosen)
+            return parsed.value.connection_id === undefined
+                ? requestInvalid(state)
+                : notFound(state);
         const request = {
             subscriber_id: parsed.value.subscriber_id,
-            notifier_id: parsed.value.notifier_id,
-            connection_id: parsed.value.connection_id,
-            domain_id: parsed.value.domain_id,
+            notifier_id: parsed.value.notifier_id ?? "default",
+            connection_id: parsed.value.connection_id ?? chosen.connectionId,
+            domain_id: parsed.value.domain_id ?? chosen.domainId,
             address: parsed.value.address,
             ...(service
                 ? {
@@ -5411,7 +5425,7 @@ function addPublicRoutes(app, getState, options) {
                 ? {}
                 : { description: parsed.value.description }),
             diagnostic_id: state.idGenerator("diagnostic"),
-            display_name: parsed.value.display_name,
+            display_name: parsed.value.display_name ?? parsed.value.key,
             environment: identity.credential.environment,
             id: state.idGenerator("subscriber_group"),
             key: parsed.value.key,
@@ -5471,7 +5485,8 @@ function addPublicRoutes(app, getState, options) {
         const parsed = await readJson(context.req.raw, validateUpdateSubscriberGroupRequest, state.idGenerator("diagnostic"));
         if ("response" in parsed)
             return parsed.response;
-        if (parsed.value.row_version !== record.group.row_version) {
+        if (parsed.value.row_version !== undefined &&
+            parsed.value.row_version !== record.group.row_version) {
             return problemResponse(problem("subscriber_group_conflict", 409, state.idGenerator("diagnostic")));
         }
         const description = parsed.value.description === null
@@ -5673,9 +5688,10 @@ function addPublicRoutes(app, getState, options) {
         const idempotency = requireIdempotency(context.req.raw, state);
         if ("response" in idempotency)
             return idempotency.response;
-        const parsed = await readJson(context.req.raw, validateCreateGroupBroadcastRequest, state.idGenerator("diagnostic"));
-        if ("response" in parsed)
-            return parsed.response;
+        const raw = await readJson(context.req.raw, validateCreateGroupBroadcastRequest, state.idGenerator("diagnostic"));
+        if ("response" in raw)
+            return raw.response;
+        const parsed = { value: normalizeMessageEnvelope(raw.value) };
         const now = state.now();
         const requestFingerprint = fingerprint(parsed.value);
         const replay = idempotentReplay(state, identity, "createGroupBroadcast", idempotency.key, requestFingerprint);
@@ -6023,7 +6039,50 @@ function addPublicRoutes(app, getState, options) {
         if ("response" in parsed) {
             return parsed.response;
         }
-        const normalized = normalizeLinkRequest(parsed.value);
+        const input = parsed.value;
+        if (input.channels?.[0] === "email" &&
+            identity.credential.environment === "test") {
+            return problemResponse(problem("request_invalid", 400, state.idGenerator("diagnostic"), {
+                field_errors: [
+                    {
+                        field: "/channels",
+                        code: "channel_requires_live",
+                        detail: "Email subscription links require a live environment. Use a live credential, or the test simulator to test delivery.",
+                    },
+                ],
+            }));
+        }
+        const available = [...state.channelConnections.values()].filter((record) => record.ownerOrganizationId === identity.credential.organizationId &&
+            record.connection.project_id === identity.credential.projectId &&
+            record.connection.environment === identity.credential.environment &&
+            (record.connection.status === "active" ||
+                record.connection.status === "degraded") &&
+            record.connection.installation?.status === "active");
+        const candidates = available.filter((record) => (input.connection_id === undefined ||
+            record.connection.id === input.connection_id) &&
+            (input.channels === undefined ||
+                record.connection.provider === input.channels[0]));
+        const project = state.projects.get(identity.credential.projectId);
+        const notifierId = input.notifier_id === undefined || input.notifier_id === "default"
+            ? project?.environments.find((env) => env.kind === identity.credential.environment)?.default_notifier.id
+            : input.notifier_id;
+        const defaultId = notifierId === undefined
+            ? undefined
+            : state.notifierDefaultConnections.get(notifierConnectionKey(identity.credential.projectId, identity.credential.environment, notifierId));
+        const chosen = candidates.find((record) => record.connection.id === defaultId) ??
+            (candidates.length === 1 ? candidates[0] : undefined);
+        if ((input.channels === undefined ||
+            (input.channels[0] === "slack" && input.connection_id === undefined)) &&
+            available.length > 0 &&
+            chosen === undefined)
+            return requestInvalid(state);
+        const normalized = normalizeLinkRequest(chosen === undefined
+            ? input
+            : {
+                ...input,
+                channels: [chosen.connection.provider],
+                connection_id: chosen.connection.id,
+            });
         const requestFingerprint = fingerprint(normalized);
         const replay = idempotentReplay(state, identity, "createSubscriptionLink", idempotency.key, requestFingerprint);
         if (replay !== undefined) {
@@ -6032,15 +6091,26 @@ function addPublicRoutes(app, getState, options) {
         const now = timestamp(options);
         const linkId = state.idGenerator("subscription_link");
         const authorizationCapability = await deterministicSubscriptionCapability(linkId);
-        const connection = {
-            display_name: "WhooshBang",
-            id: normalized.connection_id ?? "connection_mock_default_telegram",
-            identity: {
-                handle: "WhooshBangSyntheticBot",
-                provider: "telegram",
-            },
-            mode: "whooshbang_shared",
-        };
+        const connection = chosen === undefined
+            ? {
+                display_name: "WhooshBang",
+                id: normalized.connection_id ?? "connection_mock_default_telegram",
+                identity: {
+                    handle: "WhooshBangSyntheticBot",
+                    provider: "telegram",
+                },
+                mode: "whooshbang_shared",
+            }
+            : {
+                display_name: chosen.connection.display_name,
+                id: chosen.connection.id,
+                identity: {
+                    handle: chosen.connection.identity?.handle ??
+                        chosen.connection.display_name,
+                    provider: chosen.connection.provider,
+                },
+                mode: chosen.connection.mode,
+            };
         const link = {
             authorization_url: `https://t.me/WhooshBangSyntheticBot?start=${authorizationCapability}`,
             channels: normalized.channels,
@@ -6816,6 +6886,17 @@ function addPublicRoutes(app, getState, options) {
             storeIdempotentResponse(state, identity, "ackMachineEvent", idempotency.key, requestFingerprint, 200, response, eventId, `cursor:${previousCommitted ?? "none"}->${committedCursor ?? "none"}`);
         return validatedResponse(response, validateMachineEventAckResponse, 200, state, responseDiagnosticId);
     });
+    // Flat endpoints derive their exact authority from the project credential.
+    // Forward internally so validation, replay and tenant isolation stay identical.
+    app.use("/v1/customer-endpoints*", async (context) => {
+        const state = getState();
+        const identity = requireProjectScope(context.req.raw, state, context.req.method === "GET" ? "messages:read" : "messages:write");
+        if (isAuthFailure(identity))
+            return identity.response;
+        const url = new URL(context.req.raw.url);
+        url.pathname = `/v1/projects/${identity.credential.projectId}/environments/${credentialEnvironmentId(identity.credential)}${url.pathname.slice(3)}`;
+        return app.fetch(new Request(url, context.req.raw));
+    });
     const customerEndpointRoot = "/v1/projects/:projectId/environments/:environmentId/customer-endpoints";
     /**
      * Authenticates an environment-scoped customer-endpoint request.
@@ -7205,7 +7286,7 @@ function addPublicRoutes(app, getState, options) {
         // Sorting matches the service's documented normalization, so the same
         // event-type set in a different order replays instead of conflicting.
         const eventTypes = [
-            ...request.event_types,
+            ...(request.event_types ?? CUSTOMER_EVENT_TYPES),
         ].sort();
         const normalized = {
             event_types: eventTypes,
@@ -7240,9 +7321,11 @@ function addPublicRoutes(app, getState, options) {
             id: state.idGenerator("customer_endpoint"),
             project_id: identity.credential.projectId,
             secret_version: 1,
-            status: "unverified",
+            status: "active",
             updated_at: now,
-            verification_status: "pending",
+            verification_status: "verified",
+            verification_attempted_at: now,
+            verified_at: now,
         };
         const result = {
             endpoint,
@@ -7343,7 +7426,7 @@ function addPublicRoutes(app, getState, options) {
         const version = record.endpoint.secret_version + 1;
         record.previousSecret = record.secret;
         record.rotationOverlapEndsAt =
-            nowMilliseconds + request.overlap_seconds * 1_000;
+            nowMilliseconds + (request.overlap_seconds ?? 86400) * 1_000;
         record.secret = syntheticEndpointSecret(record.sequence, version);
         record.endpoint = {
             ...record.endpoint,