@thru/thru-sdk 0.1.16 → 0.1.19

package/README.md

@@ -36,6 +36,83 @@ const { rawTransaction, signature } = await thru.transactions.buildAndSign({
 await thru.transactions.send(rawTransaction);
 ```
 
+### Using Filters
+
+Many SDK functions support CEL (Common Expression Language) filters to query or stream data based on custom expressions evaluated server-side. Filters are constructed using the `create` function from `@bufbuild/protobuf` (already a dependency of `@thru/thru-sdk`).
+
+#### Constructing Filters
+
+```ts
+import { create } from "@bufbuild/protobuf";
+import { 
+  FilterSchema, 
+  FilterParamValueSchema,
+  type Filter,
+  type FilterParamValue 
+} from "@thru/thru-sdk";
+
+// Create a filter parameter value
+const paramValue = create(FilterParamValueSchema, {
+  kind: {
+    case: "bytesValue", // or "stringValue", "boolValue", "intValue", "doubleValue"
+    value: new Uint8Array(32), // the actual value
+  },
+});
+
+// Create the filter with a CEL expression
+const filter = create(FilterSchema, {
+  expression: "meta.owner.value == params.owner_bytes",
+  params: {
+    owner_bytes: paramValue,
+  },
+});
+```
+
+#### Filter Parameter Value Types
+
+Filter parameters support these types:
+- `{ case: "stringValue", value: string }` - for string parameters
+- `{ case: "bytesValue", value: Uint8Array }` - for byte array parameters
+- `{ case: "boolValue", value: boolean }` - for boolean parameters
+- `{ case: "intValue", value: bigint }` - for integer parameters
+- `{ case: "doubleValue", value: number }` - for floating-point parameters
+
+#### Functions That Accept Filters
+
+**Query Functions:**
+- `thru.accounts.list({ filter })` - List accounts with filtering
+- `thru.blocks.list({ filter })` - List blocks with filtering
+- `thru.transactions.listForAccount(account, { filter })` - List transactions for an account with filtering
+
+**Streaming Functions:**
+- `thru.streaming.streamBlocks({ filter })` - Stream blocks with filtering
+- `thru.streaming.streamAccountUpdates(address, { filter })` - Stream account updates with filtering
+- `thru.streaming.streamTransactions({ filter })` - Stream transactions with filtering
+- `thru.streaming.streamEvents({ filter })` - Stream events with filtering
+
+#### Example: Filtering Accounts by Owner
+
+```ts
+// List accounts owned by a specific public key
+const ownerBytes = new Uint8Array(32); // your owner pubkey bytes
+
+const ownerParam = create(FilterParamValueSchema, {
+  kind: {
+    case: "bytesValue",
+    value: ownerBytes,
+  },
+});
+
+const filter = create(FilterSchema, {
+  expression: "meta.owner.value == params.owner_bytes",
+  params: {
+    owner_bytes: ownerParam,
+  },
+});
+
+const response = await thru.accounts.list({ filter });
+```
+
 ### Modules at a Glance
 
 - `thru.blocks` — query finalized or raw blocks and stream height information