Docs›SDK-Referenz

SDK-Referenz

Grepture-Klasse, clientOptions() fuer jedes OpenAI-kompatible SDK, grepture.fetch() als Drop-in-Ersatz, Fehlerklassen und TypeScript-Typen.

Ueberblick

@grepture/sdk stellt einen Grepture-Client mit zwei Integrationsmethoden bereit:

• +grepture.clientOptions() — konfiguriert jedes OpenAI-kompatible SDK so, dass es ueber den Grepture-Proxy geleitet wird
• +grepture.fetch() — ein Drop-in-Ersatz fuer fetch, der jeden HTTP-Aufruf schuetzt

Beide Methoden leiten den Datenverkehr ueber den Grepture-Proxy, wo Ihre Erkennungsregeln angewendet werden, bevor Anfragen externe Dienste erreichen.

Client erstellen

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

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

clientOptions()

Gibt eine Konfiguration zurueck, die in den Konstruktor eines OpenAI-kompatiblen SDK gespreizt werden kann. Funktioniert mit jedem Anbieter, der dasselbe Client-Interface verwendet (OpenAI, Azure OpenAI, Groq, Together usw.) — uebergeben Sie einfach den API Key und die Base-URL des Zielanbieters.

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",
  }),
});

Eingabeoptionen

Rueckgabewert

clientOptions() gibt ein ClientOptionsOutput mit folgenden Feldern zurueck:

Intern verschiebt das gewrappte fetch den Authorization-Header des Ziel-SDKs nach X-Grepture-Auth-Forward und setzt Greptures eigenen Auth-Header, damit der Proxy beide Seiten authentifizieren kann.

grepture.fetch()

Ein Drop-in-Ersatz fuer fetch, der jeden HTTP-Aufruf ueber den Grepture-Proxy leitet. Verwenden Sie es fuer Webhooks, Analytics, Drittanbieter-APIs oder alles ausserhalb eines 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() akzeptiert dieselben Argumente wie die Standard-fetch-API. Es gibt eine GreptureResponse zurueck — einen Wrapper um die Standard-Response mit zusaetzlichen Eigenschaften:

Alle Standard-Response-Methoden (json(), text(), blob(), arrayBuffer(), formData(), clone()) und Eigenschaften (status, ok, headers, body) sind verfuegbar.

Conversation Tracing

Gruppieren Sie zusammengehoerige Anfragen in einem einzelnen Trace, um Multi-Turn-Konversationen und Agenten-Loops zu debuggen. Alle Anfragen mit derselben Trace-ID erscheinen zusammen im Traces-Tab des Traffic Logs.

const grepture = new Grepture({
  apiKey: process.env.GREPTURE_API_KEY!,
  proxyUrl: "https://proxy.grepture.com",
  traceId: `agent-${crypto.randomUUID().slice(0, 12)}`,
});

Labels

Weisen Sie einzelnen Anfragen innerhalb eines Traces ein Label zu, um zu kennzeichnen was jeder Schritt tut — z. B. "extract-facts" oder "tool-call". Labels werden als Badges in der Trace-Timeline angezeigt.

grepture.setLabel("extract-facts");
await openai.chat.completions.create({ ... });

grepture.setLabel("draft-response");
await openai.chat.completions.create({ ... });

grepture.setLabel(undefined); // zuruecksetzen

Per-Request-Label mit grepture.fetch():

const res = await grepture.fetch(url, {
  body: JSON.stringify({ model: "gpt-4o", messages }),
  label: "summarize",
});

Metadata

Haengen Sie beliebige Key-Value-Tags an Anfragen an — z. B. User-IDs, Umgebungen oder Feature-Flags. Metadata erscheint im Detail-Panel des Dashboards.

// Global fuer alle nachfolgenden Anfragen
grepture.setMetadata({ userId: "u_123", environment: "production" });

// Per-Request (wird mit globaler Metadata zusammengefuehrt)
const res = await grepture.fetch(url, {
  body: JSON.stringify({ model: "gpt-4o", messages }),
  metadata: { feature: "chat" },
});

Eigene Log-Events

Loggen Sie Nicht-AI-Events in den aktuellen Trace — Cache-Hits, Tool-Ausfuehrungen oder Validierungsergebnisse. Log-Events erscheinen in der Trace-Timeline neben AI-Aufrufen.

grepture.log("tool-executed", { tool: "web-search", query: "aktuelle Nachrichten" });
grepture.log("cache-hit", { key: "embedding-abc" });

Trace-Methoden

Fehlerbehandlung

Das SDK wirft typisierte Fehlerklassen, wenn der Proxy einen Fehlerstatus zurueckgibt. Ihre bestehende Fehlerbehandlung funktioniert weiterhin — Fehler von der Ziel-API werden unveraendert durchgereicht.

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)
  }
}

Fehlerklassen

Alle Fehlerklassen erweitern GreptureError, welche Error erweitert und eine status-Eigenschaft enthaelt.

TypeScript-Typen

Das SDK ist vollstaendig typisiert. Alle Konfigurations- und Fehlertypen werden exportiert:

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

Laufzeitunterstuetzung

Das SDK laeuft in Node.js, Bun, Deno und Edge-Runtimes (Cloudflare Workers, Vercel Edge). Keine nativen Abhaengigkeiten.