@bizcore/js 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,129 @@
+/**
+ * The BizCore client for JavaScript (M21).
+ *
+ * ONE DEPENDENCY-FREE FILE OVER `fetch`. A client library for an HTTP API is
+ * mostly a typing exercise plus good errors, and every dependency it takes is
+ * one a customer inherits into their bundle. There are none.
+ *
+ * WHAT THIS CLIENT WILL NOT DO, and it matters more than what it will:
+ *
+ *   * It never holds a personal access token. A PAT authenticates a PERSON
+ *     across every organization they belong to; a browser bundle is the last
+ *     place that belongs. This client takes a PROJECT API KEY, whose blast
+ *     radius is one project — and warns if you hand it a PAT by mistake.
+ *
+ *   * It does not paper over row-level security. If you are acting on behalf
+ *     of one of your own end users, you pass their token and PostgreSQL
+ *     decides what they see. There is no client-side filtering here that could
+ *     be mistaken for a security boundary.
+ *
+ * A KEY IN A BROWSER IS STILL A KEY. Even scoped to one project, an API key
+ * shipped in front-end JavaScript is readable by anyone who opens devtools.
+ * Use `rest:read`-scoped keys for anything public-facing, enable row-level
+ * security, and keep write-capable keys on your server. `createClient` says so
+ * once, out loud, when it sees a write-capable key in a browser.
+ */
+export interface ClientOptions {
+    /** e.g. "https://api.bizcorehq.com". Trailing slash optional. */
+    url?: string;
+    /** A PROJECT API KEY — `bzc_live_…`. Never a personal access token. */
+    key: string;
+    /** Your project's id. */
+    projectId: string;
+    /**
+     * An end user's token, when acting on their behalf. Their claims are bound
+     * to the transaction server-side and your RLS policies apply.
+     */
+    endUserToken?: string;
+    fetch?: typeof globalThis.fetch;
+}
+export declare class BizCoreError extends Error {
+    readonly status: number;
+    readonly detail?: unknown | undefined;
+    constructor(message: string, status: number, detail?: unknown | undefined);
+}
+/** Comparison operators, exactly the ones the server implements. */
+export type Operator = "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "like" | "ilike" | "is" | "in";
+export interface SelectResult<T> {
+    rows: T[];
+    count: number;
+}
+/**
+ * A query against one table.
+ *
+ * Chainable and immutable-ish: each call mutates and returns `this`, which is
+ * the shape people expect from this kind of client. It is only sent when you
+ * await it.
+ */
+declare class Query<T> implements PromiseLike<SelectResult<T>> {
+    private readonly client;
+    private readonly table;
+    private filters;
+    private columns?;
+    private ordering?;
+    private rowLimit?;
+    private rowOffset?;
+    constructor(client: BizCoreClient, table: string);
+    select(columns: string): this;
+    filter(column: string, operator: Operator, value: unknown): this;
+    eq(column: string, value: unknown): this;
+    neq(column: string, value: unknown): this;
+    gt(column: string, value: unknown): this;
+    gte(column: string, value: unknown): this;
+    lt(column: string, value: unknown): this;
+    lte(column: string, value: unknown): this;
+    like(column: string, value: string): this;
+    isNull(column: string): this;
+    in(column: string, values: readonly unknown[]): this;
+    order(column: string, direction?: "asc" | "desc"): this;
+    limit(count: number): this;
+    offset(count: number): this;
+    private queryString;
+    /** Makes the query awaitable without a `.execute()` nobody remembers. */
+    then<R1 = SelectResult<T>, R2 = never>(onfulfilled?: ((value: SelectResult<T>) => R1 | PromiseLike<R1>) | null, onrejected?: ((reason: unknown) => R2 | PromiseLike<R2>) | null): PromiseLike<R1 | R2>;
+    /** The first row, or null. */
+    single(): Promise<T | null>;
+    insert(values: Record<string, unknown> | Record<string, unknown>[]): Promise<SelectResult<T>>;
+    update(values: Record<string, unknown>): Promise<SelectResult<T>>;
+    delete(): Promise<SelectResult<T>>;
+    /**
+     * Refused HERE as well as on the server.
+     *
+     * The server already rejects an unfiltered UPDATE or DELETE, and this is not
+     * a substitute for that — it is a better error, thrown before a round trip,
+     * naming the method that is missing a filter. A forgotten `.eq()` on a
+     * `.delete()` is one keystroke from an empty table.
+     */
+    private requireFilter;
+}
+export declare class BizCoreClient {
+    private readonly url;
+    private readonly key;
+    private readonly projectId;
+    private readonly doFetch;
+    private endUserToken?;
+    constructor(options: ClientOptions);
+    /** Act on behalf of one of your end users. Their RLS policies apply. */
+    asUser(token: string): BizCoreClient;
+    from<T = Record<string, unknown>>(table: string): Query<T>;
+    /** Queue a job — an invocation of one of this project's functions. */
+    enqueue(functionName: string, payload?: Record<string, unknown>): Promise<{
+        id: string;
+        status: string;
+    }>;
+    /** Call one of this project's functions and get its response. */
+    invoke<T = unknown>(functionName: string, payload?: Record<string, unknown>): Promise<T>;
+    private headers;
+    /** @internal */
+    request<T>(method: string, path: string, body?: unknown): Promise<T>;
+}
+/**
+ * Create a client.
+ *
+ * Warns once — not throws — if a write-capable key appears in a browser. It
+ * cannot know your intent (a public read-only app is a legitimate thing), but
+ * a key in front-end JavaScript is readable by anyone who opens devtools, and
+ * somebody should be told that at least once.
+ */
+export declare function createClient(options: ClientOptions): BizCoreClient;
+export { Query };

package/dist/index.js

@@ -0,0 +1,261 @@
+/**
+ * The BizCore client for JavaScript (M21).
+ *
+ * ONE DEPENDENCY-FREE FILE OVER `fetch`. A client library for an HTTP API is
+ * mostly a typing exercise plus good errors, and every dependency it takes is
+ * one a customer inherits into their bundle. There are none.
+ *
+ * WHAT THIS CLIENT WILL NOT DO, and it matters more than what it will:
+ *
+ *   * It never holds a personal access token. A PAT authenticates a PERSON
+ *     across every organization they belong to; a browser bundle is the last
+ *     place that belongs. This client takes a PROJECT API KEY, whose blast
+ *     radius is one project — and warns if you hand it a PAT by mistake.
+ *
+ *   * It does not paper over row-level security. If you are acting on behalf
+ *     of one of your own end users, you pass their token and PostgreSQL
+ *     decides what they see. There is no client-side filtering here that could
+ *     be mistaken for a security boundary.
+ *
+ * A KEY IN A BROWSER IS STILL A KEY. Even scoped to one project, an API key
+ * shipped in front-end JavaScript is readable by anyone who opens devtools.
+ * Use `rest:read`-scoped keys for anything public-facing, enable row-level
+ * security, and keep write-capable keys on your server. `createClient` says so
+ * once, out loud, when it sees a write-capable key in a browser.
+ */
+export class BizCoreError extends Error {
+    status;
+    detail;
+    constructor(message, status, detail) {
+        super(message);
+        this.status = status;
+        this.detail = detail;
+        this.name = "BizCoreError";
+    }
+}
+const DEFAULT_URL = "https://api.bizcorehq.com";
+function inBrowser() {
+    return typeof window !== "undefined" && typeof window.document !== "undefined";
+}
+/**
+ * A query against one table.
+ *
+ * Chainable and immutable-ish: each call mutates and returns `this`, which is
+ * the shape people expect from this kind of client. It is only sent when you
+ * await it.
+ */
+class Query {
+    client;
+    table;
+    filters = [];
+    columns;
+    ordering;
+    rowLimit;
+    rowOffset;
+    constructor(client, table) {
+        this.client = client;
+        this.table = table;
+    }
+    select(columns) {
+        this.columns = columns;
+        return this;
+    }
+    filter(column, operator, value) {
+        this.filters.push({ column, operator, value: String(value) });
+        return this;
+    }
+    eq(column, value) {
+        return this.filter(column, "eq", value);
+    }
+    neq(column, value) {
+        return this.filter(column, "neq", value);
+    }
+    gt(column, value) {
+        return this.filter(column, "gt", value);
+    }
+    gte(column, value) {
+        return this.filter(column, "gte", value);
+    }
+    lt(column, value) {
+        return this.filter(column, "lt", value);
+    }
+    lte(column, value) {
+        return this.filter(column, "lte", value);
+    }
+    like(column, value) {
+        return this.filter(column, "like", value);
+    }
+    isNull(column) {
+        return this.filter(column, "is", "null");
+    }
+    in(column, values) {
+        return this.filter(column, "in", `(${values.map(String).join(",")})`);
+    }
+    order(column, direction = "asc") {
+        this.ordering = `${column}.${direction}`;
+        return this;
+    }
+    limit(count) {
+        this.rowLimit = count;
+        return this;
+    }
+    offset(count) {
+        this.rowOffset = count;
+        return this;
+    }
+    queryString() {
+        const params = new URLSearchParams();
+        for (const filter of this.filters) {
+            params.append(filter.column, `${filter.operator}.${filter.value}`);
+        }
+        if (this.columns)
+            params.set("select", this.columns);
+        if (this.ordering)
+            params.set("order", this.ordering);
+        if (this.rowLimit !== undefined)
+            params.set("limit", String(this.rowLimit));
+        if (this.rowOffset !== undefined)
+            params.set("offset", String(this.rowOffset));
+        const text = params.toString();
+        return text ? `?${text}` : "";
+    }
+    /** Makes the query awaitable without a `.execute()` nobody remembers. */
+    then(onfulfilled, onrejected) {
+        return this.client
+            .request("GET", `/rest/${this.table}${this.queryString()}`)
+            .then(onfulfilled, onrejected);
+    }
+    /** The first row, or null. */
+    async single() {
+        const result = await this.limit(1);
+        return result.rows[0] ?? null;
+    }
+    async insert(values) {
+        return this.client.request("POST", `/rest/${this.table}`, values);
+    }
+    async update(values) {
+        this.requireFilter("update");
+        return this.client.request("PATCH", `/rest/${this.table}${this.queryString()}`, values);
+    }
+    async delete() {
+        this.requireFilter("delete");
+        return this.client.request("DELETE", `/rest/${this.table}${this.queryString()}`);
+    }
+    /**
+     * Refused HERE as well as on the server.
+     *
+     * The server already rejects an unfiltered UPDATE or DELETE, and this is not
+     * a substitute for that — it is a better error, thrown before a round trip,
+     * naming the method that is missing a filter. A forgotten `.eq()` on a
+     * `.delete()` is one keystroke from an empty table.
+     */
+    requireFilter(operation) {
+        if (this.filters.length === 0) {
+            throw new BizCoreError(`Refusing to ${operation} every row in "${this.table}". Add a filter, ` +
+                `e.g. .eq("id", 1). The server refuses this too.`, 400);
+        }
+    }
+}
+export class BizCoreClient {
+    url;
+    key;
+    projectId;
+    doFetch;
+    endUserToken;
+    constructor(options) {
+        this.url = (options.url ?? DEFAULT_URL).replace(/\/$/, "");
+        this.key = options.key;
+        this.projectId = options.projectId;
+        this.endUserToken = options.endUserToken;
+        this.doFetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+        if (this.key.startsWith("bzp_")) {
+            // A PAT reaches everything its owner reaches, in every organization.
+            // Refused rather than warned about: this is not a preference.
+            throw new BizCoreError("That is a personal access token, not a project API key. A personal token " +
+                "authenticates you across every organization you belong to and must never be " +
+                "given to a client library. Use a project key (bzc_live_…).", 400);
+        }
+    }
+    /** Act on behalf of one of your end users. Their RLS policies apply. */
+    asUser(token) {
+        return new BizCoreClient({
+            url: this.url,
+            key: this.key,
+            projectId: this.projectId,
+            endUserToken: token,
+            fetch: this.doFetch,
+        });
+    }
+    from(table) {
+        return new Query(this, table);
+    }
+    /** Queue a job — an invocation of one of this project's functions. */
+    async enqueue(functionName, payload = {}) {
+        return this.request("POST", "/jobs", { function_name: functionName, payload });
+    }
+    /** Call one of this project's functions and get its response. */
+    async invoke(functionName, payload = {}) {
+        const response = await this.doFetch(`${this.url}/fn/${this.projectId}/${functionName}`, {
+            method: "POST",
+            headers: this.headers(),
+            body: JSON.stringify(payload),
+        });
+        if (!response.ok) {
+            throw new BizCoreError(`The function returned ${response.status}.`, response.status);
+        }
+        return (await response.json());
+    }
+    headers() {
+        const headers = {
+            "X-API-Key": this.key,
+            "Content-Type": "application/json",
+        };
+        if (this.endUserToken)
+            headers["Authorization"] = `Bearer ${this.endUserToken}`;
+        return headers;
+    }
+    /** @internal */
+    async request(method, path, body) {
+        const response = await this.doFetch(`${this.url}/v1/projects/${this.projectId}${path}`, {
+            method,
+            headers: this.headers(),
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+        if (!response.ok) {
+            let detail;
+            try {
+                detail = await response.json();
+            }
+            catch {
+                detail = undefined;
+            }
+            const message = detail && typeof detail === "object" && "detail" in detail
+                ? String(detail.detail)
+                : `The API returned ${response.status}.`;
+            throw new BizCoreError(message, response.status, detail);
+        }
+        if (response.status === 204)
+            return undefined;
+        return (await response.json());
+    }
+}
+/**
+ * Create a client.
+ *
+ * Warns once — not throws — if a write-capable key appears in a browser. It
+ * cannot know your intent (a public read-only app is a legitimate thing), but
+ * a key in front-end JavaScript is readable by anyone who opens devtools, and
+ * somebody should be told that at least once.
+ */
+export function createClient(options) {
+    const client = new BizCoreClient(options);
+    if (inBrowser() && !warned) {
+        warned = true;
+        console.warn("[bizcore] This API key is visible to anyone who opens devtools. For anything " +
+            "public-facing, use a key scoped to rest:read and enable row-level security. " +
+            "Keep write-capable keys on your server.");
+    }
+    return client;
+}
+let warned = false;
+export { Query };

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@bizcore/js",
+  "version": "0.1.0",
+  "description": "The BizCore client for JavaScript and TypeScript.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BizCoreHQ/bizcore.git",
+    "directory": "packages/js"
+  },
+  "homepage": "https://docs.bizcorehq.com",
+  "keywords": [
+    "bizcore",
+    "postgres",
+    "postgresql",
+    "database",
+    "backend",
+    "client"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}