@rivium/sync-node 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,337 @@
+/**
+ * RiviumSync Node.js SDK
+ * Server-side SDK for RiviumSync Realtime Database
+ *
+ * Features:
+ * - Admin-level access (bypasses security rules by default)
+ * - Full CRUD operations on databases, collections, documents
+ * - Query support with filters, sorting, pagination
+ * - Batch operations for atomic writes
+ * - Realtime subscriptions via MQTT
+ * - Ideal for backend services, serverless functions, data migrations
+ *
+ * @packageDocumentation
+ */
+declare enum RiviumSyncErrorCode {
+    CONNECTION_FAILED = 1000,
+    CONNECTION_TIMEOUT = 1001,
+    CONNECTION_LOST = 1002,
+    AUTHENTICATION_FAILED = 1004,
+    SUBSCRIPTION_FAILED = 1100,
+    DATA_FETCH_FAILED = 1200,
+    DATA_PARSE_ERROR = 1201,
+    DATA_WRITE_FAILED = 1202,
+    DATA_DELETE_FAILED = 1203,
+    DOCUMENT_NOT_FOUND = 1204,
+    INVALID_CONFIG = 1300,
+    MISSING_API_KEY = 1301,
+    MISSING_SERVER_URL = 1302,
+    MISSING_SERVER_SECRET = 1303,
+    NOT_INITIALIZED = 1500,
+    NOT_CONNECTED = 1501,
+    INVALID_QUERY = 1700,
+    QUERY_EXECUTION_FAILED = 1701,
+    BATCH_WRITE_FAILED = 1800,
+    UNKNOWN_ERROR = 9999
+}
+declare class RiviumSyncError extends Error {
+    readonly code: RiviumSyncErrorCode;
+    readonly details?: string;
+    constructor(code: RiviumSyncErrorCode, details?: string);
+    toJSON(): {
+        code: RiviumSyncErrorCode;
+        message: string;
+        details: string | undefined;
+    };
+}
+declare enum RiviumSyncLogLevel {
+    NONE = 0,
+    ERROR = 1,
+    WARNING = 2,
+    INFO = 3,
+    DEBUG = 4,
+    VERBOSE = 5
+}
+interface RiviumSyncAdminConfig {
+    /** Your Project API Key (rv_live_xxx or rv_test_xxx) - REQUIRED */
+    apiKey: string;
+    /** Server secret for server-side authentication (nl_srv_xxx) - REQUIRED for all server operations */
+    serverSecret: string;
+    /** Optional user identifier for Security Rules (used as auth.uid when acting on behalf of a user) */
+    userId?: string;
+    /** Enable realtime subscriptions (default: false for server-side) */
+    enableRealtime?: boolean;
+    /** Log level (default: ERROR) */
+    logLevel?: RiviumSyncLogLevel;
+    /** Request timeout in ms (default: 30000) */
+    timeout?: number;
+}
+interface SyncDocument<T = Record<string, unknown>> {
+    id: string;
+    data: T;
+    createdAt?: string;
+    updatedAt?: string;
+    version?: number;
+}
+type QueryOperator = '==' | '!=' | '<' | '<=' | '>' | '>=' | 'in' | 'not-in' | 'array-contains';
+interface QueryFilter {
+    field: string;
+    operator: QueryOperator;
+    value: unknown;
+}
+interface QueryOptions {
+    filters?: QueryFilter[];
+    orderBy?: string;
+    orderDirection?: 'asc' | 'desc';
+    limit?: number;
+    offset?: number;
+}
+type DocumentListener<T = Record<string, unknown>> = (doc: SyncDocument<T> | null) => void;
+type CollectionListener<T = Record<string, unknown>> = (docs: SyncDocument<T>[]) => void;
+type Unsubscribe = () => void;
+interface BatchOperation {
+    type: 'set' | 'update' | 'delete';
+    databaseId: string;
+    collectionId: string;
+    documentId: string;
+    data?: unknown;
+}
+declare class SyncCollection<T = Record<string, unknown>> {
+    private admin;
+    private databaseId;
+    private collectionId;
+    constructor(admin: RiviumSyncAdmin, databaseId: string, collectionId: string);
+    /**
+     * Get a document reference
+     */
+    doc(documentId: string): SyncDocumentRef<T>;
+    /**
+     * Create a new document with auto-generated ID
+     */
+    add(data: T): Promise<SyncDocument<T>>;
+    /**
+     * Get a single document by ID
+     */
+    get(documentId: string): Promise<SyncDocument<T> | null>;
+    /**
+     * Get all documents in collection
+     */
+    getAll(options?: QueryOptions): Promise<SyncDocument<T>[]>;
+    /**
+     * Listen to collection changes (requires enableRealtime: true)
+     */
+    onSnapshot(callback: CollectionListener<T>, options?: QueryOptions): Unsubscribe;
+    /**
+     * Start a query builder
+     */
+    query(): SyncQuery<T>;
+    /**
+     * Add a filter condition
+     */
+    where(field: string, operator: QueryOperator, value: unknown): SyncQuery<T>;
+    /**
+     * Order results
+     */
+    orderBy(field: string, direction?: 'asc' | 'desc'): SyncQuery<T>;
+    /**
+     * Limit results
+     */
+    limit(count: number): SyncQuery<T>;
+}
+declare class SyncDocumentRef<T = Record<string, unknown>> {
+    private admin;
+    private databaseId;
+    private collectionId;
+    private documentId;
+    constructor(admin: RiviumSyncAdmin, databaseId: string, collectionId: string, documentId: string);
+    get id(): string;
+    get path(): string;
+    /**
+     * Get document data
+     */
+    get(): Promise<SyncDocument<T> | null>;
+    /**
+     * Check if document exists
+     */
+    exists(): Promise<boolean>;
+    /**
+     * Set document data (overwrite)
+     */
+    set(data: T): Promise<void>;
+    /**
+     * Update document data (merge)
+     */
+    update(data: Partial<T>): Promise<void>;
+    /**
+     * Delete document
+     */
+    delete(): Promise<void>;
+    /**
+     * Listen to document changes (requires enableRealtime: true)
+     */
+    onSnapshot(callback: DocumentListener<T>): Unsubscribe;
+}
+declare class SyncQuery<T = Record<string, unknown>> {
+    private admin;
+    private databaseId;
+    private collectionId;
+    private options;
+    constructor(admin: RiviumSyncAdmin, databaseId: string, collectionId: string);
+    /**
+     * Add a filter condition
+     */
+    where(field: string, operator: QueryOperator, value: unknown): SyncQuery<T>;
+    /**
+     * Order results
+     */
+    orderBy(field: string, direction?: 'asc' | 'desc'): SyncQuery<T>;
+    /**
+     * Limit results
+     */
+    limit(count: number): SyncQuery<T>;
+    /**
+     * Skip results (for pagination)
+     */
+    offset(count: number): SyncQuery<T>;
+    /**
+     * Alias for offset - skip first N results
+     */
+    startAfter(count: number): SyncQuery<T>;
+    /**
+     * Execute query and get results
+     */
+    get(): Promise<SyncDocument<T>[]>;
+    /**
+     * Get first result only
+     */
+    getFirst(): Promise<SyncDocument<T> | null>;
+    /**
+     * Count matching documents
+     */
+    count(): Promise<number>;
+    /**
+     * Listen to query results (requires enableRealtime: true)
+     */
+    onSnapshot(callback: CollectionListener<T>): Unsubscribe;
+}
+declare class SyncDatabase {
+    private admin;
+    private databaseId;
+    constructor(admin: RiviumSyncAdmin, databaseId: string);
+    get id(): string;
+    /**
+     * Get a collection reference
+     */
+    collection<T = Record<string, unknown>>(collectionId: string): SyncCollection<T>;
+}
+declare class WriteBatch {
+    private admin;
+    private operations;
+    constructor(admin: RiviumSyncAdmin);
+    /**
+     * Add a set operation to the batch
+     */
+    set<T>(docRef: SyncDocumentRef<T>, data: T): WriteBatch;
+    /**
+     * Add an update operation to the batch
+     */
+    update<T>(docRef: SyncDocumentRef<T>, data: Partial<T>): WriteBatch;
+    /**
+     * Add a delete operation to the batch
+     */
+    delete<T>(docRef: SyncDocumentRef<T>): WriteBatch;
+    /**
+     * Commit all operations in the batch
+     */
+    commit(): Promise<void>;
+    /**
+     * Get the number of pending operations
+     */
+    get size(): number;
+}
+/**
+ * RiviumSync Admin SDK for Node.js
+ *
+ * @example
+ * ```typescript
+ * import { RiviumSyncAdmin } from '@rivium/sync-node';
+ *
+ * const riviumSync = new RiviumSyncAdmin({
+ *   apiKey: process.env.RIVIUM_SYNC_API_KEY,
+ *   serverSecret: process.env.RIVIUM_SYNC_SERVER_SECRET, // Required for server-side operations
+ * });
+ *
+ * // Get a database reference
+ * const db = riviumSync.database('my-database-id');
+ *
+ * // CRUD operations
+ * const users = db.collection('users');
+ *
+ * // Create
+ * const newUser = await users.add({ name: 'John', email: 'john@example.com' });
+ *
+ * // Read
+ * const user = await users.get('user-id');
+ *
+ * // Query
+ * const adults = await users.where('age', '>=', 18).orderBy('name').get();
+ *
+ * // Update
+ * await users.doc('user-id').update({ age: 31 });
+ *
+ * // Delete
+ * await users.doc('user-id').delete();
+ *
+ * // Batch operations
+ * const batch = riviumSync.batch();
+ * batch.set(users.doc('user1'), { name: 'User 1' });
+ * batch.update(users.doc('user2'), { status: 'active' });
+ * batch.delete(users.doc('user3'));
+ * await batch.commit();
+ * ```
+ */
+declare class RiviumSyncAdmin {
+    private static readonly DEFAULT_BASE_URL;
+    private config;
+    private mqttClient;
+    private mqttConfig;
+    private logLevel;
+    private timeout;
+    private documentListeners;
+    private collectionListeners;
+    private cachedCollections;
+    constructor(config: RiviumSyncAdminConfig);
+    private log;
+    setLogLevel(level: RiviumSyncLogLevel): void;
+    private request;
+    /**
+     * Get a database reference
+     */
+    database(databaseId: string): SyncDatabase;
+    /**
+     * Create a new write batch
+     */
+    batch(): WriteBatch;
+    getDocument<T>(databaseId: string, collectionId: string, documentId: string): Promise<SyncDocument<T> | null>;
+    getDocuments<T>(databaseId: string, collectionId: string, options?: QueryOptions): Promise<SyncDocument<T>[]>;
+    addDocument<T>(databaseId: string, collectionId: string, data: T): Promise<SyncDocument<T>>;
+    setDocument<T>(databaseId: string, collectionId: string, documentId: string, data: T): Promise<void>;
+    updateDocument<T>(databaseId: string, collectionId: string, documentId: string, data: Partial<T>): Promise<void>;
+    deleteDocument(databaseId: string, collectionId: string, documentId: string): Promise<void>;
+    executeBatch(operations: BatchOperation[]): Promise<void>;
+    private initRealtime;
+    private connectMqtt;
+    listenDocument<T>(databaseId: string, collectionId: string, documentId: string, callback: DocumentListener<T>): Unsubscribe;
+    listenCollection<T>(databaseId: string, collectionId: string, callback: CollectionListener<T>, options?: QueryOptions): Unsubscribe;
+    private resubscribeAll;
+    private handleMqttMessage;
+    private applyFilters;
+    private applyOrdering;
+    private generateUUID;
+    /**
+     * Disconnect from realtime updates
+     */
+    disconnect(): void;
+}
+
+export { type CollectionListener, type DocumentListener, type QueryFilter, type QueryOperator, type QueryOptions, RiviumSyncAdmin, type RiviumSyncAdminConfig, RiviumSyncError, RiviumSyncErrorCode, RiviumSyncLogLevel, SyncCollection, SyncDatabase, type SyncDocument, SyncDocumentRef, SyncQuery, type Unsubscribe, WriteBatch, RiviumSyncAdmin as default };

