add-sdk-endpoint

# 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.