@grepture/sdk

Drop-in fetch wrapper for routing AI API calls through Grepture. Zero dependencies — works in Node, Bun, Deno, and edge runtimes.

Install

npm install @grepture/sdk

Quick Start

Direct fetch

Use grepture.fetch() as a drop-in replacement for fetch. The SDK handles all proxy header plumbing automatically.

import { Grepture } from "@grepture/sdk";

const grepture = new Grepture({
  apiKey: "gpt_abc123",
  proxyUrl: "https://proxy.grepture.com",
});

const res = await grepture.fetch("https://api.openai.com/v1/chat/completions", {
  method: "POST",
  headers: {
    Authorization: "Bearer sk-openai-key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "gpt-4o",
    messages: [{ role: "user", content: "hi" }],
  }),
});

console.log(res.status);       // 200
console.log(res.requestId);    // "uuid"
console.log(res.rulesApplied); // ["rule-uuid-1"]
console.log(await res.json()); // parsed response body

OpenAI SDK integration

Use grepture.clientOptions() to get a config object compatible with any OpenAI-shaped SDK constructor.

import OpenAI from "openai";
import { Grepture } from "@grepture/sdk";

const grepture = new Grepture({
  apiKey: "gpt_abc123",
  proxyUrl: "https://proxy.grepture.com",
});

const client = new OpenAI(
  grepture.clientOptions({
    apiKey: "sk-openai-key",
    baseURL: "https://api.openai.com/v1",
  })
);

// Works exactly like normal — requests flow through Grepture
const completion = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "hi" }],
});

API

new Grepture(config)

| Parameter | Type | Description | |-----------|------|-------------| | config.apiKey | string | Your Grepture API key (gpt_xxx) | | config.proxyUrl | string | Grepture proxy URL (e.g. https://proxy.grepture.com) |

grepture.fetch(targetUrl, init?)

Same signature as the standard fetch. Returns a GreptureResponse with additional metadata:

• res.requestId — unique request ID from the proxy
• res.rulesApplied — array of rule IDs that were applied
• res.status, res.ok, res.headers, res.json(), res.text() — standard Response properties

If you pass an Authorization header (for the target API), the SDK automatically moves it to X-Grepture-Auth-Forward and sets the Grepture auth header instead.

grepture.clientOptions(input)

Returns { baseURL, apiKey, fetch } for use with OpenAI-shaped SDK constructors.

| Parameter | Type | Description | |-----------|------|-------------| | input.apiKey | string | Target API key (e.g. sk-openai-key) | | input.baseURL | string | Target base URL (e.g. https://api.openai.com/v1) |

Error Handling

The SDK throws typed errors on non-OK responses from the proxy:

import { Grepture, AuthError, BlockedError } from "@grepture/sdk";

try {
  const res = await grepture.fetch(url, init);
} catch (e) {
  if (e instanceof BlockedError) {
    // Request blocked by a Grepture rule (403)
  } else if (e instanceof AuthError) {
    // Invalid Grepture API key (401)
  }
}

| Error Class | Status | When | |-------------|--------|------| | BadRequestError | 400 | Malformed request | | AuthError | 401 | Invalid Grepture API key | | BlockedError | 403 | Request blocked by a rule | | ProxyError | 502/504 | Target unreachable or timed out | | GreptureError | other | Any other non-OK status |