package/dist/index.d.ts

@@ -0,0 +1,337 @@
+/**
+ * RiviumSync Node.js SDK
+ * Server-side SDK for RiviumSync Realtime Database
+ *
+ * Features:
+ * - Admin-level access (bypasses security rules by default)
+ * - Full CRUD operations on databases, collections, documents
+ * - Query support with filters, sorting, pagination
+ * - Batch operations for atomic writes
+ * - Realtime subscriptions via MQTT
+ * - Ideal for backend services, serverless functions, data migrations
+ *
+ * @packageDocumentation
+ */
+declare enum RiviumSyncErrorCode {
+    CONNECTION_FAILED = 1000,
+    CONNECTION_TIMEOUT = 1001,
+    CONNECTION_LOST = 1002,
+    AUTHENTICATION_FAILED = 1004,
+    SUBSCRIPTION_FAILED = 1100,
+    DATA_FETCH_FAILED = 1200,
+    DATA_PARSE_ERROR = 1201,
+    DATA_WRITE_FAILED = 1202,
+    DATA_DELETE_FAILED = 1203,
+    DOCUMENT_NOT_FOUND = 1204,
+    INVALID_CONFIG = 1300,
+    MISSING_API_KEY = 1301,
+    MISSING_SERVER_URL = 1302,
+    MISSING_SERVER_SECRET = 1303,
+    NOT_INITIALIZED = 1500,
+    NOT_CONNECTED = 1501,
+    INVALID_QUERY = 1700,
+    QUERY_EXECUTION_FAILED = 1701,
+    BATCH_WRITE_FAILED = 1800,
+    UNKNOWN_ERROR = 9999
+}
+declare class RiviumSyncError extends Error {
+    readonly code: RiviumSyncErrorCode;
+    readonly details?: string;
+    constructor(code: RiviumSyncErrorCode, details?: string);
+    toJSON(): {
+        code: RiviumSyncErrorCode;
+        message: string;
+        details: string | undefined;
+    };
+}
+declare enum RiviumSyncLogLevel {
+    NONE = 0,
+    ERROR = 1,
+    WARNING = 2,
+    INFO = 3,
+    DEBUG = 4,
+    VERBOSE = 5
+}
+interface RiviumSyncAdminConfig {
+    /** Your Project API Key (rv_live_xxx or rv_test_xxx) - REQUIRED */
+    apiKey: string;
+    /** Server secret for server-side authentication (nl_srv_xxx) - REQUIRED for all server operations */
+    serverSecret: string;
+    /** Optional user identifier for Security Rules (used as auth.uid when acting on behalf of a user) */
+    userId?: string;
+    /** Enable realtime subscriptions (default: false for server-side) */
+    enableRealtime?: boolean;
+    /** Log level (default: ERROR) */
+    logLevel?: RiviumSyncLogLevel;
+    /** Request timeout in ms (default: 30000) */
+    timeout?: number;
+}
+interface SyncDocument<T = Record<string, unknown>> {
+    id: string;
+    data: T;
+    createdAt?: string;
+    updatedAt?: string;
+    version?: number;
+}
+type QueryOperator = '==' | '!=' | '<' | '<=' | '>' | '>=' | 'in' | 'not-in' | 'array-contains';
+interface QueryFilter {
+    field: string;
+    operator: QueryOperator;
+    value: unknown;
+}
+interface QueryOptions {
+    filters?: QueryFilter[];
+    orderBy?: string;
+    orderDirection?: 'asc' | 'desc';
+    limit?: number;
+    offset?: number;
+}
+type DocumentListener<T = Record<string, unknown>> = (doc: SyncDocument<T> | null) => void;
+type CollectionListener<T = Record<string, unknown>> = (docs: SyncDocument<T>[]) => void;
+type Unsubscribe = () => void;
+interface BatchOperation {
+    type: 'set' | 'update' | 'delete';
+    databaseId: string;
+    collectionId: string;
+    documentId: string;
+    data?: unknown;
+}
+declare class SyncCollection<T = Record<string, unknown>> {
+    private admin;
+    private databaseId;
+    private collectionId;
+    constructor(admin: RiviumSyncAdmin, databaseId: string, collectionId: string);
+    /**
+     * Get a document reference
+     */
+    doc(documentId: string): SyncDocumentRef<T>;
+    /**
+     * Create a new document with auto-generated ID
+     */
+    add(data: T): Promise<SyncDocument<T>>;
+    /**
+     * Get a single document by ID
+     */
+    get(documentId: string): Promise<SyncDocument<T> | null>;
+    /**
+     * Get all documents in collection
+     */
+    getAll(options?: QueryOptions): Promise<SyncDocument<T>[]>;
+    /**
+     * Listen to collection changes (requires enableRealtime: true)
+     */
+    onSnapshot(callback: CollectionListener<T>, options?: QueryOptions): Unsubscribe;
+    /**
+     * Start a query builder
+     */
+    query(): SyncQuery<T>;
+    /**
+     * Add a filter condition
+     */
+    where(field: string, operator: QueryOperator, value: unknown): SyncQuery<T>;
+    /**
+     * Order results
+     */
+    orderBy(field: string, direction?: 'asc' | 'desc'): SyncQuery<T>;
+    /**
+     * Limit results
+     */
+    limit(count: number): SyncQuery<T>;
+}
+declare class SyncDocumentRef<T = Record<string, unknown>> {
+    private admin;
+    private databaseId;
+    private collectionId;
+    private documentId;
+    constructor(admin: RiviumSyncAdmin, databaseId: string, collectionId: string, documentId: string);
+    get id(): string;
+    get path(): string;
+    /**
+     * Get document data
+     */
+    get(): Promise<SyncDocument<T> | null>;
+    /**
+     * Check if document exists
+     */
+    exists(): Promise<boolean>;
+    /**
+     * Set document data (overwrite)
+     */
+    set(data: T): Promise<void>;
+    /**
+     * Update document data (merge)
+     */
+    update(data: Partial<T>): Promise<void>;
+    /**
+     * Delete document
+     */
+    delete(): Promise<void>;
+    /**
+     * Listen to document changes (requires enableRealtime: true)
+     */
+    onSnapshot(callback: DocumentListener<T>): Unsubscribe;
+}
+declare class SyncQuery<T = Record<string, unknown>> {
+    private admin;
+    private databaseId;
+    private collectionId;
+    private options;
+    constructor(admin: RiviumSyncAdmin, databaseId: string, collectionId: string);
+    /**
+     * Add a filter condition
+     */
+    where(field: string, operator: QueryOperator, value: unknown): SyncQuery<T>;
+    /**
+     * Order results
+     */
+    orderBy(field: string, direction?: 'asc' | 'desc'): SyncQuery<T>;
+    /**
+     * Limit results
+     */
+    limit(count: number): SyncQuery<T>;
+    /**
+     * Skip results (for pagination)
+     */
+    offset(count: number): SyncQuery<T>;
+    /**
+     * Alias for offset - skip first N results
+     */
+    startAfter(count: number): SyncQuery<T>;
+    /**
+     * Execute query and get results
+     */
+    get(): Promise<SyncDocument<T>[]>;
+    /**
+     * Get first result only
+     */
+    getFirst(): Promise<SyncDocument<T> | null>;
+    /**
+     * Count matching documents
+     */
+    count(): Promise<number>;
+    /**
+     * Listen to query results (requires enableRealtime: true)
+     */
+    onSnapshot(callback: CollectionListener<T>): Unsubscribe;
+}
+declare class SyncDatabase {
+    private admin;
+    private databaseId;
+    constructor(admin: RiviumSyncAdmin, databaseId: string);
+    get id(): string;
+    /**
+     * Get a collection reference
+     */
+    collection<T = Record<string, unknown>>(collectionId: string): SyncCollection<T>;
+}
+declare class WriteBatch {
+    private admin;
+    private operations;
+    constructor(admin: RiviumSyncAdmin);
+    /**
+     * Add a set operation to the batch
+     */
+    set<T>(docRef: SyncDocumentRef<T>, data: T): WriteBatch;
+    /**
+     * Add an update operation to the batch
+     */
+    update<T>(docRef: SyncDocumentRef<T>, data: Partial<T>): WriteBatch;
+    /**
+     * Add a delete operation to the batch
+     */
+    delete<T>(docRef: SyncDocumentRef<T>): WriteBatch;
+    /**
+     * Commit all operations in the batch
+     */
+    commit(): Promise<void>;
+    /**
+     * Get the number of pending operations
+     */
+    get size(): number;
+}
+/**
+ * RiviumSync Admin SDK for Node.js
+ *
+ * @example
+ * ```typescript
+ * import { RiviumSyncAdmin } from '@rivium/sync-node';
+ *
+ * const riviumSync = new RiviumSyncAdmin({
+ *   apiKey: process.env.RIVIUM_SYNC_API_KEY,
+ *   serverSecret: process.env.RIVIUM_SYNC_SERVER_SECRET, // Required for server-side operations
+ * });
+ *
+ * // Get a database reference
+ * const db = riviumSync.database('my-database-id');
+ *
+ * // CRUD operations
+ * const users = db.collection('users');
+ *
+ * // Create
+ * const newUser = await users.add({ name: 'John', email: 'john@example.com' });
+ *
+ * // Read
+ * const user = await users.get('user-id');
+ *
+ * // Query
+ * const adults = await users.where('age', '>=', 18).orderBy('name').get();
+ *
+ * // Update
+ * await users.doc('user-id').update({ age: 31 });
+ *
+ * // Delete
+ * await users.doc('user-id').delete();
+ *
+ * // Batch operations
+ * const batch = riviumSync.batch();
+ * batch.set(users.doc('user1'), { name: 'User 1' });
+ * batch.update(users.doc('user2'), { status: 'active' });
+ * batch.delete(users.doc('user3'));
+ * await batch.commit();
+ * ```
+ */
+declare class RiviumSyncAdmin {
+    private static readonly DEFAULT_BASE_URL;
+    private config;
+    private mqttClient;
+    private mqttConfig;
+    private logLevel;
+    private timeout;
+    private documentListeners;
+    private collectionListeners;
+    private cachedCollections;
+    constructor(config: RiviumSyncAdminConfig);
+    private log;
+    setLogLevel(level: RiviumSyncLogLevel): void;
+    private request;
+    /**
+     * Get a database reference
+     */
+    database(databaseId: string): SyncDatabase;
+    /**
+     * Create a new write batch
+     */
+    batch(): WriteBatch;
+    getDocument<T>(databaseId: string, collectionId: string, documentId: string): Promise<SyncDocument<T> | null>;
+    getDocuments<T>(databaseId: string, collectionId: string, options?: QueryOptions): Promise<SyncDocument<T>[]>;
+    addDocument<T>(databaseId: string, collectionId: string, data: T): Promise<SyncDocument<T>>;
+    setDocument<T>(databaseId: string, collectionId: string, documentId: string, data: T): Promise<void>;
+    updateDocument<T>(databaseId: string, collectionId: string, documentId: string, data: Partial<T>): Promise<void>;
+    deleteDocument(databaseId: string, collectionId: string, documentId: string): Promise<void>;
+    executeBatch(operations: BatchOperation[]): Promise<void>;
+    private initRealtime;
+    private connectMqtt;
+    listenDocument<T>(databaseId: string, collectionId: string, documentId: string, callback: DocumentListener<T>): Unsubscribe;
+    listenCollection<T>(databaseId: string, collectionId: string, callback: CollectionListener<T>, options?: QueryOptions): Unsubscribe;
+    private resubscribeAll;
+    private handleMqttMessage;
+    private applyFilters;
+    private applyOrdering;
+    private generateUUID;
+    /**
+     * Disconnect from realtime updates
+     */
+    disconnect(): void;
+}
+
+export { type CollectionListener, type DocumentListener, type QueryFilter, type QueryOperator, type QueryOptions, RiviumSyncAdmin, type RiviumSyncAdminConfig, RiviumSyncError, RiviumSyncErrorCode, RiviumSyncLogLevel, SyncCollection, SyncDatabase, type SyncDocument, SyncDocumentRef, SyncQuery, type Unsubscribe, WriteBatch, RiviumSyncAdmin as default };