@lobehub/market-sdk 0.22.6 → 0.22.8-beta.0

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { MarketItemBase, PluginConnectionType, RangeQuery, RangeStats, TopPluginsQuery, TopPlugin, PluginManifest, AdminPluginItem, AdminPluginItemDetail, PluginVersion, PluginVersionLocalization, AdminDeploymentOption, InstallationDetails, SystemDependency, IncompleteI18nPlugin, CategoryListQuery, CategoryItem, PluginItemDetail, InstallReportRequest, InstallReportResponse, CallReportRequest, CallReportResponse } from '@lobehub/market-types';
+import { AgentItem, MarketItemBase, PluginConnectionType, InstallFailureAnalysisQuery, InstallFailureAnalysis, RangeQuery, RangeStats, TopPluginsQuery, TopPlugin, PluginManifest, AdminPluginItem, AdminPluginItemDetail, PluginVersion, PluginVersionLocalization, AdminDeploymentOption, InstallationDetails, SystemDependency, IncompleteI18nPlugin, CategoryListQuery, CategoryItem, PluginItemDetail, InstallReportRequest, InstallReportResponse, CallReportRequest, CallReportResponse } from '@lobehub/market-types';
 export * from '@lobehub/market-types';
 export { CategoryItem, CategoryListQuery, CategoryListResponse } from '@lobehub/market-types';
 import { z } from 'zod';
@@ -228,6 +228,443 @@ interface UnclaimedPluginItem {
     identifier: string;
 }
 
