@zenland/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,382 @@
+/**
+ * Generated types from the Zenland indexer GraphQL schema.
+ * These types are bundled with the SDK for convenience.
+ */
+type Maybe<T> = T | null;
+type InputMaybe<T> = T | null | undefined;
+/** 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 GqlAgentFilter {
+    id?: InputMaybe<string>;
+    id_in?: InputMaybe<string[]>;
+    isActive?: InputMaybe<boolean>;
+    isAvailable?: InputMaybe<boolean>;
+    AND?: InputMaybe<GqlAgentFilter[]>;
+    OR?: InputMaybe<GqlAgentFilter[]>;
+}
+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 GqlEscrowFilter {
+    id?: InputMaybe<string>;
+    id_in?: InputMaybe<string[]>;
+    buyer?: InputMaybe<string>;
+    seller?: InputMaybe<string>;
+    agent?: InputMaybe<string>;
+    state?: InputMaybe<string>;
+    state_in?: InputMaybe<string[]>;
+    token?: InputMaybe<string>;
+    AND?: InputMaybe<GqlEscrowFilter[]>;
+    OR?: InputMaybe<GqlEscrowFilter[]>;
+}
+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;
+}
+interface GqlTransactionLogPage {
+    items: GqlTransactionLog[];
+    totalCount: number;
+    pageInfo: GqlPageInfo;
+}
+interface GqlTransactionLogFilter {
+    escrowAddress?: InputMaybe<string>;
+    agentAddress?: InputMaybe<string>;
+    userAddress?: InputMaybe<string>;
+    eventName?: InputMaybe<string>;
+    AND?: InputMaybe<GqlTransactionLogFilter[]>;
+    OR?: InputMaybe<GqlTransactionLogFilter[]>;
+}
+
+/**
+ * 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;
+/**
+ * Default client instance using production API.
+ * Use this for quick access without creating a new client.
+ *
+ * @example
+ * ```typescript
+ * import { zenland } from '@zenland/sdk';
+ *
+ * const escrows = await zenland.escrows.list();
+ * ```
+ */
+declare const zenland: ZenlandClient;
+
+/**
+ * Agent eligibility utilities.
+ *
+ * This is protocol/business logic (React-agnostic) and is safe to consume
+ * from any app (interface, backend, bots, etc.).
+ */
+/**
+ * Minimal view of an Agent returned by the indexer.
+ */
+type IndexerAgent = {
+    id: string;
+    isActive: boolean;
+    isAvailable: boolean;
+    stablecoinStake: bigint;
+    stablecoinDecimals: number;
+    registrationTime: bigint;
+    activeCases: number;
+    totalResolved: number;
+};
+type AgentEligibilityFailureReason = "NOT_REGISTERED" | "NOT_ACTIVE" | "NOT_AVAILABLE" | "INSUFFICIENT_MAV";
+type AgentEligibilityResult = {
+    ok: true;
+    agentMavUsd: bigint;
+    requiredUsd: bigint;
+} | {
+    ok: false;
+    reason: AgentEligibilityFailureReason;
+    agentMavUsd?: bigint;
+    requiredUsd: bigint;
+};
+/**
+ * Compute agent MAV from its stablecoin stake.
+ *
+ * Bigint-safe:
+ * - stablecoinStake is in smallest units (stablecoinDecimals)
+ * - return MAV in the same smallest units (stablecoinDecimals)
+ */
+declare function computeAgentMavUsd(agent: Pick<IndexerAgent, "stablecoinStake" | "stablecoinDecimals">): bigint;
+/**
+ * Evaluate whether an agent is eligible for a given escrow amount.
+ *
+ * NOTE: escrowAmount must be the escrow principal ONLY (fees excluded).
+ */
+declare function isAgentEligibleForEscrow(args: {
+    agent: IndexerAgent | null | undefined;
+    escrowAmount: bigint;
+}): AgentEligibilityResult;
+
+/**
+ * GraphQL request utilities for the Zenland SDK
+ */
+type GraphQLErrorLike = {
+    message?: string;
+    [key: string]: unknown;
+};
+/**
+ * Error thrown when the indexer returns GraphQL errors
+ */
+declare class ZenlandGraphQLError extends Error {
+    readonly errors: GraphQLErrorLike[];
+    constructor(message: string, errors: GraphQLErrorLike[]);
+}
+/**
+ * Error thrown when the indexer request fails at the network/HTTP level
+ */
+declare class ZenlandRequestError extends Error {
+    readonly status: number;
+    readonly statusText: string;
+    constructor(message: string, status: number, statusText: string);
+}
+
+export { type AgentEligibilityFailureReason, type AgentEligibilityResult, type AgentsDomain, type BigIntScalar, type EscrowsDomain, type GqlAgent, type GqlAgentCase, type GqlAgentCasePage, type GqlAgentFilter, type GqlAgentPage, type GqlEscrow, type GqlEscrowFilter, type GqlEscrowPage, type GqlPageInfo, type GqlProtocolStats, type GqlTransactionLog, type GqlTransactionLogFilter, type GqlTransactionLogPage, type IndexerAgent, type InputMaybe, type ListAgentsArgs, type ListEscrowsArgs, type ListTransactionLogsArgs, type Maybe, type ProtocolStats, type ProtocolStatsDomain, STATE_GROUPS, type StateGroup, type TransactionLogsDomain, type ZenlandClient, type ZenlandClientConfig, ZenlandGraphQLError, ZenlandRequestError, computeAgentMavUsd, createAgentsDomain, createEscrowsDomain, createProtocolStatsDomain, createTransactionLogsDomain, createZenlandClient, isAgentEligibleForEscrow, zenland };