@codespar/types

@codespar/types

Zero-dependency TypeScript package defining the shared session interface hierarchy for CodeSpar runtimes.

Any runtime that implements SessionBase — the managed CodeSpar backend, Anthropic Managed Agents, a self-hosted server, or a test double — is a first-class citizen in the SDK ecosystem. The contract is the only coupling between runtimes and the tools that run on top of them.

Install

npm install @codespar/types

Interfaces

SessionBase

The minimal interface any runtime must implement.

import type { SessionBase } from "@codespar/types";

interface SessionBase {
  readonly id: string;
  readonly status: "active" | "closed" | "error";

  execute(toolName: string, params: Record<string, unknown>): Promise<ToolResult>;
  send(message: string): Promise<SendResult>;
  sendStream(message: string): AsyncIterable<StreamEvent>;
  connections(): Promise<BaseConnection[]>;
  close(): Promise<void>;
}

Session

The codespar-specific extension of SessionBase, used when a session was created through the managed CodeSpar API.

import type { Session } from "@codespar/types";

interface Session extends SessionBase {
  proxyExecute(request: ProxyRequest): Promise<ProxyResult>;
  authorize(serverId: string, config: AuthConfig): Promise<AuthResult>;

  // Tool discovery + connection wizard (codespar_discover / codespar_manage_connections)
  discover(useCase: string, options?: DiscoverOptions): Promise<DiscoverResult>;
  connectionWizard(options: ConnectionWizardOptions): Promise<ConnectionWizardResult>;

  // Meta-tool wrappers — typed payloads, same wire as session.execute(...)
  charge(args: ChargeArgs): Promise<ChargeResult>;
  ship(args: ShipArgs): Promise<ShipResult>;
  shop(args: ShopArgs): Promise<ShopResult>;

  // Async settlement (codespar_charge / codespar_pay)
  paymentStatus(toolCallId: string): Promise<PaymentStatusResult>;
  paymentStatusStream(
    toolCallId: string,
    options: PaymentStatusStreamOptions,
  ): Promise<PaymentStatusResult>;

  // Async verification (codespar_kyc)
  verificationStatus(toolCallId: string): Promise<VerificationStatusResult>;
  verificationStatusStream(
    toolCallId: string,
    options: VerificationStatusStreamOptions,
  ): Promise<VerificationStatusResult>;

  mcp?: {
    url: string;
    headers: Record<string, string>;
  };
}

isCodesparSession

Type guard to narrow a SessionBase to Session when you need codespar-specific methods.

import { isCodesparSession } from "@codespar/types";

function useSession(session: SessionBase) {
  if (isCodesparSession(session)) {
    // session is Session here — proxyExecute, authorize, mcp available
    const config = session.mcp;
  }
}

Wire types

Type	Description
ToolResult	Return value of execute() — success, data, error, duration, server, tool
SendResult	Return value of send() — message, tool_calls, iterations
StreamEvent	Union of events yielded by sendStream() — user_message, assistant_text, tool_use, tool_result, done, error
BaseConnection	Entry from connections() — id, connected
ServerConnection	Extended connection with name and provider metadata
ProxyRequest	Input to proxyExecute() — server, endpoint, method, body, headers
ProxyResult	Return value of proxyExecute() — status, data, headers, duration, proxy_call_id
AuthConfig	Input to authorize() — redirectUri, scopes?
AuthResult	Return value of authorize() — linkToken, authorizeUrl, expiresAt
DiscoverOptions / DiscoverResult / DiscoverToolMatch / DiscoverPlanStep	Wire shapes for session.discover(...) (codespar_discover)
ConnectionWizardOptions / ConnectionWizardResult / ConnectionStatusRow	Wire shapes for session.connectionWizard(...) (codespar_manage_connections)
ChargeArgs / ChargeBuyer / ChargeResult	Wire shapes for session.charge(...) (codespar_charge, inbound)
ShipArgs / ShipAddress / ShipItem / ShipResult	Wire shapes for session.ship(...) (codespar_ship)
ShopArgs / ShopSearchArgs / ShopCheckoutArgs / ShopStatusArgs / ShopOffer / ShopVariant / ShopResult / ShopSearchResult / ShopCheckoutResult / ShopStatusResult / ShopCheckoutStatus	Wire shapes for session.shop(...) (codespar_shop) — discriminated on action. Canonical spec: docs/codespar-shop-contract.md
PaymentStatus / PaymentStatusResult / PaymentStatusEvent	Wire shapes for session.paymentStatus(toolCallId) — async webhook correlation
PaymentStatusStreamOptions	Options for session.paymentStatusStream(...) — onUpdate?, signal?
VerificationStatus / VerificationStatusResult / VerificationStatusEvent	Wire shapes for session.verificationStatus(toolCallId) — async KYC poll
VerificationStatusStreamOptions	Options for session.verificationStatusStream(...) — onUpdate?, signal?

The typed meta-tool facades (shop(), charge(), ship(), …) require a runtime that implements the meta-tool. These wire types are the contract; the facade in @codespar/sdk is a client over execute("codespar_<tool>", args). Against a self-hosted runtime with no registered implementation for that meta-tool, the call returns Tool not registered. The types + facade are MIT and self-hostable; the implementation is registered by the runtime the SDK points at.

Conformance testing

@codespar/types ships a runContractSuite helper under a /testing subpath export. It registers a Vitest test suite that exercises the five SessionBase methods against a live HTTP endpoint.

// my-runtime.test.ts
import { runContractSuite } from "@codespar/types/testing";

// Skip unless the env vars are present
const apiKey = process.env["MY_RUNTIME_API_KEY"];
const baseUrl = process.env["MY_RUNTIME_BASE_URL"] ?? "http://localhost:3000";

if (apiKey) {
  runContractSuite(baseUrl, apiKey);
}

The suite opens a session via POST /v1/sessions with Authorization: Bearer <apiKey> and body { servers: [], user_id: "contract-suite" }, then validates:

• execute() calls a registered tool and returns a ToolResult
• send() returns a SendResult with a message field
• sendStream() yields well-typed StreamEvents including a done event
• connections() returns entries with id and connected fields
• close() transitions session.status to "closed"

See docs/custom-session-runtime.md for a full implementation guide.

Need more?

Need governance, budget limits, and audit trails for agent payments? CodeSpar Enterprise adds policy engine, payment routing, and compliance templates on top of these MCP servers.

License

MIT — codespar.dev