@kweaver-ai/kweaver-sdk 0.4.0

package/dist/api/context-loader.js

@@ -0,0 +1,259 @@
+import { fetchTextOrThrow } from "../utils/http.js";
+const MCP_PROTOCOL_VERSION = "2024-11-05";
+const sessionCache = new Map();
+function sessionKey(options) {
+    return `${options.mcpUrl}:${options.knId}`;
+}
+function buildHeaders(options, sessionId) {
+    const headers = {
+        "Content-Type": "application/json",
+        Accept: "application/json, text/event-stream",
+        Authorization: `Bearer ${options.accessToken}`,
+        "X-Kn-ID": options.knId,
+        "MCP-Protocol-Version": MCP_PROTOCOL_VERSION,
+    };
+    if (sessionId) {
+        headers["MCP-Session-Id"] = sessionId;
+    }
+    return headers;
+}
+async function ensureSession(options) {
+    const key = sessionKey(options);
+    const cached = sessionCache.get(key);
+    if (cached)
+        return cached;
+    const initBody = JSON.stringify({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "initialize",
+        params: {
+            protocolVersion: MCP_PROTOCOL_VERSION,
+            capabilities: {},
+            clientInfo: { name: "kweaver-caller", version: "0.1.0" },
+        },
+    });
+    const { response, body } = await fetchTextOrThrow(options.mcpUrl, {
+        method: "POST",
+        headers: buildHeaders(options),
+        body: initBody,
+    });
+    const sessionId = response.headers.get("MCP-Session-Id") ?? response.headers.get("mcp-session-id");
+    if (!sessionId) {
+        throw new Error("MCP server did not return MCP-Session-Id. The server may require session initialization.");
+    }
+    const initNotifBody = JSON.stringify({
+        jsonrpc: "2.0",
+        method: "notifications/initialized",
+    });
+    await fetchTextOrThrow(options.mcpUrl, {
+        method: "POST",
+        headers: buildHeaders(options, sessionId),
+        body: initNotifBody,
+    });
+    sessionCache.set(key, sessionId);
+    return sessionId;
+}
+function isMissingInputParams(obj) {
+    return (typeof obj === "object" &&
+        obj !== null &&
+        obj.error_code === "MISSING_INPUT_PARAMS");
+}
+/** Build retry hint from MISSING_INPUT_PARAMS response. */
+export function formatMissingInputParamsHint(err) {
+    const lines = [
+        "MISSING_INPUT_PARAMS: " + err.message,
+        "Add the following to additional_context and retry:",
+    ];
+    for (const m of err.missing ?? []) {
+        for (const p of m.params ?? []) {
+            if (p.hint)
+                lines.push(`  - ${p.name}: ${p.hint}`);
+        }
+    }
+    return lines.join("\n");
+}
+/** Guardrail: value_from only supports "const"; must appear with value. */
+export function validateCondition(condition) {
+    if (!condition || typeof condition !== "object")
+        return;
+    const c = condition;
+    const sub = c.sub_conditions;
+    if (Array.isArray(sub)) {
+        for (const s of sub) {
+            if (s && typeof s === "object") {
+                const sc = s;
+                if (sc.value_from !== undefined && sc.value_from !== "const") {
+                    throw new Error('Condition value_from only supports "const". Must use value_from: "const" with value.');
+                }
+                if (sc.value_from === "const" && sc.value === undefined) {
+                    throw new Error('When value_from is "const", value must be provided.');
+                }
+            }
+        }
+    }
+    if (c.value_from !== undefined && c.value_from !== "const") {
+        throw new Error('Condition value_from only supports "const".');
+    }
+}
+/** Guardrail: _instance_identity must be a plain object (from Layer 2 output, not fabricated). */
+export function validateInstanceIdentity(v, label) {
+    if (v === null || typeof v !== "object" || Array.isArray(v)) {
+        throw new Error(`${label} must be a plain object from Layer 2 query result (_instance_identity). Do not fabricate.`);
+    }
+}
+/** Guardrail: _instance_identities must be array of plain objects from Layer 2. */
+export function validateInstanceIdentities(v) {
+    if (!Array.isArray(v)) {
+        throw new Error("_instance_identities must be an array from Layer 2 query result.");
+    }
+    for (let i = 0; i < v.length; i += 1) {
+        validateInstanceIdentity(v[i], `_instance_identities[${i}]`);
+    }
+}
+let requestId = 0;
+/** Call a generic MCP JSON-RPC method (e.g. tools/list, resources/list). Returns result as-is. */
+async function callMcpMethod(options, method, params = {}) {
+    const sessionId = await ensureSession(options);
+    const id = (requestId += 1);
+    const body = JSON.stringify({
+        jsonrpc: "2.0",
+        method,
+        params: Object.keys(params).length > 0 ? params : undefined,
+        id,
+    });
+    const { body: responseBody } = await fetchTextOrThrow(options.mcpUrl, {
+        method: "POST",
+        headers: buildHeaders(options, sessionId),
+        body,
+    });
+    let parsed;
+    try {
+        parsed = JSON.parse(responseBody);
+    }
+    catch {
+        throw new Error(`Context-loader returned invalid JSON: ${responseBody.slice(0, 200)}`);
+    }
+    const rpc = parsed;
+    if (rpc.error) {
+        throw new Error(`Context-loader error: ${rpc.error.message}`);
+    }
+    if (rpc.result !== undefined) {
+        return rpc.result;
+    }
+    throw new Error("Context-loader returned no result");
+}
+async function callTool(options, toolName, args) {
+    const sessionId = await ensureSession(options);
+    const id = (requestId += 1);
+    const body = JSON.stringify({
+        jsonrpc: "2.0",
+        method: "tools/call",
+        params: { name: toolName, arguments: args },
+        id,
+    });
+    const { body: responseBody } = await fetchTextOrThrow(options.mcpUrl, {
+        method: "POST",
+        headers: buildHeaders(options, sessionId),
+        body,
+    });
+    let parsed;
+    try {
+        parsed = JSON.parse(responseBody);
+    }
+    catch {
+        throw new Error(`Context-loader returned invalid JSON: ${responseBody.slice(0, 200)}`);
+    }
+    if (isMissingInputParams(parsed)) {
+        throw new Error(formatMissingInputParamsHint(parsed));
+    }
+    const rpc = parsed;
+    if (rpc.error) {
+        const data = rpc.error.data;
+        if (isMissingInputParams(data)) {
+            throw new Error(formatMissingInputParamsHint(data));
+        }
+        throw new Error(`Context-loader error: ${rpc.error.message}`);
+    }
+    const result = rpc.result;
+    if (result !== undefined) {
+        const content = result.content;
+        if (Array.isArray(content) && content.length > 0) {
+            const first = content[0];
+            const text = first?.text;
+            if (typeof text === "string") {
+                try {
+                    return JSON.parse(text);
+                }
+                catch {
+                    return { raw: text };
+                }
+            }
+        }
+        return result;
+    }
+    const direct = parsed;
+    if ("object_types" in direct ||
+        "concepts" in direct ||
+        "datas" in direct ||
+        "entries" in direct ||
+        "_dynamic_tools" in direct) {
+        return parsed;
+    }
+    throw new Error("Context-loader returned no result");
+}
+/** Layer 1: kn_search. Returns object_types, relation_types, action_types. */
+export async function knSearch(options, args) {
+    return callTool(options, "kn_search", { ...args });
+}
+/** Layer 1: kn_schema_search. Returns concepts (candidate discovery only). */
+export async function knSchemaSearch(options, args) {
+    return callTool(options, "kn_schema_search", { ...args });
+}
+/** Layer 2: query_object_instance. Returns datas with _instance_identity. */
+export async function queryObjectInstance(options, args) {
+    validateCondition(args.condition);
+    return callTool(options, "query_object_instance", { ...args });
+}
+/** Layer 2: query_instance_subgraph. Returns entries with nested _instance_identity. */
+export async function queryInstanceSubgraph(options, args) {
+    for (const path of args.relation_type_paths) {
+        for (const ot of path.object_types) {
+            validateCondition(ot.condition);
+        }
+    }
+    return callTool(options, "query_instance_subgraph", { ...args });
+}
+/** Layer 3: get_logic_properties_values. Throws with retry hint on MISSING_INPUT_PARAMS. */
+export async function getLogicPropertiesValues(options, args) {
+    validateInstanceIdentities(args._instance_identities);
+    return callTool(options, "get_logic_properties_values", { ...args });
+}
+/** Layer 3: get_action_info. Returns _dynamic_tools. */
+export async function getActionInfo(options, args) {
+    validateInstanceIdentity(args._instance_identity, "_instance_identity");
+    return callTool(options, "get_action_info", { ...args });
+}
+/** MCP tools/list. Returns list of available tools. */
+export async function listTools(options, params) {
+    return callMcpMethod(options, "tools/list", params ? { cursor: params.cursor } : {});
+}
+/** MCP resources/list. Returns list of available resources. */
+export async function listResources(options, params) {
+    return callMcpMethod(options, "resources/list", params ? { cursor: params.cursor } : {});
+}
+/** MCP resources/read. Returns resource content by URI. */
+export async function readResource(options, uri) {
+    return callMcpMethod(options, "resources/read", { uri });
+}
+/** MCP resources/templates/list. Returns list of resource templates. */
+export async function listResourceTemplates(options, params) {
+    return callMcpMethod(options, "resources/templates/list", params ? { cursor: params.cursor } : {});
+}
+/** MCP prompts/list. Returns list of available prompts. */
+export async function listPrompts(options, params) {
+    return callMcpMethod(options, "prompts/list", params ? { cursor: params.cursor } : {});
+}
+/** MCP prompts/get. Returns prompt by name with optional arguments. */
+export async function getPrompt(options, name, args) {
+    return callMcpMethod(options, "prompts/get", args ? { name, arguments: args } : { name });
+}

