/** * Internal helper for the Onetime Fax developer API. Not a package export. * * Docs: https://www.onetimefax.com/developers/ * Every request sends `Authorization: Bearer `. 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( 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}.`, ) }