@clinebot/core 0.0.22 → 0.0.23

package/src/ClineCore.ts

@@ -0,0 +1,137 @@
+import type {
+	AgentConfig,
+	ToolApprovalRequest,
+	ToolApprovalResult,
+} from "@clinebot/agents";
+import type { ITelemetryService } from "@clinebot/shared";
+import {
+	createSessionHost,
+	type SessionBackend,
+	type SessionHost,
+} from "./session/session-host";
+import type { ToolExecutors } from "./tools";
+
+/** Advanced options for connecting to or spawning the Cline RPC server. */
+export interface RpcOptions {
+	/**
+	 * The address of the Cline RPC server to connect to.
+	 * Defaults to the `CLINE_RPC_ADDRESS` env var, or the SDK default address if unset.
+	 */
+	address?: string;
+	/**
+	 * When `true` (default), automatically spawns a background RPC server process if one is
+	 * not already running.
+	 */
+	autoStart?: boolean;
+	/**
+	 * Number of connection attempts made to the RPC server after it is spawned.
+	 * Defaults to `5`.
+	 */
+	connectAttempts?: number;
+	/**
+	 * Milliseconds to wait between RPC connection attempts. Defaults to `100`.
+	 */
+	connectDelayMs?: number;
+}
+
+export interface ClineCoreOptions {
+	/**
+	 * A human-readable name for this SDK client (e.g. `"my-app"`, `"acme-bot"`).
+	 * Used to identify the consumer in telemetry and logs.
+	 */
+	clientName?: string;
+	/**
+	 * A stable identifier for this machine or user, used for telemetry attribution.
+	 * Defaults to the system machine ID, falling back to a generated `cl-<nanoid>` persisted
+	 * at `~/.cline/data/machine-id`.
+	 */
+	distinctId?: string;
+	/**
+	 * Controls how the session backend is selected:
+	 * - `"auto"` (default) — connects to a running RPC server if available, starts one in the
+	 *   background if `rpc.autoStart` is true, and falls back to local SQLite/file storage.
+	 * - `"rpc"` — requires an RPC server; throws if one is not reachable.
+	 * - `"local"` — always uses local SQLite (or file-based) storage; never touches RPC.
+	 */
+	backendMode?: "auto" | "rpc" | "local";
+	/**
+	 * RPC server connection options. Only relevant when `backendMode` is `"auto"` or `"rpc"`.
+	 */
+	rpc?: RpcOptions;
+	/**
+	 * Override one or more default tool executors (e.g. file I/O, shell, browser).
+	 * Partial — only the keys you supply are replaced; the rest use built-in implementations.
+	 */
+	defaultToolExecutors?: Partial<ToolExecutors>;
+	/**
+	 * Telemetry service instance to use for capturing events and usage.
+	 * If omitted, telemetry is a no-op.
+	 */
+	telemetry?: ITelemetryService;
+	/**
+	 * Per-tool approval policies that control whether a tool runs automatically,
+	 * requires user confirmation, or is blocked entirely.
+	 */
+	toolPolicies?: AgentConfig["toolPolicies"];
+	/**
+	 * Called before any tool is executed that requires explicit user approval.
+	 * Return `{ approved: true }` to allow or `{ approved: false }` to deny.
+	 * If omitted, all approval-required tools are auto-denied.
+	 */
+	requestToolApproval?: (
+		request: ToolApprovalRequest,
+	) => Promise<ToolApprovalResult>;
+	/**
+	 * An already-constructed session backend to use instead of resolving one automatically.
+	 * Intended for testing or embedding a custom persistence layer.
+	 * @internal
+	 */
+	sessionService?: SessionBackend;
+}
+
+/**
+ * The primary entry point for the Cline Core SDK.
+ *
+ * @example
+ * ```ts
+ * import { ClineCore } from "@clinebot/core";
+ *
+ * const cline = await ClineCore.create({ clientName: "my-app" });
+ * const session = await cline.start({ ... });
+ * ```
+ */
+export class ClineCore implements SessionHost {
+	readonly clientName: string | undefined;
+	private readonly host: SessionHost;
+
+	private constructor(host: SessionHost, clientName: string | undefined) {
+		this.clientName = clientName;
+		this.host = host;
+	}
+
+	static async create(options: ClineCoreOptions = {}): Promise<ClineCore> {
+		const host = await createSessionHost(options);
+		return new ClineCore(host, options.clientName);
+	}
+
+	start: SessionHost["start"] = (...args) => this.host.start(...args);
+	send: SessionHost["send"] = (...args) => this.host.send(...args);
+	getAccumulatedUsage: SessionHost["getAccumulatedUsage"] = (...args) =>
+		this.host.getAccumulatedUsage(...args);
+	abort: SessionHost["abort"] = (...args) => this.host.abort(...args);
+	stop: SessionHost["stop"] = (...args) => this.host.stop(...args);
+	dispose: SessionHost["dispose"] = (...args) => this.host.dispose(...args);
+	get: SessionHost["get"] = (...args) => this.host.get(...args);
+	list: SessionHost["list"] = (...args) => this.host.list(...args);
+	delete: SessionHost["delete"] = (...args) => this.host.delete(...args);
+	readMessages: SessionHost["readMessages"] = (...args) =>
+		this.host.readMessages(...args);
+	readTranscript: SessionHost["readTranscript"] = (...args) =>
+		this.host.readTranscript(...args);
+	readHooks: SessionHost["readHooks"] = (...args) =>
+		this.host.readHooks(...args);
+	subscribe: SessionHost["subscribe"] = (...args) =>
+		this.host.subscribe(...args);
+	updateSessionModel: SessionHost["updateSessionModel"] = (...args) =>
+		this.host.updateSessionModel?.(...args) ?? Promise.resolve();
+}

