dexie-cloud-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Fahlander
+
+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,174 @@
+# Dexie Cloud SDK
+
+Official server-side JavaScript/TypeScript SDK for [Dexie Cloud](https://dexie.org/cloud) — local-first database with sync.
+
+## Features
+
+- **Transparent auth** — configure credentials once, tokens are managed automatically
+- **Impersonation** — act as any user with `db.asUser()`
+- **Blob handling** — automatic offloading of large strings and binaries
+- **TSON support** — `Date`, `Map`, `Set`, `BigInt` serialized out of the box
+- **Multi-environment** — Node.js, Deno, Cloudflare Workers
+
+## Installation
+
+```bash
+npm install dexie-cloud-sdk
+```
+
+## Quick Start
+
+```typescript
+import { DexieCloudClient } from 'dexie-cloud-sdk';
+import { readFileSync } from 'fs';
+
+// 1. Read credentials from dexie-cloud.key (generated by `npx dexie-cloud connect`)
+const keys = JSON.parse(readFileSync('dexie-cloud.key', 'utf-8'));
+const dbUrl = Object.keys(keys)[0];
+const { clientId, clientSecret } = keys[dbUrl];
+
+// 2. Create client and database session
+const client = new DexieCloudClient('https://dexie.cloud');
+const db = client.db(dbUrl, { clientId, clientSecret });
+
+// 3. Use it — no tokens to manage!
+const items = await db.data.list('todoItems');
+console.log(items);
+
+await db.data.create('todoItems', {
+  title: 'Buy milk',
+  done: false,
+});
+```
+
+## Impersonation
+
+Act as a specific user (requires `IMPERSONATE` scope on the client):
+
+```typescript
+const userDb = db.asUser({
+  sub: 'user@example.com',
+  email: 'user@example.com',
+});
+
+// All operations run as that user
+const items = await userDb.data.list('todoItems');
+await userDb.data.create('todoItems', { title: 'User task', done: false });
+```
+
+## API
+
+### `client.db(dbUrl, credentials)`
+
+Creates a `DatabaseSession` with automatic token management.
+
+```typescript
+const db = client.db('https://xxxxxxxx.dexie.cloud', {
+  clientId: '...',
+  clientSecret: '...',
+});
+```
+
+Tokens are cached in-memory and refreshed automatically when within 5 minutes of expiry.
+
+### `db.data`
+
+CRUD operations on database tables:
+
+```typescript
+await db.data.list('table');                          // List all
+await db.data.list('table', { realm: 'realmId' });   // Filter by realm
+await db.data.get('table', 'id');                     // Get one
+await db.data.create('table', { ... });               // Create
+await db.data.replace('table', 'id', { ... });        // Full replace (PUT)
+await db.data.delete('table', 'id');                   // Delete
+await db.data.bulkCreate('table', [{ ... }, ...]);    // Bulk create
+```
+
+### `db.blobs`
+
+Binary blob operations:
+
+```typescript
+const ref = await db.blobs.upload(uint8Array, 'image/png');
+const { data, contentType } = await db.blobs.download(ref);
+```
+
+### `db.asUser(claims)`
+
+Returns a new `DatabaseSession` impersonating a user:
+
+```typescript
+const userDb = db.asUser({ sub: 'user@example.com', email: 'user@example.com' });
+```
+
+### Client Initialization
+
+```typescript
+// Simple
+const client = new DexieCloudClient('https://dexie.cloud');
+
+// Full config
+const client = new DexieCloudClient({
+  serviceUrl: 'https://dexie.cloud',
+  dbUrl: 'https://xxxxxxxx.dexie.cloud',
+  blobHandling: 'auto',      // 'auto' | 'lazy'
+  maxStringLength: 32768,     // Strings longer than this are offloaded to blobs
+  timeout: 30000,
+  debug: true,
+});
+```
+
+### Health Monitoring
+
+```typescript
+await client.waitForReady(60000);
+const status = await client.getStatus();
+const isReady = await client.isReady();
+```
+
+## Error Handling
+
+```typescript
+import {
+  DexieCloudError,
+  DexieCloudAuthError,
+  DexieCloudNetworkError,
+} from 'dexie-cloud-sdk';
+
+try {
+  await db.data.list('todoItems');
+} catch (error) {
+  if (error instanceof DexieCloudAuthError) {
+    console.log('Auth failed:', error.message);
+  } else if (error instanceof DexieCloudError) {
+    console.log('API error:', error.status, error.message);
+  }
+}
+```
+
+## E2E Testing
+
+The repo includes a Docker-based test stack:
+
+```bash
+# Start stack
+docker compose -f docker-compose.test.yml up -d
+
+# Run E2E tests
+pnpm run test:e2e
+
+# Stop
+docker compose -f docker-compose.test.yml down -v
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.
+
+## Links
+
+- [Dexie.js](https://dexie.org) — IndexedDB wrapper
+- [Dexie Cloud](https://dexie.org/cloud) — Sync service
+- [SDK Documentation](https://dexie.org/docs/cloud/sdk) — Full docs
+- [GitHub](https://github.com/dexie/dexie-cloud-sdk) — Source code

package/dist/index.d.mts

@@ -0,0 +1,236 @@
+type BlobHandling = 'auto' | 'lazy';
+interface DexieCloudConfig {
+    serviceUrl: string;
+    dbUrl?: string;
+    blobHandling?: BlobHandling;
+    maxStringLength?: number;
+    fetch?: typeof globalThis.fetch;
+    timeout?: number;
+    debug?: boolean;
+}
+interface OTPRequest {
+    email: string;
+    scopes?: string[];
+}
+interface OTPVerification {
+    email: string;
+    otpId: string;
+    otp: string;
+    scopes?: string[];
+}
+interface TokenResponse {
+    type: 'otp-sent' | 'tokens';
+    otp_id?: string;
+    accessToken?: string;
+    refreshToken?: string;
+    userId?: string;
+    claims?: Record<string, any>;
+}
+interface DatabaseInfo {
+    url: string;
+    clientId: string;
+    clientSecret: string;
+}
+interface CreateDatabaseOptions {
+    timeZone?: string;
+    hackathon?: boolean;
+}
+interface AuthTokens {
+    accessToken: string;
+    refreshToken?: string;
+    userId?: string;
+}
+interface DatabaseTokens {
+    accessToken: string;
+    refreshToken: string;
+    userId: string;
+}
+interface HealthStatus {
+    healthy: boolean;
+    ready: boolean;
+}
+interface BlobRef {
+    _bt: string;
+    ref: string;
+    size: number;
+    ct?: string;
+}
+interface InlineBlob {
+    _bt: string;
+    v: string;
+    ct?: string;
+}
+declare class DexieCloudError extends Error {
+    readonly status?: number | undefined;
+    readonly response?: string | undefined;
+    constructor(message: string, status?: number | undefined, response?: string | undefined);
+}
+declare class DexieCloudAuthError extends DexieCloudError {
+    constructor(message: string, status?: number);
+}
+declare class DexieCloudNetworkError extends DexieCloudError {
+    constructor(message: string);
+}
+
+interface HttpAdapter {
+    fetch(url: string, options?: RequestInit): Promise<Response>;
+}
+declare class FetchAdapter implements HttpAdapter {
+    private config;
+    private fetchImpl;
+    constructor(config: DexieCloudConfig, fetchImpl?: typeof globalThis.fetch);
+    fetch(url: string, options?: RequestInit): Promise<Response>;
+}
+declare class NodeAdapter implements HttpAdapter {
+    private config;
+    constructor(config: DexieCloudConfig);
+    fetch(url: string, options?: RequestInit): Promise<Response>;
+}
+declare function createAdapter(config: DexieCloudConfig): HttpAdapter;
+
+declare class AuthManager {
+    private config;
+    private http;
+    constructor(config: DexieCloudConfig, http: HttpAdapter);
+    private get serviceUrl();
+    requestOTP(email: string, scopes?: string[]): Promise<string>;
+    verifyOTP(email: string, otpId: string, otp: string, scopes?: string[]): Promise<AuthTokens>;
+    authenticateWithOTP(email: string, getOTP: () => Promise<string>, scopes?: string[]): Promise<AuthTokens>;
+    requestDatabaseOTP(dbUrl: string, email: string): Promise<void>;
+    verifyDatabaseOTP(dbUrl: string, email: string, otp: string): Promise<DatabaseTokens>;
+    authenticateDatabase(dbUrl: string, email: string, getOTP: () => Promise<string>): Promise<DatabaseTokens>;
+    authenticateWithClientCredentials(dbUrl: string, clientId: string, clientSecret: string, scopes?: string[]): Promise<AuthTokens>;
+}
+
+declare class DatabaseManager {
+    private config;
+    private http;
+    constructor(config: DexieCloudConfig, http: HttpAdapter);
+    private get serviceUrl();
+    create(accessToken: string, options?: CreateDatabaseOptions): Promise<DatabaseInfo>;
+    list(accessToken: string): Promise<DatabaseInfo[]>;
+    getInfo(dbUrl: string, accessToken: string): Promise<DatabaseInfo>;
+    delete(dbUrl: string, accessToken: string): Promise<void>;
+}
+
+declare class HealthManager {
+    private config;
+    private http;
+    constructor(config: DexieCloudConfig, http: HttpAdapter);
+    health(): Promise<boolean>;
+    ready(): Promise<boolean>;
+    status(): Promise<HealthStatus>;
+    waitForReady(timeout?: number, interval?: number): Promise<void>;
+    waitForHealth(timeout?: number, interval?: number): Promise<void>;
+}
+
+declare class BlobManager {
+    private dbUrl;
+    private http;
+    private mode;
+    private maxStringLength;
+    constructor(dbUrl: string, http: HttpAdapter, mode?: BlobHandling, maxStringLength?: number);
+    upload(data: Uint8Array | Blob | ArrayBuffer | ArrayBufferView, contentType: string | undefined, token: string): Promise<string>;
+    download(ref: string, token: string): Promise<{
+        data: Uint8Array;
+        contentType: string;
+    }>;
+    processForUpload(obj: any, token: string): Promise<any>;
+    processForRead(obj: any, token: string): Promise<any>;
+    private _walkForUpload;
+    private _walkForRead;
+    private _parallelMap;
+}
+
+type DataAccess = 'my' | 'all' | 'public';
+declare class DataManager {
+    private dbUrl;
+    private http;
+    private blobManager?;
+    private access;
+    constructor(dbUrl: string, http: HttpAdapter, blobManager?: BlobManager | undefined, access?: DataAccess);
+    private tableUrl;
+    private itemUrl;
+    list(table: string, token: string, options?: {
+        realm?: string;
+    }): Promise<any[]>;
+    get(table: string, id: string, token: string): Promise<any>;
+    create(table: string, obj: any, token: string): Promise<{
+        id: string;
+    }>;
+    replace(table: string, id: string, obj: any, token: string): Promise<{
+        id: string;
+    }>;
+    update(table: string, id: string, obj: any, token: string): Promise<any>;
+    delete(table: string, id: string, token: string): Promise<void>;
+    bulkCreate(table: string, objects: any[], token: string): Promise<any[]>;
+}
+
+interface ImpersonateClaims {
+    sub?: string;
+    email?: string;
+    [key: string]: any;
+}
+interface DatabaseCredentials {
+    clientId: string;
+    clientSecret: string;
+    impersonate?: ImpersonateClaims;
+}
+interface DataSessionProxy {
+    list(table: string, options?: {
+        realm?: string;
+    }): Promise<any[]>;
+    get(table: string, id: string): Promise<any>;
+    create(table: string, obj: any): Promise<any>;
+    replace(table: string, id: string, obj: any): Promise<any>;
+    update(table: string, id: string, obj: any): Promise<any>;
+    delete(table: string, id: string): Promise<void>;
+    bulkCreate(table: string, objects: any[]): Promise<any[]>;
+}
+interface BlobSessionProxy {
+    upload(data: Uint8Array | Blob | ArrayBuffer | ArrayBufferView, contentType?: string): Promise<string>;
+    download(ref: string): Promise<{
+        data: Uint8Array;
+        contentType: string;
+    }>;
+    processForUpload(obj: any): Promise<any>;
+    processForRead(obj: any): Promise<any>;
+}
+declare class DatabaseSession {
+    private dbUrl;
+    private credentials;
+    private http;
+    readonly data: DataSessionProxy;
+    readonly blobs: BlobSessionProxy;
+    private inflightToken;
+    constructor(dbUrl: string, credentials: DatabaseCredentials, http: HttpAdapter, blobManager: BlobManager, dataManager: DataManager);
+    asUser(claims: ImpersonateClaims): DatabaseSession;
+    private getToken;
+    private fetchToken;
+}
+
+declare class DexieCloudClient {
+    readonly auth: AuthManager;
+    readonly databases: DatabaseManager;
+    readonly health: HealthManager;
+    readonly data: DataManager;
+    readonly blobs: BlobManager;
+    private readonly http;
+    constructor(config: DexieCloudConfig | string);
+    createDatabase(email: string, getOTP: () => Promise<string>, options?: CreateDatabaseOptions): Promise<DatabaseInfo & {
+        accessToken: string;
+    }>;
+    isReady(): Promise<boolean>;
+    getStatus(): Promise<HealthStatus>;
+    waitForReady(timeout?: number): Promise<void>;
+    db(dbUrl: string, credentials: DatabaseCredentials): DatabaseSession;
+}
+
+declare const TSON: {
+    stringify(value: any, alternateChannel?: any, space?: number): string;
+    parse(tson: string, alternateChannel?: any): any;
+};
+declare function stringify(value: any, space?: number): string;
+declare function parse<T = any>(text: string): T;
+
+export { AuthManager, type AuthTokens, type BlobHandling, BlobManager, type BlobRef, type BlobSessionProxy, type CreateDatabaseOptions, DataManager, type DataSessionProxy, type DatabaseCredentials, type DatabaseInfo, DatabaseManager, DatabaseSession, type DatabaseTokens, DexieCloudAuthError, DexieCloudClient, type DexieCloudConfig, DexieCloudError, DexieCloudNetworkError, FetchAdapter, HealthManager, type HealthStatus, type HttpAdapter, type ImpersonateClaims, type InlineBlob, NodeAdapter, type OTPRequest, type OTPVerification, TSON, type TokenResponse, createAdapter, DexieCloudClient as default, parse, stringify };

package/dist/index.d.ts

@@ -0,0 +1,236 @@
+type BlobHandling = 'auto' | 'lazy';
+interface DexieCloudConfig {
+    serviceUrl: string;
+    dbUrl?: string;
+    blobHandling?: BlobHandling;
+    maxStringLength?: number;
+    fetch?: typeof globalThis.fetch;
+    timeout?: number;
+    debug?: boolean;
+}
+interface OTPRequest {
+    email: string;
+    scopes?: string[];
+}
+interface OTPVerification {
+    email: string;
+    otpId: string;
+    otp: string;
+    scopes?: string[];
+}
+interface TokenResponse {
+    type: 'otp-sent' | 'tokens';
+    otp_id?: string;
+    accessToken?: string;
+    refreshToken?: string;
+    userId?: string;
+    claims?: Record<string, any>;
+}
+interface DatabaseInfo {
+    url: string;
+    clientId: string;
+    clientSecret: string;
+}
+interface CreateDatabaseOptions {
+    timeZone?: string;
+    hackathon?: boolean;
+}
+interface AuthTokens {
+    accessToken: string;
+    refreshToken?: string;
+    userId?: string;
+}
+interface DatabaseTokens {
+    accessToken: string;
+    refreshToken: string;
+    userId: string;
+}
+interface HealthStatus {
+    healthy: boolean;
+    ready: boolean;
+}
+interface BlobRef {
+    _bt: string;
+    ref: string;
+    size: number;
+    ct?: string;
+}
+interface InlineBlob {
+    _bt: string;
+    v: string;
+    ct?: string;
+}
+declare class DexieCloudError extends Error {
+    readonly status?: number | undefined;
+    readonly response?: string | undefined;
+    constructor(message: string, status?: number | undefined, response?: string | undefined);
+}
+declare class DexieCloudAuthError extends DexieCloudError {
+    constructor(message: string, status?: number);
+}
+declare class DexieCloudNetworkError extends DexieCloudError {
+    constructor(message: string);
+}
+
+interface HttpAdapter {
+    fetch(url: string, options?: RequestInit): Promise<Response>;
+}
+declare class FetchAdapter implements HttpAdapter {
+    private config;
+    private fetchImpl;
+    constructor(config: DexieCloudConfig, fetchImpl?: typeof globalThis.fetch);
+    fetch(url: string, options?: RequestInit): Promise<Response>;
+}
+declare class NodeAdapter implements HttpAdapter {
+    private config;
+    constructor(config: DexieCloudConfig);
+    fetch(url: string, options?: RequestInit): Promise<Response>;
+}
+declare function createAdapter(config: DexieCloudConfig): HttpAdapter;
+
+declare class AuthManager {
+    private config;
+    private http;
+    constructor(config: DexieCloudConfig, http: HttpAdapter);
+    private get serviceUrl();
+    requestOTP(email: string, scopes?: string[]): Promise<string>;
+    verifyOTP(email: string, otpId: string, otp: string, scopes?: string[]): Promise<AuthTokens>;
+    authenticateWithOTP(email: string, getOTP: () => Promise<string>, scopes?: string[]): Promise<AuthTokens>;
+    requestDatabaseOTP(dbUrl: string, email: string): Promise<void>;
+    verifyDatabaseOTP(dbUrl: string, email: string, otp: string): Promise<DatabaseTokens>;
+    authenticateDatabase(dbUrl: string, email: string, getOTP: () => Promise<string>): Promise<DatabaseTokens>;
+    authenticateWithClientCredentials(dbUrl: string, clientId: string, clientSecret: string, scopes?: string[]): Promise<AuthTokens>;
+}
+
+declare class DatabaseManager {
+    private config;
+    private http;
+    constructor(config: DexieCloudConfig, http: HttpAdapter);
+    private get serviceUrl();
+    create(accessToken: string, options?: CreateDatabaseOptions): Promise<DatabaseInfo>;
+    list(accessToken: string): Promise<DatabaseInfo[]>;
+    getInfo(dbUrl: string, accessToken: string): Promise<DatabaseInfo>;
+    delete(dbUrl: string, accessToken: string): Promise<void>;
+}
+
+declare class HealthManager {
+    private config;
+    private http;
+    constructor(config: DexieCloudConfig, http: HttpAdapter);
+    health(): Promise<boolean>;
+    ready(): Promise<boolean>;
+    status(): Promise<HealthStatus>;
+    waitForReady(timeout?: number, interval?: number): Promise<void>;
+    waitForHealth(timeout?: number, interval?: number): Promise<void>;
+}
+
+declare class BlobManager {
+    private dbUrl;
+    private http;
+    private mode;
+    private maxStringLength;
+    constructor(dbUrl: string, http: HttpAdapter, mode?: BlobHandling, maxStringLength?: number);
+    upload(data: Uint8Array | Blob | ArrayBuffer | ArrayBufferView, contentType: string | undefined, token: string): Promise<string>;
+    download(ref: string, token: string): Promise<{
+        data: Uint8Array;
+        contentType: string;
+    }>;
+    processForUpload(obj: any, token: string): Promise<any>;
+    processForRead(obj: any, token: string): Promise<any>;
+    private _walkForUpload;
+    private _walkForRead;
+    private _parallelMap;
+}
+
+type DataAccess = 'my' | 'all' | 'public';
+declare class DataManager {
+    private dbUrl;
+    private http;
+    private blobManager?;
+    private access;
+    constructor(dbUrl: string, http: HttpAdapter, blobManager?: BlobManager | undefined, access?: DataAccess);
+    private tableUrl;
+    private itemUrl;
+    list(table: string, token: string, options?: {
+        realm?: string;
+    }): Promise<any[]>;
+    get(table: string, id: string, token: string): Promise<any>;
+    create(table: string, obj: any, token: string): Promise<{
+        id: string;
+    }>;
+    replace(table: string, id: string, obj: any, token: string): Promise<{
+        id: string;
+    }>;
+    update(table: string, id: string, obj: any, token: string): Promise<any>;
+    delete(table: string, id: string, token: string): Promise<void>;
+    bulkCreate(table: string, objects: any[], token: string): Promise<any[]>;
+}
+
+interface ImpersonateClaims {
+    sub?: string;
+    email?: string;
+    [key: string]: any;
+}
+interface DatabaseCredentials {
+    clientId: string;
+    clientSecret: string;
+    impersonate?: ImpersonateClaims;
+}
+interface DataSessionProxy {
+    list(table: string, options?: {
+        realm?: string;
+    }): Promise<any[]>;
+    get(table: string, id: string): Promise<any>;
+    create(table: string, obj: any): Promise<any>;
+    replace(table: string, id: string, obj: any): Promise<any>;
+    update(table: string, id: string, obj: any): Promise<any>;
+    delete(table: string, id: string): Promise<void>;
+    bulkCreate(table: string, objects: any[]): Promise<any[]>;
+}
+interface BlobSessionProxy {
+    upload(data: Uint8Array | Blob | ArrayBuffer | ArrayBufferView, contentType?: string): Promise<string>;
+    download(ref: string): Promise<{
+        data: Uint8Array;
+        contentType: string;
+    }>;
+    processForUpload(obj: any): Promise<any>;
+    processForRead(obj: any): Promise<any>;
+}
+declare class DatabaseSession {
+    private dbUrl;
+    private credentials;
+    private http;
+    readonly data: DataSessionProxy;
+    readonly blobs: BlobSessionProxy;
+    private inflightToken;
+    constructor(dbUrl: string, credentials: DatabaseCredentials, http: HttpAdapter, blobManager: BlobManager, dataManager: DataManager);
+    asUser(claims: ImpersonateClaims): DatabaseSession;
+    private getToken;
+    private fetchToken;
+}
+
+declare class DexieCloudClient {
+    readonly auth: AuthManager;
+    readonly databases: DatabaseManager;
+    readonly health: HealthManager;
+    readonly data: DataManager;
+    readonly blobs: BlobManager;
+    private readonly http;
+    constructor(config: DexieCloudConfig | string);
+    createDatabase(email: string, getOTP: () => Promise<string>, options?: CreateDatabaseOptions): Promise<DatabaseInfo & {
+        accessToken: string;
+    }>;
+    isReady(): Promise<boolean>;
+    getStatus(): Promise<HealthStatus>;
+    waitForReady(timeout?: number): Promise<void>;
+    db(dbUrl: string, credentials: DatabaseCredentials): DatabaseSession;
+}
+
+declare const TSON: {
+    stringify(value: any, alternateChannel?: any, space?: number): string;
+    parse(tson: string, alternateChannel?: any): any;
+};
+declare function stringify(value: any, space?: number): string;
+declare function parse<T = any>(text: string): T;
+
+export { AuthManager, type AuthTokens, type BlobHandling, BlobManager, type BlobRef, type BlobSessionProxy, type CreateDatabaseOptions, DataManager, type DataSessionProxy, type DatabaseCredentials, type DatabaseInfo, DatabaseManager, DatabaseSession, type DatabaseTokens, DexieCloudAuthError, DexieCloudClient, type DexieCloudConfig, DexieCloudError, DexieCloudNetworkError, FetchAdapter, HealthManager, type HealthStatus, type HttpAdapter, type ImpersonateClaims, type InlineBlob, NodeAdapter, type OTPRequest, type OTPVerification, TSON, type TokenResponse, createAdapter, DexieCloudClient as default, parse, stringify };