@openkeyai/sdk 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # `@openkeyai/sdk`
 
-The SDK every [OpenKey AI](https://openkeyai.com) tool installs. Provides JWT verification, the `SecureKey` key-fetch pattern, and typed errors mirroring the hub's frozen error contract.
+The SDK every [OpenKey AI](https://openkeyai.com) tool installs. JWT verification, the zero-trust API proxy, typed convenience methods for OpenAI / Anthropic / Replicate, and typed errors mirroring the hub's frozen error contract.
 
 ```bash
 pnpm add @openkeyai/sdk
@@ -9,18 +9,66 @@ pnpm add @openkeyai/sdk
 
 ## Status
 
-Five-module surface defined in [`hub/docs/TOOL_SDK.md`](https://github.com/Scott-Builds-AI/hub/blob/main/docs/TOOL_SDK.md). Status by module in 0.1.0:
+Surface defined in [`hub/docs/TOOL_SDK.md`](https://github.com/OpenKeyAI/hub/blob/main/docs/TOOL_SDK.md). Status by module in 0.2.0:
 
-| Module | 0.1.0 | Notes |
+| Module | 0.2.0 | Notes |
 |---|---|---|
 | `session.verify` | ✅ | Uses the hub's JWKS endpoint |
-| `keys.get` → `SecureKey` | ✅ | Talks to `/api/tools/{slug}/keys/{provider}` |
+| `proxy.call / .callRaw / .callStream` | ✅ | Phase 19 zero-trust proxy — plaintext key never enters your Worker |
+| `openai.{images,chat,embeddings,audio}` | ✅ | Typed convenience over the proxy |
+| `anthropic.messages` | ✅ | Typed convenience over the proxy |
+| `replicate.predictions` | ✅ | Typed convenience over the proxy |
+| `keys.get` → `SecureKey` | ✅ | Kept for endpoints the proxy doesn't typeset yet |
 | `user.profile` | ⏳ deferred | Needs hub to ship `/api/me` |
 | `billing.status` | ⏳ deferred | Needs hub to ship `/api/billing/status` |
 | `webhooks.handler` | ⏳ deferred | Lands with hub Phase 16 |
 
 Deferred modules are simply absent from exports — your tool gets a TypeScript error if it tries to use them, not a runtime surprise.
 
+## Which pattern should I use?
+
+| You want to… | Use |
+|---|---|
+| Call a canonical model endpoint (OpenAI images, chat, Anthropic messages, Replicate predictions) | **Typed convenience** — `openai.images.generate(token, params)` etc. |
+| Call any registered provider on any path / method we haven't typed yet | **Generic proxy** — `proxy.call(token, { provider, method, path, body })` |
+| Get a binary response (TTS audio, image bytes) | `proxy.callRaw(...)` or `openai.audio.speech.create(...)` |
+| Stream a response (chat SSE, chunked downloads) | `proxy.callStream(...)` or `openai.chat.completions.stream(...)` |
+| Call a provider the hub doesn't route through yet, or run fine-tuning / batch / custom auth | `keys.get(token, provider)` + `SecureKey.use()` (legacy) |
+
+**Default to the proxy.** The plaintext key never enters your tool process — every other consideration is downstream of that.
+
+## Quick start — proxy pattern (recommended, Phase 19+)
+
+```ts
+import { session, openai, ProviderError, RateLimitedError, SubscriptionInactiveError } from "@openkeyai/sdk";
+
+export async function handleRequest(req: Request) {
+  const jwt = req.headers.get("authorization")?.replace(/^Bearer\s+/i, "") ?? "";
+
+  const claims = await session.verify(jwt, {
+    hubUrl: "https://openkeyai.com",
+    expectedAudience: "tool-youtube-thumbnail-generator",
+  });
+
+  try {
+    const result = await openai.images.generate(jwt, {
+      model: "gpt-image-1",
+      prompt: "Vibrant YouTube thumbnail for a tech tutorial",
+      n: 4,
+      size: "1792x1024",
+    });
+    return Response.json({ images: result.data });
+  } catch (err) {
+    if (err instanceof SubscriptionInactiveError) return new Response("Paywall", { status: 402 });
+    if (err instanceof RateLimitedError) return new Response("Slow down", { status: 429, headers: { "retry-after": String(err.retryAfter) } });
+    if (err instanceof ProviderError) return Response.json({ openai_error: err.body }, { status: err.upstreamStatus });
+    throw err;
+  }
+}
+```
+
+The plaintext OpenAI key is fetched + injected + scrubbed entirely inside the hub's Worker. Your tool process never sees `sk-proj-…`.
+
 ## Quick start
 
 A typical tool's request handler:

package/dist/index.cjs

@@ -119,6 +119,41 @@ var SecureKeyConsumedError = class extends HubSdkError {
     this.name = "SecureKeyConsumedError";
   }
 };
+var ProviderNotConfiguredError = class extends HubSdkError {
+  constructor(provider) {
+    super(
+      "provider_not_configured",
+      `Provider "${provider}" is not registered with the hub proxy. Available providers are listed at /api/proxy (coming) or in the hub's src/lib/proxy/providers.ts.`,
+      404
+    );
+    this.name = "ProviderNotConfiguredError";
+  }
+};
+var ProviderError = class extends HubSdkError {
+  /** The provider slug we tried to call. */
+  provider;
+  /** The path on the provider that returned non-2xx. */
+  path;
+  /**
+   * The upstream response body. Parsed as JSON when the upstream's
+   * content-type was JSON; raw text otherwise.
+   */
+  body;
+  /** The upstream response status code (relayed unchanged). */
+  upstreamStatus;
+  constructor(provider, path, upstreamStatus, body) {
+    super(
+      "provider_error",
+      `${provider} ${path} returned ${upstreamStatus}.`,
+      upstreamStatus
+    );
+    this.name = "ProviderError";
+    this.provider = provider;
+    this.path = path;
+    this.upstreamStatus = upstreamStatus;
+    this.body = body;
+  }
+};
 function errorFromResponse(status, body, context) {
   const code = body?.error ?? "internal";
   switch (code) {
@@ -136,6 +171,8 @@ function errorFromResponse(status, body, context) {
       return new NotSubscribedError();
     case "provider_not_granted":
       return new ProviderNotGrantedError(context.provider ?? "unknown");
+    case "provider_not_configured":
+      return new ProviderNotConfiguredError(context.provider ?? "unknown");
     case "rate_limited":
       return new RateLimitedError(context.retryAfter ?? 60);
     case "key_not_found":
@@ -145,6 +182,25 @@ function errorFromResponse(status, body, context) {
       return new InternalError(status);
   }
 }
+function isHubErrorBody(body) {
+  if (typeof body !== "object" || body === null) return false;
+  const errorField = body.error;
+  if (typeof errorField !== "string") return false;
+  const knownCodes = [
+    "missing_token",
+    "bad_token",
+    "missing_scope",
+    "subscription_inactive",
+    "tool_not_found",
+    "not_subscribed",
+    "provider_not_granted",
+    "rate_limited",
+    "key_not_found",
+    "internal",
+    "provider_not_configured"
+  ];
+  return knownCodes.includes(errorField);
+}
 var resolvers = /* @__PURE__ */ new Map();
 function getJwksResolver(hubUrl) {
   const cached = resolvers.get(hubUrl);
@@ -199,6 +255,7 @@ async function verify(jwt, opts = {}) {
   const jti = payload.jti;
   const iat = payload.iat;
   const exp = payload.exp;
+  const rawMode = payload.mode;
   if (typeof sub !== "string" || sub.length === 0) {
     throw new BadTokenError("sub claim missing or invalid.");
   }
@@ -217,12 +274,19 @@ async function verify(jwt, opts = {}) {
   if (typeof iat !== "number" || typeof exp !== "number") {
     throw new BadTokenError("iat / exp claims missing or invalid.");
   }
+  const mode = typeof rawMode === "string" && (rawMode === "production" || rawMode === "owner_test") ? rawMode : rawMode === void 0 ? "production" : null;
+  if (mode === null) {
+    throw new BadTokenError(
+      `mode claim must be 'production' or 'owner_test' (got ${JSON.stringify(rawMode)}).`
+    );
+  }
   return {
     iss: "https://openkeyai.com",
     sub,
     aud,
     scopes,
     subscription_active: subscriptionActive,
+    mode,
     iat,
     exp,
     jti
@@ -357,6 +421,298 @@ async function get(jwt, provider, opts = {}) {
   });
 }
 
+// src/proxy.ts
+var PROXY_PATH = "/api/proxy";
+function ensureBearer(token) {
+  if (!token || typeof token !== "string") {
+    throw new BadTokenError("No JWT provided.");
+  }
+}
+function buildUrl(opts) {
+  if (!opts.provider) {
+    throw new BadTokenError("ProxyCallOptions.provider is required.");
+  }
+  if (!opts.path || !opts.path.startsWith("/")) {
+    throw new BadTokenError(
+      "ProxyCallOptions.path must start with '/' (e.g. '/v1/chat/completions')."
+    );
+  }
+  const hubUrl = opts.hubUrl ?? "https://openkeyai.com";
+  return new URL(
+    `${PROXY_PATH}/${encodeURIComponent(opts.provider)}${opts.path}`,
+    hubUrl
+  );
+}
+function buildRequestInit(token, opts) {
+  const headers = new Headers();
+  if (opts.headers) {
+    for (const [k, v] of Object.entries(opts.headers)) {
+      headers.set(k, v);
+    }
+  }
+  headers.set("authorization", `Bearer ${token}`);
+  let body;
+  if (opts.method === "GET" || opts.method === "DELETE" || opts.body == null) {
+    body = void 0;
+  } else if (typeof opts.body === "string" || opts.body instanceof Blob || opts.body instanceof FormData || opts.body instanceof ArrayBuffer || opts.body instanceof ReadableStream) {
+    body = opts.body;
+  } else {
+    body = JSON.stringify(opts.body);
+    if (!headers.has("content-type")) {
+      headers.set("content-type", "application/json");
+    }
+  }
+  if (!headers.has("accept")) {
+    headers.set("accept", "application/json");
+  }
+  return {
+    method: opts.method,
+    headers,
+    body,
+    signal: opts.signal,
+    // @ts-expect-error duplex is part of fetch's RequestInit on Workers + recent Node
+    duplex: body instanceof ReadableStream ? "half" : void 0
+  };
+}
+async function rawFetch(token, opts) {
+  ensureBearer(token);
+  const url = buildUrl(opts);
+  try {
+    return await fetch(url.toString(), buildRequestInit(token, opts));
+  } catch (err) {
+    if (err instanceof DOMException && err.name === "AbortError") {
+      throw err;
+    }
+    throw new NetworkError(err);
+  }
+}
+async function parseBodyByContentType(response) {
+  const ct = response.headers.get("content-type") ?? "";
+  if (ct.includes("application/json")) {
+    try {
+      return await response.json();
+    } catch {
+      return null;
+    }
+  }
+  try {
+    return await response.text();
+  } catch {
+    return null;
+  }
+}
+async function handleResponse(response, opts, expectJson) {
+  if (response.ok) {
+    if (!expectJson) return response;
+    return await response.json();
+  }
+  const body = await parseBodyByContentType(response);
+  if (isHubErrorBody(body)) {
+    const retryAfter = parseInt(response.headers.get("retry-after") ?? "60", 10);
+    throw errorFromResponse(
+      response.status,
+      { error: body.error },
+      {
+        provider: opts.provider,
+        scopeNeeded: "keys.read",
+        retryAfter: Number.isFinite(retryAfter) ? retryAfter : 60
+      }
+    );
+  }
+  throw new ProviderError(opts.provider, opts.path, response.status, body);
+}
+async function call(token, opts) {
+  const response = await rawFetch(token, opts);
+  return handleResponse(response, opts, true);
+}
+async function callRaw(token, opts) {
+  const response = await rawFetch(token, opts);
+  return handleResponse(response, opts, false);
+}
+async function callStream(token, opts) {
+  const response = await rawFetch(token, opts);
+  if (!response.ok) {
+    const body = await parseBodyByContentType(response);
+    if (isHubErrorBody(body)) {
+      const retryAfter = parseInt(
+        response.headers.get("retry-after") ?? "60",
+        10
+      );
+      throw errorFromResponse(
+        response.status,
+        { error: body.error },
+        {
+          provider: opts.provider,
+          scopeNeeded: "keys.read",
+          retryAfter: Number.isFinite(retryAfter) ? retryAfter : 60
+        }
+      );
+    }
+    throw new ProviderError(opts.provider, opts.path, response.status, body);
+  }
+  if (response.body == null) {
+    throw new BadTokenError("Upstream returned 2xx with no body to stream.");
+  }
+  return response.body;
+}
+
+// src/providers/openai.ts
+var openai = {
+  images: {
+    generate(token, params, opts = {}) {
+      return call(token, {
+        ...opts,
+        provider: "openai",
+        method: "POST",
+        path: "/v1/images/generations",
+        body: params
+      });
+    }
+  },
+  chat: {
+    completions: {
+      create(token, params, opts = {}) {
+        return call(token, {
+          ...opts,
+          provider: "openai",
+          method: "POST",
+          path: "/v1/chat/completions",
+          body: params
+        });
+      },
+      stream(token, params, opts = {}) {
+        return callStream(token, {
+          ...opts,
+          provider: "openai",
+          method: "POST",
+          path: "/v1/chat/completions",
+          body: { ...params, stream: true }
+        });
+      }
+    }
+  },
+  embeddings: {
+    create(token, params, opts = {}) {
+      return call(token, {
+        ...opts,
+        provider: "openai",
+        method: "POST",
+        path: "/v1/embeddings",
+        body: params
+      });
+    }
+  },
+  audio: {
+    transcriptions: {
+      create(token, params, opts = {}) {
+        const fd = new FormData();
+        fd.append("file", params.file, params.filename ?? "audio.webm");
+        fd.append("model", params.model);
+        if (params.language) fd.append("language", params.language);
+        if (params.prompt) fd.append("prompt", params.prompt);
+        if (params.response_format)
+          fd.append("response_format", params.response_format);
+        if (params.temperature !== void 0)
+          fd.append("temperature", String(params.temperature));
+        return call(token, {
+          ...opts,
+          provider: "openai",
+          method: "POST",
+          path: "/v1/audio/transcriptions",
+          body: fd
+        });
+      }
+    },
+    speech: {
+      create(token, params, opts = {}) {
+        return callRaw(token, {
+          ...opts,
+          provider: "openai",
+          method: "POST",
+          path: "/v1/audio/speech",
+          body: params
+        });
+      }
+    }
+  }
+};
+
+// src/providers/anthropic.ts
+var anthropic = {
+  messages: {
+    create(token, params, opts = {}) {
+      return call(token, {
+        ...opts,
+        provider: "anthropic",
+        method: "POST",
+        path: "/v1/messages",
+        body: params
+      });
+    },
+    stream(token, params, opts = {}) {
+      return callStream(token, {
+        ...opts,
+        provider: "anthropic",
+        method: "POST",
+        path: "/v1/messages",
+        body: { ...params, stream: true }
+      });
+    }
+  }
+};
+
+// src/providers/replicate.ts
+var replicate = {
+  predictions: {
+    create(token, params, opts = {}) {
+      return call(token, {
+        ...opts,
+        provider: "replicate",
+        method: "POST",
+        path: "/v1/predictions",
+        body: params
+      });
+    },
+    get(token, predictionId, opts = {}) {
+      return call(token, {
+        ...opts,
+        provider: "replicate",
+        method: "GET",
+        path: `/v1/predictions/${encodeURIComponent(predictionId)}`
+      });
+    },
+    cancel(token, predictionId, opts = {}) {
+      return call(token, {
+        ...opts,
+        provider: "replicate",
+        method: "POST",
+        path: `/v1/predictions/${encodeURIComponent(predictionId)}/cancel`
+      });
+    },
+    /**
+     * Convenience: create + poll until the prediction reaches a terminal
+     * status. Polls every `pollIntervalMs` (default 1000ms) with the
+     * provided AbortSignal honoured.
+     *
+     * For long-running predictions consider using webhooks via
+     * `create({ webhook, webhook_events_filter })` instead so you're not
+     * holding open a long fetch.
+     */
+    async run(token, params, opts = {}) {
+      const interval = opts.pollIntervalMs ?? 1e3;
+      let prediction = await this.create(token, params, opts);
+      while (prediction.status === "starting" || prediction.status === "processing") {
+        if (opts.signal?.aborted) {
+          throw opts.signal.reason ?? new DOMException("Aborted", "AbortError");
+        }
+        await new Promise((resolve) => setTimeout(resolve, interval));
+        prediction = await this.get(token, prediction.id, opts);
+      }
+      return prediction;
+    }
+  }
+};
+
 // src/index.ts
 var session = {
   verify
@@ -364,7 +720,12 @@ var session = {
 var keys = {
   get
 };
-var SDK_VERSION = "0.1.0";
+var proxy = {
+  call,
+  callRaw,
+  callStream
+};
+var SDK_VERSION = "0.2.0";
 
 exports.BadTokenError = BadTokenError;
 exports.HubSdkError = HubSdkError;
@@ -374,6 +735,8 @@ exports.MissingScopeError = MissingScopeError;
 exports.MissingTokenError = MissingTokenError;
 exports.NetworkError = NetworkError;
 exports.NotSubscribedError = NotSubscribedError;
+exports.ProviderError = ProviderError;
+exports.ProviderNotConfiguredError = ProviderNotConfiguredError;
 exports.ProviderNotGrantedError = ProviderNotGrantedError;
 exports.RateLimitedError = RateLimitedError;
 exports.SDK_VERSION = SDK_VERSION;
@@ -381,7 +744,11 @@ exports.SecureKey = SecureKey;
 exports.SecureKeyConsumedError = SecureKeyConsumedError;
 exports.SubscriptionInactiveError = SubscriptionInactiveError;
 exports.ToolNotFoundError = ToolNotFoundError;
+exports.anthropic = anthropic;
 exports.keys = keys;
+exports.openai = openai;
+exports.proxy = proxy;
+exports.replicate = replicate;
 exports.session = session;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map