@databob/sdk 0.0.0-stage → 0.0.2

package/dist/cli.js

@@ -0,0 +1,302 @@
+#!/usr/bin/env node
+// databob CLI. Every command prints JSON or plain lines, so agents can drive it.
+import { watch } from "node:fs";
+import { createServer } from "node:http";
+import { relative } from "node:path";
+import { Engine, EngineError, createHandler } from "@databob/engine";
+import { LocalTenants, StaticProjects, toNodeListener } from "@databob/engine/node";
+import { ProjectLoadError, codegen, devState, loadProject, paths, projectConfig, scaffold, writeEnv, } from "./project.js";
+import { cloudSettings, deployProject, openLocal, trackLocal } from "./ops.js";
+import { serveMcp } from "./mcp.js";
+const HELP = `databob: typed analytics you define in code
+
+Usage: databob <command> [options]
+
+  init                         Create databob/schema.ts and databob/metrics.ts
+  dev [--port 4100]            Run the local API, watch databob/, regenerate types
+  start [--port 4100]          Self-host in production. Needs DATABOB_SECRET_KEY,
+                               DATABOB_SIGNING_KEY, DATABOB_USER_KEY (32+ chars each)
+  check                        Validate the schema and every metric (exit 1 on problems)
+  deploy [--url URL]           Ship databob/ to databob cloud. Needs DATABOB_URL and
+                               DATABOB_DEPLOY_KEY (environment or .env.local)
+  codegen                      Write databob/_generated
+  describe                     Print the schema and metrics as JSON
+  query <metric> [options]     Run a metric on local data and print JSON
+      --args '{"range":"7d"}'  --tenant <id>  --tz <IANA zone>  --compare
+  track <event> [options]      Record one event locally
+      --props '{"plan":"pro"}' --tenant <id>  --user <id>
+  mcp                          Run the MCP server on stdio, for coding agents:
+                               claude mcp add databob -- npx databob mcp
+
+Data lives in .databob/ (git-ignored). Requires Node 22.13+.`;
+function parse(argv) {
+    const flags = { _: [] };
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (!arg.startsWith("--")) {
+            flags._.push(arg);
+            continue;
+        }
+        const [name, inline] = arg.slice(2).split("=", 2);
+        if (inline !== undefined)
+            flags[name] = inline;
+        else if (argv[index + 1] !== undefined && !argv[index + 1].startsWith("--"))
+            flags[name] = argv[++index];
+        else
+            flags[name] = true;
+    }
+    return flags;
+}
+function str(flags, name) {
+    const value = flags[name];
+    return typeof value === "string" ? value : undefined;
+}
+function jsonFlag(flags, name) {
+    const value = str(flags, name);
+    if (value === undefined)
+        return undefined;
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        throw new Error(`--${name} must be JSON, for example --${name} '{"range":"7d"}'`);
+    }
+}
+function print(value) {
+    process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+async function loadOrExit(p) {
+    const loaded = await loadProject(p);
+    if (loaded.problems.length > 0) {
+        for (const problem of loaded.problems)
+            console.error(`✗ ${problem}`);
+        process.exit(1);
+    }
+    return loaded;
+}
+const MIN_KEY_LENGTH = 32;
+function requiredSecret(name) {
+    const value = process.env[name] ?? "";
+    if (value.length < MIN_KEY_LENGTH) {
+        console.error(`✗ Set ${name} to a random value of at least ${MIN_KEY_LENGTH} characters.`);
+        process.exit(1);
+    }
+    return value;
+}
+// Production self-hosting: no file watching, no generated keys, no .env writes.
+async function start(p, flags) {
+    const port = Number(str(flags, "port") ?? process.env.PORT ?? process.env.DATABOB_PORT ?? 4100);
+    const host = str(flags, "host") ?? process.env.DATABOB_HOST ?? "0.0.0.0";
+    const secretKey = requiredSecret("DATABOB_SECRET_KEY");
+    if (!secretKey.startsWith("dbsk_")) {
+        console.error("✗ DATABOB_SECRET_KEY must start with dbsk_");
+        process.exit(1);
+    }
+    const loaded = await loadOrExit(p);
+    const config = {
+        id: process.env.DATABOB_PROJECT_ID ?? "default",
+        schema: loaded.schema,
+        metrics: loaded.metrics,
+        signingKey: requiredSecret("DATABOB_SIGNING_KEY"),
+        userKey: requiredSecret("DATABOB_USER_KEY"),
+    };
+    const tenants = new LocalTenants({ dir: process.env.DATABOB_DATA_DIR ?? p.data });
+    const handler = createHandler({ projects: new StaticProjects([{ secretKey, config }]), engine: new Engine(tenants) });
+    const server = createServer(toNodeListener(handler));
+    server.listen(port, host, () => {
+        console.log(`databob listening on http://${host}:${port} (${Object.keys(config.metrics).length} metrics)`);
+    });
+    const stop = () => {
+        server.close(() => {
+            tenants.close();
+            process.exit(0);
+        });
+    };
+    process.on("SIGINT", stop);
+    process.on("SIGTERM", stop);
+}
+async function deploy(p, flags) {
+    const cloud = cloudSettings(p.root, str(flags, "url"));
+    const loaded = await loadOrExit(p);
+    const result = await deployProject(loaded, cloud);
+    if (!result.ok) {
+        console.error(`✗ ${result.status ? `Deploy failed (${result.status}): ` : ""}${result.message}`);
+        for (const problem of result.problems ?? [])
+            console.error(`  ✗ ${problem}`);
+        process.exit(1);
+    }
+    console.log(`✓ Deployed version ${result.version}: ${result.events} event(s), ${result.metrics} metric(s) to ${result.url}`);
+}
+async function dev(p, flags) {
+    const port = Number(str(flags, "port") ?? process.env.DATABOB_PORT ?? 4100);
+    const host = str(flags, "host") ?? "127.0.0.1";
+    if (scaffold(p).length > 0)
+        console.log(`Created ${relative(process.cwd(), p.source)}/ with a starter schema and metrics.`);
+    const state = devState(p);
+    let loaded;
+    try {
+        loaded = await loadProject(p);
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+    for (const problem of loaded.problems)
+        console.error(`✗ ${problem}`);
+    const projects = new StaticProjects([{ secretKey: state.secretKey, config: projectConfig(state, loaded) }]);
+    const tenants = new LocalTenants({ dir: p.data });
+    const handler = createHandler({ projects, engine: new Engine(tenants) });
+    const server = createServer(toNodeListener(async (request) => {
+        const url = new URL(request.url);
+        if (url.pathname === "/") {
+            const config = await projects.byId(state.projectId);
+            return Response.json({
+                name: "databob dev",
+                project: state.projectId,
+                events: Object.keys(config?.schema.events ?? {}),
+                metrics: Object.keys(config?.metrics ?? {}),
+                routes: ["POST /v1/track", "POST /v1/metrics/:name", "GET /v1/metrics/:name/live", "POST /v1/query", "POST /v1/tokens", "GET /v1/describe"],
+            });
+        }
+        return handler(request);
+    }));
+    server.on("error", (error) => {
+        console.error(error.code === "EADDRINUSE" ? `Port ${port} is in use. Try --port ${port + 1}.` : error.message);
+        process.exit(1);
+    });
+    server.listen(port, host, () => {
+        const url = `http://${host}:${port}`;
+        const added = writeEnv(p, url, state.secretKey);
+        const events = Object.keys(loaded.schema.events).length;
+        const metrics = Object.keys(loaded.metrics).length;
+        console.log(`databob dev  ${url}`);
+        console.log(`  project  ${state.projectId}: ${events} event(s), ${metrics} metric(s)${loaded.schema.tenants ? ", tenants on" : ""}`);
+        console.log(`  data     ${relative(process.cwd(), p.data) || "."}`);
+        console.log(`  secret   ${state.secretKey}`);
+        if (added.length > 0)
+            console.log(`  env      added ${added.join(", ")} to .env.local`);
+        console.log(`Watching ${relative(process.cwd(), p.source)}/ for changes.`);
+    });
+    let timer = null;
+    const reload = async () => {
+        try {
+            const next = await loadProject(p);
+            if (next.problems.length > 0) {
+                for (const problem of next.problems)
+                    console.error(`✗ ${problem}`);
+                console.error("Keeping the previous schema and metrics until these are fixed.");
+                return;
+            }
+            projects.replace([{ secretKey: state.secretKey, config: projectConfig(state, next) }]);
+            loaded = next;
+            console.log(`✓ Reloaded: ${Object.keys(next.schema.events).length} event(s), ${Object.keys(next.metrics).length} metric(s)`);
+        }
+        catch (error) {
+            console.error(`✗ ${error instanceof Error ? error.message : error}`);
+            console.error("Keeping the previous schema and metrics until this is fixed.");
+        }
+    };
+    watch(p.source, { recursive: true }, (_event, file) => {
+        if (!file || String(file).includes("_generated"))
+            return;
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(() => void reload(), 100);
+    });
+    const stop = () => {
+        tenants.close();
+        server.close();
+        process.exit(0);
+    };
+    process.on("SIGINT", stop);
+    process.on("SIGTERM", stop);
+}
+async function main() {
+    const flags = parse(process.argv.slice(2));
+    const command = flags._[0] ?? "help";
+    const p = paths(process.cwd());
+    switch (command) {
+        case "init": {
+            const created = scaffold(p);
+            console.log(created.length > 0 ? `Created ${created.join(", ")}` : "databob/ already exists. Nothing to create.");
+            console.log("Next: npx databob dev");
+            console.log("Agents: claude mcp add databob -- npx databob mcp");
+            return;
+        }
+        case "dev":
+            return dev(p, flags);
+        case "start":
+            return start(p, flags);
+        case "deploy":
+            return deploy(p, flags);
+        case "mcp":
+            return serveMcp({ root: process.cwd() });
+        case "codegen": {
+            const written = codegen(p);
+            console.log(written.length > 0 ? `Wrote ${written.join(", ")}` : "Generated files are up to date.");
+            return;
+        }
+        case "check": {
+            const loaded = await loadOrExit(p);
+            console.log(`✓ ${Object.keys(loaded.schema.events).length} event(s) and ${Object.keys(loaded.metrics).length} metric(s) are valid`);
+            return;
+        }
+        case "describe": {
+            const loaded = await loadOrExit(p);
+            print({ schema: loaded.schema, metrics: loaded.metrics });
+            return;
+        }
+        case "query": {
+            const name = flags._[1];
+            if (!name)
+                throw new Error("Usage: databob query <metric> [--args JSON] [--tenant id]");
+            const { engine, project, tenants } = openLocal(p, await loadOrExit(p));
+            const options = {};
+            const tenant = str(flags, "tenant");
+            if (tenant)
+                options.tenant = tenant;
+            const tz = str(flags, "tz");
+            if (tz)
+                options.timeZone = tz;
+            if (flags.compare)
+                options.compare = "previous";
+            print(await engine.metric(project, name, jsonFlag(flags, "args") ?? {}, options));
+            tenants.close();
+            return;
+        }
+        case "track": {
+            const name = flags._[1];
+            if (!name)
+                throw new Error("Usage: databob track <event> [--props JSON] [--tenant id] [--user id]");
+            const event = { name, props: jsonFlag(flags, "props") ?? {} };
+            const tenant = str(flags, "tenant");
+            if (tenant)
+                event.tenant = tenant;
+            const user = str(flags, "user");
+            if (user)
+                event.user = user;
+            const port = str(flags, "port");
+            const result = await trackLocal(p, await loadOrExit(p), [event], port ? Number(port) : undefined);
+            print(result);
+            if (result.rejected.length > 0)
+                process.exit(1);
+            return;
+        }
+        case "help":
+        case "--help":
+        case "-h":
+            console.log(HELP);
+            return;
+        default:
+            console.error(`Unknown command "${command}".\n`);
+            console.log(HELP);
+            process.exit(1);
+    }
+}
+main().catch((error) => {
+    if (error instanceof EngineError || error instanceof ProjectLoadError)
+        console.error(`✗ ${error.message}`);
+    else
+        console.error(error instanceof Error ? error.message : error);
+    process.exit(1);
+});

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { v, defineSchema, event, metricFactory, queryRoot, type AggregateResult, type AnySchema, type Cell, type EventNames, type EventProps, type FunnelResult, type FunnelStep, type Infer, type MetricDef, type QueryAst, type QueryResult, type RangeValue, type Schema, } from "@databob/engine";
+export { makeApi, ref, type ApiFromModule, type MetricRef, type RefArgs, type RefResult } from "./api.js";

package/dist/index.js

@@ -0,0 +1,7 @@
+// databob: typed product analytics you define in code.
+//
+//   databob/schema.ts    events and their properties
+//   databob/metrics.ts   named queries your app and your users read
+//   databob/_generated   written by `databob dev`; commit it
+export { v, defineSchema, event, metricFactory, queryRoot, } from "@databob/engine";
+export { makeApi, ref } from "./api.js";

package/dist/mcp.d.ts

@@ -0,0 +1,163 @@
+export declare const PROTOCOL_VERSIONS: readonly ["2025-06-18", "2025-03-26", "2024-11-05"];
+type Json = Record<string, unknown>;
+export type McpOptions = {
+    root: string;
+    fetch?: typeof fetch;
+};
+export declare const TOOLS: readonly [{
+    readonly name: "describe";
+    readonly title: "Describe the analytics project";
+    readonly 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.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {};
+        readonly additionalProperties: false;
+    };
+    readonly annotations: {
+        readonly readOnlyHint: true;
+        readonly openWorldHint: false;
+    };
+}, {
+    readonly name: "check";
+    readonly title: "Check the schema and metrics";
+    readonly description: "Validate databob/schema.ts and databob/metrics.ts. Returns every problem, or ok. Run it after editing either file.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {};
+        readonly additionalProperties: false;
+    };
+    readonly annotations: {
+        readonly readOnlyHint: true;
+        readonly openWorldHint: false;
+    };
+}, {
+    readonly name: "query_metric";
+    readonly title: "Run a named metric";
+    readonly description: "Run a metric defined in databob/metrics.ts and return its rows (or funnel steps).";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly tenant: {
+                readonly type: "string";
+                readonly description: "Tenant id. Required when the schema has tenants.";
+            };
+            readonly timeZone: {
+                readonly type: "string";
+                readonly description: "IANA time zone for time buckets, e.g. \"America/New_York\". Default UTC.";
+            };
+            readonly compare: {
+                readonly type: "boolean";
+                readonly description: "Also return the same-length period just before.";
+            };
+            readonly target: {
+                readonly type: "string";
+                readonly enum: readonly ["local", "cloud"];
+                readonly description: "local: data recorded by `databob dev` in .databob/. cloud: the deployed app at DATABOB_URL. Default \"local\".";
+            };
+            readonly metric: {
+                readonly type: "string";
+                readonly description: "The metric's export name.";
+            };
+            readonly args: {
+                readonly type: "object";
+                readonly description: "The metric's arguments, e.g. { \"range\": \"7d\" }.";
+            };
+        };
+        readonly required: readonly ["metric"];
+        readonly additionalProperties: false;
+    };
+    readonly annotations: {
+        readonly readOnlyHint: true;
+        readonly openWorldHint: true;
+    };
+}, {
+    readonly name: "query";
+    readonly title: "Run an ad hoc query";
+    readonly 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.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly tenant: {
+                readonly type: "string";
+                readonly description: "Tenant id. Required when the schema has tenants.";
+            };
+            readonly timeZone: {
+                readonly type: "string";
+                readonly description: "IANA time zone for time buckets, e.g. \"America/New_York\". Default UTC.";
+            };
+            readonly compare: {
+                readonly type: "boolean";
+                readonly description: "Also return the same-length period just before.";
+            };
+            readonly target: {
+                readonly type: "string";
+                readonly enum: readonly ["local", "cloud"];
+                readonly description: "local: data recorded by `databob dev` in .databob/. cloud: the deployed app at DATABOB_URL. Default \"local\".";
+            };
+            readonly query: {
+                readonly type: "object";
+                readonly description: "A query with kind \"aggregate\" or \"funnel\".";
+            };
+        };
+        readonly required: readonly ["query"];
+        readonly additionalProperties: false;
+    };
+    readonly annotations: {
+        readonly readOnlyHint: true;
+        readonly openWorldHint: true;
+    };
+}, {
+    readonly name: "track_test_event";
+    readonly title: "Record a test event locally";
+    readonly 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.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly name: {
+                readonly type: "string";
+                readonly description: "Event name from the schema.";
+            };
+            readonly props: {
+                readonly type: "object";
+                readonly description: "Event properties.";
+            };
+            readonly tenant: {
+                readonly type: "string";
+            };
+            readonly user: {
+                readonly type: "string";
+                readonly description: "A user id. Stored as a keyed hash.";
+            };
+            readonly ts: {
+                readonly type: "string";
+                readonly description: "ISO time. Default now.";
+            };
+        };
+        readonly required: readonly ["name"];
+        readonly additionalProperties: false;
+    };
+    readonly annotations: {
+        readonly readOnlyHint: false;
+        readonly destructiveHint: false;
+        readonly idempotentHint: false;
+        readonly openWorldHint: false;
+    };
+}, {
+    readonly name: "deploy";
+    readonly title: "Deploy to databob cloud";
+    readonly 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.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {};
+        readonly additionalProperties: false;
+    };
+    readonly annotations: {
+        readonly readOnlyHint: false;
+        readonly destructiveHint: true;
+        readonly idempotentHint: true;
+        readonly openWorldHint: true;
+    };
+}];
+export declare function createMcpHandler(options: McpOptions): (message: unknown) => Promise<Json | null>;
+export declare function serveMcp(options: McpOptions, input?: NodeJS.ReadableStream, output?: NodeJS.WritableStream): Promise<void>;
+export {};