@codedprojects/api-mapper-client

TypeScript client SDK for discovering and invoking AI ApiMapper Runtime tools from JavaScript and TypeScript applications.

Install

npm install @codedprojects/api-mapper-client

What it provides

• runtime tool discovery,
• runtime system prompt loading,
• tool invocation over MCP-compatible HTTP endpoints,
• API key, delegated bearer token, and OAuth2 client credentials authentication helpers.

Quick start

import { ApiMapperClient, ApiKeyCredentialProvider } from "@codedprojects/api-mapper-client";

const client = new ApiMapperClient({
  baseUrl: "https://runtime.example.com",
  tenantId: "11111111-1111-1111-1111-111111111111",
  clientId: "my-ai-client",
  credentials: new ApiKeyCredentialProvider("replace-with-your-api-key"),
});

const tools = await client.getTools();
console.log(tools.map((tool) => tool.name));

Streamable HTTP / SSE

The Runtime's /mcp endpoint may answer a request either as plain application/json or as an SSE-framed text/event-stream body — both are normal, steady-state responses; which one you get is decided by the Runtime, not the client. The client handles both transparently: no configuration is needed, and calls like getTools() and invokeTool() behave identically either way. If an SSE-framed response stream ends before delivering its result, the client automatically makes one resumption attempt using the stream's last event id before giving up.

closeSession()

Ends the MCP session on the Runtime (DELETE /mcp) and clears local session state. Safe to call at any time, including when no session was established — it never throws, so it's safe to use in a shutdown/cleanup path.

await client.closeSession();

listen()

Opens the Runtime's standalone server-push stream (GET /mcp) and yields each message the Runtime pushes outside of a request/response exchange. Reconnects automatically (tracking Last-Event-ID) after transient faults, and stops with a clear error on a non-retryable failure (e.g. an unknown or expired session). Pass an AbortSignal to stop listening on demand.

const controller = new AbortController();

for await (const message of client.listen(controller.signal)) {
  console.log("Runtime pushed:", message);
}

// Elsewhere: controller.abort();

Correlation IDs

Send your application's own trace ID with each call and the Runtime records it against the execution ID it generates, so you can retrieve the full platform audit trail for work you triggered. Configure an ambient provider on the client options, or pass one per call. See the SDK correlation guide.

License

MIT