chore(bridge): add sandbox e2e test suite

[patoo0x]

Summary

ENG-274. Adds an opt-in sandbox end-to-end test suite for the Bridge integration.

What's Included

Test Suite (test/flash/bridge-sandbox-e2e/)

• Jest harness — config, setup with env gates, preflight checks, reusable helpers
• KYC + virtual account spec — bridgeInitiateKyc, webhook injection, bridgeCreateVirtualAccount
• External account spec — Plaid link URL generation, external-account webhook handling
• Deposit + withdrawal spec — deposit webhook persistence, withdrawal error paths, idempotency
• Cutover state spec — opt-in smoke (CUTOVER_TESTS=true)
• LN parity spec — opt-in smoke (LN_PARITY_TESTS=true)

Infrastructure

• Two npm scripts: test:bridge-sandbox-e2e and test:bridge-sandbox-e2e:ci
• Guarded by RUN_BRIDGE_SANDBOX_E2E=true + IBEX_ENVIRONMENT=sandbox
• Preflight source-code check verifies the Level 1 service guard

Service-Level Fix

• src/services/bridge/index.ts — checkAccountLevel() changed from level < 2 to level < 1 to match the GraphQL resolver gate (PR fix(bridge): lower account level requirement from level 2 to level > 0 #385)

Documentation Drift Cleanup

• Updated docs/bridge-integration/: Level 2→Level 1, Tron→ETH-USDT references
• Setup and test-running instructions live in test/flash/bridge-sandbox-e2e/README.md

How to Verify

See test/flash/bridge-sandbox-e2e/README.md for setup instructions.

Related

ENG-274

[linear]

ENG-274

[heyolaniran]

hello @islandbitcoin this branch is presenting some conflicts, can you take a look on them?

[islandbitcoin]

hello @islandbitcoin this branch is presenting some conflicts, can you take a look on them?

I made some updates, and now I'm able to run the test suite successfully with baseline settings.

I made a script that should help you set up the webhook locally using ngrok, check the updated dev/setup.sh code for details (using --webhook), and the updated README.md in the test/flash/bridge-sandbox-e2e folder.

IBEX_ENVIRONMENT=sandbox yarn test:bridge-sandbox-e2e:ci
yarn run v1.22.22
$ . ./.env && { [ ! -f ./.env.local ] || . ./.env.local; } && RUN_BRIDGE_SANDBOX_E2E=true LOGLEVEL=warn jest --config ./test/flash/bridge-sandbox-e2e/jest.config.js --bail --runInBand --verbose $TEST
{"level":50,"time":1780956936692,"pid":34912,"hostname":"MacMax","accountId":"~","error":{"name":"BridgeKycPendingError","level":"warn"},"msg":"Failed to auto-create virtual account after KYC approval"}
 PASS  test/flash/bridge-sandbox-e2e/kyc-virtual-account.spec.ts (5.729 s)
  Bridge KYC → Virtual Account
    KYC Initiation
      ✓ initiates KYC and returns a KYC link URL and TOS link (1471 ms)
    KYC Webhook Processing
      ✓ processes a KYC-approved webhook and marks account as approved (399 ms)
    Virtual Account Creation
      ○ skipped creates a virtual account after KYC approval
      ○ skipped virtual account is idempotent — calling twice returns same result

{"level":50,"time":1780956939930,"pid":34912,"hostname":"MacMax","accountId":"~","error":{"name":"BridgeKycPendingError","level":"warn"},"msg":"Failed to auto-create virtual account after KYC approval"}
 PASS  test/flash/bridge-sandbox-e2e/external-account.spec.ts
  Bridge External Account
    Plaid Link URL Generation
      ○ skipped generates a Plaid link URL when called
      ○ skipped link URL is different on each call (one-time use tokens)
    External Account Webhook Processing
      ✓ processes a valid external-account webhook and returns success (15 ms)
      ✓ returns already_processed for duplicate external-account webhooks (303 ms)
      ✓ rejects a webhook with missing customer_id

 PASS  test/flash/bridge-sandbox-e2e/deposit-withdrawal.spec.ts
  Bridge Deposit → Withdrawal
    Deposit Webhook Processing
      ✓ processes a valid deposit webhook and returns success (71 ms)
      ✓ persists a deposit log to the BridgeDeposits collection (49 ms)
      ✓ returns already_processed for duplicate deposit webhooks (159 ms)
      ✓ handles intermediate state transitions (not just payment_processed) (31 ms)
      ✓ rejects a deposit webhook with missing required fields (1 ms)
    Withdrawal Initiation
      ✓ rejects withdrawal when amount is below minimum (9 ms)
      ✓ rejects withdrawal when amount is invalid (non-numeric) (3 ms)
      ✓ rejects withdrawal when account has no Bridge customer ID (11 ms)

Test Suites: 2 skipped, 3 passed, 3 of 5 total
Tests:       7 skipped, 13 passed, 20 total
Snapshots:   0 total
Time:        14.964 s
Ran all test suites.

[islandbitcoin]

Rebased this PR onto the latest tmp/bridge-rebase-pr-ready after #395 merged.

New head: d5cb53e13
Base: a23c9fdee
GitHub reports mergeStateStatus: CLEAN.

MacMax verification:

TEST="test/flash/unit/dev/setup-bridge-webhooks.spec.ts test/flash/unit/services/frappe/models/BridgeTransferRequest.spec.ts --runInBand --forceExit" yarn test:unit
IBEX_ENVIRONMENT=sandbox yarn test:bridge-sandbox-e2e:ci
./node_modules/.bin/eslint --resolve-plugins-relative-to ./node_modules --no-ignore $(git diff --name-only origin/tmp/bridge-rebase-pr-ready...HEAD | rg '\.(ts|js)$')
git diff --check origin/tmp/bridge-rebase-pr-ready...HEAD

Results:

• Focused unit tests: 7/7 passed
• Bridge sandbox E2E CI: 3 suites passed, 2 skipped; 13 passed, 7 skipped
• ESLint on changed JS/TS files passed
• git diff --check passed
• GitHub checks: none reported for this branch

[Copilot]

Pull request overview

Adds an opt-in Bridge sandbox end-to-end Jest suite (ENG-274) that exercises Bridge GraphQL mutations and webhook handlers against a real sandbox environment, plus local developer tooling to (re)configure Bridge sandbox webhooks via ngrok. Also aligns the Bridge service-level account-level guard to match the GraphQL resolver gate, and updates integration docs to remove Level-2/Tron drift.

Changes:

• Introduces test/flash/bridge-sandbox-e2e/ Jest harness + specs (KYC, virtual account, external account, deposit webhook/idempotency, withdrawal error paths, optional cutover + LN parity smokes) guarded by env flags.
• Adds a Node-based dev/setup-bridge-webhooks.js helper (with unit tests) and wires dev/setup.sh --webhook|--dev to recreate Bridge sandbox webhooks and write local overrides.
• Updates Bridge service guard (level < 2 → level < 1), plus Frappe audit datetime serialization and Bridge docs drift cleanup.

Reviewed changes

Copilot reviewed 26 out of 28 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
test/flash/unit/services/frappe/models/BridgeTransferRequest.spec.ts	Adds coverage for Frappe datetime serialization format.
test/flash/unit/dev/setup-bridge-webhooks.spec.ts	Unit tests for webhook setup helper (definitions, ngrok URL parsing, YAML merge, reconcile behavior).
test/flash/bridge-sandbox-e2e/README.md	Runbook for the opt-in sandbox E2E suite and required env/config.
test/flash/bridge-sandbox-e2e/preflight.ts	Source-based preflight to validate service-level account guard configuration.
test/flash/bridge-sandbox-e2e/ln-parity.spec.ts	Optional LN parity smoke spec (guarded by LN_PARITY_TESTS=true).
test/flash/bridge-sandbox-e2e/kyc-virtual-account.spec.ts	KYC initiation + injected webhook + optional virtual account creation flow.
test/flash/bridge-sandbox-e2e/jest.setup.ts	Suite gating (RUN_BRIDGE_SANDBOX_E2E, IBEX_ENVIRONMENT=sandbox), Mongo/Redis lifecycle, preflight call.
test/flash/bridge-sandbox-e2e/jest.config.js	Jest config scoped to sandbox E2E suite.
test/flash/bridge-sandbox-e2e/helpers/http-utils.ts	Minimal mock req/res for Express handler injection.
test/flash/bridge-sandbox-e2e/helpers.ts	Shared helpers: schema-executed GraphQL operations, user creation, webhook injection, ERPNext/Mongo lookups.
test/flash/bridge-sandbox-e2e/external-account.spec.ts	External account Plaid link URL (optional) + injected webhook/idempotency assertions.
test/flash/bridge-sandbox-e2e/deposit-withdrawal.spec.ts	Deposit webhook injection + persistence/idempotency + withdrawal error-path assertions.
test/flash/bridge-sandbox-e2e/cutover-state.spec.ts	Optional cutover state query smoke (guarded by CUTOVER_TESTS=true).
test/flash/bridge-sandbox-e2e/config-overrides.yaml	Sandbox-only config overrides used by the suite.
src/services/frappe/models/BridgeTransferRequest.ts	Formats first_seen_at / last_seen_at into Frappe-accepted datetime strings.
src/services/bridge/index.ts	Lowers service-level account gate to Level 1+ and adds warn logging; minor formatting cleanups.
package.json	Adds test:bridge-sandbox-e2e and test:bridge-sandbox-e2e:ci scripts.
docs/plans/2026-06-08-bridge-webhook-setup.md	Plan doc for webhook setup helper + dev/setup.sh wiring.
docs/plans/2026-06-04-eng-274-bridge-sandbox-e2e.md	Detailed ENG-274 implementation plan and suite design/verification notes.
docs/bridge-integration/WEBHOOKS.md	Updates deposit narrative away from Tron-specific wording.
docs/bridge-integration/FLOWS.md	Updates flow diagram/steps away from Tron and Level-2 assumptions.
docs/bridge-integration/ARCHITECTURE.md	Updates architecture description (Ethereum USDT, Level 1+).
docs/bridge-integration/API.md	Updates account-level requirement and error table text.
dev/setup.sh	Adds --dev / --webhook options to run webhook setup path.
dev/setup-bridge-webhooks.js	Implements ngrok + Bridge Webhook API orchestration and dev-overrides YAML merge.
dev/erpnext/backup.sh	Hardens backup script (pipefail, docker compose exec/cp, paths).
.gitignore	Ignores planning scratch markdown files.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[islandbitcoin]

Updated the branch with the backup/doc cleanup requested:

• Refreshed dev/erpnext/backups/20260608_113333-frontend-database.sql.gz from the current MacMax local Frappe frontend site.
• Removed the older tracked backup dev/erpnext/backups/clean-snapshot.sql.gz.
• Removed plan-only docs:
  • docs/plans/2026-06-04-eng-274-bridge-sandbox-e2e.md
  • docs/plans/2026-06-08-bridge-webhook-setup.md
• Kept setup/testing instructions in test/flash/bridge-sandbox-e2e/README.md and updated the preflight error pointer accordingly.
• Updated the PR body so it no longer links to the removed plan doc.

Verification on MacMax:

• gzip -t dev/erpnext/backups/20260608_113333-frontend-database.sql.gz ✅
• git diff --check ✅
• TEST="test/flash/unit/dev/setup-bridge-webhooks.spec.ts test/flash/unit/services/frappe/models/BridgeTransferRequest.spec.ts --runInBand --forceExit" yarn test:unit ✅ 7/7 passed
• IBEX_ENVIRONMENT=sandbox yarn test:bridge-sandbox-e2e:ci ✅ 3 suites passed, 2 optional suites skipped; 13 passed, 7 skipped
• yarn eslint --resolve-plugins-relative-to ./node_modules --no-eslintrc -c .eslintrc.json test/flash/bridge-sandbox-e2e/preflight.ts ✅