package/dist/api/conversations.d.ts

@@ -0,0 +1,24 @@
+export interface ListConversationsOptions {
+    baseUrl: string;
+    accessToken: string;
+    agentId: string;
+    businessDomain?: string;
+    limit?: number;
+}
+export interface ListMessagesOptions {
+    baseUrl: string;
+    accessToken: string;
+    conversationId: string;
+    businessDomain?: string;
+    limit?: number;
+}
+/**
+ * List conversations for an agent.
+ * Returns empty array on 404 (endpoint may not be available in all deployments).
+ */
+export declare function listConversations(opts: ListConversationsOptions): Promise<string>;
+/**
+ * List messages for a conversation.
+ * Returns empty array on 404 (endpoint may not be available in all deployments).
+ */
+export declare function listMessages(opts: ListMessagesOptions): Promise<string>;

package/dist/api/conversations.js

@@ -0,0 +1,64 @@
+function buildConversationsUrl(baseUrl, agentId) {
+    const base = baseUrl.replace(/\/+$/, "");
+    return `${base}/api/agent-app/v1/app/${agentId}/conversations`;
+}
+function buildMessagesUrl(baseUrl, conversationId) {
+    const base = baseUrl.replace(/\/+$/, "");
+    return `${base}/api/agent-app/v1/conversations/${conversationId}/messages`;
+}
+/**
+ * List conversations for an agent.
+ * Returns empty array on 404 (endpoint may not be available in all deployments).
+ */
+export async function listConversations(opts) {
+    const { baseUrl, accessToken, agentId, businessDomain = "bd_public", limit } = opts;
+    const url = new URL(buildConversationsUrl(baseUrl, agentId));
+    if (limit !== undefined) {
+        url.searchParams.set("limit", String(limit));
+    }
+    const response = await fetch(url.toString(), {
+        method: "GET",
+        headers: {
+            accept: "application/json",
+            authorization: `Bearer ${accessToken}`,
+            token: accessToken,
+            "x-business-domain": businessDomain,
+        },
+    });
+    if (response.status === 404) {
+        return "[]";
+    }
+    const body = await response.text();
+    if (!response.ok) {
+        return "[]";
+    }
+    return body || "[]";
+}
+/**
+ * List messages for a conversation.
+ * Returns empty array on 404 (endpoint may not be available in all deployments).
+ */
+export async function listMessages(opts) {
+    const { baseUrl, accessToken, conversationId, businessDomain = "bd_public", limit } = opts;
+    const url = new URL(buildMessagesUrl(baseUrl, conversationId));
+    if (limit !== undefined) {
+        url.searchParams.set("limit", String(limit));
+    }
+    const response = await fetch(url.toString(), {
+        method: "GET",
+        headers: {
+            accept: "application/json",
+            authorization: `Bearer ${accessToken}`,
+            token: accessToken,
+            "x-business-domain": businessDomain,
+        },
+    });
+    if (response.status === 404) {
+        return "[]";
+    }
+    const body = await response.text();
+    if (!response.ok) {
+        return "[]";
+    }
+    return body || "[]";
+}