+/**
+ * Agent list query parameters
+ * Defines the query parameters for filtering and paginating agent results
+ */
+interface AgentListQuery {
+    /** Filter by category */
+    category?: string;
+    /** Filter by official status */
+    isOfficial?: 'true' | 'false';
+    /** Locale for localized content */
+    locale?: string;
+    /** Sort order */
+    order?: 'asc' | 'desc';
+    /** Filter by owner ID */
+    ownerId?: number | string;
+    /** Current page number (1-based) */
+    page?: number;
+    /** Number of items per page */
+    pageSize?: number;
+    /** Search query string */
+    q?: string;
+    /** Sort field */
+    sort?: 'createdAt' | 'updatedAt' | 'name';
+    /** Publication status filter */
+    status?: 'published' | 'unpublished' | 'archived' | 'deprecated' | 'all';
+    /** Visibility filter */
+    visibility?: 'public' | 'private' | 'internal' | 'all';
+}
+/**
+ * Agent list response structure
+ * Defines the structure of the agent list API response
+ */
+interface AgentListResponse {
+    currentPage: number;
+    items: AgentItem[];
+    pageSize: number;
+    totalCount: number;
+    totalPages: number;
+}
+/**
+ * Agent detail query parameters
+ * Defines the query parameters for retrieving agent details
+ */
+interface AgentDetailQuery {
+    /** Locale for localized content */
+    locale?: string;
+    /** Specific version number to retrieve */
+    version?: string;
+}
+/**
+ * Agent detail response structure
+ * Represents the complete agent information including A2A AgentCard data
+ */
+interface AgentItemDetail extends AgentItem {
+    /** A2A protocol version */
+    a2aProtocolVersion: string;
+    /** Agent configuration JSON */
+    config: any;
+    /** URL to human-readable documentation */
+    documentationUrl?: string;
+    /** Supported protocol extensions */
+    extensions?: any[];
+    /** Whether push notifications are supported */
+    hasPushNotifications: boolean;
+    /** Whether state transition history is supported */
+    hasStateTransitionHistory: boolean;
+    /** Whether streaming is supported */
+    hasStreaming: boolean;
+    /** Additional interfaces supported */
+    interfaces?: any[];
+    /** The transport of the preferred endpoint */
+    preferredTransport: string;
+    /** Security requirements */
+    securityRequirements?: any[];
+    /** Security schemes */
+    securitySchemes?: any;
+    /** Agent skills */
+    skills?: AgentSkill[];
+    /** A summary that helps find the correct agent */
+    summary?: string;
+    /** Whether the agent supports authenticated extended card */
+    supportsAuthenticatedExtendedCard: boolean;
+    /** Agent or A2A implementation version string */
+    version: string;
+    /** Incremental version number */
+    versionNumber: number;
+}
+/**
+ * Agent skill structure
+ * Represents a skill that an agent can perform
+ */
+interface AgentSkill {
+    /** Skill description */
+    description: string;
+    /** Example prompts or use cases */
+    examples?: string[];
+    /** Input Media Types for this skill */
+    inputModes?: string[];
+    /** Localized skill information */
+    localizations?: Array<{
+        description: string;
+        examples?: string[];
+        locale: string;
+        name: string;
+        tags: string[];
+    }>;
+    /** Human-readable skill name */
+    name: string;
+    /** Output Media Types for this skill */
+    outputModes?: string[];
+    /** Unique skill identifier within the agent */
+    skillId: string;
+    /** Keywords/categories for discoverability */
+    tags: string[];
+}
+/**
+ * Agent Create Request
+ * Parameters for creating a new agent
+ */
+interface AgentCreateRequest {
+    /** Official homepage or repository URL for the agent */
+    homepage?: string;
+    /** Human readable agent identifier */
+    identifier: string;
+    /** Whether the agent is featured */
+    isFeatured?: boolean;
+    /** Default name of the agent */
+    name: string;
+    /** Status of the agent */
+    status?: 'published' | 'unpublished' | 'archived' | 'deprecated';
+    /** Visibility of the agent */
+    visibility?: 'public' | 'private' | 'internal';
+}
+/**
+ * Agent Create Response
+ * Response from creating a new agent
+ */
+interface AgentCreateResponse {
+    createdAt: string;
+    id: number;
+    identifier: string;
+    name: string;
+    ownerId: number;
+    updatedAt: string;
+}
+/**
+ * Agent Modify Request
+ * Parameters for modifying an existing agent
+ */
+interface AgentModifyRequest {
+    /** Official homepage or repository URL for the agent */
+    homepage?: string;
+    /** Human readable agent identifier (required) */
+    identifier: string;
+    /** Whether the agent is featured */
+    isFeatured?: boolean;
+    /** Whether this agent is officially maintained by LobeHub */
+    isOfficial?: boolean;
+    /** Default name of the agent */
+    name?: string;
+    /** Status of the agent */
+    status?: 'published' | 'unpublished' | 'archived' | 'deprecated';
+    /** Visibility of the agent */
+    visibility?: 'public' | 'private' | 'internal';
+}
+/**
+ * Agent Modify Response
+ * Response from modifying an agent
+ */
+interface AgentModifyResponse {
+    createdAt: string;
+    homepage: string | null;
+    id: number;
+    identifier: string;
+    isFeatured: boolean;
+    isOfficial: boolean;
+    name: string;
+    ownerId: number;
+    status: string;
+    updatedAt: string;
+    visibility: string;
+}
+/**
+ * Agent Version Create Request
+ * Parameters for creating a new version of an existing agent
+ */
+interface AgentVersionCreateRequest {
+    /** A2A protocol version */
+    a2aProtocolVersion?: string;
+    /** Avatar URL for the agent, can be a emoji */
+    avatar?: string;
+    /** Category key for the agent */
+    category?: string;
+    /** Changelog for this version describing what changed */
+    changelog?: string;
+    /** Configuration JSON containing model definitions, tools, hyperparameters, etc. */
+    config?: Record<string, any>;
+    /** Array of default input Media Types */
+    defaultInputModes?: string[];
+    /** Array of default output Media Types */
+    defaultOutputModes?: string[];
+    /** Description of the agent */
+    description?: string;
+    /** URL to human-readable documentation */
+    documentationUrl?: string;
+    /** Supported protocol extensions */
+    extensions?: Array<Record<string, any>>;
+    /** Whether push notifications are supported */
+    hasPushNotifications?: boolean;
+    /** Whether state transition history is supported */
+    hasStateTransitionHistory?: boolean;
+    /** Whether streaming is supported */
+    hasStreaming?: boolean;
+    /** Agent identifier (required) */
+    identifier: string;
+    /** Additional interfaces supported */
+    interfaces?: Array<Record<string, any>>;
+    /** Name of the agent */
+    name?: string;
+    /** The transport of the preferred endpoint */
+    preferredTransport?: string;
+    /** Foreign key to the account that provides this agent */
+    providerId?: number;
+    /** Security requirements */
+    securityRequirements?: Array<Record<string, any>>;
+    /** Security schemes */
+    securitySchemes?: Record<string, any>;
+    /** Whether this version should become the current version */
+    setAsCurrent?: boolean;
+    /** A summary that help agent find correct agent */
+    summary?: string;
+    /** Whether the agent supports authenticated extended card */
+    supportsAuthenticatedExtendedCard?: boolean;
+    /** Tags for categorization */
+    tags?: string[];
+    /** Token usage for the agent */
+    tokenUsage?: number;
+    /** Base URL for the agent's A2A service */
+    url?: string;
+    /** Agent or A2A implementation version string */
+    version?: string;
+    /** Incremental version number for this agent (will auto-increment if not provided) */
+    versionNumber?: number;
+}
+/**
+ * Agent Version Create Response
+ * Response from creating a new agent version
+ */
+interface AgentVersionCreateResponse {
+    agentId: number;
+    createdAt: string;
+    description: string;
+    id: number;
+    isLatest: boolean;
+    name: string;
+    updatedAt: string;
+    version: string;
+    versionNumber: number;
+}
+/**
+ * Agent Version Modify Request
+ * Parameters for modifying a specific version of an existing agent
+ */
+interface AgentVersionModifyRequest {
+    /** A2A protocol version */
+    a2aProtocolVersion?: string;
+    /** Avatar URL for the agent, can be a emoji */
+    avatar?: string;
+    /** Category key for the agent */
+    category?: string;
+    /** Changelog for this version describing what changed */
+    changelog?: string;
+    /** Configuration JSON containing model definitions, tools, hyperparameters, etc. */
+    config?: Record<string, any>;
+    /** Array of default input Media Types */
+    defaultInputModes?: string[];
+    /** Array of default output Media Types */
+    defaultOutputModes?: string[];
+    /** Description of the agent */
+    description?: string;
+    /** URL to human-readable documentation */
+    documentationUrl?: string;
+    /** Supported protocol extensions */
+    extensions?: Array<Record<string, any>>;
+    /** Whether push notifications are supported */
+    hasPushNotifications?: boolean;
+    /** Whether state transition history is supported */
+    hasStateTransitionHistory?: boolean;
+    /** Whether streaming is supported */
+    hasStreaming?: boolean;
+    /** Agent identifier (required) */
+    identifier: string;
+    /** Additional interfaces supported */
+    interfaces?: Array<Record<string, any>>;
+    /** Name of the agent */
+    name?: string;
+    /** The transport of the preferred endpoint */
+    preferredTransport?: string;
+    /** Foreign key to the account that provides this agent */
+    providerId?: number;
+    /** Security requirements */
+    securityRequirements?: Array<Record<string, any>>;
+    /** Security schemes */
+    securitySchemes?: Record<string, any>;
+    /** Whether this version should become the current version */
+    setAsCurrent?: boolean;
+    /** A summary that help agent find correct agent */
+    summary?: string;
+    /** Whether the agent supports authenticated extended card */
+    supportsAuthenticatedExtendedCard?: boolean;
+    /** Token usage for the agent */
+    tokenUsage?: number;
+    /** Base URL for the agent's A2A service */
+    url?: string;
+    /** Version string to modify (required) */
+    version: string;
+    /** Agent or A2A implementation version string */
+    versionString?: string;
+}
+/**
+ * Agent Version Modify Response
+ * Response from modifying an agent version
+ */
+interface AgentVersionModifyResponse {
+    agentId: number;
+    createdAt: string;
+    description: string;
+    id: number;
+    isLatest: boolean;
+    name: string;
+    updatedAt: string;
+    version: string;
+    versionNumber: number;
+}
+/**
+ * Agent Interface
+ * Represents an interface endpoint for an agent
+ */
+interface AgentInterface {
+    transport: string;
+    url: string;
+}
+/**
+ * Agent Security Scheme
+ * Represents a security scheme for an agent
+ */
+interface AgentSecurityScheme {
+    schemeConfig: any;
+    schemeName: string;
+}
+/**
+ * Agent Security Requirement
+ * Represents a security requirement for an agent
+ */
+interface AgentSecurityRequirement {
+    requirement: any;
+}
+/**
+ * Agent Extension
+ * Represents a protocol extension for an agent
+ */
+interface AgentExtension {
+    description?: string;
+    params?: any;
+    required?: boolean;
+    uri: string;
+}
+/**
+ * Agent Version Localization
+ * Represents localized content for an agent version
+ */
+interface AgentVersionLocalization {
+    changelog?: string;
+    config: any;
+    description?: string;
+    locale: string;
+    name?: string;
+    shortDescription?: string;
+}
+/**
+ * Agent Upload Version Data
+ * Version data for agent upload
+ */
+interface AgentUploadVersion {
+    a2aProtocolVersion: string;
+    changelog?: string;
+    config: any;
+    defaultInputModes: string[];
+    defaultOutputModes: string[];
+    description: string;
+    documentationUrl?: string;
+    extensions?: AgentExtension[];
+    hasPushNotifications?: boolean;
+    hasStateTransitionHistory?: boolean;
+    hasStreaming?: boolean;
+    interfaces?: AgentInterface[];
+    localizations?: AgentVersionLocalization[];
+    name: string;
+    preferredTransport?: string;
+    providerId?: number;
+    securityRequirements?: AgentSecurityRequirement[];
+    securitySchemes?: AgentSecurityScheme[];
+    skills?: AgentSkill[];
+    supportsAuthenticatedExtendedCard?: boolean;
+    url: string;
+    version: string;
+    versionNumber: number;
+}
+/**
+ * Agent Upload Request
+ * Parameters for uploading a complete agent with version
+ */
+interface AgentUploadRequest {
+    agentIdentifier: string;
+    avatar?: string;
+    isOfficial?: boolean;
+    name: string;
+    ownerId: number;
+    version: AgentUploadVersion;
+}
+/**
+ * Agent Upload Response
+ * Response from uploading an agent
+ */
+interface AgentUploadResponse {
+    agentId: string;
+    agentIdentifier: string;
+    config: any;
+    createdAt: string;
+    description: string;
+    documentationUrl?: string;
+    hasPushNotifications: boolean;
+    hasStateTransitionHistory: boolean;
+    name: string;
+    updatedAt: string;
+}
+
 /**
  * Market Service Discovery Document
  *
@@ -623,6 +1060,16 @@ declare class AnalysisService extends BaseSDK {
      * @returns Promise resolving to market overview statistics for current year
      */
     getYearlyOverview(): Promise<MarketOverviewStats>;
