← 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.
Files
/**
* Internal helper for the Onetime Fax developer API. Not a package export.
*
* Docs: https://www.onetimefax.com/developers/
* Every request sends `Authorization: Bearer <key>`. The key is never in
* this file: Kody fills the `{{secret:onetimefax-api-token}}` placeholder at
* the network boundary, only for hosts the owner approved on that secret.
*/
export const ONETIMEFAX_API_BASE = 'https://app.onetimefax.com'
/** Save your Onetime Fax API key as the Kody secret `onetimefax-api-token`. Never commit a value. */
const AUTHORIZATION = 'Bearer {{secret:onetimefax-api-token}}'
export type OnetimeFaxFile = {
id: string
filename?: string
contentType?: string
sizeBytes?: number
pageCount?: number | null
status?: string
order?: number
createdAt?: string
}
export type OnetimeFaxQuote = {
priceCents: number
creditBalanceCents: number
shortfallCents: number
}
export type OnetimeFax = {
id: string
recipientNumber?: string
status?: string
createdAt?: string
files?: OnetimeFaxFile[]
pageCount?: number | null
quote?: OnetimeFaxQuote | null
creditsConsumedCents?: number | null
[key: string]: unknown
}
export class OnetimeFaxApiError extends Error {
status: number
body: unknown
constructor(method: string, path: string, status: number, body: unknown) {
super(
`Onetime Fax ${method} ${path} failed with HTTP ${status}${describeBody(body)}`,
)
this.name = 'OnetimeFaxApiError'
this.status = status
this.body = body
}
}
function describeBody(body: unknown) {
if (body === null || body === undefined || body === '') return '.'
const text = typeof body === 'string' ? body : JSON.stringify(body)
return `: ${text.length > 500 ? `${text.slice(0, 500)}...` : text}`
}
/** True when a fax id is safe to put in a URL path segment. */
export function assertFaxId(value: string, field = 'faxId') {
const trimmed = value.trim()
if (!/^[A-Za-z0-9_-]{1,128}$/.test(trimmed)) {
throw new Error(
`${field} must be the id returned by Onetime Fax (letters, digits, "-" or "_").`,
)
}
return trimmed
}
/**
* Call the Onetime Fax API with the bearer key placeholder.
* `x-kody-secret-resolution: headers-only` keeps Kody from filling any
* placeholder text that might appear inside an uploaded document or body.
*/
export async function onetimefaxRequest<T = unknown>(
method: 'GET' | 'POST' | 'DELETE',
path: string,
init: { json?: unknown; formData?: FormData } = {},
): Promise<{ status: number; data: T }> {
const url = `${ONETIMEFAX_API_BASE}${path}`
// Header objects stay literal so `kody dev check` can see headers-only.
const response =
init.json !== undefined
? await fetch(url, {
method,
headers: {
Authorization: AUTHORIZATION,
Accept: 'application/json',
'Content-Type': 'application/json',
'x-kody-secret-resolution': 'headers-only',
},
body: JSON.stringify(init.json),
})
: await fetch(url, {
method,
headers: {
Authorization: AUTHORIZATION,
Accept: 'application/json',
'x-kody-secret-resolution': 'headers-only',
},
body: init.formData,
})
const text = response.status === 204 ? '' : await response.text()
let data: unknown = text
if (text) {
try {
data = JSON.parse(text)
} catch {
data = text
}
}
if (!response.ok) {
throw new OnetimeFaxApiError(method, path, response.status, data)
}
return { status: response.status, data: data as T }
}
/** Format an issue list from remix/data-schema into one readable error. */
export function inputError(
exportName: string,
accepted: string,
issues: Array<{ message?: string; path?: unknown }>,
) {
const detail = issues
.map((issue) => {
const path = Array.isArray(issue.path) && issue.path.length
? `${issue.path
.map((part) =>
part && typeof part === 'object' && 'key' in part
? String((part as { key: unknown }).key)
: String(part),
)
.join('.')}: `
: ''
return `${path}${issue.message ?? 'invalid'}`
})
.join('; ')
return new Error(
`${exportName} input rejected${detail ? `: ${detail}` : ''}. Accepted keys: ${accepted}.`,
)
}