@turtleclub/hooks 0.5.0-beta.12 → 0.5.0-beta.14

package/README.md

@@ -1,51 +1,220 @@
-# @turtledev/hooks
+# @turtle-club/hooks
 
-React hooks and utilities for building applications with the Turtle ecosystem.
+React hooks package for Turtle Club APIs, providing type-safe data fetching with TanStack Query integration.
 
 ## Installation
 
 ```bash
-npm install @turtledev/hooks
-# or
-yarn add @turtledev/hooks
-# or
-bun add @turtledev/hooks
+bun add @turtle-club/hooks
 ```
 
-## Features
+## Setup
 
-- 🎣 **React Query hooks** for API endpoints
-- 🔧 **Utility functions** for chains, formatting, and numbers
-- 🔄 **Automatic caching** and persistence
-- 📝 **TypeScript** support with full type safety
+Wrap your application with the `TurtleHooksProvider`:
 
-## Usage
+```tsx
+import { TurtleHooksProvider } from '@turtle-club/hooks';
 
-### API Hooks
+function App() {
+  return (
+    <TurtleHooksProvider
+      apiConfig={{
+        apiKey: 'your-api-key',
+        earnApiKey: 'your-earn-api-key'
+      }}
+    >
+      <YourApp />
+    </TurtleHooksProvider>
+  );
+}
+```
+
+## Package Structure
+
+```
+src/
+├── index.ts                    # Root export (re-exports v2)
+└── v2/
+    ├── index.ts                # Main entry point (aggregates all endpoints)
+    ├── lib/                    # Shared utilities
+    │   ├── api-client.ts       # HTTP client singleton (supports "api" | "earn" domains)
+    │   ├── query-config.ts     # TanStack Query defaults
+    │   └── turtle-provider.tsx # React context provider
+    ├── schemas/                # Shared types across endpoints
+    │   └── shared.ts           # Common schemas (Chain, Token, Opportunity, etc.)
+    └── [endpoint]/             # Individual endpoint folders
+        ├── api.ts              # API functions
+        ├── hooks.ts            # React hooks (queries & mutations)
+        ├── queries.ts          # TanStack Query key factory
+        ├── schema.ts           # Zod schemas & types
+        └── index.ts            # Barrel export
+```
+
+## Endpoint Structure Pattern
+
+Each endpoint follows a consistent 5-file structure:
+
+### 1. `schema.ts` - Zod Schemas & Types
+```typescript
+import { z } from "zod";
+
+// Request schema (if needed)
+export const getResourceRequestSchema = z.object({
+  filter: z.string().optional(),
+});
+
+// Response schema
+export const resourceResponseSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+});
+
+// Infer types from schemas
+export type GetResourceRequest = z.infer<typeof getResourceRequestSchema>;
+export type ResourceResponse = z.infer<typeof resourceResponseSchema>;
+```
+
+### 2. `api.ts` - API Functions
+```typescript
+import type { QueryFunctionContext } from "@tanstack/react-query";
+import { apiClient } from "../lib/api-client";
+import { resourceResponseSchema, type ResourceResponse } from "./schema";
+
+export async function getResource(
+  id: string,
+  context?: QueryFunctionContext
+): Promise<ResourceResponse> {
+  const data = await apiClient.fetch(`/v1/resource/${id}`, {
+    method: "GET",
+    domain: "api", // or "earn" for Earn API
+    signal: context?.signal,
+  });
+
+  const result = resourceResponseSchema.safeParse(data);
+  if (!result.success) {
+    console.log("[ZOD ERROR]", result.error);
+    throw new Error(`Failed to parse resource: ${result.error.message}`);
+  }
+  return result.data;
+}
+```
+
+### 3. `queries.ts` - Query Key Factory
+```typescript
+import { createQueryKeys } from "@lukemorales/query-key-factory";
+import { getResource } from "./api";
 
+export const resourceQueries = createQueryKeys("resource", {
+  byId: (id: string) => ({
+    queryKey: [id],
+    queryFn: (context) => getResource(id, context),
+  }),
+  list: (filters?: Filters) => ({
+    queryKey: [{ filters }],
+    queryFn: (context) => getResources(filters, context),
+  }),
+});
+```
+
+### 4. `hooks.ts` - React Hooks
 ```typescript
-import { useOrganizations, useConfig } from "@turtledev/hooks";
-
-function MyComponent() {
-  const { data: organizations, isLoading } = useOrganizations();
-  
-  if (isLoading) return <div>Loading...</div>;
-  
-  return <div>{organizations?.name}</div>;
+import { useQuery, useMutation } from "@tanstack/react-query";
+import { resourceQueries } from "./queries";
+import { createQueryOptions } from "../lib/query-config";
+
+export interface UseResourceOptions
+  extends Omit<UseQueryOptions<ResourceResponse, Error>, "queryKey" | "queryFn"> {
+  id: string;
 }
+
+export function useResource({ id, ...options }: UseResourceOptions) {
+  return useQuery(createQueryOptions(resourceQueries.byId(id), options));
+}
+
+// For mutations
+export function useCreateResource() {
+  return useMutation({
+    mutationFn: (input: CreateResourceInput) => createResource(input),
+  });
+}
+```
+
+### 5. `index.ts` - Barrel Export
+```typescript
+export * from "./schema";
+export * from "./api";
+export * from "./queries";
+export * from "./hooks";
+```
+
+## Available Endpoints
+
+### Earn API (`domain: "earn"`)
+| Endpoint | Description |
+|----------|-------------|
+| `earn-opportunities` | Earn protocol opportunities |
+| `earn-route` | Route calculations for deposits/withdrawals |
+| `earn-membership` | User membership management |
+| `earn-deposits` | Deposit records |
+| `earn-interactions` | Deposit/withdraw/claim interactions |
+| `enso-balances` | Enso protocol balances |
+
+### Main API (`domain: "api"`)
+| Endpoint | Description |
+|----------|-------------|
+| `opportunities` | General opportunities |
+| `products` | Product CRUD operations |
+| `balance` | Portfolio and token balances |
+| `widget` | Widget configuration |
+| `supported-chains` | Chain configuration |
+| `supported-tokens` | Token configuration |
+| `geocheck` | Geographic checks |
+| `streams` | Stream data |
+| `swap` | Swap routing |
+| `users` | User data |
+
+## Shared Schemas
+
+Import shared types from `schemas/shared.ts`:
+
+```typescript
+import {
+  chainSchema,
+  tokenSchema,
+  opportunitySchema,
+  type Chain,
+  type Token,
+  type Opportunity
+} from '@turtle-club/hooks';
 ```
 
