# API

> @taskbox/schemas public exports.

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

# API

Every export is a Zod schema (suffixed `Schema`) paired with a type alias
inferred via `z.infer<...>`. The package also re-exports `z` for callers who
want to keep a single zod instance.

## Task lifecycle

| Export                                    | Kind                          | Summary                                                                                         |
| ----------------------------------------- | ----------------------------- | ----------------------------------------------------------------------------------------------- |
| `TaskSpecSchema` / `TaskSpec`             | object                        | Input contract: `tool`, `input`, `network`, optional `runtime`/`resources`/`output`/`id`.       |
| `RuntimeConfigSchema` / `RuntimeConfig`   | object                        | Optional `backend` ("podman") and `image` ref override.                                         |
| `ResourceConfigSchema` / `ResourceConfig` | object                        | Optional `cpus`, `memoryMb`, `timeoutMs`.                                                       |
| `OutputConfigSchema` / `OutputConfig`     | object                        | `dir` (where to materialize artifacts) and `materialize` flag.                                  |
| `TaskResultSchema` / `TaskResult`         | object                        | Output: `ok`, `taskId`, `tool`, `image`, timestamps, `artifacts`, `warnings`, optional `error`. |
| `TaskEventSchema` / `TaskEvent`           | discriminated union on `type` | `task.started`, `task.completed`, `task.failed`, `image.prepare.*`, `process.*`.                |

## Errors

| Export                                                | Kind   | Summary                                                                                      |
| ----------------------------------------------------- | ------ | -------------------------------------------------------------------------------------------- |
| `TaskboxErrorSchema` / `TaskboxError`                 | object | Serialized error shape with `code`, `category`, `message`, `retryable`, `suggestions`.       |
| `TaskboxErrorCodeSchema` / `TaskboxErrorCode`         | enum   | Stable error codes (e.g. `E_TIMEOUT`, `E_TOOL_EXIT_NONZERO`, `E_SCHEMA_INVALID`).            |
| `TaskboxErrorCategorySchema` / `TaskboxErrorCategory` | enum   | Coarse buckets (`runtime`, `image`, `tool`, `timeout`, `validation`, `artifact`, `network`). |

## Network and proxy

| Export                                  | Kind                          | Summary                                                     |
| --------------------------------------- | ----------------------------- | ----------------------------------------------------------- |
| `NetworkConfigSchema` / `NetworkConfig` | discriminated union on `mode` | `none`, `direct`, or `proxy` (with a `ProxyConfig`).        |
| `ProxyConfigSchema` / `ProxyConfig`     | object                        | `type`, `url`, optional `username`/`password`, `noProxy[]`. |
| `redactProxyUrl(url)`                   | function                      | Returns the URL with userinfo stripped, for safe logging.   |
| `proxyConfigToSafeJson(p)`              | function                      | Serializes a `ProxyConfig` with credentials redacted.       |

## Artifacts

| Export                                | Kind   | Summary                                                |
| ------------------------------------- | ------ | ------------------------------------------------------ |
| `ArtifactSchema` / `Artifact`         | object | `kind`, `path`, optional `mediaType`, `bytes`, `meta`. |
| `ArtifactKindSchema` / `ArtifactKind` | enum   | `file`, `dir`, `subtitles`, `audio`, `video`, etc.     |

## Tool inputs

| Export                                                              | Kind   | Summary                                       |
| ------------------------------------------------------------------- | ------ | --------------------------------------------- |
| `MediaDownloadSubtitlesInputSchema` / `MediaDownloadSubtitlesInput` | object | Input for the `media.downloadSubtitles` tool. |

## Misc

| Export | Kind      | Summary                                                         |
| ------ | --------- | --------------------------------------------------------------- |
| `z`    | re-export | The `zod` instance every schema in this package was built with. |

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