package/src/account/cline-account-service.test.ts

@@ -0,0 +1,101 @@
+import { describe, expect, it, vi } from "vitest";
+import { ClineAccountService } from "./cline-account-service";
+
+describe("ClineAccountService", () => {
+	it("fetches current user balance and sends auth header", async () => {
+		const fetchImpl = vi.fn(async (input: unknown, init?: RequestInit) => {
+			expect(String(input)).toBe(
+				"https://api.cline.bot/api/v1/users/user-1/balance",
+			);
+			expect(init?.headers).toMatchObject({
+				Authorization: "Bearer workos:token-123",
+			});
+			return new Response(
+				JSON.stringify({
+					success: true,
+					data: { balance: 5, userId: "user-1" },
+				}),
+				{ status: 200, headers: { "Content-Type": "application/json" } },
+			);
+		});
+
+		const service = new ClineAccountService({
+			apiBaseUrl: "https://api.cline.bot",
+			getAuthToken: async () => "workos:token-123",
+			getCurrentUserId: () => "user-1",
+			fetchImpl: fetchImpl as unknown as typeof fetch,
+		});
+
+		const balance = await service.fetchBalance();
+		expect(balance).toEqual({ balance: 5, userId: "user-1" });
+	});
+
+	it("resolves organization member id from /users/me when not provided", async () => {
+		const fetchImpl = vi
+			.fn()
+			.mockResolvedValueOnce(
+				new Response(
+					JSON.stringify({
+						success: true,
+						data: {
+							id: "u-1",
+							email: "u@example.com",
+							displayName: "User",
+							photoUrl: "",
+							createdAt: "2025-01-01T00:00:00Z",
+							updatedAt: "2025-01-01T00:00:00Z",
+							organizations: [
+								{
+									active: true,
+									memberId: "member-9",
+									name: "Org",
+									organizationId: "org-1",
+									roles: ["member"],
+								},
+							],
+						},
+					}),
+					{ status: 200 },
+				),
+			)
+			.mockResolvedValueOnce(
+				new Response(
+					JSON.stringify({ success: true, data: { items: [{ id: "tx-1" }] } }),
+					{ status: 200 },
+				),
+			);
+
+		const service = new ClineAccountService({
+			apiBaseUrl: "https://api.cline.bot",
+			getAuthToken: async () => "workos:token-123",
+			fetchImpl: fetchImpl as unknown as typeof fetch,
+		});
+
+		const transactions = await service.fetchOrganizationUsageTransactions({
+			organizationId: "org-1",
+		});
+
+		expect(fetchImpl).toHaveBeenCalledTimes(2);
+		expect(String(fetchImpl.mock.calls[1][0])).toBe(
+			"https://api.cline.bot/api/v1/organizations/org-1/members/member-9/usages",
+		);
+		expect(transactions).toEqual([{ id: "tx-1" }]);
+	});
+
+	it("switchAccount sends null org id for personal account", async () => {
+		const fetchImpl = vi.fn(async (_input: unknown, init?: RequestInit) => {
+			expect(init?.method).toBe("PUT");
+			expect(init?.body).toBe(JSON.stringify({ organizationId: null }));
+			return new Response(null, { status: 204 });
+		});
+
+		const service = new ClineAccountService({
+			apiBaseUrl: "https://api.cline.bot",
+			getAuthToken: async () => "workos:token-123",
+			fetchImpl: fetchImpl as unknown as typeof fetch,
+		});
+
+		await service.switchAccount(undefined);
+		expect(fetchImpl).toHaveBeenCalledTimes(1);
+	});
+});

