@tbox-dev-js/sdk 0.1.0

package/dist/conversation.d.ts

@@ -0,0 +1,112 @@
+/**
+ * 百宝箱会话管理 SDK - ConversationClient 核心类
+ *
+ * 封装 /openapi/v1/conversation 下的全部接口
+ */
+import type { TboxPluginClientConfig, MessageQueryRequest, MessageInfo, ConversationQueryRequest, ConversationInfo, ConversationCreateRequest, MessageSaveRequest, PaginationResult, SdkResponse } from './types';
+/**
+ * 百宝箱会话管理客户端
+ *
+ * @example
+ * ```ts
+ * import { TboxConversationClient } from '@tbox/plugin-sdk';
+ *
+ * const client = new TboxConversationClient({ apiKey: 'your-api-key' });
+ *
+ * // 创建新会话
+ * const res = await client.createConversation({ agentId: 'app-id', userId: 'user-id' });
+ * if (res.success) {
+ *   console.log('会话 ID:', res.data);
+ * }
+ * ```
+ */
+export declare class TboxConversationClient {
+    private readonly http;
+    constructor(config: TboxPluginClientConfig);
+    /**
+     * 创建新会话
+     *
+     * POST /openapi/v1/conversation/create
+     *
+     * @param request - 创建会话请求，包含 agentId 和 userId
+     * @returns 新会话 ID（字符串）
+     *
+     * @example
+     * ```ts
+     * const res = await client.createConversation({
+     *   agentId: 'your-app-id',
+     *   userId: 'user-123',
+     * });
+     * if (res.success) {
+     *   const conversationId = res.data;
+     * }
+     * ```
+     */
+    createConversation(request: ConversationCreateRequest): Promise<SdkResponse<string>>;
+    /**
+     * 查询会话列表（分页）
+     *
+     * POST /openapi/v1/conversation/list
+     *
+     * @param request - 查询请求，支持按 agentId、userId 过滤，支持分页
+     * @returns 分页会话列表
+     *
+     * @example
+     * ```ts
+     * const res = await client.listConversations({
+     *   agentId: 'your-app-id',
+     *   userId: 'user-123',
+     *   pageNum: 1,
+     *   pageSize: 20,
+     * });
+     * if (res.success) {
+     *   console.log(res.data?.list);
+     * }
+     * ```
+     */
+    listConversations(request: ConversationQueryRequest): Promise<SdkResponse<PaginationResult<ConversationInfo>>>;
+    /**
+     * 查询消息列表（分页）
+     *
+     * POST /openapi/v1/conversation/message/list
+     *
+     * @param request - 查询请求，支持按 conversationId、agentId、userId 过滤，支持分页
+     * @returns 分页消息列表
+     *
+     * @example
+     * ```ts
+     * const res = await client.listMessages({
+     *   conversationId: 'conv-id-xxx',
+     *   pageNum: 1,
+     *   pageSize: 20,
+     * });
+     * if (res.success) {
+     *   console.log(res.data?.list);
+     * }
+     * ```
+     */
+    listMessages(request: MessageQueryRequest): Promise<SdkResponse<PaginationResult<MessageInfo>>>;
+    /**
+     * 新增会话消息
+     *
+     * POST /openapi/v1/conversation/message/save
+     *
+     * 将一条对话消息（问题 + 回答）保存到指定会话中。
+     *
+     * @param request - 保存消息请求
+     * @returns 消息 ID（字符串）
+     *
+     * @example
+     * ```ts
+     * const res = await client.saveMessage({
+     *   conversationId: 'conv-id-xxx',
+     *   query: '今天天气怎么样？',
+     *   answer: '今天杭州晴天，25°C。',
+     * });
+     * if (res.success) {
+     *   const messageId = res.data;
+     * }
+     * ```
+     */
+    saveMessage(request: MessageSaveRequest): Promise<SdkResponse<string>>;
+}

package/dist/core.d.ts

