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
After a local Rust API change, regenerate its web contract from the repository
root with bun run --cwd apps/web gen-api <service-name> before running
bun run sync-specs && bun run generate here.
just coverage lists UNCOVERED <service>.<endpoint>.
A wrapped endpoint also needs a verb in src/utils/verbs.ts, from the closed
SdkVerb set: what it does to a resource (edited), or read, listed,
searched, queried or checked when it changes nothing, including a POST that
only reads. just coverage fails on a wrapped method with no verb or a verb for a
method that no longer exists. Don't grow the set; pick the closest.
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
- Read the method in
generated/<service>/sdk.gen.tsand its types intypes.gen.ts(notepath/query/body). - Pick a home, and read a sibling first —
entities/tasks/is the smallest complete example,entities/documents/document.tsthe richest:- acts on one entity → method on that class
- create/list/search/lookup → the namespace
- new noun → new
src/entities/<noun>/pair, registered insrc/macro.ts - cross-entity capability → a base in
src/entities/entity.ts
- Never take or return a raw id (the SDK rule). Take
the entity handle and return handles; if the noun has no entity class yet,
build it in this change rather than accepting a
string. - Match the conventions:
static byId(client, id); detail viaLazy+protected fetch(), exposed withthis.field(...)/this.mappedField(...)- extend
MacroEntity/FavoritableEntity/PropertiedEntity, settingentityType/propertyEntityType - writes touching this entity's detail →
this.mutate(...); others →unwrap(...) - every generated call goes through
unwrap() - cursor lists →
paginate()→AsyncGenerator; search →entitySearch(...) - camelCase +
undefinedon the SDK side even when the wire is snake_case/nullable - TSDoc every public member. No
any. End each public method's TSDoc with its MCP hint tag (@readonly,@write,@send,@destructive;packages/sdk-mcp/AGENTS.md) and update that package's tool snapshots (bunx vitest run -uthere). - an entity with its own page in the app gets
webUrl(), built fromthis.client.webAppUrland the route the web app's copy-link action uses (/app/agent/<id>, not the entity type when they differ), plus atoJSON()override addingurl: this.webUrl(). Agents hand these links to users; without one they guess the route.
- New service? Only when the endpoint's service isn't reachable from
MacroClientyet — per service, not per entity; a new entity needs none of this. Wire theSdkintosrc/utils/client.ts, a host intosrc/config.ts, and an entry intoACCESSORSinsrc/coverage/check.ts. That last one is easy to miss: coverage decides "is this called?" by greppingsrc/for the literal text.<accessor>.<endpoint>(, so a service absent fromACCESSORSreports every one of its endpoints asUNCOVEREDno matter how well you wrapped them. If a whole service looks uncovered, check that map before believing it. - Already listed as skipped? Remove it, or coverage fails with
STALE SKIP. - Verify:
just check && just coverage && bun run lint && bun run format. - 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/orspecs/— build output. - Accept an id where an entity handle belongs.
- Mark something skipped just to make coverage pass.