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

client.ts

147 lines · 4.0 KB · TypeScript
/**
 * 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}.`,
	)
}