TypeScript SDK

Official TypeScript/JavaScript SDK for PageGun.

Installation

npm install @pagegun/sdk
# or
pnpm add @pagegun/sdk
# or
yarn add @pagegun/sdk

API Client

The PageGun class provides a typed interface to the REST API:

import { PageGun } from '@pagegun/sdk'

const pg = new PageGun('pgk_live_xxxxx')

Projects

// List all projects
const { data: projects, has_more, total } = await pg.projects.list()

// Get a project
const project = await pg.projects.get('project-id')

// Create a project
const newProject = await pg.projects.create({ name: 'My Site' })

// Update a project
await pg.projects.update('project-id', { name: 'New Name' })

Pages

// List pages for a project
const { data: pages } = await pg.pages.list({ project_id: 'abc123' })

// Create a page
const page = await pg.pages.create({
  page_name: 'Getting Started',
  slug: 'getting-started',
  subroute: 'docs',
  type: 'docs',
  project_id: 'abc123',
  config: {},
  markdown_content: '# Getting Started\n\nWelcome!',
})

// Update a page
await pg.pages.update(page.id, {
  markdown_content: '# Getting Started\n\nUpdated content!',
})

// Publish
await pg.pages.publish(page.id)

// Unpublish
await pg.pages.unpublish(page.id)

Settings

// Get project settings
const settings = await pg.settings.get('project-id')

// Update settings (merges with existing)
await pg.settings.update('project-id', {
  docs_nav: { sections: [...] },
})

Data Mode

// Check status
const status = await pg.dataMode.status('project-id')

// Enable (returns encryption key — save it!)
const { contentKey } = await pg.dataMode.enable('project-id')

// Disable
await pg.dataMode.disable('project-id')

// Regenerate key (re-encrypts all content)
const { contentKey: newKey, pagesProcessed } =
  await pg.dataMode.regenerateKey('project-id')

Pagination

// First page
const page1 = await pg.projects.list({ limit: 10, offset: 0 })

// Next page
if (page1.has_more) {
  const page2 = await pg.projects.list({ limit: 10, offset: 10 })
}

// Iterate all
let offset = 0
let allProjects = []
while (true) {
  const { data, has_more } = await pg.projects.list({ limit: 100, offset })
  allProjects.push(...data)
  if (!has_more) break
  offset += 100
}

Data Mode Client

The PageGunContent class fetches and decrypts content from CDN:

import { PageGunContent } from '@pagegun/sdk'

const content = new PageGunContent({
  projectId: 'abc123',
  contentKey: 'your-base64-encryption-key',
})

// Get a page by slug
const page = await content.getPage('articles/hello-world')
console.log(page?.content.title)
console.log(page?.content.markdown_content)

// List all pages
const pages = await content.listPages({ locale: 'en' })

// Filter by subroute
const docs = await content.listPages({ subroute: 'docs' })

// Get the content index
const index = await content.getIndex()

Caching

Content is cached in memory by default (60s TTL):

// Custom TTL
const content = new PageGunContent({
  projectId: 'abc123',
  contentKey: 'key',
  cacheTTL: 300_000, // 5 minutes
})

// Disable cache
const content = new PageGunContent({
  projectId: 'abc123',
  contentKey: 'key',
  cache: false,
})

// Clear cache manually
content.clearCache()

Error Handling

import { PageGun, PageGunError } from '@pagegun/sdk'

const pg = new PageGun('pgk_live_xxxxx')

try {
  await pg.projects.get('invalid-id')
} catch (err) {
  if (err instanceof PageGunError) {
    console.error(err.code)     // 'not_found'
    console.error(err.message)  // 'Project not found'
    console.error(err.status)   // 404
    console.error(err.docUrl)   // 'https://pagegun.com/docs/...'
  }
}

Requirements

Node.js 18+ (uses native fetch and crypto)
TypeScript 5+ (for type definitions)