@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

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" }. Every leg asserts the 201 body carries id, status: "active", the posted user_id, servers (a string[] that includes every posted id) and a parseable created_at — the fields @codespar/sdk builds its session from. Then it 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() answers 2xx with { servers }, each entry carrying id and connected (tools, when present, must be an array)
• 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