+    /**
+     * Retrieves install failure analysis for plugins within a date range
+     *
+     * Returns detailed analysis of plugin installation failures including failure counts,
+     * failure rates, and most common error messages for each plugin with failures.
+     *
+     * @param params - Query parameters for the failure analysis
+     * @returns Promise resolving to install failure analysis data
+     */
+    getInstallFailureAnalysis(params: InstallFailureAnalysisQuery): Promise<InstallFailureAnalysis[]>;
     /**
      * Calculates growth rate between current and previous values
      *
@@ -1413,6 +1860,169 @@ declare class MarketAdmin extends BaseSDK {
     constructor(options?: MarketSDKOptions);
 }
 
+/**
+ * Agents Service
+ *
+ * Provides access to agent-related functionality in the LobeHub Marketplace.
+ * This service handles listing, searching, and retrieving detailed information
+ * about agents available in the marketplace.
+ */
+declare class AgentService extends BaseSDK {
+    /**
+     * Retrieves a list of agents from the marketplace
+     *
+     * Supports filtering, pagination, and localization of results.
+     *
+     * @param params - Query parameters for filtering and pagination
+     * @param options - Optional request options
+     * @returns Promise resolving to the agent list response containing items and pagination info
+     */
+    getAgentList(params?: AgentListQuery, options?: globalThis.RequestInit): Promise<AgentListResponse>;
+    /**
+     * Retrieves detailed information about a specific agent
+     *
+     * Returns complete agent information including A2A AgentCard data,
+     * configuration, skills, and localized content.
+     *
+     * @param id - Unique identifier of the agent
+     * @param params - Query parameters for locale and version
+     * @param options - Optional request options
+     * @returns Promise resolving to the agent detail information
+     */
+    getAgentDetail(id: string, params?: AgentDetailQuery, options?: globalThis.RequestInit): Promise<AgentItemDetail>;
+    /**
+     * Retrieves all published agent identifiers
+     *
+     * Returns a lightweight list of all published agent identifiers without
+     * full agent metadata. This is useful for clients that need to know which
+     * agents are available without fetching complete agent information.
+     *
+     * @param options - Optional request options
+     * @returns Promise resolving to an array containing identifiers array and last modified time
+     */
+    getPublishedIdentifiers(options?: globalThis.RequestInit): Promise<{
+        id: string;
+        lastModified: string;
+    }[]>;
+    /**
+     * Retrieves agent categories and their counts
+     *
+     * Returns a list of categories along with the number of agents in each category.
+     * Useful for building category filters in a UI. Supports optional search filtering
+     * via 'q' parameter and locale specification.
+     *
+     * @param params - Query parameters for filtering categories
+     * @param options - Optional request options
+     * @returns Promise resolving to an array of category items with counts
+     */
+    getCategories(params?: {
+        locale?: string;
+        q?: string;
+    }, options?: globalThis.RequestInit): Promise<{
+        category: string;
+        count: number;
+    }[]>;
+    /**
+     * Uploads an agent to the marketplace
+     *
+     * Allows users to upload new agents or update existing ones.
+     * The agent data should conform to the A2A AgentCard specification.
+     *
+     * @param agentData - The agent data to upload
+     * @param options - Optional request options
+     * @returns Promise resolving to the upload response
+     */
+    uploadAgent(agentData: AgentUploadRequest, options?: globalThis.RequestInit): Promise<AgentUploadResponse>;
+    /**
+     * Creates a new agent in the marketplace
+     *
+     * @param agentData - The agent data to create
+     * @param options - Optional request options
+     * @returns Promise resolving to the created agent response
+     */
+    createAgent(agentData: AgentCreateRequest, options?: globalThis.RequestInit): Promise<AgentCreateResponse>;
+    /**
+     * Creates a new version for an existing agent
+     *
+     * @param versionData - The version data to create
+     * @param options - Optional request options
+     * @returns Promise resolving to the created version response
+     */
+    createAgentVersion(versionData: AgentVersionCreateRequest, options?: globalThis.RequestInit): Promise<AgentVersionCreateResponse>;
+    /**
+     * Modifies an existing agent
+     *
+     * @param agentData - The agent data to modify
+     * @param options - Optional request options
+     * @returns Promise resolving to the modified agent response
+     */
+    modifyAgent(agentData: AgentModifyRequest, options?: globalThis.RequestInit): Promise<AgentModifyResponse>;
+    /**
+     * Modifies a specific version of an existing agent
+     *
+     * @param versionData - The version data to modify
+     * @param options - Optional request options
+     * @returns Promise resolving to the modified version response
+     */
+    modifyAgentVersion(versionData: AgentVersionModifyRequest, options?: globalThis.RequestInit): Promise<AgentVersionModifyResponse>;
+    /**
+     * Checks if an agent exists in the marketplace
+     *
+     * @param identifier - Unique identifier of the agent
+     * @param options - Optional request options
+     * @returns Promise resolving to true if agent exists, false otherwise
+     */
+    checkAgentExists(identifier: string, options?: globalThis.RequestInit): Promise<boolean>;
+}
+
+/**
+ * Auth Service
+ *
+ * Provides authentication and authorization functionality for the LobeHub Marketplace.
+ * This service handles OIDC user authentication, client registration, and M2M token management.
+ */
+declare class AuthService extends BaseSDK {
+    /**
+     * Retrieves user information from the OIDC userinfo endpoint
+     *
+     * Requires a valid access token in the Authorization header.
+     *
+     * @param accessToken - The access token to use for authentication
+     * @param options - Optional request options
+     * @returns Promise resolving to the user information
+     */
+    getUserInfo(accessToken: string, options?: globalThis.RequestInit): Promise<{
+        email?: string;
+        email_verified?: boolean;
+        name?: string;
+        picture?: string;
+        sub: string;
+    }>;
+    /**
+     * Registers a new OAuth client with the marketplace
+     *
+     * This is typically used for device registration or application setup.
+     * Returns client credentials that can be used for M2M authentication.
+     *
+     * @param clientData - The client registration data
+     * @param options - Optional request options
+     * @returns Promise resolving to the client credentials
+     */
+    registerClient(clientData: ClientRegistrationRequest, options?: globalThis.RequestInit): Promise<ClientRegistrationResponse>;
+    /**
+     * Fetches an M2M (Machine-to-Machine) access token
+     *
+     * Uses client credentials to obtain an access token for server-to-server communication.
+     * This method requires clientId and clientSecret to be set in the SDK options.
+     *
+     * @returns Promise resolving to the access token and expiration time
+     */
+    getM2MToken(): Promise<{
+        accessToken: string;
+        expiresIn: number;
+    }>;
+}
+
 /**
  * Plugins Service
  *
@@ -1521,6 +2131,16 @@ declare class PluginsService extends BaseSDK {
  * by combining specialized domain services.
  */
 declare class MarketSDK extends BaseSDK {
+    /**
+     * Agents service for accessing agent-related functionality
+     * Provides methods to list, search, retrieve agent information, and upload agents
+     */
+    readonly agents: AgentService;
+    /**
+     * Auth service for authentication and authorization
+     * Provides methods for OIDC user authentication, client registration, and M2M token management
+     */
+    readonly auth: AuthService;
     /**
      * Plugins service for accessing plugin-related functionality
      * Provides methods to list, search, retrieve plugin information, and report installation attempts
@@ -1556,8 +2176,9 @@ declare class MarketSDK extends BaseSDK {
      * @param request - Client registration request data
      * @returns Promise resolving to the client registration response with credentials
      * @throws Error if registration fails
+     * @deprecated Use auth.registerClient() instead
      */
     registerClient(request: ClientRegistrationRequest): Promise<ClientRegistrationResponse>;
 }
 
