nwdb-sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NUP WHITE Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,85 @@
+# NW DB SDK
+
+Official JavaScript/TypeScript SDK for [NW DB](https://nwdb.dev) — AI-native Database as a Service.
+
+## Install
+
+```bash
+npm install nwdb-sdk
+```
+
+## Quick Start — Supabase-style client (recommended)
+
+```typescript
+import { createClient } from 'nwdb-sdk';
+
+const db = createClient('https://api.nwdb.dev', 'nwdb_your_api_key');
+
+// SELECT with chainable filters — returns { data, error }
+const { data, error } = await db
+  .from('leads')
+  .select('*')
+  .eq('status', 'hot')
+  .gte('score', 80)
+  .order('score', { ascending: false })
+  .limit(20);
+
+// Single row
+const { data: lead } = await db.from('leads').select('*').eq('id', leadId).single();
+
+// INSERT
+const { data: created } = await db.from('leads').insert({
+  name: 'Acme Inc', status: 'hot', score: 90,
+});
+
+// UPDATE (id-addressed)
+await db.from('leads').update({ status: 'warm' }).eq('id', leadId);
+
+// DELETE (id-addressed)
+await db.from('leads').delete().eq('id', leadId);
+
+// Raw SQL escape hatch
+const { data: rows } = await db.rpc("SELECT * FROM leads WHERE score > 80");
+```
+
+The query builder is **thenable** — `await` runs it directly, no `.exec()` needed.
+Every call resolves to `{ data, error }` (Supabase-compatible shape).
+
+### Filter operators
+`eq` `neq` `gt` `gte` `lt` `lte` `like` `ilike` — e.g. `.ilike('name', 'acme')`.
+
+Filter values are sanitised against injection (`,` `(` `)` and control chars are
+rejected). For arbitrary free-text predicates use `db.rpc(sql)`.
+
+## Legacy explicit-method client
+
+The original `NWDB` class is still exported and supported:
+
+```typescript
+import NWDB from 'nwdb-sdk';
+
+const db = new NWDB({ apiKey: 'nwdb_...', apiUrl: 'https://api.nwdb.dev' });
+
+await db.createTable('users', [
+  { name: 'name', type: 'string', required: true },
+  { name: 'email', type: 'string', required: true },
+]);
+await db.createRecord('users', { name: 'Taro', email: 'taro@example.com' });
+
+// Vector search
+await db.createCollection('docs', 768);
+await db.upsertVector('docs', { id: 'doc1', vector: [/* 768 numbers */], content: 'Hello' });
+const hits = await db.searchVectors('docs', { query: 'greeting', top_k: 5 });
+
+// AI Agents
+await db.triggerAgent('cleansing', 'users');
+```
+
+## Get an API key
+
+Sign up at [nwdb.dev](https://nwdb.dev) → create a workspace → copy the key from
+**Settings → API Keys**. Plans: Hobby ¥1,000 / Pro ¥5,000 / Scale ¥20,000 (monthly).
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,175 @@
+/**
+ * NW DB — Official JavaScript / TypeScript SDK
+ *
+ * Two interfaces:
+ *   1. createClient(url, key)  — Supabase-style chainable query builder (recommended)
+ *   2. new NWDB({ ... })       — explicit method client (legacy, still supported)
+ *
+ * Quickstart:
+ *   import { createClient } from 'nwdb-sdk';
+ *   const db = createClient('https://api.nwdb.dev', 'nwdb_xxx');
+ *   const { data, error } = await db.from('leads').select('*').eq('status', 'hot').limit(20);
+ */
+export interface NWDBConfig {
+    apiUrl?: string;
+    apiKey?: string;
+    token?: string;
+    workspaceId?: string;
+}
+export interface NWDBRecord {
+    id: string;
+    [key: string]: unknown;
+}
+export interface QueryResult {
+    rows: NWDBRecord[];
+    rowCount: number;
+}
+export interface VectorSearchResult {
+    id: string;
+    content?: string;
+    metadata?: Record<string, unknown>;
+    similarity: number;
+}
+export interface AgentRun {
+    id: string;
+    agent_type: string;
+    status: string;
+    records_processed: number;
+    errors: number;
+}
+/** Supabase-style result envelope. */
+export interface Result<T> {
+    data: T | null;
+    error: {
+        message: string;
+        code?: string;
+    } | null;
+    count?: number;
+}
+interface Transport {
+    apiUrl: string;
+    headers: Record<string, string>;
+}
+/**
+ * Supabase-style query builder bound to one table.
+ * Thenable — `await` triggers the request.
+ */
+declare class QueryBuilder<T = NWDBRecord> implements PromiseLike<Result<T[]>> {
+    private t;
+    private table;
+    private filters;
+    private _orderBy?;
+    private _order;
+    private _limit?;
+    private _offset?;
+    private _single;
+    private _columns?;
+    private mode;
+    private payload?;
+    constructor(t: Transport, table: string);
+    /** Column projection. NW DB returns all columns; projection is applied client-side. */
+    select(columns?: string): this;
+    insert(rows: Record<string, unknown> | Record<string, unknown>[]): this;
+    update(patch: Record<string, unknown>): this;
+    delete(): this;
+    private addFilter;
+    eq(c: string, v: unknown): this;
+    neq(c: string, v: unknown): this;
+    gt(c: string, v: unknown): this;
+    gte(c: string, v: unknown): this;
+    lt(c: string, v: unknown): this;
+    lte(c: string, v: unknown): this;
+    like(c: string, v: unknown): this;
+    ilike(c: string, v: unknown): this;
+    order(column: string, opts?: {
+        ascending?: boolean;
+    }): this;
+    limit(n: number): this;
+    range(from: number, to: number): this;
+    /** Return a single object instead of an array. */
+    single(): this;
+    private project;
+    private idFromFilters;
+    exec(): Promise<Result<T[]>>;
+    then<R1 = Result<T[]>, R2 = never>(onfulfilled?: ((v: Result<T[]>) => R1 | PromiseLike<R1>) | null, onrejected?: ((reason: unknown) => R2 | PromiseLike<R2>) | null): PromiseLike<R1 | R2>;
+}
+/** Supabase-style client. */
+export interface NWDBClient {
+    from<T = NWDBRecord>(table: string): QueryBuilder<T>;
+    rpc(sql: string): Promise<Result<NWDBRecord[]>>;
+    raw: NWDB;
+}
+export declare function createClient(apiUrl: string, apiKey: string, opts?: {
+    workspaceId?: string;
+}): NWDBClient;
+export declare class NWDB {
+    private apiUrl;
+    private headers;
+    constructor(config?: NWDBConfig);
+    private request;
+    listTables(): Promise<{
+        tables: Array<{
+            name: string;
+            columns: unknown[];
+        }>;
+    }>;
+    createTable(name: string, columns: Array<{
+        name: string;
+        type: string;
+        required?: boolean;
+    }>): Promise<{
+        table: string;
+    }>;
+    deleteTable(name: string): Promise<{
+        success: boolean;
+    }>;
+    listRecords(table: string, options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        records: NWDBRecord[];
+        total: number;
+    }>;
+    getRecord(table: string, id: string): Promise<{
+        record: NWDBRecord;
+    }>;
+    createRecord(table: string, data: Record<string, unknown>): Promise<{
+        record: NWDBRecord;
+    }>;
+    updateRecord(table: string, id: string, data: Record<string, unknown>): Promise<{
+        record: NWDBRecord;
+    }>;
+    deleteRecord(table: string, id: string): Promise<{
+        success: boolean;
+    }>;
+    query(sql: string): Promise<QueryResult>;
+    listCollections(): Promise<{
+        collections: Array<{
+            name: string;
+            dimensions: number;
+            count: number;
+        }>;
+    }>;
+    createCollection(name: string, dimensions?: number): Promise<{
+        collection: string;
+    }>;
+    searchVectors(collection: string, options: {
+        vector?: number[];
+        query?: string;
+        top_k?: number;
+    }): Promise<{
+        results: VectorSearchResult[];
+    }>;
+    upsertVector(collection: string, data: {
+        id: string;
+        vector: number[];
+        content?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<{
+        success: boolean;
+    }>;
+    triggerAgent(agentType: 'cleansing' | 'normalization' | 'masking' | 'vectorization' | 'metadata', table: string): Promise<{
+        run: AgentRun;
+    }>;
+}
+export default NWDB;

package/dist/index.js

@@ -0,0 +1,287 @@
+"use strict";
+/**
+ * NW DB — Official JavaScript / TypeScript SDK
+ *
+ * Two interfaces:
+ *   1. createClient(url, key)  — Supabase-style chainable query builder (recommended)
+ *   2. new NWDB({ ... })       — explicit method client (legacy, still supported)
+ *
+ * Quickstart:
+ *   import { createClient } from 'nwdb-sdk';
+ *   const db = createClient('https://api.nwdb.dev', 'nwdb_xxx');
+ *   const { data, error } = await db.from('leads').select('*').eq('status', 'hot').limit(20);
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NWDB = void 0;
+exports.createClient = createClient;
+const DEFAULT_API_URL = 'https://api.nwdb.dev';
+/**
+ * The /records filter parser splits on `,` and matches `field.op(value)`.
+ * A value containing `,`, `(`, or `)` could inject extra filters (including
+ * tenant-boundary overrides), so we reject those characters defensively.
+ */
+function safeFilterValue(v) {
+    if (v === null || v === undefined)
+        throw new Error('nwdb: filter value cannot be null/undefined');
+    const s = String(v);
+    if (s.length === 0)
+        throw new Error('nwdb: filter value cannot be empty');
+    if (s.length > 256)
+        throw new Error('nwdb: filter value too long');
+    if (/[,()\n\r\t\0]/.test(s)) {
+        throw new Error(`nwdb: filter value contains unsupported char: ${s.slice(0, 40)}`);
+    }
+    return s;
+}
+function safePathSegment(v) {
+    const s = String(v ?? '');
+    if (!/^[A-Za-z0-9._~-]+$/.test(s)) {
+        throw new Error(`nwdb: identifier contains unsupported char: ${s.slice(0, 40)}`);
+    }
+    return s;
+}
+async function rawRequest(t, path, options = {}) {
+    const res = await fetch(`${t.apiUrl}${path}`, {
+        ...options,
+        headers: { ...t.headers, ...(options.headers || {}) },
+    });
+    const text = await res.text();
+    if (!res.ok) {
+        let parsed = {};
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch { /* keep empty */ }
+        const err = new Error(parsed.error || res.statusText);
+        err.code = parsed.code;
+        err.status = res.status;
+        throw err;
+    }
+    return (text ? JSON.parse(text) : {});
+}
+/**
+ * Supabase-style query builder bound to one table.
+ * Thenable — `await` triggers the request.
+ */
+class QueryBuilder {
+    constructor(t, table) {
+        this.t = t;
+        this.table = table;
+        this.filters = [];
+        this._order = 'desc';
+        this._single = false;
+        this.mode = 'select';
+        safePathSegment(table);
+    }
+    /** Column projection. NW DB returns all columns; projection is applied client-side. */
+    select(columns = '*') {
+        this.mode = 'select';
+        this._columns = columns === '*' ? undefined : columns.split(',').map((c) => c.trim());
+        return this;
+    }
+    insert(rows) {
+        this.mode = 'insert';
+        this.payload = rows;
+        return this;
+    }
+    update(patch) {
+        this.mode = 'update';
+        this.payload = patch;
+        return this;
+    }
+    delete() {
+        this.mode = 'delete';
+        return this;
+    }
+    addFilter(op, column, value) {
+        this.filters.push(`${safePathSegment(column)}.${op}(${safeFilterValue(value)})`);
+        return this;
+    }
+    eq(c, v) { return this.addFilter('eq', c, v); }
+    neq(c, v) { return this.addFilter('neq', c, v); }
+    gt(c, v) { return this.addFilter('gt', c, v); }
+    gte(c, v) { return this.addFilter('gte', c, v); }
+    lt(c, v) { return this.addFilter('lt', c, v); }
+    lte(c, v) { return this.addFilter('lte', c, v); }
+    like(c, v) { return this.addFilter('like', c, v); }
+    ilike(c, v) { return this.addFilter('ilike', c, v); }
+    order(column, opts = {}) {
+        this._orderBy = safePathSegment(column);
+        this._order = opts.ascending ? 'asc' : 'desc';
+        return this;
+    }
+    limit(n) { this._limit = n; return this; }
+    range(from, to) {
+        this._offset = from;
+        this._limit = to - from + 1;
+        return this;
+    }
+    /** Return a single object instead of an array. */
+    single() { this._single = true; return this; }
+    project(rows) {
+        if (!this._columns)
+            return rows;
+        return rows.map((r) => {
+            const o = { id: r.id };
+            for (const c of this._columns)
+                o[c] = r[c];
+            return o;
+        });
+    }
+    idFromFilters() {
+        for (const f of this.filters) {
+            const m = f.match(/^id\.eq\((.+)\)$/);
+            if (m)
+                return m[1];
+        }
+        return null;
+    }
+    async exec() {
+        try {
+            if (this.mode === 'insert') {
+                const r = await rawRequest(this.t, `/api/v1/records/${this.table}/records`, { method: 'POST', body: JSON.stringify(this.payload) });
+                const data = (r.records ?? (r.record ? [r.record] : []));
+                return { data, error: null };
+            }
+            if (this.mode === 'update') {
+                const id = this.idFromFilters();
+                if (!id)
+                    throw new Error('nwdb: update requires .eq("id", <uuid>)');
+                const r = await rawRequest(this.t, `/api/v1/records/${this.table}/records/${safePathSegment(id)}`, { method: 'PUT', body: JSON.stringify(this.payload) });
+                return { data: [r.record], error: null };
+            }
+            if (this.mode === 'delete') {
+                const id = this.idFromFilters();
+                if (!id)
+                    throw new Error('nwdb: delete requires .eq("id", <uuid>)');
+                await rawRequest(this.t, `/api/v1/records/${this.table}/records/${safePathSegment(id)}`, { method: 'DELETE' });
+                return { data: [], error: null };
+            }
+            // select
+            const q = new URLSearchParams();
+            if (this.filters.length)
+                q.set('filter', this.filters.join(','));
+            q.set('limit', String(this._limit ?? 100));
+            if (this._offset)
+                q.set('offset', String(this._offset));
+            if (this._orderBy) {
+                q.set('orderBy', this._orderBy);
+                q.set('order', this._order);
+            }
+            const r = await rawRequest(this.t, `/api/v1/records/${this.table}/records?${q.toString()}`);
+            const rows = this.project(r.records ?? []);
+            const data = (this._single ? (rows[0] ?? null) : rows);
+            return { data, error: null, count: r.total };
+        }
+        catch (e) {
+            const err = e;
+            return { data: null, error: { message: err.message, code: err.code } };
+        }
+    }
+    // Thenable: `await db.from(...).select()...` works without an explicit `.exec()`
+    then(onfulfilled, onrejected) {
+        return this.exec().then(onfulfilled, onrejected);
+    }
+}
+function createClient(apiUrl, apiKey, opts = {}) {
+    const transport = {
+        apiUrl: (apiUrl || DEFAULT_API_URL).replace(/\/$/, ''),
+        headers: {
+            'Content-Type': 'application/json',
+            'X-API-Key': apiKey,
+            ...(opts.workspaceId ? { 'X-Workspace-ID': opts.workspaceId } : {}),
+        },
+    };
+    const raw = new NWDB({ apiUrl: transport.apiUrl, apiKey, workspaceId: opts.workspaceId });
+    return {
+        from(table) {
+            return new QueryBuilder(transport, table);
+        },
+        async rpc(sql) {
+            try {
+                const r = await rawRequest(transport, '/api/v1/query', { method: 'POST', body: JSON.stringify({ sql }) });
+                return { data: r.records ?? r.rows ?? [], error: null };
+            }
+            catch (e) {
+                const err = e;
+                return { data: null, error: { message: err.message, code: err.code } };
+            }
+        },
+        raw,
+    };
+}
+// ─────────────────────────────────────────────────────────────────────────
+// Legacy explicit-method client (kept for backward compatibility)
+// ─────────────────────────────────────────────────────────────────────────
+class NWDB {
+    constructor(config = {}) {
+        this.apiUrl = (config.apiUrl || DEFAULT_API_URL).replace(/\/$/, '') + '/api/v1';
+        this.headers = {
+            'Content-Type': 'application/json',
+            ...(config.apiKey ? { 'X-API-Key': config.apiKey } : {}),
+            ...(config.token ? { 'Authorization': `Bearer ${config.token}` } : {}),
+            ...(config.workspaceId ? { 'X-Workspace-ID': config.workspaceId } : {}),
+        };
+    }
+    async request(path, options = {}) {
+        const res = await fetch(`${this.apiUrl}${path}`, {
+            ...options,
+            headers: { ...this.headers, ...(options.headers || {}) },
+        });
+        if (!res.ok) {
+            const err = await res.json().catch(() => ({ error: res.statusText }));
+            throw new Error(err.error || res.statusText);
+        }
+        return res.json();
+    }
+    listTables() {
+        return this.request('/tables');
+    }
+    createTable(name, columns) {
+        return this.request('/tables', { method: 'POST', body: JSON.stringify({ name, columns }) });
+    }
+    deleteTable(name) {
+        return this.request(`/tables/${name}`, { method: 'DELETE' });
+    }
+    listRecords(table, options) {
+        const params = new URLSearchParams();
+        if (options?.limit)
+            params.set('limit', String(options.limit));
+        if (options?.offset)
+            params.set('offset', String(options.offset));
+        const qs = params.toString();
+        return this.request(`/records/${table}/records${qs ? '?' + qs : ''}`);
+    }
+    getRecord(table, id) {
+        return this.request(`/records/${table}/records/${id}`);
+    }
+    createRecord(table, data) {
+        return this.request(`/records/${table}/records`, { method: 'POST', body: JSON.stringify(data) });
+    }
+    updateRecord(table, id, data) {
+        return this.request(`/records/${table}/records/${id}`, { method: 'PUT', body: JSON.stringify(data) });
+    }
+    deleteRecord(table, id) {
+        return this.request(`/records/${table}/records/${id}`, { method: 'DELETE' });
+    }
+    query(sql) {
+        return this.request('/query', { method: 'POST', body: JSON.stringify({ sql }) });
+    }
+    listCollections() {
+        return this.request('/vectors/collections');
+    }
+    createCollection(name, dimensions = 768) {
+        return this.request('/vectors/collections', { method: 'POST', body: JSON.stringify({ name, dimensions }) });
+    }
+    searchVectors(collection, options) {
+        return this.request(`/vectors/collections/${collection}/search`, { method: 'POST', body: JSON.stringify(options) });
+    }
+    upsertVector(collection, data) {
+        return this.request(`/vectors/collections/${collection}/upsert`, { method: 'POST', body: JSON.stringify(data) });
+    }
+    triggerAgent(agentType, table) {
+        return this.request(`/agents/run/${agentType}`, { method: 'POST', body: JSON.stringify({ table }) });
+    }
+}
+exports.NWDB = NWDB;
+exports.default = NWDB;

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "nwdb-sdk",
+  "version": "1.0.0",
+  "description": "Official JavaScript/TypeScript SDK for NW DB - AI-native Database as a Service",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": ["database", "AI", "MCP", "vector-search", "DBaaS", "nwdb", "postgres"],
+  "author": "NUP WHITE Inc. <nupwhite@nupwhite.com>",
+  "license": "MIT",
+  "homepage": "https://nwdb.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nup-cloud/nw-db.git",
+    "directory": "sdk/javascript"
+  },
+  "bugs": {
+    "url": "https://github.com/nup-cloud/nw-db/issues"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0"
+  }
+}