@databob/sdk 0.0.0-stage → 0.0.2

package/dist/mcp.js

@@ -0,0 +1,307 @@
+// `databob mcp`: a Model Context Protocol server on stdio, so a coding agent
+// working in this repo can read the schema, check it, query local or cloud
+// data, record test events, and deploy.
+//
+//   claude mcp add databob -- npx databob mcp
+//
+// Newline-delimited JSON-RPC 2.0. Nothing but protocol messages is written to
+// stdout; logs go to stderr.
+import { createRequire } from "node:module";
+import { createInterface } from "node:readline";
+import { QUERY_LANGUAGE } from "@databob/engine";
+import { ProjectLoadError, loadProject, paths } from "./project.js";
+import { cloudSettings, deployProject, openLocal, trackLocal } from "./ops.js";
+import { Databob } from "./server.js";
+export const PROTOCOL_VERSIONS = ["2025-06-18", "2025-03-26", "2024-11-05"];
+const INSTRUCTIONS = `databob is analytics defined in code. databob/schema.ts lists events and their properties; databob/metrics.ts holds named queries.
+Start with describe. Edit those two files with your own file tools, then run check. Query with target "local" for data recorded by \`databob dev\`, or "cloud" for the deployed app. Record test events with track_test_event (local only). Deploy only when the user asks.
+databob refuses personal data: no emails, IP addresses, phone numbers, or names in properties. Pass user ids as the user field; they are hashed.`;
+const READ_OPTIONS = {
+    tenant: { type: "string", description: "Tenant id. Required when the schema has tenants." },
+    timeZone: { type: "string", description: 'IANA time zone for time buckets, e.g. "America/New_York". Default UTC.' },
+    compare: { type: "boolean", description: "Also return the same-length period just before." },
+    target: {
+        type: "string",
+        enum: ["local", "cloud"],
+        description: 'local: data recorded by `databob dev` in .databob/. cloud: the deployed app at DATABOB_URL. Default "local".',
+    },
+};
+export const TOOLS = [
+    {
+        name: "describe",
+        title: "Describe the analytics project",
+        description: "The events, properties, and metrics defined in databob/, whether a cloud app is configured, and a reference for the JSON query language. Call this first.",
+        inputSchema: { type: "object", properties: {}, additionalProperties: false },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    },
+    {
+        name: "check",
+        title: "Check the schema and metrics",
+        description: "Validate databob/schema.ts and databob/metrics.ts. Returns every problem, or ok. Run it after editing either file.",
+        inputSchema: { type: "object", properties: {}, additionalProperties: false },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    },
+    {
+        name: "query_metric",
+        title: "Run a named metric",
+        description: "Run a metric defined in databob/metrics.ts and return its rows (or funnel steps).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                metric: { type: "string", description: "The metric's export name." },
+                args: { type: "object", description: 'The metric\'s arguments, e.g. { "range": "7d" }.' },
+                ...READ_OPTIONS,
+            },
+            required: ["metric"],
+            additionalProperties: false,
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    },
+    {
+        name: "query",
+        title: "Run an ad hoc query",
+        description: "Run a JSON query that is not a saved metric. describe returns the query language. Use it to explore data or to try a metric before adding it to metrics.ts.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: { type: "object", description: 'A query with kind "aggregate" or "funnel".' },
+                ...READ_OPTIONS,
+            },
+            required: ["query"],
+            additionalProperties: false,
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    },
+    {
+        name: "track_test_event",
+        title: "Record a test event locally",
+        description: "Record one event in local dev data (never the cloud), to check instrumentation or to give a new metric something to show. Refused events come back with the reason.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: { type: "string", description: "Event name from the schema." },
+                props: { type: "object", description: "Event properties." },
+                tenant: { type: "string" },
+                user: { type: "string", description: "A user id. Stored as a keyed hash." },
+                ts: { type: "string", description: "ISO time. Default now." },
+            },
+            required: ["name"],
+            additionalProperties: false,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    },
+    {
+        name: "deploy",
+        title: "Deploy to databob cloud",
+        description: "Ship databob/schema.ts and databob/metrics.ts to the cloud app at DATABOB_URL with DATABOB_DEPLOY_KEY. Events not in the new schema are refused from then on. Only deploy when the user asks.",
+        inputSchema: { type: "object", properties: {}, additionalProperties: false },
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
+    },
+];
+class ToolError extends Error {
+}
+function readOptions(input) {
+    const options = {};
+    if (input.tenant !== undefined) {
+        if (typeof input.tenant !== "string")
+            throw new ToolError("tenant must be a string");
+        options.tenant = input.tenant;
+    }
+    if (input.timeZone !== undefined) {
+        if (typeof input.timeZone !== "string")
+            throw new ToolError("timeZone must be a string");
+        options.timeZone = input.timeZone;
+    }
+    if (input.compare === true)
+        options.compare = "previous";
+    return options;
+}
+function target(input) {
+    if (input.target === undefined)
+        return "local";
+    if (input.target === "local" || input.target === "cloud")
+        return input.target;
+    throw new ToolError('target is "local" or "cloud"');
+}
+function objectArg(input, name, required) {
+    const value = input[name];
+    if (value === undefined) {
+        if (required)
+            throw new ToolError(`${name} is required`);
+        return undefined;
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        throw new ToolError(`${name} must be an object`);
+    return value;
+}
+export function createMcpHandler(options) {
+    const p = paths(options.root);
+    const version = (() => {
+        try {
+            return createRequire(import.meta.url)("../package.json").version;
+        }
+        catch {
+            return "0.0.0";
+        }
+    })();
+    async function project() {
+        return loadProject(p);
+    }
+    function cloudClient() {
+        const cloud = cloudSettings(p.root);
+        if (!cloud.url || !cloud.secretKey) {
+            throw new ToolError("No cloud app is configured. Set DATABOB_URL and DATABOB_SECRET_KEY (or use target local).");
+        }
+        const clientOptions = { url: cloud.url, secretKey: cloud.secretKey, strict: true };
+        if (options.fetch)
+            clientOptions.fetch = options.fetch;
+        return new Databob(clientOptions);
+    }
+    async function run(name, input) {
+        switch (name) {
+            case "describe": {
+                const loaded = await project();
+                const cloud = cloudSettings(p.root);
+                return {
+                    schema: loaded.schema,
+                    metrics: loaded.metrics,
+                    problems: loaded.problems,
+                    cloud: { url: cloud.url, secretKey: cloud.secretKey !== null, deployKey: cloud.deployKey !== null },
+                    files: { schema: "databob/schema.ts", metrics: "databob/metrics.ts" },
+                    queryLanguage: QUERY_LANGUAGE,
+                };
+            }
+            case "check": {
+                const loaded = await project();
+                return {
+                    ok: loaded.problems.length === 0,
+                    problems: loaded.problems,
+                    events: Object.keys(loaded.schema.events).length,
+                    metrics: Object.keys(loaded.metrics).length,
+                };
+            }
+            case "query_metric":
+            case "query": {
+                const read = readOptions(input);
+                const where = target(input);
+                if (name === "query_metric" && typeof input.metric !== "string")
+                    throw new ToolError("metric is required");
+                const args = objectArg(input, "args", false) ?? {};
+                const query = name === "query" ? objectArg(input, "query", true) : null;
+                if (where === "cloud") {
+                    const client = cloudClient();
+                    const result = query ? await client.queryJson(query, read) : await client.metric({ name: String(input.metric) }, args, read);
+                    return { target: "cloud", result };
+                }
+                const loaded = await project();
+                if (loaded.problems.length > 0)
+                    throw new ToolError(`Fix these first:\n${loaded.problems.join("\n")}`);
+                const local = openLocal(p, loaded);
+                try {
+                    const result = query
+                        ? await local.engine.query(local.project, query, read)
+                        : await local.engine.metric(local.project, String(input.metric), args, read);
+                    return { target: "local", result };
+                }
+                finally {
+                    local.tenants.close();
+                }
+            }
+            case "track_test_event": {
+                if (typeof input.name !== "string")
+                    throw new ToolError("name is required");
+                const event = { name: input.name, props: objectArg(input, "props", false) ?? {} };
+                for (const key of ["tenant", "user", "ts"]) {
+                    if (input[key] !== undefined)
+                        event[key] = input[key];
+                }
+                const loaded = await project();
+                if (loaded.problems.length > 0)
+                    throw new ToolError(`Fix these first:\n${loaded.problems.join("\n")}`);
+                return await trackLocal(p, loaded, [event]);
+            }
+            case "deploy": {
+                const result = await deployProject(await project(), cloudSettings(p.root), options.fetch);
+                if (!result.ok) {
+                    throw new ToolError(`${result.message}${result.problems ? `\n${result.problems.join("\n")}` : ""}`);
+                }
+                return result;
+            }
+            default:
+                throw new ToolError(`Unknown tool "${name}"`);
+        }
+    }
+    async function callTool(params) {
+        const name = typeof params.name === "string" ? params.name : "";
+        const input = (params.arguments ?? {});
+        try {
+            const result = await run(name, input);
+            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }], structuredContent: result };
+        }
+        catch (error) {
+            const message = error instanceof ToolError || error instanceof ProjectLoadError || error instanceof Error ? error.message : String(error);
+            return { content: [{ type: "text", text: message }], isError: true };
+        }
+    }
+    // Answers one JSON-RPC message. Returns null for notifications.
+    return async function handle(message) {
+        if (typeof message !== "object" || message === null || Array.isArray(message)) {
+            return { jsonrpc: "2.0", id: null, error: { code: -32600, message: "Invalid request" } };
+        }
+        const { id, method, params } = message;
+        const isNotification = id === undefined;
+        const reply = (result) => (isNotification ? null : { jsonrpc: "2.0", id, result });
+        const fail = (code, text) => isNotification ? null : { jsonrpc: "2.0", id, error: { code, message: text } };
+        switch (method) {
+            case "initialize": {
+                const requested = typeof params?.protocolVersion === "string" ? params.protocolVersion : "";
+                const protocolVersion = PROTOCOL_VERSIONS.includes(requested) ? requested : PROTOCOL_VERSIONS[0];
+                return reply({
+                    protocolVersion,
+                    capabilities: { tools: { listChanged: false } },
+                    serverInfo: { name: "databob", title: "databob", version },
+                    instructions: INSTRUCTIONS,
+                });
+            }
+            case "notifications/initialized":
+            case "notifications/cancelled":
+                return null;
+            case "ping":
+                return reply({});
+            case "tools/list":
+                return reply({ tools: TOOLS });
+            case "tools/call":
+                return reply(await callTool(params ?? {}));
+            default:
+                return fail(-32601, `Method not found: ${String(method)}`);
+        }
+    };
+}
+export async function serveMcp(options, input = process.stdin, output = process.stdout) {
+    // stdout carries protocol messages only.
+    console.log = console.error;
+    console.info = console.error;
+    console.warn = console.error;
+    const handle = createMcpHandler(options);
+    const lines = createInterface({ input, crlfDelay: Infinity });
+    const pending = new Set();
+    for await (const line of lines) {
+        if (line.trim() === "")
+            continue;
+        let message;
+        try {
+            message = JSON.parse(line);
+        }
+        catch {
+            output.write(`${JSON.stringify({ jsonrpc: "2.0", id: null, error: { code: -32700, message: "Parse error" } })}\n`);
+            continue;
+        }
+        const job = handle(message).then((response) => {
+            if (response)
+                output.write(`${JSON.stringify(response)}\n`);
+        });
+        pending.add(job);
+        void job.finally(() => pending.delete(job));
+    }
+    await Promise.all(pending);
+}

