06-big-tree-and-apis/04-how-apps-call-scripts.md

How apps call scripts

Vroq apps should call BigTree scripts through small API client helpers instead of calling transport APIs directly from UI code.

This keeps networking logic isolated and makes debugging easier.

Preferred pattern

The UI should call a small helper function in an API client file.

Example:

import { listFiles } from "./fileApi.js";

const files = await listFiles();

The API client file handles the transport details.

Example API client

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

export async function listFiles() {
  const result = await btRun("files_list", {});
  return result?.items || [];
}

This pattern keeps UI code simple and prevents transport logic from spreading across many files.

Rules

UI files should not construct script URLs
UI files should not handle tokens
UI files should not call fetch directly for BigTree scripts

Instead, call a small helper that represents the API capability.

Why this matters

Centralizing remote calls makes it easier to:

update script behavior
debug remote errors
normalize responses
reuse remote operations across features

Final rule

UI files call **API client helpers**, and API clients call **scripts**.

This keeps the remote boundary clear and maintainable.