add-sdk-endpoint

name	add-sdk-endpoint
description	Wrap a new backend endpoint in the TypeScript SDK (packages/sdk), or record it as skipped. Use when `just coverage` fails, or after adding an endpoint to a Rust service.
allowed-tools	Bash, Read, Edit, Write, Grep, Glob

Add an SDK endpoint

Arg skip: record the endpoint as skipped instead of wrapping it. Run everything from packages/sdk.

Every generated endpoint must either have a call site under src/ or be listed in src/coverage/skipped.ts. Being in both also fails.

0. Find it

Not in generated/ yet? bun run sync-specs && bun run generate (or ask the user to run just update-generated if the Rust spec changed locally — it rebuilds apps/web).

just coverage lists UNCOVERED <service>.<endpoint>.

1. Skip or wrap?

With the skip arg, skip. Otherwise ask the user, one line per endpoint, with a short recommendation — don't decide silently.

Skip-worthy: internal plumbing (auth/session, health, infra, web-app internals, MCP, batch previews) and features so narrow that no SDK user would reach for them. Everything a user could plausibly want belongs in the SDK.

To skip: add the method name, alphabetically, to <camelService>Excluded in src/coverage/skipped.ts, then just coverage && just check. Don't wrap.

To wrap it

1. Read the method in generated/<service>/sdk.gen.ts and its types in types.gen.ts (note path / query / body).
2. Pick a home, and read a sibling first — entities/tasks/ is the smallest complete example, entities/documents/document.ts the richest:
   • acts on one entity → method on that class
   • create/list/search/lookup → the namespace
   • new noun → new src/entities/<noun>/ pair, registered in src/macro.ts
   • cross-entity capability → a base in src/entities/entity.ts
3. Never take or return a raw id. Wherever the generated endpoint takes an id, the SDK takes the entity handle and reads .id off it internally; wherever it returns an id, the SDK returns a handle. If the id refers to a noun that has no entity class yet, build that entity (and its namespace) as part of this change — do not fall back to a string parameter. The one exception is a static byId, which is how handles are minted in the first place.
4. Match the conventions:
   • static byId(client, id); detail via Lazy + protected fetch(), exposed with this.field(...) / this.mappedField(...)
   • extend MacroEntity / FavoritableEntity / PropertiedEntity, setting entityType / propertyEntityType
   • writes touching this entity's detail → this.mutate(...); others → unwrap(...)
   • every generated call goes through unwrap()
   • cursor lists → paginate() → AsyncGenerator; search → entitySearch(...)
   • camelCase + undefined on the SDK side even when the wire is snake_case/nullable
   • TSDoc every public member. No any.
5. New service? Only when the endpoint's service isn't reachable from MacroClient yet — per service, not per entity; a new entity needs none of this. Wire the Sdk into src/utils/client.ts, a host into src/config.ts, and an entry into ACCESSORS in src/coverage/check.ts. That last one is easy to miss: coverage decides "is this called?" by grepping src/ for the literal text .<accessor>.<endpoint>(, so a service absent from ACCESSORS reports every one of its endpoints as UNCOVERED no matter how well you wrapped them. If a whole service looks uncovered, check that map before believing it.
6. Already listed as skipped? Remove it, or coverage fails with STALE SKIP.
7. Verify: just check && just coverage && bun run lint && bun run format.
8. Document: README only for genuinely new user-facing capability. New webhook events come from the storage spec via src/events/types.ts — regenerate, never hand-write.

Never

• Hand-edit generated/ or specs/ — build output.
• Accept an id where an entity handle belongs.
• Mark something skipped just to make coverage pass.