@neta-art/cohub 1.0.0

package/README.md

@@ -0,0 +1,132 @@
+# @neta-art/cohub
+
+Cohub SDK for interacting with spaces, sessions, checkpoints, and realtime agent collaboration.
+
+## Install
+
+```bash
+npm install @neta-art/cohub @neta-art/cohub-protocol
+```
+
+## Quick start
+
+```ts
+import { createCohubClient } from "@neta-art/cohub";
+
+const client = createCohubClient({
+  baseUrl: "https://api.example.com",
+  getAccessToken: async () => localStorage.getItem("token"),
+  websocket: {
+    url: "https://gateway.example.com",
+  },
+});
+```
+
+## Spaces and sessions
+
+A **Space** is a live, isolated working environment where users and agents create together.
+
+```ts
+const created = await client.spaces.create({ name: "Demo" });
+const space = client.space(created.space.id);
+
+const sessionResult = await space.sessions.create({ title: "Planning" });
+const session = space.session(sessionResult.session.id);
+
+await session.messages.send({
+  content: [{ type: "text", text: "Help me plan the next steps" }],
+});
+```
+
+## Session subscriptions
+
+```ts
+const stop = session.subscribe({
+  progress(event) {
+    console.log("progress", event.payload);
+  },
+  final(event) {
+    console.log("final", event.payload);
+  },
+  error(event) {
+    console.error("error", event.payload);
+  },
+  persisted(event) {
+    console.log("persisted", event.payload);
+  },
+});
+
+// later
+stop();
+```
+
+You can also listen with business-oriented event names:
+
+```ts
+session.on("turn.final", (event) => {
+  console.log(event.payload);
+});
+
+space.on("message.persisted", (event) => {
+  console.log(event.payload);
+});
+```
+
+Supported business event names:
+
+- `turn.progress`
+- `turn.final`
+- `turn.error`
+- `message.persisted`
+
+## HTTP-only usage
+
+If you only want HTTP transport, use the dedicated entry:
+
+```ts
+import { createHttpClient } from "@neta-art/cohub/http";
+
+const http = createHttpClient({
+  baseUrl: "https://api.example.com",
+  getAccessToken: async () => localStorage.getItem("token"),
+});
+
+const spaces = await http.spaces.list();
+```
+
+Note: realtime methods like `space.subscribe(...)` or `session.subscribe(...)` require the main client with websocket configuration.
+
+## Low-level websocket usage
+
+If you need direct realtime transport access, use the websocket entry:
+
+```ts
+import { createWebsocketClient } from "@neta-art/cohub/websocket";
+
+const ws = createWebsocketClient({
+  url: "https://gateway.example.com",
+  getAccessToken: async () => localStorage.getItem("token"),
+});
+
+await ws.connect();
+```
+
+## Design principles
+
+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

package/dist/apis/channels.d.ts

@@ -0,0 +1,13 @@
+import type { HttpTransport, Fetch } from "../transport.js";
+import type { Channel } from "../types.js";
+export declare class ChannelsApi {
+    private readonly transport;
+    constructor(transport: HttpTransport);
+    list(customFetch?: Fetch): Promise<Channel[]>;
+    create(data: {
+        provider: string;
+        name: string;
+        credentials: Record<string, unknown>;
+    }): Promise<unknown>;
+    delete(id: string): Promise<unknown>;
+}

package/dist/apis/channels.js

@@ -0,0 +1,24 @@
+export class ChannelsApi {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    list(customFetch) {
+        return this.transport.request("/api/channels", {
+            method: "GET",
+            fetch: customFetch,
+        });
+    }
+    create(data) {
+        return this.transport.request("/api/channels", {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify(data),
+        });
+    }
+    delete(id) {
+        return this.transport.request(`/api/channels/${id}`, { method: "DELETE" });
+    }
+}

package/dist/apis/cron-jobs.d.ts

@@ -0,0 +1,19 @@
+import type { HttpTransport } from "../transport.js";
+import type { CreateCronJobInput, CronJobRecord, TaskRunRecord } from "../types.js";
+export declare class CronJobsApi {
+    private readonly transport;
+    constructor(transport: HttpTransport);
+    list(spaceId?: string): Promise<{
+        jobs: CronJobRecord[];
+    }>;
+    create(data: CreateCronJobInput): Promise<CronJobRecord>;
+    delete(id: string): Promise<{
+        ok: true;
+    }>;
+    toggle(id: string, enabled: boolean): Promise<{
+        ok: true;
+    }>;
+    runs(cronJobId: string): Promise<{
+        runs: TaskRunRecord[];
+    }>;
+}

package/dist/apis/cron-jobs.js

