Client SDK Reference

The Client SDK is the public API surface of the Lantern web app — every utility, service, hook, and constant exported from apps/web/src/lib/ and apps/web/src/hooks/. The admin portal renders an interactive listing of this surface at /client-sdk, generated from the source code's JSDoc comments.

Why it exists

• Discoverability — one place to browse what the web app can do without grepping lib/.
• Single source of truth — descriptions, signatures, and parameters live next to the code (JSDoc), not in hand-written docs that drift.
• Onboarding — new contributors can scan categories like Venue Services or Authentication & Security before opening files.

Where it lives

Surface	Path	Purpose
Source JSDoc	apps/web/src/lib/*.js, apps/web/src/hooks/*.js	The actual functions and their @param / @returns / @example blocks
Generator	tooling/scripts/generate-client-sdk-docs.mjs	Parses JSDoc → categorizes → emits HTML + JSON
Standalone HTML	tooling/client-sdk-static/index.html	Dark-themed reference, mirrored to apps/admin/public/client-sdk/
React manifest	apps/admin/src/generated/client-sdk.json	Consumed by the admin's native React page
Admin page	apps/admin/src/components/ClientSdkPage.jsx	Renders the manifest at /client-sdk in the admin portal

Pipeline

apps/web/src/lib/*.js  ──documentation.js──▶  raw JSON
        │                                         │
        │                                         ▼
        │                              dedupe + categorize
        │                                         │
        │                            ┌────────────┴────────────┐
        │                            ▼                         ▼
        │              tooling/client-sdk-static/   apps/admin/src/generated/
        │                  index.html                  client-sdk.json
        │                                                       │
        │                                                       ▼
        └──────────────────────────────────────▶  ClientSdkPage.jsx
                                                  (admin portal /client-sdk)

1. documentation.js (npm package) walks the source files and emits a JSON AST of every exported symbol with its JSDoc.
2. The generator deduplicates re-exports (e.g. devLog shows up wherever it's imported — only the home file wins), categorizes each symbol, and renders descriptions to HTML.
3. Two outputs are written: a self-contained HTML reference (port 6007 when served standalone) and a JSON manifest the admin React page consumes.

How files get categorized

Every .js file in apps/web/src/lib/ and apps/web/src/hooks/ must declare a category via an @sdkCategory tag in its top-level JSDoc block. There is no fallback — if the tag is missing or names an unknown category, the build fails with an error pointing at the file.

/**
 * @file Wave service — meeting requests between users.
 * @sdkCategory Social Features
 */

To see all valid categories: npm run client-sdk:categories.

Available categories

Analytics, Authentication & Security, Dev & Testing Tools, Location & Proximity, Merchant & Offers, OpenStreetMap Integration, React Hooks, Social Features, User Profiles, Utilities, Venue Services. Adding a new one requires editing CATEGORY_ORDER, CATEGORY_ICONS, and CATEGORY_DESCRIPTIONS in the generator (keep CATEGORY_ORDER alphabetical).

Adding a new function or file

The TL;DR — if you add any new exported function, hook, or constant under apps/web/src/lib/ or apps/web/src/hooks/, do this before committing:

1. Document the export with JSDoc. At minimum a one-line summary; ideally @param, @returns, and @example blocks. The generator reads these directly.

   /**
    * Send a wave to another user at a venue.
    * @param {string} targetUserId
    * @param {string} venueId
    * @returns {Promise<void>}
    */
   export async function sendWave(targetUserId, venueId) { /* ... */ }

2. If it's a brand-new file, add an @sdkCategory tag to the top JSDoc block (see above). Skipping this fails the build immediately.
3. Regenerate with npm run client-sdk:docs:build.
4. Commit the regenerated artifacts alongside your source change:
   • apps/admin/src/generated/client-sdk.json
   • apps/admin/public/client-sdk/index.html
   • tooling/client-sdk-static/index.html
5. Verify with npm run client-sdk:docs:check (also runs as part of npm run validate and in CI).

If you forget step 3 or 4, npm run validate fails locally and CI blocks the PR. The error message tells you exactly which command to run.

When the listing is regenerated

The pipeline is enforced. The generated manifest is committed to git, and a freshness check runs in CI / npm run validate to fail if the committed files have drifted from the source JSDoc.

Trigger	Behavior	Notes
Editing JSDoc in apps/web/src/lib/*.js	⚠️ Manual regeneration required	Run npm run client-sdk:docs:build and commit the updated client-sdk.json + HTML mirrors
npm run validate (pre-commit)	✅ Fails if stale	Runs client-sdk:docs:check — regenerates in memory and compares against committed files
GitHub Actions CI	✅ Fails if stale	Same check as validate. Also uploads a fresh build as a 7-day artifact
npm run admin:build (production)	✅ Regenerates	Always runs the generator before bundling — production deploys are guaranteed fresh

If the check fails, the CI/local error tells you exactly what to do: run npm run client-sdk:docs:build and commit the resulting files (apps/admin/src/generated/client-sdk.json, apps/admin/public/client-sdk/index.html, tooling/client-sdk-static/index.html).

Commands

# Regenerate the manifest + standalone HTML (no server)
npm run client-sdk:docs:build

# Regenerate AND serve the standalone HTML at http://localhost:6007
npm run client-sdk:docs

# Verify the committed manifest matches the source (used by CI / validate)
npm run client-sdk:docs:check

# List valid @sdkCategory values
npm run client-sdk:categories

After running client-sdk:docs:build, commit the updated apps/admin/src/generated/client-sdk.json (and apps/admin/public/client-sdk/index.html).

Window dev utilities

The Window Dev Utilities category is manually curated — it lists window.* functions exposed in apps/web/src/main.jsx (e.g. lantern.spoof.location.set(), lantern.dev.seedVenues()). These aren't ES exports, so JSDoc parsing won't find them. They live in the WINDOW_UTILITIES array at the top of the generator and must be edited by hand when adding new console-callable helpers.

See also

• The Storybook reference covers React components; the Client SDK covers non-component utilities, services, and hooks.
• API reference docs (Cloud Run services) live under Admin → API Reference, not here.
• Source: tooling/scripts/generate-client-sdk-docs.mjs