@synap-core/cli 1.6.1 → 1.7.0

package/node_modules/@synap/hub-rest-client/dist/index.js

@@ -0,0 +1,851 @@
+// src/errors.ts
+var HubApiError = class extends Error {
+  constructor(message, statusCode, body) {
+    super(message);
+    this.statusCode = statusCode;
+    this.body = body;
+    this.name = "HubApiError";
+  }
+  get isUnauthorized() {
+    return this.statusCode === 401;
+  }
+  get isForbidden() {
+    return this.statusCode === 403;
+  }
+  get isNotFound() {
+    return this.statusCode === 404;
+  }
+  get isServerError() {
+    return this.statusCode >= 500;
+  }
+};
+
+// src/client.ts
+function normalizeUrl(url) {
+  return url.replace(/\/$/, "");
+}
+function formatHubErrorMessage(status, statusText, errorBody) {
+  let detail = "";
+  if (errorBody && typeof errorBody === "object" && "error" in errorBody) {
+    detail = String(errorBody.error);
+  }
+  const base = `Hub API error: ${status} ${statusText}`;
+  let msg = detail ? `${base} \u2014 ${detail}` : base;
+  if (status === 403 && /hub-protocol\.write/i.test(detail)) {
+    msg += " Create or reconnect an API key that includes the hub-protocol.write scope (Settings \u2192 API keys on your pod).";
+  }
+  return msg;
+}
+function unwrapList(result) {
+  return Array.isArray(result) ? result : result.data ?? [];
+}
+function unwrapWorkspacesResponse(result) {
+  if (Array.isArray(result)) return result;
+  if (result && typeof result === "object" && "workspaces" in result) {
+    const w = result.workspaces;
+    return Array.isArray(w) ? w : [];
+  }
+  return unwrapList(result);
+}
+function unwrapSingle(result) {
+  if (result && typeof result === "object" && "data" in result) {
+    return result.data;
+  }
+  return result;
+}
+var HubRestClient = class {
+  base;
+  headers;
+  timeoutMs;
+  workspaceId;
+  /** Cached from GET /users/me — avoids repeated identity calls. */
+  resolvedUserId = null;
+  constructor(config) {
+    this.base = normalizeUrl(config.podUrl);
+    this.headers = {
+      Authorization: `Bearer ${config.apiKey}`,
+      "Content-Type": "application/json"
+    };
+    this.workspaceId = config.workspaceId;
+    this.timeoutMs = config.timeoutMs ?? 3e4;
+  }
+  /** User id for the current API key (Hub REST requires userId on several GETs). */
+  async resolveUserId() {
+    if (this.resolvedUserId) return this.resolvedUserId;
+    const me = await this.getMe();
+    this.resolvedUserId = me.id;
+    return me.id;
+  }
+  async request(method, path, body, signal) {
+    const url = `${this.base}${path}`;
+    const timeout = AbortSignal.timeout(this.timeoutMs);
+    const combined = signal ? AbortSignal.any([signal, timeout]) : timeout;
+    const res = await fetch(url, {
+      method,
+      headers: this.headers,
+      body: body !== void 0 ? JSON.stringify(body) : void 0,
+      signal: combined
+    });
+    if (!res.ok) {
+      const errorBody = await res.json().catch(() => ({}));
+      throw new HubApiError(
+        formatHubErrorMessage(res.status, res.statusText, errorBody),
+        res.status,
+        errorBody
+      );
+    }
+    return res.json();
+  }
+  // ─── Identity ─────────────────────────────────────────────────────────────
+  async getMe() {
+    return this.request("GET", "/api/hub/users/me");
+  }
+  async getWorkspaces() {
+    const result = await this.request("GET", "/api/hub/workspaces");
+    return unwrapWorkspacesResponse(result);
+  }
+  async provisionAgentWorkspace(input) {
+    return this.request(
+      "POST",
+      "/api/hub/workspaces/provision-agent",
+      input
+    );
+  }
+  /**
+   * Get full activity context for a user — recent entities, active threads, workspace summary.
+   * Use at session start to orient the agent to the user's current state.
+   */
+  async getUserContext(userId, options) {
+    const params = new URLSearchParams();
+    const wsId = options?.workspaceId ?? this.workspaceId;
+    if (wsId) params.set("workspaceId", wsId);
+    const qs = params.toString() ? `?${params}` : "";
+    return this.request(
+      "GET",
+      `/api/hub/users/${userId}/context${qs}`
+    );
+  }
+  // ─── Entities ─────────────────────────────────────────────────────────────
+  async searchEntities(query, options, signal) {
+    const params = new URLSearchParams({ q: query });
+    if (options?.profileSlug) params.set("profileSlug", options.profileSlug);
+    if (options?.scope !== "all") {
+      const wsId = options?.workspaceId ?? this.workspaceId;
+      if (wsId) params.set("workspaceId", wsId);
+    }
+    if (options?.limit) params.set("limit", String(options.limit));
+    const result = await this.request(
+      "GET",
+      `/api/hub/entities?${params}`,
+      void 0,
+      signal
+    );
+    return unwrapList(result);
+  }
+  async getEntity(id) {
+    const result = await this.request(
+      "GET",
+      `/api/hub/entities/${id}`
+    );
+    return unwrapSingle(result);
+  }
+  async getRecentEntities(options) {
+    const params = new URLSearchParams({
+      sort: "updatedAt:desc",
+      limit: String(options?.limit ?? 20)
+    });
+    if (options?.profileSlug) params.set("profileSlug", options.profileSlug);
+    if (options?.scope !== "all") {
+      const wsId = options?.workspaceId ?? this.workspaceId;
+      if (wsId) params.set("workspaceId", wsId);
+    }
+    const result = await this.request(
+      "GET",
+      `/api/hub/entities?${params}`
+    );
+    return unwrapList(result);
+  }
+  async createEntity(input) {
+    return this.request("POST", "/api/hub/entities", {
+      ...input,
+      workspaceId: input.workspaceId ?? this.workspaceId
+    });
+  }
+  async updateEntity(id, input) {
+    return this.request(
+      "PATCH",
+      `/api/hub/entities/${id}`,
+      input
+    );
+  }
+  // ─── Unified Search ───────────────────────────────────────────────────────
+  /**
+   * Unified full-text search across entities, documents, and views.
+   * Use when you don't know the content type. For entity-only search use searchEntities().
+   *
+   * Note: The backend GET /search requires userId as a query param; this method resolves
+   * the current user automatically.
+   */
+  async search(query, options, signal) {
+    const userId = await this.resolveUserId();
+    const wsId = options?.workspaceId ?? this.workspaceId;
+    const params = new URLSearchParams({ userId, query });
+    if (wsId) params.set("workspaceId", wsId);
+    if (options?.collections?.length)
+      params.set("collections", options.collections.join(","));
+    if (options?.limit) params.set("limit", String(options.limit));
+    return this.request(
+      "GET",
+      `/api/hub/search?${params}`,
+      void 0,
+      signal
+    );
+  }
+  // ─── Relations & Graph ────────────────────────────────────────────────────
+  /**
+   * Get all relations for an entity — inbound and outbound.
+   * Use to discover connections before graph traversal.
+   *
+   * Note: The backend GET /relations requires both userId and workspaceId.
+   * This method resolves userId automatically; workspaceId falls back to client default.
+   */
+  async getRelations(entityId, options) {
+    const userId = await this.resolveUserId();
+    const wsId = options?.workspaceId ?? this.workspaceId;
+    if (!wsId) throw new Error("workspaceId is required for getRelations");
+    const params = new URLSearchParams({ userId, workspaceId: wsId, entityId });
+    const result = await this.request("GET", `/api/hub/relations?${params}`);
+    return unwrapList(result);
+  }
+  /**
+   * Create a typed relation between two entities.
+   * Type is a free string — conventions: "related_to", "parent_of", "child_of",
+   * "belongs_to", "authored_by", "depends_on", "references".
+   * Goes through governance — may return "proposed".
+   */
+  async createRelation(input) {
+    const userId = input.userId ?? await this.resolveUserId();
+    const wsId = input.workspaceId ?? this.workspaceId;
+    if (!wsId) throw new Error("workspaceId is required for createRelation");
+    return this.request("POST", "/api/hub/relations", {
+      userId,
+      workspaceId: wsId,
+      sourceEntityId: input.sourceEntityId,
+      targetEntityId: input.targetEntityId,
+      type: input.type
+    });
+  }
+  /**
+   * Delete a relation by ID (get from getRelations()).
+   */
+  async deleteRelation(relationId) {
+    const userId = await this.resolveUserId();
+    await this.request("DELETE", `/api/hub/relations/${relationId}`, {
+      userId
+    });
+  }
+  /**
+   * Traverse the knowledge graph from an entity using BFS.
+   * Returns nodes and edges up to maxDepth hops away.
+   * maxDepth: 1=direct neighbors, 2=neighborhood (recommended), 3=extended (expensive).
+   *
+   * @example
+   * const graph = await client.traverseGraph(projectId, { maxDepth: 2 });
+   * const tasks = graph.nodes.filter(n => n.profileSlug === "task");
+   */
+  async traverseGraph(entityId, options) {
+    const userId = await this.resolveUserId();
+    const params = new URLSearchParams({
+      userId,
+      startEntityId: entityId,
+      maxDepth: String(options?.maxDepth ?? 2)
+    });
+    const wsId = options?.workspaceId ?? this.workspaceId;
+    if (wsId) params.set("workspaceId", wsId);
+    return this.request(
+      "GET",
+      `/api/hub/graph/traverse?${params}`
+    );
+  }
+  /**
+   * Unified view of everything connected to an entity. Merges three sources:
+   *   1. Graph relations — explicit rows in the relations table (both directions)
+   *   2. Structural links — entities whose `entity_id` properties point to this entity
+   *   3. Thread connections — chat threads that touched this entity
+   *
+   * Prefer this over `getRelations()` / `traverseGraph()` when you want the complete
+   * picture — those only see the relations table and miss property-based links that
+   * haven't been synced (notably custom profiles without a `relationDefId` mapping).
+   *
+   * Each connection carries a `source` field so callers can filter by origin.
+   *
+   * @example
+   * const { connections } = await client.getConnections(entityId);
+   * const tasks = connections.filter(c => c.entity?.profileSlug === "task");
+   */
+  async getConnections(entityId, options) {
+    const userId = await this.resolveUserId();
+    const wsId = options?.workspaceId ?? this.workspaceId;
+    const params = new URLSearchParams({ userId });
+    if (wsId) params.set("workspaceId", wsId);
+    if (options?.limit) params.set("limit", String(options.limit));
+    return this.request(
+      "GET",
+      `/api/hub/entities/${entityId}/connections?${params}`
+    );
+  }
+  // ─── Profiles & Schema ────────────────────────────────────────────────────
+  /**
+   * List all entity profile types in the workspace.
+   * Always call before creating entities to discover what types are available.
+   * Returns system profiles (always present) + custom workspace profiles.
+   */
+  async listProfiles(workspaceId) {
+    const userId = await this.resolveUserId();
+    const params = new URLSearchParams({ userId, workspaceId });
+    const result = await this.request("GET", `/api/hub/profiles?${params}`);
+    return unwrapList(result);
+  }
+  /**
+   * List property definitions for a workspace, optionally filtered by profile.
+   */
+  async listPropertyDefs(workspaceId, options) {
+    const userId = await this.resolveUserId();
+    const params = new URLSearchParams({ userId, workspaceId });
+    if (options?.profileSlug) params.set("profileId", options.profileSlug);
+    const result = await this.request("GET", `/api/hub/property-defs?${params}`);
+    return unwrapList(result);
+  }
+  /**
+   * Runtime discovery — profiles with property schemas + command tree.
+   *
+   * Call once per session at session start. Returns ground-truth profile
+   * schemas (including custom workspace profiles) and the canonical CLI
+   * command map. Replaces static skill file profile descriptions.
+   */
+  async discover(workspaceId) {
+    const userId = await this.resolveUserId();
+    const wsId = workspaceId ?? this.workspaceId ?? "";
+    const params = new URLSearchParams({ userId, workspaceId: wsId });
+    return this.request(
+      "GET",
+      `/api/hub/discover?${params}`
+    );
+  }
+  // ─── Threads & Channels ───────────────────────────────────────────────────
+  /**
+   * List threads (channels) accessible to a user.
+   */
+  async listThreads(userId, options) {
+    const wsId = options?.workspaceId ?? this.workspaceId;
+    const params = new URLSearchParams({ userId });
+    if (wsId) params.set("workspaceId", wsId);
+    if (options?.type) params.set("type", options.type);
+    const result = await this.request(
+      "GET",
+      `/api/hub/threads?${params}`
+    );
+    return unwrapList(result);
+  }
+  /**
+   * Get the user's personal channel — their private AI conversation thread.
+   * Use as default destination for messages and proactive posts.
+   *
+   * Note: The backend GET /channels/personal requires both userId and workspaceId.
+   */
+  async getPersonalChannel(userId, workspaceId) {
+    const wsId = workspaceId ?? this.workspaceId;
+    if (!wsId)
+      throw new Error("workspaceId is required for getPersonalChannel");
+    const params = new URLSearchParams({ userId, workspaceId: wsId });
+    return this.request(
+      "GET",
+      `/api/hub/channels/personal?${params}`
+    );
+  }
+  /**
+   * Create a new thread. Pass entityId to auto-link on creation.
+   *
+   * Note: The backend POST /threads requires workspaceId in the body.
+   */
+  async createThread(input) {
+    const userId = input.userId ?? await this.resolveUserId();
+    const wsId = input.workspaceId ?? this.workspaceId;
+    if (!wsId) throw new Error("workspaceId is required for createThread");
+    return this.request("POST", "/api/hub/threads", {
+      userId,
+      workspaceId: wsId,
+      title: input.name,
+      agentType: input.agentType,
+      contextObjectType: input.entityId ? "entity" : input.documentId ? "document" : void 0,
+      contextObjectId: input.entityId ?? input.documentId
+    });
+  }
+  /**
+   * Get full thread context: messages + all linked entities and documents.
+   * Call before sending a message to orient the AI with conversation history.
+   */
+  async getThreadContext(threadId) {
+    return this.request(
+      "GET",
+      `/api/hub/threads/${threadId}/context`
+    );
+  }
+  /**
+   * Get messages in a thread.
+   */
+  async getMessages(threadId, _options) {
+    const result = await this.request("GET", `/api/hub/threads/${threadId}/messages`);
+    return unwrapList(result);
+  }
+  /**
+   * Link an entity to a thread so it appears in thread context for AI.
+   */
+  async linkEntityToThread(threadId, entityId) {
+    const userId = await this.resolveUserId();
+    await this.request(
+      "POST",
+      `/api/hub/threads/${threadId}/link-entity`,
+      { userId, entityId }
+    );
+  }
+  /**
+   * Link a document to a thread.
+   */
+  async linkDocumentToThread(threadId, documentId) {
+    const userId = await this.resolveUserId();
+    await this.request(
+      "POST",
+      `/api/hub/threads/${threadId}/link-document`,
+      { userId, documentId }
+    );
+  }
+  /**
+   * Get research branches of a thread — parallel AI investigations.
+   */
+  async getThreadBranches(threadId) {
+    const result = await this.request("GET", `/api/hub/threads/${threadId}/branches`);
+    return result.branches ?? [];
+  }
+  // ─── Memory ───────────────────────────────────────────────────────────────
+  async storeMemory(input) {
+    const userId = await this.resolveUserId();
+    const fact = input.context && String(input.context).trim().length > 0 ? `[${String(input.context).trim()}] ${input.fact}` : input.fact;
+    return this.request("POST", "/api/hub/memory", {
+      userId,
+      fact
+    });
+  }
+  async recallMemory(query, options) {
+    const wsId = options?.workspaceId ?? this.workspaceId;
+    const userId = await this.resolveUserId();
+    const params = new URLSearchParams({
+      userId,
+      query,
+      limit: String(options?.limit ?? 10)
+    });
+    if (wsId) params.set("workspaceId", wsId);
+    const result = await this.request("GET", `/api/hub/memory?${params}`);
+    return unwrapList(result);
+  }
+  /**
+   * Delete a stored memory fact by ID.
+   */
+  async deleteMemory(memoryId) {
+    const userId = await this.resolveUserId();
+    const params = new URLSearchParams({ userId });
+    await this.request(
+      "DELETE",
+      `/api/hub/memory/${memoryId}?${params}`
+    );
+  }
+  // ─── Channels (Hub REST: channels are listed via GET /threads) ────────────
+  async getChannels(options) {
+    const wsId = options?.workspaceId ?? this.workspaceId;
+    const userId = await this.resolveUserId();
+    const params = new URLSearchParams({ userId });
+    if (wsId) params.set("workspaceId", wsId);
+    const result = await this.request("GET", `/api/hub/threads?${params}`);
+    return unwrapList(result);
+  }
+  async sendToChannel(input) {
+    const userId = input.userId ?? await this.resolveUserId();
+    return this.request(
+      "POST",
+      `/api/hub/threads/${input.channelId}/messages`,
+      {
+        role: input.role ?? "user",
+        content: input.content,
+        userId,
+        ...input.autoRespond !== void 0 ? { autoRespond: input.autoRespond } : {}
+      }
+    );
+  }
+  // ─── Proposals ────────────────────────────────────────────────────────────
+  /**
+   * List proposals — pending AI writes awaiting human review.
+   * Filter by status: "pending" (needs review), "approved", "rejected".
+   */
+  async listProposals(options) {
+    const userId = await this.resolveUserId();
+    const wsId = options?.workspaceId ?? this.workspaceId;
+    const params = new URLSearchParams({ userId });
+    if (options?.status) params.set("status", options.status);
+    if (wsId) params.set("workspaceId", wsId);
+    if (options?.limit) params.set("limit", String(options.limit));
+    const result = await this.request("GET", `/api/hub/proposals?${params}`);
+    return unwrapList(result);
+  }
+  /**
+   * Approve or reject a proposal.
+   *
+   * Note: The backend PATCH /proposals/:id is an AI-revision endpoint that updates
+   * the proposal data/summary, not a review (approve/reject) endpoint.
+   * Use this to update proposal data before human review.
+   */
+  async reviewProposal(proposalId, decision, reason) {
+    return this.request(
+      "PATCH",
+      `/api/hub/proposals/${proposalId}`,
+      {
+        data: { status: decision },
+        summary: reason
+      }
+    );
+  }
+  // ─── Views ────────────────────────────────────────────────────────────────
+  /**
+   * List data views in a workspace.
+   */
+  async listViews(workspaceId, options) {
+    const userId = await this.resolveUserId();
+    const params = new URLSearchParams({ userId, workspaceId });
+    if (options?.profileSlug) params.set("profileId", options.profileSlug);
+    const result = await this.request(
+      "GET",
+      `/api/hub/views?${params}`
+    );
+    return unwrapList(result);
+  }
+  /**
+   * Create a new view. Goes through governance.
+   */
+  async createView(input) {
+    const userId = input.userId ?? await this.resolveUserId();
+    return this.request("POST", "/api/hub/views", {
+      userId,
+      workspaceId: input.workspaceId ?? this.workspaceId,
+      name: input.name,
+      type: input.type,
+      profileId: input.profileSlug,
+      config: input.config
+    });
+  }
+  // ─── Documents ────────────────────────────────────────────────────────────
+  /**
+   * Get a document by ID with full markdown content.
+   */
+  async getDocument(documentId) {
+    const userId = await this.resolveUserId();
+    const params = new URLSearchParams({ userId });
+    return this.request(
+      "GET",
+      `/api/hub/documents/${documentId}?${params}`
+    );
+  }
+  /**
+   * Create a document. Use for long-form content: meeting notes, research, writeups.
+   * Goes through governance.
+   */
+  async createDocument(input) {
+    const userId = await this.resolveUserId();
+    return this.request("POST", "/api/hub/documents", {
+      userId,
+      workspaceId: input.workspaceId ?? this.workspaceId,
+      title: input.title,
+      content: input.content ?? ""
+    });
+  }
+  // ─── Commands & Agents ────────────────────────────────────────────────────
+  /**
+   * List available commands (automation shortcuts) in the workspace.
+   */
+  async listCommands(workspaceId) {
+    const wsId = workspaceId ?? this.workspaceId;
+    const params = new URLSearchParams();
+    if (wsId) params.set("workspaceId", wsId);
+    const qs = params.toString() ? `?${params}` : "";
+    const result = await this.request("GET", `/api/hub/commands${qs}`);
+    return unwrapList(result);
+  }
+  /**
+   * Execute a command by slug.
+   *
+   * Note: The backend POST /commands/execute uses a `command` field (the shell command
+   * string) and `userId`, not a `slug`. This maps ExecuteCommandInput.slug to `command`.
+   */
+  async executeCommand(input) {
+    const userId = input.userId ?? await this.resolveUserId();
+    return this.request(
+      "POST",
+      "/api/hub/commands/execute",
+      {
+        command: input.slug,
+        userId,
+        workspaceId: input.workspaceId ?? this.workspaceId,
+        ...input.parameters ? { parameters: input.parameters } : {}
+      }
+    );
+  }
+  /**
+   * List agent users provisioned in the workspace.
+   */
+  async listAgentUsers(workspaceId) {
+    const wsId = workspaceId ?? this.workspaceId;
+    const params = new URLSearchParams();
+    if (wsId) params.set("workspaceId", wsId);
+    const qs = params.toString() ? `?${params}` : "";
+    const result = await this.request("GET", `/api/hub/agent-users${qs}`);
+    return unwrapList(result);
+  }
+  // ─── Proactive posting ────────────────────────────────────────────────────
+  /**
+   * Post a proactive message to the user's personal channel.
+   * For AI-initiated insights and summaries. Rate-limited: 3/hour, 10/day.
+   * proactiveType must be one of: insight, suggestion, alert, nudge,
+   * morning_briefing, weekly_digest, health_check.
+   */
+  async postProactive(userId, content, options) {
+    const wsId = options?.workspaceId ?? this.workspaceId;
+    if (!wsId) throw new Error("workspaceId is required for postProactive");
+    return this.request("POST", "/api/hub/proactive/post", {
+      userId,
+      workspaceId: wsId,
+      content,
+      proactiveType: options?.type ?? "insight"
+    });
+  }
+  // ─── Capture pipeline ─────────────────────────────────────────────────────
+  async captureStructure(input) {
+    const userId = await this.resolveUserId();
+    return this.request(
+      "POST",
+      "/api/hub/capture/structure",
+      {
+        userId,
+        text: input.text,
+        url: input.url,
+        workspaceId: input.workspaceId ?? this.workspaceId,
+        previousEntities: input.previousEntities
+      }
+    );
+  }
+  async captureExecute(input) {
+    const userId = await this.resolveUserId();
+    return this.request(
+      "POST",
+      "/api/hub/capture/execute",
+      {
+        userId,
+        entities: input.entities,
+        relations: input.relations ?? [],
+        workspaceId: input.workspaceId ?? this.workspaceId
+      }
+    );
+  }
+  // ─── Automations ───────────────────────────────────────────────────────────
+  /**
+   * List automations for the current user, optionally filtered by workspace and status.
+   */
+  async listAutomations(options) {
+    const userId = await this.resolveUserId();
+    const wsId = options?.workspaceId ?? this.workspaceId;
+    const params = new URLSearchParams({ userId });
+    if (wsId) params.set("workspaceId", wsId);
+    if (options?.status) params.set("status", options.status);
+    if (options?.limit) params.set("limit", String(options.limit));
+    const result = await this.request("GET", `/api/hub/automations?${params}`);
+    return unwrapList(result);
+  }
+  /**
+   * Get a single automation by ID.
+   */
+  async getAutomation(automationId, options) {
+    const userId = await this.resolveUserId();
+    const wsId = options?.workspaceId ?? this.workspaceId;
+    const params = new URLSearchParams({ userId });
+    if (wsId) params.set("workspaceId", wsId);
+    return this.request(
+      "GET",
+      `/api/hub/automations/${automationId}?${params}`
+    );
+  }
+  /**
+   * Create an automation. Defaults to status=draft.
+   * Use activateAutomation() to enable it.
+   */
+  async createAutomation(input) {
+    const userId = input.userId ?? await this.resolveUserId();
+    const wsId = input.workspaceId ?? this.workspaceId;
+    return this.request("POST", "/api/hub/automations/create", {
+      ...input,
+      userId,
+      workspaceId: wsId ?? null
+    });
+  }
+  /**
+   * Update an automation's definition or metadata.
+   */
+  async updateAutomation(automationId, input) {
+    const userId = input.userId ?? await this.resolveUserId();
+    const wsId = input.workspaceId ?? this.workspaceId;
+    if (!wsId) throw new Error("workspaceId is required for updateAutomation");
+    return this.request(
+      "PATCH",
+      `/api/hub/automations/${automationId}`,
+      { ...input, userId, workspaceId: wsId }
+    );
+  }
+  /**
+   * Manually trigger an automation once with an optional payload.
+   * Bypasses the automation's normal trigger config.
+   */
+  async triggerAutomation(automationId, options) {
+    const userId = await this.resolveUserId();
+    const wsId = options?.workspaceId ?? this.workspaceId;
+    return this.request(
+      "POST",
+      `/api/hub/automations/${automationId}/trigger`,
+      { userId, workspaceId: wsId ?? null, payload: options?.payload }
+    );
+  }
+  /**
+   * Activate a draft or paused automation (sets status=active).
+   */
+  async activateAutomation(automationId, options) {
+    const userId = await this.resolveUserId();
+    const wsId = options?.workspaceId ?? this.workspaceId;
+    if (!wsId)
+      throw new Error("workspaceId is required for activateAutomation");
+    return this.request(
+      "POST",
+      `/api/hub/automations/${automationId}/activate`,
+      { userId, workspaceId: wsId }
+    );
+  }
+  /**
+   * Pause an active automation (sets status=paused).
+   */
+  async pauseAutomation(automationId, options) {
+    const userId = await this.resolveUserId();
+    const wsId = options?.workspaceId ?? this.workspaceId;
+    if (!wsId) throw new Error("workspaceId is required for pauseAutomation");
+    return this.request(
+      "POST",
+      `/api/hub/automations/${automationId}/pause`,
+      { userId, workspaceId: wsId }
+    );
+  }
+  // ─── Subscriptions / Reactions (Pulse) ────────────────────────────────────
+  /**
+   * List the user-wide Pulse feed — the timestamp-sorted union of reactive events.
+   * Call getSubscriptionFanout() on an individual event for its dense reactions[].
+   */
+  async listSubscriptions(options) {
+    const wsId = options?.workspaceId ?? this.workspaceId;
+    const params = new URLSearchParams();
+    if (wsId) params.set("workspaceId", wsId);
+    if (options?.kind) params.set("kind", options.kind);
+    if (options?.eventType) params.set("eventType", options.eventType);
+    if (options?.lens) params.set("lens", options.lens);
+    if (options?.limit) params.set("limit", String(options.limit));
+    const qs = params.toString() ? `?${params}` : "";
+    const result = await this.request("GET", `/api/hub/subscriptions${qs}`);
+    return unwrapList(result);
+  }
+  /**
+   * Get the reaction fan-out for a single event — full reactions[] populated.
+   */
+  async getSubscriptionFanout(eventId, options) {
+    const params = new URLSearchParams();
+    if (options?.lens) params.set("lens", options.lens);
+    const qs = params.toString() ? `?${params}` : "";
+    return this.request(
+      "GET",
+      `/api/hub/subscriptions/${eventId}/fanout${qs}`
+    );
+  }
+  // ─── Notifications ─────────────────────────────────────────────────────────
+  /**
+   * Persist a notification and emit notification:new to the frontend.
+   * Use for IS-originated events (skill.triggered, agent actions, etc.).
+   * Backend-originated notifications (vault, proposals) use NotificationService directly.
+   */
+  async createNotification(input) {
+    return this.request(
+      "POST",
+      "/api/hub/notifications",
+      input
+    );
+  }
+  // ─── Webhooks ──────────────────────────────────────────────────────────────
+  /**
+   * List delivery log for a webhook subscription.
+   * Powers the Reactions Health tab and replay flows.
+   */
+  async getWebhookDeliveries(subscriptionId, options) {
+    const params = new URLSearchParams();
+    if (options?.limit) params.set("limit", String(options.limit));
+    const qs = params.toString() ? `?${params}` : "";
+    const result = await this.request("GET", `/api/hub/webhooks/${subscriptionId}/deliveries${qs}`);
+    return unwrapList(result);
+  }
+};
+
+// src/setup.ts
+function normalizeUrl2(url) {
+  return url.replace(/\/$/, "");
+}
+async function checkPodHealth(podUrl) {
+  const url = normalizeUrl2(podUrl);
+  const status = { url, healthy: false };
+  try {
+    const res = await fetch(`${url}/health`, {
+      signal: AbortSignal.timeout(5e3)
+    });
+    if (res.ok) {
+      status.healthy = true;
+      const data = await res.json();
+      status.version = data.version;
+    }
+  } catch {
+  }
+  return status;
+}
+async function setupAgent(podUrl, provisioningToken, agentType = "openclaw") {
+  const url = normalizeUrl2(podUrl);
+  const res = await fetch(`${url}/api/hub/setup/agent`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${provisioningToken}`
+    },
+    body: JSON.stringify({ agentType }),
+    signal: AbortSignal.timeout(15e3)
+  });
+  if (!res.ok) {
+    const body = await res.json().catch(() => ({}));
+    throw new HubApiError(
+      `Agent setup failed (HTTP ${res.status})`,
+      res.status,
+      body
+    );
+  }
+  return res.json();
+}
+export {
+  HubApiError,
+  HubRestClient,
+  checkPodHealth,
+  setupAgent
+};