Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
chore: add skill for updating sdk (#5271)
Wolf Mermelstein262d9179e263
diff --git a/.claude/skills/add-sdk-endpoint/SKILL.md b/.claude/skills/add-sdk-endpoint/SKILL.mdnew file mode 100644index 0000000000..214e3544ec--- /dev/null+++ b/.claude/skills/add-sdk-endpoint/SKILL.md@@ -0,0 +1,78 @@+---+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.