@howone/sdk 0.1.0

package/README.md

@@ -0,0 +1,129 @@
+# HowOne Client Library
+
+A comprehensive client library for AI templates with reusable components, hooks, and services.
+
+## Components
+
+### Auth Components
+
+#### LoginForm
+
+A simplified login form component with email/code authentication and social login buttons.
+
+```tsx
+import { LoginForm } from "howone-client";
+
+function LoginPage() {
+  return <LoginForm />;
+}
+```
+
+# @howone/sdk — Howone 客户端（中文使用手册）
+
+本包为 Howone 提供前端 SDK，公开用于创建客户端实例的工厂函数：`createClient`。
+
+本说明以 `createClient` 为中心，示例展示如何通过 `createClient` 创建并使用客户端实例来调用业务 API、执行 AI workflow、管理 token 与操作 artifacts。
+
+目录
+
+- 快速概览
+- 安装
+- 快速开始（以 howone 为主）
+- howone 对象详解
+- Auth / token 注入（iframe 与 standalone）
+- Artifacts 使用
+- 进阶指引与常见问题
+- 开发与构建
+
+## 快速概览
+
+@howone/sdk — Howone 客户端（简明使用手册）
+
+本包提供 Howone 前端 SDK 的核心工厂：`createClient`，用于创建并配置客户端实例。
+
+## 快速概览
+
+- `createClient(opts)`：创建自定义客户端实例（包含 `request`、`workflowRequest`、`executeWorkflow`、`artifacts`、`auth`）。
+
+## 安装
+
+工作区（monorepo）开发：
+
+```bash
+pnpm -w install
+```
+
+外部项目：
+
+```bash
+pnpm add @howone/sdk
+```
+
+## 快速开始
+
+在应用启动时创建并使用客户端实例：
+
+```ts
+import { createClient } from "@howone/sdk";
+
+const client = createClient({
+  projectId: "demo",
+  baseUrl: "https://your-business.api",
+  aiBaseUrl: "https://your-ai.api",
+  authRequired: false,
+  auth: {
+    getToken: async () => localStorage.getItem("howone_token") ?? null,
+    tokenInjection: {
+      allowedOrigins: ["https://parent.example.com"],
+      waitMs: 3000,
+    },
+  },
+});
+
+// 业务请求
+await client.request.post({ url: "/items", data: { name: "hello" } });
+
+// 执行 AI workflow（使用 workflowRequest）
+// 直接调用独立的 AI 请求实例，POST 到 /workflow/{id}/execute
+await client.workflowRequest.post({
+  url: `/workflow/${encodeURIComponent("workflow-id")}/execute`,
+  data: { input: { text: "hi" } },
+});
+
+// Auth helper
+client.auth.setToken("Bearer xxx");
+```
+
+## API 概览
+
+- `client.request` — 业务 API 的 Request 实例（基于 axios 的包装器）。
+- `client.workflowRequest` — AI workflow 的 Request 实例（独立于业务 API）。
+- `client.workflowRequest` — 用于直接调用 AI workflow 后端，请构造 POST 到 `/workflow/{id}/execute`（或使用 `createAIWorkflowClientAxios` / `createAIWorkflowClient` 提供的高阶 helper）。
+- `client.artifacts` — artifacts 客户端：{ create, list, get, setVisibility, delete }。
+- `client.auth` — 轻量 auth 辅助：{ setToken, getToken, isAuthenticated, login, logout }。
+
+## Auth / token 注入
+
+初始化 token 优先级（createClient 默认行为）：
+
+1. `auth.getToken()` 回调（最高优先级）
+2. 嵌入式场景下的父页面 postMessage 注入（当配置了 `auth.tokenInjection`）
+3. 否则不自动设置 token，需手动 `client.auth.setToken`
+
+注意：SDK 只在内存中写入 axios header；持久化请在 `getToken`/`setToken` 中实现或使用后端 HttpOnly cookie。
+
+## 开发与构建
+
+```bash
+pnpm -w install
+pnpm -w -F @howone/sdk build
+```
+
+## 代码结构（快速浏览）
+
+- `src/services/index.ts` — createClient 与请求实例构造
+- `src/services/ai-workflow.ts` / `ai-workflow-axios.ts` — AI workflow 客户端实现
+- `src/services/artifacts-client.ts` — artifacts 封装
+
+如需完整示例（iframe 注入、redirect 登录、后端交换）请告知，我可以把示例代码直接添加到 template。
+工作区内（monorepo）：