@@ -0,0 +1,32 @@
+export class CronJobsApi {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    list(spaceId) {
+        const query = spaceId ? `?spaceId=${encodeURIComponent(spaceId)}` : "";
+        return this.transport.request(`/api/cron-jobs${query}`);
+    }
+    create(data) {
+        return this.transport.request("/api/cron-jobs", {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(data),
+        });
+    }
+    delete(id) {
+        return this.transport.request(`/api/cron-jobs/${id}`, {
+            method: "DELETE",
+        });
+    }
+    toggle(id, enabled) {
+        return this.transport.request(`/api/cron-jobs/${id}`, {
+            method: "PATCH",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ enabled }),
+        });
+    }
+    runs(cronJobId) {
+        return this.transport.request(`/api/cron-jobs/${cronJobId}/runs`);
+    }
+}

package/dist/apis/models.d.ts

@@ -0,0 +1,8 @@
+import type { Fetch } 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[]>>;
+}

package/dist/apis/models.js

@@ -0,0 +1,17 @@
+export class ModelsApi {
+    fetcher;
+    baseUrl;
+    constructor(fetcher, baseUrl) {
+        this.fetcher = fetcher;
+        this.baseUrl = baseUrl;
+    }
+    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();
+    }
+}

package/dist/apis/session-access.d.ts

@@ -0,0 +1,13 @@
+import type { HttpTransport } from "../transport.js";
+import type { SpaceAccessPolicy, SpaceRole } from "../types.js";
+export declare class SessionAccessApi {
+    private readonly transport;
+    constructor(transport: HttpTransport);
+    get(sessionId: string): Promise<SpaceAccessPolicy>;
+    set(sessionId: string, body: {
+        anonymous_user?: SpaceRole | null;
+    }): Promise<SpaceAccessPolicy>;
+    remove(sessionId: string): Promise<{
+        ok: true;
+    }>;
+}

package/dist/apis/session-access.js

@@ -0,0 +1,19 @@
+export class SessionAccessApi {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    get(sessionId) {
+        return this.transport.request(`/api/sessions/${sessionId}/access`);
+    }
+    set(sessionId, body) {
+        return this.transport.request(`/api/sessions/${sessionId}/access`, {
+            method: "PUT",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(body),
+        });
+    }
+    remove(sessionId) {
+        return this.transport.request(`/api/sessions/${sessionId}/access`, { method: "DELETE" });
+    }
+}

package/dist/apis/spaces.d.ts

