stillmade-sdk 0.1.42 → 0.1.43

package/docs/build/cookbook.md

@@ -0,0 +1,57 @@
+# Cookbook
+
+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](testing.md).
+
+**Type your code.** Run `stillmade-block types .` and use `BlockRun`,
+`BlockInputs` and the typed `StillMade` global. See TypeScript above.