TypeScript SDK

TypeScript SDK (planned)

A typed client for the pptx.dev REST API is planned. It is not published to any package registry, so there is nothing to install today. The examples below show the intended API shape; call the REST API directly in the meantime.

← REST API reference OPF reference →CLI →

Availability

Not available yet

No @pptx/sdk package is published, so there is no install command. Until it ships, use fetch against the REST API, or the open source @openpresentation/opf package for local OPF validation.

First call

Create a client with your Clerk API key and validate an OPF document. Validation is always free.

TypeScript

import { PptxClient } from "@pptx/sdk";

const pptx = new PptxClient({ apiKey: process.env.PPTX_API_KEY });

const result = await pptx.opf.validate({
  $schema: "https://openpresentation.org/schema/opf/v1",
  name: "Hello",
  slides: [{ title: "Hello, world" }]
});

console.log(result.valid, result.errors, result.warnings);

Authentication

The client resolves a bearer token in this order:

The apiKey option passed to the constructor.
The PPTX_API_KEY environment variable (Node / Bun runtimes only).

TypeScript

import { PptxClient } from "@pptx/sdk";

const pptx = new PptxClient({ apiKey: "ak_..." });

Get your Clerk API key from the API Keys page.

Generate a .pptx from OPF

TypeScript

import { writeFile } from "node:fs/promises";
import { PptxClient } from "@pptx/sdk";

const pptx = new PptxClient();

const doc: Record<string, unknown> = {
  $schema: "https://openpresentation.org/schema/opf/v1",
  name: "Q1 Review",
  filename: "q1-review",
  slides: [{ title: "Q1 Review" }]
};

const result = await pptx.opf.generate(doc, { format: "pptx" });
await writeFile(result.filename ?? "q1-review.pptx", Buffer.from(result.bytes));
console.log(result.filename, result.slideCount);

Parse an existing .pptx

TypeScript

import { readFile } from "node:fs/promises";
import { PptxClient } from "@pptx/sdk";

const pptx = new PptxClient();
const bytes = await readFile("deck.pptx");

const { parseId, slideCount } = await pptx.parse.upload({
  data: bytes,
  filename: "deck.pptx",
});

const slide0 = await pptx.parse.slide(parseId, 0);
console.log(slide0.textRuns);

Error handling

All errors extend PptxError.

Error	When
PptxNetworkError	fetch threw (DNS, TLS, timeout, aborted)
PptxApiError	HTTP 4xx / 5xx response with JSON or text body
PptxValidationError	HTTP 422 with validationErrors[] from `opf.generate`
PptxRateLimitError	HTTP 429 (exposes `retryAfterSeconds`)

TypeScript

import {
  PptxValidationError,
  PptxRateLimitError,
} from "@pptx/sdk";

try {
  await pptx.opf.generate(badDoc);
} catch (err) {
  if (err instanceof PptxValidationError) {
    console.error("OPF schema errors:", err.validationErrors);
  } else if (err instanceof PptxRateLimitError) {
    console.error("Retry after:", err.retryAfterSeconds, "s");
  } else {
    throw err;
  }
}

Every error exposes requestId when the server returned an X-Request-Id header.

OPF types

The SDK's historical OPF helper types still describe the retired meta/elements format. Use canonical JSON through the client's Record input until those helpers migrate (tracked in issue #136). For current static types, use the schema-matching core package.

TypeScript

import type { Presentation } from "@openpresentation/opf/types";

Custom base URL

For local development against a Next.js dev server:

TypeScript

const pptx = new PptxClient({
  baseUrl: "http://localhost:3000/api",
});