Usage & Integration Guide

OPENROUTER_API_KEY=sk-or-v1-xxxxxxxxxxxxxxxxxxxxxxxx
POOLSIDE_API_KEY=psk-xxxxxxxxxxxxxxxxxxxxxxxx
# Optional:
DEFAULT_PROVIDER=openrouter
# CUSTOM_BASE_URL=https://api.openai.com/v1
# CUSTOM_API_KEY=sk-xxxx
# CUSTOM_MODEL=gpt-4o-mini

const GATEWAY = "https://YOUR-DOMAIN";   // auto-detected on this page
const API_KEY  = "";                             // only if API_SECRET_KEY is set

export async function chat({ provider, message, systemPrompt, model, temperature, maxTokens }) {
  const body = { provider, message };
  if (systemPrompt) body.system_prompt = systemPrompt;
  if (model) body.model = model;
  if (temperature !== undefined) body.temperature = temperature;
  if (maxTokens) body.max_tokens = maxTokens;

  const res = await fetch(`${GATEWAY}/api/v1/chat`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      ...(API_KEY ? { "X-API-Key": API_KEY } : {}),
    },
    body: JSON.stringify(body),
  });

  const data = await res.json();
  if (!data.success) {
    const err = new Error(data.error?.message || "Gateway error");
    err.code = data.error?.code;
    err.retryAfter = data.error?.details?.retryAfterSeconds;
    throw err;
  }
  return data; // { reply, provider, model, usage }
}

import { chat } from "./chat.js";

const answer = await chat({
  provider: "poolside",
  message: "Write a Go function that sums a slice of ints",
  systemPrompt: "You are a senior Go developer. Answer with code first.",
  maxTokens: 400,
});
console.log(answer.reply);

import os
import requests

GATEWAY = "https://YOUR-DOMAIN"
API_KEY = os.getenv("GATEWAY_API_KEY", "")  # only if API_SECRET_KEY is set


def chat(message, provider="openrouter", system_prompt=None, **kwargs):
    payload = {"provider": provider, "message": message, **kwargs}
    if system_prompt:
        payload["system_prompt"] = system_prompt

    res = requests.post(
        f"{GATEWAY}/api/v1/chat",
        json=payload,
        headers={"X-API-Key": API_KEY} if API_KEY else {},
        timeout=60,
    )
    res.raise_for_status()
    data = res.json()
    if not data["success"]:
        raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}")
    return data["reply"]


if __name__ == "__main__":
    print(chat("What are channels in Go?", provider="poolside"))

const turns = [
  { role: "system", content: "You are a helpful assistant." },
];

async function talk(userText) {
  turns.push({ role: "user", content: userText });

  const res = await fetch(`${GATEWAY}/api/v1/chat`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ provider: "openrouter", messages: turns }),
  });
  const data = await res.json();
  if (!data.success) throw new Error(data.error?.code);

  turns.push({ role: "assistant", content: data.reply });
  return data.reply;
}

await talk("Hi! What is HTTP 429?");     // -> explanation
await talk("Show me a retry example.");  // model remembers the context

const RETRYABLE = new Set([
  "UPSTREAM_RATE_LIMIT", "UPSTREAM_UNAVAILABLE",
  "UPSTREAM_TIMEOUT", "UPSTREAM_ERROR",
]);

export async function chatWithRetry(body, attempts = 3) {
  for (let i = 0; i < attempts; i++) {
    const res = await fetch(`${GATEWAY}/api/v1/chat`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(body),
    });
    const data = await res.json();

    if (data.success) return data.reply;

    const code = data.error?.code;
    if (!RETRYABLE.has(code) || i === attempts - 1) {
      throw new Error(`${code}: ${data.error?.message}`);
    }

    const wait = (data.error?.details?.retryAfterSeconds ?? 2 ** i) * 1000;
    await new Promise((r) => setTimeout(r, wait));
  }
}

npm install

# Option A — Node runtime (simplest): serves site + API on :5000
cp .env.example .env      # add your keys
npm start

# Option B — exact Cloudflare runtime (wrangler): site + API on :8787
cp .dev.vars.example .dev.vars   # add your keys
npm run dev

# Smoke tests against a running gateway
npm run smoke                 # add RUN_E2E=1 for a real chat call