Skip to content
← Public packages

@kody/onetimefax

Head-start stub for sending faxes from Kody with the Onetime Fax developer API. Fork it and add your API key.

FollowFork

Files

AGENTS.md

89 lines · 5.6 KB · Markdown

@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.

ExportEndpoint(s)Side effects
./accountGET /api/v1/accountnone
./prepare-faxPOST /api/v1/faxes, POST /api/v1/faxes/{id}/files, GET /api/v1/faxes/{id}creates a draft, no charge
./send-faxGET /api/v1/faxes/{id}, then POST /api/v1/faxes/{id}/send only with confirm: truespends credits
./fax-statusGET /api/v1/faxes/{id}none
./remove-fileDELETE /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:

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 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.