@@ -0,0 +1,79 @@
+/**
+ * @tbox/sdk — APIClient 核心基类
+ *
+ * 对齐 coze-js 的 core.ts 设计：
+ * - Token 管理（静态字符串 / 动态函数）
+ * - 请求构建（JSON / FormData / SSE）
+ * - 响应解包（兼容多种服务端格式）
+ * - 错误映射（HTTP 状态码 → 错误子类）
+ */
+/** SDK 初始化配置 */
+export interface ClientOptions {
+    /**
+     * API Key or dynamic token function.
+     * String is used directly as Bearer Token; function is called before each request.
+     */
+    token: string | (() => string | Promise<string>);
+    /** API base URL. @default "https://o.tbox.cn" */
+    baseURL?: string;
+    /** Request timeout in milliseconds. @default undefined (no timeout) */
+    timeout?: number;
+    /** Enable debug logging. @default false */
+    debug?: boolean;
+    /** Custom headers merged into every request. */
+    headers?: Record<string, string>;
+}
+/** Per-request option overrides */
+export interface RequestOptions {
+    timeout?: number;
+    headers?: Record<string, string>;
+    debug?: boolean;
+    signal?: AbortSignal;
+    baseURL?: string;
+}
+/** SSE event object */
+export interface SSEEvent {
+    data: string;
+    event?: string;
+    id?: string;
+    retry?: number;
+}
+/**
+ * Core request engine. All Resource classes call methods on this via `this._client`.
+ */
+export declare class APIClient {
+    protected baseURL: string;
+    protected token: string | (() => string | Promise<string>);
+    protected timeout?: number;
+    protected debug: boolean;
+    protected defaultHeaders?: Record<string, string>;
+    constructor(options: ClientOptions);
+    /** Resolve the current token value (supports async token functions). */
+    protected getToken(): Promise<string>;
+    /** JSON POST request — returns unwrapped business data. */
+    post<Rsp>(path: string, body?: unknown, options?: RequestOptions): Promise<Rsp>;
+    /** GET request — query params auto-appended to URL. */
+    get<Rsp>(path: string, params?: Record<string, string | number | boolean | undefined>, options?: RequestOptions): Promise<Rsp>;
+    /** FormData POST request (file uploads). Content-Type is set automatically by fetch. */
+    postFormData<Rsp>(path: string, formData: FormData, options?: RequestOptions): Promise<Rsp>;
+    /** SSE streaming POST request — yields SSEEvent objects. */
+    postStream(path: string, body?: unknown, options?: RequestOptions): AsyncGenerator<SSEEvent>;
+    private buildUrl;
+    private buildHeaders;
+    private fetchWithTimeout;
+    private parseAndUnwrap;
+    /**
+     * Unwrap server response — extract business data from various envelope formats.
+     *
+     * Priority: data > resultObj > result.response (knowledge) > result > raw
+     */
+    private unwrapResponse;
+    /** Parse JSON response using ArrayBuffer + TextDecoder for correct UTF-8 handling. */
+    private parseJsonResponse;
+    /** Safely parse JSON without throwing (for error responses). */
+    private safeParseJson;
+    /** Parse SSE stream from ReadableStream. */
+    private parseSSEStream;
+    /** Output debug log when debug mode is enabled. */
+    protected debugLog(options: RequestOptions | undefined, ...messages: unknown[]): void;
+}

package/dist/error.d.ts

