@kalera/munin-sdk 0.1.0

package/.turbo/turbo-build.log

@@ -0,0 +1,4 @@
+
+> @kalera/munin-sdk@0.1.0 build /home/runner/work/munin-for-agents/munin-for-agents/packages/ts-sdk
+> tsc -p tsconfig.json
+

package/dist/capabilities.d.ts

@@ -0,0 +1,3 @@
+import type { MuninCapabilities } from "./types.js";
+export declare function fetchCapabilities(baseUrl: string, apiKey?: string, fetchImpl?: typeof fetch): Promise<MuninCapabilities>;
+export declare function isActionSupported(capabilities: MuninCapabilities, action: string): boolean;

package/dist/capabilities.js

@@ -0,0 +1,27 @@
+import { MuninSdkError, MuninTransportError } from "./errors.js";
+export async function fetchCapabilities(baseUrl, apiKey, fetchImpl = fetch) {
+    const response = await fetchImpl(`${baseUrl}/api/mcp/capabilities`, {
+        method: "GET",
+        headers: {
+            "Content-Type": "application/json",
+            ...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}),
+        },
+    }).catch((error) => {
+        throw new MuninTransportError(`Failed to call capabilities endpoint: ${String(error)}`);
+    });
+    if (!response.ok) {
+        throw new MuninTransportError(`Capabilities request failed with status ${response.status}`);
+    }
+    const body = (await response.json());
+    if (!body.ok || !body.data) {
+        throw new MuninSdkError(body.error ?? {
+            code: "INTERNAL_ERROR",
+            message: "Capabilities response missing data",
+        });
+    }
+    return body.data;
+}
+export function isActionSupported(capabilities, action) {
+    return (capabilities.actions.core.includes(action) ||
+        capabilities.actions.optional.includes(action));
+}

package/dist/client.d.ts

@@ -0,0 +1,20 @@
+import type { MuninAction, MuninCapabilities, MuninClientConfig, MuninResponse } from "./types.js";
+export declare class MuninClient {
+    private readonly baseUrl;
+    private readonly apiKey?;
+    private readonly project;
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    private capabilitiesCache?;
+    constructor(config: MuninClientConfig);
+    capabilities(forceRefresh?: boolean): Promise<MuninCapabilities>;
+    invoke<TPayload extends Record<string, unknown>, TData = unknown>(action: MuninAction, payload: TPayload, options?: {
+        requestId?: string;
+        ensureCapability?: boolean;
+    }): Promise<MuninResponse<TData>>;
+    store(payload: Record<string, unknown>): Promise<MuninResponse<unknown>>;
+    retrieve(payload: Record<string, unknown>): Promise<MuninResponse<unknown>>;
+    search(payload: Record<string, unknown>): Promise<MuninResponse<unknown>>;
+    list(payload?: Record<string, unknown>): Promise<MuninResponse<unknown>>;
+    recent(payload?: Record<string, unknown>): Promise<MuninResponse<unknown>>;
+}

package/dist/client.js

