Skip to content

FE-2217 test(account): pin the generated billing contracts the SDK decodes - #17829

Merged
dante01yoon merged 8 commits into
mainfrom
jaewon/fe-2217-billing-contract-tests
Sep 17, 2026
Merged

dante01yoon merged 8 commits into
mainfrom
jaewon/fe-2217-billing-contract-tests

Conversation

@dante01yoon

@dante01yoon dante01yoon commented Sep 16, 2026 •

Copy link
Copy Markdown
Collaborator

Linear FE-2217.

Why

The billing SDK core decodes generated zod schemas from @comfyorg/ingest-types/zod, which a bot regenerates from the cloud OpenAPI whenever the backend moves. Today a regen that renames a field, drops it, or widens an enum the reducer switches on surfaces either as a typecheck error somewhere deep in the core or, worse, as a runtime MALFORMED_RESPONSE in front of a customer mid-payment. Nothing states, in one readable place, which fields of which schema the SDK actually depends on.

This adds a contract test per generated schema the core decodes. Each pins the fields the core reads and the enum members it branches on, at the type level and at parse time, so a regen that changes one of them fails a named block whose name says what broke — the parse rows under vitest run, the expectTypeOf exhaustiveness pins under the package typecheck. A failure here means the backend contract moved: fix the SDK, not the test.

These are pins, not behaviour: reader and command behaviour stays covered by the existing credits.test.ts, status.test.ts, capabilities.test.ts, operationState.test.ts, subscriptionCommands.test.ts, and topup.test.ts.

How

New folder packages/account-core/src/core/billing/contracts/, one file per endpoint contract, picked up by the package's existing src/core/**/*.{test,spec}.ts include. Each file holds a canonical fixture typed as z.input<typeof schema> built by a small typed builder (no casts), parses it with safeParse, pins the output type with expectTypeOf, and runs one it.for row per enum value the SDK branches on.

Schema Module that decodes it Fields pinned
zBillingBalanceResponse credits.ts (read by topup.ts, balanceWatch.ts) amount_micros as a number; the four optional breakdown micros
zBillingStatusResponse status.ts (read by operationLifecycle.ts, subscriptionCommands.ts, presentation.ts) billing_rail (3), pending_billing_op_id, pending_billing_op_type (2), action_url, payment_intent_client_secret, is_active, subscription_tier (7), subscription_status (3)
zBillingCapabilitiesResponse, zBillingCapabilities, zBillingCapabilityScope, zBillingCapabilityRolloutDefaults capabilities.ts (which parses the three named pieces, not the response schema) the five response keys the reader recomposes into its own schema, reading expires_at as a plain string and revision as a number; all seven capability booleans; resolved_for.user_id / workspace_id; expires_at; revision as an int64 bounded to the JavaScript-safe range the reader reads it back as a number over; denied_reasons absent from the contract, which is why capabilityDenials.ts decodes it off the raw body
zBillingOpStatusResponse operationLifecycle.ts, operationState.ts id; status (the 4 the reducer handles); authentication_state (the 5 it reads or assigns); decline_reason (8, incl. the generic fallback); recovery_action (4); phase (3); action_url; payment_intent_client_secret; retryable optional
zErrorResponse billingErrorBody.ts code as an open string the commands match against their own closed set; a body without message yields no code
zSubscribeRequest, zSubscribeResponse subscriptionCommands.ts confirmation_token, saved_payment_method_id (pm_ prefix), idempotency_key, confirm_reactivation; billing_op_id, status (3), optional payment_method_url
zResubscribeResponse subscriptionCommands.ts billing_op_id regardless of status (2)
zCancelSubscriptionResponse2 subscriptionCommands.ts billing_op_id on both members of the response union
zPaymentPortalResponse subscriptionCommands.ts url required, and not https-checked by the schema, which is why the command re-checks it
zPreviewSubscribeRequest, zPreviewSubscribeResponse subscriptionCommands.ts plan_slug required and the three optional request fields; allowed, is_immediate, effective_at, transition_type (4), the int64 money fields and their JSON-number coercion, discounts, requires_reactivation_confirmation
zCreateTopupRequest, zCreateTopupResponse topup.ts amount_cents minimum and its int64 coercion of the JSON number the command validates but does not send; idempotency_key; billing_op_id regardless of status (3)
zCreateTopupCheckoutRequest, zCreateTopupCheckoutResponse topup.ts the amount bounds and the return_url URL rule, pinned by the issue path the command reads to tell the two apart; checkout_url required, session_id optional

capabilityDenials.ts is the one billing module that decodes without a generated schema — deliberately, since a strict enum parse would lose the whole capability set the first time the server names an unfamiliar policy branch. Its absence from the generated contract is pinned in billingCapabilities.contract.test.ts.

AS-IS / TO-BE

No UI. A regenerated zBillingOpStatusResponse that adds a fifth status:

  • AS-IS: the new value falls through terminalFromStatus into the pending branch; the operation polls until its budget runs out and reports timed_out.
  • TO-BE: billingOpStatus.contract.test.ts fails on the regen PR, naming the reducer as what needs updating. Two gates, and which one fires depends on the pin: the enum rows (accepts the %s status) fail under vitest run, while the exhaustiveness pin at billingOpStatus.contract.test.ts:36 sits at module scope and fails as a TS2344 under the package typecheck, not in the test run.

Testing

  • cd packages/account-core && vitest run src/core/billing/contracts — 12 files, 90 tests, all passing. The type pins are not among them: they sit at module scope and fail pnpm --filter @comfyorg/account-core typecheck instead, because nothing here runs vitest --typecheck.
  • cd packages/account-core && tsc --noEmit — clean
  • pnpm typecheck — passing; verified the type pins bite by injecting a spurious enum member and watching expectTypeOf fail with TS2344
  • pnpm lint, pnpm format, pnpm knip — passing
  • fallow audit --changed-since origin/main — no issues in the 13 changed files

