@blankline/dropstone-sdk 1.0.8

package/README.md

@@ -0,0 +1,146 @@
+# @blankline/dropstone-sdk
+
+TypeScript SDK for [Dropstone](https://dropstone.io). Two ways to use it:
+
+1. **Headless HTTP API client** — for CI, automation, serverless, and any context without the Dropstone CLI installed. Uses an API key, talks directly to `https://api.dropstone.io/api/v1`.
+2. **Local agent client** — spawns `dropstone serve` as a subprocess and gives you a typed client against the full local agent surface (sessions, file ops, tools). Use when embedding the interactive agent in a Node app.
+
+> **Status:** preview. The API surface may shift before `1.0.0`. Pin the version range you depend on.
+
+## Install
+
+```bash
+npm install @blankline/dropstone-sdk
+# or
+pnpm add @blankline/dropstone-sdk
+# or
+bun add @blankline/dropstone-sdk
+```
+
+For the **headless API client**, you only need the npm package and a `DROPSTONE_API_KEY` (generate one at [dropstone.io/dashboard/settings](https://dropstone.io/dashboard/settings)).
+
+For the **local agent client**, you also need the Dropstone CLI installed on the same machine:
+
+```bash
+brew install blankline-org/dropstone-cli/dropstone   # macOS / Linux
+irm https://dropstone.io/install.ps1 | iex            # Windows
+curl -fsSL https://dropstone.io/install | bash        # Linux (bash)
+```
+
+## Headless HTTP API client (recommended for CI / automation)
+
+```ts
+import { createDropstoneApi } from "@blankline/dropstone-sdk"
+
+// Reads DROPSTONE_API_KEY from env automatically.
+const dropstone = createDropstoneApi()
+
+const resp = await dropstone.chat.completions.create({
+  model: "dropstone-fast",      // or "dropstone-pro" / "dropstone-heavy"
+  messages: [
+    { role: "user", content: "Write a haiku about debugging." },
+  ],
+})
+
+console.log(resp.choices[0].message.content)
+console.log("Cost: $" + resp.usage?.cost)   // billed amount, in USD
+```
+
+Streaming:
+
+```ts
+const stream = await dropstone.chat.completions.create({
+  model: "dropstone-fast",
+  stream: true,
+  messages: [{ role: "user", content: "Count to 5." }],
+})
+
+for await (const chunk of stream) {
+  process.stdout.write(chunk.choices?.[0]?.delta?.content ?? "")
+}
+```
+
+The API client is also drop-in OpenAI-compatible — if you'd rather use the OpenAI SDK, override its `baseURL`:
+
+```ts
+import OpenAI from "openai"
+const openai = new OpenAI({
+  baseURL: "https://api.dropstone.io/api/v1",
+  apiKey: process.env.DROPSTONE_API_KEY,
+})
+```
+
+Full HTTP API reference: [docs.dropstone.io/cli/api](https://docs.dropstone.io/cli/api).
+
+## Local agent client
+
+Spin up a local Dropstone server and send it a chat prompt:
+
+```ts
+import { createDropstone } from "@blankline/dropstone-sdk"
+
+const { client, server } = await createDropstone()
+
+const session = await client.session.create.mutate({
+  body: { agent: "build", model: { providerID: "dropstone", id: "dropstone-pro" } },
+})
+
+const reply = await client.session.prompt.mutate({
+  path: { id: session.data.id },
+  body: { parts: [{ type: "text", text: "Hello, who are you?" }] },
+})
+
+console.log(reply.data)
+
+await server.close()
+```
+
+`createDropstone` launches a fresh `dropstone serve` subprocess bound to `127.0.0.1` on a free port, returns a typed HTTP client pointed at it, and a `close()` to tear it down.
+
+## Talking to an already-running server
+
+If you already have a Dropstone server running (or want to point at a remote one), use `createDropstoneClient` directly:
+
+```ts
+import { createDropstoneClient } from "@blankline/dropstone-sdk"
+
+const client = createDropstoneClient({ baseUrl: "http://127.0.0.1:4096" })
+const config = await client.config.get.query()
+console.log(config.data)
+```
+
+## v2 API
+
+The SDK has both a stable v1 surface (auto-generated from the legacy Hono routes) and a v2 surface that mirrors the new Effect HttpApi contract. Prefer v2 for new code:
+
+```ts
+import { createDropstone } from "@blankline/dropstone-sdk/v2"
+
+const { client, server } = await createDropstone()
+// v2 exposes a richer resource hierarchy: workspace, worktree, file, find, etc.
+const files = await client.file.list.query({ path: { worktreeID: "default" } })
+```
+
+The v1 surface is kept for backward compatibility with existing integrations. New endpoints (`/api/usage`, PKCE auth, workspace adapters) only land on v2.
+
+## TUI
+
+You can also launch the Dropstone interactive TUI from a Node process:
+
+```ts
+import { createDropstoneTui } from "@blankline/dropstone-sdk"
+
+const tui = createDropstoneTui({ model: "dropstone-pro" })
+// ... when you're done:
+tui.close()
+```
+
+The TUI takes over stdin/stdout/stderr inherited from the parent process.
+
+## TypeScript
+
+The SDK ships full type definitions generated from the server's OpenAPI spec via `@hey-api/openapi-ts`. All request bodies, query params, and responses are typed end-to-end — your editor will autocomplete every endpoint.
+
+## License
+
+MIT

package/dist/api.d.ts

@@ -0,0 +1,118 @@
+export type DropstoneTier = "dropstone-fast" | "dropstone-pro" | "dropstone-heavy";
+export interface DropstoneApiOptions {
+    /**
+     * API key in the form `dsk_live_...`. Generate one at
+     * https://dropstone.io/dashboard/settings (API tab).
+     * Falls back to `process.env.DROPSTONE_API_KEY` if omitted.
+     */
+    apiKey?: string;
+    /**
+     * Override the base URL. Default `https://api.dropstone.io/api/v1`.
+     * Only useful for testing against a local server.
+     */
+    baseUrl?: string;
+    /**
+     * Custom fetch — useful for retries / instrumentation / proxies.
+     */
+    fetch?: typeof fetch;
+}
+export interface ChatMessage {
+    role: "system" | "user" | "assistant" | "tool";
+    content: string;
+    name?: string;
+    tool_call_id?: string;
+    tool_calls?: Array<{
+        id: string;
+        type: "function";
+        function: {
+            name: string;
+            arguments: string;
+        };
+    }>;
+}
+export interface ChatCompletionRequest {
+    model: DropstoneTier;
+    messages: ChatMessage[];
+    stream?: boolean;
+    temperature?: number;
+    top_p?: number;
+    max_tokens?: number;
+    stop?: string | string[];
+    tools?: any[];
+    tool_choice?: any;
+    /** Any additional OpenAI-compatible field; passed through verbatim. */
+    [k: string]: any;
+}
+export interface ChatCompletionUsage {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+    /** USD amount billed (real upstream cost × 1.3 markup). */
+    cost?: number;
+}
+export interface ChatCompletionResponse {
+    id: string;
+    object: "chat.completion";
+    created: number;
+    model: DropstoneTier;
+    choices: Array<{
+        index: number;
+        message: {
+            role: string;
+            content: string | null;
+            tool_calls?: any[];
+        };
+        finish_reason: string | null;
+    }>;
+    usage?: ChatCompletionUsage;
+}
+export interface ModelListResponse {
+    object: "list";
+    data: Array<{
+        id: DropstoneTier;
+        object: "model";
+        display_name: string;
+        owned_by: string;
+    }>;
+}
+export interface InsufficientCreditsError {
+    status: 402;
+    balance: number;
+    message: string;
+    topUpUrl: string;
+}
+export declare class DropstoneApiError extends Error {
+    status: number;
+    body: any;
+    constructor(status: number, body: any, message?: string);
+}
+/**
+ * Create a Dropstone HTTP API client. Reads `DROPSTONE_API_KEY` from env
+ * unless `apiKey` is passed explicitly.
+ *
+ * ```ts
+ * const dropstone = createDropstoneApi()
+ * const resp = await dropstone.chat.completions.create({
+ *   model: "dropstone-fast",
+ *   messages: [{ role: "user", content: "Hello" }],
+ * })
+ * console.log(resp.choices[0].message.content)
+ * ```
+ */
+export declare function createDropstoneApi(options?: DropstoneApiOptions): {
+    chat: {
+        completions: {
+            create: {
+                (req: ChatCompletionRequest & {
+                    stream?: false;
+                }): Promise<ChatCompletionResponse>;
+                (req: ChatCompletionRequest & {
+                    stream: true;
+                }): Promise<AsyncIterable<any>>;
+            };
+        };
+    };
+    models: {
+        list: () => Promise<ModelListResponse>;
+    };
+};

package/dist/api.js

@@ -0,0 +1,125 @@
+// Headless API client for the Dropstone public HTTP API.
+//
+// This is the surface for CI, automation, serverless, and any other
+// context where there is no interactive `dropstone` install. It does
+// NOT spawn a local `dropstone serve` subprocess (that's what
+// `createDropstone()` in index.ts does). It talks straight to
+// https://api.dropstone.io/api/v1 with a `DROPSTONE_API_KEY` bearer.
+//
+// Surface mirrors the OpenAI SDK ergonomics so users can drop us in
+// behind the OpenAI client if they prefer; we just give a slightly
+// nicer wrapper with `usage.cost` typed.
+const DEFAULT_BASE_URL = "https://api.dropstone.io/api/v1";
+export class DropstoneApiError extends Error {
+    status;
+    body;
+    constructor(status, body, message) {
+        super(message ?? body?.error?.message ?? body?.message ?? `Dropstone API error ${status}`);
+        this.name = "DropstoneApiError";
+        this.status = status;
+        this.body = body;
+    }
+}
+/**
+ * Create a Dropstone HTTP API client. Reads `DROPSTONE_API_KEY` from env
+ * unless `apiKey` is passed explicitly.
+ *
+ * ```ts
+ * const dropstone = createDropstoneApi()
+ * const resp = await dropstone.chat.completions.create({
+ *   model: "dropstone-fast",
+ *   messages: [{ role: "user", content: "Hello" }],
+ * })
+ * console.log(resp.choices[0].message.content)
+ * ```
+ */
+export function createDropstoneApi(options = {}) {
+    const apiKey = options.apiKey ??
+        (typeof process !== "undefined" ? process.env.DROPSTONE_API_KEY : undefined);
+    if (!apiKey) {
+        throw new Error("DROPSTONE_API_KEY is not set. Pass `apiKey` to createDropstoneApi() " +
+            "or set the DROPSTONE_API_KEY environment variable. " +
+            "Generate a key at https://dropstone.io/dashboard/settings");
+    }
+    const baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    const fetchImpl = options.fetch ?? fetch;
+    // Shared headers builder — keeps Bearer + UA in one place.
+    const buildHeaders = (extra) => ({
+        Authorization: `Bearer ${apiKey}`,
+        "Content-Type": "application/json",
+        "User-Agent": "@blankline/dropstone-sdk",
+        ...(extra ?? {}),
+    });
+    // Standardized error path so 402 (insufficient credits) is easy to
+    // detect — every consumer should special-case it to show a top-up CTA.
+    const parseError = async (res) => {
+        let body = null;
+        try {
+            body = await res.json();
+        }
+        catch {
+            try {
+                body = { error: { message: await res.text() } };
+            }
+            catch {
+                body = { error: { message: res.statusText } };
+            }
+        }
+        return new DropstoneApiError(res.status, body);
+    };
+    async function listModels() {
+        const res = await fetchImpl(`${baseUrl}/models`, { headers: buildHeaders() });
+        if (!res.ok)
+            throw await parseError(res);
+        return (await res.json());
+    }
+    async function createChatCompletion(req) {
+        const res = await fetchImpl(`${baseUrl}/chat/completions`, {
+            method: "POST",
+            headers: buildHeaders(),
+            body: JSON.stringify(req),
+        });
+        if (!res.ok)
+            throw await parseError(res);
+        // Non-streaming branch: just parse and return the OpenAI-shaped JSON.
+        if (!req.stream) {
+            return (await res.json());
+        }
+        // Streaming branch: yield each SSE `data: ` chunk parsed as JSON.
+        // Consumers can do `for await (const chunk of stream) { ... }`.
+        if (!res.body)
+            throw new DropstoneApiError(500, null, "Empty response body");
+        const reader = res.body.getReader();
+        const decoder = new TextDecoder();
+        return (async function* () {
+            let buf = "";
+            while (true) {
+                const { value, done } = await reader.read();
+                if (done)
+                    break;
+                buf += decoder.decode(value, { stream: true });
+                const lines = buf.split("\n");
+                buf = lines.pop() ?? "";
+                for (const raw of lines) {
+                    if (!raw.startsWith("data: "))
+                        continue;
+                    const payload = raw.slice(6).trim();
+                    if (!payload || payload === "[DONE]")
+                        continue;
+                    try {
+                        yield JSON.parse(payload);
+                    }
+                    catch {
+                        // Ignore partial JSON — should not happen with proper SSE framing.
+                    }
+                }
+            }
+        })();
+    }
+    return {
+        chat: {
+            completions: { create: createChatCompletion },
+        },
+        models: { list: listModels },
+    };
+}

package/dist/client.d.ts

@@ -0,0 +1,7 @@
+export * from "./gen/types.gen.js";
+import { type Config } from "./gen/client/types.gen.js";
+import { DropstoneClient } from "./gen/sdk.gen.js";
+export { type Config as DropstoneClientConfig, DropstoneClient };
+export declare function createDropstoneClient(config?: Config & {
+    directory?: string;
+}): DropstoneClient;

package/dist/client.js

@@ -0,0 +1,51 @@
+export * from "./gen/types.gen.js";
+import { createClient } from "./gen/client/client.gen.js";
+import { DropstoneClient } from "./gen/sdk.gen.js";
+export { DropstoneClient };
+function pick(value, fallback) {
+    if (!value)
+        return;
+    if (!fallback)
+        return value;
+    if (value === fallback)
+        return fallback;
+    if (value === encodeURIComponent(fallback))
+        return fallback;
+    return value;
+}
+function rewrite(request, directory) {
+    if (request.method !== "GET" && request.method !== "HEAD")
+        return request;
+    const value = pick(request.headers.get("x-dropstone-directory"), directory);
+    if (!value)
+        return request;
+    const url = new URL(request.url);
+    if (!url.searchParams.has("directory")) {
+        url.searchParams.set("directory", value);
+    }
+    const next = new Request(url, request);
+    next.headers.delete("x-dropstone-directory");
+    return next;
+}
+export function createDropstoneClient(config) {
+    if (!config?.fetch) {
+        const customFetch = (req) => {
+            // @ts-ignore
+            req.timeout = false;
+            return fetch(req);
+        };
+        config = {
+            ...config,
+            fetch: customFetch,
+        };
+    }
+    if (config?.directory) {
+        config.headers = {
+            ...config.headers,
+            "x-dropstone-directory": encodeURIComponent(config.directory),
+        };
+    }
+    const client = createClient(config);
+    client.interceptors.request.use((request) => rewrite(request, config?.directory));
+    return new DropstoneClient({ client });
+}

package/dist/gen/client/client.gen.d.ts

@@ -0,0 +1,2 @@
+import type { Client, Config } from "./types.gen.js";
+export declare const createClient: (config?: Config) => Client;

package/dist/gen/client/client.gen.js

@@ -0,0 +1,165 @@
+// This file is auto-generated by @hey-api/openapi-ts
+import { createSseClient } from "../core/serverSentEvents.gen.js";
+import { buildUrl, createConfig, createInterceptors, getParseAs, mergeConfigs, mergeHeaders, setAuthParams, } from "./utils.gen.js";
+export const createClient = (config = {}) => {
+    let _config = mergeConfigs(createConfig(), config);
+    const getConfig = () => ({ ..._config });
+    const setConfig = (config) => {
+        _config = mergeConfigs(_config, config);
+        return getConfig();
+    };
+    const interceptors = createInterceptors();
+    const beforeRequest = async (options) => {
+        const opts = {
+            ..._config,
+            ...options,
+            fetch: options.fetch ?? _config.fetch ?? globalThis.fetch,
+            headers: mergeHeaders(_config.headers, options.headers),
+            serializedBody: undefined,
+        };
+        if (opts.security) {
+            await setAuthParams({
+                ...opts,
+                security: opts.security,
+            });
+        }
+        if (opts.requestValidator) {
+            await opts.requestValidator(opts);
+        }
+        if (opts.body && opts.bodySerializer) {
+            opts.serializedBody = opts.bodySerializer(opts.body);
+        }
+        // remove Content-Type header if body is empty to avoid sending invalid requests
+        if (opts.serializedBody === undefined || opts.serializedBody === "") {
+            opts.headers.delete("Content-Type");
+        }
+        const url = buildUrl(opts);
+        return { opts, url };
+    };
+    const request = async (options) => {
+        // @ts-expect-error
+        const { opts, url } = await beforeRequest(options);
+        const requestInit = {
+            redirect: "follow",
+            ...opts,
+            body: opts.serializedBody,
+        };
+        let request = new Request(url, requestInit);
+        for (const fn of interceptors.request._fns) {
+            if (fn) {
+                request = await fn(request, opts);
+            }
+        }
+        // fetch must be assigned here, otherwise it would throw the error:
+        // TypeError: Failed to execute 'fetch' on 'Window': Illegal invocation
+        const _fetch = opts.fetch;
+        let response = await _fetch(request);
+        for (const fn of interceptors.response._fns) {
+            if (fn) {
+                response = await fn(response, request, opts);
+            }
+        }
+        const result = {
+            request,
+            response,
+        };
+        if (response.ok) {
+            if (response.status === 204 || response.headers.get("Content-Length") === "0") {
+                return opts.responseStyle === "data"
+                    ? {}
+                    : {
+                        data: {},
+                        ...result,
+                    };
+            }
+            const parseAs = (opts.parseAs === "auto" ? getParseAs(response.headers.get("Content-Type")) : opts.parseAs) ?? "json";
+            let data;
+            switch (parseAs) {
+                case "arrayBuffer":
+                case "blob":
+                case "formData":
+                case "json":
+                case "text":
+                    data = await response[parseAs]();
+                    break;
+                case "stream":
+                    return opts.responseStyle === "data"
+                        ? response.body
+                        : {
+                            data: response.body,
+                            ...result,
+                        };
+            }
+            if (parseAs === "json") {
+                if (opts.responseValidator) {
+                    await opts.responseValidator(data);
+                }
+                if (opts.responseTransformer) {
+                    data = await opts.responseTransformer(data);
+                }
+            }
+            return opts.responseStyle === "data"
+                ? data
+                : {
+                    data,
+                    ...result,
+                };
+        }
+        const textError = await response.text();
+        let jsonError;
+        try {
+            jsonError = JSON.parse(textError);
+        }
+        catch {
+            // noop
+        }
+        const error = jsonError ?? textError;
+        let finalError = error;
+        for (const fn of interceptors.error._fns) {
+            if (fn) {
+                finalError = (await fn(error, response, request, opts));
+            }
+        }
+        finalError = finalError || {};
+        if (opts.throwOnError) {
+            throw finalError;
+        }
+        // TODO: we probably want to return error and improve types
+        return opts.responseStyle === "data"
+            ? undefined
+            : {
+                error: finalError,
+                ...result,
+            };
+    };
+    const makeMethod = (method) => {
+        const fn = (options) => request({ ...options, method });
+        fn.sse = async (options) => {
+            const { opts, url } = await beforeRequest(options);
+            return createSseClient({
+                ...opts,
+                body: opts.body,
+                headers: opts.headers,
+                method,
+                url,
+            });
+        };
+        return fn;
+    };
+    return {
+        buildUrl,
+        connect: makeMethod("CONNECT"),
+        delete: makeMethod("DELETE"),
+        get: makeMethod("GET"),
+        getConfig,
+        head: makeMethod("HEAD"),
+        interceptors,
+        options: makeMethod("OPTIONS"),
+        patch: makeMethod("PATCH"),
+        post: makeMethod("POST"),
+        put: makeMethod("PUT"),
+        request,
+        setConfig,
+        trace: makeMethod("TRACE"),
+    };
+};

package/dist/gen/client/index.d.ts

@@ -0,0 +1,7 @@
+export type { Auth } from "../core/auth.gen.js";
+export type { QuerySerializerOptions } from "../core/bodySerializer.gen.js";
+export { formDataBodySerializer, jsonBodySerializer, urlSearchParamsBodySerializer, } from "../core/bodySerializer.gen.js";
+export { buildClientParams } from "../core/params.gen.js";
+export { createClient } from "./client.gen.js";
+export type { Client, ClientOptions, Config, CreateClientConfig, Options, OptionsLegacyParser, RequestOptions, RequestResult, ResolvedRequestOptions, ResponseStyle, TDataShape, } from "./types.gen.js";
+export { createConfig, mergeHeaders } from "./utils.gen.js";

package/dist/gen/client/index.js

@@ -0,0 +1,5 @@
+// This file is auto-generated by @hey-api/openapi-ts
+export { formDataBodySerializer, jsonBodySerializer, urlSearchParamsBodySerializer, } from "../core/bodySerializer.gen.js";
+export { buildClientParams } from "../core/params.gen.js";
+export { createClient } from "./client.gen.js";
+export { createConfig, mergeHeaders } from "./utils.gen.js";