PromptsGptClient

The PromptsGptClient class provides HTTP access to the prompts-gpt.com API for pulling prompts, generating prompt packs, fetching models, and retrieving project information.

Constructor

import { PromptsGptClient } from "prompts-gpt";

const client = new PromptsGptClient({
  apiUrl: "https://prompts-gpt.com",
  token: "pgpt_your_token_here",
  fetch: globalThis.fetch,
  timeoutMs: 30_000,          // optional, default 30s
  accountId: "acct_123",      // optional
});

ClientOptions

Security

• Refuses to send credentials over unencrypted HTTP (except to localhost)
• Token must start with pgpt_ prefix
• Max timeout capped at 600 seconds

Methods

getProject()

Fetch the project context linked to the current token.

const project = await client.getProject();
// Returns: ProjectContext

Returns: ProjectContext

{
  id: string;
  brandName: string;
  websiteUrl: string;
  industryCategory: string;
  targetCountries: string[];
  targetLanguage: string;
  brandAliases: string[];
  productKeywords: string[];
  targetPersonas: string[];
  competitors: Array<{
    name: string;
    websiteUrl: string | null;
    aliases: string[];
  }>;
}

pullPrompts()

Download prompt packs from the project library.

const prompts = await client.pullPrompts({
  q: "security",
  category: "Code Review",
  tool: "Codex",
  outputType: "Markdown",
  limit: 10,
});
// Returns: PromptPack[]

Parameters: PullPromptsQuery

Returns: PromptPack[]

fetchModels()

Fetch available models from the registry.

const models = await client.fetchModels({ provider: "codex" });
// Returns: Record<string, string[]>

generatePrompt()

Generate a new prompt pack from a goal using AI.

const prompt = await client.generatePrompt({
  goal: "Review PRs for security issues",
  context: "Next.js + Prisma + Supabase",
  constraints: "Must check for SQL injection",
  desiredOutput: "Checklist format",
  tool: "Codex",
  mode: "implement",
  includeWebSearch: true,
});
// Returns: PromptPack

Parameters: GeneratePromptInput

Timeout: 60 seconds (vs 30s default for other methods).

Request Options

All methods accept an optional ClientRequestOptions:

const project = await client.getProject({
  timeoutMs: 10_000,
  signal: abortController.signal,
  requestId: "custom-id-123",
});

Retry Logic

• Automatic retries for GET requests on status codes 408, 429, 502, 503, 504
• Max 2 retries with exponential backoff
• Respects Retry-After headers
• POST requests are not retried

Error Handling

import { PromptsGptApiError } from "prompts-gpt";

try {
  await client.pullPrompts();
} catch (error) {
  if (error instanceof PromptsGptApiError) {
    error.status;       // HTTP status code
    error.code;         // Error code (e.g., "AUTH_ERROR", "TIMEOUT")
    error.message;      // Human-readable message
    error.recovery;     // Suggested recovery action
    error.requestId;    // Request ID for support
    error.retryAfterMs; // Milliseconds to wait before retrying
    error.fieldErrors;  // Per-field validation errors
  }
}

Error Codes

Credential Management

saveLocalCredentials()

import { saveLocalCredentials } from "prompts-gpt";

const { credentialsPath } = await saveLocalCredentials({
  token: "pgpt_abc123",
  apiUrl: "https://prompts-gpt.com",  // optional
  cwd: process.cwd(),                  // optional
});

• Creates .prompts-gpt/.credentials.json
• Sets 0600 permissions on Unix
• Auto-adds to .gitignore

loadLocalCredentials()

import { loadLocalCredentials } from "prompts-gpt";

const creds = await loadLocalCredentials(process.cwd());
if (creds) {
  console.log(creds.token);  // "pgpt_abc123" or null
  console.log(creds.apiUrl); // "https://prompts-gpt.com"
}

• Auto-fixes overly permissive file permissions on Unix
• Returns null if no credentials file exists

See Also

• Types Reference — PromptPack, ProjectContext, etc.
• Sync API — Write prompts to disk