@@ -0,0 +1,84 @@
+import { MuninSdkError, MuninTransportError } from "./errors.js";
+import { fetchCapabilities, isActionSupported, } from "./capabilities.js";
+const DEFAULT_TIMEOUT_MS = 15_000;
+export class MuninClient {
+    baseUrl;
+    apiKey;
+    project;
+    timeoutMs;
+    fetchImpl;
+    capabilitiesCache;
+    constructor(config) {
+        this.baseUrl = config.baseUrl.replace(/\/$/, "");
+        this.apiKey = config.apiKey;
+        this.project = config.project;
+        this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.fetchImpl = config.fetchImpl ?? fetch;
+    }
+    async capabilities(forceRefresh = false) {
+        if (this.capabilitiesCache && !forceRefresh) {
+            return this.capabilitiesCache;
+        }
+        const caps = await fetchCapabilities(this.baseUrl, this.apiKey, this.fetchImpl);
+        this.capabilitiesCache = caps;
+        return caps;
+    }
+    async invoke(action, payload, options) {
+        if (options?.ensureCapability) {
+            const caps = await this.capabilities();
+            if (!isActionSupported(caps, action)) {
+                throw new MuninSdkError({
+                    code: "FEATURE_DISABLED",
+                    message: `Action '${action}' is not supported by current server capabilities`,
+                });
+            }
+        }
+        const request = {
+            apiKey: this.apiKey,
+            projectId: this.project,
+            action,
+            payload,
+            requestId: options?.requestId,
+            client: {
+                name: "@kalera/munin-sdk",
+                version: "0.1.0",
+            },
+        };
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+        const response = await this.fetchImpl(`${this.baseUrl}/api/mcp/action`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify(request),
+            signal: controller.signal,
+        }).catch((error) => {
+            throw new MuninTransportError(`Request failed for action '${action}': ${String(error)}`);
+        });
+        clearTimeout(timeout);
+        const body = (await response.json());
+        if (!response.ok || (body.ok === false) || (body.success === false)) {
+            throw new MuninSdkError(body.error ?? {
+                code: "INTERNAL_ERROR",
+                message: `Unexpected failure invoking action '${action}'`,
+            });
+        }
+        return body;
+    }
+    async store(payload) {
+        return this.invoke("store", payload, { ensureCapability: true });
+    }
+    async retrieve(payload) {
+        return this.invoke("retrieve", payload, { ensureCapability: true });
+    }
+    async search(payload) {
+        return this.invoke("search", payload, { ensureCapability: true });
+    }
+    async list(payload = {}) {
+        return this.invoke("list", payload, { ensureCapability: true });
+    }
+    async recent(payload = {}) {
+        return this.invoke("recent", payload, { ensureCapability: true });
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,9 @@
+import type { MuninError } from "./types.js";
+export declare class MuninSdkError extends Error {
+    readonly code: MuninError["code"];
+    readonly details?: Record<string, unknown>;
+    constructor(error: MuninError);
+}
+export declare class MuninTransportError extends Error {
+    constructor(message: string);
+}

package/dist/errors.js

@@ -0,0 +1,16 @@
+export class MuninSdkError extends Error {
+    code;
+    details;
+    constructor(error) {
+        super(error.message);
+        this.name = "MuninSdkError";
+        this.code = error.code;
+        this.details = error.details;
+    }
+}
+export class MuninTransportError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "MuninTransportError";
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./types.js";
+export * from "./errors.js";
+export * from "./capabilities.js";
+export * from "./client.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from "./types.js";
+export * from "./errors.js";
+export * from "./capabilities.js";
+export * from "./client.js";

package/dist/types.d.ts

@@ -0,0 +1,45 @@
+export type MuninAction = "store" | "retrieve" | "search" | "list" | "recent" | "share" | "versions" | "rollback" | "encrypt" | "decrypt";
+export interface MuninActionEnvelope<TPayload = Record<string, unknown>> {
+    action: MuninAction;
+    project: string;
+    payload: TPayload;
+    requestId?: string;
+    client?: {
+        name: string;
+        version: string;
+    };
+}
+export interface MuninCapabilities {
+    specVersion: string;
+    actions: {
+        core: string[];
+        optional: string[];
+    };
+    features: Record<string, {
+        supported: boolean;
+        reason?: string;
+    }>;
+    metadata: {
+        serverVersion: string;
+        timestamp: string;
+        [key: string]: unknown;
+    };
+}
+export interface MuninError {
+    code: "AUTH_INVALID" | "FEATURE_DISABLED" | "NOT_FOUND" | "RATE_LIMITED" | "VALIDATION_ERROR" | "INTERNAL_ERROR";
+    message: string;
+    details?: Record<string, unknown>;
+}
+export interface MuninResponse<TData = unknown> {
+    ok: boolean;
+    data?: TData;
+    error?: MuninError;
+    requestId?: string;
+}
+export interface MuninClientConfig {
+    baseUrl: string;
+    apiKey?: string;
+    project: string;
+    timeoutMs?: number;
+    fetchImpl?: typeof fetch;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@kalera/munin-sdk",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "typescript": "^5.9.2",
+    "tsx": "^4.20.5"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "tsc -p tsconfig.json --noEmit",
+    "test": "tsx test/client.test.ts"
+  }
+}

package/src/capabilities.ts