package/dist/index.d.mts

@@ -0,0 +1,434 @@
+import React, { Component, ReactNode } from 'react';
+import { AxiosResponse, InternalAxiosRequestConfig, AxiosRequestConfig, AxiosInstance } from 'axios';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+interface FloatingButtonProps {
+    text?: string;
+    onClick?: () => void;
+    className?: string;
+}
+declare const FloatingButton: React.FC<FloatingButtonProps>;
+
+/**
+ * 统一认证服务
+ *
+ * 提供多种认证功能，包括：
+ * - Google OAuth 认证
+ * - GitHub OAuth 认证
+ * - 邮箱验证码认证
+ * - Token 验证和管理
+ * - 退出登录
+ */
+/**
+ * 发送验证码请求接口
+ */
+interface SendCodeRequest {
+    /** 邮箱地址 */
+    email: string;
+    /** 来源 URL */
+    from_url: string;
+    /** 应用 ID（可选） */
+    app_id?: string;
+    /** 应用名称（可选） */
+    app_name?: string;
+}
+/**
+ * 发送验证码响应接口
+ */
+interface SendCodeResponse {
+    /** 是否成功 */
+    success: boolean;
+    /** 消息（可选） */
+    message?: string;
+    /** 过期时间（秒）（可选） */
+    expiresIn?: number;
+    /** 状态码（可选，用于处理业务逻辑错误） */
+    code?: number;
+    /** 数据对象（可选，用于处理业务逻辑错误） */
+    data?: {
+        success: boolean;
+        message?: string;
+        code?: number;
+    };
+    /** 追踪 ID（可选） */
+    traceId?: number;
+}
+/**
+ * 邮箱登录请求接口
+ */
+interface EmailLoginRequest {
+    /** 邮箱地址 */
+    email: string;
+    /** 验证码 */
+    code: string;
+    /** 来源 URL */
+    from_url: string;
+    /** 应用 ID（可选） */
+    app_id?: string;
+}
+/**
+ * 邮箱登录响应接口
+ */
+interface EmailLoginResponse {
+    /** 是否成功 */
+    success: boolean;
+    /** JWT token（可选） */
+    token?: string;
+    /** 用户信息（可选） */
+    user?: {
+        email: string;
+        name?: string;
+    };
+    /** 重定向 URL（可选） */
+    redirect_url?: string;
+    /** 消息（可选） */
+    message?: string;
+    /** 状态码（可选，用于处理业务逻辑错误） */
+    code?: number;
+    /** 数据对象（可选，用于处理业务逻辑错误） */
+    data?: {
+        success: boolean;
+        message?: string;
+        code?: number;
+    };
+    /** 追踪 ID（可选） */
+    traceId?: number;
+}
+declare class UnifiedAuthService {
+    private readonly API_BASE_URL;
+    /**
+     * 初始化 Google 登录流程
+     * @returns 包含 token 和用户信息的 Promise
+     */
+    initiateGoogleLogin(): Promise<{
+        token: string;
+        user?: any;
+    }>;
+    /**
+     * 打开 OAuth 认证弹窗
+     * @param authUrl 认证 URL
+     * @returns 包含 token 和用户信息的 Promise
+     */
+    private openOAuthPopup;
+    /**
+     * 初始化 GitHub 登录流程
+     * @returns 包含 token 和用户信息的 Promise
+     */
+    initiateGitHubLogin(): Promise<{
+        token: string;
+        user?: any;
+    }>;
+    /**
+     * 发送邮箱验证码
+     * @param email 邮箱地址
+     * @param appName 应用名称（可选）
+     * @returns 发送结果 Promise
+     */
+    sendEmailVerificationCode(email: string, appName?: string): Promise<SendCodeResponse>;
+    /**
+     * 邮箱验证码登录
+     * @param email 邮箱地址
+     * @param code 验证码
+     * @returns 登录结果 Promise
+     */
+    loginWithEmailCode(email: string, code: string): Promise<EmailLoginResponse>;
+    /**
+     * 获取验证码状态（调试用）
+     * @param email 邮箱地址
+     * @returns 验证码状态 Promise
+     */
+    getCodeStatus(email: string): Promise<any>;
+    private generateAppId;
+    /**
+     * 检查 OAuth 回调
+     * 从 URL 参数中获取 token 和错误信息
+     * @returns 包含 token、用户信息和错误的对象
+     */
+    checkOAuthCallback(): {
+        success: boolean;
+        token?: string;
+        error?: string;
+        user?: any;
+    };
+    /**
+     * 验证 token 是否有效
+     * @param token JWT token
+     * @returns 包含有效状态和用户信息的 Promise
+     */
+    verifyToken(token: string): Promise<{
+        valid: boolean;
+        user?: any;
+    }>;
+    /**
+   * 从本地存储获取认证数据
+   */
+    private getSavedAuthData;
+    /**
+   * 保存认证数据到本地存储
+   */
+    private saveAuthData;
+    /**
+     * 退出登录
+     * @param token JWT token
+     */
+    logout(token: string): Promise<void>;
+}
+declare const unifiedAuth: UnifiedAuthService;
+declare const unifiedOAuth: UnifiedAuthService;
+declare function sendEmailVerificationCode(email: string, appName?: string): Promise<SendCodeResponse>;
+declare function loginWithEmailCode(email: string, code: string): Promise<EmailLoginResponse>;
+declare function getCodeStatus(email: string): Promise<any>;
+
+/**
+ * AI Workflow 服务（精简版，仅支持按 ID 的 path 风格执行）
+ *
+ * 说明：模板仅需要一种执行接口，形如 POST {baseUrl}/workflow/{workflowId}/execute
+ */
+interface AIWorkflowResponse {
+    success: boolean;
+    output?: Record<string, unknown>;
+    error?: string;
+    metadata?: Record<string, unknown>;
+}
+interface AIWorkflowClientOptions {
+    baseUrl?: string;
+    apiKey?: string;
+    headers?: Record<string, string>;
+    fetchImpl?: typeof fetch;
+}
+declare class AIWorkflowClient {
+    private readonly baseUrl;
+    private readonly apiKey?;
+    private readonly headers;
+    private readonly fetchImpl;
+    constructor(options?: AIWorkflowClientOptions);
+    private buildHeaders;
+    private safeJson;
+    /**
+     * 按 ID 执行工作流：POST {baseUrl}/workflow/{workflowId}/execute
+     * body: { input, options }
+     */
+    executeWorkflow(workflowId: string, input: Record<string, unknown>, options?: Record<string, unknown>): Promise<AIWorkflowResponse>;
+}
+declare function createAIWorkflowClient(options?: AIWorkflowClientOptions): AIWorkflowClient;
+declare const aiWorkflow: AIWorkflowClient;
+
+interface RequestInterceptors<T = AxiosResponse> {
+    requestInterceptor?: (config: InternalAxiosRequestConfig) => InternalAxiosRequestConfig;
+    requestInterceptorCatch?: (error: any) => any;
+    responseInterceptor?: (res: T) => T;
+    responseInterceptorCatch?: (error: any) => any;
+}
+interface RequestConfig<T = AxiosResponse> extends AxiosRequestConfig {
+    interceptors?: RequestInterceptors<T>;
+    showLoading?: boolean;
+}
+
+declare class Request {
+    instance: AxiosInstance;
+    interceptors?: RequestInterceptors;
+    abortControllers: Map<string, AbortController>;
+    constructor(config: RequestConfig);
+    cancelRequest(url: string): void;
+    cancelAllRequests(): void;
+    request<T = any>(config: RequestConfig<T>): Promise<T>;
+    get<T = any>(config: RequestConfig<T>): Promise<T>;
+    post<T = any>(config: RequestConfig<T>): Promise<T>;
+    delete<T = any>(config: RequestConfig<T>): Promise<T>;
+    put<T = any>(config: RequestConfig<T>): Promise<T>;
+    patch<T = any>(config: RequestConfig<T>): Promise<T>;
+}
+
+interface AxiosAIWorkflowOptions {
+    baseUrl?: string;
+    basePath?: string;
+    apiKey?: string;
+    timeout?: number;
+    headers?: Record<string, string>;
+    requestInstance?: Request;
+    /** 'body' (default) or 'path' for /workflow/{id}/execute */
+    workflowEndpointStyle?: 'body' | 'path';
+}
+/**
+ * Create an AI workflow client backed by the project's Request (axios) wrapper.
+ * If `requestInstance` is provided it will be used directly; otherwise a new Request will be created.
+ */
+declare function createAIWorkflowClientAxios(options?: AxiosAIWorkflowOptions): {
+    executeWorkflow(workflowId: string, input: Record<string, unknown>, opts?: Record<string, unknown>): Promise<AIWorkflowResponse>;
+};
+
+type Visibility = 'private' | 'project' | 'public' | 'shared';
+interface Artifact {
+    id: string;
+    ownerId?: string | null;
+    projectId?: string | null;
+    visibility: Visibility;
+    storageUrl: string;
+    thumbnailUrl?: string;
+    input?: any;
+    output?: any;
+    model?: string;
+    metadata?: Record<string, any>;
+    createdAt?: string;
+    likes?: number;
+    stats?: {
+        views?: number;
+    };
+    sharedWith?: string[];
+}
+interface ArtifactCreateInput {
+    storageUrl: string;
+    thumbnailUrl?: string;
+    visibility?: Visibility;
+    metadata?: Record<string, any>;
+    model?: string;
+    ownerId?: string;
+    projectId?: string;
+}
+interface ArtifactListQuery {
+    ownerId?: string;
+    projectId?: string;
+    visibility?: Visibility;
+    limit?: number;
+    cursor?: string;
+}
+interface AccessContext {
+    userId?: string | null;
+    projectId?: string | null;
+    tokenScopes?: string[];
+}
+/**
+ * Basic client-side permission check for an artifact.
+ * Note: final authorization must be enforced on the server. This is a convenience helper.
+ */
+declare function canAccessArtifact(a: Artifact, ctx?: AccessContext): boolean;
+
+declare function createArtifactsClient(req: Request): {
+    create(input: ArtifactCreateInput): Promise<Artifact>;
+    list(query?: ArtifactListQuery): Promise<Artifact[]>;
+    get(id: string): Promise<Artifact>;
+    setVisibility(id: string, visibility: string): Promise<void>;
+    delete(id: string): Promise<void>;
+    canAccessLocal(a: Artifact, ctx: AccessContext): boolean;
+};
+
+declare const request: Request;
+declare const aiRequest: Request;
+declare const workflowRequest: Request;
+/**
+ * 简单工厂：返回一个对外友好的 client，封装业务 request 与 AI workflow request。
+ * 默认使用上面导出的 `request` 和 `aiRequest`，也可以通过 options 覆盖。
+ */
+/**
+ * Higher-level factory: createClient
+ * - minimal surface compatible with `createClient({ projectId, authRequired })`
+ * - returns executeWorkflow, request, aiRequest and a tiny auth helper (set/get token)
+ */
+declare function createClient(opts?: {
+    projectId?: string;
+    authRequired?: boolean;
+    baseUrl?: string;
+    aiBaseUrl?: string;
+    mode?: 'auto' | 'standalone' | 'embedded';
+    auth?: {
+        mode?: 'none' | 'managed' | 'headless';
+        getToken?: () => Promise<string | null>;
+        tokenInjection?: {
+            allowedOrigins?: string[];
+            waitMs?: number;
+        };
+    };
+    requestInstance?: Request;
+    aiRequestInstance?: Request;
+}): {
+    request: Request;
+    aiRequest: Request;
+    workflowRequest: Request;
+    artifacts: {
+        create(input: ArtifactCreateInput): Promise<Artifact>;
+        list(query?: ArtifactListQuery): Promise<Artifact[]>;
+        get(id: string): Promise<Artifact>;
+        setVisibility(id: string, visibility: string): Promise<void>;
+        delete(id: string): Promise<void>;
+    };
+    auth: {
+        setToken: (t: string | null) => void;
+        getToken: () => string | null;
+        isAuthenticated: () => boolean;
+        login: (redirect?: string) => void;
+        logout: () => void;
+    };
+};
+
+interface LoginFormProps {
+    onLoginSuccess?: () => void;
+    appName?: string;
+    className?: string;
+}
+declare const LoginForm: React.FC<LoginFormProps>;
+
+interface AuthGuardProps {
+    children: React.ReactNode;
+    fallback?: React.ReactNode;
+    redirectTo?: string;
+    requireAuth?: boolean;
+    roles?: string[];
+    permissions?: string[];
+}
+declare const AuthGuard: React.FC<AuthGuardProps>;
+
+interface LoadingProps {
+    size?: 'sm' | 'md' | 'lg';
+    text?: string;
+    className?: string;
+    fullScreen?: boolean;
+}
+declare const Loading: React.FC<LoadingProps>;
+interface LoadingSpinnerProps {
+    size?: 'sm' | 'md' | 'lg';
+    className?: string;
+}
+declare const LoadingSpinner: React.FC<LoadingSpinnerProps>;
+
+interface ErrorBoundaryState {
+    hasError: boolean;
+    error?: Error;
+    errorInfo?: React.ErrorInfo;
+}
+interface ErrorBoundaryProps {
+    children: ReactNode;
+    fallback?: React.ComponentType<{
+        error?: Error;
+        retry?: () => void;
+    }>;
+    onError?: (error: Error, errorInfo: React.ErrorInfo) => void;
+}
+declare class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+    constructor(props: ErrorBoundaryProps);
+    static getDerivedStateFromError(error: Error): ErrorBoundaryState;
+    componentDidCatch(error: Error, errorInfo: React.ErrorInfo): void;
+    handleRetry: () => void;
+    render(): string | number | boolean | react_jsx_runtime.JSX.Element | Iterable<React.ReactNode> | null | undefined;
+}
+interface ErrorFallbackProps {
+    error?: Error;
+    retry?: () => void;
+}
+declare const DefaultErrorFallback: React.FC<ErrorFallbackProps>;
+
+declare function useIsMobile(): boolean;
+
+declare function useLocalStorage<T>(key: string, initialValue: T): readonly [T, (value: T | ((val: T) => T)) => void, () => void];
+
+declare function useDebounce<T>(value: T, delay: number): T;
+
+/**
+ * Early error handler injector
+ * This module provides a runtime function to inject the original
+ * `error-handler.js` script into the page. The script is executed
+ * as soon as it's injected, providing early capture of runtime and
+ * Vite overlay errors for the host app.
+ */
+declare function injectEarlyErrorHandler(): void;
+
+export { type AIWorkflowClientOptions, type AIWorkflowResponse, type AccessContext, type Artifact, type ArtifactCreateInput, type ArtifactListQuery, AuthGuard, type AxiosAIWorkflowOptions, DefaultErrorFallback, type EmailLoginRequest, type EmailLoginResponse, ErrorBoundary, FloatingButton, Loading, LoadingSpinner, LoginForm, type SendCodeRequest, type SendCodeResponse, type Visibility, aiRequest, aiWorkflow, canAccessArtifact, createAIWorkflowClient, createAIWorkflowClientAxios, createArtifactsClient, createClient, getCodeStatus, injectEarlyErrorHandler, loginWithEmailCode, request, sendEmailVerificationCode, unifiedAuth, unifiedOAuth, useDebounce, useIsMobile, useLocalStorage, workflowRequest };