Connections

Finding the tool for a job, getting the server it lives on connected, and ending the session.

discover

Semantic and lexical search across the whole catalog, not just the session's loaded tools. Wraps codespar_discover and returns the recommended tool with its connection status, known pitfalls and a plan, plus related matches. search_strategy says which path served the result; embedding beats trigram in quality.

const found = await session.discover("emit a Pix QR code", { country: "BR", limit: 5 });
if (found.recommended) {
  console.log(found.recommended.tool_name, found.recommended.connection_status);
}
for (const step of found.next_steps) console.log(step);

interface DiscoverResult {
  use_case: string;
  search_strategy: "embedding" | "trigram" | "empty";
  recommended: DiscoverToolMatch | null;
  related: DiscoverToolMatch[];
  next_steps: string[];
}

interface DiscoverToolMatch {
  server_id: string;
  tool_name: string;
  description: string;
  http_method: string;
  endpoint_template: string;
  cosine_distance: number | null;
  trigram_similarity: number | null;
  connection_status: "connected" | "disconnected" | "not_required";
  known_pitfalls: string[];
  recommended_plan: { step: string; description?: string; prereq?: boolean; action?: boolean }[];
}

Throws Error("discover failed: ...") when the tool result is not success; otherwise as execute.

Related codespar_discover, findTools for a substring match over the loaded tools.

connectionWizard

List every server's connection status, read one server's status, or start connecting one. Wraps codespar_manage_connections. action defaults to status when server_id is given and list otherwise. initiate returns a dashboard deep link and instructions for the operator or end user; credentials never pass through this call.

const wizard = await session.connectionWizard({ action: "initiate", server_id: "asaas" });
if (wizard.initiate) {
  console.log("open:", wizard.initiate.connect_url);
  for (const line of wizard.initiate.instructions) console.log(line);
}

interface ConnectionWizardResult {
  action: "list" | "status" | "initiate";
  /** action=list */
  connections: ConnectionStatusRow[];
  /** action=status */
  status: ConnectionStatusRow | null;
  /** action=initiate */
  initiate: ConnectionWizardInstructions | null;
}

interface ConnectionStatusRow {
  server_id: string;
  display_name: string;
  auth_type: string;
  status: "connected" | "disconnected" | "not_required" | "expired";
  difficulty: "easy" | "medium" | "hard";
  connection_metadata: Record<string, unknown>;
  connected_at: string | null;
}

interface ConnectionWizardInstructions {
  server_id: string;
  display_name: string;
  auth_type: string;
  difficulty: "easy" | "medium" | "hard";
  status: ConnectionStatusRow["status"];
  connect_url: string;
  instructions: string[];
  required_secrets: { name: string; hint?: string }[];
  known_pitfalls: string[];
  next_action: string;
}

Throws Error("connectionWizard failed: ...") when the tool result is not success; otherwise as execute.

Related codespar_manage_connections, which also covers the store logins and buyer profiles the wrapper's typed options do not expose (use execute for those actions).

authorize

Starts a Connect Link OAuth flow for a server that needs the end user's own login. Sends POST /v1/connect/start and returns the URL to send the user to; the backend completes the connection on the callback. config is required: the redirect URI is where the user lands afterwards.

const auth = await session.authorize("mercado-pago", {
  redirectUri: "https://example.com/oauth/callback",
});
console.log(auth.authorizeUrl, auth.expiresAt);

interface AuthConfig {
  redirectUri: string;
  scopes?: string;
}

interface AuthResult {
  linkToken: string;
  authorizeUrl: string;
  expiresAt: string;
}

Throws a CodesparApiError on a non-2xx answer or a transport failure, a TimeoutError on timeout.

Related Connect Links, REST POST /v1/connect/start.

connections

The session's servers with their connection state. Also refreshes the cache tools reads from. Best effort: a transport failure or a non-2xx answer returns the last list seen (or []), so a transient blip during a poll does not crater the session.

No parameters.

const servers = await session.connections();
const pending = servers.filter((s) => !s.connected).map((s) => s.id);

interface ServerConnection {
  id: string;
  name: string;
  category: string;
  country: string;
  auth_type: "oauth" | "api_key" | "cert" | "none";
  connected: boolean;
}

Throws nothing for a failed request. It does throw a plain Error for an invalid timeout configuration, because a misconfiguration is not a transient failure.

Related REST GET /v1/sessions/{id}/connections.

close

Ends the session on the backend with DELETE /v1/sessions/{id}. Best effort and bounded: the request is subject to the timeout so close cannot hang, and its outcome is swallowed so a slow or failing backend never throws from a finally. The backend reaps stale sessions on a timer either way.

No parameters.

const session = await cs.create("user_0000");
try {
  await session.send("What can you do?");
} finally {
  await session.close();
}

Promise<void>

Throws nothing for a failed request; a plain Error for an invalid timeout configuration.

Related REST DELETE /v1/sessions/{id}.