@@ -0,0 +1,71 @@
+/**
+ * @tbox/sdk — 分层错误体系
+ *
+ * 对齐 coze-js 的 error.ts 设计：
+ * TboxError → APIError → 按 HTTP 状态码的子类
+ */
+/** 所有 SDK 错误的基类 */
+export declare class TboxError extends Error {
+    constructor(message: string);
+}
+/** 服务端原始响应结构（用于错误工厂） */
+interface RawErrorBody {
+    success?: boolean;
+    errorCode?: string;
+    code?: string | number;
+    resultCode?: string;
+    errorMsg?: string;
+    msg?: string;
+    resultDesc?: string;
+    traceId?: string;
+}
+/** API 调用错误，包含 HTTP 状态码和业务错误信息 */
+export declare class APIError extends TboxError {
+    readonly status: number;
+    readonly errorCode?: string;
+    readonly errorMsg?: string;
+    readonly traceId?: string;
+    readonly rawResponse?: unknown;
+    constructor(status: number, errorCode: string | undefined, errorMsg: string | undefined, traceId: string | undefined, rawResponse?: unknown);
+    /**
+     * Factory: create the appropriate error subclass based on HTTP status code.
+     */
+    static generate(status: number, body?: RawErrorBody): APIError;
+}
+export declare class BadRequestError extends APIError {
+    constructor(errorCode?: string, errorMsg?: string, traceId?: string, rawResponse?: unknown);
+}
+export declare class AuthenticationError extends APIError {
+    constructor(errorCode?: string, errorMsg?: string, traceId?: string, rawResponse?: unknown);
+}
+export declare class ForbiddenError extends APIError {
+    constructor(errorCode?: string, errorMsg?: string, traceId?: string, rawResponse?: unknown);
+}
+export declare class NotFoundError extends APIError {
+    constructor(errorCode?: string, errorMsg?: string, traceId?: string, rawResponse?: unknown);
+}
+export declare class RateLimitError extends APIError {
+    constructor(errorCode?: string, errorMsg?: string, traceId?: string, rawResponse?: unknown);
+}
+export declare class InternalServerError extends APIError {
+    constructor(errorCode?: string, errorMsg?: string, traceId?: string, rawResponse?: unknown);
+}
+export declare class GatewayError extends APIError {
+    constructor(errorCode?: string, errorMsg?: string, traceId?: string, rawResponse?: unknown);
+}
+/** Network unreachable error */
+export declare class NetworkError extends TboxError {
+    readonly cause?: Error;
+    constructor(message: string, cause?: Error);
+}
+/** Request timeout error */
+export declare class TimeoutError extends TboxError {
+    readonly timeout: number;
+    constructor(timeout: number);
+}
+/** JSON parse error */
+export declare class ParseError extends TboxError {
+    readonly responseText?: string;
+    constructor(message: string, responseText?: string);
+}
+export {};

package/dist/http.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 百宝箱插件服务 SDK - 底层 HTTP 请求封装
+ */
+import type { SdkResponse } from './types';
+/** 默认调用域名 */
+export declare const DEFAULT_BASE_URL = "https://o.tbox.cn";
+/** 内部 HTTP 客户端配置 */
+export interface HttpClientConfig {
+    baseUrl: string;
+    apiKey: string;
+    timeout?: number;
+}
+/**
+ * 底层 HTTP 客户端
+ */
+export declare class HttpClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly timeout?;
+    constructor(config: HttpClientConfig);
+    /** 构建通用请求头 */
+    private buildHeaders;
+    /** 构建 FormData 请求头（不设置 Content-Type，让浏览器自动处理 boundary） */
+    private buildHeadersForFormData;
+    /** 发起 fetch，支持可选超时 */
+    private fetchWithTimeout;
+    /**
+     * POST 请求
+     */
+    post<T>(path: string, body: unknown, queryParams?: Record<string, string>): Promise<SdkResponse<T>>;
+    /**
+     * POST FormData 请求（用于文件上传）
+     */
+    postFormData<T>(path: string, formData: FormData, queryParams?: Record<string, string>): Promise<SdkResponse<T>>;
+    /**
+     * GET 请求
+     */
+    get<T>(path: string, queryParams?: Record<string, string>): Promise<SdkResponse<T>>;
+    /** 构建完整 URL（含 query string） */
+    private buildUrl;
+    /** 解析响应体 */
+    private parseResponse;
+}