# API

> @taskbox/tools public exports.

Source: https://taskbox.n.yatsyk.com/docs/tools/api

# API

## Factory

| Export          | Signature                                                                                             | Summary                                                                                  |
| --------------- | ----------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `createTaskbox` | `(config: TaskboxConfig) => { prepare, runTask, media }`                                              | Build a Taskbox façade bound to a runtime adapter and optional defaults.                 |
| `TaskboxConfig` | `{ runtime: RuntimeAdapter; image?: string; defaults?: { timeoutMs?; networkMode?; defaultProxy? } }` | Adapter + image override + per-call defaults.                                            |
| `PrepareResult` | `{ runtime: string; image: { ref; digest? }; [k: string]: unknown }`                                  | Shape returned by `prepare()`. Extra keys come from the adapter's `available().details`. |

## Façade methods

| Method                     | Signature                                                                  | Summary                                                                                                                              |
| -------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `prepare`                  | `() => Promise<PrepareResult>`                                             | Verifies the runtime is available and pulls/inspects the image. Throws `TaskboxError({ code: "E_RUNTIME_UNAVAILABLE" })` on failure. |
| `runTask`                  | `(spec: unknown, opts?: { onEvent? }) => Promise<TaskResult>`              | Thin pass-through to `@taskbox/core`'s `runTask` with the bound runtime.                                                             |
| `media.downloadSubtitles`  | `(input: unknown, opts?: DownloadSubtitlesOptions) => Promise<TaskResult>` | Validates a `MediaDownloadSubtitlesInput`, builds a `TaskSpec`, and runs it.                                                         |
| `DownloadSubtitlesOptions` | `{ onEvent?: (e: TaskEvent) => void }`                                     | Optional event sink.                                                                                                                 |

## Re-exports

| Export                  | From               | Why                                                                     |
| ----------------------- | ------------------ | ----------------------------------------------------------------------- |
| `RuntimeAdapter` (type) | `@taskbox/core`    | Convenience for callers wiring custom runtimes.                         |
| `defaultImageRef`       | `@taskbox/core`    | The kitchen-sink image ref.                                             |
| `TaskboxError` (class)  | `@taskbox/core`    | So you can catch the same error type without an extra import.           |
| `TaskboxErrorSchema`    | `@taskbox/schemas` | For validating wire errors received over a queue/ipc.                   |
| `EventBus` (class)      | `@taskbox/core`    | If you want to construct your own bus and pass it via core's `runTask`. |

## Behaviour notes

* A `proxy` field on the tool input forces `network.mode === "proxy"`,
  overriding `defaults.networkMode`.
* `defaults.timeoutMs` is applied as `spec.resources.timeoutMs` only when the
  input doesn't set one.
* `outputDir` on a tool input becomes `spec.output = { dir, materialize: true }`,
  which makes `@taskbox/core` clean up the workspace after success.

See the generated [JSDoc reference](/docs/tools/jsdoc) for the full surface.