@@ -0,0 +1,49 @@
+import type { MuninCapabilities, MuninResponse } from "./types.js";
+import { MuninSdkError, MuninTransportError } from "./errors.js";
+
+export async function fetchCapabilities(
+  baseUrl: string,
+  apiKey?: string,
+  fetchImpl: typeof fetch = fetch,
+): Promise<MuninCapabilities> {
+  const response = await fetchImpl(`${baseUrl}/api/mcp/capabilities`, {
+    method: "GET",
+    headers: {
+      "Content-Type": "application/json",
+      ...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}),
+    },
+  }).catch((error: unknown) => {
+    throw new MuninTransportError(
+      `Failed to call capabilities endpoint: ${String(error)}`,
+    );
+  });
+
+  if (!response.ok) {
+    throw new MuninTransportError(
+      `Capabilities request failed with status ${response.status}`,
+    );
+  }
+
+  const body = (await response.json()) as MuninResponse<MuninCapabilities>;
+
+  if (!body.ok || !body.data) {
+    throw new MuninSdkError(
+      body.error ?? {
+        code: "INTERNAL_ERROR",
+        message: "Capabilities response missing data",
+      },
+    );
+  }
+
+  return body.data;
+}
+
+export function isActionSupported(
+  capabilities: MuninCapabilities,
+  action: string,
+): boolean {
+  return (
+    capabilities.actions.core.includes(action) ||
+    capabilities.actions.optional.includes(action)
+  );
+}

package/src/client.ts

@@ -0,0 +1,124 @@
+import { MuninSdkError, MuninTransportError } from "./errors.js";
+import {
+  fetchCapabilities,
+  isActionSupported,
+} from "./capabilities.js";
+import type {
+  MuninAction,
+  MuninActionEnvelope,
+  MuninCapabilities,
+  MuninClientConfig,
+  MuninResponse,
+} from "./types.js";
+
+const DEFAULT_TIMEOUT_MS = 15_000;
+
+export class MuninClient {
+  private readonly baseUrl: string;
+  private readonly apiKey?: string;
+  private readonly project: string;
+  private readonly timeoutMs: number;
+  private readonly fetchImpl: typeof fetch;
+  private capabilitiesCache?: MuninCapabilities;
+
+  constructor(config: MuninClientConfig) {
+    this.baseUrl = config.baseUrl.replace(/\/$/, "");
+    this.apiKey = config.apiKey;
+    this.project = config.project;
+    this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.fetchImpl = config.fetchImpl ?? fetch;
+  }
+
+  async capabilities(forceRefresh = false): Promise<MuninCapabilities> {
+    if (this.capabilitiesCache && !forceRefresh) {
+      return this.capabilitiesCache;
+    }
+
+    const caps = await fetchCapabilities(
+      this.baseUrl,
+      this.apiKey,
+      this.fetchImpl,
+    );
+    this.capabilitiesCache = caps;
+    return caps;
+  }
+
+  async invoke<TPayload extends Record<string, unknown>, TData = unknown>(
+    action: MuninAction,
+    payload: TPayload,
+    options?: { requestId?: string; ensureCapability?: boolean },
+  ): Promise<MuninResponse<TData>> {
+    if (options?.ensureCapability) {
+      const caps = await this.capabilities();
+      if (!isActionSupported(caps, action)) {
+        throw new MuninSdkError({
+          code: "FEATURE_DISABLED",
+          message: `Action '${action}' is not supported by current server capabilities`,
+        });
+      }
+    }
+
+    const request = {
+      apiKey: this.apiKey,
+      projectId: this.project,
+      action,
+      payload,
+      requestId: options?.requestId,
+      client: {
+        name: "@kalera/munin-sdk",
+        version: "0.1.0",
+      },
+    };
+
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+
+    const response = await this.fetchImpl(`${this.baseUrl}/api/mcp/action`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify(request),
+      signal: controller.signal,
+    }).catch((error: unknown) => {
+      throw new MuninTransportError(
+        `Request failed for action '${action}': ${String(error)}`,
+      );
+    });
+
+    clearTimeout(timeout);
+
+    const body = (await response.json()) as any;
+
+    if (!response.ok || (body.ok === false) || (body.success === false)) {
+      throw new MuninSdkError(
+        body.error ?? {
+          code: "INTERNAL_ERROR",
+          message: `Unexpected failure invoking action '${action}'`,
+        },
+      );
+    }
+
+    return body;
+  }
+
+  async store(payload: Record<string, unknown>) {
+    return this.invoke("store", payload, { ensureCapability: true });
+  }
+
+  async retrieve(payload: Record<string, unknown>) {
+    return this.invoke("retrieve", payload, { ensureCapability: true });
+  }
+
+  async search(payload: Record<string, unknown>) {
+    return this.invoke("search", payload, { ensureCapability: true });
+  }
+
+  async list(payload: Record<string, unknown> = {}) {
+    return this.invoke("list", payload, { ensureCapability: true });
+  }
+
+  async recent(payload: Record<string, unknown> = {}) {
+    return this.invoke("recent", payload, { ensureCapability: true });
+  }
+}

