@tyroneross/build-loop 0.30.3

package/skills/authentication/references/google-calendar-sync.md

@@ -0,0 +1,278 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Google Calendar API v3 — Sync Patterns
+
+Syncing events between your app and a user's Google Calendar. Covers scopes, incremental sync via `syncToken`, refresh-token storage, and the 410-recovery dance.
+
+## Scopes — Pick the Narrowest
+
+| Scope | What you can do | Sensitive? |
+|-------|-----------------|------------|
+| `calendar.readonly` | List events, list calendars | Yes (verification required) |
+| `calendar.events.readonly` | List events (any calendar you specify) | Yes |
+| `calendar.events` | Create/update/delete events | Yes |
+| `calendar.app.created` | Only events your app created | **No** (unverified OK) |
+| `calendar` | Full access (including settings) | Yes |
+
+**Use `calendar.app.created` if possible** — it only lets your app touch events it created, requires no Google verification, and is the least privacy-invasive. The catch: you can't read events the user created manually. For two-way sync of user events you need `calendar.events`.
+
+## Adding Calendar Scope to Existing OAuth
+
+```
+Google Cloud Console → APIs & Services → OAuth consent screen → EDIT APP
+  → Scopes → ADD OR REMOVE SCOPES
+  → Search for "calendar" → select scope → UPDATE → SAVE
+```
+
+If your app was already published, adding a sensitive scope triggers re-verification. Plan for ~1 week.
+
+## Store the Refresh Token (Critical)
+
+Google only returns a `refresh_token` on the **first** consent, unless you pass `prompt=consent&access_type=offline`. Always request both:
+
+```
+https://accounts.google.com/o/oauth2/v2/auth?
+  client_id=...&
+  redirect_uri=...&
+  response_type=code&
+  scope=openid%20email%20profile%20https%3A//www.googleapis.com/auth/calendar.events&
+  access_type=offline&   ← required for refresh_token
+  prompt=consent&        ← force refresh_token even on re-consent
+  state=...
+```
+
+The refresh_token is **long-lived** (months). The access_token expires in 1 hour. Store both:
+
+```sql
+CREATE TABLE user_calendars (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  user_id UUID REFERENCES auth.users(id) NOT NULL,
+  google_email VARCHAR(255) NOT NULL,
+  google_calendar_id VARCHAR(255) NOT NULL,  -- 'primary' or specific ID
+  access_token TEXT NOT NULL,                 -- expires in ~1h
+  refresh_token TEXT NOT NULL,                -- long-lived
+  token_expires_at TIMESTAMPTZ NOT NULL,
+  sync_token TEXT,                            -- Google's nextSyncToken for incremental sync
+  last_synced_at TIMESTAMPTZ,
+  created_at TIMESTAMPTZ DEFAULT NOW(),
+  UNIQUE (user_id, google_calendar_id)
+);
+```
+
+**Encrypt refresh_token at rest.** Use column-level encryption (pgcrypto) or your hosting provider's secret manager.
+
+## Refresh an Access Token
+
+```ts
+async function refreshAccessToken(refreshToken: string) {
+  const res = await fetch('https://oauth2.googleapis.com/token', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body: new URLSearchParams({
+      client_id: process.env.GOOGLE_CLIENT_ID!,
+      client_secret: process.env.GOOGLE_CLIENT_SECRET!,
+      refresh_token: refreshToken,
+      grant_type: 'refresh_token',
+    }),
+  })
+
+  if (!res.ok) {
+    const err = await res.json()
+    if (err.error === 'invalid_grant') {
+      // User revoked access or refresh_token is dead
+      throw new CalendarReauthRequiredError()
+    }
+    throw new Error(`Token refresh failed: ${JSON.stringify(err)}`)
+  }
+
+  return res.json() as Promise<{ access_token: string; expires_in: number }>
+}
+```
+
+**`invalid_grant` handling**: Mark the user_calendar row as needing re-auth and show a UI prompt. Don't retry silently — they've revoked access.
+
+## Incremental Sync with syncToken
+
+This is the whole point — don't fetch all events every time.
+
+### First sync (full)
+
+```ts
+async function fullSync(calendarId: string, accessToken: string) {
+  let pageToken: string | undefined
+  let nextSyncToken: string | undefined
+  const events: any[] = []
+
+  do {
+    const url = new URL(`https://www.googleapis.com/calendar/v3/calendars/${encodeURIComponent(calendarId)}/events`)
+    url.searchParams.set('singleEvents', 'true')        // expand recurring
+    url.searchParams.set('showDeleted', 'false')
+    url.searchParams.set('maxResults', '250')
+    if (pageToken) url.searchParams.set('pageToken', pageToken)
+
+    const res = await fetch(url, {
+      headers: { Authorization: `Bearer ${accessToken}` },
+    })
+
+    if (!res.ok) throw new Error(`Calendar list failed: ${res.status}`)
+    const data = await res.json()
+
+    events.push(...(data.items ?? []))
+    pageToken = data.nextPageToken
+    nextSyncToken = data.nextSyncToken  // only on the LAST page
+  } while (pageToken)
+
+  // Store nextSyncToken for the next incremental sync
+  return { events, nextSyncToken }
+}
+```
+
+### Incremental sync (subsequent runs)
+
+```ts
+async function incrementalSync(calendarId: string, accessToken: string, syncToken: string) {
+  let pageToken: string | undefined
+  let newSyncToken: string | undefined
+  const changes: any[] = []
+
+  do {
+    const url = new URL(`https://www.googleapis.com/calendar/v3/calendars/${encodeURIComponent(calendarId)}/events`)
+    url.searchParams.set('syncToken', syncToken)
+    if (pageToken) url.searchParams.set('pageToken', pageToken)
+
+    const res = await fetch(url, {
+      headers: { Authorization: `Bearer ${accessToken}` },
+    })
+
+    // 410 GONE — syncToken expired (happens after ~7 days of inactivity, or if Google invalidates it)
+    if (res.status === 410) {
+      // Drop stored syncToken and do a full sync
+      await db.query('UPDATE user_calendars SET sync_token = NULL WHERE ...')
+      return fullSync(calendarId, accessToken)
+    }
+
+    if (!res.ok) throw new Error(`Calendar sync failed: ${res.status}`)
+    const data = await res.json()
+
+    // Events returned here include deletions (status: 'cancelled')
+    changes.push(...(data.items ?? []))
+    pageToken = data.nextPageToken
+    newSyncToken = data.nextSyncToken
+  } while (pageToken)
+
+  return { changes, newSyncToken }
+}
+```
+
+**Critical**: `nextSyncToken` is only on the LAST page of results. If you stop paging early, you lose the token and have to full-sync next time.
+
+**Do NOT combine `syncToken` with other filters** like `timeMin`, `timeMax`, `q`. Google errors out. Sync tokens return ALL events that changed — filter client-side after.
+
+## Create an Event
+
+```ts
+async function createEvent(calendarId: string, accessToken: string, event: {
+  summary: string
+  description?: string
+  location?: string
+  start: { dateTime: string; timeZone: string }
+  end: { dateTime: string; timeZone: string }
+}) {
+  const res = await fetch(
+    `https://www.googleapis.com/calendar/v3/calendars/${encodeURIComponent(calendarId)}/events`,
+    {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(event),
+    }
+  )
+
+  if (!res.ok) throw new Error(`Create event failed: ${res.status} ${await res.text()}`)
+  return res.json() as Promise<{ id: string; htmlLink: string }>
+}
+```
+
+Store the returned `id` as `google_event_id` on your local row so you can update/delete it later.
+
+## Push Notifications (Watch Channels)
+
+For near-real-time sync, subscribe to a channel:
+
+```ts
+await fetch(`https://www.googleapis.com/calendar/v3/calendars/primary/events/watch`, {
+  method: 'POST',
+  headers: {
+    Authorization: `Bearer ${accessToken}`,
+    'Content-Type': 'application/json',
+  },
+  body: JSON.stringify({
+    id: randomUUID(),
+    type: 'web_hook',
+    address: 'https://your-domain.com/api/calendar/webhook',
+    token: 'your-verification-secret',
+    expiration: String(Date.now() + 7 * 24 * 60 * 60 * 1000),  // 7 days max
+  }),
+})
+```
+
+Google POSTs to your webhook when the calendar changes. The webhook doesn't contain the change — it's a signal to trigger an incremental sync.
+
+**Your webhook must be HTTPS with a valid public cert.** ngrok works for local testing.
+
+Channels expire after 7 days. Refresh them on a cron.
+
+## Sync Job Pattern
+
+```ts
+// Cron or queued job — runs per user_calendar row
+async function syncUserCalendar(userCalendarId: string) {
+  const row = await db.queryOne(/* user_calendars by id */)
+  if (!row) return
+
+  // Refresh token if needed
+  if (row.token_expires_at < new Date(Date.now() + 5 * 60_000)) {
+    try {
+      const { access_token, expires_in } = await refreshAccessToken(row.refresh_token)
+      await db.query(/* update access_token, token_expires_at */)
+      row.access_token = access_token
+    } catch (e) {
+      if (e instanceof CalendarReauthRequiredError) {
+        await db.query(/* mark needs_reauth = true */)
+        return
+      }
+      throw e
+    }
+  }
+
+  // Sync
+  let result
+  if (row.sync_token) {
+    result = await incrementalSync(row.google_calendar_id, row.access_token, row.sync_token)
+  } else {
+    result = await fullSync(row.google_calendar_id, row.access_token)
+  }
+
+  // Apply changes to local DB
+  for (const ev of result.changes ?? result.events) {
+    if (ev.status === 'cancelled') {
+      await db.query('DELETE FROM events WHERE google_event_id = $1', [ev.id])
+    } else {
+      await upsertEvent(ev)
+    }
+  }
+
+  // Persist new sync token
+  await db.query('UPDATE user_calendars SET sync_token = $1, last_synced_at = NOW() WHERE id = $2',
+    [result.nextSyncToken ?? result.newSyncToken, userCalendarId])
+}
+```
+
+## Sources
+
+- [Sync resources efficiently](https://developers.google.com/workspace/calendar/api/guides/sync)
+- [Choose Calendar API scopes](https://developers.google.com/workspace/calendar/api/auth)
+- [Events: list](https://developers.google.com/workspace/calendar/api/v3/reference/events/list)
+- [Push notifications](https://developers.google.com/workspace/calendar/api/guides/push)

package/skills/authentication/references/google-cloud-console.md

@@ -0,0 +1,159 @@
+---
+name: google-cloud-console
+description: Use when setting up Google Cloud Console for a web app — Google OAuth sign-in, Maps JavaScript API, Places API (New), Geocoding, Directions, or Google Calendar sync. Covers console setup, credentials, scopes, common footguns, and Next.js 16 / Supabase patterns. Trigger on "google oauth", "google sign in", "google maps", "places api", "google calendar sync", "google cloud credentials".
+---
+
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Google Cloud Console — Auth + Maps + Calendar
+
+Hard-won reference for wiring Google Cloud services into a web app. Lessons baked in from a real Next.js + Supabase build (Example Web App, 2025). Every footgun here was paid for once already — don't pay for it again.
+
+## When to Use
+
+- Setting up Google sign-in (OAuth 2.0) for a web or mobile app
+- Adding Google Maps, Places, Geocoding, or Directions to a UI
+- Syncing Google Calendar events to/from your app
+- Debugging auth redirect loops, `redirect_uri_mismatch`, or `invalid_grant`
+- Migrating from legacy Places API / `gapi.auth2` / `google.maps.Marker`
+
+## Core Mental Model
+
+Google Cloud Console is four layered concerns — get them in this order:
+
+1. **Project** — a container. APIs are enabled _per project_.
+2. **APIs** — enable only the ones you need (billing consequences).
+3. **Credentials** — OAuth client IDs (for user auth) OR API keys (for Maps) OR service accounts (server-to-server).
+4. **OAuth Consent Screen** — what the user sees on the consent dialog. Required before OAuth works.
+
+A single project can hold multiple credentials. Use **separate projects for dev and prod** — not just separate credentials. This keeps quotas, billing, and consent-screen state isolated.
+
+## Decision Matrix
+
+| Need | Credential type | Key doc |
+|------|-----------------|---------|
+| "Sign in with Google" button | OAuth 2.0 client (Web application) | [OAuth web server](https://developers.google.com/identity/protocols/oauth2/web-server) |
+| Embed a map in a web page | API key (HTTP referrer restricted) | [Load Maps JS API](https://developers.google.com/maps/documentation/javascript/load-maps-js-api) |
+| Search places / autocomplete | API key (same one if same project) | [Places API New](https://developers.google.com/maps/documentation/places/web-service/overview) |
+| Read user's Google Calendar | OAuth client + Calendar scope | [Calendar auth](https://developers.google.com/workspace/calendar/api/auth) |
+| Server-to-server Calendar (Workspace) | Service account + domain-wide delegation | [Service accounts](https://developers.google.com/identity/protocols/oauth2/service-account) |
+| Native mobile sign-in | OAuth client (iOS/Android) + PKCE | [Mobile OAuth](https://developers.google.com/identity/protocols/oauth2/native-app) |
+
+## Setup Order (Do NOT skip steps)
+
+```
+1. Create project (dev + prod, separate)
+2. Enable required APIs (per project)
+3. Configure OAuth consent screen (BEFORE creating OAuth client)
+4. Create credentials (OAuth client / API key / service account)
+5. Restrict credentials (referrer, IP, or scope)
+6. Add credentials to app env vars (NEVER commit)
+7. Configure app-side redirect URIs to match EXACTLY
+8. Test in dev → test in prod-like env → ship
+```
+
+Details per surface are in `references/` — load progressively.
+
+## References (Progressive Disclosure)
+
+Load only what you need:
+
+- **`references/oauth-setup.md`** — OAuth consent screen fields, web-app client creation, Supabase Google provider wiring, Next.js 16 cookie API, CSRF via state param, redirect URI rules. Start here for "add sign in with Google".
+- **`references/maps.md`** — Maps JS API loader, `importLibrary()` async pattern, Advanced Markers (Marker is deprecated), Map ID requirement, key restriction recipe.
+- **`references/places.md`** — Places API (New) v1 — Text Search, Nearby, Place Details. Field masks (cost control). Migration from legacy. Autocomplete.
+- **`references/geocoding-directions.md`** — Geocoding + Directions + Distance Matrix, rate limits, caching strategy.
+- **`references/calendar-sync.md`** — Google Calendar API v3 scopes, incremental sync with `syncToken`, 410 recovery, refresh-token storage, watch channels for push.
+- **`references/lessons-example-web-app.md`** — Real failure modes from production: Supabase SSR cookie bug, production-only redirect loops, route-group manifest conflicts, credential rotation pain.
+
+## The 10 Footguns (Read This Section Every Time)
+
+These are the failures that cost days in the Example Web App build. Check for each when something breaks.
+
+1. **Supabase SSR cookie API mismatch (Next.js 15+)** — Must use `getAll`/`setAll`, NOT `get`/`set`/`remove`. Works in dev, fails in prod. Error surfaces as "Cannot read properties of undefined (reading 'get')" in Supabase SSR. See `references/oauth-setup.md#nextjs-cookies`.
+
+2. **`redirect_uri_mismatch`** — The redirect URI in Google Cloud Console must match the one your app sends **exactly** (no trailing slash, correct protocol, correct port). For Supabase it must be `https://<project>.supabase.co/auth/v1/callback` — **not** your app's URL.
+
+3. **OAuth consent screen in "Testing" mode** — Until you publish it, only listed test users can sign in. Publishing triggers verification if you use sensitive scopes (like Calendar).
+
+4. **No OAuth consent screen at all** — You cannot create a Web-app OAuth client until the consent screen is configured. The console lets you start and then fails silently on some fields.
+
+5. **Map ID missing for Advanced Markers** — `google.maps.Marker` is deprecated (Feb 2024). `AdvancedMarkerElement` requires a **Map ID** on the `Map` constructor. Without it, markers silently don't render.
+
+6. **Legacy Places API enabled instead of Places API (New)** — Legacy can no longer be enabled for new projects. If you followed a 2023 tutorial it won't work. Use the New API with `FieldMask` headers.
+
+7. **API key with no referrer restriction** — Anyone who views source grabs your key and racks up billing. Always restrict Maps/Places keys by HTTP referrer (`https://your-domain.com/*`) and API (only the APIs you actually use).
+
+8. **Client secret in `NEXT_PUBLIC_*`** — Easy to do by mistake; exposes the secret to the browser. Client secrets go in server-only env vars. API keys for Maps JS are public by design (protected by referrer restriction, not secrecy).
+
+9. **Route-group conflicts cause Vercel build failures** — `app/page.tsx` + `app/(app)/page.tsx` both existing generates the `client-reference-manifest.js` at the wrong path. Builds locally, fails on Vercel. Pick one.
+
+10. **`invalid_grant` on token refresh** — User revoked access, or the refresh token wasn't stored (Google only returns it on the _first_ consent unless you pass `prompt=consent` or `access_type=offline`). Always request `access_type=offline&prompt=consent` for first consent if you need durable calendar access.
+
+## Required Env Vars (Web App Template)
+
+```env
+# Supabase (if using)
+NEXT_PUBLIC_SUPABASE_URL=https://xxx.supabase.co
+NEXT_PUBLIC_SUPABASE_ANON_KEY=ey...
+
+# Google OAuth (server-side only — Supabase handles the flow)
+GOOGLE_CLIENT_ID=...apps.googleusercontent.com
+GOOGLE_CLIENT_SECRET=GOCSPX-...
+
+# Google Maps (browser-exposed, protected by HTTP referrer restriction)
+NEXT_PUBLIC_GOOGLE_MAPS_API_KEY=AIza...
+NEXT_PUBLIC_GOOGLE_MAPS_MAP_ID=...     # required for Advanced Markers
+
+# App URLs — MUST match what's in Google Cloud Console + Supabase
+NEXT_PUBLIC_APP_URL=https://your-domain.com
+NEXT_PUBLIC_SITE_URL=https://your-domain.com  # must equal APP_URL in prod
+```
+
+Add a boot-time validator that refuses to run if any are missing or contain `your_`/`demo_`/`development`. See `references/oauth-setup.md#env-validation`.
+
+## Quick Verification Commands
+
+Before claiming auth works:
+
+```bash
+# 1. Build succeeds
+npm run build
+
+# 2. Manifest file exists where Vercel expects it
+ls .next/server/app/**/page_client-reference-manifest.js
+
+# 3. Sign-in flow end to end (manual)
+#    - open /signin
+#    - click Google
+#    - grant consent
+#    - land on /dashboard
+#    - hard refresh — session persists
+#    - close browser, reopen — session persists for 7 days
+#    - sign out — cookies cleared, /dashboard redirects to /signin
+```
+
+"Build passed" ≠ "auth works". "Sign-in UI appears" ≠ "session persists". Test the full loop.
+
+## Honest Certainty Markers
+
+When wiring this up, report state with markers — NEVER "100% complete":
+
+- ✅ Console configured (project exists, APIs enabled, consent screen published, credentials created)
+- ✅ App env vars set (validated at boot)
+- ✅ Sign-in UI renders
+- ⚠️ Sign-in flow works in dev — not yet tested in prod
+- ❓ Refresh-token storage — need to verify on 2nd-day session
+
+## Latest Docs (April 2026)
+
+Bookmark these — Google rewrites them regularly, and old blog posts lie.
+
+- [OAuth 2.0 for Web Server Apps](https://developers.google.com/identity/protocols/oauth2/web-server) — the canonical auth flow doc
+- [Using OAuth 2.0 (index)](https://developers.google.com/identity/protocols/oauth2) — scope & flow overview
+- [Load Maps JS API](https://developers.google.com/maps/documentation/javascript/load-maps-js-api) — modern async loader
+- [Advanced Markers migration](https://developers.google.com/maps/documentation/javascript/advanced-markers/migration) — required migration from deprecated `Marker`
+- [Places API (New) overview](https://developers.google.com/maps/documentation/places/web-service/overview) — legacy is end-of-life for new projects
+- [Calendar API sync guide](https://developers.google.com/workspace/calendar/api/guides/sync) — incremental sync tokens
+- [Calendar API scopes](https://developers.google.com/workspace/calendar/api/auth) — pick the narrowest scope
+
+When in doubt, use Context7 MCP (`context7__query-docs`) against library IDs for `@googlemaps/js-api-loader`, `@supabase/ssr`, `googleapis`.

package/skills/authentication/references/google-geocoding-directions.md

@@ -0,0 +1,126 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Geocoding + Directions + Distance Matrix
+
+Non-interactive, server-side APIs. Get an API key restricted to your server's IP (or unrestricted + used only via server routes).
+
+## Geocoding — address ↔ lat/lng
+
+```ts
+async function geocode(address: string) {
+  const url = new URL('https://maps.googleapis.com/maps/api/geocode/json')
+  url.searchParams.set('address', address)
+  url.searchParams.set('key', process.env.GOOGLE_GEOCODING_API_KEY!)
+
+  const res = await fetch(url)
+  const json = await res.json()
+
+  if (json.status !== 'OK') {
+    throw new Error(`Geocode failed: ${json.status} ${json.error_message ?? ''}`)
+  }
+
+  const first = json.results[0]
+  return {
+    formattedAddress: first.formatted_address,
+    location: first.geometry.location, // { lat, lng }
+    placeId: first.place_id,
+    types: first.types,
+  }
+}
+```
+
+**Status codes to handle:**
+- `OK` — results found
+- `ZERO_RESULTS` — valid request, no match (show "address not found")
+- `OVER_QUERY_LIMIT` — rate limited, back off
+- `REQUEST_DENIED` — key issue, log loudly
+- `INVALID_REQUEST` — bad params
+
+**Reverse geocoding** uses the same endpoint with `latlng=` instead of `address=`.
+
+**Cache aggressively.** A given address's lat/lng doesn't change. Store results permanently in your DB keyed by normalized address.
+
+## Directions
+
+```ts
+async function directions(origin: string, destination: string, mode: 'driving' | 'walking' | 'bicycling' | 'transit' = 'driving') {
+  const url = new URL('https://maps.googleapis.com/maps/api/directions/json')
+  url.searchParams.set('origin', origin)
+  url.searchParams.set('destination', destination)
+  url.searchParams.set('mode', mode)
+  url.searchParams.set('key', process.env.GOOGLE_DIRECTIONS_API_KEY!)
+
+  const res = await fetch(url)
+  const json = await res.json()
+  return json.routes[0]  // legs, overview_polyline, duration, distance
+}
+```
+
+Directions returns an **encoded polyline** (`overview_polyline.points`) — decode client-side with `google.maps.geometry.encoding.decodePath()` (import the `geometry` library) to draw on a map.
+
+## Distance Matrix — many-to-many
+
+When you need "what's the drive time from home to each of these 5 camps":
+
+```ts
+async function distanceMatrix(origins: string[], destinations: string[]) {
+  const url = new URL('https://maps.googleapis.com/maps/api/distancematrix/json')
+  url.searchParams.set('origins', origins.join('|'))
+  url.searchParams.set('destinations', destinations.join('|'))
+  url.searchParams.set('mode', 'driving')
+  url.searchParams.set('key', process.env.GOOGLE_DIRECTIONS_API_KEY!)
+
+  const res = await fetch(url)
+  return res.json() // rows[i].elements[j] = { distance, duration, status }
+}
+```
+
+**Billing**: Distance Matrix is charged per element (origins × destinations). 3 origins × 5 destinations = 15 elements. Cap batch sizes to avoid surprise bills.
+
+## Rate Limiting + Caching Strategy
+
+Both Geocoding and Directions have generous free tiers but billing ramps fast. Build a simple cache layer:
+
+```ts
+// lib/google-cache.ts
+import { createHash } from 'crypto'
+
+type CacheRow = { key: string; value: unknown; cached_at: Date }
+
+async function cachedFetch<T>(
+  bucket: 'geocode' | 'directions',
+  keyParts: string[],
+  fetcher: () => Promise<T>,
+  ttlDays: number,
+): Promise<T> {
+  const key = createHash('sha256').update(`${bucket}:${keyParts.join('|')}`).digest('hex')
+
+  const row = await db.query<CacheRow>(
+    'SELECT value, cached_at FROM google_cache WHERE key = $1',
+    [key],
+  )
+
+  if (row && daysSince(row.cached_at) < ttlDays) {
+    return row.value as T
+  }
+
+  const value = await fetcher()
+  await db.query(
+    'INSERT INTO google_cache (key, value, cached_at) VALUES ($1, $2, NOW()) ON CONFLICT (key) DO UPDATE SET value = $2, cached_at = NOW()',
+    [key, value],
+  )
+  return value
+}
+```
+
+TTL suggestions:
+- Geocode (address → lat/lng): **permanent** (addresses don't move)
+- Reverse geocode: **90 days** (neighborhoods/places do change)
+- Directions: **1 day** (traffic + road changes + route updates)
+- Distance Matrix: **1 day**
+
+## Sources
+
+- [Geocoding API](https://developers.google.com/maps/documentation/geocoding/overview)
+- [Directions API](https://developers.google.com/maps/documentation/directions/overview)
+- [Distance Matrix API](https://developers.google.com/maps/documentation/distance-matrix/overview)