# @kody/onetimefax Head-start package for sending faxes from Kody with the [Onetime Fax developer API](https://www.onetimefax.com/developers/). Fork it, add your own API key, and build your fax workflow on top. ## Intent Give people a working starting point for integrating Onetime Fax with Kody, so they do not have to read the API reference and wire up auth, uploads, quotes, and sending from scratch. It covers the documented developer preview flow: prepare a fax (draft, upload, quote) without spending anything, send it only after an explicit confirm, and check its status. Success means a fork can read its account balance with its own key, prepare a fax and see the price, send it, and follow delivery. This is a starter, not a finished product. It only wraps endpoints Onetime Fax documents today. The API is marked "developer preview", so check their docs if something changes. ## What it can do | Export | What it does | Spends credits? | | --- | --- | --- | | `account` | Shows your Onetime Fax account name and prepaid credit balance. Good first test. | No | | `prepare-fax` | Creates a draft fax to a number, uploads your documents, and waits for the page count and price. | No | | `send-fax` | Sends a prepared fax. Without `confirm: true` it only shows a preview. | Yes, with confirm | | `fax-status` | Shows the draft quote, or delivery status after sending. Also the default export. | No | | `remove-file` | Removes a document from an unsent draft so you can replace it. | No | Onetime Fax does not document a "list faxes" endpoint, so this package does not have one. Keep the fax ids you get back. ## When to use - You want Kody (or an agent using Kody) to send a fax from a document or text. - You want a quote shown to a person before anything is charged. - You want to check whether a fax you sent went through. Do not use it to buy credits. Credits are added by a person in the Onetime Fax developer console. ## Setup 1. **Fork this package.** Open [kody.codes/@kody/onetimefax](https://kody.codes/@kody/onetimefax) and choose Fork. Your copy lives under your own account, and you can change anything in it. 2. **Create a Onetime Fax developer account.** Sign up at [app.onetimefax.com/developers/signup](https://app.onetimefax.com/developers/signup) and verify your email. 3. **Add prepaid credits** in the [Onetime Fax developer console](https://app.onetimefax.com/developers). Sending charges that balance. Preparing a fax and getting a quote are free. 4. **Create an API key** in the developer console. It starts with `otf_live_`. 5. **Save the key in Kody** as a secret named `onetimefax-api-token`, allowed only for `app.onetimefax.com`. This link prefills the form: [Add onetimefax-api-token](https://kody.codes/account/secrets/new?name=onetimefax-api-token&description=Onetime%20Fax%20developer%20API%20key&allowedHosts=app.onetimefax.com&scope=user). Paste the key into that page only. Never paste it into a chat, a commit, or the package source. 6. **Approve the fork's access to the secret** if Kody asks. Community forks need the owner to review and adopt them on the website before they can use your secrets. 7. **Test it.** Ask your agent to run the `account` export. You should see your account name and credit balance. Then prepare a fax to a number you control (a test or your own fax line), check the quote, and send it with confirm. ### Prefer OAuth? Onetime Fax also runs a remote MCP server at `https://app.onetimefax.com/mcp` that signs in with OAuth instead of an API key. See their [MCP announcement](https://www.onetimefax.com/blog/onetime-fax-mcp-server/). You can connect it in Kody as an MCP server credential and let an agent use its tools directly. This package uses the REST API with a bearer key because that API is publicly documented. The MCP tool list is only visible after you sign in, so this starter does not wrap it. Either path uses the same account and the same prepaid credits. ## Done when - `account` returns your account name and credit balance. - `prepare-fax` returns a fax id, a page count, and a price, and nothing is charged. - `send-fax` without confirm shows the preview; with `confirm: true` it returns `sent: true` and the credits used. - `fax-status` shows the fax moving from `queued` to a delivery result. ## Ideas for your fork - Add a cover page or build the document from a template before uploading. - Wire `send-fax` behind a human approval step in your own workflow. - Run a job that checks `fax-status` until delivery finishes and notifies you. ## Credits and license MIT. Onetime Fax is a product of High Velocity Acorns, LLC. This package is a community starter and is not made by Onetime Fax. There is no package icon because no clearly licensed Onetime Fax logo was found.