08-recipes/05-add-a-bigtree-api.md

Add a BigTree API

Use this recipe when a feature needs a backend operation provided by a BigTree script.

Steps

1. Check whether an existing script already provides the capability. 2. If not, design a new script with one clear responsibility. 3. Use object-shaped arguments for inputs. 4. Return a stable result shape (prefer { ok, result }). 5. Create a small API client helper in the feature folder. 6. Call the API helper from sections or actions, not directly from UI transport code.

Typical structure

features/featureName/
  apiClient.js

Example helper:

import { btRun } from "../debugger/btClient.js";

export async function listItems() {
  const res = await btRun("items_list", {});
  if (!res?.ok) throw new Error(res?.error || "items_list failed");
  return res.result || [];
}

Rules

UI files should call API helpers, not scripts directly
keep transport details out of UI
keep scripts small and well-named

Final rule

Expose backend behavior through small, well-named API helpers that call focused scripts.