@@ -0,0 +1,177 @@
+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";
+export type SessionSubscriptionHandlers = {
+    progress?: (event: WebsocketEventPayload) => void;
+    final?: (event: WebsocketEventPayload) => void;
+    error?: (event: WebsocketEventPayload) => void;
+    persisted?: (event: WebsocketEventPayload) => void;
+    event?: (event: WebsocketEventPayload) => void;
+};
+export type SessionEventName = "turn.progress" | "turn.final" | "turn.error" | "message.persisted";
+export type SpaceEventName = SessionEventName | "event";
+type SessionSendMessageInput = {
+    content: ContentBlock[];
+    model?: string;
+    provider?: string;
+    clientMessageId?: string;
+};
+export declare class SpacesApi {
+    private readonly transport;
+    constructor(transport: HttpTransport);
+    list(customFetch?: Fetch): Promise<SpaceRecord[]>;
+    get(spaceId: string, customFetch?: Fetch): Promise<SpaceRecord>;
+    create(input?: {
+        name?: string;
+        description?: string;
+        source?: string;
+        extraEnv?: SpaceEnvInput[];
+        channelBindings?: SpaceChannelBindingInput[];
+        bootstrapSource?: SpaceBootstrapSource;
+    }, headers?: Record<string, string>): Promise<SpaceCreateResponse>;
+}
+export declare class SpaceFilesApi {
+    private readonly transport;
+    private readonly spaceId;
+    constructor(transport: HttpTransport, spaceId: string);
+    list(path?: string, customFetch?: Fetch): Promise<SpaceFsTreeResponse>;
+    read(path: string, customFetch?: Fetch): Promise<SpaceFsFileResponse>;
+    getDownloadUrl(path: string): string;
+    write(input: SpaceFsWriteFileInput): Promise<{
+        ok: true;
+        path: string;
+        size: number;
+        mtimeMs: number;
+    }>;
+    createDir(path: string): Promise<{
+        ok: true;
+        path: string;
+        size: number;
+        mtimeMs: number;
+    }>;
+    delete(path: string, recursive?: boolean): Promise<{
+        ok: true;
+        path: string;
+    }>;
+    move(input: SpaceFsMoveInput): Promise<{
+        ok: true;
+        fromPath: string;
+        toPath: string;
+    }>;
+}
+declare class SessionMessagesClient {
+    private readonly transport;
+    private readonly sessionId;
+    private lastSentSignature;
+    private lastSentSessionId;
+    private lastSentAt;
+    constructor(transport: HttpTransport, sessionId: string);
+    list(customFetch?: Fetch): Promise<SessionMessagesResponse>;
+    listPaginated(options?: {
+        cursor?: number;
+        limit?: number;
+        direction?: "older" | "newer";
+    }, customFetch?: Fetch): Promise<SessionMessagesPaginatedResponse>;
+    send(input: SessionSendMessageInput): Promise<{
+        ok: true;
+        userMessageId: string;
+    }>;
+}
+declare class SessionRealtimeClient {
+    private readonly websocketClient;
+    private readonly spaceId;
+    private readonly sessionId;
+    constructor(websocketClient: WebsocketClient | null, spaceId: string, sessionId: string);
+    subscribe(handlers: SessionSubscriptionHandlers): () => void;
+    on(type: SessionEventName, handler: (event: WebsocketEventPayload) => void): () => void;
+}
+export declare class SessionClient {
+    readonly spaceId: string;
+    readonly id: string;
+    private readonly transport;
+    readonly messages: SessionMessagesClient;
+    readonly realtime: SessionRealtimeClient;
+    constructor(spaceId: string, id: string, transport: HttpTransport, websocketClient: WebsocketClient | null);
+    get(customFetch?: Fetch): Promise<{
+        space: SpaceRecord;
+        session: SessionRecord;
+    }>;
+    subscribe(handlers: SessionSubscriptionHandlers): () => void;
+    on(type: SessionEventName, handler: (event: WebsocketEventPayload) => void): () => void;
+}
+export declare class SpaceSessionsApi {
+    private readonly transport;
+    private readonly spaceId;
+    private readonly websocketClient;
+    constructor(transport: HttpTransport, spaceId: string, websocketClient: WebsocketClient | null);
+    create(input?: {
+        title?: string;
+        source?: string;
+    }): Promise<{
+        ok: true;
+        session: SessionRecord;
+    }>;
+    list(customFetch?: Fetch): Promise<SpaceSessionsResponse>;
+    byId(sessionId: string): SessionClient;
+}
+export declare class SpaceEventsApi {
+    private readonly websocketClient;
+    private readonly spaceId;
+    constructor(websocketClient: WebsocketClient | null, spaceId: string);
+    subscribe(handler: (event: WebsocketEventPayload) => void): () => void;
+    on(type: SpaceEventName, handler: (event: WebsocketEventPayload) => void): () => void;
+}
+export declare class SpaceMembersApi {
+    private readonly transport;
+    private readonly spaceId;
+    constructor(transport: HttpTransport, spaceId: string);
+    list(): Promise<{
+        items: SpaceMember[];
+    }>;
+    update(userId: string, role: SpaceRole): Promise<SpaceMember>;
+    remove(userId: string): Promise<{
+        ok: true;
+    }>;
+}
+export declare class SpaceAccessApi {
+    private readonly transport;
+    private readonly spaceId;
+    constructor(transport: HttpTransport, spaceId: string);
+    get(): Promise<SpaceAccessPolicy>;
+    set(body: {
+        signed_in_user?: SpaceRole | null;
+        anonymous_user?: SpaceRole | null;
+    }): Promise<SpaceAccessPolicy>;
+}
+export declare class SpaceCheckpointsApi {
+    private readonly transport;
+    private readonly spaceId;
+    constructor(transport: HttpTransport, spaceId: string);
+    create(description?: string | null): Promise<{
+        ok: true;
+        taskRunId: string;
+    }>;
+    list(): Promise<{
+        checkpoints: CheckpointRecord[];
+    }>;
+    get(checkpointId: string, customFetch?: Fetch): Promise<SpaceCheckpointDetailResponse>;
+}
+export declare class SpaceClient {
+    readonly id: string;
+    private readonly transport;
+    private readonly websocketClient;
+    readonly files: SpaceFilesApi;
+    readonly sessions: SpaceSessionsApi;
+    readonly members: SpaceMembersApi;
+    readonly access: SpaceAccessApi;
+    readonly checkpoints: SpaceCheckpointsApi;
+    constructor(id: string, transport: HttpTransport, websocketClient: WebsocketClient | null);
+    get(customFetch?: Fetch): Promise<SpaceRecord>;
+    rename(name: string): Promise<{
+        space: SpaceRecord;
+    }>;
+    session(sessionId: string): SessionClient;
+    subscribe(handler: (event: WebsocketEventPayload) => void): () => void;
+    on(type: SpaceEventName, handler: (event: WebsocketEventPayload) => void): () => void;
+}
+export {};