@usearete/sdk 0.2.0 → 0.4.0

package/README.md

@@ -2,6 +2,8 @@
 
 Pure TypeScript SDK for generated stack definitions, program SDKs, prepared operation execution, and chain reads.
 
+Connected clients expose the typed six-route transaction relay as `client.transactions`. Wallet adapters receive it per invocation from `client.transaction` and `client.inspectOperation`, so a shared wallet can safely serve multiple clients. Sessions expose `session.transactions` and accept a `transactions` override. HTTP `u64` fields are decimal strings on the wire and `bigint` in the SDK; sends are never automatically retried.
+
 ## Installation
 
 ```bash
@@ -81,6 +83,64 @@ Each packaged, attached, or standalone program is canonically available under `s
 - `defaults` - reusable program defaults
 - `math` - pure protocol calculations
 
+### Program Read Transports
+
+Generated account readers use a `ProgramReadDescriptor` for each program. Local
+generation emits an explicit `local-http` descriptor, so the endpoint must come
+from the connection call:
+
+```ts
+const client = await Arete.connect(LOCAL_STACK, {
+  url: 'ws://localhost:8877',
+  httpUrl: 'http://localhost:8877',
+});
+```
+
+Installed hosted SDKs instead contain a complete `hosted-binding` descriptor:
+the release, read endpoint, binding ID, and auth metadata are pinned together.
+Hosted account reads ignore `httpUrl` and stack HTTP endpoints. A
+`programReads` runtime override must replace that complete descriptor; release,
+binding, and endpoint fields are never patched independently.
+
+Stack and program queries remain stack-HTTP operations. They continue to use
+`httpUrl` or `stack.endpoints.http` and do not use a hosted Program Read binding.
+Composition sessions accept only complete hosted descriptors or complete hosted
+overrides, and never infer Program Read endpoints from their members.
+
+### Hosted Solana Gateway Transports
+
+Hosted composition installs also emit complete, independent `chain` and
+`transactions` gateway bindings. Construct both authenticated transports from
+those generated descriptors instead of using a LiveSpec query endpoint:
+
+```ts
+import { createHostedSolanaGatewayTransports } from '@usearete/sdk';
+import { MY_STACK_HOSTED_BINDINGS } from './generated/my-stack';
+
+const { chain, transactions } = createHostedSolanaGatewayTransports(
+  {
+    chain: MY_STACK_HOSTED_BINDINGS.chain,
+    transactions: MY_STACK_HOSTED_BINDINGS.transactions,
+  },
+  {
+    auth: { publishableKey: import.meta.env.VITE_ARETE_PUBLISHABLE_KEY },
+  }
+);
+```
+
+The helper mints tokens for the exact `solana-gateway-binding` target. `read`,
+`transaction:inspect`, and `transaction:send` use separate scope caches. An
+authentication failure is refreshed at most once, and transaction requests are
+replayed only when the gateway explicitly reports that upstream dispatch did
+not begin. Chain and transaction descriptors may intentionally share the same
+endpoint and binding ID.
+
+Generated hosted compositions additionally export
+`create<StackName>HostedSession(options)`. It constructs these transports and
+passes them to the explicit composition session; the lower-level
+`create<StackName>Session(options)` continues to require caller-supplied `chain`
+and `transactions` transports.
+
 ### Raw Instructions
 
 Use raw handlers when you want exact wire control and will compose the transaction yourself:
@@ -307,20 +367,78 @@ for await (const update of session.stacks.myStack.views.settlementGame.list.watc
 const game = await session.stacks.myStack.views.settlementGame.state.get('game-123');
 ```
 
+Every options object is a protocol v2 query with independent ordered membership. Different windows and filters on the same view can run concurrently, while equivalent normalized queries share one reference-counted wire subscription:
+
+```ts
+const rounds = session.stacks.ore.views.OreRound.latest;
+
+const firstPage = rounds.watch({ take: 10 });
+const secondPage = rounds.watch({ take: 10, skip: 10 });
+
+for await (const update of firstPage) {
+  if (update.type === 'remove') {
+    console.log(`${update.key} left the first-page window`);
+  }
+}
+```
+
+Completed authoritative snapshots replace membership for their exact query after reconnect. Cursor queries created with `after` receive incremental snapshots and merge without pruning.
+
+Low-level `QueryLease.refresh()` returns a `Promise<void>` that resolves after the refreshed subscription's next complete snapshot is committed. Registration, send, and subscription failures reject and are published on the lease's `QuerySnapshot.error`, with `isRefreshing` cleared. Subscriptions created with snapshots disabled resolve after the refresh request is sent.
+
+### Connection recovery
+
+`autoConnect` and `autoReconnect` default to `true` and control separate lifecycle phases. Set `autoConnect: false` to create a disconnected client that the application connects later. Set `autoReconnect: false` when the application wants to handle post-disconnect recovery itself:
+
+```ts
+const client = await Arete.connect(MY_STACK, {
+  autoConnect: false,
+  autoReconnect: false,
+});
+```
+
+The same independent options are available per stack member in `createSession(...)` and on React's `AreteProvider`.
+
+### Caller-supplied schema diagnostics
+
+Core view schemas continue to filter rejected entities. React view hooks additionally accept `onSchemaValidationError`, which reports `{ view, key?, entity, error }` without changing accepted data.
+
+## Safe amount parsing
+
+`toRawAmount(input, decimals)` throws when user input is invalid. Form and API boundaries can use `safeToRawAmount(input, decimals)` instead:
+
+```ts
+import { safeToRawAmount } from '@usearete/sdk';
+
+const result = safeToRawAmount({ ui: amountText }, 9);
+if (!result.success) {
+  console.error(result.error);
+  return;
+}
+
+console.log(result.data); // bigint in raw base units
+```
+
+It returns `{ success: true, data } | { success: false, error }` and never throws for an invalid amount input.
+
 ## Update Types
 
 ```ts
 type Update<T> =
   | { type: 'upsert'; key: string; data: T }
   | { type: 'patch'; key: string; data: Partial<T> }
+  | { type: 'remove'; key: string }
   | { type: 'delete'; key: string };
 
 type RichUpdate<T> =
   | { type: 'created'; key: string; data: T }
   | { type: 'updated'; key: string; before: T; after: T; patch?: unknown }
+  | { type: 'removed'; key: string; lastKnown?: T }
   | { type: 'deleted'; key: string; lastKnown?: T };
 ```
 
+`remove` means an entity left only this query's filter or window. `delete` means the source entity was deleted and is removed from every query for that view.
+
 ## License
 
 MIT