@kweaver-ai/kweaver-sdk 0.5.1 → 0.5.2

package/dist/api/headers.js

@@ -0,0 +1,25 @@
+/**
+ * Shared HTTP header builder for all KWeaver API calls.
+ *
+ * Supports optional x-account-id / x-account-type headers read from
+ * environment variables KWEAVER_ACCOUNT_ID and KWEAVER_ACCOUNT_TYPE.
+ * These are required by older platform versions (e.g. dip-poc.aishu.cn)
+ * that do not infer account info from the token automatically.
+ */
+export function buildHeaders(accessToken, businessDomain) {
+    const headers = {
+        accept: "application/json, text/plain, */*",
+        "accept-language": "zh-cn",
+        authorization: `Bearer ${accessToken}`,
+        token: accessToken,
+        "x-business-domain": businessDomain,
+        "x-language": "zh-cn",
+    };
+    const accountId = process.env.KWEAVER_ACCOUNT_ID;
+    const accountType = process.env.KWEAVER_ACCOUNT_TYPE;
+    if (accountId)
+        headers["x-account-id"] = accountId;
+    if (accountType)
+        headers["x-account-type"] = accountType;
+    return headers;
+}

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

@@ -55,6 +55,43 @@ export interface ListSchemaTypesOptions {
 export declare function listObjectTypes(options: ListSchemaTypesOptions): Promise<string>;
 export declare function listRelationTypes(options: ListSchemaTypesOptions): Promise<string>;
 export declare function listActionTypes(options: ListSchemaTypesOptions): Promise<string>;
+export interface GetActionTypeOptions {
+    baseUrl: string;
+    accessToken: string;
+    knId: string;
+    atId: string;
+    businessDomain?: string;
+    branch?: string;
+}
+export declare function getActionType(options: GetActionTypeOptions): Promise<string>;
+export interface CreateActionTypesOptions {
+    baseUrl: string;
+    accessToken: string;
+    knId: string;
+    body: string;
+    businessDomain?: string;
+    branch?: string;
+}
+export declare function createActionTypes(options: CreateActionTypesOptions): Promise<string>;
+export interface UpdateActionTypeOptions {
+    baseUrl: string;
+    accessToken: string;
+    knId: string;
+    atId: string;
+    body: string;
+    businessDomain?: string;
+    branch?: string;
+}
+export declare function updateActionType(options: UpdateActionTypeOptions): Promise<string>;
+export interface DeleteActionTypesOptions {
+    baseUrl: string;
+    accessToken: string;
+    knId: string;
+    atIds: string;
+    businessDomain?: string;
+    branch?: string;
+}
+export declare function deleteActionTypes(options: DeleteActionTypesOptions): Promise<void>;
 export interface GetObjectTypeOptions {
     baseUrl: string;
     accessToken: string;
@@ -80,6 +117,7 @@ export interface UpdateObjectTypeOptions {
     otId: string;
     body: string;
     businessDomain?: string;
+    branch?: string;
 }
 export declare function updateObjectType(options: UpdateObjectTypeOptions): Promise<string>;
 export interface DeleteObjectTypesOptions {
@@ -88,6 +126,7 @@ export interface DeleteObjectTypesOptions {
     knId: string;
     otIds: string;
     businessDomain?: string;
+    branch?: string;
 }
 export declare function deleteObjectTypes(options: DeleteObjectTypesOptions): Promise<void>;
 export interface GetRelationTypeOptions {
@@ -115,6 +154,7 @@ export interface UpdateRelationTypeOptions {
     rtId: string;
     body: string;
     businessDomain?: string;
+    branch?: string;
 }
 export declare function updateRelationType(options: UpdateRelationTypeOptions): Promise<string>;
 export interface DeleteRelationTypesOptions {
@@ -123,6 +163,7 @@ export interface DeleteRelationTypesOptions {
     knId: string;
     rtIds: string;
     businessDomain?: string;
+    branch?: string;
 }
 export declare function deleteRelationTypes(options: DeleteRelationTypesOptions): Promise<void>;
 export interface BuildKnowledgeNetworkOptions {

package/dist/api/knowledge-networks.js

@@ -1,14 +1,5 @@
 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",
-    };
-}
+import { buildHeaders } from "./headers.js";
 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(/\/+$/, "");
@@ -156,6 +147,58 @@ export async function listActionTypes(options) {
     }
     return body;
 }
+export async function getActionType(options) {
+    const { baseUrl, accessToken, knId, atId, businessDomain = "bd_public", branch = "main" } = options;
+    const base = baseUrl.replace(/\/+$/, "");
+    const url = new URL(`${base}/api/ontology-manager/v1/knowledge-networks/${encodeURIComponent(knId)}/action-types/${encodeURIComponent(atId)}`);
+    url.searchParams.set("branch", branch);
+    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 createActionTypes(options) {
+    const { baseUrl, accessToken, knId, body, businessDomain = "bd_public", branch = "main" } = 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);
+    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 updateActionType(options) {
+    const { baseUrl, accessToken, knId, atId, body, businessDomain = "bd_public", branch = "main" } = options;
+    const base = baseUrl.replace(/\/+$/, "");
+    const url = new URL(`${base}/api/ontology-manager/v1/knowledge-networks/${encodeURIComponent(knId)}/action-types/${encodeURIComponent(atId)}`);
+    url.searchParams.set("branch", branch);
+    const response = await fetch(url.toString(), {
+        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 deleteActionTypes(options) {
+    const { baseUrl, accessToken, knId, atIds, businessDomain = "bd_public", branch = "main" } = options;
+    const base = baseUrl.replace(/\/+$/, "");
+    const url = new URL(`${base}/api/ontology-manager/v1/knowledge-networks/${encodeURIComponent(knId)}/action-types/${encodeURIComponent(atIds)}`);
+    url.searchParams.set("branch", branch);
+    const response = await fetch(url.toString(), { 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 getObjectType(options) {
     const { baseUrl, accessToken, knId, otId, businessDomain = "bd_public", branch = "main", } = options;
     const base = baseUrl.replace(/\/+$/, "");
@@ -191,10 +234,11 @@ export async function createObjectTypes(options) {
     return responseBody;
 }
 export async function updateObjectType(options) {
-    const { baseUrl, accessToken, knId, otId, body, businessDomain = "bd_public", } = options;
+    const { baseUrl, accessToken, knId, otId, body, businessDomain = "bd_public", branch = "main", } = options;
     const base = baseUrl.replace(/\/+$/, "");
-    const url = `${base}/api/ontology-manager/v1/knowledge-networks/${encodeURIComponent(knId)}/object-types/${encodeURIComponent(otId)}`;
-    const response = await fetch(url, {
+    const url = new URL(`${base}/api/ontology-manager/v1/knowledge-networks/${encodeURIComponent(knId)}/object-types/${encodeURIComponent(otId)}`);
+    url.searchParams.set("branch", branch);
+    const response = await fetch(url.toString(), {
         method: "PUT",
         headers: {
             ...buildHeaders(accessToken, businessDomain),
@@ -209,10 +253,11 @@ export async function updateObjectType(options) {
     return responseBody;
 }
 export async function deleteObjectTypes(options) {
-    const { baseUrl, accessToken, knId, otIds, businessDomain = "bd_public", } = options;
+    const { baseUrl, accessToken, knId, otIds, businessDomain = "bd_public", branch = "main", } = options;
     const base = baseUrl.replace(/\/+$/, "");
-    const url = `${base}/api/ontology-manager/v1/knowledge-networks/${encodeURIComponent(knId)}/object-types/${encodeURIComponent(otIds)}`;
-    const response = await fetch(url, {
+    const url = new URL(`${base}/api/ontology-manager/v1/knowledge-networks/${encodeURIComponent(knId)}/object-types/${encodeURIComponent(otIds)}`);
+    url.searchParams.set("branch", branch);
+    const response = await fetch(url.toString(), {
         method: "DELETE",
         headers: buildHeaders(accessToken, businessDomain),
     });
@@ -256,10 +301,11 @@ export async function createRelationTypes(options) {
     return responseBody;
 }
 export async function updateRelationType(options) {
-    const { baseUrl, accessToken, knId, rtId, body, businessDomain = "bd_public", } = options;
+    const { baseUrl, accessToken, knId, rtId, body, businessDomain = "bd_public", branch = "main", } = options;
     const base = baseUrl.replace(/\/+$/, "");
-    const url = `${base}/api/ontology-manager/v1/knowledge-networks/${encodeURIComponent(knId)}/relation-types/${encodeURIComponent(rtId)}`;
-    const response = await fetch(url, {
+    const url = new URL(`${base}/api/ontology-manager/v1/knowledge-networks/${encodeURIComponent(knId)}/relation-types/${encodeURIComponent(rtId)}`);
+    url.searchParams.set("branch", branch);
+    const response = await fetch(url.toString(), {
         method: "PUT",
         headers: {
             ...buildHeaders(accessToken, businessDomain),
@@ -274,10 +320,11 @@ export async function updateRelationType(options) {
     return responseBody;
 }
 export async function deleteRelationTypes(options) {
-    const { baseUrl, accessToken, knId, rtIds, businessDomain = "bd_public", } = options;
+    const { baseUrl, accessToken, knId, rtIds, businessDomain = "bd_public", branch = "main", } = options;
     const base = baseUrl.replace(/\/+$/, "");
-    const url = `${base}/api/ontology-manager/v1/knowledge-networks/${encodeURIComponent(knId)}/relation-types/${encodeURIComponent(rtIds)}`;
-    const response = await fetch(url, {
+    const url = new URL(`${base}/api/ontology-manager/v1/knowledge-networks/${encodeURIComponent(knId)}/relation-types/${encodeURIComponent(rtIds)}`);
+    url.searchParams.set("branch", branch);
+    const response = await fetch(url.toString(), {
         method: "DELETE",
         headers: buildHeaders(accessToken, businessDomain),
     });

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

@@ -1,3 +1,8 @@
+/**
+ * Fetch with timeout + retry for idempotent (read-only) ontology-query endpoints.
+ * Retries on 5xx, 429, and transient network errors with exponential backoff.
+ */
+export declare function fetchWithRetry(url: string, init: RequestInit): Promise<string>;
 export interface OntologyQueryBaseOptions {
     baseUrl: string;
     accessToken: string;
@@ -36,7 +41,15 @@ export interface ActionTypeQueryOptions extends OntologyQueryBaseOptions {
     excludeSystemProperties?: string[];
 }
 export declare function actionTypeQuery(options: ActionTypeQueryOptions): Promise<string>;
-/** Action-type execute: POST (has side effects) */
+/**
+ * Action-type execute: POST (has side effects).
+ *
+ * The request body must include `_instance_identities` — an array of objects
+ * identifying which instances the action operates on:
+ * ```json
+ * {"_instance_identities": [{"<primary_key>": "<value>"}], ...otherParams}
+ * ```
+ */
 export interface ActionTypeExecuteOptions extends OntologyQueryBaseOptions {
     atId: string;
     body: string;

package/dist/api/ontology-query.js

@@ -1,13 +1,63 @@
 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",
-    };
+import { buildHeaders } from "./headers.js";
+const QUERY_TIMEOUT_MS = 30_000;
+const QUERY_MAX_RETRIES = 2;
+const QUERY_RETRY_BASE_MS = 500;
+function isRetryableStatus(status) {
+    return status >= 500 || status === 429;
+}
+function isRetryableNetworkError(error) {
+    if (error instanceof HttpError)
+        return isRetryableStatus(error.status);
+    if (!(error instanceof Error))
+        return false;
+    if (error.name === "AbortError" || error.name === "TimeoutError")
+        return true;
+    const msg = error.message.toLowerCase();
+    const cause = "cause" in error && error.cause instanceof Error ? error.cause.message.toLowerCase() : "";
+    const combined = `${msg} ${cause}`;
+    return ["fetch failed", "econnreset", "econnrefused", "etimedout", "socket hang up", "network socket disconnected"].some((t) => combined.includes(t));
+}
+async function fetchWithTimeout(url, init) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), QUERY_TIMEOUT_MS);
+    try {
+        return await fetch(url, { ...init, signal: controller.signal });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Fetch with timeout + retry for idempotent (read-only) ontology-query endpoints.
+ * Retries on 5xx, 429, and transient network errors with exponential backoff.
+ */
+export async function fetchWithRetry(url, init) {
+    let lastError;
+    for (let attempt = 0; attempt <= QUERY_MAX_RETRIES; attempt++) {
+        try {
+            const response = await fetchWithTimeout(url, init);
+            const body = await response.text();
+            if (!response.ok) {
+                if (attempt < QUERY_MAX_RETRIES && isRetryableStatus(response.status)) {
+                    lastError = new HttpError(response.status, response.statusText, body);
+                    await new Promise((r) => setTimeout(r, QUERY_RETRY_BASE_MS * 2 ** attempt));
+                    continue;
+                }
+                throw new HttpError(response.status, response.statusText, body);
+            }
+            return body;
+        }
+        catch (error) {
+            lastError = error;
+            if (attempt < QUERY_MAX_RETRIES && isRetryableNetworkError(error)) {
+                await new Promise((r) => setTimeout(r, QUERY_RETRY_BASE_MS * 2 ** attempt));
+                continue;
+            }
+            throw error;
+        }
+    }
+    throw lastError;
 }
 export async function objectTypeQuery(options) {
     const { baseUrl, accessToken, knId, otId, body, businessDomain = "bd_public", includeTypeInfo, includeLogicParams, excludeSystemProperties, } = options;
@@ -29,16 +79,7 @@ export async function objectTypeQuery(options) {
         "content-type": "application/json",
         "X-HTTP-Method-Override": "GET",
     };
-    const response = await fetch(url.toString(), {
-        method: "POST",
-        headers,
-        body,
-    });
-    const responseBody = await response.text();
-    if (!response.ok) {
-        throw new HttpError(response.status, response.statusText, responseBody);
-    }
-    return responseBody;
+    return fetchWithRetry(url.toString(), { method: "POST", headers, body });
 }
 export async function objectTypeProperties(options) {
     const { baseUrl, accessToken, knId, otId, body, businessDomain = "bd_public", excludeSystemProperties, } = options;
@@ -54,16 +95,7 @@ export async function objectTypeProperties(options) {
         "content-type": "application/json",
         "X-HTTP-Method-Override": "GET",
     };
-    const response = await fetch(url.toString(), {
-        method: "POST",
-        headers,
-        body,
-    });
-    const responseBody = await response.text();
-    if (!response.ok) {
-        throw new HttpError(response.status, response.statusText, responseBody);
-    }
-    return responseBody;
+    return fetchWithRetry(url.toString(), { method: "POST", headers, body });
 }
 export async function subgraph(options) {
     const { baseUrl, accessToken, knId, body, businessDomain = "bd_public", includeLogicParams, excludeSystemProperties, queryType, } = options;
@@ -85,16 +117,7 @@ export async function subgraph(options) {
         "content-type": "application/json",
         "X-HTTP-Method-Override": "GET",
     };
-    const response = await fetch(url.toString(), {
-        method: "POST",
-        headers,
-        body,
-    });
-    const responseBody = await response.text();
-    if (!response.ok) {
-        throw new HttpError(response.status, response.statusText, responseBody);
-    }
-    return responseBody;
+    return fetchWithRetry(url.toString(), { method: "POST", headers, body });
 }
 export async function actionTypeQuery(options) {
     const { baseUrl, accessToken, knId, atId, body, businessDomain = "bd_public", includeTypeInfo, excludeSystemProperties, } = options;
@@ -113,16 +136,7 @@ export async function actionTypeQuery(options) {
         "content-type": "application/json",
         "X-HTTP-Method-Override": "GET",
     };
-    const response = await fetch(url.toString(), {
-        method: "POST",
-        headers,
-        body,
-    });
-    const responseBody = await response.text();
-    if (!response.ok) {
-        throw new HttpError(response.status, response.statusText, responseBody);
-    }
-    return responseBody;
+    return fetchWithRetry(url.toString(), { method: "POST", headers, body });
 }
 export async function actionTypeExecute(options) {
     const { baseUrl, accessToken, knId, atId, body, businessDomain = "bd_public" } = options;

package/dist/api/semantic-search.js

@@ -1,22 +1,12 @@
 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",
-        "content-type": "application/json",
-    };
-}
+import { buildHeaders } from "./headers.js";
 export async function semanticSearch(options) {
     const { baseUrl, accessToken, knId, query, businessDomain = "bd_public", mode = "keyword_vector_retrieval", rerankAction = "default", maxConcepts = 10, returnQueryUnderstanding = false, } = options;
     const base = baseUrl.replace(/\/+$/, "");
     const url = `${base}/api/agent-retrieval/v1/kn/semantic-search`;
     const response = await fetch(url, {
         method: "POST",
-        headers: buildHeaders(accessToken, businessDomain),
+        headers: { ...buildHeaders(accessToken, businessDomain), "content-type": "application/json" },
         body: JSON.stringify({
             kn_id: knId,
             query,

package/dist/api/skills.d.ts

@@ -0,0 +1,141 @@
+export type SkillStatus = "unpublish" | "published" | "offline";
+export type SkillFileType = "zip" | "content";
+export interface SkillSummary {
+    skill_id: string;
+    name: string;
+    description?: string;
+    version?: string;
+    status?: SkillStatus;
+    source?: string;
+    create_user?: string;
+    create_time?: number;
+    update_user?: string;
+    update_time?: number;
+    business_domain_id?: string;
+    category?: string;
+    category_name?: string;
+}
+export interface SkillInfo extends SkillSummary {
+    dependencies?: Record<string, unknown>;
+    extend_info?: Record<string, unknown>;
+}
+export interface SkillFileSummary {
+    rel_path: string;
+    file_type?: string;
+    size?: number;
+    mime_type?: string;
+}
+export interface SkillContentIndex {
+    skill_id: string;
+    url: string;
+    files: SkillFileSummary[];
+    status?: SkillStatus;
+}
+export interface SkillFileReadResult {
+    skill_id: string;
+    rel_path: string;
+    url: string;
+    mime_type?: string;
+    file_type?: string;
+}
+export interface RegisterSkillResult {
+    skill_id: string;
+    name: string;
+    description?: string;
+    version?: string;
+    status?: SkillStatus;
+    files?: string[];
+}
+export interface DeleteSkillResult {
+    skill_id: string;
+    deleted: boolean;
+}
+export interface UpdateSkillStatusResult {
+    skill_id: string;
+    status: SkillStatus;
+}
+export interface SkillListResult {
+    total_count?: number;
+    total?: number;
+    page?: number;
+    page_size?: number;
+    total_page?: number;
+    total_pages?: number;
+    has_next?: boolean;
+    has_prev?: boolean;
+    data: SkillSummary[];
+}
+export interface SkillApiBaseOptions {
+    baseUrl: string;
+    accessToken: string;
+    businessDomain?: string;
+}
+export interface ListSkillsOptions extends SkillApiBaseOptions {
+    page?: number;
+    pageSize?: number;
+    sortBy?: "create_time" | "update_time" | "name";
+    sortOrder?: "asc" | "desc";
+    all?: boolean;
+    name?: string;
+    status?: SkillStatus;
+    source?: string;
+    createUser?: string;
+}
+export interface ListSkillMarketOptions extends SkillApiBaseOptions {
+    page?: number;
+    pageSize?: number;
+    sortBy?: "create_time" | "update_time" | "name";
+    sortOrder?: "asc" | "desc";
+    all?: boolean;
+    name?: string;
+    source?: string;
+}
+export interface GetSkillOptions extends SkillApiBaseOptions {
+    skillId: string;
+}
+export interface RegisterSkillContentOptions extends SkillApiBaseOptions {
+    content: string;
+    source?: string;
+    extendInfo?: Record<string, unknown>;
+}
+export interface RegisterSkillZipOptions extends SkillApiBaseOptions {
+    filename: string;
+    bytes: Uint8Array;
+    source?: string;
+    extendInfo?: Record<string, unknown>;
+}
+export interface UpdateSkillStatusOptions extends SkillApiBaseOptions {
+    skillId: string;
+    status: SkillStatus;
+}
+export interface ReadSkillFileOptions extends SkillApiBaseOptions {
+    skillId: string;
+    relPath: string;
+}
+export interface DownloadSkillOptions extends SkillApiBaseOptions {
+    skillId: string;
+}
+export interface DownloadedSkillArchive {
+    fileName: string;
+    bytes: Uint8Array;
+}
+export interface InstallSkillArchiveOptions {
+    bytes: Uint8Array;
+    directory: string;
+    force?: boolean;
+}
+export declare function listSkills(options: ListSkillsOptions): Promise<SkillListResult>;
+export declare function listSkillMarket(options: ListSkillMarketOptions): Promise<SkillListResult>;
+export declare function getSkill(options: GetSkillOptions): Promise<SkillInfo>;
+export declare function deleteSkill(options: GetSkillOptions): Promise<DeleteSkillResult>;
+export declare function updateSkillStatus(options: UpdateSkillStatusOptions): Promise<UpdateSkillStatusResult>;
+export declare function registerSkillContent(options: RegisterSkillContentOptions): Promise<RegisterSkillResult>;
+export declare function registerSkillZip(options: RegisterSkillZipOptions): Promise<RegisterSkillResult>;
+export declare function getSkillContentIndex(options: GetSkillOptions): Promise<SkillContentIndex>;
+export declare function fetchSkillContent(options: GetSkillOptions): Promise<string>;
+export declare function readSkillFile(options: ReadSkillFileOptions): Promise<SkillFileReadResult>;
+export declare function fetchSkillFile(options: ReadSkillFileOptions): Promise<Uint8Array>;
+export declare function downloadSkill(options: DownloadSkillOptions): Promise<DownloadedSkillArchive>;
+export declare function installSkillArchive(options: InstallSkillArchiveOptions): {
+    directory: string;
+};