@synap-core/cli 1.6.1 → 1.7.0

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

@@ -0,0 +1,907 @@
+/**
+ * @synap/hub-rest-client — Hub Protocol REST API Types
+ *
+ * Canonical TypeScript interfaces for all objects returned by the
+ * Synap Hub Protocol REST API (`/api/hub/*`).
+ *
+ * These are the source of truth for external consumers (Raycast extension,
+ * CLI, third-party integrations). Keep in sync with hub-protocol-rest.ts
+ * response shapes in synap-backend.
+ *
+ * Zero runtime dependencies — pure TypeScript interfaces.
+ */
+interface HubEntity {
+    id: string;
+    title: string;
+    profileSlug: string;
+    workspaceId: string | null;
+    /** JSONB property bag — keys depend on the profile schema */
+    properties: Record<string, unknown>;
+    createdAt: string;
+    updatedAt: string;
+    status?: string;
+    priority?: string;
+    dueDate?: string;
+    content?: string;
+    url?: string;
+}
+interface HubDocument {
+    id: string;
+    title: string;
+    content: string;
+    workspaceId: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface HubChannel {
+    id: string;
+    name: string;
+    type: "personal" | "thread" | "sub_thread" | "feed" | "external" | "agent_collab";
+    workspaceId: string | null;
+    agentType?: string;
+    contextObjectType?: "workspace" | "entity" | "document" | "view" | "project" | "task" | "user" | "external" | null;
+    contextObjectId?: string | null;
+    createdAt: string;
+}
+interface HubWorkspace {
+    id: string;
+    name: string;
+    role?: string;
+}
+/** GET /api/hub/workspaces — canonical Hub Protocol shape (not `data`). */
+interface HubWorkspacesListResponse {
+    workspaces: HubWorkspace[];
+}
+/** GET /api/hub/users/me returns at least `id` (and `scopes`); email may be omitted. */
+interface HubUser {
+    id: string;
+    email?: string;
+    name?: string;
+    scopes?: string[];
+}
+interface HubMemoryResult {
+    id: string;
+    content: string;
+    score?: number;
+    createdAt: string;
+}
+interface HubListResponse<T> {
+    data: T[];
+    total?: number;
+    hasMore?: boolean;
+}
+interface HubSingleResponse<T> {
+    data: T;
+}
+interface CreateEntityInput {
+    profileSlug: string;
+    title: string;
+    workspaceId?: string;
+    properties?: Record<string, unknown>;
+    content?: string;
+    url?: string;
+    status?: string;
+    priority?: "low" | "medium" | "high" | "urgent";
+    dueDate?: string;
+}
+interface UpdateEntityInput {
+    title?: string;
+    properties?: Record<string, unknown>;
+    content?: string;
+    url?: string;
+    status?: string;
+    priority?: "low" | "medium" | "high" | "urgent";
+    dueDate?: string;
+}
+interface CreateDocumentInput {
+    title: string;
+    content?: string;
+    workspaceId?: string;
+    entityId?: string;
+}
+interface StoreMemoryInput {
+    fact: string;
+    context?: string;
+    workspaceId?: string;
+}
+interface SendToChannelInput {
+    channelId: string;
+    content: string;
+    /** Defaults to the authenticated user (GET /users/me). */
+    userId?: string;
+    role?: "system" | "assistant" | "user";
+    /** When true, may queue an IS response on AI-active threads (server-side). */
+    autoRespond?: boolean;
+    workspaceId?: string;
+}
+interface AgentSetupResult {
+    hubApiKey: string;
+    agentUserId: string;
+    workspaceId: string;
+}
+interface PodStatus {
+    url: string;
+    healthy: boolean;
+    version?: string;
+}
+interface CaptureProposal {
+    tempId: string;
+    profileSlug: string;
+    title: string;
+    description?: string;
+    properties?: Record<string, unknown>;
+    confidence: number;
+    action: "create" | "link" | "dismiss";
+    linkedEntityId?: string;
+    linkedEntityTitle?: string;
+    dedupCandidates?: Array<{
+        entityId: string;
+        title: string;
+        profileSlug: string;
+        score: number;
+    }>;
+}
+interface CaptureRelation {
+    sourceTempId: string;
+    targetTempId: string;
+    relationType: string;
+}
+interface CaptureStructureResponse {
+    proposals: CaptureProposal[];
+    relations: CaptureRelation[];
+    followUp: string | null;
+    dedupCandidates?: Record<string, Array<{
+        entityId: string;
+        title: string;
+        score: number;
+    }>>;
+}
+interface CaptureExecuteInput {
+    entities: Array<{
+        tempId: string;
+        profileSlug: string;
+        title: string;
+        description?: string;
+        properties?: Record<string, unknown>;
+        action: "create" | "link" | "dismiss";
+        linkedEntityId?: string;
+        confidence?: number;
+    }>;
+    relations?: CaptureRelation[];
+}
+interface CaptureExecuteResponse {
+    created: Array<{
+        tempId: string;
+        entityId: string;
+        profileSlug: string;
+        linked: boolean;
+    }>;
+    relations: Array<{
+        sourceTempId: string;
+        targetTempId: string;
+        relationType: string;
+    }>;
+}
+interface HubRelation {
+    id: string;
+    sourceEntityId: string;
+    targetEntityId: string;
+    type: string;
+    label?: string;
+    createdAt: string;
+}
+interface HubGraphNode extends HubEntity {
+    depth: number;
+}
+interface HubGraphEdge {
+    sourceId: string;
+    targetId: string;
+    type: string;
+    label?: string;
+}
+interface HubGraphResult {
+    nodes: HubGraphNode[];
+    edges: HubGraphEdge[];
+}
+/**
+ * A single link returned by getConnections() — unified view across three sources:
+ *  - `"graph"` : an explicit row in the relations table
+ *  - `"property"` : derived from another entity's `entity_id` property pointing here
+ *  - `"thread"` : a chat thread created, updated, or referenced this entity
+ */
+interface HubConnection {
+    entityId: string;
+    entity: HubEntity | null;
+    label: string;
+    direction: "outgoing" | "incoming" | "structural";
+    source: "graph" | "property" | "thread";
+    relationType?: string;
+    propertySlug?: string;
+    propertyLabel?: string;
+    channelId?: string;
+    channelRelationshipType?: string;
+    createdAt?: string | null;
+}
+interface HubConnectionsResult {
+    connections: HubConnection[];
+    counts: {
+        total: number;
+        graph: number;
+        structural: number;
+        threads: number;
+    };
+}
+interface HubProfile {
+    id: string;
+    slug: string;
+    displayName: string;
+    description?: string;
+    entityScope: "pod" | "workspace";
+    parentSlug?: string;
+    icon?: string;
+    color?: string;
+    properties?: HubPropertyDef[];
+}
+interface HubPropertyDef {
+    id: string;
+    slug: string;
+    displayName: string;
+    type: "string" | "number" | "boolean" | "date" | "entity_id" | "array" | "object" | "secret";
+    required?: boolean;
+    options?: string[];
+}
+interface HubDiscoverProperty {
+    slug: string;
+    displayName: string;
+    type: string;
+    options?: string[];
+    required?: boolean;
+}
+interface HubDiscoverProfile {
+    slug: string;
+    displayName: string;
+    scope: "pod" | "workspace";
+    description?: string | null;
+    icon?: string | null;
+    properties: HubDiscoverProperty[];
+    createCommand: string;
+}
+interface HubDiscoverResult {
+    profiles: HubDiscoverProfile[];
+    commands: Record<string, string>;
+    hint: string;
+}
+interface HubThread {
+    id: string;
+    name?: string;
+    type: "personal" | "thread" | "sub_thread" | "feed" | "external" | "agent_collab";
+    workspaceId?: string;
+    agentType?: string;
+    contextObjectType?: "workspace" | "entity" | "document" | "view" | "project" | "task" | "user" | "external";
+    contextObjectId?: string;
+    parentChannelId?: string;
+    linkedEntityIds?: string[];
+    linkedDocumentIds?: string[];
+    createdAt: string;
+    updatedAt: string;
+}
+interface HubMessage {
+    id: string;
+    content: string;
+    role: "user" | "assistant" | "system";
+    userId?: string;
+    createdAt: string;
+}
+interface HubThreadContext {
+    thread: HubThread;
+    messages: HubMessage[];
+    linkedEntities: HubEntity[];
+    linkedDocuments: HubDocument[];
+}
+interface HubProposal {
+    id: string;
+    status: "pending" | "approved" | "rejected";
+    action: "create" | "update" | "delete";
+    subjectType: string;
+    data: Record<string, unknown>;
+    reason?: string;
+    createdAt: string;
+    reviewedAt?: string;
+}
+interface HubView {
+    id: string;
+    name: string;
+    type: "table" | "kanban" | "list" | "grid" | "gallery" | "calendar" | "timeline" | "graph" | "bento" | string;
+    profileSlug?: string;
+    workspaceId?: string;
+    config?: Record<string, unknown>;
+    createdAt: string;
+    updatedAt: string;
+}
+interface HubSearchResult {
+    entities: HubEntity[];
+    documents: HubDocument[];
+    total: number;
+}
+interface HubCommand {
+    id: string;
+    name: string;
+    slug: string;
+    description?: string;
+    workspaceId?: string;
+}
+interface HubAgentUser {
+    id: string;
+    name: string;
+    agentType?: string;
+    workspaceId?: string;
+}
+interface HubUserContext {
+    recentEntities: HubEntity[];
+    activeThreads: HubThread[];
+    workspaceSummary?: Record<string, unknown>;
+}
+interface HubGovernanceResult {
+    status: "approved" | "proposed" | "denied";
+    id?: string;
+    proposalId?: string;
+    reason?: string;
+    message?: string;
+    /**
+     * Short human-readable summary of what was proposed. Present on `proposed`
+     * responses. Example: `Delete task "Q2 plan review"`.
+     */
+    summary?: string;
+    /**
+     * Reasoning — echoed from the AI's rationale or the policy's explanation
+     * of why review is needed. Present on `proposed` responses.
+     */
+    reasoning?: string;
+    /**
+     * Pod-relative path for the review UI: `/proposals/{id}`.
+     * Present on `proposed` responses.
+     */
+    reviewPath?: string;
+    /**
+     * Absolute URL for the review UI (defaults to `studio.synap.live`,
+     * overridable via `SYNAP_APP_URL` on the pod). Surface this directly to
+     * the user so they can approve without digging through the app.
+     */
+    reviewUrl?: string;
+}
+interface CreateThreadInput {
+    name?: string;
+    type?: HubThread["type"];
+    workspaceId?: string;
+    agentType?: string;
+    entityId?: string;
+    documentId?: string;
+    userId?: string;
+}
+interface CreateRelationInput {
+    sourceEntityId: string;
+    targetEntityId: string;
+    type: string;
+    label?: string;
+    workspaceId?: string;
+    userId?: string;
+}
+interface CreateViewInput {
+    name: string;
+    type: HubView["type"];
+    profileSlug?: string;
+    workspaceId: string;
+    config?: Record<string, unknown>;
+    userId?: string;
+}
+interface ExecuteCommandInput {
+    slug: string;
+    workspaceId?: string;
+    parameters?: Record<string, unknown>;
+    userId?: string;
+}
+type AutomationStatus = "draft" | "active" | "paused" | "error";
+type AutomationTriggerType = "event" | "cron" | "webhook" | "manual";
+interface HubAutomation {
+    id: string;
+    userId: string;
+    workspaceId?: string | null;
+    name: string;
+    description?: string | null;
+    triggerType: AutomationTriggerType;
+    triggerConfig?: Record<string, unknown>;
+    flowDefinition?: {
+        nodes: Record<string, unknown>[];
+        edges: Record<string, unknown>[];
+    };
+    status: AutomationStatus;
+    metadata?: Record<string, unknown>;
+    createdAt?: string;
+    updatedAt?: string;
+}
+interface CreateAutomationInput {
+    name: string;
+    triggerType: AutomationTriggerType;
+    workspaceId?: string | null;
+    description?: string;
+    triggerConfig?: Record<string, unknown>;
+    flowDefinition?: {
+        nodes: Record<string, unknown>[];
+        edges: Record<string, unknown>[];
+    };
+    status?: AutomationStatus;
+    metadata?: Record<string, unknown>;
+    userId?: string;
+    agentUserId?: string;
+}
+interface UpdateAutomationInput {
+    name?: string;
+    description?: string;
+    triggerType?: AutomationTriggerType;
+    triggerConfig?: Record<string, unknown>;
+    flowDefinition?: {
+        nodes: Record<string, unknown>[];
+        edges: Record<string, unknown>[];
+    };
+    status?: AutomationStatus;
+    metadata?: Record<string, unknown>;
+    workspaceId?: string;
+    userId?: string;
+}
+type ReactionKind = "automation" | "ai_feed" | "ai_react" | "notify" | "webhook" | "message_out";
+type ReactionLens = "all" | "internal" | "external";
+/** Opaque reaction event from the Pulse feed — shape varies by kind. */
+interface HubReactionEvent {
+    id: string;
+    eventType: string;
+    kind?: ReactionKind;
+    workspaceId?: string | null;
+    userId?: string;
+    createdAt: string;
+    reactions?: Record<string, unknown>[];
+    [key: string]: unknown;
+}
+type NotificationSourceType = "proposal" | "connector" | "agent" | "system" | "inbox_item";
+interface CreateNotificationInput {
+    userId: string;
+    workspaceId: string;
+    type: string;
+    sourceType?: NotificationSourceType;
+    sourceId?: string;
+    workspaceUrl?: string;
+    groupKey?: string;
+    data?: Record<string, unknown>;
+}
+interface HubWebhookDelivery {
+    id: string;
+    subscriptionId: string;
+    status: string;
+    responseStatus?: number;
+    attempt: number;
+    deliveredAt?: string;
+    createdAt: string;
+}
+
+/**
+ * HubRestClient — typed HTTP client for the Synap Hub Protocol REST API.
+ *
+ * Uses the native `fetch` API (Node.js >= 18, browsers, Deno, Bun).
+ * Zero runtime dependencies.
+ *
+ * @example
+ * ```ts
+ * const client = new HubRestClient({
+ *   podUrl: "https://my-pod.synap.live",
+ *   apiKey: "synap_hub_live_...",
+ * });
+ *
+ * const entities = await client.searchEntities("meeting notes", { profileSlug: "note" });
+ * ```
+ */
+
+interface HubRestClientConfig {
+    /** Pod URL, e.g. https://my-pod.synap.live */
+    podUrl: string;
+    /** Hub Protocol API key (Bearer token) */
+    apiKey: string;
+    /** Default workspace ID — used when not specified per call */
+    workspaceId?: string;
+    /** Optional request timeout in ms (default: 30000) */
+    timeoutMs?: number;
+}
+declare class HubRestClient {
+    private readonly base;
+    private readonly headers;
+    private readonly timeoutMs;
+    readonly workspaceId: string | undefined;
+    /** Cached from GET /users/me — avoids repeated identity calls. */
+    private resolvedUserId;
+    constructor(config: HubRestClientConfig);
+    /** User id for the current API key (Hub REST requires userId on several GETs). */
+    private resolveUserId;
+    private request;
+    getMe(): Promise<HubUser>;
+    getWorkspaces(): Promise<HubWorkspace[]>;
+    provisionAgentWorkspace(input: {
+        agentUserId: string;
+        workspaceName?: string;
+    }): Promise<{
+        workspaceId: string;
+        created: boolean;
+    }>;
+    /**
+     * 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.
+     */
+    getUserContext(userId: string, options?: {
+        workspaceId?: string;
+    }): Promise<HubUserContext>;
+    searchEntities(query: string, options?: {
+        profileSlug?: string;
+        workspaceId?: string;
+        /**
+         * "workspace" (default) — applies the client workspaceId filter.
+         * "all" — omits workspaceId entirely so results span all workspaces.
+         */
+        scope?: "workspace" | "all";
+        limit?: number;
+    }, signal?: AbortSignal): Promise<HubEntity[]>;
+    getEntity(id: string): Promise<HubEntity>;
+    getRecentEntities(options?: {
+        profileSlug?: string;
+        workspaceId?: string;
+        limit?: number;
+        /** "all" — omits workspaceId so results span all workspaces the user can access. */
+        scope?: "workspace" | "all";
+    }): Promise<HubEntity[]>;
+    createEntity(input: CreateEntityInput): Promise<HubGovernanceResult>;
+    updateEntity(id: string, input: UpdateEntityInput): Promise<HubEntity | HubGovernanceResult>;
+    /**
+     * 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.
+     */
+    search(query: string, options?: {
+        collections?: Array<"entities" | "documents" | "views">;
+        workspaceId?: string;
+        limit?: number;
+    }, signal?: AbortSignal): Promise<HubSearchResult>;
+    /**
+     * 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.
+     */
+    getRelations(entityId: string, options?: {
+        workspaceId?: string;
+    }): Promise<HubRelation[]>;
+    /**
+     * 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".
+     */
+    createRelation(input: CreateRelationInput): Promise<HubGovernanceResult>;
+    /**
+     * Delete a relation by ID (get from getRelations()).
+     */
+    deleteRelation(relationId: string): Promise<void>;
+    /**
+     * 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");
+     */
+    traverseGraph(entityId: string, options?: {
+        maxDepth?: number;
+        workspaceId?: string;
+    }): Promise<HubGraphResult>;
+    /**
+     * 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");
+     */
+    getConnections(entityId: string, options?: {
+        workspaceId?: string;
+        limit?: number;
+    }): Promise<HubConnectionsResult>;
+    /**
+     * 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.
+     */
+    listProfiles(workspaceId: string): Promise<HubProfile[]>;
+    /**
+     * List property definitions for a workspace, optionally filtered by profile.
+     */
+    listPropertyDefs(workspaceId: string, options?: {
+        profileSlug?: string;
+    }): Promise<HubPropertyDef[]>;
+    /**
+     * 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.
+     */
+    discover(workspaceId?: string): Promise<HubDiscoverResult>;
+    /**
+     * List threads (channels) accessible to a user.
+     */
+    listThreads(userId: string, options?: {
+        workspaceId?: string;
+        type?: string;
+    }): Promise<HubThread[]>;
+    /**
+     * 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.
+     */
+    getPersonalChannel(userId: string, workspaceId?: string): Promise<HubThread>;
+    /**
+     * Create a new thread. Pass entityId to auto-link on creation.
+     *
+     * Note: The backend POST /threads requires workspaceId in the body.
+     */
+    createThread(input: CreateThreadInput): Promise<HubThread>;
+    /**
+     * Get full thread context: messages + all linked entities and documents.
+     * Call before sending a message to orient the AI with conversation history.
+     */
+    getThreadContext(threadId: string): Promise<HubThreadContext>;
+    /**
+     * Get messages in a thread.
+     */
+    getMessages(threadId: string, _options?: {
+        limit?: number;
+        before?: string;
+    }): Promise<HubMessage[]>;
+    /**
+     * Link an entity to a thread so it appears in thread context for AI.
+     */
+    linkEntityToThread(threadId: string, entityId: string): Promise<void>;
+    /**
+     * Link a document to a thread.
+     */
+    linkDocumentToThread(threadId: string, documentId: string): Promise<void>;
+    /**
+     * Get research branches of a thread — parallel AI investigations.
+     */
+    getThreadBranches(threadId: string): Promise<Array<{
+        channelId: string;
+        branchPurpose: string | null;
+        status: string;
+    }>>;
+    storeMemory(input: StoreMemoryInput): Promise<{
+        id: string;
+    }>;
+    recallMemory(query: string, options?: {
+        workspaceId?: string;
+        limit?: number;
+    }): Promise<HubMemoryResult[]>;
+    /**
+     * Delete a stored memory fact by ID.
+     */
+    deleteMemory(memoryId: string): Promise<void>;
+    getChannels(options?: {
+        workspaceId?: string;
+    }): Promise<HubChannel[]>;
+    sendToChannel(input: SendToChannelInput): Promise<{
+        id: string;
+    }>;
+    /**
+     * List proposals — pending AI writes awaiting human review.
+     * Filter by status: "pending" (needs review), "approved", "rejected".
+     */
+    listProposals(options?: {
+        status?: "pending" | "approved" | "rejected";
+        workspaceId?: string;
+        limit?: number;
+    }): Promise<HubProposal[]>;
+    /**
+     * 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.
+     */
+    reviewProposal(proposalId: string, decision: "approved" | "rejected", reason?: string): Promise<HubProposal>;
+    /**
+     * List data views in a workspace.
+     */
+    listViews(workspaceId: string, options?: {
+        profileSlug?: string;
+    }): Promise<HubView[]>;
+    /**
+     * Create a new view. Goes through governance.
+     */
+    createView(input: CreateViewInput): Promise<HubGovernanceResult>;
+    /**
+     * Get a document by ID with full markdown content.
+     */
+    getDocument(documentId: string): Promise<HubDocument>;
+    /**
+     * Create a document. Use for long-form content: meeting notes, research, writeups.
+     * Goes through governance.
+     */
+    createDocument(input: CreateDocumentInput & {
+        workspaceId?: string;
+    }): Promise<HubGovernanceResult>;
+    /**
+     * List available commands (automation shortcuts) in the workspace.
+     */
+    listCommands(workspaceId?: string): Promise<HubCommand[]>;
+    /**
+     * 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`.
+     */
+    executeCommand(input: ExecuteCommandInput): Promise<{
+        status: string;
+        result?: unknown;
+    }>;
+    /**
+     * List agent users provisioned in the workspace.
+     */
+    listAgentUsers(workspaceId?: string): Promise<HubAgentUser[]>;
+    /**
+     * 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.
+     */
+    postProactive(userId: string, content: string, options?: {
+        workspaceId?: string;
+        type?: string;
+    }): Promise<{
+        id: string;
+    }>;
+    captureStructure(input: {
+        text: string;
+        url?: string;
+        workspaceId?: string;
+        previousEntities?: CaptureProposal[];
+    }): Promise<CaptureStructureResponse>;
+    captureExecute(input: CaptureExecuteInput & {
+        workspaceId?: string;
+    }): Promise<CaptureExecuteResponse>;
+    /**
+     * List automations for the current user, optionally filtered by workspace and status.
+     */
+    listAutomations(options?: {
+        workspaceId?: string;
+        status?: AutomationStatus;
+        limit?: number;
+    }): Promise<HubAutomation[]>;
+    /**
+     * Get a single automation by ID.
+     */
+    getAutomation(automationId: string, options?: {
+        workspaceId?: string;
+    }): Promise<HubAutomation>;
+    /**
+     * Create an automation. Defaults to status=draft.
+     * Use activateAutomation() to enable it.
+     */
+    createAutomation(input: CreateAutomationInput): Promise<HubAutomation>;
+    /**
+     * Update an automation's definition or metadata.
+     */
+    updateAutomation(automationId: string, input: UpdateAutomationInput): Promise<HubAutomation>;
+    /**
+     * Manually trigger an automation once with an optional payload.
+     * Bypasses the automation's normal trigger config.
+     */
+    triggerAutomation(automationId: string, options?: {
+        payload?: Record<string, unknown>;
+        workspaceId?: string;
+    }): Promise<{
+        status: string;
+        runId?: string;
+        result?: unknown;
+    }>;
+    /**
+     * Activate a draft or paused automation (sets status=active).
+     */
+    activateAutomation(automationId: string, options?: {
+        workspaceId?: string;
+    }): Promise<HubAutomation>;
+    /**
+     * Pause an active automation (sets status=paused).
+     */
+    pauseAutomation(automationId: string, options?: {
+        workspaceId?: string;
+    }): Promise<HubAutomation>;
+    /**
+     * List the user-wide Pulse feed — the timestamp-sorted union of reactive events.
+     * Call getSubscriptionFanout() on an individual event for its dense reactions[].
+     */
+    listSubscriptions(options?: {
+        workspaceId?: string;
+        kind?: ReactionKind;
+        eventType?: string;
+        lens?: ReactionLens;
+        limit?: number;
+    }): Promise<HubReactionEvent[]>;
+    /**
+     * Get the reaction fan-out for a single event — full reactions[] populated.
+     */
+    getSubscriptionFanout(eventId: string, options?: {
+        lens?: ReactionLens;
+    }): Promise<HubReactionEvent>;
+    /**
+     * 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.
+     */
+    createNotification(input: CreateNotificationInput): Promise<{
+        id: string;
+    }>;
+    /**
+     * List delivery log for a webhook subscription.
+     * Powers the Reactions Health tab and replay flows.
+     */
+    getWebhookDeliveries(subscriptionId: string, options?: {
+        limit?: number;
+    }): Promise<HubWebhookDelivery[]>;
+}
+
+/**
+ * Hub Protocol REST API error class.
+ * Thrown when the server returns a non-2xx response.
+ */
+declare class HubApiError extends Error {
+    readonly statusCode: number;
+    readonly body?: unknown | undefined;
+    constructor(message: string, statusCode: number, body?: unknown | undefined);
+    get isUnauthorized(): boolean;
+    get isForbidden(): boolean;
+    get isNotFound(): boolean;
+    get isServerError(): boolean;
+}
+
+/**
+ * Pod setup and health utilities.
+ *
+ * These functions are the canonical implementations shared between
+ * the Synap CLI and the Raycast extension. They use the native fetch API
+ * and have zero Node.js-specific dependencies.
+ */
+
+/**
+ * Check whether a Synap pod is healthy.
+ * Hits `GET {podUrl}/health` with a 5s timeout.
+ */
+declare function checkPodHealth(podUrl: string): Promise<PodStatus>;
+/**
+ * Create an agent user + Hub Protocol API key on the pod.
+ *
+ * Auth: `Authorization: Bearer <provisioningToken>`
+ * The provisioning token is either:
+ *   - The pod's `PROVISIONING_TOKEN` env var (self-hosted path)
+ *   - A CP-signed `agent_setup` JWT (managed pod path)
+ *
+ * Endpoint: `POST {podUrl}/api/hub/setup/agent`
+ */
+declare function setupAgent(podUrl: string, provisioningToken: string, agentType?: string): Promise<AgentSetupResult>;
+
+export { type AgentSetupResult, type CaptureExecuteInput, type CaptureExecuteResponse, type CaptureProposal, type CaptureRelation, type CaptureStructureResponse, type CreateDocumentInput, type CreateEntityInput, type CreateRelationInput, type CreateThreadInput, type CreateViewInput, type ExecuteCommandInput, type HubAgentUser, HubApiError, type HubChannel, type HubCommand, type HubConnection, type HubConnectionsResult, type HubDiscoverProfile, type HubDiscoverProperty, type HubDiscoverResult, type HubDocument, type HubEntity, type HubGovernanceResult, type HubGraphEdge, type HubGraphNode, type HubGraphResult, type HubListResponse, type HubMemoryResult, type HubMessage, type HubProfile, type HubPropertyDef, type HubProposal, type HubRelation, HubRestClient, type HubRestClientConfig, type HubSearchResult, type HubSingleResponse, type HubThread, type HubThreadContext, type HubUser, type HubUserContext, type HubView, type HubWorkspace, type HubWorkspacesListResponse, type PodStatus, type SendToChannelInput, type StoreMemoryInput, type UpdateEntityInput, checkPodHealth, setupAgent };