-## Available Hooks
+Available shared schemas:
+- `chainSchema` / `Chain`
+- `tokenSchema` / `Token`
+- `organizationSchema` / `Organization`
+- `productSchema` / `Product`
+- `vaultConfigSchema` / `VaultConfig`
+- `lendingConfigSchema` / `LendingConfig`
+- `incentiveSchema` / `Incentive`
+- `opportunitySchema` / `Opportunity`
+- `paginationMetadataSchema` / `PaginationMetadata`
+
+## Query Defaults
+
+All queries use consistent defaults from `lib/query-config.ts`:
 
-### Endpoints
-- `useOrganizations()` - Get organization data
-- `useOrganizationDeals()` - Get organization deals
-- `useOrganizationsDeals()` - Get all organizations deals
-- `useProjectTvl()` - Get project TVL data
-- `useExists()` - Check if user exists
-- `usePrepareSignup()` - Prepare signup process
-- `useSignup()` - Complete signup
+```typescript
+export const queryDefaults = {
+  staleTime: 5 * 60 * 1000,      // 5 minutes
+  gcTime: 10 * 60 * 1000,        // 10 minutes
+  retry: 1,
+  refetchOnWindowFocus: false,
+};
+```
 
-### Configuration
-- `useConfig()` - Get current API configuration
+## Adding a New Endpoint
 
+1. Create a new folder in `src/v2/` with the endpoint name
+2. Create the 5 standard files: `schema.ts`, `api.ts`, `queries.ts`, `hooks.ts`, `index.ts`
+3. Add the queries import and merge in `src/v2/index.ts`
+4. Add the export in `src/v2/index.ts`