@synap-core/cli 1.8.0 → 1.11.0

package/dist/lib/hub-client.d.ts

@@ -1,10 +1,86 @@
 import { HubRestClient } from "@synap/hub-rest-client";
+/**
+ * A failed Hub call, carrying the structured facts callers need to branch on.
+ *
+ * `message` is HUMAN-READABLE and is what the many `log.error((err as Error).message)`
+ * sites print. It keeps a literal `(HTTP <status>)` token: several call sites
+ * classify errors by matching that substring, and the token is the contract they
+ * depend on. The raw response body is kept on `rawBody` and never spliced into
+ * `message` — a JSON blob truncated mid-object is unreadable and leaks internals.
+ */
+export declare class HubError extends Error {
+    readonly status: number;
+    readonly code?: string;
+    readonly reason?: string;
+    readonly body?: unknown;
+    readonly rawBody: string;
+    readonly path: string;
+    readonly method: string;
+    /** Origin of the pod this call actually hit — for cross-pod diagnostics. */
+    readonly podUrl?: string;
+    /** Workspace this call actually sent — for cross-pod 403 diagnostics. */
+    readonly workspaceId?: string;
+    constructor(init: {
+        message: string;
+        status: number;
+        code?: string;
+        reason?: string;
+        body?: unknown;
+        rawBody: string;
+        path: string;
+        method: string;
+        podUrl?: string;
+        workspaceId?: string;
+    });
+}
+/**
+ * A Hub call that never reached the pod — DNS, TCP, TLS or timeout.
+ *
+ * Peer of {@link HubError}: same rendering path, same `message`-is-human-readable
+ * rule. It deliberately carries NO `(HTTP <status>)` token — there was no HTTP
+ * response, and the call sites that classify on that substring must not match.
+ * `podUrl` is the origin we failed to reach and `hint` is the next action.
+ */
+export declare class HubNetworkError extends Error {
+    /** Transport code we classified on: ENOTFOUND, ECONNREFUSED, TIMEOUT, TLS… */
+    readonly code: string;
+    readonly podUrl: string;
+    readonly path: string;
+    readonly method: string;
+    /** The one thing the user should do next. Rendered under the message. */
+    readonly hint: string;
+    constructor(init: {
+        message: string;
+        code: string;
+        podUrl: string;
+        path: string;
+        method: string;
+        hint: string;
+        cause?: unknown;
+    });
+}
+/**
+ * Append a one-line "need help?" footer with a clickable Discord invite. Prints
+ * to stderr (same stream as the error it follows, so `2>/dev/null` hides both)
+ * and only once per process. The invite is an OSC-8 hyperlink on an interactive
+ * terminal, a plain URL when the stream is redirected/piped.
+ */
+export declare function discordHelpLine(): void;
+/**
+ * Print a failed Hub call: its humanized message plus a hint for the classes
+ * where the cause is not obvious from the message alone. Lives here rather than
+ * in utils/logger so the logger stays domain-agnostic and the taxonomy and its
+ * presentation sit in one file. Always closes with the one-time Discord footer.
+ */
+export declare function renderHubError(err: unknown): void;
 export interface HubConfig {
     podUrl: string;
     apiKey: string;
     userId: string;
     /** Active workspace — from `synap use`, pod default, or env var. Undefined if none configured. */
     workspaceId?: string;
+    /** Active project — from `synap project use`, pod default, or env var. Peer of workspaceId; independent. */
+    projectId?: string;
     scopes?: string[];
 }
 export declare function resolveUserId(cfg: HubConfig): Promise<string>;
@@ -20,8 +96,22 @@ export declare function writeActiveSessionId(sessionId: string): void;
 /** Detach the active session from this terminal — removes .synap-session. */
 export declare function clearActiveSessionId(): void;
 export declare function hubGet(path: string, params: Record<string, string | number | undefined>, cfg: HubConfig): Promise<unknown>;
-export declare function hubPost(path: string, body: unknown, cfg: HubConfig): Promise<unknown>;
+export declare function hubPost(path: string, body: unknown, cfg: HubConfig, timeoutMs?: number): Promise<unknown>;
+/**
+ * Multipart POST for Hub doors that accept file uploads (e.g. source-file).
+ * Do NOT set Content-Type — fetch sets the boundary for FormData.
+ *
+ * Note: on 429 retry we cannot re-use a consumed FormData body in all runtimes.
+ * Callers that hit 429 mid-bulk should rebuild FormData — see hubPostMultipartRetryable.
+ */
+export declare function hubPostMultipart(path: string, form: FormData, cfg: HubConfig, timeoutMs?: number): Promise<unknown>;
+/**
+ * Multipart POST that rebuilds the body on each 429 retry (FormData streams
+ * can only be read once).
+ */
+export declare function hubPostMultipartRetryable(path: string, buildForm: () => FormData, cfg: HubConfig, timeoutMs?: number): Promise<unknown>;
 export declare function hubPatch(path: string, body: unknown, cfg: HubConfig): Promise<unknown>;
+export declare function hubDelete(path: string, cfg: HubConfig): Promise<unknown>;
 /**
  * Create a typed HubRestClient from a resolved HubConfig.
  * Use this in new code and shared surfaces (e.g. Raycast) to get full