feat(sandbox): export VERIFY_TOKEN from sandbox env (AIT-179)

[ord669]

Summary

• sandbox env now writes VERIFY_TOKEN (GET-handshake echo value, distinct from WEBHOOK_HMAC_SECRET) for WhatsApp and Instagram sessions — sandbox webhook set now verifies against a starter-kit server configured via sandbox env --write .env.
• Session parser requires verifyToken on the wire; older backends surface MALFORMED_SANDBOX_SESSION.

Rollout

Release AFTER hookmyapp/hookmyapp#97 is deployed (backend must emit verifyToken first).

Test plan

• 937/937 tests green, build clean
• Manual: sandbox env --write .env + starter-kit v3 + sandbox webhook set end to end on staging

Summary by CodeRabbit

• New Features

  • sandbox env now includes VERIFY_TOKEN for WhatsApp and Instagram sessions in dotenv and JSON output.
  • sandbox webhook set now verifies the configured webhook URL using the session’s verification token.

• Bug Fixes

  • Sandbox sessions missing a verification token are now reported as malformed.

• Documentation

  • Updated environment variable examples and webhook verification guidance.

[coderabbitai]

📝 Walkthrough

Walkthrough

Sandbox sessions now require verifyToken. sandbox env emits VERIFY_TOKEN for WhatsApp and Instagram sessions, and documentation describes its use by the webhook verification handshake. Tests and fixtures were updated for the required session field.

Changes

Sandbox verification token

Layer / File(s)	Summary
Require verifyToken in sandbox sessions src/api/sandbox-session.ts, src/api/__tests__/sandbox-session.test.ts	The shared session type and parser require a non-empty verifyToken, with malformed-session errors for missing values.
Emit VERIFY_TOKEN in sandbox environments src/commands/sandbox/env.ts, src/commands/sandbox/__tests__/env.test.ts, README.md, CHANGELOG.md	WhatsApp and Instagram dotenv and JSON output include VERIFY_TOKEN; documentation describes its distinct webhook verification role.
Update downstream sandbox fixtures src/**/__tests__/*	Sandbox command, listener, wizard, login, picker, send, logs, status, stop, and webhook fixtures include verifyToken.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• hookmyapp/cli#11: Directly overlaps the handling of VERIFY_TOKEN in sandbox environment output, tests, and documentation.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: exporting VERIFY_TOKEN from sandbox env.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch ait-179-sandbox-verify-token

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

🧹 Nitpick comments (1)

src/api/__tests__/sandbox-session.test.ts (1)

16-16: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Add a regression test for missing verifyToken.

The fixture update covers only valid payloads. Add a case such as { ...validWa, verifyToken: '' } and assert the parser throws MALFORMED_SANDBOX_SESSION; this protects the new boundary contract from being accidentally relaxed.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/api/__tests__/sandbox-session.test.ts` at line 16, Add a regression case
in the sandbox session parser tests using the valid payload with an empty
verifyToken, and assert that parsing throws MALFORMED_SANDBOX_SESSION. Keep the
existing valid fixture tests unchanged and target the parser behavior exercised
by the surrounding sandbox-session tests.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@src/api/__tests__/sandbox-session.test.ts`:
- Line 16: Add a regression case in the sandbox session parser tests using the
valid payload with an empty verifyToken, and assert that parsing throws
MALFORMED_SANDBOX_SESSION. Keep the existing valid fixture tests unchanged and
target the parser behavior exercised by the surrounding sandbox-session tests.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: bd2c857b-0b5c-44b7-a746-ecf722c3022b

📥 Commits

Reviewing files that changed from the base of the PR and between 678cd4b and 0e12801.

📒 Files selected for processing (20)

• CHANGELOG.md
• README.md
• src/__tests__/sandbox-listen/picker.test.ts
• src/api/__tests__/sandbox-session.test.ts
• src/api/sandbox-session.ts
• src/auth/__tests__/login.test.ts
• src/commands/__tests__/sandbox-listen-banner.test.ts
• src/commands/__tests__/wizard.test.ts
• src/commands/sandbox-listen/__tests__/listen-positional.test.ts
• src/commands/sandbox/__tests__/env.test.ts
• src/commands/sandbox/__tests__/helpers.test.ts
• src/commands/sandbox/__tests__/logs-default-format.test.ts
• src/commands/sandbox/__tests__/logs.test.ts
• src/commands/sandbox/__tests__/picker.test.ts
• src/commands/sandbox/__tests__/send-positional.test.ts
• src/commands/sandbox/__tests__/send.test.ts
• src/commands/sandbox/__tests__/status.test.ts
• src/commands/sandbox/__tests__/stop.test.ts
• src/commands/sandbox/__tests__/webhook.test.ts
• src/commands/sandbox/env.ts