@clawhive/openclaw-plugin 0.2.0

package/dist/src/client.js

@@ -0,0 +1,595 @@
+export class DeviceCodeExpiredError extends Error {
+    constructor() {
+        super("Device code expired before the user approved it");
+        this.name = "DeviceCodeExpiredError";
+    }
+}
+export class DeviceCodeDeniedError extends Error {
+    constructor() {
+        super("The user denied the device authorization request");
+        this.name = "DeviceCodeDeniedError";
+    }
+}
+/**
+ * Preserve low-level transport details so gateway logs show the real fetch cause.
+ */
+function formatTransportError(error) {
+    if (!(error instanceof Error)) {
+        return String(error);
+    }
+    const details = [error.message];
+    const cause = error.cause;
+    if (cause instanceof Error) {
+        details.push(`cause=${cause.name}: ${cause.message}`);
+    }
+    else if (cause !== undefined) {
+        details.push(`cause=${String(cause)}`);
+    }
+    const errorWithCode = error;
+    if (typeof errorWithCode.code === "string") {
+        details.push(`code=${errorWithCode.code}`);
+    }
+    return details.join("; ");
+}
+function mapPanelContribution(raw) {
+    return {
+        id: String(raw.id),
+        agentId: String(raw.agentId ?? raw.agent_id),
+        round: raw.round,
+        status: raw.status,
+        assignment: raw.assignment ?? null,
+        content: raw.content ?? null,
+        errorMessage: raw.errorMessage ?? raw.error_message ?? null,
+    };
+}
+export class ClawHiveApiError extends Error {
+    status;
+    errorCode;
+    details;
+    constructor(payload) {
+        super(payload.error);
+        this.name = "ClawHiveApiError";
+        this.status = payload.status;
+        this.errorCode = payload.error;
+        this.details = payload.details;
+    }
+}
+export class ClawHiveCloudApi {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    get baseUrl() {
+        return this.config.projectUrl.replace(/\/$/, "");
+    }
+    get userId() {
+        return this.config.userId ?? null;
+    }
+    get pluginToken() {
+        return this.config.pluginToken ?? null;
+    }
+    requireUserId() {
+        if (!this.config.userId) {
+            throw new Error("ClawHiveCloudApi: userId is not set. Call registerPluginNode() before making user-scoped calls.");
+        }
+        return this.config.userId;
+    }
+    requirePluginToken() {
+        if (!this.config.pluginToken) {
+            throw new Error("ClawHiveCloudApi: pluginToken is not set. Call bootstrap() first.");
+        }
+        return this.config.pluginToken;
+    }
+    async startDeviceCode(opts) {
+        return await this.request({
+            path: "plugin-device-code-start",
+            method: "POST",
+            auth: "none",
+            body: {
+                node_name: opts?.nodeName ?? this.config.nodeName ?? "OpenClaw Desktop",
+                plugin_version: opts?.pluginVersion ?? this.config.pluginVersion ?? "0.2.0",
+                description: opts?.description,
+            },
+        });
+    }
+    async exchangeDeviceCode(deviceCode) {
+        try {
+            const result = await this.request({
+                path: "plugin-device-code-exchange",
+                method: "POST",
+                auth: "none",
+                body: { device_code: deviceCode },
+            });
+            if (result.status === "approved") {
+                this.config.userId = result.user_id;
+                this.config.pluginToken = result.plugin_token;
+                return {
+                    status: "approved",
+                    user_id: result.user_id,
+                    plugin_token: result.plugin_token,
+                };
+            }
+            return { status: "pending", interval: result.interval };
+        }
+        catch (error) {
+            if (error instanceof ClawHiveApiError) {
+                if (error.errorCode === "expired_token") {
+                    throw new DeviceCodeExpiredError();
+                }
+                if (error.errorCode === "access_denied") {
+                    throw new DeviceCodeDeniedError();
+                }
+            }
+            throw error;
+        }
+    }
+    async registerPluginNode() {
+        const body = {
+            plugin_node_id: this.config.pluginNodeId ?? null,
+            node_name: this.config.nodeName ?? "OpenClaw Desktop",
+            plugin_version: this.config.pluginVersion ?? "0.2.0",
+        };
+        if (this.config.userId) {
+            body.user_id = this.config.userId;
+        }
+        const result = await this.request({
+            path: "plugin-register",
+            method: "POST",
+            auth: "plugin",
+            body,
+        });
+        this.config.userId = result.user_id;
+        return result;
+    }
+    async createPairingCode(pluginNodeId, ttlSeconds) {
+        return this.request({
+            path: "pairing-code-create",
+            method: "POST",
+            auth: "plugin",
+            body: {
+                plugin_node_id: pluginNodeId,
+                ttl_seconds: ttlSeconds,
+            },
+        });
+    }
+    async heartbeat(params) {
+        return this.request({
+            path: "plugin-heartbeat",
+            method: "POST",
+            auth: "plugin",
+            body: {
+                plugin_node_id: params.pluginNodeId,
+                user_id: this.requireUserId(),
+                status: params.status ?? "online",
+                plugin_version: this.config.pluginVersion ?? "0.2.0",
+            },
+        });
+    }
+    async writeAgentMessage(params) {
+        return this.request({
+            path: "plugin-message-write",
+            method: "POST",
+            auth: "plugin",
+            body: {
+                plugin_node_id: params.pluginNodeId,
+                session_id: params.sessionId,
+                agent_id: params.agentId,
+                user_id: this.requireUserId(),
+                content: params.content,
+                type: params.type,
+                metadata: params.metadata,
+                client_message_id: params.clientMessageId,
+                role: params.role ?? "agent",
+            },
+        });
+    }
+    async syncAgents(agents) {
+        return this.request({
+            path: "plugin-agents-sync",
+            method: "POST",
+            auth: "plugin",
+            body: {
+                user_id: this.requireUserId(),
+                agents: agents.map((agent) => ({
+                    openclaw_agent_id: agent.openclawAgentId,
+                    name: agent.name,
+                    description: agent.description ?? null,
+                    avatar_url: agent.avatarUrl ?? null,
+                    config: agent.config ?? {},
+                })),
+            },
+        });
+    }
+    async refreshUserSession(refreshToken) {
+        return this.request({
+            path: "auth-refresh",
+            method: "POST",
+            auth: "none",
+            body: { refreshToken },
+        });
+    }
+    async syncMessages(params) {
+        return this.request({
+            path: "messages-sync",
+            method: "GET",
+            auth: "user",
+            accessToken: params.accessToken,
+            query: {
+                session_id: params.sessionId,
+                after_sequence: params.afterSequence ?? 0,
+                limit: params.limit ?? 100,
+            },
+        });
+    }
+    async getMessageAttachmentDownloadUrl(params) {
+        return this.request({
+            path: "message-attachment-download-url",
+            method: "GET",
+            auth: "plugin",
+            query: {
+                message_id: params.messageId,
+                storage_path: params.storagePath,
+                public_origin: this.baseUrl,
+            },
+        });
+    }
+    /**
+     * Claim the oldest queued install job for the current plugin node.
+     */
+    async claimInstallJob(params) {
+        return this.request({
+            path: "market-install-claim",
+            method: "POST",
+            auth: "plugin",
+            body: {
+                pluginNodeId: params.pluginNodeId,
+                userId: params.userId ?? this.requireUserId(),
+            },
+        });
+    }
+    /**
+     * Persist node-side install execution state back to the durable market job.
+     */
+    async updateInstallJob(params) {
+        return this.request({
+            path: "market-install-update",
+            method: "POST",
+            auth: "plugin",
+            body: {
+                pluginNodeId: params.pluginNodeId,
+                jobId: params.jobId,
+                status: params.status,
+                userId: params.userId ?? this.requireUserId(),
+                reasonKind: params.reasonKind,
+                errorMessage: params.errorMessage,
+                details: params.details ?? {},
+            },
+        });
+    }
+    /**
+     * Fetch the approved manifest payload for one claimed install job.
+     */
+    async fetchInstallManifest(params) {
+        return this.request({
+            path: "market-install-manifest",
+            method: "POST",
+            auth: "plugin",
+            body: {
+                pluginNodeId: params.pluginNodeId,
+                jobId: params.jobId,
+                userId: params.userId ?? this.requireUserId(),
+            },
+        });
+    }
+    /**
+     * Claim the oldest queued Agency install job for the current plugin node.
+     */
+    async claimAgencyInstallJob(params) {
+        return this.request({
+            path: "agency-install-claim",
+            method: "POST",
+            auth: "plugin",
+            body: {
+                pluginNodeId: params.pluginNodeId,
+                userId: params.userId ?? this.requireUserId(),
+            },
+        });
+    }
+    /**
+     * Persist node-side Agency install execution state back to the durable job.
+     */
+    async updateAgencyInstallJob(params) {
+        return this.request({
+            path: "agency-install-update",
+            method: "POST",
+            auth: "plugin",
+            body: {
+                pluginNodeId: params.pluginNodeId,
+                jobId: params.jobId,
+                status: params.status,
+                userId: params.userId ?? this.requireUserId(),
+                reasonKind: params.reasonKind,
+                errorMessage: params.errorMessage,
+                details: params.details ?? {},
+            },
+        });
+    }
+    /**
+     * Fetch the approved Agency manifest payload for one claimed install job.
+     */
+    async fetchAgencyInstallManifest(params) {
+        return this.request({
+            path: "agency-install-manifest",
+            method: "POST",
+            auth: "plugin",
+            body: {
+                pluginNodeId: params.pluginNodeId,
+                jobId: params.jobId,
+                userId: params.userId ?? this.requireUserId(),
+            },
+        });
+    }
+    async createMarketListing(params) {
+        const body = {
+            name: params.name,
+            slug: params.slug,
+            status: params.status ?? "draft",
+        };
+        if (params.listingId)
+            body.listing_id = params.listingId;
+        if (params.authorDisplayName)
+            body.author_display_name = params.authorDisplayName;
+        if (params.summary)
+            body.summary = params.summary;
+        if (params.description)
+            body.description = params.description;
+        if (params.category)
+            body.category = params.category;
+        if (params.license)
+            body.license = params.license;
+        if (params.avatarUrl)
+            body.avatar_url = params.avatarUrl;
+        if (params.tags)
+            body.tags = params.tags;
+        if (params.sourceNodeId)
+            body.source_node_id = params.sourceNodeId;
+        return this.request({
+            path: "market-listings",
+            method: "POST",
+            auth: "user",
+            accessToken: params.accessToken,
+            body,
+        });
+    }
+    async createMarketRelease(params) {
+        const body = {
+            listing_id: params.listingId,
+            version: params.version,
+            storage_path: params.storagePath,
+            fingerprint: params.fingerprint,
+            source_type: params.sourceType,
+            source_ref: params.sourceRef,
+            publish: params.publish,
+        };
+        if (params.minPluginVersion)
+            body.min_plugin_version = params.minPluginVersion;
+        if (params.minOpenClawVersion)
+            body.min_openclaw_version = params.minOpenClawVersion;
+        if (params.compatibilityNotes)
+            body.compatibility_notes = params.compatibilityNotes;
+        return this.request({
+            path: "market-releases-create",
+            method: "POST",
+            auth: "user",
+            accessToken: params.accessToken,
+            body,
+        });
+    }
+    async claimPanelTurn(params) {
+        return this.request({
+            path: "agent-panel-turn-claim",
+            method: "POST",
+            auth: "plugin",
+            body: {
+                pluginNodeId: params.pluginNodeId,
+                userId: params.userId ?? this.requireUserId(),
+            },
+        });
+    }
+    async updatePanelContribution(params) {
+        await this.request({
+            path: "agent-panel-contribution-update",
+            method: "POST",
+            auth: "plugin",
+            body: {
+                contributionId: params.contributionId,
+                status: params.status,
+                content: params.content,
+                errorMessage: params.errorMessage,
+                startedAt: params.startedAt,
+                completedAt: params.completedAt,
+                assignment: params.assignment,
+            },
+        });
+    }
+    async createPanelContribution(params) {
+        const result = await this.request({
+            path: "agent-panel-contribution-create",
+            method: "POST",
+            auth: "plugin",
+            body: {
+                turnId: params.turnId,
+                agentId: params.agentId,
+                round: params.round,
+                assignment: params.assignment,
+            },
+        });
+        return { contribution: mapPanelContribution(result.contribution) };
+    }
+    async updatePanelTurn(params) {
+        await this.request({
+            path: "agent-panel-turn-update",
+            method: "POST",
+            auth: "plugin",
+            body: {
+                turnId: params.turnId,
+                status: params.status,
+                errorMessage: params.errorMessage,
+                startedAt: params.startedAt,
+                completedAt: params.completedAt,
+                plan: params.plan,
+                planStatus: params.planStatus,
+                planErrorMessage: params.planErrorMessage,
+            },
+        });
+    }
+    /**
+     * 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
+     */
+    async getSignedDownloadUrl(releaseId, accessToken) {
+        return this.request({
+            path: "market-release-download",
+            method: "GET",
+            auth: "user",
+            accessToken,
+            query: {
+                release_id: releaseId,
+            },
+        });
+    }
+    /**
+     * 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
+     */
+    async uploadReleasePackage(params) {
+        const url = new URL(`${this.baseUrl}/functions/v1/market-release-upload`);
+        const headers = {
+            "Content-Type": "application/json",
+            apikey: this.config.anonKey,
+            Authorization: `Bearer ${params.accessToken}`,
+        };
+        let response;
+        try {
+            response = await fetch(url.toString(), {
+                method: "POST",
+                headers,
+                body: JSON.stringify({
+                    listing_id: params.listingId,
+                    version: params.version,
+                    file_data: params.buffer.toString("base64"),
+                }),
+            });
+        }
+        catch (error) {
+            const reason = formatTransportError(error);
+            throw new Error(`ClawHive market-release-upload request failed (POST ${url.toString()}): ${reason}`);
+        }
+        const text = await response.text();
+        const payload = text ? JSON.parse(text) : {};
+        if (!response.ok) {
+            throw new ClawHiveApiError({
+                status: response.status,
+                error: typeof payload.error === "string"
+                    ? payload.error
+                    : `ClawHive market-release-upload failed (${response.status})`,
+                details: payload.details,
+            });
+        }
+        return payload;
+    }
+    async request(options) {
+        const url = new URL(`${this.baseUrl}/functions/v1/${options.path}`);
+        const method = options.method ?? "GET";
+        for (const [key, value] of Object.entries(options.query ?? {})) {
+            if (value !== undefined && value !== null) {
+                url.searchParams.set(key, String(value));
+            }
+        }
+        const headers = {
+            "Content-Type": "application/json",
+            Connection: "close",
+            apikey: this.config.anonKey,
+        };
+        if (options.auth === "plugin") {
+            headers.Authorization = `Bearer ${this.config.anonKey}`;
+            headers["x-plugin-token"] = this.requirePluginToken();
+        }
+        else if (options.auth === "user" && options.accessToken) {
+            headers.Authorization = `Bearer ${options.accessToken}`;
+        }
+        else if (options.auth === "none") {
+            headers.Authorization = `Bearer ${this.config.anonKey}`;
+        }
+        let response;
+        try {
+            response = await fetch(url.toString(), {
+                method,
+                headers,
+                body: options.body && method !== "GET"
+                    ? JSON.stringify(options.body)
+                    : undefined,
+            });
+        }
+        catch (error) {
+            const reason = formatTransportError(error);
+            throw new Error(`ClawHive ${options.path} request failed (${method} ${url.toString()}): ${reason}`);
+        }
+        const text = await response.text();
+        const payload = text ? JSON.parse(text) : {};
+        if (!response.ok) {
+            throw new ClawHiveApiError({
+                status: response.status,
+                error: typeof payload.error === "string"
+                    ? payload.error
+                    : `ClawHive ${options.path} failed (${response.status})`,
+                details: payload.details,
+            });
+        }
+        return payload;
+    }
+}

