Reef TypeScript SDK

Server-only TypeScript client for Reef. The package export map blocks browser bundlers so Reef credentials do not leak into client code.

Install

npm install @fluxtopus/reef-sdk

Create a typed decision

DecisionCreateRequest uses a discriminated union for choice, score, and noul questions. DecisionResponse uses status to narrow queued, completed, and failed results.

import {
  ReefClient,
  type DecisionCreateRequest,
} from "@fluxtopus/reef-sdk";

const credential = process.env.REEF_SERVICE_API_KEY;
if (credential === undefined) {
  throw new Error("REEF_SERVICE_API_KEY is required");
}

const reef = new ReefClient({
  baseUrl: "https://reef.example.com",
  credential,
  credentialKind: "service",
});

const request = {
  state: {
    ticket: "I upgraded to Pro, still see Free, and was charged.",
  },
  questions: {
    route: {
      type: "choice",
      instructions: "Choose the team that should handle this ticket.",
      criteria: {
        billing: "Billing, subscription, or charge issue",
        technical: "Technical product malfunction",
        account: "Account access or identity issue",
      },
    },
    urgency: {
      type: "score",
      instructions: "Score the urgency of this ticket.",
      criteria: ["low", "medium", "high"],
    },
    billing_related: {
      type: "noul",
      instructions: "Does this ticket concern billing?",
    },
  },
  requested_model: "~typesafe/jev-latest",
  model_policy_id: "decision_model_default",
} satisfies DecisionCreateRequest;

const decision = await reef.decisions.create(
  "support-product",
  request,
  "ticket-4821-routing-v1",
);

if (decision.status === "completed") {
  const route = decision.answers.route;
  if (route?.type === "choice") {
    console.info(route.choice, route.confidence);
  }
}

The SDK validates successful decision responses at the HTTP boundary. Completed responses cannot omit answers, provider metadata, or usage without raising an error.

Runtime requirements

• Call the SDK from a product backend or server route.
• The principal needs agent_decision:execute.
• The product needs an active OpenRouter provider configuration and an execution policy whose model policy requires the decisions capability.
• Reuse an idempotency key only for the same request. Reef returns the stored result without a second provider call.

See Reef decision requests for policy setup, the HTTP contract, errors, accounting, and production verification evidence.

The SDK also covers configuration, prompts, conversations, files, runs, memory, and evidence. Provider credentials remain inside Reef.