TypeScript integration
A typed submission client for the Postvia public API.
type PostviaSuccess = {
success: true
submission_id: string
message: string
}
type PostviaErrorBody = {
success: false
error: {
code: string
message: string
fields?: Record<string, string[]>
}
request_id: string
}
type PostviaError = Error & {
status: number
code?: string
fields?: Record<string, string[]>
requestId?: string
retryAfter?: string | null
}
export async function submitToPostvia(
publicId: string,
fields: Record<string, unknown>,
options: { turnstileToken?: string, idempotencyKey?: string } = {},
): Promise<PostviaSuccess> {
const key = options.idempotencyKey ?? crypto.randomUUID()
const response = await fetch(
`https://api.postvia.dev/v1/forms/${publicId}/submissions`,
{
method: 'POST',
headers: {
Accept: 'application/json',
'Content-Type': 'application/json',
'Idempotency-Key': key,
},
body: JSON.stringify({
...fields,
...(options.turnstileToken
? { 'cf-turnstile-response': options.turnstileToken }
: {}),
}),
},
)
if (response.ok) return response.json() as Promise<PostviaSuccess>
const body = (await response.json()) as PostviaErrorBody
const error = new Error(body.error?.message ?? 'Submission failed') as PostviaError
error.status = response.status
error.code = body.error?.code
error.fields = body.error?.fields
error.requestId = body.request_id
error.retryAfter = response.headers.get('Retry-After')
throw error
}
The request body is intentionally open: customer-defined fields are allowed. Keep your own form-specific type around the values.
Type the form values separately and pass them as
Record<string, unknown>; the API does not fix a global field schema.