package/dist/src/config.d.ts

@@ -0,0 +1,28 @@
+import { type ChannelSetupInput, type OpenClawConfig } from "openclaw/plugin-sdk/core";
+export declare const CLAWHIVE_CHANNEL_ID = "clawhive";
+export type ClawHiveResolvedAccount = {
+    accountId: string;
+    projectUrl: string;
+    anonKey: string;
+    pluginToken: string;
+    userId: string | null;
+    pluginNodeId: string | null;
+    nodeName: string;
+    pluginVersion: string;
+    publishSourceRef: string | null;
+    publishFingerprint: string | null;
+    minPluginVersion: string | null;
+    minOpenClawVersion: string | null;
+    dmPolicy: string | null;
+    allowFrom: Array<string | number>;
+};
+export declare function readRawChannelSection(cfg: OpenClawConfig): Record<string, unknown>;
+export declare function resolveResolvedAccount(cfg: OpenClawConfig, accountId?: string | null): ClawHiveResolvedAccount;
+export declare function writeChannelSection(cfg: OpenClawConfig, input: ChannelSetupInput): OpenClawConfig;
+export declare function writePluginNodeId(cfg: OpenClawConfig, pluginNodeId: string): OpenClawConfig;
+export declare function writeRegistrationIdentity(cfg: OpenClawConfig, patch: {
+    userId?: string;
+    pluginNodeId?: string;
+    pluginToken?: string;
+    anonKey?: string;
+}): OpenClawConfig;