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.