@keeprer/js 0.1.0

package/README.md

@@ -0,0 +1,111 @@
+# @keeprer/js
+
+Official TypeScript / JavaScript client for [Keeprer](https://keeprer.space) — The Lightweight No-Code Database & Headless Backend.
+
+## 📦 Features
+
+- ⚡ **Zero Dependencies**: Powered by native `fetch`.
+- 🛡️ **Full TypeScript Support**: Auto-complete and type inference.
+- 🎯 **Fluent Supabase-style API**: Chain filters like `.eq()`, `.gt()`, `.sort()`, `.limit()`.
+- 🔐 **Scoped API Keys**: Supports `pk_` (publishable/read-only) and `sk_` (secret/read-write).
+
+---
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+npm install @keeprer/js
+# or yarn add @keeprer/js
+# or pnpm add @keeprer/js
+```
+
+### Initialize Client
+
+```typescript
+import { createClient } from "@keeprer/js"
+
+const keeprer = createClient("https://keeprer.space", "pk_xxxxxxxxxxxx")
+```
+
+---
+
+## 📖 Usage Examples
+
+### 1. Query Records (Select & Filter)
+
+```typescript
+// Query products where status is active and price > 100
+const { data, total, error } = await keeprer
+  .from("products")
+  .select()
+  .eq("status", "active")
+  .gt("price", 100)
+  .sort("-created_at")
+  .limit(20)
+
+console.log(data) // [{ id: "...", name: "Shirt", price: 350, ... }]
+```
+
+### 2. Insert Records (Create)
+
+```typescript
+// Insert single row
+const { data: item, error } = await keeprer
+  .from("products")
+  .insert({
+    name: "เสื้อยืด Keeprer",
+    price: 350,
+    status: "in_stock",
+  })
+
+// Batch insert up to 500 rows
+const { data: items } = await keeprer
+  .from("products")
+  .insert([
+    { name: "Item 1", price: 100 },
+    { name: "Item 2", price: 200 },
+  ])
+```
+
+### 3. Update Record (Patch)
+
+```typescript
+const { data: updated, error } = await keeprer
+  .from("products")
+  .update("row_uuid_here", {
+    price: 290,
+  })
+```
+
+### 4. Delete Record (Delete)
+
+```typescript
+const { success, error } = await keeprer
+  .from("products")
+  .delete("row_uuid_here")
+```
+
+### 5. Inspect Schema
+
+```typescript
+const { table, fields } = await keeprer
+  .from("products")
+  .schema()
+```
+
+---
+
+## 🔑 Security Best Practices
+
+- **Frontend (React, Next.js client, Vue, Mobile apps)**:
+  Always use a publishable key starting with `pk_...` or toggle the table to **Public** mode in Keeprer.
+- **Backend (Node.js, Express, Next.js Server Actions, Python)**:
+  Use a secret key starting with `sk_...` kept securely in environment variables.
+
+---
+
+## 📄 License
+
+MIT © Keeprer Team

package/dist/index.d.ts

@@ -0,0 +1,136 @@
+export interface KeeprerClientOptions {
+    baseUrl: string;
+    apiKey?: string;
+    fetch?: typeof globalThis.fetch;
+}
+export interface KeeprerError {
+    message: string;
+    status?: number;
+    code?: string;
+}
+export interface QueryResponse<T = Record<string, unknown>> {
+    data: T[];
+    total: number;
+    hasMore: boolean;
+    cursor: number | null;
+    error: KeeprerError | null;
+}
+export interface SingleResponse<T = Record<string, unknown>> {
+    data: T | null;
+    error: KeeprerError | null;
+}
+export interface DeleteResponse {
+    success: boolean;
+    error: KeeprerError | null;
+}
+export interface ColumnSchema {
+    id: string;
+    name: string;
+    key: string;
+    type: string;
+    options?: string[];
+}
+export interface TableSchemaResponse {
+    table: {
+        id: string;
+        name: string;
+        is_public: boolean;
+    };
+    fields: ColumnSchema[];
+    error: KeeprerError | null;
+}
+export declare class QueryBuilder<T = Record<string, unknown>> implements PromiseLike<QueryResponse<T>> {
+    private client;
+    private tableId;
+    private filters;
+    private sortField;
+    private limitCount;
+    private offsetCount;
+    constructor(client: KeeprerClient, tableId: string);
+    select(_columns?: string): this;
+    eq(column: string, value: unknown): this;
+    neq(column: string, value: unknown): this;
+    contains(column: string, value: unknown): this;
+    gt(column: string, value: number | string): this;
+    gte(column: string, value: number | string): this;
+    lt(column: string, value: number | string): this;
+    lte(column: string, value: number | string): this;
+    sort(field: string): this;
+    order(field: string, options?: {
+        ascending?: boolean;
+    }): this;
+    limit(count: number): this;
+    offset(count: number): this;
+    execute(): Promise<QueryResponse<T>>;
+    then<TResult1 = QueryResponse<T>, TResult2 = never>(onfulfilled?: ((value: QueryResponse<T>) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+}
+export declare class TableClient<T = Record<string, unknown>> {
+    private client;
+    private tableId;
+    constructor(client: KeeprerClient, tableId: string);
+    /**
+     * Start a query chain.
+     * e.g. `client.from("products").select().eq("status", "active")`
+     */
+    select(columns?: string): QueryBuilder<T>;
+    /**
+     * Fetch a single row by its ID.
+     */
+    get(id: string): Promise<SingleResponse<T>>;
+    /**
+     * Insert one or multiple rows.
+     * e.g. `client.from("products").insert({ name: "Shoes", price: 500 })`
+     */
+    insert(rowOrRows: Partial<T> | Partial<T>[]): Promise<SingleResponse<T | T[]>>;
+    /**
+     * Update an existing row by ID.
+     * e.g. `client.from("products").update("row_123", { price: 450 })`
+     */
+    update(id: string, values: Partial<T>): Promise<SingleResponse<T>>;
+    /**
+     * Delete a row by ID.
+     * e.g. `client.from("products").delete("row_123")`
+     */
+    delete(id: string): Promise<DeleteResponse>;
+    /**
+     * Fetch table column schema and metadata.
+     */
+    schema(): Promise<TableSchemaResponse>;
+}
+export declare class KeeprerClient {
+    private baseUrl;
+    private apiKey?;
+    private customFetch;
+    constructor(options: KeeprerClientOptions | string, apiKey?: string);
+    /**
+     * Access a table by its Table ID or name.
+     */
+    from<T = Record<string, unknown>>(tableId: string): TableClient<T>;
+    /**
+     * Export the entire workspace data as JSON.
+     */
+    exportWorkspace(workspaceId: string): Promise<{
+        data: any;
+        error: KeeprerError | null;
+    }>;
+    /**
+     * Internal HTTP request handler.
+     */
+    request(path: string, options?: RequestInit): Promise<{
+        data?: any;
+        error: KeeprerError | null;
+    }>;
+}
+/**
+ * Factory function to create a new Keeprer client instance.
+ *
+ * @example
+ * ```typescript
+ * import { createClient } from "@keeprer/js"
+ *
+ * const keeprer = createClient("https://keeprer.space", "pk_xxxxxxxxxxxx")
+ * const { data, total } = await keeprer.from("products").select().eq("status", "active")
+ * ```
+ */
+export declare function createClient(baseUrlOrOptions: string | KeeprerClientOptions, apiKey?: string): KeeprerClient;
+export default createClient;

package/dist/index.js

@@ -0,0 +1,260 @@
+// Keeprer Client SDK (@keeprer/js)
+//
+// A lightweight, zero-dependency, type-safe client library for Keeprer Headless Database.
+// Designed with a fluent Supabase-style query builder interface.
+//
+// Usage:
+//   import { createClient } from "@keeprer/js"
+//   const keeprer = createClient("https://keeprer.space", "pk_xxxxxxxxxxxx")
+//   const { data, total } = await keeprer.from("products").select().eq("status", "active").limit(10)
+export class QueryBuilder {
+    client;
+    tableId;
+    filters = [];
+    sortField = null;
+    limitCount = 100;
+    offsetCount = 0;
+    constructor(client, tableId) {
+        this.client = client;
+        this.tableId = tableId;
+    }
+    select(_columns) {
+        // Keeprer returns all columns by default, columns parameter reserved for projections
+        return this;
+    }
+    eq(column, value) {
+        this.filters.push(`${column}.eq.${encodeURIComponent(String(value))}`);
+        return this;
+    }
+    neq(column, value) {
+        this.filters.push(`${column}.neq.${encodeURIComponent(String(value))}`);
+        return this;
+    }
+    contains(column, value) {
+        this.filters.push(`${column}.contains.${encodeURIComponent(String(value))}`);
+        return this;
+    }
+    gt(column, value) {
+        this.filters.push(`${column}.gt.${encodeURIComponent(String(value))}`);
+        return this;
+    }
+    gte(column, value) {
+        this.filters.push(`${column}.gte.${encodeURIComponent(String(value))}`);
+        return this;
+    }
+    lt(column, value) {
+        this.filters.push(`${column}.lt.${encodeURIComponent(String(value))}`);
+        return this;
+    }
+    lte(column, value) {
+        this.filters.push(`${column}.lte.${encodeURIComponent(String(value))}`);
+        return this;
+    }
+    sort(field) {
+        this.sortField = field;
+        return this;
+    }
+    order(field, options) {
+        this.sortField = options?.ascending === false ? `-${field}` : field;
+        return this;
+    }
+    limit(count) {
+        this.limitCount = Math.max(1, Math.min(1000, count));
+        return this;
+    }
+    offset(count) {
+        this.offsetCount = Math.max(0, count);
+        return this;
+    }
+    async execute() {
+        const params = new URLSearchParams();
+        if (this.filters.length > 0) {
+            params.set("where", this.filters.join(","));
+        }
+        if (this.sortField) {
+            params.set("sort", this.sortField);
+        }
+        params.set("limit", String(this.limitCount));
+        params.set("offset", String(this.offsetCount));
+        const path = `/v1/t/${encodeURIComponent(this.tableId)}/rows?${params.toString()}`;
+        const res = await this.client.request(path, { method: "GET" });
+        if (res.error) {
+            return { data: [], total: 0, hasMore: false, cursor: null, error: res.error };
+        }
+        return {
+            data: res.data?.rows || [],
+            total: res.data?.total || 0,
+            hasMore: !!res.data?.hasMore,
+            cursor: res.data?.cursor ?? null,
+            error: null,
+        };
+    }
+    then(onfulfilled, onrejected) {
+        return this.execute().then(onfulfilled, onrejected);
+    }
+}
+export class TableClient {
+    client;
+    tableId;
+    constructor(client, tableId) {
+        this.client = client;
+        this.tableId = tableId;
+    }
+    /**
+     * Start a query chain.
+     * e.g. `client.from("products").select().eq("status", "active")`
+     */
+    select(columns) {
+        const q = new QueryBuilder(this.client, this.tableId);
+        return q.select(columns);
+    }
+    /**
+     * Fetch a single row by its ID.
+     */
+    async get(id) {
+        const res = await this.client.request(`/v1/t/${encodeURIComponent(this.tableId)}/rows/${encodeURIComponent(id)}`, {
+            method: "GET",
+        });
+        if (res.error)
+            return { data: null, error: res.error };
+        return { data: res.data, error: null };
+    }
+    /**
+     * Insert one or multiple rows.
+     * e.g. `client.from("products").insert({ name: "Shoes", price: 500 })`
+     */
+    async insert(rowOrRows) {
+        const payload = Array.isArray(rowOrRows) ? { rows: rowOrRows } : rowOrRows;
+        const res = await this.client.request(`/v1/t/${encodeURIComponent(this.tableId)}/rows`, {
+            method: "POST",
+            body: JSON.stringify(payload),
+        });
+        if (res.error)
+            return { data: null, error: res.error };
+        return { data: res.data, error: null };
+    }
+    /**
+     * Update an existing row by ID.
+     * e.g. `client.from("products").update("row_123", { price: 450 })`
+     */
+    async update(id, values) {
+        const res = await this.client.request(`/v1/t/${encodeURIComponent(this.tableId)}/rows/${encodeURIComponent(id)}`, {
+            method: "PATCH",
+            body: JSON.stringify(values),
+        });
+        if (res.error)
+            return { data: null, error: res.error };
+        return { data: res.data, error: null };
+    }
+    /**
+     * Delete a row by ID.
+     * e.g. `client.from("products").delete("row_123")`
+     */
+    async delete(id) {
+        const res = await this.client.request(`/v1/t/${encodeURIComponent(this.tableId)}/rows/${encodeURIComponent(id)}`, {
+            method: "DELETE",
+        });
+        if (res.error)
+            return { success: false, error: res.error };
+        return { success: true, error: null };
+    }
+    /**
+     * Fetch table column schema and metadata.
+     */
+    async schema() {
+        const res = await this.client.request(`/v1/t/${encodeURIComponent(this.tableId)}/schema`, {
+            method: "GET",
+        });
+        if (res.error) {
+            return { table: { id: this.tableId, name: "", is_public: false }, fields: [], error: res.error };
+        }
+        return { table: res.data.table, fields: res.data.fields, error: null };
+    }
+}
+export class KeeprerClient {
+    baseUrl;
+    apiKey;
+    customFetch;
+    constructor(options, apiKey) {
+        if (typeof options === "string") {
+            this.baseUrl = options.replace(/\/+$/, "");
+            this.apiKey = apiKey;
+            this.customFetch = globalThis.fetch.bind(globalThis);
+        }
+        else {
+            this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+            this.apiKey = options.apiKey || apiKey;
+            this.customFetch = options.fetch || globalThis.fetch.bind(globalThis);
+        }
+    }
+    /**
+     * Access a table by its Table ID or name.
+     */
+    from(tableId) {
+        return new TableClient(this, tableId);
+    }
+    /**
+     * Export the entire workspace data as JSON.
+     */
+    async exportWorkspace(workspaceId) {
+        const res = await this.request(`/v1/workspaces/${encodeURIComponent(workspaceId)}/export`, { method: "GET" });
+        return { data: res.data, error: res.error };
+    }
+    /**
+     * Internal HTTP request handler.
+     */
+    async request(path, options = {}) {
+        const url = `${this.baseUrl}${path.startsWith("/") ? path : `/${path}`}`;
+        const headers = {
+            Accept: "application/json",
+            ...(this.apiKey ? { Authorization: `Bearer ${this.apiKey}` } : {}),
+            ...options.headers,
+        };
+        if (options.body && !headers["Content-Type"]) {
+            headers["Content-Type"] = "application/json";
+        }
+        try {
+            const response = await this.customFetch(url, {
+                ...options,
+                headers,
+            });
+            if (response.status === 204) {
+                return { error: null };
+            }
+            const json = await response.json().catch(() => ({}));
+            if (!response.ok) {
+                return {
+                    error: {
+                        message: json.error || response.statusText || "Request failed",
+                        status: response.status,
+                        code: json.code,
+                    },
+                };
+            }
+            return { data: json, error: null };
+        }
+        catch (err) {
+            return {
+                error: {
+                    message: err.message || "Network error",
+                    status: 0,
+                },
+            };
+        }
+    }
+}
+/**
+ * Factory function to create a new Keeprer client instance.
+ *
+ * @example
+ * ```typescript
+ * import { createClient } from "@keeprer/js"
+ *
+ * const keeprer = createClient("https://keeprer.space", "pk_xxxxxxxxxxxx")
+ * const { data, total } = await keeprer.from("products").select().eq("status", "active")
+ * ```
+ */
+export function createClient(baseUrlOrOptions, apiKey) {
+    return new KeeprerClient(baseUrlOrOptions, apiKey);
+}
+export default createClient;

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@keeprer/js",
+  "version": "0.1.0",
+  "description": "Official TypeScript & JavaScript client for Keeprer Headless Database",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc ../../lib/sdk/index.ts --declaration --target es2022 --module esnext --moduleResolution bundler --outDir dist"
+  },
+  "keywords": [
+    "keeprer",
+    "database",
+    "headless",
+    "no-code",
+    "supabase",
+    "rest",
+    "sdk"
+  ],
+  "author": "Keeprer Team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ikarisz/Keeprer"
+  }
+}