Create google API mock server

[tyler-dane]

Summary

Replace the current issue body with a concrete request for a narrow, typed Google mock service that supports Compass development and cross-process integration flows. Frame it as a complement to the existing Jest mocks, not a replacement, and explicitly recommend a phased implementation so the first version stays small.

Feature Description

Create a typed Google mock service that can run as a separate Node process and emulate the subset of Google OAuth and Google Calendar behavior that Compass actually uses today.

This is for local development, integration testing, and preview/cloud environments where we want realistic Google-like behavior without depending on live Google credentials, quota, webhooks, or network stability.

Why This Is Needed

Compass already has good in-process Jest mocks for backend tests, but those mocks do not cover the full cross-process development path:

• backend auth and sync flows that currently talk to Google libraries directly
• webhook-driven Google Calendar notifications
• websocket updates triggered by Google-originated changes
• local and preview environments where we want deterministic Google behavior without real Google access

We need a single mockable integration target for those flows.

Scope

Build only the Google surface area Compass currently uses.

OAuth/auth behavior:

• mock enough identity and token behavior for sign-in, reconnect, and access-token refresh flows
• support deterministic success and failure responses such as revoked/invalid grant

Calendar behavior:

• events.get
• events.list
• events.instances
• events.insert
• events.update
• events.patch
• events.delete
• events.watch
• calendarList.list
• calendarList.watch
• channels.stop

Webhook behavior:

• provide a deterministic way to trigger Compass's Google notification endpoint with Google-shaped headers/data so incremental sync can be exercised locally without real Google push delivery

State behavior:

• keep mock state in memory for v1
• allow seed/reset of calendars, events, watches, sync tokens, and user auth state
• use the existing backend Google test fixtures/mocks as a source of behavior and sample data where helpful

Non-Goals

• full Google API parity
• persistent storage in v1
• replacing the existing Jest/unit-test mocks
• building a generic Google emulator for other projects
• emulating every OAuth edge case beyond what Compass currently needs

Recommended Approach

Use a phased implementation.

Phase 1:

• introduce a thin Google integration boundary in Compass so auth/sync code does not depend directly on live Google clients everywhere
• define the typed subset contract Compass needs

Phase 2:

• implement an in-memory mock engine for that contract
• wrap it in a small separate-process HTTP service for dev/integration use

Phase 3:

• add failure-mode controls and seed/reset/notification trigger endpoints
• document local usage and env wiring

This keeps the first version focused and avoids trying to clone all of Google up front.

Public Interfaces / Config To Add

Expected additions:

• an environment switch to choose live Google vs mock Google in non-production environments
• a typed contract for the Google operations Compass uses
• mock-only endpoints for seed/reset/triggering notifications

Acceptance Criteria

• Compass backend can run against the mock provider without code changes to business logic
• local sign-in/reconnect flows can run against deterministic mock auth responses
• full import and incremental sync can be exercised without real Google
• watch creation and notification handling can be tested locally without ngrok/real Google delivery
• common failure modes already modeled in the repo can be reproduced, including:
  • invalid grant
  • missing refresh token
  • invalid sync token / full resync required
  • invalid value style errors
• documentation explains when to use the separate mock service vs the existing in-process Jest mocks

Test Plan

• Happy path: signup/signin/reconnect against mock auth
• Sync path: initial import, incremental sync, event create/update/delete, recurring-instance fetch
• Realtime path: watch create, notification trigger, websocket/client refresh behavior
• Failure path: revoked token, missing refresh token, invalid sync token, invalid value
• Isolation path: seed/reset state between runs so dev/test scenarios stay deterministic

Use Case

This'll help development by allowing us to test against realistic, strongly-typed data from Google in local and cloud environments....without running into rate limit or environment issues. As long as the mocks match the Google API contracts, we can depend on our clone without actually reaching out to the live resources