# Functions

> @faustine-ai/browser-sandbox documentation · https://browser-sandbox.faustine.ai/docs/functions/ · source: README.md on GitHub (https://github.com/faustine-ai/browser-sandbox)

`defineFunctions` is the only way a capability enters the sandbox. Each
entry is the real function, which runs in your page, plus its policy.

```ts
import { defineFunctions, fromObject, describe } from '@faustine-ai/browser-sandbox';

const functions = defineFunctions({
  'orders.list':   (input) => api.orders.list(input),                   // plain
  'orders.cancel': { call: (input) => api.orders.cancel(input),          // with a policy
                     approval: true, description: 'Cancels an order' },
  'util.sum':      { call: (...nums) => nums.reduce((a, b) => a + b, 0),
                     positional: true },                                 // code calls sum(1, 2, 3)
  help:            (topic) => docs.lookup(topic),
});
```

- A **dotted name** becomes a path in the tree: `sdk.orders.list(input)`.
  Segments are identifiers; `__proto__`, `constructor` and `prototype` are
  refused.
- A function receives **one argument** (whatever the code passed) unless
  `positional: true`, in which case it receives the arguments spread.
- A name can be both a leaf and a branch (`help` and `help.topics`): it is
  a function with properties.
- `approval: true` holds the call for a human (see [Approval](https://browser-sandbox.faustine.ai/docs/approval.md)).
- `description` and `input` (a JSON Schema) are used only by `describe`.

`fromObject` builds the map from an existing object by **listing** names,
never by enumerating the object:

```ts
const functions = fromObject(client, {
  names: ['orders.list', 'orders.cancel', 'customers.get'],
  approval: (name) => name.endsWith('.cancel'),
  descriptions: (name) => catalog[name]?.summary,
  extra: { help: (topic) => docs.lookup(topic) },
});
```

Paths are resolved at call time with the right `this`, so lazily built
clients work; a missing path throws `UnknownFunction` into the code.

For the system prompt, `describe` prints the names exactly as the code will
use them:

```ts
describe(functions);                       // - sdk.orders.list(input)
                                           // - sdk.orders.cancel(input) (requires approval) — Cancels an order
describe(functions, { format: 'ts' });     // declare const sdk: { orders: { list(input?: unknown): Promise<unknown>; … } };
```