package/dist/api/knowledge-networks.d.ts

@@ -0,0 +1,57 @@
+export interface ListKnowledgeNetworksOptions {
+    baseUrl: string;
+    accessToken: string;
+    businessDomain?: string;
+    offset?: number;
+    limit?: number;
+    sort?: string;
+    direction?: "asc" | "desc";
+    name_pattern?: string;
+    tag?: string;
+}
+export declare function listKnowledgeNetworks(options: ListKnowledgeNetworksOptions): Promise<string>;
+export interface GetKnowledgeNetworkOptions {
+    baseUrl: string;
+    accessToken: string;
+    knId: string;
+    businessDomain?: string;
+    mode?: "export" | "";
+    include_statistics?: boolean;
+}
+export declare function getKnowledgeNetwork(options: GetKnowledgeNetworkOptions): Promise<string>;
+export interface CreateKnowledgeNetworkOptions {
+    baseUrl: string;
+    accessToken: string;
+    body: string;
+    businessDomain?: string;
+    import_mode?: "normal" | "ignore" | "overwrite";
+    validate_dependency?: boolean;
+}
+export declare function createKnowledgeNetwork(options: CreateKnowledgeNetworkOptions): Promise<string>;
+export interface UpdateKnowledgeNetworkOptions {
+    baseUrl: string;
+    accessToken: string;
+    knId: string;
+    body: string;
+    businessDomain?: string;
+}
+export declare function updateKnowledgeNetwork(options: UpdateKnowledgeNetworkOptions): Promise<string>;
+export interface DeleteKnowledgeNetworkOptions {
+    baseUrl: string;
+    accessToken: string;
+    knId: string;
+    businessDomain?: string;
+}
+export declare function deleteKnowledgeNetwork(options: DeleteKnowledgeNetworkOptions): Promise<void>;
+/** List object types, relation types, or action types (ontology-manager). */
+export interface ListSchemaTypesOptions {
+    baseUrl: string;
+    accessToken: string;
+    knId: string;
+    businessDomain?: string;
+    branch?: string;
+    limit?: number;
+}
+export declare function listObjectTypes(options: ListSchemaTypesOptions): Promise<string>;
+export declare function listRelationTypes(options: ListSchemaTypesOptions): Promise<string>;
+export declare function listActionTypes(options: ListSchemaTypesOptions): Promise<string>;

