sqlite-hub-client 0.7.0 → 0.8.0

package/README.md

@@ -20,6 +20,25 @@ const db = connect({
   db:    "my-service",
 });
 
+// File upload
+const uploaded = await db.files!.upload({
+  file: new Blob(["hello world"], { type: "text/plain" }),
+  filename: "hello.txt",
+  folderPath: "docs/examples",
+  metadata: { source: "docs" },
+});
+
+// File list
+const filePage = await db.files!.list({
+  limit: 20,
+  offset: 0,
+  folderPrefix: "docs",
+});
+
+// Presigned browser URL (for third-party dashboards)
+const signed = await db.files!.presign(uploaded.id, { expiresIn: 1800 });
+console.log(signed.url);
+
 // Create table
 await db.createTable("users", [
   { name: "id", type: "INTEGER", primaryKey: true, autoIncrement: true },
@@ -306,6 +325,136 @@ await db.exec("CREATE INDEX IF NOT EXISTS idx_title ON posts (title)");
 
 ---
 
+### Files
+
+#### `db.files.upload(input)`
+
+```ts
+const uploaded = await db.files!.upload({
+  file: new Blob(["report"], { type: "text/plain" }),
+  filename: "report.txt",
+  folderPath: "ops/reports",
+  conflictMode: "replace", // or "error"
+  contentType: "text/plain",
+  metadata: { owner: "ops" },
+  expiresIn: 3600,
+});
+```
+
+#### `db.files.list(options?)`
+
+```ts
+const files = await db.files!.list({
+  limit: 50,
+  offset: 0,
+  sort: "uploaded_at",
+  order: "desc",
+  folderPrefix: "ops",
+});
+```
+
+#### `db.files.getMeta(fileId)`
+
+```ts
+const meta = await db.files!.getMeta("file-id");
+```
+
+#### `db.files.delete(fileId)`
+
+```ts
+await db.files!.delete("file-id");
+```
+
+#### `db.files.bulkDelete(fileIds)`
+
+```ts
+await db.files!.bulkDelete(["id1", "id2"]);
+```
+
+#### `db.files.presign(fileId, options?)`
+
+Returns a signed URL that can be opened directly in browser without bearer token.
+
+```ts
+const signed = await db.files!.presign("file-id", {
+  expiresIn: 900,
+  disposition: "inline", // or "attachment"
+});
+
+// e.g. embed in dashboard iframe/image link
+console.log(signed.url);
+```
+
+#### `db.files.batchPresign(options)`
+
+Generate presigned URLs for multiple files at once. Maximum 100 file IDs per request.
+
+```ts
+const batch = await db.files!.batchPresign({
+  fileIds: ["id1", "id2", "id3"],
+  expiresIn: 900,
+  disposition: "inline",
+});
+
+// Check results
+batch.results.forEach((result) => {
+  if (result.error) {
+    console.error(`Failed for ${result.file_id}: ${result.error}`);
+  } else {
+    console.log(`URL for ${result.file_id}: ${result.url}`);
+  }
+});
+```
+
+#### `db.files.createFileAccessToken(options?)`
+
+Creates a long-lived access token for file operations. Unlike presigned URLs which are per-file, this token works for all file operations on the database.
+
+```ts
+const tokenData = await db.files!.createFileAccessToken({
+  scope: "files:read",
+  expiresIn: 2592000, // 30 days
+  description: "Dashboard access",
+});
+
+// Use in query parameter or Authorization header
+const fileUrl = `https://host/api/db/mydb/files/file-id?token=${tokenData.token}`;
+
+// Or with Authorization header:
+// Authorization: Bearer <token>
+```
+
+The token is read-only (`files:read`) and cannot be used for upload/delete operations. Default TTL is 30 days, maximum is 1 year.
+
+#### `db.files.revokeFileAccessToken(options)`
+
+Revokes a previously issued file access token.
+
+```ts
+// Revoke using the original token string
+await db.files!.revokeFileAccessToken({
+  token: tokenData.token,
+  reason: "rotated credential",
+});
+
+// Or revoke by token ID + expiresAt if stored separately
+await db.files!.revokeFileAccessToken({
+  tokenId: "token-id",
+  expiresAt: tokenData.expires_at,
+  reason: "compromised",
+});
+```
+
+#### `db.files.getDownloadUrl(fileId)`
+
+Returns the authenticated endpoint URL (requires bearer auth unless using presigned query).
+
+```ts
+const url = db.files!.getDownloadUrl("file-id");
+```
+
+---
+
 ## Architecture
 
 ```

package/dist/database.d.ts

@@ -1,4 +1,5 @@
 import type { ExecResult, IAdapter, RawResult } from "./adapters/types.js";
+import type { FileClient } from "./files.js";
 export type WhereClause = Record<string, unknown>;
 export type OrderDirection = "ASC" | "DESC";
 export interface FindOptions {
@@ -47,7 +48,8 @@ export interface UpsertOptions {
  */
 export declare class Database {
     private readonly adapter;
-    constructor(adapter: IAdapter);
+    readonly files?: FileClient;
+    constructor(adapter: IAdapter, filesClient?: FileClient);
     /**
      * Create a table.
      *

package/dist/database.js

@@ -22,8 +22,9 @@ function isExecResult(r) {
  * SQLite (via better-sqlite3 or sql.js) without changing business code.
  */
 export class Database {
-    constructor(adapter) {
+    constructor(adapter, filesClient) {
         this.adapter = adapter;
+        this.files = filesClient;
     }
     // ── Schema ──────────────────────────────────────────────────────────────
     /**

package/dist/files.d.ts

@@ -0,0 +1,135 @@
+import type { HttpAdapterOptions } from "./adapters/http.js";
+export interface FileListOptions {
+    limit?: number;
+    offset?: number;
+    sort?: "uploaded_at" | "size_bytes" | "filename" | "folder_path";
+    order?: "asc" | "desc";
+    folderPrefix?: string;
+}
+export interface StoredFile {
+    id: string;
+    db_name: string;
+    content_hash: string;
+    filename: string;
+    folder_path: string;
+    content_type: string | null;
+    size_bytes: number;
+    storage_path?: string;
+    uploaded_at: string;
+    expires_at: string | null;
+    metadata: string | null;
+}
+export interface FileListResponse {
+    files: StoredFile[];
+    total: number;
+    offset: number;
+    limit: number;
+}
+export interface UploadFileInput {
+    file: Blob | Uint8Array | ArrayBuffer;
+    filename?: string;
+    folderPath?: string;
+    conflictMode?: "replace" | "error";
+    contentType?: string;
+    metadata?: Record<string, unknown>;
+    expiresIn?: number;
+}
+export interface UploadFileResponse {
+    id: string;
+    filename: string;
+    folder_path: string;
+    size_bytes: number;
+    content_type: string | null;
+    url: string;
+    uploaded_at: string;
+    expires_at: string | null;
+}
+export interface FileMetaResponse {
+    id: string;
+    filename: string;
+    folder_path: string;
+    content_type: string | null;
+    size_bytes: number;
+    uploaded_at: string;
+    expires_at: string | null;
+    metadata: Record<string, unknown> | null;
+    content_hash: string;
+}
+export interface BulkDeleteFilesResponse {
+    deleted: number;
+    failed: number;
+}
+export interface PresignFileOptions {
+    expiresIn?: number;
+    disposition?: "inline" | "attachment";
+}
+export interface PresignFileResponse {
+    url: string;
+    expires_at: string;
+    expires_in: number;
+    disposition: "inline" | "attachment";
+    token_type: "signed_query";
+}
+export interface BatchPresignOptions {
+    fileIds: string[];
+    expiresIn?: number;
+    disposition?: "inline" | "attachment";
+}
+export interface BatchPresignResult {
+    file_id: string;
+    url?: string;
+    expires_at?: string;
+    expires_in?: number;
+    disposition?: "inline" | "attachment";
+    error?: string;
+}
+export interface BatchPresignResponse {
+    results: BatchPresignResult[];
+    token_type: "signed_query";
+    total: number;
+    successful: number;
+    failed: number;
+}
+export interface CreateFileAccessTokenOptions {
+    scope?: "files:read";
+    expiresIn?: number;
+    description?: string;
+}
+export interface FileAccessTokenResponse {
+    token_id: string;
+    token: string;
+    token_type: "bearer";
+    expires_at: string;
+    expires_in: number;
+    scope: string;
+    description?: string;
+    usage: string;
+}
+export interface RevokeFileAccessTokenOptions {
+    token?: string;
+    tokenId?: string;
+    expiresAt?: string;
+    reason?: string;
+}
+export interface RevokeFileAccessTokenResponse {
+    success: boolean;
+    token_id: string;
+    revoked_at: string;
+}
+export declare class FileClient {
+    private readonly options;
+    private readonly baseUrl;
+    private readonly basePath;
+    constructor(options: HttpAdapterOptions);
+    private requestJson;
+    list(options?: FileListOptions): Promise<FileListResponse>;
+    upload(input: UploadFileInput): Promise<UploadFileResponse>;
+    getMeta(fileId: string): Promise<FileMetaResponse>;
+    delete(fileId: string): Promise<void>;
+    bulkDelete(fileIds: string[]): Promise<BulkDeleteFilesResponse>;
+    presign(fileId: string, options?: PresignFileOptions): Promise<PresignFileResponse>;
+    batchPresign(options: BatchPresignOptions): Promise<BatchPresignResponse>;
+    createFileAccessToken(options?: CreateFileAccessTokenOptions): Promise<FileAccessTokenResponse>;
+    revokeFileAccessToken(options: RevokeFileAccessTokenOptions): Promise<RevokeFileAccessTokenResponse>;
+    getDownloadUrl(fileId: string): string;
+}

package/dist/files.js

@@ -0,0 +1,144 @@
+function toBlob(file, contentType) {
+    if (file instanceof Blob)
+        return file;
+    if (file instanceof Uint8Array)
+        return new Blob([file], { type: contentType });
+    return new Blob([new Uint8Array(file)], { type: contentType });
+}
+export class FileClient {
+    constructor(options) {
+        this.options = options;
+        this.baseUrl = options.url.replace(/\/$/, "");
+        this.basePath = `/api/db/${encodeURIComponent(options.db)}/files`;
+    }
+    async requestJson(path, init = {}) {
+        const headers = new Headers(init.headers ?? {});
+        headers.set("Authorization", `Bearer ${this.options.token}`);
+        const res = await fetch(`${this.baseUrl}${path}`, {
+            ...init,
+            headers,
+        });
+        if (res.status === 204) {
+            return undefined;
+        }
+        const body = (await res.json().catch(() => null));
+        if (!res.ok) {
+            throw new Error(body?.error ?? `sqlite-hub: HTTP ${res.status} (db: "${this.options.db}")`);
+        }
+        return body;
+    }
+    async list(options = {}) {
+        const qs = new URLSearchParams();
+        if (options.limit !== undefined)
+            qs.set("limit", String(options.limit));
+        if (options.offset !== undefined)
+            qs.set("offset", String(options.offset));
+        if (options.sort)
+            qs.set("sort", options.sort);
+        if (options.order)
+            qs.set("order", options.order);
+        if (options.folderPrefix)
+            qs.set("folder_prefix", options.folderPrefix);
+        const suffix = qs.toString() ? `?${qs.toString()}` : "";
+        return this.requestJson(`${this.basePath}${suffix}`);
+    }
+    async upload(input) {
+        const formData = new FormData();
+        const blob = toBlob(input.file, input.contentType);
+        const filename = input.filename ?? "file";
+        formData.append("file", blob, filename);
+        if (input.filename)
+            formData.append("filename", input.filename);
+        if (input.folderPath)
+            formData.append("folder_path", input.folderPath);
+        if (input.conflictMode)
+            formData.append("conflict_mode", input.conflictMode);
+        if (input.contentType)
+            formData.append("content_type", input.contentType);
+        if (input.metadata)
+            formData.append("metadata", JSON.stringify(input.metadata));
+        if (input.expiresIn !== undefined)
+            formData.append("expires_in", String(input.expiresIn));
+        const headers = new Headers({ Authorization: `Bearer ${this.options.token}` });
+        const res = await fetch(`${this.baseUrl}${this.basePath}`, {
+            method: "POST",
+            headers,
+            body: formData,
+        });
+        const body = (await res.json().catch(() => null));
+        if (!res.ok || !body) {
+            throw new Error(body?.error ?? `sqlite-hub: HTTP ${res.status} (db: "${this.options.db}")`);
+        }
+        return body;
+    }
+    async getMeta(fileId) {
+        return this.requestJson(`${this.basePath}/${encodeURIComponent(fileId)}/meta`);
+    }
+    async delete(fileId) {
+        await this.requestJson(`${this.basePath}/${encodeURIComponent(fileId)}`, {
+            method: "DELETE",
+        });
+    }
+    async bulkDelete(fileIds) {
+        return this.requestJson(`${this.basePath}/bulk-delete`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ file_ids: fileIds }),
+        });
+    }
+    async presign(fileId, options = {}) {
+        return this.requestJson(`${this.basePath}/${encodeURIComponent(fileId)}/presign`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                ...(options.expiresIn !== undefined ? { expires_in: options.expiresIn } : {}),
+                ...(options.disposition ? { disposition: options.disposition } : {}),
+            }),
+        });
+    }
+    async batchPresign(options) {
+        return this.requestJson(`${this.basePath}/presign/batch`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                file_ids: options.fileIds,
+                ...(options.expiresIn !== undefined ? { expires_in: options.expiresIn } : {}),
+                ...(options.disposition ? { disposition: options.disposition } : {}),
+            }),
+        });
+    }
+    async createFileAccessToken(options = {}) {
+        const tokenPath = `/api/db/${encodeURIComponent(this.options.db)}/tokens/files`;
+        return this.requestJson(tokenPath, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                scope: "files:read",
+                ...(options.expiresIn !== undefined ? { expires_in: options.expiresIn } : {}),
+                ...(options.description ? { description: options.description } : {}),
+            }),
+        });
+    }
+    async revokeFileAccessToken(options) {
+        const tokenPath = `/api/db/${encodeURIComponent(this.options.db)}/tokens/files/revoke`;
+        const payload = {
+            ...(options.token ? { token: options.token } : {}),
+            ...(options.reason ? { reason: options.reason } : {}),
+        };
+        if (!options.token) {
+            if (!options.tokenId || !options.expiresAt) {
+                throw new Error("tokenId and expiresAt are required when token is not provided");
+            }
+            payload.token_id = options.tokenId;
+            payload.expires_at = options.expiresAt;
+        }
+        return this.requestJson(tokenPath, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(payload),
+        });
+    }
+    getDownloadUrl(fileId) {
+        return `${this.baseUrl}${this.basePath}/${encodeURIComponent(fileId)}`;
+    }
+}

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export { Database } from "./database.js";
 export type { ColumnDef, CreateIndexOptions, CreateTableOptions, FindOptions, OrderDirection, UpsertOptions, WhereClause } from "./database.js";
+export { FileClient, } from "./files.js";
+export type { BatchPresignOptions, BatchPresignResponse, BatchPresignResult, BulkDeleteFilesResponse, CreateFileAccessTokenOptions, FileAccessTokenResponse, FileListOptions, FileListResponse, FileMetaResponse, PresignFileOptions, PresignFileResponse, RevokeFileAccessTokenOptions, RevokeFileAccessTokenResponse, StoredFile, UploadFileInput, UploadFileResponse, } from "./files.js";
 export { HttpAdapter } from "./adapters/http.js";
 export type { HttpAdapterOptions } from "./adapters/http.js";
 export type { ColumnHeader, ExecResult, IAdapter, QueryResult, RawResult } from "./adapters/types.js";

package/dist/index.js

@@ -1,8 +1,10 @@
 export { Database } from "./database.js";
+export { FileClient, } from "./files.js";
 export { HttpAdapter } from "./adapters/http.js";
 // ── Convenience factory ──────────────────────────────────────────────────────
 import { HttpAdapter } from "./adapters/http.js";
 import { Database } from "./database.js";
+import { FileClient } from "./files.js";
 /**
  * Create a Database connected to a sqlite-hub service over HTTP.
  *
@@ -14,6 +16,6 @@ import { Database } from "./database.js";
  * });
  */
 export function connect(options) {
-    return new Database(new HttpAdapter(options));
+    return new Database(new HttpAdapter(options), new FileClient(options));
 }
 export default connect;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sqlite-hub-client",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "High-level SQLite client for sqlite-hub — HTTP adapter included, direct SQLite coming soon",
   "type": "module",
   "main": "dist/index.js",