# @kody/onetimefax Agent notes for the Onetime Fax head-start package. Human setup lives in `README.md`. API reference this package is built from: https://www.onetimefax.com/developers/ (developer preview). Base URL `https://app.onetimefax.com`. Every request sends `Authorization: Bearer {{secret:onetimefax-api-token}}`. ## Imports ```ts import getAccount from 'kody:@kody/onetimefax/account' import prepareFax from 'kody:@kody/onetimefax/prepare-fax' import sendFax from 'kody:@kody/onetimefax/send-fax' import faxStatus from 'kody:@kody/onetimefax/fax-status' import removeFile from 'kody:@kody/onetimefax/remove-file' ``` `kody:@kody/onetimefax` is the same function as `./fax-status`. In a fork, replace `@kody/onetimefax` with the fork's own `@owner/leaf`. | Export | Endpoint(s) | Side effects | | --- | --- | --- | | `./account` | `GET /api/v1/account` | none | | `./prepare-fax` | `POST /api/v1/faxes`, `POST /api/v1/faxes/{id}/files`, `GET /api/v1/faxes/{id}` | creates a draft, no charge | | `./send-fax` | `GET /api/v1/faxes/{id}`, then `POST /api/v1/faxes/{id}/send` only with `confirm: true` | spends credits | | `./fax-status` | `GET /api/v1/faxes/{id}` | none | | `./remove-file` | `DELETE /api/v1/faxes/{id}/files/{fileId}` | edits a draft | No list endpoint is documented (`GET /api/v1/faxes` answers 405), so there is no list export. Do not add one unless Onetime Fax documents it. ## Credential - Declared in `package.json#kody.credentials` as `onetimefax-api-token` (`kind: "secret"`, `provider: "onetimefax"`). - The secret must allow host `app.onetimefax.com` only. Prefilled create link (send this, never ask for the value in chat): `https://kody.codes/account/secrets/new?name=onetimefax-api-token&description=Onetime%20Fax%20developer%20API%20key&allowedHosts=app.onetimefax.com&scope=user` - All requests set `x-kody-secret-resolution: headers-only`, so placeholder text inside uploaded documents is never filled. - Unadopted community forks get `pending_secret_package_approvals` on publish. Send the owner the `approval_url`, or have them adopt the fork on the website. - OAuth alternative: the Onetime Fax MCP server at `https://app.onetimefax.com/mcp` (OAuth). It can be connected as a Kody `mcp` credential and called with `credential(key).callTool`. Its tool names are only listed after sign-in, so they are not wrapped here; discover them from the connected server before writing code against them. ## Smoke tests Local unit tests (mocked fetch, no network, no secret): `npm install && npm test`. Then `kody dev check`. After publish, prove the secret works with the read-only export first: ```bash kody execute --local --invoke kody:@kody/onetimefax/account --params '{}' ``` No-network checks: ```bash kody execute --local --invoke kody:@kody/onetimefax/prepare-fax --params '{"recipientNumber":"+14155551212","files":[{"filename":"hello.txt","text":"Hello from Kody"}],"dryRun":true}' ``` Full flow (only with the owner's go-ahead and a recipient number they control, because `send-fax` with confirm spends real credits): ```ts import prepareFax from 'kody:@kody/onetimefax/prepare-fax' import sendFax from 'kody:@kody/onetimefax/send-fax' import faxStatus from 'kody:@kody/onetimefax/fax-status' const draft = await prepareFax({ recipientNumber: '+14155551212', files: [{ filename: 'hello.txt', contentType: 'text/plain', text: 'Hello from Kody' }], }) // Show draft.recipientNumber, draft.fax.files, draft.pageCount, draft.quote to the person. const preview = await sendFax({ faxId: draft.faxId }) const sent = await sendFax({ faxId: draft.faxId, confirm: true, maxPriceCents: draft.quote.priceCents }) const status = await faxStatus({ faxId: draft.faxId }) ``` A call with an unknown key must fail: ```ts await sendFax({ faxId: 'cmr4...', confirmed: true }) // throws: input rejected ``` ## Edge cases - Every export rejects unknown input keys (`remix/data-schema` with `unknownKeys: 'error'`). There are no aliases: it is `recipientNumber`, not `to`, and `confirm`, not `confirmed`. - `send-fax` never sends unless `confirm === true`. `dryRun: true` wins over `confirm`. Both return `{ sent: false, reason, preview }` with recipient, files, page count, and quote so a person can approve the exact details. - With `confirm: true`, `send-fax` re-reads the fax and throws before sending when files are not all `ready`, `quote` is null, `shortfallCents > 0`, or `priceCents > maxPriceCents`. The API itself returns 409 while files process and 402 with the shortfall and a top-up path when credits are short; those surface as `OnetimeFaxApiError` with `status` and `body`. - Sending the same fax id again returns the original charge with `replayed: true` and no second debit (documented API behavior). - `recipientNumber` must be E.164. Spaces, dashes, dots, and parentheses are stripped before the check. - Each file needs exactly one of `base64`, `text`, or `url`. `url` must be HTTPS and is downloaded with a plain fetch that never carries the API key. Do not use `url` for documents that should not be public. Files over 25 MB are refused (the limit listed in the MCP announcement). - `prepare-fax` polls `GET /api/v1/faxes/{id}` every 2 seconds for up to `waitForQuoteMs` (default 30000, max 120000). If the quote is not ready in time it returns `readyToSend: false`; poll `./fax-status` later. A draft is created as soon as `prepare-fax` runs without `dryRun`, even if a later upload fails; the error names the draft id. - `faxId` and `fileId` must be letters, digits, `-` or `_`, so they cannot change the request path. - Credits cannot be bought through the API. Point the person to the developer console. - Never log, return, or echo the API key. The Kody gateway redacts it if the API ever echoes it.