Docs›SDK Reference

SDK Reference

Grepture class, clientOptions() for any OpenAI-compatible SDK, grepture.fetch() drop-in, error classes, and TypeScript types.

Overview

@grepture/sdk provides a Grepture client with two integration methods:

• grepture.clientOptions() — configure any OpenAI-compatible SDK to route through the Grepture proxy
• grepture.fetch() — a drop-in replacement for fetch that protects any HTTP call

Both methods route traffic through the Grepture proxy, where your detection rules are applied before requests reach external services.

Creating a client

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

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

clientOptions()

Returns configuration to spread into an OpenAI-compatible SDK constructor. Works with any provider that uses the same client interface (OpenAI, Azure OpenAI, Groq, Together, etc.) — just pass the target provider's API key and base URL.

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

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

const openai = new OpenAI({
  ...grepture.clientOptions({
    apiKey: process.env.OPENAI_API_KEY!,
    baseURL: "https://api.openai.com/v1",
  }),
});

Input options

What it returns

clientOptions() returns a ClientOptionsOutput with:

Under the hood, the wrapped fetch moves the target SDK's Authorization header to X-Grepture-Auth-Forward and sets Grepture's own auth header, so the proxy can authenticate both sides.

grepture.fetch()

A drop-in replacement for fetch that routes any HTTP call through the Grepture proxy. Use it for webhooks, analytics, third-party APIs, or anything outside an SDK.

const response = await grepture.fetch("https://api.example.com/data", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ user: "jane@example.com" }),
});

const data = await response.json();

grepture.fetch() accepts the same arguments as the standard fetch API. It returns a GreptureResponse — a wrapper around the standard Response with extra properties:

All standard Response methods (json(), text(), blob(), arrayBuffer(), formData(), clone()) and properties (status, ok, headers, body) are available.

Error handling

The SDK throws typed error classes when the proxy returns an error status. Your existing error handling continues to work — errors from the target API pass through unchanged.

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

try {
  const response = await openai.chat.completions.create({
    model: "gpt-4o",
    messages: [{ role: "user", content: prompt }],
  });
} catch (error) {
  if (error instanceof BlockedError) {
    // Request blocked by a detection rule (HTTP 403)
  } else if (error instanceof AuthError) {
    // Invalid or missing Grepture API key (HTTP 401)
  }
}

Error classes

All error classes extend GreptureError, which extends Error and includes a status property.

TypeScript types

The SDK is fully typed. All configuration and error types are exported:

import type {
  GreptureConfig,
  ClientOptionsInput,
  ClientOptionsOutput,
  FetchOptions,
  GreptureResponseMeta,
} from "@grepture/sdk";

Runtime support

The SDK runs in Node.js, Bun, Deno, and edge runtimes (Cloudflare Workers, Vercel Edge). Zero native dependencies.