-export { type AdminListQueryParams, type AdminListResponse, type AdminPluginParams, type ClientRegistrationError, type ClientRegistrationRequest, type ClientRegistrationResponse, type DiscoveryDocument, MarketAdmin, MarketSDK, type MarketSDKOptions, type PluginI18nImportParams, type PluginI18nImportResponse, type PluginItem, type PluginListResponse, type PluginLocalization, type PluginQueryParams, type PluginUpdateParams, type PluginVersionCreateParams, type PluginVersionUpdateParams, type ReviewStatus, ReviewStatusEnumSchema, type SharedTokenState, StatusEnumSchema, type UnclaimedPluginItem, VisibilityEnumSchema };
+export { type AdminListQueryParams, type AdminListResponse, type AdminPluginParams, type AgentCreateRequest, type AgentCreateResponse, type AgentDetailQuery, type AgentExtension, type AgentInterface, type AgentItemDetail, type AgentListQuery, type AgentListResponse, type AgentModifyRequest, type AgentModifyResponse, type AgentSecurityRequirement, type AgentSecurityScheme, type AgentSkill, type AgentUploadRequest, type AgentUploadResponse, type AgentUploadVersion, type AgentVersionCreateRequest, type AgentVersionCreateResponse, type AgentVersionLocalization, type AgentVersionModifyRequest, type AgentVersionModifyResponse, type ClientRegistrationError, type ClientRegistrationRequest, type ClientRegistrationResponse, type DiscoveryDocument, MarketAdmin, MarketSDK, type MarketSDKOptions, type PluginI18nImportParams, type PluginI18nImportResponse, type PluginItem, type PluginListResponse, type PluginLocalization, type PluginQueryParams, type PluginUpdateParams, type PluginVersionCreateParams, type PluginVersionUpdateParams, type ReviewStatus, ReviewStatusEnumSchema, type SharedTokenState, StatusEnumSchema, type UnclaimedPluginItem, VisibilityEnumSchema };