Where this sits in the plan

Billing SDK track FE-2210 (implementation plan V2). Hybrid model: top-up in-app, subscription management / invoices / payment methods on the hosted billing app.

Phase Item Ticket Status
1-2 Session core, transport, readers FE-2211/2212/2213 merged
3 Operation lifecycle, commands, eight-state projection FE-2227/2214/2223 merged (#17655)
4 @comfyorg/account-ui composables + CheckoutSteps FE-2215 merged (#17662, #17663)
5 slice 1 Top-up through the SDK behind billing_sdk_topup_enabled FE-2216 merged (#17665)
rollout C hosted_billing_destination server flag read by the host FE-2218 merged (#17716)
rollout C hostedDestination port on the lifecycle, value on operation state FE-2210/2218 open (#17783, carries slice 2a)
7 prep Scope-source port + credentialed transport (BFF / cookie hosts) FE-2218 merged (#17782)
7 prep @comfyorg/account → @comfyorg/account-core rename FE-2218 merged (#17851) — this PR sits on it
7 prep billing-contract route builder + return_to registry FE-2218 merged (#17795)
3A-3 Workshop adapter over createHostedTopupCheckout FE-2214 merged (#17793)
8 core previewSubscribe command FE-2331 merged (#17797)
8 core Plans + saved payment-methods readers FE-2331 merged (#17798)
8 ui account-ui composables (usePlans, usePaymentMethods, usePreviewSubscribe) FE-2331 merged (#17798)
7 billing-web own-origin session, sign-in, SDK composition FE-2218 merged (#17798)
7 billing-web unit tests in CI (ci-billing-web-unit.yaml) FE-2218 merged (#17827, #17844)
7 ingest CORS + top-up return hosts for billing.comfy.org and its previews (Comfy-Org/cloud) FE-2218 merged (Comfy-Org/cloud#9512)
8 ui billing-web /v1 entry routing + subscription / payment-method surfaces FE-2331 merged (#17798)
7 Publish readiness: dist build, files allowlist, pack smoke test FE-2218 merged (#17882)
7 Package release workflows + versioning ADR FE-2218 open (#17881)
7 First publish (private off), Platform install, billing-web live top-up FE-2218 todo
6 Contract tests per generated schema (package layer) FE-2217 this PR
6 Live E2E per flow × consumer + evidence table FE-2217 todo (needs staging flags)
5 slice 2 Subscription flows through the SDK FE-2216 open (#17856, #17860)
follow-up One needsCustomerAttention predicate (from the #17665 review) FE-2216 merged (#17792)
follow-up Opaque BillingServerCode (from the #17656 review) FE-2227 merged (#17794)
follow-up useCredits clears on SUPERSEDED (from the #17799 review) FE-2215 merged (#17824)
follow-up credits / status / capabilities readers fence a late failure as SUPERSEDED (from the #17798 review) FE-2331 open (#17828)
flowchart LR
  P3["Phase 3 core lifecycle (merged)"]
  P4["Phase 4 account-ui (merged)"]
  P5["Phase 5 slice 1 top-up flag (merged)"]
  FC["PR 17716 hosted_billing_destination flag (merged)"]
  HD["PR 17783 hostedDestination port"]
  SS["PR 17782 scope-source port + credentialed transport"]
  RN["account-core rename"]
  RB["billing-contract route builder + return_to"]
  WS["Workshop adapter"]
  P8PV["previewSubscribe command"]
  P8RD["plans + payment-methods readers"]
  P8["account-ui hosted composables"]
  BWS["billing-web session + sign-in"]
  BWV["billing-web /v1 surfaces"]
  CORS["cloud PR 9512 ingest CORS + return hosts"]
  PUB["npm publish account-core / billing-contract"]
  P7["Phase 7 host proof: Platform + billing-web live"]
  P6C["Phase 6 contract tests"]
  P6["Phase 6 live evidence"]
  S2["Phase 5 slice 2 subscription"]
  FU9["customer-attention predicate"]
  FU11["opaque BillingServerCode"]
  FU12["useCredits clears on SUPERSEDED"]
  FU13["reader late-failure fence"]
  P3 --> HD
  FC --> HD
  HD --> RB
  P3 --> SS
  SS --> P7
  RB --> P7
  P3 --> RN
  RN --> PUB
  RB --> PUB
  PUB --> P7
  P3 --> P8PV
  P3 --> P8RD
  P8PV --> P8
  P8RD --> P8
  P4 --> P8
  P8 --> S2
  P8 --> BWS
  BWS --> BWV
  RB --> BWV
  BWV --> P7
  CORS --> P7
  P5 --> P6
  P3 --> P6C
  P5 --> WS
  P5 --> FU9
  P3 --> FU11
  P4 --> FU12
  P3 --> FU13
  style P3 fill:#d4edda,stroke:#155724
  style P4 fill:#d4edda,stroke:#155724
  style P5 fill:#d4edda,stroke:#155724
  style FC fill:#d4edda,stroke:#155724
  style SS fill:#d4edda,stroke:#155724
  style RB fill:#d4edda,stroke:#155724
  style WS fill:#d4edda,stroke:#155724
  style FU9 fill:#d4edda,stroke:#155724
  style P8PV fill:#d4edda,stroke:#155724
  style P6C stroke:#0366d6,stroke-width:4px
Loading

Loading
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

risk:high PR risk grade (advisory shadow check; grader-owned)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants