@bluecopa/core 0.1.55 → 0.1.56

package/README.md

@@ -20,6 +20,13 @@ The core package provides essential API utilities and functions for data managem
     - [Workbook Module](#workbook-module)
     - [Workflow Module](#workflow-module)
     - [Worksheet Module](#worksheet-module)
+  - [InputTableDB — Reactive Database Client](#inputtabledb--reactive-database-client)
+    - [Quick Start](#quick-start)
+    - [CRUD](#crud)
+    - [Query Operators](#query-operators)
+    - [Framework Integration](#framework-integration)
+    - [WebSocket Provider (optional)](#websocket-provider-optional)
+    - [Cleanup](#cleanup)
   - [WebSocket Connection](#websocket-connection)
     - [WebSocket Factory](#websocket-factory)
     - [WebSocket Provider Interface](#websocket-provider-interface)
@@ -103,6 +110,8 @@ export interface Config {
   accessToken: string;
   workspaceId: string;
   userId: string;
+  solutionId?: string;                   // used by InputTableDB
+  websocketProvider?: IWebsocketProvider; // enables realtime sync
 }
 ```
 
@@ -174,6 +183,133 @@ See: [`workflow/triggerHttpWorkflowById.ts`](src/api/workflow/triggerHttpWorkflo
 
 See: [`worksheet/getWorksheets.ts`](src/api/worksheet/getWorksheets.ts:1), [`worksheet/getWorksheetsByType.ts`](src/api/worksheet/getWorksheetsByType.ts:1)
 
+## InputTableDB — Reactive Database Client
+
+A Firebase-like client for querying and subscribing to Bluecopa Input Table V2 data. No init required — just import and use.
+
+> **[Full SDK Guide](docs/input-table-db-guide.md)** — comprehensive documentation with architecture details, error handling, framework integration (Svelte/React), and all available features.
+
+### Quick Start
+
+```typescript
+import { copaSetConfig, copaInputTableDb } from "@bluecopa/core";
+
+// Configure once at app startup
+copaSetConfig({
+  apiBaseUrl: "https://develop.bluecopa.com",
+  accessToken: "your-token",
+  workspaceId: "ws-123",
+  solutionId: "sol-abc",           // optional — falls back to SOLUTION_ID cookie
+  websocketProvider: ws,           // optional — enables realtime sync
+});
+
+// Subscribe (reactive — fires on every change)
+const unsub = copaInputTableDb.collection("invoices")
+  .where("status", "==", "pending")
+  .orderBy("updated_at", "desc")
+  .limit(50)
+  .subscribe((rows) => console.log(rows));
+
+// Cleanup
+unsub();
+```
+
+### CRUD
+
+```typescript
+// One-time fetch
+const rows = await copaInputTableDb.collection("invoices").get();
+const inv  = await copaInputTableDb.collection("invoices").doc(id).get();
+
+// Write
+const newId = await copaInputTableDb.collection("invoices").add({ vendor: "Acme", amount: 100 });
+await copaInputTableDb.collection("invoices").doc(id).update({ status: "approved" });
+await copaInputTableDb.collection("invoices").doc(id).delete();
+
+// Listen to a single doc
+const unsub = copaInputTableDb.collection("invoices").doc(id).onSnapshot((doc) => {
+  console.log(doc);
+});
+
+// Reactive count
+const unsub = copaInputTableDb.collection("invoices").count((n) => console.log(n));
+```
+
+### Query Operators
+
+| Operator  | Meaning         |
+|-----------|-----------------|
+| `==`      | equals          |
+| `!=`      | not equals      |
+| `<`       | less than       |
+| `<=`      | less than or eq |
+| `>`       | greater than    |
+| `>=`      | gte             |
+| `in`      | in array        |
+| `not-in`  | not in array    |
+
+### Framework Integration
+
+**Svelte 5**
+```svelte
+<script>
+  import { copaInputTableDb } from "@bluecopa/core";
+  let rows = $state([]);
+
+  $effect(() =>
+    copaInputTableDb.collection("invoices")
+      .where("status", "==", "pending")
+      .subscribe((r) => { rows = r; })
+  );
+</script>
+```
+
+**React**
+```tsx
+useEffect(() => {
+  return copaInputTableDb.collection("invoices")
+    .where("status", "==", "pending")
+    .subscribe(setRows);
+}, []);
+```
+
+**Vanilla JS**
+```ts
+const unsub = copaInputTableDb.collection("invoices").subscribe(setRows);
+// later:
+unsub();
+```
+
+### WebSocket Provider (optional)
+
+Enables realtime sync via push instead of polling:
+
+```typescript
+import { copaSetConfig, copaInputTableDb, copaUtils } from "@bluecopa/core";
+
+const ws = copaUtils.websocketUtils.WebsocketContextFactory.create("centrifugo", {
+  connectionUrl: "wss://...",
+  token: "jwt",
+  userId: "user-123",
+});
+
+// Option A: via config
+copaSetConfig({ websocketProvider: ws });
+
+// Option B: set directly
+copaInputTableDb.setWebsocketProvider(ws);
+```
+
+If no provider is set, the SDK still works via HTTP pull replication and logs a console warning.
+
+### Cleanup
+
+```typescript
+await copaInputTableDb.destroy(); // closes all collections + WebSocket
+```
+
+---
+
 ## WebSocket Connection
 
 The core package provides WebSocket utilities for real-time communication using Centrifugo.

package/dist/config.d.ts

@@ -1,8 +1,12 @@
+import { IWebsocketProvider } from './utils/websockets/websocketProviderFactory';
+export type { IWebsocketProvider } from './utils/websockets/websocketProviderFactory';
 export interface Config {
     apiBaseUrl: string;
     accessToken: string;
     workspaceId: string;
     userId: string;
+    solutionId?: string;
+    websocketProvider?: IWebsocketProvider;
 }
 declare class ConfigSingleton {
     private static instance;

package/dist/index.d.ts

@@ -1,6 +1,9 @@
 export { setConfig as copaSetConfig, getConfig as copaGetConfig, } from './config';
+export type { Config, IWebsocketProvider } from './config';
 export * as copaApi from './api';
 export * as copaUtils from './utils';
+export { copaInputTableDb, InputTableColumnType, InputTableError } from './input-table-db';
+export type { Row, WhereOp, QueryBuilder, DocRef, CollectionRef, InputTableDB, InputTableDefinition, InputTableColumn, } from './input-table-db';
 export { default as copaTailwindConfig } from './tailwind/bluecopa.config';
 export type { GetAuditLogsRequest, AuditLogResponse, } from './api/audit/getAuditLogs';
 export type { AuditRecord, CreateAuditLogRequest, } from './api/audit/createAuditLog';