Gamma Local Dev Loop

Output

Create a local validation receipt with fixture version, schema result, owner, and redacted failure reference. Never commit private presentations, viewer data, or secrets.

Examples

Run offline tests using fictional presentation fixtures, verify logs are redacted and no production credential is required, then remove temporary artifacts after validation.

Overview

Set up an efficient local development workflow for Gamma API integrations. Since Gamma is a REST API with no SDK, the dev loop centers on HTTP request/response testing, mock servers for offline development, and a reusable client wrapper.

Prerequisites

• Completed gamma-install-auth setup
• Node.js 18+ with tsx for TypeScript execution
• GAMMA_API_KEY in .env

Instructions

Step 1: Project Structure

gamma-integration/
├── src/
│   ├── client.ts          # Reusable Gamma API client
│   ├── generate.ts        # Generation workflows
│   └── poll.ts            # Polling helper
├── test/
│   ├── mock-server.ts     # Local mock for offline dev
│   └── integration.test.ts
├── .env                   # GAMMA_API_KEY (gitignored)
├── .env.example           # Template without secrets
├── package.json
└── tsconfig.json

Step 2: Reusable Client Wrapper

// src/client.ts
import "dotenv/config";

const GAMMA_BASE = "https://public-api.gamma.app/v1.0";

export interface GammaClient {
  generate(body: GenerateRequest): Promise<GenerateResponse>;
  poll(generationId: string): Promise<PollResponse>;
  listThemes(): Promise<Theme[]>;
  listFolders(): Promise<Folder[]>;
}

export function createClient(apiKey?: string, baseUrl?: string): GammaClient {
  const key = apiKey ?? process.env.GAMMA_API_KEY;
  if (!key) throw new Error("GAMMA_API_KEY required");
  const base = baseUrl ?? GAMMA_BASE;
  const headers = { "X-API-KEY": key, "Content-Type": "application/json" };

  async function request(method: string, path: string, body?: unknown) {
    const res = await fetch(`${base}${path}`, {
      method,
      headers,
      body: body ? JSON.stringify(body) : undefined,
    });
    if (!res.ok) {
      const text = await res.text();
      throw new Error(`Gamma ${res.status}: ${text}`);
    }
    return res.json();
  }

  return {
    generate: (body) => request("POST", "/generations", body),
    poll: (id) => request("GET", `/generations/${id}`),
    listThemes: () => request("GET", "/themes"),
    listFolders: () => request("GET", "/folders"),
  };
}

Step 3: Poll Helper with Timeout

// src/poll.ts
import type { GammaClient } from "./client";

export async function waitForCompletion(
  client: GammaClient,
  generationId: string,
  opts = { intervalMs: 5000, timeoutMs: 120000 }
) {
  const deadline = Date.now() + opts.timeoutMs;
  while (Date.now() < deadline) {
    const result = await client.poll(generationId);
    if (result.status === "completed") return result;
    if (result.status === "failed") throw new Error(`Generation failed: ${result.error}`);
    await new Promise((r) => setTimeout(r, opts.intervalMs));
  }
  throw new Error(`Poll timeout after ${opts.timeoutMs}ms`);
}

Step 4: Mock Server for Offline Dev

// test/mock-server.ts
import http from "node:http";

const MOCK_PORT = 9876;
const generations = new Map<string, { status: string; tick: number }>();

const server = http.createServer((req, res) => {
  res.setHeader("Content-Type", "application/json");

  // POST /v1.0/generations
  if (req.method === "POST" && req.url === "/v1.0/generations") {
    const id = `mock_${Date.now()}`;
    generations.set(id, { status: "in_progress", tick: 0 });
    res.end(JSON.stringify({ generationId: id }));
    return;
  }

  // GET /v1.0/generations/:id — completes after 3 polls
  const pollMatch = req.url?.match(/\/v1\.0\/generations\/(.+)/);
  if (req.method === "GET" && pollMatch) {
    const gen = generations.get(pollMatch[1]);
    if (!gen) { res.writeHead(404); res.end("{}"); return; }
    gen.tick++;
    if (gen.tick >= 3) gen.status = "completed";
    res.end(JSON.stringify({
      generationId: pollMatch[1],
      status: gen.status,
      ...(gen.status === "completed" && {
        gammaUrl: `https://gamma.app/docs/mock-${pollMatch[1]}`,
        exportUrl: `https://export.gamma.app/mock.pdf`,
        creditsUsed: 10,
      }),
    }));
    return;
  }

  // GET /v1.0/themes
  if (req.url === "/v1.0/themes") {
    res.end(JSON.stringify([
      { id: "theme_1", name: "Professional" },
      { id: "theme_2", name: "Modern" },
    ]));
    return;
  }

  // GET /v1.0/folders
  if (req.url === "/v1.0/folders") {
    res.end(JSON.stringify([{ id: "folder_1", name: "Test Folder" }]));
    return;
  }

  res.writeHead(404);
  res.end("{}");
});

server.listen(MOCK_PORT, () => console.log(`Mock Gamma API on :${MOCK_PORT}`));

Step 5: Development Scripts

{
  "scripts": {
    "dev:mock": "tsx test/mock-server.ts",
    "dev:generate": "tsx src/generate.ts",
    "test": "vitest run",
    "test:integration": "GAMMA_BASE=http://localhost:9876/v1.0 vitest run test/integration"
  }
}

Step 6: Integration Test

// test/integration.test.ts
import { describe, it, expect } from "vitest";
import { createClient } from "../src/client";
import { waitForCompletion } from "../src/poll";

const BASE = process.env.GAMMA_BASE ?? "http://localhost:9876/v1.0";

describe("Gamma API", () => {
  const client = createClient("test-key", BASE);

  it("generates and polls to completion", async () => {
    const { generationId } = await client.generate({
      content: "Test presentation",
      outputFormat: "presentation",
    });
    expect(generationId).toBeTruthy();

    const result = await waitForCompletion(client, generationId);
    expect(result.status).toBe("completed");
    expect(result.gammaUrl).toContain("gamma.app");
  });

  it("lists workspace themes", async () => {
    const themes = await client.listThemes();
    expect(themes.length).toBeGreaterThan(0);
  });
});

Dev Loop Summary

Activity	Command	Hits Live API?
Start mock server	npm run dev:mock	No
Generate (mock)	GAMMA_BASE=http://localhost:9876/v1.0 npm run dev:generate	No
Run tests	npm test (uses mock)	No
Live API test	GAMMA_API_KEY=gma_... tsx src/generate.ts	Yes

Error Handling

Issue	Cause	Fix
GAMMA_API_KEY required	Missing env var	Add to .env or export
Mock returns 404	Wrong mock port/path	Verify GAMMA_BASE points to mock
Poll timeout locally	Mock tick count too high	Reduce tick threshold
fetch is not defined	Node.js < 18	Upgrade to Node.js 18+

Resources

• Gamma Developer Docs
• Generate API Parameters

Next Steps

Proceed to gamma-sdk-patterns for reusable API wrapper patterns.