Learn idiomatic Gamma SDK patterns and best practices. Use when implementing complex presentation workflows, handling async operations, or structuring Gamma code. Trigger with phrases like "gamma patterns", "gamma best practices", "gamma SDK usage", "gamma async", "gamma code structure".
npxskills add jeremylongshore/claude-code-plugins-plus-skills--skill gamma-sdk-patternsLoading…
Gamma has no published SDK — all interaction is via REST at https://public-api.gamma.app/v1.0/. This skill provides production-grade patterns for typed clients, generation helpers, polling, template workflows, and error handling.
gamma-install-auth setupfetch (Node.js 18+)// lib/gamma.ts
const GAMMA_BASE = "https://public-api.gamma.app/v1.0";
interface GammaConfig {
apiKey: string;
baseUrl?: string;
timeoutMs?: number;
}
// Types based on actual API responses
interface GenerateRequest {
content: string;
outputFormat?: "presentation" | "document" | "webpage" | "social_post";
themeId?: string;
exportAs?: "pdf" | "pptx" | "png";
textMode?: "generate" | "condense" | "preserve";
textAmount?: "brief" | "medium" | "detailed" | "extensive";
imageOptions?: { style?: string };
sharingOptions?: {
workspaceAccess?: "noAccess" | "view" | "comment" | "edit" | "fullAccess";
externalAccess?: "noAccess" | "view" | "comment" | "edit" | "fullAccess";
};
folderIds?: string[];
}
interface GenerateResult {
generationId: string;
status: "in_progress" | "completed" | "failed";
gammaUrl?: string;
exportUrl?: string;
creditsUsed?: number;
}
let instance: ReturnType<typeof createGammaClient> | null = null;
export function getGamma() {
if (!instance) {
instance = createGammaClient({
apiKey: process.env.GAMMA_API_KEY!,
});
}
return instance;
}
export function createGammaClient(config: GammaConfig) {
const base = config.baseUrl ?? GAMMA_BASE;
const headers: Record<string, string> = {
"X-API-KEY": config.apiKey,
"Content-Type": "application/json",
};
async function request<T>(method: string, path: string, body?: unknown): Promise<T> {
const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), config.timeoutMs ?? 30000);
try {
const res = await fetch(`${base}${path}`, {
method,
headers,
body: body ? JSON.stringify(body) : undefined,
signal: controller.signal,
});
if (!res.ok) {
const text = await res.text();
throw new GammaApiError(res.status, text, path);
}
return res.json() as T;
} finally {
clearTimeout(timeout);
}
}
return {
generate: (body: GenerateRequest) =>
request<{ generationId: string }>("POST", "/generations", body),
generateFromTemplate: (body: TemplateRequest) =>
request<{ generationId: string }>("POST", "/generations/from-template", body),
poll: (id: string) =>
request<GenerateResult>("GET", `/generations/${id}`),
getFileUrls: (id: string) =>
request<{ exportUrl: string }>("GET", `/generations/${id}/files`),
listThemes: () => request<Theme[]>("GET", "/themes"),
listFolders: () => request<Folder[]>("GET", "/folders"),
};
}
// lib/errors.ts
export class GammaApiError extends Error {
constructor(
public status: number,
public body: string,
public path: string
) {
super(`Gamma API ${status} on ${path}: ${body}`);
this.name = "GammaApiError";
}
get isRateLimit() { return this.status === 429; }
get isAuth() { return this.status === 401 || this.status === 403; }
get isServerError() { return this.status >= 500; }
}
// lib/poll.ts
export async function pollUntilDone(
gamma: ReturnType<typeof createGammaClient>,
generationId: string,
opts = { intervalMs: 5000, timeoutMs: 180000 }
): Promise<GenerateResult> {
const deadline = Date.now() + opts.timeoutMs;
while (Date.now() < deadline) {
const result = await gamma.poll(generationId);
if (result.status === "completed") return result;
if (result.status === "failed") {
throw new Error(`Generation ${generationId} failed`);
}
await new Promise((r) => setTimeout(r, opts.intervalMs));
}
throw new Error(`Poll timeout for ${generationId} after ${opts.timeoutMs}ms`);
}
// lib/generate.ts
export async function generateAndWait(
gamma: ReturnType<typeof createGammaClient>,
request: GenerateRequest
): Promise<GenerateResult> {
const { generationId } = await gamma.generate(request);
console.log(`Generation started: ${generationId}`);
return pollUntilDone(gamma, generationId);
}
// Usage
const gamma = getGamma();
const result = await generateAndWait(gamma, {
content: "Quarterly business review for Q1 2026",
outputFormat: "presentation",
themeId: "theme_abc123",
exportAs: "pptx",
textAmount: "medium",
imageOptions: { style: "photorealistic corporate" },
});
console.log(`View: ${result.gammaUrl}`);
console.log(`Download: ${result.exportUrl}`);
// lib/templates.ts
// Uses POST /v1.0/generations/from-template
// The template gamma must contain exactly one page
interface TemplateRequest {
gammaId: string; // Template gamma ID (one-page template)
prompt: string; // Content + instructions for the template
themeId?: string;
exportAs?: "pdf" | "pptx" | "png";
imageOptions?: { style?: string };
sharingOptions?: object;
folderIds?: string[];
}
export async function generateFromTemplate(
gamma: ReturnType<typeof createGammaClient>,
templateId: string,
prompt: string,
options: Partial<TemplateRequest> = {}
): Promise<GenerateResult> {
const { generationId } = await gamma.generateFromTemplate({
gammaId: templateId,
prompt,
...options,
});
return pollUntilDone(gamma, generationId);
}
// lib/retry.ts
export async function withRetry<T>(
fn: () => Promise<T>,
maxRetries = 3,
baseDelayMs = 1000
): Promise<T> {
for (let attempt = 0; attempt <= maxRetries; attempt++) {
try {
return await fn();
} catch (err) {
if (attempt === maxRetries) throw err;
if (err instanceof GammaApiError && !err.isRateLimit && !err.isServerError) {
throw err; // Don't retry auth errors or 4xx
}
const delay = baseDelayMs * Math.pow(2, attempt);
console.warn(`Retry ${attempt + 1}/${maxRetries} in ${delay}ms`);
await new Promise((r) => setTimeout(r, delay));
}
}
throw new Error("Unreachable");
}
// Usage
const result = await withRetry(() =>
generateAndWait(gamma, { content: "My deck", outputFormat: "presentation" })
);
| Method | Endpoint | Purpose |
|---|---|---|
| POST | /v1.0/generations | Generate from text content |
| POST | /v1.0/generations/from-template | Generate from a template gamma |
| GET | /v1.0/generations/{id} | Poll generation status |
| GET | /v1.0/generations/{id}/files | Get export file URLs |
| GET | /v1.0/themes | List workspace themes |
| GET | /v1.0/folders | List workspace folders |
| Pattern | Use Case |
|---|---|
GammaApiError class | Typed error handling with isRateLimit, isAuth, isServerError |
withRetry() | Auto-retry on 429/5xx with exponential backoff |
pollUntilDone() | Timeout-aware polling with configurable interval |
Singleton getGamma() | Consistent config across modules |
Proceed to gamma-core-workflow-a for content generation workflows.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).