package/dist/ops.d.ts

@@ -0,0 +1,33 @@
+import { Engine, type ProjectConfig, type TrackResult } from "@databob/engine";
+import { LocalTenants } from "@databob/engine/node";
+import { type LoadedProject, type Paths } from "./project.js";
+export declare function loadEnvFiles(root: string): void;
+export declare function isLocalUrl(url: string): boolean;
+export type CloudSettings = {
+    url: string | null;
+    secretKey: string | null;
+    deployKey: string | null;
+};
+export declare function cloudSettings(root: string, urlOverride?: string): CloudSettings;
+export type DeployResult = {
+    ok: true;
+    version: number;
+    events: number;
+    metrics: number;
+    url: string;
+} | {
+    ok: false;
+    status: number;
+    message: string;
+    problems?: string[];
+};
+export declare function deployProject(loaded: LoadedProject, cloud: CloudSettings, fetchImpl?: typeof fetch): Promise<DeployResult>;
+export type LocalData = {
+    engine: Engine;
+    project: ProjectConfig;
+    tenants: LocalTenants;
+};
+export declare function openLocal(p: Paths, loaded: LoadedProject): LocalData;
+export declare function trackLocal(p: Paths, loaded: LoadedProject, events: Record<string, unknown>[], port?: number): Promise<TrackResult & {
+    via: "dev server" | "local data";
+}>;

