feat(e2e): API upgrade integration — all domains migrated to @gusto/embedded-api-v-2025-11-15

.claude/commands/create-hook.md

@@ -202,7 +202,7 @@ import { useMemo } from 'react'
 import { useForm } from 'react-hook-form'
 import type { UseFormProps } from 'react-hook-form'
 import { zodResolver } from '@hookform/resolvers/zod'
-import type { {Entity} } from '@gusto/embedded-api/models/components/{entity}'
+import type { {Entity} } from '@gusto/embedded-api-v-2025-11-15/models/components/{entity}'
 // React-query hooks for the GET / mutations this hook drives
 import {
   create{Domain}Schema,

.claude/commands/starttechspec.md

@@ -298,7 +298,7 @@ git commit -m "docs: initialize {feature_name} tech spec"
 
 ### Step 5: Run Zod Validation Tests
 
-Validate the `@gusto/embedded-api` Zod schemas against real API responses to catch bugs early.
+Validate the `@gusto/embedded-api-v-2025-11-15` Zod schemas against real API responses to catch bugs early.
 
 **Why this matters:**
 The embedded-api SDK uses Zod schemas to validate API responses. If the schema doesn't match reality, the SDK throws `ResponseValidationError`. Finding these mismatches during spec phase prevents runtime failures later.
@@ -357,7 +357,7 @@ In the spec repo, create a quick test harness:
 ```bash
 cd ~/workspace/{slug}-spec/zod-validation-test
 npm init -y
-npm install @gusto/embedded-api tsx typescript
+npm install @gusto/embedded-api-v-2025-11-15 tsx typescript
 ```
 
 **Step 5d: Test via the embedded-api React Query hooks**
@@ -373,9 +373,9 @@ The SDK provides React Query hooks that validate responses with Zod schemas. If
 
 ```tsx
 import { ApiProvider } from './ApiProvider'
-import { useEmployeesListSuspense } from '@gusto/embedded-api/react-query/employeesList'
-import { usePayrollsListSuspense } from '@gusto/embedded-api/react-query/payrollsList'
-import { usePayrollsCreateOffCycleMutation } from '@gusto/embedded-api/react-query/payrollsCreateOffCycle'
+import { useEmployeesListSuspense } from '@gusto/embedded-api-v-2025-11-15/react-query/employeesList'
+import { usePayrollsListSuspense } from '@gusto/embedded-api-v-2025-11-15/react-query/payrollsList'
+import { usePayrollsCreateOffCycleMutation } from '@gusto/embedded-api-v-2025-11-15/react-query/payrollsCreateOffCycle'
 
 function TestHarness({ companyId }: { companyId: string }) {
   // Each hook call triggers Zod validation on the response
@@ -399,7 +399,7 @@ function TestHarness({ companyId }: { companyId: string }) {
 **Test the hooks you'll use in this feature:**
 
 - List through your API inventory
-- Call each React Query hook from `@gusto/embedded-api/react-query/*`
+- Call each React Query hook from `@gusto/embedded-api-v-2025-11-15/react-query/*`
 - Record which hooks pass/fail Zod validation
 
 **Step 5e: Document findings**

.claude/hooks-implementation.md

@@ -194,7 +194,7 @@ export function JobTitleField(props: JobTitleFieldProps) {
 
 ### Data Fetching
 
-- Use `@gusto/embedded-api/react-query/*` hooks for all API calls
+- Use `@gusto/embedded-api-v-2025-11-15/react-query/*` hooks for all API calls
 - Gate dependent queries with `enabled: !!dependency`
 - Use `composeErrorHandler` to build the `errorHandling` bag (see Error Handling section below)
 
@@ -308,7 +308,7 @@ const errorHandling = composeErrorHandler(queries, { submitError, setSubmitError
 
 You can pass **nested SDK hook results** (objects with `errorHandling`) plus extra React Query results in the first array — see `composeErrorHandler` in `src/partner-hook-utils/composeErrorHandler.ts`.
 
-**Multi-form screens:** `composeSubmitHandler` coordinates validation + ordered submits **and** returns `{ handleSubmit, errorHandling }` aggregated across the forms it receives. Partners that want to combine in extra `@gusto/embedded-api` queries or screen-level submit state feed the result into **`composeErrorHandler([submitResult, ...extraQueries], optionalScreenSubmit)`**.
+**Multi-form screens:** `composeSubmitHandler` coordinates validation + ordered submits **and** returns `{ handleSubmit, errorHandling }` aggregated across the forms it receives. Partners that want to combine in extra `@gusto/embedded-api-v-2025-11-15` queries or screen-level submit state feed the result into **`composeErrorHandler([submitResult, ...extraQueries], optionalScreenSubmit)`**.
 
 `composeErrorHandler` returns `HookErrorHandling`:
 
@@ -407,7 +407,7 @@ Reference `gws-flows/app/frontend/react_sdk/CustomCompensationForm.tsx` as the r
 
 Infrastructure utilities like `buildFormSchema`, `useDeriveFieldsMetadata`, `deriveFieldsMetadata`, `withOptions`, `FormFieldsMetadataProvider`, `composeErrorHandler`, `collectErrors`, generic `*HookField` components, and base types like `HookFormInternals`, `BaseFormHookReady` are used by the SDK to build hooks — not by partners. Only promote to the public barrel if a partner use case demands it.
 
-Do NOT re-export `@gusto/embedded-api` entity types directly — partners derive them from field prop generics (e.g. `NonNullable<FlsaStatusFieldProps['getOptionLabel']>` infers the entity type).
+Do NOT re-export `@gusto/embedded-api-v-2025-11-15` entity types directly — partners derive them from field prop generics (e.g. `NonNullable<FlsaStatusFieldProps['getOptionLabel']>` infers the entity type).
 
 ## 7. Validation Parity with Stable Components
 

.github/workflows/ci.yaml

@@ -207,13 +207,46 @@ jobs:
       - name: Test with coverage
         run: npm run test:ci
 
-  # E2E job: Run Playwright e2e tests (parallel with other checks)
-  e2e:
+  # Scenarios job: Validate scenario JSON against schema and run scenario unit tests.
+  # E2E jobs depend on this so a broken scenario fails fast (cheap) before Playwright runs (expensive).
+  scenarios:
     needs: setup
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
 
+      - uses: actions/setup-node@v6
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: Restore node_modules cache
+        uses: actions/cache/restore@v5
+        with:
+          path: node_modules
+          key: ${{ needs.setup.outputs.cache-key }}
+
+      - name: Validate scenario JSON
+        run: npm run scenarios:validate
+
+      - name: Run scenario unit tests
+        run: npm run test:scenarios
+
+  # E2E setup: Provision demo companies once on flows.gusto-demo.com and
+  # publish the resulting state (flow token, primary company, dismissal
+  # company, terminated employee, etc.) as an artifact. Each e2e shard
+  # downloads this artifact and skips provisioning thanks to
+  # globalSetup's idempotency check.
+  #
+  # Without this job, every shard's globalSetup re-provisions ~2 demo
+  # companies; with 9 shards that meant ~18 concurrent demo creations on
+  # the demo backend, which caused 200s flow-token lookup timeouts and
+  # cascading shard failures. Provisioning once removes the bottleneck.
+  e2e-setup:
+    needs: [setup, scenarios]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
       - uses: actions/setup-node@v6
         with:
           node-version-file: '.nvmrc'
@@ -241,24 +274,58 @@ jobs:
         if: steps.playwright-cache.outputs.cache-hit == 'true'
         run: npx playwright install-deps chromium
 
-      - name: Initialize MSW
-        run: npx msw init e2e/public --save=false
-
-      - name: Run e2e tests
-        run: npm run test:e2e
+      - name: Provision demo companies
+        env:
+          E2E_LOCAL: 'true'
+        run: npm run e2e:setup
 
-      - name: Upload test results
-        if: ${{ !cancelled() }}
+      - name: Upload e2e state
         uses: actions/upload-artifact@v6
         with:
-          name: playwright-report
-          path: playwright-report/
-          retention-days: 7
-
-  # E2E Demo job: Run Playwright e2e tests against the live demo environment
-  e2e-demo:
-    needs: setup
+          name: e2e-state
+          path: e2e/.e2e-state.json
+          # File starts with a dot (.e2e-state.json); upload-artifact@v6
+          # excludes hidden files by default, so opt in explicitly.
+          include-hidden-files: true
+          retention-days: 1
+          if-no-files-found: error
+
+  # E2E job: Run Playwright e2e tests against the live demo environment.
+  # This is the sole Playwright gate. A previous MSW-mode e2e job was removed
+  # because its mock fixtures could not keep pace with real demo backend
+  # behavior, and the duplicate run added CI minutes for shallow coverage
+  # already provided by Storybook + unit tests. This job exercises the
+  # actual API contract, scenario provisioning, and state machine terminal
+  # states. The local npm script is still named test:e2e:demo to reflect
+  # what it points at.
+  #
+  # Sharded by domain so each domain runs in parallel and one domain's
+  # failure doesn't block feedback on the others. The `domain` filter is a
+  # Playwright path-substring match, so it picks up both flat specs at
+  # `e2e/tests/<domain>*.spec.ts` and nested specs at
+  # `e2e/tests/<domain>/**/*.spec.ts`.
+  e2e:
+    needs: [setup, scenarios, e2e-setup]
     runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      # Throttle concurrent shards to avoid overwhelming flows.gusto-demo.com
+      # with per-test scenario provisioning. globalSetup is now shared via
+      # the e2e-setup job's artifact, but scenario-backed specs still create
+      # additional demo companies on demand. 2 concurrent shards keeps that
+      # load manageable.
+      max-parallel: 2
+      matrix:
+        domain:
+          - company
+          - contractor
+          - dismissal
+          - employee
+          - payroll
+          - termination
+          - time-off
+          - legacy
+    name: e2e (${{ matrix.domain }})
     steps:
       - uses: actions/checkout@v6
 
@@ -289,13 +356,27 @@ jobs:
         if: steps.playwright-cache.outputs.cache-hit == 'true'
         run: npx playwright install-deps chromium
 
-      - name: Run e2e tests against demo environment
-        run: npm run test:e2e:demo
+      - name: Download e2e state
+        uses: actions/download-artifact@v6
+        with:
+          name: e2e-state
+          path: e2e/
+
+      - name: Run e2e tests
+        run: npm run test:e2e:demo -- --pass-with-no-tests ${{ matrix.domain }}
 
-      - name: Upload demo test results
+      - name: Upload test results
         if: ${{ !cancelled() }}
         uses: actions/upload-artifact@v6
         with:
-          name: playwright-report-demo
+          name: playwright-report-${{ matrix.domain }}
           path: playwright-report/
           retention-days: 7
+
+      - name: Upload scenario reports
+        if: ${{ !cancelled() }}
+        uses: actions/upload-artifact@v6
+        with:
+          name: e2e-scenario-report-${{ matrix.domain }}
+          path: e2e/reports/
+          retention-days: 7

.gitignore

@@ -196,9 +196,11 @@ test-results/
 
 # E2E local testing
 e2e/.e2e-state.json
+e2e/.scenario-cache.json
 e2e/local.config.env
 e2e/recordings/
 e2e-recordings/
+e2e/reports/
 
 # Playwright MCP artifacts
 .playwright-mcp/

AGENTS.md

@@ -76,16 +76,16 @@ src/components/
 └── Flow/ # Multi-step flow orchestration
 ```
 
-### API Layer (`@gusto/embedded-api`)
+### API Layer (`@gusto/embedded-api-v-2025-11-15`)
 
-All API calls go through `@gusto/embedded-api` with React Query hooks and Zod schema validation.
+All API calls go through `@gusto/embedded-api-v-2025-11-15` with React Query hooks and Zod schema validation.
 
 Import paths:
 
-- `@gusto/embedded-api/react-query/<operation>` — React Query hooks
-- `@gusto/embedded-api/models/components/<name>` — Entity types
-- `@gusto/embedded-api/models/operations/<name>` — Request/response types
-- `@gusto/embedded-api/models/errors/<name>` — Error types
+- `@gusto/embedded-api-v-2025-11-15/react-query/<operation>` — React Query hooks
+- `@gusto/embedded-api-v-2025-11-15/models/components/<name>` — Entity types
+- `@gusto/embedded-api-v-2025-11-15/models/operations/<name>` — Request/response types
+- `@gusto/embedded-api-v-2025-11-15/models/errors/<name>` — Error types
 
 Hook naming: `use<Resource><Action>Suspense` (queries), `use<Resource><Action>Mutation` (mutations)
 
@@ -101,7 +101,7 @@ All user-facing text uses i18next. Run `npm run i18n:generate` after changing tr
 
 ### Partner hooks (`composeErrorHandler` / `composeSubmitHandler`)
 
-Exported headless hooks build `errorHandling` with **`composeErrorHandler`** (not a React hook). For multi-form screens, **`composeSubmitHandler`** coordinates validation + ordered submits and returns `{ handleSubmit, errorHandling }` aggregated across those forms. The result plugs back into `composeErrorHandler` when partners need extra `@gusto/embedded-api` queries or screen-level submit state in the same error surface — see [docs/hooks/hooks.md](docs/hooks/hooks.md).
+Exported headless hooks build `errorHandling` with **`composeErrorHandler`** (not a React hook). For multi-form screens, **`composeSubmitHandler`** coordinates validation + ordered submits and returns `{ handleSubmit, errorHandling }` aggregated across those forms. The result plugs back into `composeErrorHandler` when partners need extra `@gusto/embedded-api-v-2025-11-15` queries or screen-level submit state in the same error surface — see [docs/hooks/hooks.md](docs/hooks/hooks.md).
 
 ## PR and Commit Conventions
 

CLAUDE.md

@@ -76,16 +76,16 @@ src/components/
 └── Flow/           # Multi-step flow orchestration
 ```
 
-### API Layer (`@gusto/embedded-api`)
+### API Layer (`@gusto/embedded-api-v-2025-11-15`)
 
-All API calls go through `@gusto/embedded-api` with React Query hooks and Zod schema validation.
+All API calls go through `@gusto/embedded-api-v-2025-11-15` with React Query hooks and Zod schema validation.
 
 Import paths:
 
-- `@gusto/embedded-api/react-query/<operation>` — React Query hooks
-- `@gusto/embedded-api/models/components/<name>` — Entity types
-- `@gusto/embedded-api/models/operations/<name>` — Request/response types
-- `@gusto/embedded-api/models/errors/<name>` — Error types
+- `@gusto/embedded-api-v-2025-11-15/react-query/<operation>` — React Query hooks
+- `@gusto/embedded-api-v-2025-11-15/models/components/<name>` — Entity types
+- `@gusto/embedded-api-v-2025-11-15/models/operations/<name>` — Request/response types
+- `@gusto/embedded-api-v-2025-11-15/models/errors/<name>` — Error types
 
 Hook naming: `use<Resource><Action>Suspense` (queries), `use<Resource><Action>Mutation` (mutations)
 
@@ -101,7 +101,7 @@ All user-facing text uses i18next. Run `npm run i18n:generate` after changing tr
 
 ### Partner hooks (`composeErrorHandler` / `composeSubmitHandler`)
 
-Exported headless hooks build `errorHandling` with **`composeErrorHandler`** (not a React hook). For multi-form screens, **`composeSubmitHandler`** coordinates validation + ordered submits and returns `{ handleSubmit, errorHandling }` aggregated across those forms. The result plugs back into `composeErrorHandler` when partners need extra `@gusto/embedded-api` queries or screen-level submit state in the same error surface — see [docs/hooks/hooks.md](docs/hooks/hooks.md).
+Exported headless hooks build `errorHandling` with **`composeErrorHandler`** (not a React hook). For multi-form screens, **`composeSubmitHandler`** coordinates validation + ordered submits and returns `{ handleSubmit, errorHandling }` aggregated across those forms. The result plugs back into `composeErrorHandler` when partners need extra `@gusto/embedded-api-v-2025-11-15` queries or screen-level submit state in the same error surface — see [docs/hooks/hooks.md](docs/hooks/hooks.md).
 
 ## PR and Commit Conventions
 

build/deriveEndpointInventory.ts

@@ -7,8 +7,8 @@ const __filename = fileURLToPath(import.meta.url)
 const __dirname = dirname(__filename)
 
 const ROOT = join(__dirname, '..')
-const FUNCS_DIR = join(ROOT, 'node_modules/@gusto/embedded-api/src/funcs')
-const OPS_DIR = join(ROOT, 'node_modules/@gusto/embedded-api/src/models/operations')
+const FUNCS_DIR = join(ROOT, 'node_modules/@gusto/embedded-api-v-2025-11-15/src/funcs')
+const OPS_DIR = join(ROOT, 'node_modules/@gusto/embedded-api-v-2025-11-15/src/models/operations')
 const COMPONENTS_DIR = join(ROOT, 'src/components')
 const JSON_OUTPUT_PATH = join(ROOT, 'docs/reference/endpoint-inventory.json')
 const MD_OUTPUT_PATH = join(ROOT, 'docs/reference/endpoint-reference.md')
@@ -33,7 +33,7 @@ interface FlowEntry {
   variables: string[]
 }
 
-// --- AST-based extraction from @gusto/embedded-api ---
+// --- AST-based extraction from @gusto/embedded-api-v-2025-11-15 ---
 
 function createApiProject(): Project {
   return new Project({
@@ -175,13 +175,14 @@ function walkDir(dir: string): string[] {
   return results
 }
 
-// --- Extract @gusto/embedded-api imports from component files ---
+// --- Extract @gusto/embedded-api-v-2025-11-15 imports from component files ---
 
 function extractApiImports(filePaths: string[]): Set<string> {
   const funcNames = new Set<string>()
 
-  const hookImportPattern = /from\s+['"]@gusto\/embedded-api\/react-query\/([^'"]+)['"]/g
-  const funcImportPattern = /from\s+['"]@gusto\/embedded-api\/funcs\/([^'"]+)['"]/g
+  const hookImportPattern =
+    /from\s+['"]@gusto\/embedded-api-v-2025-11-15\/react-query\/([^'"]+)['"]/g
+  const funcImportPattern = /from\s+['"]@gusto\/embedded-api-v-2025-11-15\/funcs\/([^'"]+)['"]/g
 
   for (const filePath of filePaths) {
     const content = readFileSync(filePath, 'utf-8')
@@ -626,7 +627,7 @@ function generateMarkdown(inventory: Inventory): string {
   return lines.join('\n')
 }
 
-// --- Validate all inventory endpoints exist in @gusto/embedded-api ---
+// --- Validate all inventory endpoints exist in @gusto/embedded-api-v-2025-11-15 ---
 
 function validateEndpoints(
   inventory: { blocks: Record<string, BlockEntry> },
@@ -648,7 +649,9 @@ function validateEndpoints(
   }
 
   if (invalid.length > 0) {
-    console.error('WARNING: Some inventory endpoints were not found in @gusto/embedded-api:')
+    console.error(
+      'WARNING: Some inventory endpoints were not found in @gusto/embedded-api-v-2025-11-15:',
+    )
     for (const ep of invalid) console.error(`  ${ep}`)
     console.error('')
   }
@@ -708,7 +711,7 @@ function verify() {
   console.error('This can happen when:')
   console.error('  - A component added or removed an API hook/function import')
   console.error('  - A flow added or removed a block component')
-  console.error('  - The @gusto/embedded-api package was updated')
+  console.error('  - The @gusto/embedded-api-v-2025-11-15 package was updated')
   console.error('  - The pre-commit hook was bypassed (--no-verify)')
   console.error('')
   console.error('Fix: run "npm run endpoints:derive" and commit the updated files.')