# Cookbook

Short recipes for common Block work: files, structured replies, generation, storage, outside APIs, audio, interfaces, shared editing, triggers, offline tests and types.

Short recipes for common work. Each links to a complete example or template.

**Read an uploaded CSV in a module Block.** Declare a `file` input, then
`const text = new TextDecoder().decode(await stillmade.files.read(input.csv));`.
Return a `table` value (`{columns, rows}`) to get a table with a CSV download.
Example: `examples/module-csv-summary`.

**Ask a model for structured JSON.** List `text.generate` in
`permissions.capabilities` and call
`await stillmade.hosted.run('text.generate', {prompt, schema})`; the reply is
checked against the schema. Example: `examples/module-action-items`.

**Generate an image and add it to the project.** Call
`await stillmade.hosted.run('image.generate', {prompt})`, then
`await stillmade.assets.create(image, {name: 'Poster'})` with `asset.create` in
`permissions.project`. Template: `module-hosted`.

**Remember settings between runs.** Declare `storage` with `cloud: "metered"`,
then `await stillmade.storage.get('settings')` and
`await stillmade.storage.set('settings', value)`. Template: `storage`.

**Call an outside API with the person's own key.** Declare the origin and key
in `permissions.network`, call `await stillmade.net.fetch(url)`, and record
responses under `network` in `tests/mocks.json` for offline tests. Template:
`outside-api`.

**Show progress and stop when cancelled.** Call
`stillmade.progress(0.5, 'Halfway')` as work advances and check
`stillmade.signal.aborted` in long loops.

**Analyse audio on the device.** `await stillmade.media.transform({operation:
'audio.decode', source: input.audio, sampleRate: 16000})` returns mono samples.
Example: `examples/module-tempo`.

**Run the Block from a React interface.** Initialize from
`StillMade.onInput(setInput)`, call `await StillMade.run(values)` from a button
and show the outputs. Template: `view-react`.

**Let collaborators edit together.** Keep each independently edited value in
its own shared field: `StillMade.updateShared({point3: 0.8})`, and listen with
`StillMade.onShared`. Example: `examples/view-react-chart`.

**Show an image output.** `const preview = await StillMade.previewImage(output.image)`
gives a display copy for an `<img>`; keep passing the original value to `run`.

**Run on every new video.** Declare
`"triggers": [{"event": "media.saved", "input": "video", "kinds": ["video"]}]`;
the project owner turns it on and approves a credit budget. Template:
`trigger-media`.

**Test hosted calls offline.** Add `tests/mocks.json` (an empty object uses the
recorded stand-ins) or pass `--mock`. See [local testing](/docs/build/testing).

**Type your code.** Run `stillmade-block types .` and use `BlockRun`,
`BlockInputs` and the typed `StillMade` global. See TypeScript above.