package/dist/ops.js

@@ -0,0 +1,102 @@
+// Operations shared by the CLI and the MCP server. Nothing here prints: each
+// function returns a result, and the caller decides how to show it.
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseEnv } from "node:util";
+import { Engine } from "@databob/engine";
+import { LocalTenants } from "@databob/engine/node";
+import { devState, projectConfig } from "./project.js";
+// Reads .env.local and .env without overriding variables already set.
+export function loadEnvFiles(root) {
+    for (const name of [".env.local", ".env"]) {
+        const file = join(root, name);
+        if (!existsSync(file))
+            continue;
+        const parsed = parseEnv(readFileSync(file, "utf8"));
+        for (const [key, value] of Object.entries(parsed)) {
+            if (process.env[key] === undefined && value !== undefined)
+                process.env[key] = value;
+        }
+    }
+}
+export function isLocalUrl(url) {
+    return /^https?:\/\/(127\.0\.0\.1|localhost|\[::1\])(:|\/|$)/.test(url);
+}
+// The cloud app this project deploys to, from the environment or .env.local.
+export function cloudSettings(root, urlOverride) {
+    loadEnvFiles(root);
+    const url = (urlOverride ?? process.env.DATABOB_URL ?? "").replace(/\/+$/, "");
+    return {
+        url: url === "" || isLocalUrl(url) ? null : url,
+        secretKey: process.env.DATABOB_SECRET_KEY?.startsWith("dbsk_") ? process.env.DATABOB_SECRET_KEY : null,
+        deployKey: process.env.DATABOB_DEPLOY_KEY?.startsWith("dbdk_") ? process.env.DATABOB_DEPLOY_KEY : null,
+    };
+}
+export async function deployProject(loaded, cloud, fetchImpl = fetch) {
+    if (!cloud.url) {
+        return {
+            ok: false,
+            status: 0,
+            message: "Set DATABOB_URL to your databob cloud URL. `databob dev` reloads by itself and needs no deploy.",
+        };
+    }
+    if (!cloud.deployKey) {
+        return {
+            ok: false,
+            status: 0,
+            message: "Set DATABOB_DEPLOY_KEY to the app's deploy key (dbdk_...). The dashboard shows it once.",
+        };
+    }
+    if (loaded.problems.length > 0) {
+        return { ok: false, status: 0, message: "Fix the schema and metrics first", problems: loaded.problems };
+    }
+    let response;
+    try {
+        response = await fetchImpl(`${cloud.url}/v1/deploy`, {
+            method: "POST",
+            headers: { authorization: `Bearer ${cloud.deployKey}`, "content-type": "application/json" },
+            body: JSON.stringify({ schema: loaded.schema, metrics: loaded.metrics }),
+        });
+    }
+    catch (error) {
+        return { ok: false, status: 0, message: `Could not reach ${cloud.url}: ${error instanceof Error ? error.message : error}` };
+    }
+    const body = (await response.json().catch(() => ({})));
+    if (!response.ok) {
+        const failed = { ok: false, status: response.status, message: body.message ?? response.statusText };
+        if (body.problems)
+            failed.problems = body.problems;
+        return failed;
+    }
+    return { ok: true, version: body.version ?? 0, events: body.events ?? 0, metrics: body.metrics ?? 0, url: cloud.url };
+}
+// The local dev data in .databob/data. Close `tenants` when done.
+export function openLocal(p, loaded) {
+    const tenants = new LocalTenants({ dir: p.data });
+    return { engine: new Engine(tenants), project: projectConfig(devState(p), loaded), tenants };
+}
+// Records events locally. A running `databob dev` takes them first, so live
+// views see them; without one they are written to .databob/data directly.
+export async function trackLocal(p, loaded, events, port = Number(process.env.DATABOB_PORT ?? 4100)) {
+    const state = devState(p);
+    try {
+        const response = await fetch(`http://127.0.0.1:${port}/v1/track`, {
+            method: "POST",
+            headers: { authorization: `Bearer ${state.secretKey}`, "content-type": "application/json" },
+            body: JSON.stringify({ events }),
+        });
+        const result = (await response.json());
+        if (Array.isArray(result.rejected))
+            return { ...result, via: "dev server" };
+    }
+    catch {
+        // No dev server.
+    }
+    const local = openLocal(p, loaded);
+    try {
+        return { ...(await local.engine.track(local.project, events)), via: "local data" };
+    }
+    finally {
+        local.tenants.close();
+    }
+}

package/dist/project.d.ts

@@ -0,0 +1,31 @@
+import { type MetricJson, type ProjectConfig, type SchemaJson } from "@databob/engine";
+export declare const SOURCE_DIR = "databob";
+export declare const STATE_DIR = ".databob";
+export type Paths = {
+    root: string;
+    source: string;
+    generated: string;
+    state: string;
+    data: string;
+    build: string;
+};
+export declare function paths(root: string): Paths;
+export declare function codegen(p: Paths): string[];
+export declare function scaffold(p: Paths): string[];
+export type LoadedProject = {
+    schema: SchemaJson;
+    metrics: Record<string, MetricJson>;
+    problems: string[];
+};
+export declare class ProjectLoadError extends Error {
+}
+export declare function loadProject(p: Paths): Promise<LoadedProject>;
+export type DevState = {
+    projectId: string;
+    secretKey: string;
+    signingKey: string;
+    userKey: string;
+};
+export declare function devState(p: Paths): DevState;
+export declare function projectConfig(state: DevState, loaded: LoadedProject): ProjectConfig;
+export declare function writeEnv(p: Paths, url: string, secretKey: string): string[];