package/dist/api/knowledge-networks.js

@@ -0,0 +1,158 @@
+import { HttpError } from "../utils/http.js";
+function buildHeaders(accessToken, businessDomain) {
+    return {
+        accept: "application/json, text/plain, */*",
+        "accept-language": "zh-cn",
+        authorization: `Bearer ${accessToken}`,
+        token: accessToken,
+        "x-business-domain": businessDomain,
+        "x-language": "zh-cn",
+    };
+}
+export async function listKnowledgeNetworks(options) {
+    const { baseUrl, accessToken, businessDomain = "bd_public", offset = 0, limit = 50, sort = "update_time", direction = "desc", name_pattern, tag, } = options;
+    const base = baseUrl.replace(/\/+$/, "");
+    const url = new URL(`${base}/api/ontology-manager/v1/knowledge-networks`);
+    url.searchParams.set("offset", String(offset));
+    url.searchParams.set("limit", String(limit));
+    url.searchParams.set("direction", direction);
+    url.searchParams.set("sort", sort);
+    if (name_pattern !== undefined && name_pattern !== "") {
+        url.searchParams.set("name_pattern", name_pattern);
+    }
+    if (tag !== undefined && tag !== "") {
+        url.searchParams.set("tag", tag);
+    }
+    const response = await fetch(url.toString(), {
+        method: "GET",
+        headers: buildHeaders(accessToken, businessDomain),
+    });
+    const body = await response.text();
+    if (!response.ok) {
+        throw new HttpError(response.status, response.statusText, body);
+    }
+    return body;
+}
+export async function getKnowledgeNetwork(options) {
+    const { baseUrl, accessToken, knId, businessDomain = "bd_public", mode, include_statistics, } = options;
+    const base = baseUrl.replace(/\/+$/, "");
+    const url = new URL(`${base}/api/ontology-manager/v1/knowledge-networks/${encodeURIComponent(knId)}`);
+    if (mode === "export") {
+        url.searchParams.set("mode", "export");
+    }
+    if (include_statistics === true) {
+        url.searchParams.set("include_statistics", "true");
+    }
+    const response = await fetch(url.toString(), {
+        method: "GET",
+        headers: buildHeaders(accessToken, businessDomain),
+    });
+    const body = await response.text();
+    if (!response.ok) {
+        throw new HttpError(response.status, response.statusText, body);
+    }
+    return body;
+}
+export async function createKnowledgeNetwork(options) {
+    const { baseUrl, accessToken, body, businessDomain = "bd_public", import_mode, validate_dependency, } = options;
+    const base = baseUrl.replace(/\/+$/, "");
+    const url = new URL(`${base}/api/ontology-manager/v1/knowledge-networks`);
+    if (import_mode) {
+        url.searchParams.set("import_mode", import_mode);
+    }
+    if (validate_dependency !== undefined) {
+        url.searchParams.set("validate_dependency", String(validate_dependency));
+    }
+    const response = await fetch(url.toString(), {
+        method: "POST",
+        headers: {
+            ...buildHeaders(accessToken, businessDomain),
+            "content-type": "application/json",
+        },
+        body,
+    });
+    const responseBody = await response.text();
+    if (!response.ok) {
+        throw new HttpError(response.status, response.statusText, responseBody);
+    }
+    return responseBody;
+}
+export async function updateKnowledgeNetwork(options) {
+    const { baseUrl, accessToken, knId, body, businessDomain = "bd_public", } = options;
+    const base = baseUrl.replace(/\/+$/, "");
+    const url = `${base}/api/ontology-manager/v1/knowledge-networks/${encodeURIComponent(knId)}`;
+    const response = await fetch(url, {
+        method: "PUT",
+        headers: {
+            ...buildHeaders(accessToken, businessDomain),
+            "content-type": "application/json",
+        },
+        body,
+    });
+    const responseBody = await response.text();
+    if (!response.ok) {
+        throw new HttpError(response.status, response.statusText, responseBody);
+    }
+    return responseBody;
+}
+export async function deleteKnowledgeNetwork(options) {
+    const { baseUrl, accessToken, knId, businessDomain = "bd_public", } = options;
+    const base = baseUrl.replace(/\/+$/, "");
+    const url = `${base}/api/ontology-manager/v1/knowledge-networks/${encodeURIComponent(knId)}`;
+    const response = await fetch(url, {
+        method: "DELETE",
+        headers: buildHeaders(accessToken, businessDomain),
+    });
+    if (!response.ok) {
+        const body = await response.text();
+        throw new HttpError(response.status, response.statusText, body);
+    }
+}
+export async function listObjectTypes(options) {
+    const { baseUrl, accessToken, knId, businessDomain = "bd_public", branch = "main", limit = -1, } = options;
+    const base = baseUrl.replace(/\/+$/, "");
+    const url = new URL(`${base}/api/ontology-manager/v1/knowledge-networks/${encodeURIComponent(knId)}/object-types`);
+    url.searchParams.set("branch", branch);
+    url.searchParams.set("limit", String(limit));
+    const response = await fetch(url.toString(), {
+        method: "GET",
+        headers: buildHeaders(accessToken, businessDomain),
+    });
+    const body = await response.text();
+    if (!response.ok) {
+        throw new HttpError(response.status, response.statusText, body);
+    }
+    return body;
+}
+export async function listRelationTypes(options) {
+    const { baseUrl, accessToken, knId, businessDomain = "bd_public", branch = "main", limit = -1, } = options;
+    const base = baseUrl.replace(/\/+$/, "");
+    const url = new URL(`${base}/api/ontology-manager/v1/knowledge-networks/${encodeURIComponent(knId)}/relation-types`);
+    url.searchParams.set("branch", branch);
+    url.searchParams.set("limit", String(limit));
+    const response = await fetch(url.toString(), {
+        method: "GET",
+        headers: buildHeaders(accessToken, businessDomain),
+    });
+    const body = await response.text();
+    if (!response.ok) {
+        throw new HttpError(response.status, response.statusText, body);
+    }
+    return body;
+}
+export async function listActionTypes(options) {
+    const { baseUrl, accessToken, knId, businessDomain = "bd_public", branch = "main", limit = -1, } = options;
+    const base = baseUrl.replace(/\/+$/, "");
+    const url = new URL(`${base}/api/ontology-manager/v1/knowledge-networks/${encodeURIComponent(knId)}/action-types`);
+    url.searchParams.set("branch", branch);
+    url.searchParams.set("limit", String(limit));
+    const response = await fetch(url.toString(), {
+        method: "GET",
+        headers: buildHeaders(accessToken, businessDomain),
+    });
+    const body = await response.text();
+    if (!response.ok) {
+        throw new HttpError(response.status, response.statusText, body);
+    }
+    return body;
+}

