@ircg/pgs

Server-side SDK for IRCG PDF Generation. PGS renders an allowlisted HTTPS URL and returns an ephemeral PDF stream.

import { PGSClient } from '@ircg/pgs'
import { writeFile } from 'node:fs/promises'

const pgs = new PGSClient({ apiKey: process.env.IRCG_PGS_API_KEY! })
const result = await pgs.generate({
	fileName: 'invoice.pdf',
	timeoutSeconds: 10,
	url: 'https://example.com/invoice/123',
})
if (result.error) throw new Error(result.error.message)
await writeFile('invoice.pdf', Buffer.from(await result.response.arrayBuffer()))

Dry run

Dry-run mode returns a minimal valid PDF without making an HTTP request or consuming credits:

const pgs = new PGSClient({ apiKey: 'unused', dryRun: true })
const result = await pgs.generate({ fileName: 'invoice.pdf', url: 'https://example.com/invoice/123' })

if (!result.error) console.log(result.billing, (await result.response.arrayBuffer()).byteLength)

Both generate() and generateUnsafe() return a streamable synthetic PDF. This mode exercises the SDK integration but does not load the URL or validate authentication, allowlists, timeouts or other server-side rendering rules. It does apply the public fileName format and returns Cache-Control: no-store, matching the production response contract.

By default, PGS uses a 10-second timeout, screen CSS, waits for a stable network, generates A4 pages and includes background graphics. timeoutSeconds accepts an integer from 5 to 60. Use mediaType, waitUntil and pdfOptions to override the appearance and readiness settings for print-specific documents or faster captures. The timeout stops a stalled load and caps the maximum possible charge at timeoutSeconds × 3 credits, so choose it according to the page's expected load time.

Do not place a PGS API key in browser JavaScript. PGS does not store generated PDFs. A failed render consumes credits only when the rendering infrastructure reports billable browser time; inspect result.error.details for billing metadata. PGS does not currently accept an idempotency key or replay a generated binary, so do not automatically retry generate() calls. Free and paid subscriptions use the same render timeout. A free subscription reserves timeoutSeconds × 3 credits before rendering and returns the unused portion afterward; paid subscriptions do not reserve credits in advance. In both cases, the final charge corresponds only to the measured billable seconds.