@usearete/react 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arete
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,108 @@
+# Arete React SDK
+
+React SDK for real-time Solana program data streaming from Arete.
+
+Built on top of [`@usearete/sdk`](https://www.npmjs.com/package/@usearete/sdk), the pure TypeScript core SDK.
+
+## Installation
+
+```bash
+npm install @usearete/react
+```
+
+> **Not using React?** Use [`@usearete/sdk`](../core/README.md) directly for Vue, Svelte, Node.js, or vanilla JavaScript.
+
+## Usage
+
+### Basic Setup
+
+```tsx
+import { AreteProvider, useArete, defineStack } from '@usearete/react';
+
+const myStack = defineStack({
+  // Your stack configuration
+});
+
+function App() {
+  return (
+    <AreteProvider config={{ /* your config */ }}>
+      <MyComponent />
+    </AreteProvider>
+  );
+}
+
+function MyComponent() {
+  const stack = useArete(myStack);
+  // Use your stack
+}
+```
+
+### Core Features
+
+- **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()`
+
+### API
+
+#### Providers
+
+- `AreteProvider` - Root provider for Arete configuration
+
+#### Hooks
+
+- `useArete` - Main hook for accessing stack functionality
+- `useAreteContext` - Access the runtime context directly
+
+#### View Methods
+
+- `.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`)
+
+#### Factory Functions
+
+- `defineStack` - Define a new stack configuration
+- `createStateView` - Create a state view
+- `createListView` - Create a list view
+- `createRuntime` - Create a runtime instance
+
+#### Utilities
+
+- `ConnectionManager` - Manage WebSocket connections
+
+## Relationship with @usearete/sdk
+
+This package depends on and re-exports the core `@usearete/sdk` package. The core SDK provides:
+
+- `Arete` - Main client class
+- `ConnectionManager` - WebSocket connection handling
+- `EntityStore` - State management
+- AsyncIterable-based streaming APIs
+
+The React SDK adds:
+
+- `AreteProvider` - React context provider
+- `useArete` - Main hook for accessing stacks
+- `useConnectionState` - Connection monitoring hook
+- `defineStack`, `createStateView`, `createListView` - React-friendly factories
+
+If you need low-level access, you can import directly from the core:
+
+```typescript
+import { Arete, ConnectionManager } from '@usearete/react';
+// or
+import { Arete, ConnectionManager } from '@usearete/sdk';
+```
+
+## License
+
+MIT
+
+## Author
+
+Arete Team

package/dist/index.d.ts

@@ -0,0 +1,211 @@
+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 { UseBoundStore, StoreApi } from 'zustand';
+
+type ViewMode = 'state' | 'list';
+interface TransactionDefinition<TParams = unknown> {
+    build: (params: TParams) => {
+        instruction: string;
+        params: TParams;
+    };
+    refresh?: Array<{
+        view: string;
+        key?: string | ((params: TParams) => string);
+    }>;
+}
+/**
+ * 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: '...' })
+ */
+interface AreteConfig {
+    autoConnect?: boolean;
+    wallet?: WalletAdapter;
+    reconnectIntervals?: number[];
+    maxReconnectAttempts?: number;
+    maxEntriesPerView?: number | null;
+    flushIntervalMs?: number;
+    /** Authentication configuration */
+    auth?: _usearete_sdk.AuthConfig;
+}
+/**
+ * Options for useArete hook
+ */
+interface UseAreteOptions {
+    /** Override the stack's embedded URL (useful for local development) */
+    url?: string;
+}
+interface ViewHookOptions<TSchema = unknown> {
+    enabled?: boolean;
+    initialData?: unknown;
+    refreshOnReconnect?: boolean;
+    /** Schema to validate entities. Returns undefined if validation fails. */
+    schema?: Schema<TSchema>;
+    /** Whether to include initial snapshot (defaults to true) */
+    withSnapshot?: boolean;
+    /** Cursor for resuming from a specific point (_seq value) */
+    after?: string;
+    /** Maximum number of entities to include in snapshot */
+    snapshotLimit?: number;
+}
+interface ViewHookResult<T> {
+    data: T | undefined;
+    isLoading: boolean;
+    error?: Error;
+    refresh: () => void;
+}
+interface ListParamsBase<TSchema = unknown> {
+    key?: string;
+    where?: Record<string, unknown>;
+    limit?: number;
+    filters?: Record<string, string>;
+    skip?: number;
+    /** Schema to validate/filter entities. Only entities passing safeParse will be returned. */
+    schema?: Schema<TSchema>;
+    /** Whether to include initial snapshot (defaults to true) */
+    withSnapshot?: boolean;
+    /** Cursor for resuming from a specific point (_seq value) */
+    after?: string;
+    /** Maximum number of entities to include in snapshot */
+    snapshotLimit?: number;
+}
+interface ListParamsSingle<TSchema = unknown> extends ListParamsBase<TSchema> {
+    take: 1;
+}
+interface ListParamsMultiple<TSchema = unknown> extends ListParamsBase<TSchema> {
+    take?: number;
+}
+type ListParams<TSchema = unknown> = ListParamsSingle<TSchema> | ListParamsMultiple<TSchema>;
+interface UseMutationReturn {
+    submit: (instructionOrTx: unknown | unknown[]) => Promise<string>;
+    status: 'idle' | 'pending' | 'success' | 'error';
+    error?: string;
+    signature?: string;
+    reset: () => void;
+}
+interface StateViewHook<T> {
+    use: (key: {
+        [keyField: string]: string;
+    }, options?: ViewHookOptions) => ViewHookResult<T>;
+}
+interface ListViewHook<T> {
+    use<TSchema = T>(params: ListParamsSingle<TSchema>, options?: ViewHookOptions): ViewHookResult<TSchema | undefined>;
+    use<TSchema = T>(params?: ListParamsMultiple<TSchema>, options?: ViewHookOptions): ViewHookResult<TSchema[]>;
+    useOne: <TSchema = T>(params?: Omit<ListParamsBase<TSchema>, 'take'>, options?: ViewHookOptions) => ViewHookResult<TSchema | undefined>;
+}
+
+interface AreteContextValue {
+    getOrCreateClient: <TStack extends StackDefinition>(stack: TStack, urlOverride?: string) => Promise<Arete<TStack>>;
+    getClient: <TStack extends StackDefinition>(stack: TStack | undefined) => Arete<TStack> | null;
+    subscribeToClientChanges: (callback: () => void) => () => void;
+    config: AreteConfig;
+}
+declare function AreteProvider({ children, fallback, ...config }: AreteConfig & {
+    children: ReactNode;
+    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;
+
+type MutationStatus = 'idle' | 'pending' | 'success' | 'error';
+interface UseMutationOptions extends InstructionExecutorOptions {
+    onSuccess?: (result: ExecutionResult) => void;
+    onError?: (error: Error) => void;
+}
+interface UseMutationResult {
+    submit: (args: Record<string, unknown>, options?: Partial<UseMutationOptions>) => Promise<ExecutionResult>;
+    status: MutationStatus;
+    error: string | null;
+    signature: string | null;
+    isLoading: boolean;
+    reset: () => void;
+}
+declare function useInstructionMutation(execute: InstructionExecutor): UseMutationResult;
+
+interface ZustandState {
+    entities: Map<string, Map<string, unknown>>;
+    viewConfigs: Map<string, ViewSortConfig>;
+    connectionState: ConnectionState;
+    lastError?: string;
+}
+interface ZustandActions {
+    _set: <T>(viewPath: string, key: string, data: T) => void;
+    _delete: (viewPath: string, key: string) => void;
+    _clear: (viewPath?: string) => void;
+    _setConnectionState: (state: ConnectionState, error?: string) => void;
+    _setViewConfig: (viewPath: string, config: ViewSortConfig) => void;
+}
+type AreteStore = ZustandState & ZustandActions;
+declare class ZustandAdapter implements StorageAdapter {
+    private updateCallbacks;
+    private richUpdateCallbacks;
+    private accessOrder;
+    readonly store: UseBoundStore<StoreApi<AreteStore>>;
+    constructor(_config?: StorageAdapterConfig);
+    get<T>(viewPath: string, key: string): T | null;
+    getAll<T>(viewPath: string): T[];
+    getAllSync<T>(viewPath: string): T[] | undefined;
+    getSync<T>(viewPath: string, key: string): T | null | undefined;
+    has(viewPath: string, key: string): boolean;
+    keys(viewPath: string): string[];
+    size(viewPath: string): number;
+    set<T>(viewPath: string, key: string, data: T): void;
+    delete(viewPath: string, key: string): void;
+    clear(viewPath?: string): void;
+    evictOldest(viewPath: string): string | undefined;
+    onUpdate(callback: UpdateCallback): () => void;
+    onRichUpdate(callback: RichUpdateCallback): () => void;
+    notifyUpdate<T>(viewPath: string, key: string, update: Update<T>): void;
+    notifyRichUpdate<T>(viewPath: string, key: string, update: RichUpdate<T>): void;
+    setConnectionState(state: ConnectionState, error?: string): void;
+    setViewConfig(viewPath: string, config: ViewSortConfig): void;
+    getViewConfig(viewPath: string): ViewSortConfig | 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'> ? {
+    use: {
+        <TSchema = T>(params: ListParamsSingle<TSchema>, options?: ViewHookOptions<TSchema>): ViewHookResult<TSchema | undefined>;
+        <TSchema = T>(params?: ListParamsMultiple<TSchema>, options?: ViewHookOptions<TSchema>): ViewHookResult<TSchema[]>;
+    };
+    useOne: <TSchema = T>(params?: Omit<ListParamsBase<TSchema>, 'take'>, options?: ViewHookOptions<TSchema>) => ViewHookResult<TSchema | undefined>;
+} : TDef extends ViewDef<infer T, 'state' | 'list'> ? {
+    use: {
+        <TSchema = T>(params: ListParamsSingle<TSchema>, options?: ViewHookOptions<TSchema>): ViewHookResult<TSchema | undefined>;
+        <TSchema = T>(params?: ListParamsMultiple<TSchema> | Record<string, string>, options?: ViewHookOptions<TSchema>): ViewHookResult<TSchema | TSchema[]>;
+    };
+    useOne: <TSchema = T>(params?: Omit<ListParamsBase<TSchema>, 'take'>, options?: ViewHookOptions<TSchema>) => ViewHookResult<TSchema | undefined>;
+} : never;
+type BuildViewInterface<TViews extends Record<string, ViewGroup>> = {
+    [K in keyof TViews]: {
+        [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> = {
+    views: BuildViewInterface<TStack['views']>;
+    instructions: BuildInstructionInterface<TStack['instructions']>;
+    zustandStore: UseBoundStore<StoreApi<AreteStore>>;
+    client: Arete<TStack>;
+    connectionState: ConnectionState;
+    isConnected: boolean;
+    isLoading: boolean;
+    error: Error | null;
+};
+declare function useArete<TStack extends StackDefinition>(stack: TStack, options?: UseAreteOptions): StackClient<TStack>;
+
+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 };