@neta-art/cohub 1.0.0 → 1.2.0

package/README.md

@@ -13,6 +13,39 @@ npm install @neta-art/cohub @neta-art/cohub-protocol
 ```ts
 import { createCohubClient } from "@neta-art/cohub";
 
+const client = createCohubClient({
+  getAccessToken: async () => localStorage.getItem("token"),
+});
+```
+
+The SDK connects to production by default:
+
+- API: `https://api.cohub.run`
+- WebSocket: `wss://gateway.cohub.run/ws`
+
+Use development with `ENV=dev` in Node.js:
+
+```bash
+ENV=dev node app.js
+```
+
+Or select it explicitly in code:
+
+```ts
+const client = createCohubClient({
+  env: "dev",
+  getAccessToken: async () => localStorage.getItem("token"),
+});
+```
+
+Development uses:
+
+- API: `https://api-dev.cohub.run`
+- WebSocket: `wss://gateway-dev.cohub.run/ws`
+
+Custom endpoints are still supported when needed:
+
+```ts
 const client = createCohubClient({
   baseUrl: "https://api.example.com",
   getAccessToken: async () => localStorage.getItem("token"),
@@ -87,7 +120,6 @@ If you only want HTTP transport, use the dedicated entry:
 import { createHttpClient } from "@neta-art/cohub/http";
 
 const http = createHttpClient({
-  baseUrl: "https://api.example.com",
   getAccessToken: async () => localStorage.getItem("token"),
 });
 
@@ -104,7 +136,6 @@ If you need direct realtime transport access, use the websocket entry:
 import { createWebsocketClient } from "@neta-art/cohub/websocket";
 
 const ws = createWebsocketClient({
-  url: "https://gateway.example.com",
   getAccessToken: async () => localStorage.getItem("token"),
 });
 
@@ -118,15 +149,4 @@ This SDK is intentionally built around Cohub's co-creation model:
 - work with `space(...)` and `session(...)` as the primary creative surface
 - send messages through `session.messages.send(...)`
 - subscribe through `space.subscribe(...)` and `session.subscribe(...)`
-- keep protocol details behind the SDK surface
-
-## Publish checklist
-
-Before publishing:
-
-1. build the protocol package: `pnpm --filter @neta-art/cohub-protocol build`
-2. build this package: `pnpm --filter @neta-art/cohub build`
-3. typecheck the protocol package: `pnpm --filter @neta-art/cohub-protocol typecheck`
-4. typecheck this package: `pnpm --filter @neta-art/cohub typecheck`
-5. verify consuming apps still typecheck
-6. verify `dist/` contains `index`, `http`, and `websocket` outputs
+- keep HTTP and realtime transports separate but coordinated

package/dist/apis/invitations.d.ts

@@ -0,0 +1,20 @@
+import type { HttpTransport } from "../transport.js";
+import type { SpaceInvitation, CreateInvitationInput, CreateInvitationResponse, InvitationDetail, AcceptInvitationResponse } from "../types.js";
+export declare class SpaceInvitationsApi {
+    private readonly transport;
+    private readonly spaceId;
+    constructor(transport: HttpTransport, spaceId: string);
+    list(): Promise<{
+        items: SpaceInvitation[];
+    }>;
+    create(input?: CreateInvitationInput): Promise<CreateInvitationResponse>;
+    revoke(token: string): Promise<{
+        ok: true;
+    }>;
+}
+export declare class PublicInviteApi {
+    private readonly transport;
+    constructor(transport: HttpTransport);
+    get(token: string): Promise<InvitationDetail>;
+    accept(token: string): Promise<AcceptInvitationResponse>;
+}

package/dist/apis/invitations.js

@@ -0,0 +1,36 @@
+export class SpaceInvitationsApi {
+    transport;
+    spaceId;
+    constructor(transport, spaceId) {
+        this.transport = transport;
+        this.spaceId = spaceId;
+    }
+    list() {
+        return this.transport.request(`/api/spaces/${this.spaceId}/invitations`);
+    }
+    create(input) {
+        return this.transport.request(`/api/spaces/${this.spaceId}/invitations`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(input ?? {}),
+        });
+    }
+    revoke(token) {
+        return this.transport.request(`/api/spaces/${this.spaceId}/invitations/${token}`, { method: "DELETE" });
+    }
+}
+// Public invite API (no auth required for viewing)
+export class PublicInviteApi {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    get(token) {
+        return this.transport.request(`/api/invite/${token}`);
+    }
+    accept(token) {
+        return this.transport.request(`/api/invite/${token}/accept`, {
+            method: "POST",
+        });
+    }
+}

package/dist/apis/models.d.ts

@@ -1,8 +1,7 @@
-import type { Fetch } from "../transport.js";
+import type { HttpTransport } from "../transport.js";
 import type { ModelCatalogEntry } from "../types.js";
 export declare class ModelsApi {
-    private readonly fetcher;
-    private readonly baseUrl;
-    constructor(fetcher: Fetch, baseUrl: string);
-    list(customFetch?: Fetch): Promise<Record<string, ModelCatalogEntry[]>>;
+    private readonly transport;
+    constructor(transport: HttpTransport);
+    list(): Promise<Record<string, ModelCatalogEntry[]>>;
 }

package/dist/apis/models.js

@@ -1,17 +1,9 @@
 export class ModelsApi {
-    fetcher;
-    baseUrl;
-    constructor(fetcher, baseUrl) {
-        this.fetcher = fetcher;
-        this.baseUrl = baseUrl;
+    transport;
+    constructor(transport) {
+        this.transport = transport;
     }
-    async list(customFetch) {
-        const fetchImpl = customFetch ?? this.fetcher;
-        const url = this.baseUrl ? `${this.baseUrl}/api/models` : "/api/models";
-        const response = await fetchImpl(url);
-        if (!response.ok) {
-            throw new Error(`Failed to fetch models: ${response.status} ${response.statusText}`);
-        }
-        return response.json();
+    async list() {
+        return this.transport.request("/api/models");
     }
 }

package/dist/apis/prompts.d.ts

@@ -0,0 +1,10 @@
+import type { Fetch } from "../transport.js";
+import type { PromptTemplateCatalogResponse } from "../types.js";
+export declare class PromptsApi {
+    private readonly fetcher;
+    private readonly baseUrl;
+    constructor(fetcher: Fetch, baseUrl: string);
+    list(options?: {
+        spaceId?: string;
+    }, customFetch?: Fetch): Promise<PromptTemplateCatalogResponse>;
+}

package/dist/apis/prompts.js

@@ -0,0 +1,22 @@
+export class PromptsApi {
+    fetcher;
+    baseUrl;
+    constructor(fetcher, baseUrl) {
+        this.fetcher = fetcher;
+        this.baseUrl = baseUrl;
+    }
+    async list(options, customFetch) {
+        const fetchImpl = customFetch ?? this.fetcher;
+        const params = new URLSearchParams();
+        if (options?.spaceId)
+            params.set("spaceId", options.spaceId);
+        const query = params.toString();
+        const base = this.baseUrl ? `${this.baseUrl}/api/prompts` : "/api/prompts";
+        const url = query ? `${base}?${query}` : base;
+        const response = await fetchImpl(url);
+        if (!response.ok) {
+            throw new Error(`Failed to fetch prompt templates: ${response.status} ${response.statusText}`);
+        }
+        return response.json();
+    }
+}

package/dist/apis/session-access.js

@@ -8,7 +8,7 @@ export class SessionAccessApi {
     }
     set(sessionId, body) {
         return this.transport.request(`/api/sessions/${sessionId}/access`, {
-            method: "PUT",
+            method: "PATCH",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify(body),
         });

package/dist/apis/spaces.d.ts

@@ -1,6 +1,7 @@
 import type { WebsocketClient, WebsocketEventPayload } from "../websocket.js";
 import type { HttpTransport, Fetch } from "../transport.js";
-import type { CheckpointRecord, ContentBlock, SessionMessagesPaginatedResponse, SessionMessagesResponse, SessionRecord, SpaceAccessPolicy, SpaceBootstrapSource, SpaceChannelBindingInput, SpaceCheckpointDetailResponse, SpaceCreateResponse, SpaceEnvInput, SpaceFsFileResponse, SpaceFsMoveInput, SpaceFsTreeResponse, SpaceFsWriteFileInput, SpaceMember, SpaceRecord, SpaceRole, SpaceSessionsResponse } from "../types.js";
+import type { CheckpointRecord, ContentBlock, SessionMessageResponse, SessionMessagesPaginatedResponse, SessionMessagesResponse, SessionRecord, SpaceAccessPolicy, SpaceBootstrapSource, SpaceChannelBindingInput, SpaceCheckpointDetailResponse, SpaceCreateResponse, SpaceEnvInput, SpaceFsFileResponse, SpaceFsMoveInput, SpaceFsTreeResponse, SpaceFsUploadResponse, SpaceUsageResponse, SpaceFsWriteFileInput, SpaceMember, SpaceRecord, SpaceRole, SpaceSessionsResponse } from "../types.js";
+import { SpaceInvitationsApi } from "./invitations.js";
 export type SessionSubscriptionHandlers = {
     progress?: (event: WebsocketEventPayload) => void;
     final?: (event: WebsocketEventPayload) => void;
@@ -58,6 +59,7 @@ export declare class SpaceFilesApi {
         fromPath: string;
         toPath: string;
     }>;
+    upload(files: File[], dir?: string): Promise<SpaceFsUploadResponse>;
 }
 declare class SessionMessagesClient {
     private readonly transport;
@@ -67,6 +69,9 @@ declare class SessionMessagesClient {
     private lastSentAt;
     constructor(transport: HttpTransport, sessionId: string);
     list(customFetch?: Fetch): Promise<SessionMessagesResponse>;
+    get(messageId: string, optionsOrFetch?: {
+        detail?: "summary" | "full";
+    } | Fetch, customFetch?: Fetch): Promise<SessionMessageResponse>;
     listPaginated(options?: {
         cursor?: number;
         limit?: number;
@@ -96,6 +101,9 @@ export declare class SessionClient {
         space: SpaceRecord;
         session: SessionRecord;
     }>;
+    rename(title: string | null, customFetch?: Fetch): Promise<{
+        session: SessionRecord;
+    }>;
     subscribe(handlers: SessionSubscriptionHandlers): () => void;
     on(type: SessionEventName, handler: (event: WebsocketEventPayload) => void): () => void;
 }
@@ -111,9 +119,20 @@ export declare class SpaceSessionsApi {
         ok: true;
         session: SessionRecord;
     }>;
-    list(customFetch?: Fetch): Promise<SpaceSessionsResponse>;
+    list(optionsOrFetch?: {
+        limit?: number;
+        cursor?: string | null;
+    } | Fetch, customFetch?: Fetch): Promise<SpaceSessionsResponse>;
     byId(sessionId: string): SessionClient;
 }
+export type WebSocketConnectionState = {
+    state: "connecting" | "reconnecting" | "open" | "closed" | "error";
+    willReconnect: boolean;
+    connectionId?: string | null;
+    attempt?: number;
+    delayMs?: number;
+    recoverable?: boolean;
+};
 export declare class SpaceEventsApi {
     private readonly websocketClient;
     private readonly spaceId;
@@ -143,6 +162,55 @@ export declare class SpaceAccessApi {
         anonymous_user?: SpaceRole | null;
     }): Promise<SpaceAccessPolicy>;
 }
+export declare class SpaceUsageApi {
+    private readonly transport;
+    private readonly spaceId;
+    constructor(transport: HttpTransport, spaceId: string);
+    get(days?: number, customFetch?: Fetch): Promise<SpaceUsageResponse>;
+}
+export type SpaceChannelBindingRecord = {
+    id: string;
+    spaceId: string;
+    channelId: string;
+    config: Record<string, unknown> | null;
+    createdAt: string;
+    channel: {
+        id: string;
+        userUuid: string;
+        provider: string;
+        name: string;
+        status: string;
+        createdAt: string;
+        updatedAt: string;
+    } | null;
+};
+export declare class SpaceChannelsApi {
+    private readonly transport;
+    private readonly spaceId;
+    constructor(transport: HttpTransport, spaceId: string);
+    list(): Promise<SpaceChannelBindingRecord[]>;
+    bind(channelId: string, config?: Record<string, unknown> | null): Promise<SpaceChannelBindingRecord>;
+    unbind(channelId: string): Promise<{
+        ok: true;
+    }>;
+}
+export declare class SpaceEnvApi {
+    private readonly transport;
+    private readonly spaceId;
+    constructor(transport: HttpTransport, spaceId: string);
+    list(): Promise<{
+        env: SpaceEnvInput[];
+    }>;
+    create(input: SpaceEnvInput): Promise<{
+        env: SpaceEnvInput[];
+    }>;
+    update(name: string, value: string): Promise<{
+        env: SpaceEnvInput[];
+    }>;
+    remove(name: string): Promise<{
+        env: SpaceEnvInput[];
+    }>;
+}
 export declare class SpaceCheckpointsApi {
     private readonly transport;
     private readonly spaceId;
@@ -165,6 +233,10 @@ export declare class SpaceClient {
     readonly members: SpaceMembersApi;
     readonly access: SpaceAccessApi;
     readonly checkpoints: SpaceCheckpointsApi;
+    readonly usage: SpaceUsageApi;
+    readonly channels: SpaceChannelsApi;
+    readonly env: SpaceEnvApi;
+    readonly invitations: SpaceInvitationsApi;
     constructor(id: string, transport: HttpTransport, websocketClient: WebsocketClient | null);
     get(customFetch?: Fetch): Promise<SpaceRecord>;
     rename(name: string): Promise<{

package/dist/apis/spaces.js

@@ -1,4 +1,5 @@
 import { ensureRealtimeConnected } from "../realtime.js";
+import { SpaceInvitationsApi } from "./invitations.js";
 const DEFAULT_DEDUP_WINDOW_MS = 2000;
 const toSessionEventName = (type) => {
     switch (type) {
@@ -90,6 +91,19 @@ export class SpaceFilesApi {
             body: JSON.stringify(input),
         });
     }
+    upload(files, dir = "") {
+        const params = new URLSearchParams();
+        if (dir)
+            params.set("dir", dir);
+        const query = params.toString();
+        const formData = new FormData();
+        for (const file of files)
+            formData.append("files", file);
+        return this.transport.request(`/api/spaces/${this.spaceId}/fs/upload${query ? `?${query}` : ""}`, {
+            method: "POST",
+            body: formData,
+        });
+    }
 }
 class SessionMessagesClient {
     transport;
@@ -106,6 +120,17 @@ class SessionMessagesClient {
             fetch: customFetch,
         });
     }
+    get(messageId, optionsOrFetch, customFetch) {
+        const options = typeof optionsOrFetch === "function" ? undefined : optionsOrFetch;
+        const fetch = typeof optionsOrFetch === "function" ? optionsOrFetch : customFetch;
+        const params = new URLSearchParams();
+        if (options?.detail)
+            params.set("detail", options.detail);
+        const query = params.toString();
+        return this.transport.request(`/api/sessions/${this.sessionId}/messages/${messageId}${query ? `?${query}` : ""}`, {
+            fetch,
+        });
+    }
     listPaginated(options, customFetch) {
         const params = new URLSearchParams();
         if (options?.cursor !== undefined)
@@ -201,6 +226,13 @@ export class SessionClient {
             fetch: customFetch,
         });
     }
+    rename(title, customFetch) {
+        return this.transport.request(`/api/sessions/${this.id}`, {
+            method: "PATCH",
+            body: JSON.stringify({ title }),
+            fetch: customFetch,
+        });
+    }
     subscribe(handlers) {
         return this.realtime.subscribe(handlers);
     }
@@ -226,9 +258,17 @@ export class SpaceSessionsApi {
             body: JSON.stringify(input ?? {}),
         });
     }
-    list(customFetch) {
-        return this.transport.request(`/api/spaces/${this.spaceId}/sessions`, {
-            fetch: customFetch,
+    list(optionsOrFetch, customFetch) {
+        const options = typeof optionsOrFetch === "function" ? undefined : optionsOrFetch;
+        const fetch = typeof optionsOrFetch === "function" ? optionsOrFetch : customFetch;
+        const params = new URLSearchParams();
+        if (options?.limit !== undefined)
+            params.set("limit", String(options.limit));
+        if (options?.cursor)
+            params.set("cursor", options.cursor);
+        const query = params.toString();
+        return this.transport.request(`/api/spaces/${this.spaceId}/sessions${query ? `?${query}` : ""}`, {
+            fetch,
         });
     }
     byId(sessionId) {
@@ -301,12 +341,73 @@ export class SpaceAccessApi {
     }
     set(body) {
         return this.transport.request(`/api/spaces/${this.spaceId}/access`, {
-            method: "PUT",
+            method: "PATCH",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify(body),
         });
     }
 }
+export class SpaceUsageApi {
+    transport;
+    spaceId;
+    constructor(transport, spaceId) {
+        this.transport = transport;
+        this.spaceId = spaceId;
+    }
+    get(days = 30, customFetch) {
+        const params = new URLSearchParams({ days: String(days) });
+        return this.transport.request(`/api/spaces/${this.spaceId}/usage?${params.toString()}`, { fetch: customFetch });
+    }
+}
+export class SpaceChannelsApi {
+    transport;
+    spaceId;
+    constructor(transport, spaceId) {
+        this.transport = transport;
+        this.spaceId = spaceId;
+    }
+    list() {
+        return this.transport.request(`/api/spaces/${this.spaceId}/channels`);
+    }
+    bind(channelId, config) {
+        return this.transport.request(`/api/spaces/${this.spaceId}/channels/${channelId}`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ config: config ?? null }),
+        });
+    }
+    unbind(channelId) {
+        return this.transport.request(`/api/spaces/${this.spaceId}/channels/${channelId}`, { method: "DELETE" });
+    }
+}
+export class SpaceEnvApi {
+    transport;
+    spaceId;
+    constructor(transport, spaceId) {
+        this.transport = transport;
+        this.spaceId = spaceId;
+    }
+    list() {
+        return this.transport.request(`/api/spaces/${this.spaceId}/env`);
+    }
+    create(input) {
+        return this.transport.request(`/api/spaces/${this.spaceId}/env`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(input),
+        });
+    }
+    update(name, value) {
+        return this.transport.request(`/api/spaces/${this.spaceId}/env/${encodeURIComponent(name)}`, {
+            method: "PUT",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ value }),
+        });
+    }
+    remove(name) {
+        return this.transport.request(`/api/spaces/${this.spaceId}/env/${encodeURIComponent(name)}`, { method: "DELETE" });
+    }
+}
 export class SpaceCheckpointsApi {
     transport;
     spaceId;
@@ -337,6 +438,10 @@ export class SpaceClient {
     members;
     access;
     checkpoints;
+    usage;
+    channels;
+    env;
+    invitations;
     constructor(id, transport, websocketClient) {
         this.id = id;
         this.transport = transport;
@@ -346,6 +451,10 @@ export class SpaceClient {
         this.members = new SpaceMembersApi(transport, id);
         this.access = new SpaceAccessApi(transport, id);
         this.checkpoints = new SpaceCheckpointsApi(transport, id);
+        this.usage = new SpaceUsageApi(transport, id);
+        this.channels = new SpaceChannelsApi(transport, id);
+        this.env = new SpaceEnvApi(transport, id);
+        this.invitations = new SpaceInvitationsApi(transport, id);
     }
     get(customFetch) {
         return this.transport.request(`/api/spaces/${this.id}`, {

package/dist/client.d.ts

@@ -1,22 +1,27 @@
 import { ChannelsApi } from "./apis/channels.js";
 import { CronJobsApi } from "./apis/cron-jobs.js";
 import { ModelsApi } from "./apis/models.js";
+import { PromptsApi } from "./apis/prompts.js";
 import { SessionAccessApi } from "./apis/session-access.js";
-import { SpaceClient, SpacesApi } from "./apis/spaces.js";
+import { SpaceClient, SpacesApi, type WebSocketConnectionState } from "./apis/spaces.js";
 import { TasksApi } from "./apis/tasks.js";
 import { UserApi } from "./apis/user.js";
+import { PublicInviteApi } from "./apis/invitations.js";
 import { type CohubClientOptions } from "./transport.js";
 export declare class CohubClient {
     readonly spaces: SpacesApi;
     readonly channels: ChannelsApi;
     readonly user: UserApi;
     readonly models: ModelsApi;
+    readonly prompts: PromptsApi;
     readonly sessionAccess: SessionAccessApi;
     readonly tasks: TasksApi;
     readonly cronJobs: CronJobsApi;
+    readonly invite: PublicInviteApi;
     private readonly transport;
     private readonly websocketClient;
     constructor(options?: CohubClientOptions);
     space(spaceId: string): SpaceClient;
+    onConnection(handler: (state: WebSocketConnectionState) => void): () => void;
 }
 export declare const createCohubClient: (options?: CohubClientOptions) => CohubClient;

package/dist/client.js

@@ -1,38 +1,94 @@
 import { ChannelsApi } from "./apis/channels.js";
 import { CronJobsApi } from "./apis/cron-jobs.js";
 import { ModelsApi } from "./apis/models.js";
+import { PromptsApi } from "./apis/prompts.js";
 import { SessionAccessApi } from "./apis/session-access.js";
 import { SpaceClient, SpacesApi } from "./apis/spaces.js";
 import { TasksApi } from "./apis/tasks.js";
 import { UserApi } from "./apis/user.js";
+import { PublicInviteApi } from "./apis/invitations.js";
 import { HttpTransport } from "./transport.js";
 import { createWebsocketClient } from "./websocket.js";
+import { resolveApiBaseUrl, resolveWebsocketUrl } from "./environment.js";
 export class CohubClient {
     spaces;
     channels;
     user;
     models;
+    prompts;
     sessionAccess;
     tasks;
     cronJobs;
+    invite;
     transport;
     websocketClient;
     constructor(options = {}) {
+        const apiBaseUrl = resolveApiBaseUrl(options);
         this.transport = new HttpTransport(options);
         this.websocketClient = createWebsocketClient({
+            url: resolveWebsocketUrl({
+                env: options.websocket?.env ?? options.env,
+                url: options.websocket?.url,
+            }),
             ...options.websocket,
             getAccessToken: options.getAccessToken,
         });
         this.spaces = new SpacesApi(this.transport);
         this.channels = new ChannelsApi(this.transport);
-        this.user = new UserApi(this.transport, options.baseUrl ?? "", options.setStoredAuthToken, options.clearStoredAuthToken);
-        this.models = new ModelsApi(options.fetch ?? fetch, options.baseUrl ?? "");
+        this.user = new UserApi(this.transport, apiBaseUrl, options.setStoredAuthToken, options.clearStoredAuthToken);
+        this.models = new ModelsApi(this.transport);
+        this.prompts = new PromptsApi(options.fetch ?? fetch, apiBaseUrl);
         this.sessionAccess = new SessionAccessApi(this.transport);
         this.tasks = new TasksApi(this.transport);
         this.cronJobs = new CronJobsApi(this.transport);
+        this.invite = new PublicInviteApi(this.transport);
     }
     space(spaceId) {
         return new SpaceClient(spaceId, this.transport, this.websocketClient);
     }
+    onConnection(handler) {
+        const connectingCleanup = this.websocketClient.on("connecting", (payload) => {
+            handler({
+                state: payload.isReconnect ? "reconnecting" : "connecting",
+                willReconnect: payload.isReconnect,
+                attempt: payload.attempt,
+            });
+        });
+        const reconnectingCleanup = this.websocketClient.on("reconnecting", (payload) => {
+            handler({
+                state: "reconnecting",
+                willReconnect: true,
+                attempt: payload.attempt,
+                delayMs: payload.delayMs,
+            });
+        });
+        const openCleanup = this.websocketClient.on("open", (payload) => {
+            handler({
+                state: "open",
+                willReconnect: false,
+                connectionId: payload.connectionId,
+            });
+        });
+        const closeCleanup = this.websocketClient.on("close", (payload) => {
+            handler({
+                state: "closed",
+                willReconnect: payload.willReconnect,
+            });
+        });
+        const errorCleanup = this.websocketClient.on("error", (payload) => {
+            handler({
+                state: "error",
+                willReconnect: payload.recoverable,
+                recoverable: payload.recoverable,
+            });
+        });
+        return () => {
+            connectingCleanup();
+            reconnectingCleanup();
+            openCleanup();
+            closeCleanup();
+            errorCleanup();
+        };
+    }
 }
 export const createCohubClient = (options) => new CohubClient(options);

package/dist/environment.d.ts

@@ -0,0 +1,22 @@
+export type CohubEnvironment = "prod" | "dev";
+export declare const COHUB_ENVIRONMENTS: {
+    readonly prod: {
+        readonly apiBaseUrl: "https://api.cohub.run";
+        readonly websocketUrl: "wss://gateway.cohub.run/ws";
+    };
+    readonly dev: {
+        readonly apiBaseUrl: "https://api-dev.cohub.run";
+        readonly websocketUrl: "wss://gateway-dev.cohub.run/ws";
+    };
+};
+export declare const resolveCohubEnvironment: (env?: CohubEnvironment) => CohubEnvironment;
+export declare const normalizeBaseUrl: (url: string) => string;
+export declare const normalizeWebsocketUrl: (input: string) => string;
+export declare const resolveApiBaseUrl: (options?: {
+    baseUrl?: string;
+    env?: CohubEnvironment;
+}) => string;
+export declare const resolveWebsocketUrl: (options?: {
+    url?: string;
+    env?: CohubEnvironment;
+}) => string;

package/dist/environment.js

@@ -0,0 +1,37 @@
+export const COHUB_ENVIRONMENTS = {
+    prod: {
+        apiBaseUrl: "https://api.cohub.run",
+        websocketUrl: "wss://gateway.cohub.run/ws",
+    },
+    dev: {
+        apiBaseUrl: "https://api-dev.cohub.run",
+        websocketUrl: "wss://gateway-dev.cohub.run/ws",
+    },
+};
+const readRuntimeEnv = () => {
+    const runtime = globalThis;
+    return runtime.process?.env?.ENV;
+};
+export const resolveCohubEnvironment = (env) => {
+    if (env)
+        return env;
+    return readRuntimeEnv() === "dev" ? "dev" : "prod";
+};
+export const normalizeBaseUrl = (url) => url.trim().replace(/\/+$/, "");
+export const normalizeWebsocketUrl = (input) => {
+    const trimmed = normalizeBaseUrl(input);
+    const withProtocol = trimmed
+        .replace(/^http:/, "ws:")
+        .replace(/^https:/, "wss:");
+    return withProtocol.endsWith("/ws") ? withProtocol : `${withProtocol}/ws`;
+};
+export const resolveApiBaseUrl = (options = {}) => {
+    if (options.baseUrl)
+        return normalizeBaseUrl(options.baseUrl);
+    return COHUB_ENVIRONMENTS[resolveCohubEnvironment(options.env)].apiBaseUrl;
+};
+export const resolveWebsocketUrl = (options = {}) => {
+    if (options.url)
+        return normalizeWebsocketUrl(options.url);
+    return COHUB_ENVIRONMENTS[resolveCohubEnvironment(options.env)].websocketUrl;
+};

package/dist/http.d.ts

@@ -1,19 +1,23 @@
 import { ChannelsApi } from "./apis/channels.js";
 import { CronJobsApi } from "./apis/cron-jobs.js";
 import { ModelsApi } from "./apis/models.js";
+import { PromptsApi } from "./apis/prompts.js";
 import { SessionAccessApi } from "./apis/session-access.js";
 import { SpaceClient, SpacesApi } from "./apis/spaces.js";
 import { TasksApi } from "./apis/tasks.js";
 import { UserApi } from "./apis/user.js";
+import { PublicInviteApi } from "./apis/invitations.js";
 import { HttpTransport, HttpError, type CohubClientOptions, type Fetch } from "./transport.js";
 export declare class CohubHttpClient {
     readonly spaces: SpacesApi;
     readonly channels: ChannelsApi;
     readonly user: UserApi;
     readonly models: ModelsApi;
+    readonly prompts: PromptsApi;
     readonly sessionAccess: SessionAccessApi;
     readonly tasks: TasksApi;
     readonly cronJobs: CronJobsApi;
+    readonly invite: PublicInviteApi;
     private readonly transport;
     constructor(options?: CohubClientOptions);
     space(spaceId: string): SpaceClient;

package/dist/http.js

@@ -1,29 +1,37 @@
 import { ChannelsApi } from "./apis/channels.js";
 import { CronJobsApi } from "./apis/cron-jobs.js";
 import { ModelsApi } from "./apis/models.js";
+import { PromptsApi } from "./apis/prompts.js";
 import { SessionAccessApi } from "./apis/session-access.js";
 import { SpaceClient, SpacesApi } from "./apis/spaces.js";
 import { TasksApi } from "./apis/tasks.js";
 import { UserApi } from "./apis/user.js";
+import { PublicInviteApi } from "./apis/invitations.js";
 import { HttpTransport, HttpError } from "./transport.js";
+import { resolveApiBaseUrl } from "./environment.js";
 export class CohubHttpClient {
     spaces;
     channels;
     user;
     models;
+    prompts;
     sessionAccess;
     tasks;
     cronJobs;
+    invite;
     transport;
     constructor(options = {}) {
+        const apiBaseUrl = resolveApiBaseUrl(options);
         this.transport = new HttpTransport(options);
         this.spaces = new SpacesApi(this.transport);
         this.channels = new ChannelsApi(this.transport);
-        this.user = new UserApi(this.transport, options.baseUrl ?? "", options.setStoredAuthToken, options.clearStoredAuthToken);
-        this.models = new ModelsApi(options.fetch ?? fetch, options.baseUrl ?? "");
+        this.user = new UserApi(this.transport, apiBaseUrl, options.setStoredAuthToken, options.clearStoredAuthToken);
+        this.models = new ModelsApi(this.transport);
+        this.prompts = new PromptsApi(options.fetch ?? fetch, apiBaseUrl);
         this.sessionAccess = new SessionAccessApi(this.transport);
         this.tasks = new TasksApi(this.transport);
         this.cronJobs = new CronJobsApi(this.transport);
+        this.invite = new PublicInviteApi(this.transport);
     }
     space(spaceId) {
         return new SpaceClient(spaceId, this.transport, null);

package/dist/index.d.ts

@@ -2,6 +2,8 @@ export { CohubHttpClient, createHttpClient } from "./http.js";
 export { CohubClient, createCohubClient } from "./client.js";
 export { WebsocketClient, createWebsocketClient } from "./websocket.js";
 export { HttpError } from "./transport.js";
+export { COHUB_ENVIRONMENTS, normalizeBaseUrl, normalizeWebsocketUrl, resolveApiBaseUrl, resolveCohubEnvironment, resolveWebsocketUrl, } from "./environment.js";
 export type { CohubClientOptions, Fetch } from "./transport.js";
+export type { CohubEnvironment } from "./environment.js";
 export * from "./types.js";
-export type { SessionEventName, SessionSubscriptionHandlers, SpaceEventName } from "./apis/spaces.js";
+export type { SessionEventName, SessionSubscriptionHandlers, SpaceChannelBindingRecord, SpaceEventName, WebSocketConnectionState } from "./apis/spaces.js";

package/dist/index.js

@@ -2,4 +2,5 @@ export { CohubHttpClient, createHttpClient } from "./http.js";
 export { CohubClient, createCohubClient } from "./client.js";
 export { WebsocketClient, createWebsocketClient } from "./websocket.js";
 export { HttpError } from "./transport.js";
+export { COHUB_ENVIRONMENTS, normalizeBaseUrl, normalizeWebsocketUrl, resolveApiBaseUrl, resolveCohubEnvironment, resolveWebsocketUrl, } from "./environment.js";
 export * from "./types.js";

package/dist/realtime.js

@@ -1,4 +1,7 @@
 export function ensureRealtimeConnected(websocketClient) {
+    if (websocketClient.state === "open" || websocketClient.state === "connecting" || websocketClient.state === "reconnecting") {
+        return;
+    }
     void websocketClient.connect().catch((error) => {
         console.error("[CohubClient] Failed to connect realtime websocket:", error);
     });

package/dist/transport.d.ts

@@ -1,6 +1,8 @@
+import type { CohubEnvironment } from "./environment.js";
 import type { WebsocketClientOptions } from "./websocket.js";
 export type Fetch = typeof globalThis.fetch;
 export type CohubClientOptions = {
+    env?: CohubEnvironment;
     baseUrl?: string;
     getAccessToken?: () => Promise<string | null> | string | null;
     onUnauthorized?: () => Promise<void> | void;

package/dist/transport.js

@@ -1,3 +1,4 @@
+import { resolveApiBaseUrl } from "./environment.js";
 export class HttpError extends Error {
     status;
     body;
@@ -14,7 +15,7 @@ export class HttpTransport {
     getAccessToken;
     onUnauthorized;
     constructor(options = {}) {
-        this.baseUrl = options.baseUrl ?? "";
+        this.baseUrl = resolveApiBaseUrl(options);
         this.fetcher = options.fetch ?? fetch;
         this.getAccessToken = options.getAccessToken;
         this.onUnauthorized = options.onUnauthorized;

package/dist/types.d.ts

@@ -40,6 +40,22 @@ export type SpaceFsMoveInput = {
     fromPath: string;
     toPath: string;
 };
+export type SpaceFsUploadEntry = {
+    path: string;
+    name: string;
+    size: number;
+    mimeType: string | null;
+    mtimeMs: number;
+};
+export type SpaceFsUploadError = {
+    name: string;
+    code: "file_too_large" | "name_invalid" | "write_failed";
+    message: string;
+};
+export type SpaceFsUploadResponse = {
+    uploaded: SpaceFsUploadEntry[];
+    errors: SpaceFsUploadError[];
+};
 export type SessionBindingRecord = ProtocolSessionBindingRecord;
 export type SessionRecord = ProtocolSessionRecord & {
     bindings?: SessionBindingRecord[];
@@ -49,6 +65,10 @@ export type SessionRecord = ProtocolSessionRecord & {
     totalOutputTokens?: number;
     totalCost?: string | number | null;
 };
+export type SpaceGitInfo = {
+    giteaHost: string;
+    giteaUsername: string;
+};
 export type SpaceRecord = {
     id: string;
     userUuid: string;
@@ -69,6 +89,7 @@ export type SpaceRecord = {
         status: string;
     }[];
     accessLevel?: "minimal";
+    gitInfo?: SpaceGitInfo | null;
 };
 export type SpaceBootstrapSource = {
     type: "blank";
@@ -86,12 +107,14 @@ export type SpaceCreateResponse = {
 };
 export type SpaceListItem = SpaceRecord;
 export type SessionMessagesResponse = {
-    space: SpaceRecord;
     session: SessionRecord;
     messages: MessageRecord[];
 };
+export type SessionMessageResponse = {
+    session: SessionRecord;
+    message: MessageRecord;
+};
 export type SessionMessagesPaginatedResponse = {
-    space: SpaceRecord;
     session: SessionRecord;
     messages: MessageRecord[];
     hasMore: boolean;
@@ -102,6 +125,16 @@ export type ModelCatalogEntry = {
     id: string;
     model: Record<string, unknown>;
 };
+export type PromptTemplateCatalogEntry = {
+    name: string;
+    description: string;
+    argumentHint?: string;
+    category?: string;
+    scope: "platform";
+};
+export type PromptTemplateCatalogResponse = {
+    prompts: PromptTemplateCatalogEntry[];
+};
 export type Channel = {
     id: string;
     userUuid: string;
@@ -125,8 +158,11 @@ export type SpaceChannelBindingInput = {
     config?: ChannelConfig | null;
 };
 export type SpaceSessionsResponse = {
-    space: SpaceRecord;
     sessions: SessionRecord[];
+    pageInfo?: {
+        hasMore: boolean;
+        nextCursor: string | null;
+    };
 };
 export type UserSshKey = {
     id: string;
@@ -198,7 +234,7 @@ export type CreateScheduledTaskInput = {
     spaceId?: string;
     sessionId?: string;
 };
-export type SpaceRole = "host" | "maker" | "guest";
+export type SpaceRole = "host" | "builder" | "guest";
 export type SpaceMember = {
     userId: string;
     role: SpaceRole;
@@ -209,3 +245,65 @@ export type SpaceAccessPolicy = {
     signed_in_user: SpaceRole | null;
     anonymous_user: SpaceRole | null;
 };
+export type SpaceUsageHourlyStat = {
+    bucketStartAt: string;
+    totalTokens: number;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    costTotal: number;
+    requestCount: number;
+    successCount: number;
+    errorCount: number;
+    models: string[];
+};
+export type SpaceUsageSummary = {
+    totalTokens: number;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    costTotal: number;
+    requestCount: number;
+    successCount: number;
+    errorCount: number;
+};
+export type SpaceUsageResponse = {
+    hourly: SpaceUsageHourlyStat[];
+    summary: SpaceUsageSummary;
+    days: number;
+};
+export type SpaceInvitation = {
+    token: string;
+    role: SpaceRole;
+    status: "active" | "revoked" | "exhausted";
+    useCount: number;
+    maxUses: number | null;
+    createdAt: string | null;
+    expiresInSeconds: number | null;
+};
+export type CreateInvitationInput = {
+    role?: SpaceRole;
+    ttlSeconds?: number;
+    maxUses?: number;
+};
+export type CreateInvitationResponse = {
+    token: string;
+    role: SpaceRole;
+    expiresAt: string;
+    maxUses: number | null;
+};
+export type InvitationDetail = {
+    token: string;
+    spaceId: string;
+    spaceName: string;
+    role: SpaceRole;
+    expiresInSeconds: number | null;
+};
+export type AcceptInvitationResponse = {
+    ok: true;
+    spaceId: string;
+    spaceName: string;
+    role: SpaceRole;
+};

package/dist/websocket.d.ts

@@ -1,5 +1,6 @@
 import { type ChannelEnvelope } from "@neta-art/cohub-protocol/realtime";
 import type { ContentBlock } from "@neta-art/cohub-protocol/core";
+import type { CohubEnvironment } from "./environment.js";
 export type WebsocketEventPayload = ChannelEnvelope;
 export type WebSocketLike = {
     readonly readyState: number;
@@ -12,6 +13,7 @@ export type WebSocketLike = {
 };
 export type WebSocketConstructor = new (url: string) => WebSocketLike;
 export type WebsocketClientOptions = {
+    env?: CohubEnvironment;
     url?: string;
     autoReconnect?: boolean;
     reconnectBaseDelayMs?: number;
@@ -22,8 +24,18 @@ export type WebsocketClientOptions = {
     getAccessToken?: () => Promise<string | null> | string | null;
     WebSocketImpl?: WebSocketConstructor;
 };
-export type WebsocketClientState = "idle" | "connecting" | "open" | "closed";
+export type WebsocketClientState = "idle" | "connecting" | "reconnecting" | "open" | "closed";
 export type WebsocketClientEvents = {
+    connecting: {
+        isReconnect: boolean;
+        attempt: number;
+    };
+    reconnecting: {
+        attempt: number;
+        delayMs: number;
+        reason?: string;
+        code?: number;
+    };
     open: {
         connectionId?: string | null;
     };
@@ -34,6 +46,7 @@ export type WebsocketClientEvents = {
     };
     error: {
         error: unknown;
+        recoverable: boolean;
     };
     event: WebsocketEventPayload;
     ready: {
@@ -75,6 +88,7 @@ export declare class WebsocketClient {
     private ws;
     private pingTimer;
     private reconnectTimer;
+    private reconnectTimerResolver;
     private reconnectAttempt;
     private manuallyClosed;
     private connectPromise;

package/dist/websocket.js

@@ -1,5 +1,8 @@
 import { realtimeEnvelopeSchema, } from "@neta-art/cohub-protocol/realtime";
+import { resolveWebsocketUrl } from "./environment.js";
 const createEventMap = () => ({
+    connecting: new Set(),
+    reconnecting: new Set(),
     open: new Set(),
     close: new Set(),
     error: new Set(),
@@ -10,24 +13,9 @@ const createEventMap = () => ({
     serverError: new Set(),
     pong: new Set(),
 });
-const toWebSocketUrl = (input) => {
-    const base = (input?.trim() || "").replace(/\/$/, "");
-    if (base) {
-        if (base.startsWith("ws://") || base.startsWith("wss://"))
-            return `${base}/ws`;
-        if (base.startsWith("http://"))
-            return `${base.replace(/^http:/, "ws:")}/ws`;
-        if (base.startsWith("https://"))
-            return `${base.replace(/^https:/, "wss:")}/ws`;
-    }
-    if (typeof window !== "undefined") {
-        const protocol = window.location.protocol === "https:" ? "wss:" : "ws:";
-        return `${protocol}//${window.location.host}/ws`;
-    }
-    return "ws://localhost:8788/ws";
-};
+const toWebSocketUrl = (input, env) => resolveWebsocketUrl({ url: input, env });
 const normalizeOptions = (options = {}) => ({
-    url: toWebSocketUrl(options.url),
+    url: toWebSocketUrl(options.url, options.env),
     autoReconnect: options.autoReconnect !== false,
     reconnectBaseDelayMs: options.reconnectBaseDelayMs ?? 1000,
     reconnectMaxDelayMs: options.reconnectMaxDelayMs ?? 15000,
@@ -35,6 +23,15 @@ const normalizeOptions = (options = {}) => ({
     pongTimeoutMs: options.pongTimeoutMs ?? 15000,
     debug: options.debug === true,
 });
+const formatCloseMessage = (code, reason) => `WebSocket closed: ${code ?? 0} ${reason || ""}`.trim();
+const isRetryableCloseCode = (code) => {
+    if (code === 1000)
+        return false;
+    if (code === 4003)
+        return false;
+    return true;
+};
+const AUTH_CLOSE_REASON = "authentication failed";
 class WebsocketAuthError extends Error {
     constructor(message) {
         super(message);
@@ -54,6 +51,7 @@ export class WebsocketClient {
     ws = null;
     pingTimer = null;
     reconnectTimer = null;
+    reconnectTimerResolver = null;
     reconnectAttempt = 0;
     manuallyClosed = false;
     connectPromise = null;
@@ -97,8 +95,11 @@ export class WebsocketClient {
             return this.connectPromise;
         if (this.state === "open" && this.ws?.readyState === WebSocket.OPEN)
             return;
+        const isReconnect = this.reconnectAttempt > 0 || this.state === "reconnecting";
         this.manuallyClosed = false;
-        this.state = "connecting";
+        this.clearReconnectTimer();
+        this.state = isReconnect ? "reconnecting" : "connecting";
+        this.emit("connecting", { isReconnect, attempt: this.reconnectAttempt });
         this.connectPromise = new Promise((resolve, reject) => {
             const ws = new this.WebSocketImpl(this.url);
             this.ws = ws;
@@ -119,7 +120,7 @@ export class WebsocketClient {
             };
             ws.onopen = async () => {
                 try {
-                    this.log("connected", this.url);
+                    this.log("connected", { url: this.url, isReconnect, attempt: this.reconnectAttempt });
                     this.startPingLoop();
                     await this.authenticate();
                     this.state = "open";
@@ -129,37 +130,36 @@ export class WebsocketClient {
                 }
                 catch (error) {
                     const authError = error instanceof Error ? error : new Error("authentication failed");
+                    this.emit("error", { error: authError, recoverable: false });
                     rejectOnce(authError);
-                    ws.close(4003, authError.message);
+                    ws.close(4003, AUTH_CLOSE_REASON);
                 }
             };
             ws.onmessage = (event) => {
                 this.handleMessage(event.data);
             };
             ws.onerror = (error) => {
-                this.emit("error", { error });
+                this.emit("error", { error, recoverable: !this.manuallyClosed });
             };
             ws.onclose = (event) => {
                 this.stopPingLoop();
-                const wasConnecting = this.state === "connecting";
+                const wasConnecting = this.state === "connecting" || this.state === "reconnecting";
                 this.state = "closed";
                 this.ws = null;
-                this.rejectAuthWaiter(new Error(`WebSocket closed: ${event.code} ${event.reason || ""}`.trim()));
-                const willReconnect = !this.manuallyClosed && this.autoReconnect;
+                const closeError = new Error(formatCloseMessage(event.code, event.reason));
+                this.rejectAuthWaiter(closeError);
+                const willReconnect = !this.manuallyClosed && this.autoReconnect && isRetryableCloseCode(event.code);
+                this.log("closed", { code: event.code, reason: event.reason, willReconnect, wasConnecting });
                 this.emit("close", {
                     code: event.code,
                     reason: event.reason,
                     willReconnect,
                 });
                 if (wasConnecting) {
-                    rejectOnce(new Error(`WebSocket closed: ${event.code} ${event.reason || ""}`.trim()));
-                    if (event.code === 4001 && willReconnect) {
-                        void this.scheduleReconnect();
-                    }
-                    return;
+                    rejectOnce(closeError);
                 }
                 if (willReconnect) {
-                    void this.scheduleReconnect();
+                    void this.scheduleReconnect(event.code, event.reason);
                 }
             };
         });
@@ -253,12 +253,12 @@ export class WebsocketClient {
             parsed = typeof raw === "string" ? JSON.parse(raw) : JSON.parse(String(raw));
         }
         catch {
-            this.emit("error", { error: new Error("invalid websocket payload") });
+            this.emit("error", { error: new Error("invalid websocket payload"), recoverable: true });
             return;
         }
         const result = realtimeEnvelopeSchema.safeParse(parsed);
         if (!result.success) {
-            this.emit("error", { error: new Error("invalid realtime envelope") });
+            this.emit("error", { error: new Error("invalid realtime envelope"), recoverable: true });
             return;
         }
         const envelope = result.data;
@@ -359,7 +359,7 @@ export class WebsocketClient {
             if (this.awaitingPong &&
                 this.pongDeadlineAt > 0 &&
                 Date.now() > this.pongDeadlineAt) {
-                this.emit("error", { error: new Error("websocket pong timeout") });
+                this.emit("error", { error: new Error("websocket pong timeout"), recoverable: true });
                 this.ws.close(4002, "pong timeout");
                 return;
             }
@@ -376,22 +376,41 @@ export class WebsocketClient {
         this.pongDeadlineAt = 0;
     }
     clearReconnectTimer() {
-        if (!this.reconnectTimer)
-            return;
-        clearTimeout(this.reconnectTimer);
-        this.reconnectTimer = null;
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        if (this.reconnectTimerResolver) {
+            const resolve = this.reconnectTimerResolver;
+            this.reconnectTimerResolver = null;
+            resolve();
+        }
     }
-    async scheduleReconnect() {
+    async scheduleReconnect(code, reason) {
         this.clearReconnectTimer();
+        const attempt = this.reconnectAttempt + 1;
         const delay = Math.min(this.reconnectBaseDelayMs * 2 ** this.reconnectAttempt, this.reconnectMaxDelayMs);
-        this.reconnectAttempt += 1;
+        this.reconnectAttempt = attempt;
+        this.state = "reconnecting";
+        this.log("schedule reconnect", { attempt, delay, code, reason });
+        this.emit("reconnecting", {
+            attempt,
+            delayMs: delay,
+            code,
+            reason,
+        });
         await new Promise((resolve) => {
-            this.reconnectTimer = setTimeout(() => resolve(), delay);
+            this.reconnectTimerResolver = resolve;
+            this.reconnectTimer = setTimeout(() => {
+                this.reconnectTimer = null;
+                this.reconnectTimerResolver = null;
+                resolve();
+            }, delay);
         });
         if (this.manuallyClosed)
             return;
         await this.connect().catch((error) => {
-            this.emit("error", { error });
+            this.emit("error", { error, recoverable: true });
         });
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neta-art/cohub",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Cohub SDK for spaces, sessions, checkpoints, and realtime agent collaboration.",
   "license": "UNLICENSED",
   "private": false,
@@ -8,10 +8,10 @@
   "sideEffects": false,
   "repository": {
     "type": "git",
-    "url": "https://github.com/neta-art/cohub.git",
+    "url": "https://github.com/talesofai/cohub.git",
     "directory": "packages/sdk"
   },
-  "homepage": "https://github.com/neta-art/cohub",
+  "homepage": "https://github.com/talesofai/cohub",
   "keywords": [
     "cohub",
     "sdk",
@@ -44,7 +44,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@neta-art/cohub-protocol": "^1.0.0"
+    "@neta-art/cohub-protocol": "1.2.0"
   },
   "devDependencies": {
     "typescript": "^6.0.3"