package/src/errors.ts

@@ -0,0 +1,20 @@
+import type { MuninError } from "./types.js";
+
+export class MuninSdkError extends Error {
+  public readonly code: MuninError["code"];
+  public readonly details?: Record<string, unknown>;
+
+  constructor(error: MuninError) {
+    super(error.message);
+    this.name = "MuninSdkError";
+    this.code = error.code;
+    this.details = error.details;
+  }
+}
+
+export class MuninTransportError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "MuninTransportError";
+  }
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from "./types.js";
+export * from "./errors.js";
+export * from "./capabilities.js";
+export * from "./client.js";

package/src/types.ts

@@ -0,0 +1,63 @@
+export type MuninAction =
+  | "store"
+  | "retrieve"
+  | "search"
+  | "list"
+  | "recent"
+  | "share"
+  | "versions"
+  | "rollback"
+  | "encrypt"
+  | "decrypt";
+
+export interface MuninActionEnvelope<TPayload = Record<string, unknown>> {
+  action: MuninAction;
+  project: string;
+  payload: TPayload;
+  requestId?: string;
+  client?: {
+    name: string;
+    version: string;
+  };
+}
+
+export interface MuninCapabilities {
+  specVersion: string;
+  actions: {
+    core: string[];
+    optional: string[];
+  };
+  features: Record<string, { supported: boolean; reason?: string }>;
+  metadata: {
+    serverVersion: string;
+    timestamp: string;
+    [key: string]: unknown;
+  };
+}
+
+export interface MuninError {
+  code:
+    | "AUTH_INVALID"
+    | "FEATURE_DISABLED"
+    | "NOT_FOUND"
+    | "RATE_LIMITED"
+    | "VALIDATION_ERROR"
+    | "INTERNAL_ERROR";
+  message: string;
+  details?: Record<string, unknown>;
+}
+
+export interface MuninResponse<TData = unknown> {
+  ok: boolean;
+  data?: TData;
+  error?: MuninError;
+  requestId?: string;
+}
+
+export interface MuninClientConfig {
+  baseUrl: string;
+  apiKey?: string;
+  project: string;
+  timeoutMs?: number;
+  fetchImpl?: typeof fetch;
+}

package/test/client.test.ts

@@ -0,0 +1,64 @@
+import assert from "node:assert/strict";
+import { MuninClient } from "../src/client";
+
+async function run() {
+  const fakeFetch: typeof fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
+    const url = String(input);
+
+    if (url.endsWith("/api/mcp/capabilities")) {
+      return new Response(
+        JSON.stringify({
+          ok: true,
+          data: {
+            specVersion: "v1.0.0",
+            actions: {
+              core: ["store", "retrieve", "search", "list", "recent"],
+              optional: ["share"],
+            },
+            features: {
+              encryption: { supported: true },
+            },
+            metadata: {
+              serverVersion: "0.0.1",
+              timestamp: new Date().toISOString(),
+            },
+          },
+        }),
+        { status: 200, headers: { "Content-Type": "application/json" } },
+      );
+    }
+
+    if (url.endsWith("/api/mcp/action") && init?.method === "POST") {
+      const body = JSON.parse(String(init.body));
+      return new Response(
+        JSON.stringify({
+          ok: true,
+          data: {
+            echoedAction: body.action,
+            echoedProject: body.project,
+          },
+        }),
+        { status: 200, headers: { "Content-Type": "application/json" } },
+      );
+    }
+
+    return new Response(JSON.stringify({ ok: false }), { status: 404 });
+  }) as typeof fetch;
+
+  const client = new MuninClient({
+    baseUrl: "http://localhost:4000",
+    project: "default",
+    fetchImpl: fakeFetch,
+  });
+
+  const capabilities = await client.capabilities();
+  assert.equal(capabilities.specVersion, "v1.0.0");
+
+  const result = await client.store({ key: "hello", content: "world" });
+  assert.equal(result.ok, true);
+  assert.equal((result.data as any).echoedAction, "store");
+
+  console.log("sdk-ts tests passed");
+}
+
+void run();

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src"]
+}