@clawhive/openclaw-plugin 0.2.0

package/dist/src/client.d.ts

@@ -0,0 +1,386 @@
+import type { ClaimedPanelTurn, PanelContribution, PanelContributionStatus, PanelPlan, PanelPlanAssignment, PanelTurnStatus } from "./agent-panel/types.js";
+import type { MarketInstallAgentManifest, MarketInstallClaimedJob, MarketInstallReasonKind, MarketInstallUpdateStatus } from "./market-install/types.js";
+export type ClawHivePluginConfig = {
+    projectUrl: string;
+    pluginToken?: string | null;
+    anonKey: string;
+    userId?: string | null;
+    pluginNodeId?: string | null;
+    nodeName?: string;
+    pluginVersion?: string;
+};
+export type DeviceCodeStartResult = {
+    device_code: string;
+    user_code: string;
+    verification_uri: string;
+    verification_uri_complete: string;
+    expires_in: number;
+    interval: number;
+    poll_interval_seconds: number;
+};
+export type DeviceCodeExchangeSuccess = {
+    status: "approved";
+    user_id: string;
+    plugin_token: string;
+};
+export type DeviceCodeExchangePending = {
+    status: "pending";
+    interval: number;
+};
+export type DeviceCodeExchangeResult = DeviceCodeExchangeSuccess | DeviceCodeExchangePending;
+export declare class DeviceCodeExpiredError extends Error {
+    constructor();
+}
+export declare class DeviceCodeDeniedError extends Error {
+    constructor();
+}
+export type UserSession = {
+    access_token: string;
+    refresh_token: string;
+    expires_in?: number;
+    expires_at?: number;
+    token_type?: string;
+};
+export type PluginNode = {
+    id: string;
+    user_id: string;
+    node_name?: string | null;
+    plugin_version?: string | null;
+    plugin_status: "online" | "offline" | "degraded";
+    last_heartbeat_at?: string | null;
+};
+export type PluginRegisterResult = {
+    plugin_node: PluginNode;
+    user_id: string;
+    user_created: boolean;
+    realtime_topic: string;
+    heartbeat_interval: number;
+    user_session: UserSession;
+};
+export type PairingCodeResult = {
+    pair_token: string;
+    expires_at: string;
+    pairing_code: {
+        id: string;
+        expires_at: string;
+        max_attempts: number;
+        plugin_node_id: string;
+    };
+};
+export type SyncAgentInput = {
+    openclawAgentId: string;
+    name: string;
+    description?: string | null;
+    avatarUrl?: string | null;
+    config?: Record<string, unknown>;
+};
+export type SyncedAgent = {
+    id: string;
+    user_id: string;
+    openclaw_agent_id: string;
+    name: string;
+    description: string | null;
+    avatar_url: string | null;
+    source_type: string;
+    config: Record<string, unknown>;
+    created_at: string;
+};
+export type SyncAgentsResult = {
+    items: SyncedAgent[];
+    skipped: number;
+};
+export type AppendedMessage = {
+    id: string;
+    session_id: string;
+    agent_id: string;
+    user_id: string;
+    sequence: number;
+    role: string;
+    type: string;
+    content: string;
+    client_message_id?: string | null;
+    created_at: string;
+    metadata?: Record<string, unknown>;
+};
+export type SyncMessagesResult = {
+    items: AppendedMessage[];
+    next_cursor: number;
+    has_more: boolean;
+};
+export type MarketInstallClaimResult = {
+    job: MarketInstallClaimedJob | null;
+};
+export type MarketInstallUpdateResult = {
+    job: {
+        createdAt: string | null;
+        failureReason: string | null;
+        finishedAt?: string | null;
+        jobId: string;
+        listingId: string | null;
+        listingName: string | null;
+        reasonKind: string | null;
+        releaseId: string;
+        status: MarketInstallUpdateStatus | "queued" | "dispatched";
+        targetNodeId: string | null;
+        targetNodeName: string | null;
+        updatedAt: string;
+        version: string | null;
+    };
+};
+export type MarketInstallManifestResult = {
+    manifest: MarketInstallAgentManifest;
+};
+export type MarketListingStatus = "archived" | "draft" | "published" | "suspended";
+export type CreateMarketListingParams = {
+    accessToken: string;
+    listingId?: string;
+    name: string;
+    slug: string;
+    authorDisplayName?: string;
+    summary?: string;
+    description?: string;
+    category?: string;
+    license?: string;
+    avatarUrl?: string;
+    tags?: string[];
+    sourceNodeId?: string | null;
+    status?: MarketListingStatus;
+};
+export type CreateMarketReleaseParams = {
+    accessToken: string;
+    listingId: string;
+    version: string;
+    storagePath: string;
+    fingerprint: string;
+    sourceType: "manifest" | "git_ref" | "plugin_node";
+    sourceRef: string;
+    publish: boolean;
+    minPluginVersion?: string;
+    minOpenClawVersion?: string;
+    compatibilityNotes?: string;
+};
+export type AgentPanelTurnClaimResult = {
+    turn: ClaimedPanelTurn | null;
+};
+export type ClawHiveApiErrorPayload = {
+    status: number;
+    error: string;
+    details?: unknown;
+};
+export declare class ClawHiveApiError extends Error {
+    readonly status: number;
+    readonly errorCode: string;
+    readonly details?: unknown;
+    constructor(payload: ClawHiveApiErrorPayload);
+}
+export declare class ClawHiveCloudApi {
+    private readonly config;
+    constructor(config: ClawHivePluginConfig);
+    get baseUrl(): string;
+    get userId(): string | null;
+    get pluginToken(): string | null;
+    private requireUserId;
+    private requirePluginToken;
+    startDeviceCode(opts?: {
+        nodeName?: string;
+        pluginVersion?: string;
+        description?: string;
+    }): Promise<DeviceCodeStartResult>;
+    exchangeDeviceCode(deviceCode: string): Promise<DeviceCodeExchangeResult>;
+    registerPluginNode(): Promise<PluginRegisterResult>;
+    createPairingCode(pluginNodeId: string, ttlSeconds?: number): Promise<PairingCodeResult>;
+    heartbeat(params: {
+        pluginNodeId: string;
+        status?: "online" | "offline" | "degraded";
+    }): Promise<{
+        plugin_node: PluginNode;
+    }>;
+    writeAgentMessage(params: {
+        pluginNodeId: string;
+        sessionId: string;
+        agentId: string;
+        content: string;
+        type?: "text" | "image" | "file" | "system";
+        metadata?: Record<string, unknown>;
+        clientMessageId?: string;
+        role?: "agent" | "system";
+    }): Promise<{
+        message: AppendedMessage;
+    }>;
+    syncAgents(agents: SyncAgentInput[]): Promise<SyncAgentsResult>;
+    refreshUserSession(refreshToken: string): Promise<UserSession>;
+    syncMessages(params: {
+        accessToken: string;
+        sessionId: string;
+        afterSequence?: number;
+        limit?: number;
+    }): Promise<SyncMessagesResult>;
+    getMessageAttachmentDownloadUrl(params: {
+        messageId: string;
+        storagePath: string;
+    }): Promise<{
+        signedUrl: string;
+        expiresIn: number;
+        mimeType: string;
+    }>;
+    /**
+     * Claim the oldest queued install job for the current plugin node.
+     */
+    claimInstallJob(params: {
+        pluginNodeId: string;
+        userId?: string;
+    }): Promise<MarketInstallClaimResult>;
+    /**
+     * Persist node-side install execution state back to the durable market job.
+     */
+    updateInstallJob(params: {
+        pluginNodeId: string;
+        jobId: string;
+        status: MarketInstallUpdateStatus;
+        userId?: string;
+        reasonKind?: MarketInstallReasonKind;
+        errorMessage?: string;
+        details?: Record<string, unknown>;
+    }): Promise<MarketInstallUpdateResult>;
+    /**
+     * Fetch the approved manifest payload for one claimed install job.
+     */
+    fetchInstallManifest(params: {
+        pluginNodeId: string;
+        jobId: string;
+        userId?: string;
+    }): Promise<MarketInstallManifestResult>;
+    /**
+     * Claim the oldest queued Agency install job for the current plugin node.
+     */
+    claimAgencyInstallJob(params: {
+        pluginNodeId: string;
+        userId?: string;
+    }): Promise<MarketInstallClaimResult>;
+    /**
+     * Persist node-side Agency install execution state back to the durable job.
+     */
+    updateAgencyInstallJob(params: {
+        pluginNodeId: string;
+        jobId: string;
+        status: MarketInstallUpdateStatus;
+        userId?: string;
+        reasonKind?: MarketInstallReasonKind;
+        errorMessage?: string;
+        details?: Record<string, unknown>;
+    }): Promise<MarketInstallUpdateResult>;
+    /**
+     * Fetch the approved Agency manifest payload for one claimed install job.
+     */
+    fetchAgencyInstallManifest(params: {
+        pluginNodeId: string;
+        jobId: string;
+        userId?: string;
+    }): Promise<MarketInstallManifestResult>;
+    createMarketListing(params: CreateMarketListingParams): Promise<{
+        listing: Record<string, unknown>;
+    }>;
+    createMarketRelease(params: CreateMarketReleaseParams): Promise<{
+        release: Record<string, unknown>;
+    }>;
+    claimPanelTurn(params: {
+        pluginNodeId: string;
+        userId?: string;
+    }): Promise<AgentPanelTurnClaimResult>;
+    updatePanelContribution(params: {
+        contributionId: string;
+        status: PanelContributionStatus;
+        content?: string | null;
+        errorMessage?: string | null;
+        startedAt?: string | null;
+        completedAt?: string | null;
+        assignment?: PanelPlanAssignment | null;
+    }): Promise<void>;
+    createPanelContribution(params: {
+        turnId: string;
+        agentId: string;
+        round: 1 | 2;
+        assignment?: PanelPlanAssignment | null;
+    }): Promise<{
+        contribution: PanelContribution;
+    }>;
+    updatePanelTurn(params: {
+        turnId: string;
+        status: PanelTurnStatus;
+        errorMessage?: string | null;
+        startedAt?: string | null;
+        completedAt?: string | null;
+        plan?: PanelPlan | null;
+        planStatus?: "pending" | "completed" | "fallback" | "failed";
+        planErrorMessage?: string | null;
+    }): Promise<void>;
+    /**
+     * Get signed download URL for a release package.
+     *
+     * This is used during install to obtain a time-limited signed URL for downloading
+     * the release package from Supabase Storage (D-12).
+     *
+     * The signed URL expires after 1 hour. If download fails with 403, the caller should
+     * retry by calling this method again to get a fresh signed URL.
+     *
+     * @param releaseId - Release UUID
+     * @param accessToken - User JWT access token
+     * @returns Signed URL, fingerprint, and expiry time
+     * @throws {ClawHiveApiError} If release is withdrawn (410), not found (404), or other errors
+     */
+    getSignedDownloadUrl(releaseId: string, accessToken: string): Promise<{
+        signed_url: string;
+        fingerprint: string;
+        expires_in: number;
+    }>;
+    /**
+     * Upload a release package to Supabase Storage.
+     *
+     * This is step 1 of the two-step publish flow (D-08):
+     * 1. Upload the tar.gz to Storage via this method → receive storage_path + fingerprint
+     * 2. Call market-releases-create with the storage_path + fingerprint + release metadata
+     *
+     * The upload is idempotent: uploading the same content to the same path is safe.
+     * Storage path format: releases/{listing_id}/{version}.tar.gz (D-09)
+     * Size limit: 10 MiB (D-10), enforced by the edge function
+     *
+     * Example usage:
+     * ```typescript
+     * import { packageAgentDirectory } from "./market-publish/packager.js";
+     *
+     * // Step 1: Package and upload
+     * const pkg = await packageAgentDirectory({ agentDir: "/path/to/agent" });
+     * const uploadResult = await client.uploadReleasePackage({
+     *   listingId: "listing-uuid",
+     *   version: "v1.0.0",
+     *   buffer: pkg.buffer,
+     *   fingerprint: pkg.fingerprint,
+     *   accessToken: "user-jwt",
+     * });
+     *
+     * // Step 2: Create release record
+     * await client.createMarketRelease({
+     *   listingId: uploadResult.listing_id,
+     *   version: "v1.0.0",
+     *   storagePath: uploadResult.storage_path,
+     *   fingerprint: uploadResult.fingerprint,
+     *   // ... other release metadata
+     * });
+     * ```
+     *
+     * @param params - Upload parameters
+     * @returns Upload result with storage_path and fingerprint
+     */
+    uploadReleasePackage(params: {
+        listingId: string;
+        version: string;
+        buffer: Buffer;
+        fingerprint: string;
+        accessToken: string;
+        onProgress?: (uploaded: number, total: number) => void;
+    }): Promise<{
+        storage_path: string;
+        fingerprint: string;
+    }>;
+    private request;
+}