@usearete/react 0.1.5 → 0.2.0

package/README.md

@@ -1,108 +1,162 @@
 # Arete React SDK
 
-React SDK for real-time Solana program data streaming from Arete.
+React hooks and provider for consuming Arete stacks in React applications.
 
-Built on top of [`@usearete/sdk`](https://www.npmjs.com/package/@usearete/sdk), the pure TypeScript core SDK.
+Built on top of [`@usearete/sdk`](https://www.npmjs.com/package/@usearete/sdk), the framework-agnostic TypeScript core SDK.
 
 ## Installation
 
 ```bash
-npm install @usearete/react
+npm install @usearete/react react zustand
 ```
 
-> **Not using React?** Use [`@usearete/sdk`](../core/README.md) directly for Vue, Svelte, Node.js, or vanilla JavaScript.
+> Not using React? Use [`@usearete/sdk`](../core/README.md) directly.
 
-## Usage
-
-### Basic Setup
+## Quick Start
 
 ```tsx
-import { AreteProvider, useArete, defineStack } from '@usearete/react';
+import { AreteProvider, useArete } from '@usearete/react';
+import { ORE_STREAM_STACK } from './generated/ore-stack';
+
+function Dashboard() {
+  const { views, isLoading, error } = useArete(ORE_STREAM_STACK, {
+    url: 'ws://localhost:8877',
+    httpUrl: 'http://localhost:8877',
+  });
+
+  const { data: latestRound } = views.OreRound.latest.useOne();
 
-const myStack = defineStack({
-  // Your stack configuration
-});
+  if (isLoading) {
+    return <div>Connecting...</div>;
+  }
+
+  if (error) {
+    return <div>{error.message}</div>;
+  }
+
+  return <pre>{JSON.stringify(latestRound, null, 2)}</pre>;
+}
 
-function App() {
+export default function App() {
   return (
-    <AreteProvider config={{ /* your config */ }}>
-      <MyComponent />
+    <AreteProvider
+      autoConnect={true}
+      auth={{
+        // publishableKey: 'hspk_...',
+      }}
+    >
+      <Dashboard />
     </AreteProvider>
   );
 }
-
-function MyComponent() {
-  const stack = useArete(myStack);
-  // Use your stack
-}
 ```
 
-### Core Features
+## Provider
 
-- **Real-time Data Streaming**: Subscribe to Solana program state changes
-- **React Integration**: Hooks-based API for easy integration with React applications
-- **State Management**: Built-in state management with Zustand
-- **Type Safety**: Full TypeScript support with comprehensive type definitions
-- **View Definitions**: Create state and list views for your data
-- **Transaction Handling**: Define and execute transactions with hooks
-- **Single Item Queries**: Type-safe single item fetching with `take: 1` or `useOne()`
+`AreteProvider` manages connected clients for descendant hooks.
 
-### API
+Supported props:
 
-#### Providers
+- `autoConnect`
+- `wallet`
+- `auth`
+- `fetch`
+- `validateFrames`
+- `reconnectIntervals`
+- `maxReconnectAttempts`
+- `maxEntriesPerView`
+- `flushIntervalMs`
 
-- `AreteProvider` - Root provider for Arete configuration
+These are provider-wide defaults. Endpoint overrides stay on the hook call.
 
-#### Hooks
+## `useArete(stack, options?)`
 
-- `useArete` - Main hook for accessing stack functionality
-- `useAreteContext` - Access the runtime context directly
+`useArete` returns the connected React surface for a stack:
 
-#### View Methods
+- `views`
+- `programs`
+- `queries`
+- `chain`
+- `client`
+- `connectionState`
+- `isConnected`
+- `isLoading`
+- `error`
 
-- `.use()` - Subscribe to view data (returns `T[]` for lists, `T` for state)
-- `.use({ take: 1 })` - Subscribe to single item with type narrowing (returns `T | undefined`)
-- `.useOne()` - Convenience method for single item queries (returns `T | undefined`)
+Supported hook options:
 
-#### Factory Functions
+- `url`
+- `httpUrl`
+- `transport`
+- `programs`
 
-- `defineStack` - Define a new stack configuration
-- `createStateView` - Create a state view
-- `createListView` - Create a list view
-- `createRuntime` - Create a runtime instance
+Notes:
 
-#### Utilities
+- `transport: 'http'` disables streaming view subscriptions, but HTTP-backed surfaces like `queries`, `chain`, and program reads still work.
+- If you pass attached `programs`, keep that object stable with a module constant or `useMemo` so React does not create a fresh client on every render.
 
-- `ConnectionManager` - Manage WebSocket connections
+## Views
 
-## Relationship with @usearete/sdk
+View hooks return a `ViewHookResult<T>` object:
 
-This package depends on and re-exports the core `@usearete/sdk` package. The core SDK provides:
+```ts
+type ViewHookResult<T> = {
+  data: T | undefined;
+  isLoading: boolean;
+  error?: Error;
+  refresh: () => void;
+};
+```
 
-- `Arete` - Main client class
-- `ConnectionManager` - WebSocket connection handling
-- `EntityStore` - State management
-- AsyncIterable-based streaming APIs
+List views support:
 
-The React SDK adds:
+- `.use()`
+- `.use({ take: 1 })`
+- `.useOne()`
 
-- `AreteProvider` - React context provider
-- `useArete` - Main hook for accessing stacks
-- `useConnectionState` - Connection monitoring hook
-- `defineStack`, `createStateView`, `createListView` - React-friendly factories
+State views support:
 
-If you need low-level access, you can import directly from the core:
+- `.use(key)`
 
-```typescript
-import { Arete, ConnectionManager } from '@usearete/react';
-// or
-import { Arete, ConnectionManager } from '@usearete/sdk';
-```
+## Programs, Queries, and Chain
 
-## License
+`useArete` mirrors the connected core client surface:
 
-MIT
+- `programs.<program>.raw.<instruction>` for raw typed instructions
+- `programs.<program>.plan` / `programs.<program>.instructions` for semantic instructions
+- `programs.<program>.accounts` and `programs.<program>.queries` for HTTP reads
+- `queries` for stack-level HTTP queries
+- `chain` for chain helpers
 
-## Author
+Raw instruction hooks preserve `.execute`, `.build`, and `.useMutation()`.
 
-Arete Team
+Semantic instruction hooks preserve:
+
+- `.execute`
+- `.send`
+- `.resolve`
+- `.plan`
+- `.build`
+- `.stage`
+- `.useMutation()`
+
+## Low-Level Hooks
+
+The React SDK also exports:
+
+- `useConnectionState`
+- `useView`
+- `useEntity`
+- `useAreteContext`
+
+These accept the same client lookup overrides when you need to target a non-default client.
+
+## Relationship with `@usearete/sdk`
+
+`@usearete/react` re-exports selected core APIs and types for convenience, but it is not a complete mirror of the core package.
+
+If you need the full low-level surface, import directly from `@usearete/sdk`.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -1,7 +1,6 @@
 import React, { ReactNode } from 'react';
-import * as _usearete_sdk from '@usearete/sdk';
-import { WalletAdapter, Schema, StackDefinition, ConnectionState, Arete, InstructionExecutorOptions, ExecutionResult, InstructionExecutor, StorageAdapter, StorageAdapterConfig, UpdateCallback, RichUpdateCallback, Update, RichUpdate, ViewSortConfig, ViewGroup, ViewDef, InstructionHandler } from '@usearete/sdk';
-export { AccountCategory, AccountMeta, AccountResolutionOptions, AccountResolutionResult, Arete, AreteError, AreteOptions, AreteOptionsWithStorage, ArgSchema, ArgType, BuiltInstruction, ConfirmationLevel, ConnectionManager, ConnectionState, DEFAULT_CONFIG, DEFAULT_MAX_ENTRIES_PER_VIEW, EntityFrame, ErrorMetadata, ExecuteOptions, ExecutionResult, Frame, FrameMode, FrameOp, FrameProcessor, FrameProcessorConfig, InstructionDefinition, InstructionExecutor, InstructionExecutorOptions, InstructionHandler, MemoryAdapter, PdaConfig, PdaSeed, ProgramError, ResolvedAccount, ResolvedAccounts, RichUpdate, RichUpdateCallback, Schema, SnapshotEntity, SnapshotFrame, StackDefinition, StorageAdapter, StorageAdapterConfig, Subscription, SubscriptionRegistry, Update, UpdateCallback, ViewDef, ViewGroup, WalletAdapter, WalletConnectOptions, WalletState, createInstructionExecutor, createPublicKeySeed, createSeed, derivePda, executeInstruction, formatProgramError, isSnapshotFrame, isValidFrame, parseFrame, parseFrameFromBlob, parseInstructionError, resolveAccounts, serializeInstructionData, validateAccountResolution, waitForConfirmation } from '@usearete/sdk';
+import { WalletAdapter, ConnectOptions, AuthConfig, Schema, ProgramSdkDefinition, StackDefinition, ConnectionState, ConnectedArete, StackWithAttachedPrograms, ProgramInterface, TypedInstruction, PreparedOperation, OperationReceiptFor, StorageAdapter, StorageAdapterConfig, UpdateCallback, RichUpdateCallback, Update, RichUpdate, ViewSortConfig, QueriesInterface, ChainClient, StackQueryDefinition, ViewGroup, ViewDef } from '@usearete/sdk';
+export { AccountCategory, AccountMeta, AccountResolutionOptions, AccountResolutionResult, Arete, AreteError, AreteOptions, AreteOptionsWithStorage, ArgSchema, ArgType, AuthConfig, BuildOptions, BuiltAccountMeta, BuiltInstruction, ConfirmationLevel, ConnectOptions, ConnectedArete, ConnectionManager, ConnectionState, DEFAULT_CONFIG, DEFAULT_MAX_ENTRIES_PER_VIEW, EntityFrame, ErrorMetadata, ExecuteOptions, ExecutionResult, Frame, FrameMode, FrameOp, FrameProcessor, FrameProcessorConfig, InstructionError, InstructionExecutor, InstructionHandler, InstructionHandlerConfig, MemoryAdapter, MergeProgramMaps, OperationExecutionOptions, OperationReceiptFor, PdaConfig, PdaSeed, PreparedFlow, PreparedInstruction, PreparedOperation, PreparedTransaction, PreparedTransactionInstruction, ProgramError, ReadRequestError, ResolvedAccount, ResolvedAccounts, RichUpdate, RichUpdateCallback, Schema, SendOptions, SendResult, SnapshotEntity, SnapshotFrame, StackDefinition, StackWithAttachedPrograms, StorageAdapter, StorageAdapterConfig, Subscription, SubscriptionRegistry, TransactionOptions, TypedInstruction, Update, UpdateCallback, ViewDef, ViewGroup, WalletAdapter, WalletConnectOptions, WalletState, buildInstruction, createInstructionExecutor, createInstructionHandler, createPublicKeySeed, createSeed, derivePda, executeInstruction, formatProgramError, isSnapshotFrame, isValidFrame, parseFrame, parseFrameFromBlob, parseInstructionError, resolveAccounts, serializeInstructionData, validateAccountResolution, withPrograms } from '@usearete/sdk';
 import { UseBoundStore, StoreApi } from 'zustand';
 
 type ViewMode = 'state' | 'list';
@@ -15,12 +14,13 @@ interface TransactionDefinition<TParams = unknown> {
         key?: string | ((params: TParams) => string);
     }>;
 }
+type ProgramMap$2 = Record<string, ProgramSdkDefinition>;
 /**
  * Global configuration for AreteProvider.
  *
  * Note: WebSocket URL is no longer configured here. The URL is:
- * 1. Embedded in the stack definition (stack.url)
- * 2. Optionally overridden per-hook via useArete(stack, { url: '...' })
+ * 1. Embedded in the stack definition (`stack.endpoints.ws` / `stack.endpoints.http`)
+ * 2. Optionally overridden per-hook via `useArete(stack, { url, httpUrl })`
  */
 interface AreteConfig {
     autoConnect?: boolean;
@@ -29,16 +29,25 @@ interface AreteConfig {
     maxReconnectAttempts?: number;
     maxEntriesPerView?: number | null;
     flushIntervalMs?: number;
+    fetch?: ConnectOptions['fetch'];
+    validateFrames?: boolean;
     /** Authentication configuration */
-    auth?: _usearete_sdk.AuthConfig;
+    auth?: AuthConfig;
 }
 /**
- * Options for useArete hook
+ * Client lookup/connect options for React hooks.
  */
-interface UseAreteOptions {
-    /** Override the stack's embedded URL (useful for local development) */
+interface ClientLookupOptions<TPrograms extends ProgramMap$2 | undefined = undefined> {
+    /** Override the stack's embedded WebSocket URL (useful for local development) */
     url?: string;
+    /** Override the stack's embedded HTTP read URL (useful for local development) */
+    httpUrl?: string;
+    /** Override the stack transport. HTTP mode disables streaming view subscriptions. */
+    transport?: ConnectOptions<TPrograms>['transport'];
+    /** Attach additional program SDKs to the connected client. */
+    programs?: TPrograms;
 }
+type UseAreteOptions<TPrograms extends ProgramMap$2 | undefined = undefined> = ClientLookupOptions<TPrograms>;
 interface ViewHookOptions<TSchema = unknown> {
     enabled?: boolean;
     initialData?: unknown;
@@ -98,9 +107,11 @@ interface ListViewHook<T> {
     useOne: <TSchema = T>(params?: Omit<ListParamsBase<TSchema>, 'take'>, options?: ViewHookOptions) => ViewHookResult<TSchema | undefined>;
 }
 
+type ProgramMap$1 = Record<string, ProgramSdkDefinition>;
+type ResolvedStack$1<TStack extends StackDefinition, TPrograms extends ProgramMap$1 | undefined> = StackWithAttachedPrograms<TStack, TPrograms>;
 interface AreteContextValue {
-    getOrCreateClient: <TStack extends StackDefinition>(stack: TStack, urlOverride?: string) => Promise<Arete<TStack>>;
-    getClient: <TStack extends StackDefinition>(stack: TStack | undefined) => Arete<TStack> | null;
+    getOrCreateClient: <TStack extends StackDefinition, TPrograms extends ProgramMap$1 | undefined = undefined>(stack: TStack, options?: ClientLookupOptions<TPrograms>) => Promise<ConnectedArete<ResolvedStack$1<TStack, TPrograms>>>;
+    getClient: <TStack extends StackDefinition, TPrograms extends ProgramMap$1 | undefined = undefined>(stack: TStack | undefined, options?: ClientLookupOptions<TPrograms>) => ConnectedArete<ResolvedStack$1<TStack, TPrograms>> | null;
     subscribeToClientChanges: (callback: () => void) => () => void;
     config: AreteConfig;
 }
@@ -109,24 +120,71 @@ declare function AreteProvider({ children, fallback, ...config }: AreteConfig &
     fallback?: ReactNode;
 }): React.JSX.Element;
 declare function useAreteContext(): AreteContextValue;
-declare function useConnectionState(stack?: StackDefinition): ConnectionState;
-declare function useView<T>(stack: StackDefinition, viewPath: string): T[];
-declare function useEntity<T>(stack: StackDefinition, viewPath: string, key: string): T | null;
+declare function useConnectionState(stack?: StackDefinition, options?: ClientLookupOptions): ConnectionState;
+declare function useView<T>(stack: StackDefinition, viewPath: string, options?: ClientLookupOptions): T[];
+declare function useEntity<T>(stack: StackDefinition, viewPath: string, key: string, options?: ClientLookupOptions): T | null;
 
 type MutationStatus = 'idle' | 'pending' | 'success' | 'error';
-interface UseMutationOptions extends InstructionExecutorOptions {
-    onSuccess?: (result: ExecutionResult) => void;
+type UseMutationOptions<TOptions extends object = Record<string, never>, TResult = unknown> = TOptions & {
+    onSuccess?: (result: TResult) => void;
     onError?: (error: Error) => void;
-}
-interface UseMutationResult {
-    submit: (args: Record<string, unknown>, options?: Partial<UseMutationOptions>) => Promise<ExecutionResult>;
+};
+/**
+ * Result of {@link useInstructionMutation}.
+ *
+ * `TParams` is the merged params object accepted by the instruction (IDL args
+ * plus any user-provided account addresses), inferred from the generated
+ * handler. `TError` is the handler's typed program-error union.
+ */
+interface UseMutationResult<TParams = Record<string, unknown>, TResult = unknown, TOptions extends object = Record<string, never>> {
+    submit: (args: TParams, options?: Partial<UseMutationOptions<TOptions, TResult>>) => Promise<TResult>;
     status: MutationStatus;
     error: string | null;
+    signatures: string[];
     signature: string | null;
     isLoading: boolean;
     reset: () => void;
 }
-declare function useInstructionMutation(execute: InstructionExecutor): UseMutationResult;
+type MutationExecutor<TParams = Record<string, unknown>, TResult = unknown, TOptions extends object = Record<string, never>> = {
+    (args: TParams, options?: TOptions): Promise<TResult>;
+};
+declare function useInstructionMutation<TParams = Record<string, unknown>, TResult = unknown, TOptions extends object = Record<string, never>>(execute: MutationExecutor<TParams, TResult, TOptions>): UseMutationResult<TParams, TResult, TOptions>;
+
+type OperationOptionsArg<TClient> = TClient extends {
+    execute(prepared: PreparedOperation, options?: infer TOptions): Promise<unknown>;
+} ? NonNullable<TOptions> : Record<string, never>;
+type RawOptionsArg<TClient> = TClient extends {
+    transaction(instructions: readonly unknown[], options?: infer TOptions): Promise<unknown>;
+} ? NonNullable<TOptions> : Record<string, never>;
+type ConnectedOperationLike = {
+    prepare(input: unknown): Promise<PreparedOperation>;
+};
+type RawInstructionHookFor<THandler, TClient> = THandler extends TypedInstruction<infer P, infer E> ? {
+    useMutation: () => UseMutationResult<P, E, RawOptionsArg<TClient>>;
+    execute: (input: P, options?: RawOptionsArg<TClient>) => Promise<E>;
+    build: THandler['build'];
+} : never;
+type OperationHookFor<TOperation, TClient> = TOperation extends {
+    prepare(input: infer P): Promise<infer TPrepared extends PreparedOperation>;
+} ? {
+    useMutation: () => UseMutationResult<P, OperationReceiptFor<TPrepared>, OperationOptionsArg<TClient>>;
+    execute: (input: P, options?: OperationOptionsArg<TClient>) => Promise<OperationReceiptFor<TPrepared>>;
+    prepare: TOperation['prepare'];
+} : never;
+type OperationHookNamespace<TNamespace, TClient> = {
+    [K in keyof TNamespace]: TNamespace[K] extends ConnectedOperationLike ? OperationHookFor<TNamespace[K], TClient> : TNamespace[K] extends Record<string, unknown> ? OperationHookNamespace<TNamespace[K], TClient> : never;
+};
+type ProgramHookInterface<TProgram extends ProgramSdkDefinition, TClient> = Omit<ProgramInterface<TProgram>, 'raw' | 'instructions' | 'transactions' | 'flows'> & {
+    raw: {
+        [K in keyof ProgramInterface<TProgram>['raw']]: RawInstructionHookFor<ProgramInterface<TProgram>['raw'][K], TClient>;
+    };
+    instructions: OperationHookNamespace<ProgramInterface<TProgram>['instructions'], TClient>;
+    transactions: OperationHookNamespace<ProgramInterface<TProgram>['transactions'], TClient>;
+    flows: OperationHookNamespace<ProgramInterface<TProgram>['flows'], TClient>;
+};
+type BuildProgramInterface<TPrograms extends Record<string, ProgramSdkDefinition> | undefined, TClient> = TPrograms extends Record<string, ProgramSdkDefinition> ? {
+    [K in keyof TPrograms]: ProgramHookInterface<TPrograms[K], TClient>;
+} : Record<string, never>;
 
 interface ZustandState {
     entities: Map<string, Map<string, unknown>>;
@@ -168,6 +226,14 @@ declare class ZustandAdapter implements StorageAdapter {
     getViewConfig(viewPath: string): ViewSortConfig | undefined;
 }
 
+type ProgramMap = Record<string, ProgramSdkDefinition>;
+type ResolvedStack<TStack extends StackDefinition, TPrograms extends ProgramMap | undefined> = StackWithAttachedPrograms<TStack, TPrograms>;
+type StackQueries<TStack> = TStack extends {
+    queries?: infer TQueries extends Record<string, StackQueryDefinition<unknown, unknown>> | undefined;
+} ? TQueries : undefined;
+type StackPrograms<TStack> = TStack extends {
+    programs?: infer TPrograms extends Record<string, ProgramSdkDefinition> | undefined;
+} ? TPrograms : undefined;
 type ViewHookForDef<TDef> = TDef extends ViewDef<infer T, 'state'> ? {
     use: <TSchema = T>(key?: Record<string, string>, options?: ViewHookOptions<TSchema>) => ViewHookResult<TSchema>;
 } : TDef extends ViewDef<infer T, 'list'> ? {
@@ -188,24 +254,19 @@ type BuildViewInterface<TViews extends Record<string, ViewGroup>> = {
         [SubK in keyof TViews[K] as TViews[K][SubK] extends ViewDef<unknown, ViewMode> ? SubK : never]: ViewHookForDef<TViews[K][SubK]>;
     };
 };
-type InstructionHook = {
-    useMutation: () => UseMutationResult;
-    execute: InstructionExecutor;
-};
-type BuildInstructionInterface<TInstructions extends Record<string, InstructionHandler> | undefined> = TInstructions extends Record<string, InstructionHandler> ? {
-    [K in keyof TInstructions]: InstructionHook;
-} : {};
-type StackClient<TStack extends StackDefinition> = {
+type StackClient<TStack extends StackDefinition, TPrograms extends ProgramMap | undefined> = {
     views: BuildViewInterface<TStack['views']>;
-    instructions: BuildInstructionInterface<TStack['instructions']>;
+    queries: QueriesInterface<StackQueries<ResolvedStack<TStack, TPrograms>>>;
+    programs: BuildProgramInterface<StackPrograms<ResolvedStack<TStack, TPrograms>>, ConnectedArete<ResolvedStack<TStack, TPrograms>>>;
+    chain: ChainClient;
     zustandStore: UseBoundStore<StoreApi<AreteStore>>;
-    client: Arete<TStack>;
+    client: ConnectedArete<ResolvedStack<TStack, TPrograms>>;
     connectionState: ConnectionState;
     isConnected: boolean;
     isLoading: boolean;
     error: Error | null;
 };
-declare function useArete<TStack extends StackDefinition>(stack: TStack, options?: UseAreteOptions): StackClient<TStack>;
+declare function useArete<TStack extends StackDefinition, TPrograms extends ProgramMap | undefined = undefined>(stack: TStack, options?: UseAreteOptions<TPrograms>): StackClient<TStack, TPrograms>;
 
 export { AreteProvider, ZustandAdapter, useArete, useAreteContext, useConnectionState, useEntity, useInstructionMutation, useView };
-export type { AreteConfig, AreteStore, ListParams, ListParamsBase, ListParamsMultiple, ListParamsSingle, ListViewHook, MutationStatus, StateViewHook, TransactionDefinition, UseAreteOptions, UseMutationOptions, UseMutationResult, UseMutationReturn, ViewHookOptions, ViewHookResult, ViewMode };
+export type { AreteConfig, AreteStore, ClientLookupOptions, ListParams, ListParamsBase, ListParamsMultiple, ListParamsSingle, ListViewHook, MutationStatus, StateViewHook, TransactionDefinition, UseAreteOptions, UseMutationOptions, UseMutationResult, UseMutationReturn, ViewHookOptions, ViewHookResult, ViewMode };