@zenland/sdk 0.1.0

package/dist/react.d.ts

@@ -0,0 +1,554 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import * as _tanstack_react_query from '@tanstack/react-query';
+
+/**
+ * Generated types from the Zenland indexer GraphQL schema.
+ * These types are bundled with the SDK for convenience.
+ */
+type Maybe<T> = T | null;
+/** GraphQL BigInt scalar - can be string or number from the API */
+type BigIntScalar = string | number | bigint;
+/** Page info for paginated queries */
+interface GqlPageInfo {
+    hasNextPage: boolean;
+    hasPreviousPage: boolean;
+    startCursor?: Maybe<string>;
+    endCursor?: Maybe<string>;
+}
+interface GqlAgent {
+    id: string;
+    isActive: boolean;
+    isAvailable: boolean;
+    stablecoinDecimals: number;
+    stablecoinToken: string;
+    stablecoinStake: BigIntScalar;
+    daoTokenStake: BigIntScalar;
+    disputeFeeBps: number;
+    assignmentFeeBps: number;
+    description: string;
+    contact: string;
+    totalResolved: number;
+    activeCases: number;
+    registrationTime: BigIntScalar;
+    lastEngagementTimestamp: BigIntScalar;
+    totalEarnings: BigIntScalar;
+    totalSlashed: BigIntScalar;
+    cases?: Maybe<GqlAgentCasePage>;
+}
+interface GqlAgentCase {
+    id: string;
+    escrow: string;
+    agent: string;
+    invitedAt: BigIntScalar;
+    resolvedAt?: Maybe<BigIntScalar>;
+    timedOut: boolean;
+    feeEarned?: Maybe<BigIntScalar>;
+    escrowRef?: Maybe<GqlEscrow>;
+}
+interface GqlAgentCasePage {
+    items: GqlAgentCase[];
+    totalCount: number;
+    pageInfo: GqlPageInfo;
+}
+interface GqlAgentPage {
+    items: GqlAgent[];
+    totalCount: number;
+    pageInfo: GqlPageInfo;
+}
+interface GqlEscrow {
+    id: string;
+    buyer: string;
+    seller: string;
+    agent?: Maybe<string>;
+    amount: BigIntScalar;
+    token: string;
+    state: string;
+    createdAt: BigIntScalar;
+    sellerAcceptDeadline: BigIntScalar;
+    buyerProtectionTime: BigIntScalar;
+    termsHash: string;
+    version: number;
+    fundedAt: BigIntScalar;
+    fulfilledAt?: Maybe<BigIntScalar>;
+    resolvedAt?: Maybe<BigIntScalar>;
+    agentInvitedAt?: Maybe<BigIntScalar>;
+    splitProposer?: Maybe<string>;
+    proposedBuyerBps?: Maybe<number>;
+    proposedSellerBps?: Maybe<number>;
+    buyerApprovedSplit?: Maybe<boolean>;
+    sellerApprovedSplit?: Maybe<boolean>;
+    agentFeeReceived?: Maybe<BigIntScalar>;
+    buyerReceived?: Maybe<BigIntScalar>;
+    sellerReceived?: Maybe<BigIntScalar>;
+    creationFee: BigIntScalar;
+    sellerAcceptedAt?: Maybe<BigIntScalar>;
+    sellerDeclinedAt?: Maybe<BigIntScalar>;
+    cancelledExpiredAt?: Maybe<BigIntScalar>;
+}
+interface GqlEscrowPage {
+    items: GqlEscrow[];
+    totalCount: number;
+    pageInfo: GqlPageInfo;
+}
+interface GqlProtocolStats {
+    id: string;
+    totalEscrowsCreated: number;
+    totalVolumeEscrowed: BigIntScalar;
+    totalFeesCollected: BigIntScalar;
+    currentTVL: BigIntScalar;
+    activeEscrowCount: number;
+    totalAgentsRegistered: number;
+    activeAgentsCount: number;
+}
+interface GqlTransactionLog {
+    id: string;
+    txHash: string;
+    blockNumber: BigIntScalar;
+    timestamp: BigIntScalar;
+    eventName: string;
+    contractAddress: string;
+    contractType: string;
+    escrowAddress?: Maybe<string>;
+    agentAddress?: Maybe<string>;
+    userAddress?: Maybe<string>;
+    eventData: string;
+}
+
+/**
+ * Escrow domain module for the Zenland SDK
+ */
+
+/** State groups for filtering escrows */
+declare const STATE_GROUPS: {
+    readonly ACTIVE: readonly ["PENDING", "ACTIVE", "FULFILLED"];
+    readonly IN_DISPUTE: readonly ["DISPUTED", "AGENT_INVITED"];
+    readonly COMPLETED: readonly ["RELEASED", "AGENT_RESOLVED", "REFUNDED", "SPLIT"];
+};
+type StateGroup = keyof typeof STATE_GROUPS;
+interface ListEscrowsArgs {
+    limit?: number;
+    offset?: number;
+    buyer?: string;
+    seller?: string;
+    agent?: string;
+    /** Search across buyer, seller, or agent roles */
+    user?: string;
+    state?: string;
+    /** Multiple states for group filtering */
+    states?: string[];
+    orderBy?: string;
+    orderDirection?: "asc" | "desc";
+}
+/**
+ * Creates escrow domain functions bound to a base URL
+ */
+declare function createEscrowsDomain(baseUrl: string): {
+    list: (args?: ListEscrowsArgs) => Promise<GqlEscrowPage>;
+    getById: (id: string) => Promise<GqlEscrow | null>;
+    getByUser: (userAddress: string, args?: Omit<ListEscrowsArgs, "user" | "buyer" | "seller" | "agent">) => Promise<GqlEscrowPage>;
+    getByStateGroup: (stateGroup: StateGroup, args?: Omit<ListEscrowsArgs, "state" | "states">) => Promise<GqlEscrowPage>;
+};
+type EscrowsDomain = ReturnType<typeof createEscrowsDomain>;
+
+/**
+ * Agent domain module for the Zenland SDK
+ */
+
+interface ListAgentsArgs {
+    limit?: number;
+    offset?: number;
+    onlyActive?: boolean;
+    onlyAvailable?: boolean;
+    orderBy?: string;
+    orderDirection?: "asc" | "desc";
+}
+/**
+ * Creates agent domain functions bound to a base URL
+ */
+declare function createAgentsDomain(baseUrl: string): {
+    list: (args?: ListAgentsArgs) => Promise<GqlAgentPage>;
+    getById: (id: string) => Promise<GqlAgent | null>;
+    getAvailable: (args?: Omit<ListAgentsArgs, "onlyActive" | "onlyAvailable">) => Promise<GqlAgentPage>;
+};
+type AgentsDomain = ReturnType<typeof createAgentsDomain>;
+
+/**
+ * Protocol Stats domain module for the Zenland SDK
+ */
+
+/** Normalized protocol stats with BigInt values */
+interface ProtocolStats {
+    id: string;
+    totalEscrowsCreated: number;
+    totalVolumeEscrowed: bigint;
+    totalFeesCollected: bigint;
+    currentTVL: bigint;
+    activeEscrowCount: number;
+    totalAgentsRegistered: number;
+    activeAgentsCount: number;
+}
+/**
+ * Creates protocol stats domain functions bound to a base URL
+ */
+declare function createProtocolStatsDomain(baseUrl: string): {
+    get: () => Promise<ProtocolStats | null>;
+    getRaw: () => Promise<GqlProtocolStats | null>;
+};
+type ProtocolStatsDomain = ReturnType<typeof createProtocolStatsDomain>;
+
+/**
+ * Transaction Logs domain module for the Zenland SDK
+ */
+
+interface ListTransactionLogsArgs {
+    escrowAddress?: string;
+    limit?: number;
+    offset?: number;
+    orderBy?: string;
+    orderDirection?: "asc" | "desc";
+}
+/**
+ * Creates transaction logs domain functions bound to a base URL
+ */
+declare function createTransactionLogsDomain(baseUrl: string): {
+    list: (args?: ListTransactionLogsArgs) => Promise<GqlTransactionLog[]>;
+    getByEscrow: (escrowAddress: string, args?: Omit<ListTransactionLogsArgs, "escrowAddress">) => Promise<GqlTransactionLog[]>;
+    parseEventData: (eventData: string) => Record<string, unknown>;
+};
+type TransactionLogsDomain = ReturnType<typeof createTransactionLogsDomain>;
+
+/**
+ * Zenland SDK Client
+ *
+ * The main entry point for interacting with the Zenland indexer.
+ */
+
+interface ZenlandClientConfig {
+    /** Base URL for the indexer API. Defaults to https://api.zen.land */
+    baseUrl?: string;
+}
+interface ZenlandClient {
+    /** The base URL being used by this client */
+    readonly baseUrl: string;
+    /** Escrow-related operations */
+    readonly escrows: EscrowsDomain;
+    /** Agent-related operations */
+    readonly agents: AgentsDomain;
+    /** Protocol statistics */
+    readonly protocolStats: ProtocolStatsDomain;
+    /** Transaction logs */
+    readonly transactionLogs: TransactionLogsDomain;
+}
+/**
+ * Create a new Zenland SDK client.
+ *
+ * @example
+ * ```typescript
+ * // Use production API (default)
+ * const client = createZenlandClient();
+ *
+ * // Use custom endpoint (e.g., local development)
+ * const client = createZenlandClient({ baseUrl: 'http://localhost:42069' });
+ *
+ * // Fetch escrows
+ * const { items, totalCount } = await client.escrows.list({ limit: 10 });
+ *
+ * // Fetch a specific escrow
+ * const escrow = await client.escrows.getById('0x...');
+ *
+ * // Fetch agents
+ * const agents = await client.agents.list({ onlyActive: true });
+ *
+ * // Fetch protocol stats
+ * const stats = await client.protocolStats.get();
+ * ```
+ */
+declare function createZenlandClient(config?: ZenlandClientConfig): ZenlandClient;
+
+interface ZenlandProviderProps {
+    children: ReactNode;
+    /** Optional configuration for the SDK client */
+    config?: ZenlandClientConfig;
+}
+/**
+ * Provider component for the Zenland SDK.
+ *
+ * Wrap your app with this provider to use the React hooks.
+ *
+ * @example
+ * ```tsx
+ * import { ZenlandProvider } from '@zenland/sdk/react';
+ *
+ * function App() {
+ *   return (
+ *     <ZenlandProvider>
+ *       <YourApp />
+ *     </ZenlandProvider>
+ *   );
+ * }
+ *
+ * // With custom config
+ * <ZenlandProvider config={{ baseUrl: 'http://localhost:42069' }}>
+ *   <YourApp />
+ * </ZenlandProvider>
+ * ```
+ */
+declare function ZenlandProvider({ children, config }: ZenlandProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Hook to access the Zenland SDK client.
+ *
+ * Must be used within a ZenlandProvider.
+ *
+ * @example
+ * ```tsx
+ * import { useZenlandClient } from '@zenland/sdk/react';
+ *
+ * function MyComponent() {
+ *   const client = useZenlandClient();
+ *   // Use client.escrows, client.agents, etc.
+ * }
+ * ```
+ */
+declare function useZenlandClient(): ZenlandClient;
+/**
+ * Hook to access the Zenland SDK client, creating a default one if not in a provider.
+ *
+ * This is useful for components that might be used outside of a ZenlandProvider.
+ */
+declare function useZenlandClientOptional(): ZenlandClient;
+
+interface UseEscrowOptions {
+    /** Whether to enable the query */
+    enabled?: boolean;
+}
+/**
+ * Hook to fetch a single escrow by ID.
+ *
+ * @example
+ * ```tsx
+ * import { useEscrow } from '@zenland/sdk/react';
+ *
+ * function EscrowDetail({ id }: { id: string }) {
+ *   const { data: escrow, isLoading, error } = useEscrow(id);
+ *
+ *   if (isLoading) return <div>Loading...</div>;
+ *   if (error) return <div>Error: {error.message}</div>;
+ *   if (!escrow) return <div>Escrow not found</div>;
+ *
+ *   return <div>{escrow.state}</div>;
+ * }
+ * ```
+ */
+declare function useEscrow(id: string | undefined, options?: UseEscrowOptions): _tanstack_react_query.UseQueryResult<GqlEscrow | null, Error>;
+
+type EscrowRole = "all" | "buyer" | "seller" | "agent";
+type EscrowStateTab = "all" | StateGroup;
+interface UseEscrowsArgs {
+    /** User address to filter by */
+    address?: string;
+    /** Pagination limit */
+    limit?: number;
+    /** Pagination offset */
+    offset?: number;
+    /** Filter by role (requires address) */
+    role?: EscrowRole;
+    /** Filter by state group */
+    stateTab?: EscrowStateTab;
+    /** Filter by specific state */
+    state?: string;
+    /** Filter by multiple states */
+    states?: string[];
+    /** Whether to enable the query */
+    enabled?: boolean;
+}
+/**
+ * Hook to fetch escrows with filtering and pagination.
+ *
+ * @example
+ * ```tsx
+ * import { useEscrows } from '@zenland/sdk/react';
+ *
+ * function MyEscrows({ address }: { address: string }) {
+ *   const { data, isLoading } = useEscrows({
+ *     address,
+ *     role: 'buyer',
+ *     stateTab: 'ACTIVE',
+ *   });
+ *
+ *   if (isLoading) return <div>Loading...</div>;
+ *
+ *   return (
+ *     <ul>
+ *       {data?.items.map(escrow => (
+ *         <li key={escrow.id}>{escrow.state}</li>
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ */
+declare function useEscrows(args?: UseEscrowsArgs): _tanstack_react_query.UseQueryResult<GqlEscrowPage, Error>;
+
+interface UseAgentOptions {
+    /** Whether to enable the query */
+    enabled?: boolean;
+}
+/**
+ * Hook to fetch a single agent by address.
+ *
+ * @example
+ * ```tsx
+ * import { useAgent } from '@zenland/sdk/react';
+ *
+ * function AgentProfile({ address }: { address: string }) {
+ *   const { data: agent, isLoading, error } = useAgent(address);
+ *
+ *   if (isLoading) return <div>Loading...</div>;
+ *   if (error) return <div>Error: {error.message}</div>;
+ *   if (!agent) return <div>Agent not found</div>;
+ *
+ *   return <div>{agent.description}</div>;
+ * }
+ * ```
+ */
+declare function useAgent(address: string | undefined, options?: UseAgentOptions): _tanstack_react_query.UseQueryResult<GqlAgent | null, Error>;
+
+interface UseAgentsArgs {
+    /** Only return active agents */
+    onlyActive?: boolean;
+    /** Only return available agents */
+    onlyAvailable?: boolean;
+    /** Pagination limit */
+    limit?: number;
+    /** Pagination offset */
+    offset?: number;
+    /** Whether to enable the query */
+    enabled?: boolean;
+}
+/**
+ * Hook to fetch agents with filtering and pagination.
+ *
+ * @example
+ * ```tsx
+ * import { useAgents } from '@zenland/sdk/react';
+ *
+ * function AgentList() {
+ *   const { data, isLoading } = useAgents({ onlyActive: true });
+ *
+ *   if (isLoading) return <div>Loading...</div>;
+ *
+ *   return (
+ *     <ul>
+ *       {data?.items.map(agent => (
+ *         <li key={agent.id}>{agent.description}</li>
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ */
+declare function useAgents(args?: UseAgentsArgs): _tanstack_react_query.UseQueryResult<GqlAgentPage, Error>;
+
+interface UseProtocolStatsOptions {
+    /** Whether to enable the query */
+    enabled?: boolean;
+    /** Stale time in milliseconds (default: 30s) */
+    staleTime?: number;
+    /** Refetch interval in milliseconds (default: 60s) */
+    refetchInterval?: number;
+}
+/**
+ * Hook to fetch global protocol statistics.
+ *
+ * @example
+ * ```tsx
+ * import { useProtocolStats } from '@zenland/sdk/react';
+ *
+ * function ProtocolOverview() {
+ *   const { data: stats, isLoading } = useProtocolStats();
+ *
+ *   if (isLoading) return <div>Loading...</div>;
+ *   if (!stats) return <div>Stats not available</div>;
+ *
+ *   return (
+ *     <div>
+ *       <p>Total Escrows: {stats.totalEscrowsCreated}</p>
+ *       <p>TVL: {stats.currentTVL.toString()}</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useProtocolStats(options?: UseProtocolStatsOptions): _tanstack_react_query.UseQueryResult<ProtocolStats | null, Error>;
+
+interface UseRecentEscrowsOptions {
+    /** Number of escrows to fetch (default: 5) */
+    limit?: number;
+    /** Whether to enable the query */
+    enabled?: boolean;
+    /** Stale time in milliseconds (default: 15s) */
+    staleTime?: number;
+    /** Refetch interval in milliseconds (default: 30s) */
+    refetchInterval?: number;
+}
+/**
+ * Hook to fetch recent escrows for activity feeds.
+ *
+ * @example
+ * ```tsx
+ * import { useRecentEscrows } from '@zenland/sdk/react';
+ *
+ * function ActivityFeed() {
+ *   const { data: escrows, isLoading } = useRecentEscrows({ limit: 10 });
+ *
+ *   if (isLoading) return <div>Loading...</div>;
+ *
+ *   return (
+ *     <ul>
+ *       {escrows?.map(escrow => (
+ *         <li key={escrow.id}>
+ *           {escrow.state} - {escrow.amount}
+ *         </li>
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ */
+declare function useRecentEscrows(options?: UseRecentEscrowsOptions): _tanstack_react_query.UseQueryResult<GqlEscrow[], Error>;
+
+interface UserDashboardStats {
+    activeCount: number;
+    disputeCount: number;
+    completedCount: number;
+    tvl: bigint;
+    recentEscrows: GqlEscrow[];
+}
+/**
+ * Hook to fetch user-specific dashboard statistics.
+ */
+declare function useUserStats(userAddress: string | undefined): _tanstack_react_query.UseQueryResult<UserDashboardStats | null, Error>;
+/**
+ * Hook to fetch global dashboard statistics.
+ */
+declare function useGlobalStats(): _tanstack_react_query.UseQueryResult<Omit<UserDashboardStats, "tvl"> & {
+    tvl: null;
+}, Error>;
+
+interface UseTransactionLogsByEscrowOptions {
+    /** Whether to enable the query */
+    enabled?: boolean;
+    /** Stale time in milliseconds (default: 30s) */
+    staleTime?: number;
+    /** Refetch interval in milliseconds */
+    refetchInterval?: number;
+    /** Transaction log list options */
+    list?: Omit<ListTransactionLogsArgs, "escrowAddress">;
+}
+/**
+ * Hook to fetch transaction logs for a specific escrow.
+ */
+declare function useTransactionLogsByEscrow(escrowAddress: string | undefined | null, options?: UseTransactionLogsByEscrowOptions): _tanstack_react_query.UseQueryResult<GqlTransactionLog[], Error>;
+
+export { type EscrowRole, type EscrowStateTab, type GqlAgent, type GqlAgentPage, type GqlEscrow, type GqlEscrowPage, type GqlPageInfo, type GqlProtocolStats, type GqlTransactionLog, type ProtocolStats, STATE_GROUPS, type UseAgentOptions, type UseAgentsArgs, type UseEscrowOptions, type UseEscrowsArgs, type UseProtocolStatsOptions, type UseRecentEscrowsOptions, type UseTransactionLogsByEscrowOptions, type UserDashboardStats, type ZenlandClient, type ZenlandClientConfig, ZenlandProvider, type ZenlandProviderProps, createZenlandClient, useAgent, useAgents, useEscrow, useEscrows, useGlobalStats, useProtocolStats, useRecentEscrows, useTransactionLogsByEscrow, useUserStats, useZenlandClient, useZenlandClientOptional };