package/src/account/cline-account-service.ts

@@ -0,0 +1,300 @@
+import type {
+	ClineAccountBalance,
+	ClineAccountOrganization,
+	ClineAccountOrganizationBalance,
+	ClineAccountOrganizationUsageTransaction,
+	ClineAccountPaymentTransaction,
+	ClineAccountUsageTransaction,
+	ClineAccountUser,
+	ClineOrganization,
+	FeaturebaseTokenResponse,
+	UserRemoteConfigResponse,
+} from "./types";
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+interface ClineApiEnvelope<T> {
+	success?: boolean;
+	error?: string;
+	data?: T;
+}
+
+export interface ClineAccountServiceOptions {
+	apiBaseUrl: string;
+	getAuthToken: () => Promise<string | undefined | null>;
+	getCurrentUserId?: () =>
+		| Promise<string | undefined | null>
+		| string
+		| undefined
+		| null;
+	getOrganizationMemberId?: (
+		organizationId: string,
+	) => Promise<string | undefined | null> | string | undefined | null;
+	getHeaders?: () =>
+		| Promise<Record<string, string> | undefined>
+		| Record<string, string>
+		| undefined;
+	requestTimeoutMs?: number;
+	fetchImpl?: typeof fetch;
+}
+
+export class ClineAccountService {
+	private readonly apiBaseUrl: string;
+	private readonly getAuthTokenFn: ClineAccountServiceOptions["getAuthToken"];
+	private readonly getCurrentUserIdFn: ClineAccountServiceOptions["getCurrentUserId"];
+	private readonly getOrganizationMemberIdFn: ClineAccountServiceOptions["getOrganizationMemberId"];
+	private readonly getHeadersFn: ClineAccountServiceOptions["getHeaders"];
+	private readonly requestTimeoutMs: number;
+	private readonly fetchImpl: typeof fetch;
+
+	constructor(options: ClineAccountServiceOptions) {
+		const apiBaseUrl = options.apiBaseUrl.trim();
+		if (!apiBaseUrl) {
+			throw new Error("apiBaseUrl is required");
+		}
+
+		this.apiBaseUrl = apiBaseUrl;
+		this.getAuthTokenFn = options.getAuthToken;
+		this.getCurrentUserIdFn = options.getCurrentUserId;
+		this.getOrganizationMemberIdFn = options.getOrganizationMemberId;
+		this.getHeadersFn = options.getHeaders;
+		this.requestTimeoutMs = options.requestTimeoutMs ?? DEFAULT_TIMEOUT_MS;
+		this.fetchImpl = options.fetchImpl ?? fetch;
+	}
+
+	public async fetchMe(): Promise<ClineAccountUser> {
+		return this.request<ClineAccountUser>("/api/v1/users/me");
+	}
+
+	public async fetchRemoteConfig(): Promise<UserRemoteConfigResponse> {
+		return this.request<UserRemoteConfigResponse>(
+			"/api/v1/users/me/remote-config",
+		);
+	}
+
+	public async fetchFeaturebaseToken(): Promise<
+		FeaturebaseTokenResponse | undefined
+	> {
+		try {
+			return await this.request<FeaturebaseTokenResponse>(
+				"/api/v1/users/me/featurebase-token",
+			);
+		} catch {
+			return undefined;
+		}
+	}
+
+	public async fetchBalance(userId?: string): Promise<ClineAccountBalance> {
+		const resolvedUserId = await this.resolveUserId(userId);
+		return this.request<ClineAccountBalance>(
+			`/api/v1/users/${encodeURIComponent(resolvedUserId)}/balance`,
+		);
+	}
+
+	public async fetchUsageTransactions(
+		userId?: string,
+	): Promise<ClineAccountUsageTransaction[]> {
+		const resolvedUserId = await this.resolveUserId(userId);
+		const response = await this.request<{
+			items: ClineAccountUsageTransaction[];
+		}>(`/api/v1/users/${encodeURIComponent(resolvedUserId)}/usages`);
+		return response.items ?? [];
+	}
+
+	public async fetchPaymentTransactions(
+		userId?: string,
+	): Promise<ClineAccountPaymentTransaction[]> {
+		const resolvedUserId = await this.resolveUserId(userId);
+		const response = await this.request<{
+			paymentTransactions: ClineAccountPaymentTransaction[];
+		}>(`/api/v1/users/${encodeURIComponent(resolvedUserId)}/payments`);
+		return response.paymentTransactions ?? [];
+	}
+
+	public async fetchUserOrganizations(): Promise<ClineAccountOrganization[]> {
+		const me = await this.fetchMe();
+		return me.organizations ?? [];
+	}
+
+	public async fetchOrganization(
+		organizationId: string,
+	): Promise<ClineOrganization> {
+		const orgId = organizationId.trim();
+		if (!orgId) {
+			throw new Error("organizationId is required");
+		}
+		return this.request<ClineOrganization>(
+			`/api/v1/organizations/${encodeURIComponent(orgId)}`,
+		);
+	}
+
+	public async fetchOrganizationBalance(
+		organizationId: string,
+	): Promise<ClineAccountOrganizationBalance> {
+		const orgId = organizationId.trim();
+		if (!orgId) {
+			throw new Error("organizationId is required");
+		}
+		return this.request<ClineAccountOrganizationBalance>(
+			`/api/v1/organizations/${encodeURIComponent(orgId)}/balance`,
+		);
+	}
+
+	public async fetchOrganizationUsageTransactions(input: {
+		organizationId: string;
+		memberId?: string;
+	}): Promise<ClineAccountOrganizationUsageTransaction[]> {
+		const organizationId = input.organizationId.trim();
+		if (!organizationId) {
+			throw new Error("organizationId is required");
+		}
+
+		const memberId = await this.resolveOrganizationMemberId(
+			organizationId,
+			input.memberId,
+		);
+		const response = await this.request<{
+			items: ClineAccountOrganizationUsageTransaction[];
+		}>(
+			`/api/v1/organizations/${encodeURIComponent(organizationId)}/members/${encodeURIComponent(memberId)}/usages`,
+		);
+		return response.items ?? [];
+	}
+
+	public async switchAccount(organizationId?: string | null): Promise<void> {
+		await this.request<void>("/api/v1/users/active-account", {
+			method: "PUT",
+			body: {
+				organizationId: organizationId?.trim() || null,
+			},
+			expectNoContent: true,
+		});
+	}
+
+	private async resolveUserId(userId?: string): Promise<string> {
+		const explicit = userId?.trim();
+		if (explicit) {
+			return explicit;
+		}
+
+		const fromProvider = this.getCurrentUserIdFn
+			? await this.getCurrentUserIdFn()
+			: undefined;
+		const provided = fromProvider?.trim();
+		if (provided) {
+			return provided;
+		}
+
+		const me = await this.fetchMe();
+		if (!me.id?.trim()) {
+			throw new Error("Unable to resolve current user id");
+		}
+		return me.id;
+	}
+
+	private async resolveOrganizationMemberId(
+		organizationId: string,
+		memberId?: string,
+	): Promise<string> {
+		const explicit = memberId?.trim();
+		if (explicit) {
+			return explicit;
+		}
+
+		const fromProvider = this.getOrganizationMemberIdFn
+			? await this.getOrganizationMemberIdFn(organizationId)
+			: undefined;
+		const provided = fromProvider?.trim();
+		if (provided) {
+			return provided;
+		}
+
+		const organizations = await this.fetchUserOrganizations();
+		const resolved = organizations.find(
+			(org) => org.organizationId === organizationId,
+		)?.memberId;
+		if (!resolved?.trim()) {
+			throw new Error(
+				`Unable to resolve memberId for organization ${organizationId}`,
+			);
+		}
+		return resolved;
+	}
+
+	private async request<T>(
+		endpoint: string,
+		input?: {
+			method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+			body?: unknown;
+			expectNoContent?: boolean;
+		},
+	): Promise<T> {
+		const token = (await this.getAuthTokenFn())?.trim();
+		if (!token) {
+			throw new Error("No Cline account auth token found");
+		}
+
+		const extraHeaders = this.getHeadersFn ? await this.getHeadersFn() : {};
+		const controller = new AbortController();
+		const timeout = setTimeout(() => controller.abort(), this.requestTimeoutMs);
+
+		try {
+			const response = await this.fetchImpl(
+				new URL(endpoint, this.apiBaseUrl),
+				{
+					method: input?.method ?? "GET",
+					headers: {
+						Authorization: `Bearer ${token}`,
+						"Content-Type": "application/json",
+						...(extraHeaders ?? {}),
+					},
+					body:
+						input?.body !== undefined ? JSON.stringify(input.body) : undefined,
+					signal: controller.signal,
+				},
+			);
+
+			if (response.status === 204 || input?.expectNoContent) {
+				if (!response.ok) {
+					throw new Error(
+						`Cline account request failed with status ${response.status}`,
+					);
+				}
+				return undefined as T;
+			}
+
+			const text = await response.text();
+			let parsed: unknown;
+			if (text.trim()) {
+				parsed = JSON.parse(text);
+			}
+
+			if (!response.ok) {
+				const message =
+					typeof parsed === "object" && parsed !== null && "error" in parsed
+						? String((parsed as { error: unknown }).error)
+						: `Cline account request failed with status ${response.status}`;
+				throw new Error(message);
+			}
+
+			if (typeof parsed === "object" && parsed !== null) {
+				const envelope = parsed as ClineApiEnvelope<T>;
+				if (typeof envelope.success === "boolean") {
+					if (!envelope.success) {
+						throw new Error(envelope.error || "Cline account request failed");
+					}
+					if (envelope.data !== undefined) {
+						return envelope.data;
+					}
+				}
+			}
+
+			if (parsed === undefined || parsed === null) {
+				throw new Error("Cline account response payload was empty");
+			}
+			return parsed as T;
+		} finally {
+			clearTimeout(timeout);
+		}
+	}
+}