@databob/sdk 0.0.0-stage → 0.0.1

package/dist/react.d.ts

@@ -0,0 +1,27 @@
+import { type ReactNode } from "react";
+import type { MetricRef, RefArgs, RefResult } from "./api.js";
+type TokenSource = () => Promise<string>;
+export type DatabobProviderProps = {
+    url?: string;
+    token?: string;
+    fetchToken?: TokenSource;
+    children: ReactNode;
+};
+export declare function DatabobProvider({ url, token, fetchToken, children }: DatabobProviderProps): import("react").JSX.Element;
+export type MetricOptions = {
+    live?: boolean;
+    timeZone?: string;
+    compare?: "previous";
+    skip?: boolean;
+};
+export type MetricState<T> = {
+    data: T | undefined;
+    error: Error | undefined;
+    isLoading: boolean;
+};
+export declare class MetricError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare function useMetric<R extends MetricRef>(ref: R, args?: RefArgs<R>, options?: MetricOptions): MetricState<RefResult<R>>;
+export {};

package/dist/react.js

@@ -0,0 +1,133 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+// Read metrics in the browser with an embed token your backend mints.
+//
+//   <DatabobProvider url={process.env.NEXT_PUBLIC_DATABOB_URL} fetchToken={getToken}>
+//     <Dashboard />
+//   </DatabobProvider>
+//
+//   const { data } = useMetric(api.topPages, { range: "7d" }, { live: true });
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState } from "react";
+const DatabobContext = createContext(null);
+export function DatabobProvider({ url, token, fetchToken, children }) {
+    const cached = useRef({ token: token ?? "", pending: null });
+    useEffect(() => {
+        if (token)
+            cached.current.token = token;
+    }, [token]);
+    const getToken = useCallback(async (refresh) => {
+        const state = cached.current;
+        if (!refresh && state.token)
+            return state.token;
+        if (!fetchToken) {
+            if (state.token)
+                return state.token;
+            throw new Error("DatabobProvider needs token or fetchToken");
+        }
+        if (!state.pending) {
+            state.pending = fetchToken().finally(() => {
+                state.pending = null;
+            });
+        }
+        state.token = await state.pending;
+        return state.token;
+    }, [fetchToken]);
+    const value = useMemo(() => ({ url: (url ?? "http://127.0.0.1:4100").replace(/\/+$/, ""), getToken }), [url, getToken]);
+    return _jsx(DatabobContext.Provider, { value: value, children: children });
+}
+export class MetricError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "MetricError";
+    }
+}
+function browserTimeZone() {
+    try {
+        return Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
+    }
+    catch {
+        return "UTC";
+    }
+}
+export function useMetric(ref, args, options = {}) {
+    const context = useContext(DatabobContext);
+    if (!context)
+        throw new Error("useMetric needs a <DatabobProvider> above it");
+    const [state, setState] = useState({ data: undefined, error: undefined, isLoading: !options.skip });
+    const timeZone = options.timeZone ?? browserTimeZone();
+    const key = JSON.stringify([ref.name, args ?? {}, timeZone, options.compare ?? null, options.live === true]);
+    useEffect(() => {
+        if (options.skip)
+            return;
+        let cancelled = false;
+        let source = null;
+        let retry = null;
+        const { url, getToken } = context;
+        const body = { args: args ?? {}, timeZone, ...(options.compare ? { compare: options.compare } : {}) };
+        setState((previous) => ({ ...previous, isLoading: previous.data === undefined }));
+        const fail = (error) => {
+            if (cancelled)
+                return;
+            setState((previous) => ({
+                ...previous,
+                error: error instanceof Error ? error : new Error(String(error)),
+                isLoading: false,
+            }));
+        };
+        const once = async (refresh = false) => {
+            const token = await getToken(refresh);
+            const response = await fetch(`${url}/v1/metrics/${ref.name}`, {
+                method: "POST",
+                headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+                body: JSON.stringify(body),
+            });
+            if (response.status === 401 && !refresh)
+                return once(true);
+            const data = (await response.json());
+            if (!response.ok)
+                throw new MetricError(data.error ?? "error", data.message ?? response.statusText);
+            if (!cancelled)
+                setState({ data: data, error: undefined, isLoading: false });
+        };
+        const subscribe = async (refresh = false) => {
+            const token = await getToken(refresh);
+            if (cancelled)
+                return;
+            const params = new URLSearchParams({ token, args: JSON.stringify(body.args), timeZone });
+            if (options.compare)
+                params.set("compare", options.compare);
+            source = new EventSource(`${url}/v1/metrics/${ref.name}/live?${params}`);
+            source.addEventListener("result", (event) => {
+                if (!cancelled)
+                    setState({ data: JSON.parse(event.data), error: undefined, isLoading: false });
+            });
+            source.addEventListener("failure", (event) => {
+                const parsed = JSON.parse(event.data);
+                fail(new MetricError(parsed.error ?? "error", parsed.message ?? "Live metric failed"));
+            });
+            // The browser retries a dropped stream by itself. A refused one (an
+            // expired token, a restart) closes, so reconnect with a fresh token.
+            source.addEventListener("error", () => {
+                if (cancelled || source?.readyState !== EventSource.CLOSED)
+                    return;
+                retry = setTimeout(() => void subscribe(true).catch(fail), 2000);
+            });
+            source.addEventListener("expired", () => {
+                source?.close();
+                void subscribe(true).catch(fail);
+            });
+        };
+        (options.live ? subscribe() : once()).catch(fail);
+        return () => {
+            cancelled = true;
+            if (retry)
+                clearTimeout(retry);
+            source?.close();
+        };
+        // `key` covers ref, args, and options.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [key, context, options.skip]);
+    return state;
+}

package/dist/server.d.ts

@@ -0,0 +1,62 @@
+import { type AnySchema, type Built, type EventNames, type EventProps, type QueryRoot, type ResultOf, type TrackResult } from "@databob/engine";
+import type { MetricRef, RefArgs, RefResult } from "./api.js";
+export declare const DEFAULT_URL = "http://127.0.0.1:4100";
+export type TrackContext = {
+    tenant?: string;
+    user?: string | number;
+    ts?: Date | number;
+    key?: string;
+};
+export type ReadOptions = {
+    tenant?: string;
+    timeZone?: string;
+    compare?: "previous";
+};
+export type DatabobOptions = {
+    url?: string;
+    secretKey?: string;
+    fetch?: typeof fetch;
+    strict?: boolean;
+};
+export declare class DatabobError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly details?: unknown | undefined;
+    constructor(code: string, message: string, status: number, details?: unknown | undefined);
+}
+type PropsArgs<S extends AnySchema, E extends EventNames<S>> = {} extends EventProps<S, E> ? [props?: EventProps<S, E>, context?: TrackContext] : [props: EventProps<S, E>, context?: TrackContext];
+export type TrackInput<S extends AnySchema> = {
+    [E in EventNames<S>]: {
+        name: E;
+        props?: EventProps<S, E>;
+    } & TrackContext;
+}[EventNames<S>];
+export declare class Databob<S extends AnySchema = AnySchema> {
+    private readonly url;
+    private readonly secretKey;
+    private readonly fetchImpl;
+    private readonly strict;
+    constructor(options?: DatabobOptions);
+    private request;
+    track<E extends EventNames<S>>(name: E, ...[props, context]: PropsArgs<S, E>): Promise<TrackResult>;
+    trackMany(events: TrackInput<S>[]): Promise<TrackResult>;
+    metric<R extends MetricRef>(ref: R, args?: RefArgs<R>, options?: ReadOptions): Promise<RefResult<R>>;
+    query<B extends Built<unknown>>(build: (q: QueryRoot<S>) => B, options?: ReadOptions): Promise<ResultOf<B>>;
+    createToken(options?: {
+        tenant?: string;
+        expiresIn?: number;
+        metrics?: MetricRef[];
+    }): Promise<{
+        token: string;
+        expiresAt: number;
+        tenant: string;
+    }>;
+    deleteUser(userId: string | number): Promise<{
+        erased: number;
+    }>;
+    deleteTenant(tenant: string): Promise<{
+        dropped: boolean;
+    }>;
+    describe(): Promise<unknown>;
+}
+export {};

package/dist/server.js

@@ -0,0 +1,126 @@
+// Server client. It holds the secret key, so never import it in the browser.
+//
+//   import { Databob } from "@databob/sdk/server";
+//   import type { Schema } from "./databob/_generated/server";
+//   const databob = new Databob<Schema>();
+//   await databob.track("signup", { plan: "pro" }, { tenant: org.id, user: user.id });
+import { queryRoot, } from "@databob/engine";
+export const DEFAULT_URL = "http://127.0.0.1:4100";
+export class DatabobError extends Error {
+    code;
+    status;
+    details;
+    constructor(code, message, status, details) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.details = details;
+        this.name = "DatabobError";
+    }
+}
+function env(name) {
+    const value = globalThis.process?.env?.[name];
+    return value === "" ? undefined : value;
+}
+export class Databob {
+    url;
+    secretKey;
+    fetchImpl;
+    strict;
+    constructor(options = {}) {
+        this.url = (options.url ?? env("DATABOB_URL") ?? DEFAULT_URL).replace(/\/+$/, "");
+        this.secretKey = options.secretKey ?? env("DATABOB_SECRET_KEY");
+        this.fetchImpl = options.fetch ?? ((input, init) => fetch(input, init));
+        this.strict = options.strict ?? env("NODE_ENV") !== "production";
+    }
+    async request(method, path, body, allowRejected = false) {
+        if (!this.secretKey) {
+            throw new DatabobError("unauthorized", "Set DATABOB_SECRET_KEY or pass secretKey. `npx databob dev` prints a local one.", 401);
+        }
+        const headers = { authorization: `Bearer ${this.secretKey}` };
+        const init = { method, headers };
+        if (body !== undefined) {
+            init.body = JSON.stringify(body);
+            headers["content-type"] = "application/json";
+        }
+        let response;
+        try {
+            response = await this.fetchImpl(`${this.url}${path}`, init);
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            throw new DatabobError("network", `Could not reach databob at ${this.url} (${reason}). Is \`databob dev\` running?`, 0);
+        }
+        const text = await response.text();
+        let data = {};
+        try {
+            data = text ? JSON.parse(text) : {};
+        }
+        catch {
+            throw new DatabobError("bad_response", `databob answered ${response.status} with a body that is not JSON`, response.status);
+        }
+        const rejectedBatch = allowRejected && response.status === 400 && Array.isArray(data.rejected);
+        if (!response.ok && !rejectedBatch) {
+            const failure = data;
+            throw new DatabobError(failure.error ?? "error", failure.message ?? response.statusText, response.status, data);
+        }
+        return data;
+    }
+    async track(name, ...[props, context]) {
+        return this.trackMany([{ name, props, ...context }]);
+    }
+    async trackMany(events) {
+        const body = {
+            events: events.map(({ ts, props, ...rest }) => ({
+                ...rest,
+                ...(props === undefined ? {} : { props }),
+                ...(ts === undefined ? {} : { ts: ts instanceof Date ? ts.getTime() : ts }),
+            })),
+        };
+        try {
+            const result = await this.request("POST", "/v1/track", body, true);
+            if (result.rejected.length > 0) {
+                const first = result.rejected[0];
+                const message = `databob refused ${result.rejected.length} of ${events.length} event(s). First: ${first.message}`;
+                if (this.strict)
+                    throw new DatabobError(first.error, message, 400, result);
+                console.warn(message);
+            }
+            return result;
+        }
+        catch (error) {
+            if (this.strict)
+                throw error;
+            console.warn(error instanceof Error ? error.message : error);
+            return { accepted: 0, duplicates: 0, rejected: [] };
+        }
+    }
+    metric(ref, args, options = {}) {
+        return this.request("POST", `/v1/metrics/${ref.name}`, { args: args ?? {}, ...options });
+    }
+    // An ad hoc query, built with the same typed builder as metrics.
+    query(build, options = {}) {
+        return this.request("POST", "/v1/query", { query: build(queryRoot()).toJSON(), ...options });
+    }
+    // A short-lived token your frontend uses to read one tenant's metrics.
+    createToken(options = {}) {
+        const body = {};
+        if (options.tenant !== undefined)
+            body.tenant = options.tenant;
+        if (options.expiresIn !== undefined)
+            body.expiresIn = options.expiresIn;
+        if (options.metrics)
+            body.metrics = options.metrics.map((metric) => metric.name);
+        return this.request("POST", "/v1/tokens", body);
+    }
+    // Deletes every event for this user id, in every tenant.
+    deleteUser(userId) {
+        return this.request("DELETE", `/v1/users/${encodeURIComponent(String(userId))}`);
+    }
+    deleteTenant(tenant) {
+        return this.request("DELETE", `/v1/tenants/${encodeURIComponent(tenant)}`);
+    }
+    describe() {
+        return this.request("GET", "/v1/describe");
+    }
+}

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@databob/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1",
+  "description": "Privacy-first product analytics you define in code. Typed events, named metrics, per-tenant data, and live React hooks.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "databob": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
+    }
+  },
+  "engines": {
+    "node": ">=22.13"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@databob/engine": "^0.0.1",
+    "esbuild": "^0.27.0"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}