package/dist/api/ontology-query.d.ts

@@ -0,0 +1,75 @@
+export interface OntologyQueryBaseOptions {
+    baseUrl: string;
+    accessToken: string;
+    knId: string;
+    businessDomain?: string;
+}
+/** Object-type query: POST with X-HTTP-Method-Override: GET */
+export interface ObjectTypeQueryOptions extends OntologyQueryBaseOptions {
+    otId: string;
+    body: string;
+    includeTypeInfo?: boolean;
+    includeLogicParams?: boolean;
+    excludeSystemProperties?: string[];
+}
+export declare function objectTypeQuery(options: ObjectTypeQueryOptions): Promise<string>;
+/** Object-type properties: POST with X-HTTP-Method-Override: GET */
+export interface ObjectTypePropertiesOptions extends OntologyQueryBaseOptions {
+    otId: string;
+    body: string;
+    excludeSystemProperties?: string[];
+}
+export declare function objectTypeProperties(options: ObjectTypePropertiesOptions): Promise<string>;
+/** Subgraph: POST */
+export interface SubgraphOptions extends OntologyQueryBaseOptions {
+    body: string;
+    includeLogicParams?: boolean;
+    excludeSystemProperties?: string[];
+    queryType?: "" | "relation_path";
+}
+export declare function subgraph(options: SubgraphOptions): Promise<string>;
+/** Action-type query: POST with X-HTTP-Method-Override: GET */
+export interface ActionTypeQueryOptions extends OntologyQueryBaseOptions {
+    atId: string;
+    body: string;
+    includeTypeInfo?: boolean;
+    excludeSystemProperties?: string[];
+}
+export declare function actionTypeQuery(options: ActionTypeQueryOptions): Promise<string>;
+/** Action-type execute: POST (has side effects) */
+export interface ActionTypeExecuteOptions extends OntologyQueryBaseOptions {
+    atId: string;
+    body: string;
+}
+export declare function actionTypeExecute(options: ActionTypeExecuteOptions): Promise<string>;
+/** Action-execution get: GET */
+export interface ActionExecutionGetOptions extends OntologyQueryBaseOptions {
+    executionId: string;
+}
+export declare function actionExecutionGet(options: ActionExecutionGetOptions): Promise<string>;
+/** Action-logs list: GET */
+export interface ActionLogsListOptions extends OntologyQueryBaseOptions {
+    actionTypeId?: string;
+    status?: string;
+    triggerType?: string;
+    startTimeFrom?: number;
+    startTimeTo?: number;
+    limit?: number;
+    needTotal?: boolean;
+    searchAfter?: string;
+}
+export declare function actionLogsList(options: ActionLogsListOptions): Promise<string>;
+/** Action-log get: GET */
+export interface ActionLogGetOptions extends OntologyQueryBaseOptions {
+    logId: string;
+    resultsLimit?: number;
+    resultsOffset?: number;
+    resultsStatus?: "success" | "failed";
+}
+export declare function actionLogGet(options: ActionLogGetOptions): Promise<string>;
+/** Action-log cancel: POST (has side effects) */
+export interface ActionLogCancelOptions extends OntologyQueryBaseOptions {
+    logId: string;
+    body?: string;
+}
+export declare function actionLogCancel(options: ActionLogCancelOptions): Promise<string>;