@kody/onetimefax
Head-start stub for sending faxes from Kody with the Onetime Fax developer API. Fork it and add your API key.
Files
@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
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.credentialsasonetimefax-api-token(kind: "secret",provider: "onetimefax"). - The secret must allow host
app.onetimefax.comonly. 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_approvalson publish. Send the owner theapproval_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 Kodymcpcredential and called withcredential(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:
kody execute --local --invoke kody:@kody/onetimefax/account --params '{}'No-network checks:
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):
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:
await sendFax({ faxId: 'cmr4...', confirmed: true }) // throws: input rejectedEdge cases
- Every export rejects unknown input keys (
remix/data-schemawithunknownKeys: 'error'). There are no aliases: it isrecipientNumber, notto, andconfirm, notconfirmed. send-faxnever sends unlessconfirm === true.dryRun: truewins overconfirm. 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-faxre-reads the fax and throws before sending when files are not allready,quoteis null,shortfallCents > 0, orpriceCents > 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 asOnetimeFaxApiErrorwithstatusandbody. - Sending the same fax id again returns the original charge with
replayed: trueand no second debit (documented API behavior). recipientNumbermust be E.164. Spaces, dashes, dots, and parentheses are stripped before the check.- Each file needs exactly one of
base64,text, orurl.urlmust be HTTPS and is downloaded with a plain fetch that never carries the API key. Do not useurlfor documents that should not be public. Files over 25 MB are refused (the limit listed in the MCP announcement). prepare-faxpollsGET /api/v1/faxes/{id}every 2 seconds for up towaitForQuoteMs(default 30000, max 120000). If the quote is not ready in time it returnsreadyToSend: false; poll./fax-statuslater. A draft is created as soon asprepare-faxruns withoutdryRun, even if a later upload fails; the error names the draft id.faxIdandfileIdmust 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.