mirror of
https://github.com/koala73/worldmonitor.git
synced 2026-04-25 17:14:57 +02:00
e4c95ad9be
* docs(mintlify): cover MCP, OAuth, non-RPC endpoints, and usage Audit against api/ + proto/ revealed 9 OpenAPI specs missing from nav, the scenario/v1 service undocumented, and MCP (32 tools + OAuth 2.1 flow) with no user-facing docs. The stale Docs_To_Review/API_REFERENCE.md still pointed at pre-migration endpoints that no longer exist. - Wire 9 orphaned specs into docs.json: ConsumerPrices, Forecast, Health, Imagery, Radiation, Resilience, Sanctions, Thermal, Webcam - Hand-write ScenarioService.openapi.yaml (3 RPCs) until it's proto-backed (tracked in issue #3207) - New MCP page with tool catalog + client setup (Claude Desktop/web, Cursor) - New MDX for OAuth, Platform, Brief, Commerce, Notifications, Shipping v2, Proxies - New Usage group: quickstart, auth matrix, rate limits, errors - Remove docs/Docs_To_Review/API_REFERENCE.md and EXTERNAL_APIS.md (referenced dead endpoints); add README flagging dir as archival * docs(mintlify): move scenario docs out of generated docs/api/ tree The pre-push hook enforces that docs/api/ is proto-generated only. Replace the hand-written ScenarioService.openapi.yaml with a plain MDX page (docs/api-scenarios.mdx) until the proto migration lands (tracked in issue #3207). * docs(mintlify): fix factual errors flagged in PR review Reviewer caught 5 endpoints where I speculated on shape/method/limits instead of reading the code. All fixes cross-checked against the source: - api-shipping-v2: route-intelligence is GET with query params (fromIso2, toIso2, cargoType, hs2), not POST with a JSON body. Response shape is {primaryRouteId, chokepointExposures[], bypassOptions[], warRiskTier, disruptionScore, ...}. - api-commerce: /api/product-catalog returns {tiers, fetchedAt, cachedUntil, priceSource} with tier groups free|pro|api_starter| enterprise, not the invented {currency, plans}. Document the DELETE purge path too. - api-notifications: Slack/Discord /oauth/start are POST + Clerk JWT + PRO (returning {oauthUrl}), not GET redirects. Callbacks remain GET. - api-platform: /api/version returns the latest GitHub Release ({version, tag, url, prerelease}), not deployed commit/build metadata. - api-oauth + mcp: /api/oauth/register limit is 5/60s/IP (match code), not 10/hour. Also caught while double-checking: /api/register-interest and /api/contact are 5/60min and 3/60min respectively (1-hour window, not 1-minute). Both require Turnstile. Removed the fabricated limits for share-url, notification-channels, create-checkout (they fall back to the default per-IP limit). * docs(mintlify): second-round fixes — verify every claim against source Reviewer caught 7 more cases where I described API behavior I hadn't read. Each fix below cross-checked against the handler. - api-commerce (product-catalog): tiers are flat objects with monthlyPrice/annualPrice/monthlyProductId/annualProductId on paid tiers, price+period for free, price:null for enterprise. There is no nested plans[] array. - api-commerce (referral/me): returns {code, shareUrl}, not counts. Code is a deterministic 8-char HMAC of the Clerk userId; binding into Convex is fire-and-forget via ctx.waitUntil. - api-notifications (notification-channels): actual action set is create-pairing-token, set-channel, set-web-push, delete-channel, set-alert-rules, set-quiet-hours, set-digest-settings. Replaced the made-up list. - api-shipping-v2 (webhooks): alertThreshold is numeric 0-100 (default 50), not a severity string. Subscriber IDs are wh_+24hex; secret is raw 64-char hex (no whsec_ prefix). POST registration returns 201. Added the management routes: GET /{id}, POST /{id}/rotate-secret, POST /{id}/reactivate. - api-platform (cache-purge): auth is Authorization: Bearer RELAY_SHARED_SECRET, not an admin-key header. Body takes keys[] and/or patterns[] (not {key} or {tag}), with explicit per-request caps and prefix-blocklist behavior. - api-platform (download): platform+variant query params, not file=<id>. Response is a 302 to a GitHub release asset; documented the full platform/variant tables. - mcp: server also accepts direct X-WorldMonitor-Key in addition to OAuth bearer. Fixed the curl example which was incorrectly sending a wm_live_ API key as a bearer token. - api-notifications (youtube/live): handler reads channel or videoId, not channelId. - usage-auth: corrected the auth-matrix row for /api/mcp to reflect that OAuth is one of two accepted modes. * docs(mintlify): fix Greptile review findings - mcp.mdx: 'Five' slow tools → 'Six' (list contains 6 tools) - api-scenarios.mdx: replace invalid JSON numeric separator (8_400_000_000) with plain integer (8400000000) Greptile's third finding — /api/oauth/register rate-limit contradiction across api-oauth.mdx / mcp.mdx / usage-rate-limits.mdx — was already resolved in commit4f2600b2a(reviewed commit waseb5654647).
118 lines
4.3 KiB
Plaintext
118 lines
4.3 KiB
Plaintext
---
|
|
title: "Commerce Endpoints"
|
|
description: "Checkout, customer portal, product catalog, and referrals. Thin edge proxies over Convex + Dodo Payments."
|
|
---
|
|
|
|
WorldMonitor uses [Dodo Payments](https://dodopayments.com) for PRO subscriptions and [Convex](https://convex.dev) as the source-of-truth for entitlements. These edge endpoints are thin auth proxies — they validate the Clerk JWT, then forward to Convex HTTP actions via `RELAY_SHARED_SECRET`.
|
|
|
|
## Checkout
|
|
|
|
### `POST /api/create-checkout`
|
|
|
|
Creates a Dodo checkout session and returns the hosted-checkout URL.
|
|
|
|
- **Auth**: Clerk bearer (required)
|
|
- **Body**:
|
|
```json
|
|
{ "productId": "pro-monthly", "returnUrl": "https://www.worldmonitor.app/pro/success" }
|
|
```
|
|
- **Response**: `{ "checkoutUrl": "https://checkout.dodopayments.com/..." }`
|
|
- **returnUrl** is validated against an allowlist on the Convex side.
|
|
|
|
### `POST /api/customer-portal`
|
|
|
|
Creates a Dodo customer-portal session for an existing subscriber (update card, cancel, view invoices).
|
|
|
|
- **Auth**: Clerk bearer + active entitlement
|
|
- **Response**: `{ "portalUrl": "..." }`
|
|
|
|
## Product catalog
|
|
|
|
### `GET /api/product-catalog`
|
|
|
|
Returns the tier view-model used by the `/pro` pricing page. Cached in Redis under `product-catalog:v2` for 1 hour; on cache miss, fetches live prices from Dodo Payments and falls back to `_product-fallback-prices.js` if Dodo is unreachable. Response carries an `X-Product-Catalog-Source` header so probes can tell cache hits from live fetches.
|
|
|
|
**Response** (tiers ordered `free`, `pro`, `api_starter`, `enterprise`):
|
|
|
|
```json
|
|
{
|
|
"tiers": [
|
|
{
|
|
"name": "Free",
|
|
"description": "Get started with the essentials",
|
|
"features": ["Core dashboard panels", "..."],
|
|
"cta": "Get Started",
|
|
"href": "https://worldmonitor.app",
|
|
"highlighted": false,
|
|
"price": 0,
|
|
"period": "forever"
|
|
},
|
|
{
|
|
"name": "Pro",
|
|
"description": "Full intelligence dashboard",
|
|
"features": ["..."],
|
|
"highlighted": true,
|
|
"monthlyPrice": 20,
|
|
"monthlyProductId": "pdt_0Nbtt71uObulf7fGXhQup",
|
|
"annualPrice": 180,
|
|
"annualProductId": "pdt_0NbttMIfjLWC10jHQWYgJ"
|
|
},
|
|
{
|
|
"name": "API",
|
|
"description": "Programmatic access to intelligence data",
|
|
"features": ["..."],
|
|
"highlighted": false,
|
|
"monthlyPrice": 99,
|
|
"monthlyProductId": "pdt_0NbttVmG1SERrxhygbbUq",
|
|
"annualPrice": 990,
|
|
"annualProductId": "pdt_0Nbu2lawHYE3dv2THgSEV"
|
|
},
|
|
{
|
|
"name": "Enterprise",
|
|
"description": "Custom solutions for organizations",
|
|
"features": ["..."],
|
|
"cta": "Contact Sales",
|
|
"href": "mailto:enterprise@worldmonitor.app",
|
|
"highlighted": false,
|
|
"price": null
|
|
}
|
|
],
|
|
"fetchedAt": "2026-04-19T12:00:00Z",
|
|
"cachedUntil": "2026-04-19T13:00:00Z",
|
|
"priceSource": "dodo"
|
|
}
|
|
```
|
|
|
|
Notes:
|
|
- Price fields are flat on the tier. Paid tiers expose `monthlyPrice` / `monthlyProductId` and `annualPrice` / `annualProductId`. Free uses `price: 0, period: "forever"`; Enterprise uses `price: null`.
|
|
- Prices are dollars (Dodo returns cents; the handler divides by 100). Currency is implicit USD for the published catalog.
|
|
|
|
### `DELETE /api/product-catalog`
|
|
|
|
Purges the cached catalog. Requires `Authorization: Bearer $RELAY_SHARED_SECRET`. Internal.
|
|
|
|
## Referrals
|
|
|
|
### `GET /api/referral/me`
|
|
|
|
Returns the caller's deterministic referral code (an 8-char HMAC of the Clerk userId, stable for the life of the account) and a pre-built share URL. Clerk bearer required. The handler also fires a best-effort `ctx.waitUntil` Convex binding so future `/pro?ref=<code>` signups can attribute — this never blocks the response.
|
|
|
|
```json
|
|
{
|
|
"code": "a1b2c3d4",
|
|
"shareUrl": "https://worldmonitor.app/pro?ref=a1b2c3d4"
|
|
}
|
|
```
|
|
|
|
Errors:
|
|
- `401 UNAUTHENTICATED` — missing or invalid Clerk JWT.
|
|
- `503 service_unavailable` — `BRIEF_URL_SIGNING_SECRET` not configured (the referral-code HMAC reuses that secret).
|
|
|
|
No `referrals` count or `rewardMonths` is returned today — Dodo's `affonso_referral` attribution doesn't yet flow into Convex, and exposing only the waitlist-side count would mislead.
|
|
|
|
## Waitlist
|
|
|
|
### `POST /api/register-interest`
|
|
|
|
Captures an email into the Convex waitlist table. Turnstile-verified, rate-limited per IP. See [Platform endpoints](/api-platform) for the request shape.
|