sqlite-hub-client 0.2.0 → 0.3.0

package/README.md

@@ -1,25 +1,29 @@
-# sqlite-db-client
+# sqlite-hub-client
 
-High-level TypeScript/JavaScript client for [sqlite-db-hub](https://github.com/0xdps/sqlite-db-hub).  
+High-level TypeScript/JavaScript client for [sqlite-hub](https://github.com/0xdps/sqlite-hub).  
 Comes with a full set of APIs for schema management, reads, writes — all using an **adapter** abstraction so the same code works over HTTP today and can talk to SQLite directly later.
 
 ## Install
 
 ```bash
-npm install sqlite-db-client
+npm install sqlite-hub-client
 ```
 
 ## Quick start
 
 ```ts
-import { connect } from "sqlite-db-client";
+import { connect } from "sqlite-hub-client";
 
+// Using a per-DB service secret (recommended for services)
 const db = connect({
-  url: process.env.SQLITE_DB_HUB_URL, // e.g. https://my-app.up.railway.app
-  token: process.env.SQLITE_DB_HUB_TOKEN, // ADMIN_TOKEN set on the service
-  db: "my-service", // database name
+  url: process.env.SQLITE_HUB_URL,           // e.g. https://my-app.up.railway.app
+  token: process.env.SQLITE_HUB_SERVICE_SECRET, // service_secret generated at DB creation
+  db: "my-service",                           // database name
 });
 
+// Or use the global admin token (dev / admin tooling)
+// token: process.env.SQLITE_HUB_ADMIN_TOKEN
+
 // Create table
 await db.createTable("users", [
   { name: "id", type: "INTEGER", primaryKey: true, autoIncrement: true },
@@ -90,14 +94,12 @@ const result = await db.exec("PRAGMA table_info(users)");
 
 ### `connect(options)` — create a database client
 
-| Option    | Type     | Required | Description                                           |
-| --------- | -------- | -------- | ----------------------------------------------------- |
-| `url`     | `string` | ✅       | Base URL of your sqlite-db-hub deployment             |
-| `token`   | `string` | ✅       | `ADMIN_TOKEN` configured on the sqlite-db-hub service |
-| `db`      | `string` | ✅       | Name of the database to operate on                    |
-| `timeout` | `number` | ❌       | Request timeout in ms (default: `10000`)              |
-
-Returns a `Database` instance.
+| Option    | Type     | Required | Description                                                                                     |
+| --------- | -------- | -------- | ----------------------------------------------------------------------------------------------- |
+| `url`     | `string` | ✅       | Base URL of your sqlite-hub deployment                                                          |
+| `token`   | `string` | ✅       | Per-DB `service_secret` (recommended) or global `ADMIN_TOKEN` — sent as `Authorization: Bearer` |
+| `db`      | `string` | ✅       | Name of the database to operate on                                                              |
+| `timeout` | `number` | ❌       | Request timeout in ms (default: `10000`)                                                        |
 
 ---
 
@@ -251,12 +253,12 @@ await db.exec("CREATE INDEX IF NOT EXISTS idx_title ON posts (title)");
 ## Architecture
 
 ```
-sqlite-db-client
+sqlite-hub-client
 ├── index.ts              ← connect() factory + all public exports
 ├── database.ts           ← Database class — all high-level APIs
 └── adapters/
     ├── types.ts          ← IAdapter interface (exec only)
-    ├── http.ts           ← HttpAdapter (sqlite-db-hub over HTTP)
+    ├── http.ts           ← HttpAdapter (sqlite-hub over HTTP)
     └── index.ts          ← re-exports
 ```
 
@@ -264,8 +266,8 @@ Adding a direct SQLite adapter in the future is a one-liner:
 
 ```ts
 // future
-import { Database } from "sqlite-db-client";
-import { DirectAdapter } from "sqlite-db-client/adapters/direct"; // coming soon
+import { Database } from "sqlite-hub-client";
+import { DirectAdapter } from "sqlite-hub-client/adapters/direct"; // coming soon
 
 const db = new Database(new DirectAdapter({ path: "./local.db" }));
 // same API — createTable, find, insert, update, delete…
@@ -273,140 +275,3 @@ const db = new Database(new DirectAdapter({ path: "./local.db" }));
 
 ## License
 
-MIT
-
-## Install
-
-```bash
-npm install sqlite-db-hub-client
-```
-
-Or directly from GitHub (before the npm package is published):
-
-```bash
-npm install github:0xdps/sqlite-db-hub-client
-```
-
-## Quick start
-
-```ts
-import { createClient } from "sqlite-db-hub-client";
-
-const db = createClient({
-  url: process.env.SQLITE_DB_HUB_URL, // e.g. https://my-app.up.railway.app
-  token: process.env.SQLITE_DB_HUB_TOKEN, // ADMIN_TOKEN set on the service
-  db: "my-service", // name of the database to use
-});
-
-// Create a table
-await db.run(`
-  CREATE TABLE IF NOT EXISTS users (
-    id    INTEGER PRIMARY KEY AUTOINCREMENT,
-    email TEXT NOT NULL UNIQUE,
-    name  TEXT
-  )
-`);
-
-// Insert a row
-await db.run("INSERT INTO users (email, name) VALUES (?, ?)", [
-  "alice@example.com",
-  "Alice",
-]);
-
-// Query rows (typed)
-const users = await db.query<{ id: number; email: string; name: string }>(
-  "SELECT * FROM users"
-);
-
-// Query a single row (or null)
-const user = await db.queryOne<{ id: number; email: string }>(
-  "SELECT * FROM users WHERE email = ?",
-  ["alice@example.com"]
-);
-```
-
-## API
-
-### `createClient(options)` / `new FileDbClient(options)`
-
-| Option    | Type     | Required | Description                                           |
-| --------- | -------- | -------- | ----------------------------------------------------- |
-| `url`     | `string` | ✅       | Base URL of your sqlite-db-hub deployment             |
-| `token`   | `string` | ✅       | `ADMIN_TOKEN` configured on the sqlite-db-hub service |
-| `db`      | `string` | ✅       | Name of the database to operate on                    |
-| `timeout` | `number` | ❌       | Request timeout in ms (default: `10000`)              |
-
----
-
-### `db.exec(sql, bindings?)`
-
-Run any SQL statement. Returns a `QueryResult` for SELECT, or an `ExecResult` for writes.
-
-```ts
-const result = await db.exec("SELECT count(*) as n FROM users");
-// { headers: [...], rows: [{ n: 1 }], rowsRead: 1 }
-```
-
----
-
-### `db.query<T>(sql, bindings?)`
-
-Run a SELECT and return typed rows.
-
-```ts
-const rows = await db.query<{ id: number; name: string }>(
-  "SELECT id, name FROM users WHERE id > ?",
-  [5]
-);
-```
-
----
-
-### `db.queryOne<T>(sql, bindings?)`
-
-Run a SELECT and return the first row, or `null` if no results.
-
-```ts
-const row = await db.queryOne<{ name: string }>(
-  "SELECT name FROM users WHERE id = ?",
-  [1]
-);
-```
-
----
-
-### `db.run(sql, bindings?)`
-
-Run a write statement (INSERT, UPDATE, DELETE, CREATE, ALTER, DROP). Returns `{ rowsAffected, lastInsertRowid }`.
-
-```ts
-const { rowsAffected, lastInsertRowid } = await db.run(
-  "INSERT INTO jobs (payload) VALUES (?)",
-  [JSON.stringify({ task: "send-email" })]
-);
-```
-
-## Types
-
-```ts
-interface QueryResult<T> {
-  headers: ColumnHeader[];
-  rows: T[];
-  rowsRead: number;
-}
-
-interface ExecResult {
-  rowsAffected: number;
-  lastInsertRowid: number | null;
-}
-
-interface ColumnHeader {
-  name: string;
-  displayName: string;
-  originalType: string | null;
-}
-```
-
-## License
-
-MIT

package/dist/adapters/http.d.ts

@@ -1,8 +1,12 @@
 import type { IAdapter, RawResult } from "./types.js";
 export interface HttpAdapterOptions {
-    /** Base URL of the sqlite-db-hub deployment, e.g. https://my-app.up.railway.app */
+    /** Base URL of the sqlite-hub deployment, e.g. https://my-app.up.railway.app */
     url: string;
-    /** ADMIN_TOKEN configured on the sqlite-db-hub service */
+    /**
+     * Bearer token for this database.
+     * Use the per-DB `service_secret` (recommended for services) or the
+     * global `ADMIN_TOKEN` (for admin-level access or dev environments).
+     */
     token: string;
     /** Name of the database to operate on */
     db: string;
@@ -10,7 +14,7 @@ export interface HttpAdapterOptions {
     timeout?: number;
 }
 /**
- * Adapter that executes SQL via the sqlite-db-hub HTTP API
+ * Adapter that executes SQL via the sqlite-hub HTTP API
  * (POST /api/db/:name/exec).
  */
 export declare class HttpAdapter implements IAdapter {

package/dist/adapters/http.js

@@ -6,7 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.HttpAdapter = void 0;
 const fetch_1 = __importDefault(require("@pingpong-js/fetch"));
 /**
- * Adapter that executes SQL via the sqlite-db-hub HTTP API
+ * Adapter that executes SQL via the sqlite-hub HTTP API
  * (POST /api/db/:name/exec).
  */
 class HttpAdapter {
@@ -30,7 +30,7 @@ class HttpAdapter {
         if (res.isError()) {
             const body = res.data;
             throw new Error(body?.error ??
-                `sqlite-db-hub: HTTP ${res.status} for db "${this.options.db}"`);
+                `sqlite-hub: HTTP ${res.status} for db "${this.options.db}"`);
         }
         return res.data;
     }

package/dist/database.d.ts

@@ -1,4 +1,4 @@
-import type { IAdapter, ExecResult, RawResult } from "./adapters/types.js";
+import type { ExecResult, IAdapter, RawResult } from "./adapters/types.js";
 export type WhereClause = Record<string, unknown>;
 export type OrderDirection = "ASC" | "DESC";
 export interface FindOptions {

package/dist/database.js

@@ -217,14 +217,14 @@ class Database {
     async _read(sql, bindings) {
         const result = await this.adapter.exec(sql, bindings);
         if (!isQueryResult(result)) {
-            throw new Error(`sqlite-db-hub: expected SELECT, got write result for: ${sql}`);
+            throw new Error(`sqlite-hub: expected SELECT, got write result for: ${sql}`);
         }
         return result.rows;
     }
     async _write(sql, bindings) {
         const result = await this.adapter.exec(sql, bindings);
         if (!isExecResult(result)) {
-            throw new Error(`sqlite-db-hub: expected write result, got SELECT for: ${sql}`);
+            throw new Error(`sqlite-hub: expected write result, got SELECT for: ${sql}`);
         }
         return result;
     }

package/dist/index.d.ts

@@ -1,17 +1,26 @@
 export { Database } from "./database.js";
-export type { WhereClause, FindOptions, ColumnDef, CreateTableOptions, CreateIndexOptions, OrderDirection, } from "./database.js";
+export type { ColumnDef, CreateIndexOptions, CreateTableOptions, FindOptions, OrderDirection, WhereClause } from "./database.js";
 export { HttpAdapter } from "./adapters/http.js";
 export type { HttpAdapterOptions } from "./adapters/http.js";
-export type { IAdapter, ColumnHeader, QueryResult, ExecResult, RawResult, } from "./adapters/types.js";
-import { Database } from "./database.js";
+export type { ColumnHeader, ExecResult, IAdapter, QueryResult, RawResult } from "./adapters/types.js";
 import { type HttpAdapterOptions } from "./adapters/http.js";
+import { Database } from "./database.js";
 /**
- * Create a Database connected to a sqlite-db-hub service over HTTP.
+ * Create a Database connected to a sqlite-hub service over HTTP.
+ *
+ * @example
+ * // Using a per-DB service secret (recommended for services)
+ * const db = connect({
+ *   url:   process.env.SQLITE_HUB_URL,
+ *   token: process.env.SQLITE_HUB_SERVICE_SECRET,
+ *   db:    "my-service",
+ * });
  *
  * @example
+ * // Using the global admin token (dev / admin tooling)
  * const db = connect({
- *   url:   process.env.SQLITE_DB_HUB_URL,
- *   token: process.env.SQLITE_DB_HUB_TOKEN,
+ *   url:   process.env.SQLITE_HUB_URL,
+ *   token: process.env.SQLITE_HUB_ADMIN_TOKEN,
  *   db:    "my-service",
  * });
  */

package/dist/index.js

@@ -7,15 +7,24 @@ Object.defineProperty(exports, "Database", { enumerable: true, get: function ()
 var http_js_1 = require("./adapters/http.js");
 Object.defineProperty(exports, "HttpAdapter", { enumerable: true, get: function () { return http_js_1.HttpAdapter; } });
 // ── Convenience factory ──────────────────────────────────────────────────────
-const database_js_2 = require("./database.js");
 const http_js_2 = require("./adapters/http.js");
+const database_js_2 = require("./database.js");
 /**
- * Create a Database connected to a sqlite-db-hub service over HTTP.
+ * Create a Database connected to a sqlite-hub service over HTTP.
+ *
+ * @example
+ * // Using a per-DB service secret (recommended for services)
+ * const db = connect({
+ *   url:   process.env.SQLITE_HUB_URL,
+ *   token: process.env.SQLITE_HUB_SERVICE_SECRET,
+ *   db:    "my-service",
+ * });
  *
  * @example
+ * // Using the global admin token (dev / admin tooling)
  * const db = connect({
- *   url:   process.env.SQLITE_DB_HUB_URL,
- *   token: process.env.SQLITE_DB_HUB_TOKEN,
+ *   url:   process.env.SQLITE_HUB_URL,
+ *   token: process.env.SQLITE_HUB_ADMIN_TOKEN,
  *   db:    "my-service",
  * });
  */

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "sqlite-hub-client",
-  "version": "0.2.0",
-  "description": "High-level SQLite client for sqlite-db-hub — HTTP adapter included, direct SQLite coming soon",
+  "version": "0.3.0",
+  "description": "High-level SQLite client for sqlite-hub — HTTP adapter included, direct SQLite coming soon",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": ["dist", "README.md"],
   "scripts": {
     "build": "tsc"
   },
-  "keywords": ["sqlite", "sqlite-db-hub", "railway", "orm", "database"],
+  "keywords": ["sqlite", "sqlite-hub", "railway", "orm", "database"],
   "license": "MIT",
   "dependencies": {
     "@pingpong-js/fetch": "^1.0.2"