Core API - Forge

import { createForgeCore } from "@forgeintel/sdk/core";
const forge = createForgeCore(options); // same options as createForge

See Other frameworks for a complete wiring.

ForgeCore

interface ForgeCore {
  readonly challengeSentence: string;
  route(request: ForgeRequest): Promise<ForgeResponse | null>;
  call(request: { method: string; path: string; header(name: string): string | undefined }): ForgeCall;
  isSpecRequest(method: string, path: string): boolean;
  enrichOpenApi(document: unknown): { document: unknown; report: EnrichReport };
  onError(error: unknown): void;
  diagnostics(): ForgeDiagnostics;
  shutdown(): Promise<void>;
}

Member	When to call it
`route(request)`	First, on every request. Returns a response for Forge’s own routes (and a static `openapi.document`), otherwise `null`.
`call(request)`	Once per request to one of your routes. `path` is the full request path, used to name the route in events.
`isSpecRequest(method, path)`	If you serve your own OpenAPI document: when this is true, send `enrichOpenApi(doc).document` instead.
`shutdown()`	On process shutdown, to flush events.

ForgeRequest

interface ForgeRequest {
  method: string;
  path: string;                        // relative to where Forge is mounted, no query string
  header(name: string): string | undefined;
  query(name: string): unknown;        // arrays are fine; the first value is used
  json(): Promise<unknown>;            // only called for POST {basePath}; throw on bad JSON or > BODY_LIMIT (8 KB)
}

ForgeResponse

interface ForgeResponse {
  status: number;
  headers: Record<string, string>;
  body?: unknown; // JSON; absent on 405
}

ForgeCall

interface ForgeCall {
  readonly feedbackId: string | undefined; // set when the request carried PAYMENT-SIGNATURE or X-PAYMENT
  json(status: number, body: unknown): unknown;
  text(status: number, contentType: string, body: string): string;
  headers(status: number, paymentRequired: string | undefined, paymentResponse?: string): Record<string, string>;
  requestBody(body: unknown): unknown;
  requestUrl(url: string): string;
  finish(status: number, hadChallengeHeader?: boolean): void;
}

Method	What it does
`json(status, body)`	402: adds the ask to a JSON-body challenge (v1, or v2 echoed in the body). Paid 2xx object: adds `feedback_id`, `feedback_url`, `rate_this_call`. Otherwise returns `body` unchanged.
`text(status, contentType, body)`	Adds the trailer to paid 2xx `text/plain` when `injectText` is on.
`headers(status, paymentRequired, paymentResponse?)`	402: returns `PAYMENT-REQUIRED` with the sentence and extension added. Paid 2xx: returns `Forge-Feedback-Id`, plus `PAYMENT-RESPONSE` with the receipt extension if you pass your settlement header. Merge the result into your headers.
`requestBody(body)`	Before your own logic: reads `agent_context` from a parsed JSON body and returns the body without it (a new object).
`requestUrl(url)`	Before your own logic: reads the `agent_*` query parameters and returns the URL without them; other parameters are unchanged.
`finish(status)`	After the response is sent: reports a `challenge` (for a 402 that `headers()` or `json()` saw) or an `interaction` (for a paid call).

All ForgeCall methods are fail-safe: on an internal error they return the input unchanged and report the error through onError.

Lower-level helpers

Also exported from @forgeintel/sdk: describeChallenge and describeChallengeBody (challenge rewriting), feedbackExtension, enrichOpenApi, mintFeedbackId / verifyFeedbackId, parseSubmission, OUTCOMES, ISSUES and PROTOCOL.