@use-stellar/vue 0.0.0-stage → 0.2.3

package/dist/index.d.mts

@@ -0,0 +1,212 @@
+export { A as Asset, B as Balance, N as NETWORK_CONFIGS, a as NetworkConfig, S as STELLAR_RUNTIME_KEY, b as StellarNetwork, c as StellarPluginOptions, d as StellarRuntime, e as createStellarPlugin, f as createStellarRuntime, u as useStellarRuntime } from './plugin-bXIRDH8_.mjs';
+import { MaybeRefOrGetter, ComputedRef, ShallowRef, Ref } from 'vue';
+export { MaybeRefOrGetter } from 'vue';
+import { Asset, Balance, StellarError, ContractSpecLike, ContractEvent, SendPaymentOptions, SendPaymentResult, AddTrustlineOptions, TransactionResult, PathPaymentOptions, ClaimableBalance, NormalizedPayment } from 'use-stellar/core';
+export { ANONYMOUS_SIMULATION_SOURCE, AddTrustlineOptions, PathPaymentOptions, SendPaymentOptions, SendPaymentResult, accountKey, claimableBalanceKey, paymentsKey } from 'use-stellar/core';
+
+interface UseBalanceOptions {
+    address: MaybeRefOrGetter<string | null | undefined>;
+    asset?: Asset;
+    staleTime?: MaybeRefOrGetter<number | undefined>;
+    /**
+     * Retries after a rate limit (429), honouring `Retry-After`. Defaults to 3,
+     * as in the React hook; 0 disables retrying.
+     */
+    maxRetries?: MaybeRefOrGetter<number | undefined>;
+}
+interface UseBalanceReturn {
+    balance: ComputedRef<string | null>;
+    balances: ComputedRef<Balance[]>;
+    loading: ComputedRef<boolean>;
+    error: ComputedRef<StellarError | null>;
+    refetch: () => Promise<void>;
+}
+declare function useBalance(options: UseBalanceOptions): UseBalanceReturn;
+
+interface UseSorobanContractOptions {
+    contractId: MaybeRefOrGetter<string | null | undefined>;
+    method: MaybeRefOrGetter<string | null | undefined>;
+    args?: MaybeRefOrGetter<readonly unknown[] | null | undefined>;
+    spec?: MaybeRefOrGetter<ContractSpecLike | null | undefined>;
+    sourceAccount?: MaybeRefOrGetter<string | null | undefined>;
+    staleTime?: number;
+}
+interface UseSorobanContractReturn<T = unknown> {
+    data: ComputedRef<T | null>;
+    loading: ComputedRef<boolean>;
+    error: ComputedRef<StellarError | null>;
+    refetch: () => void;
+}
+/**
+ * Simulates a read-only Soroban contract call through the shared core query.
+ * Every input may be static or reactive; cache identity follows the canonical
+ * serialized arguments rather than Vue proxy identity.
+ */
+declare function useSorobanContract<T = unknown>(options: UseSorobanContractOptions): UseSorobanContractReturn<T>;
+
+interface UseContractEventsOptions {
+    contractIds: MaybeRefOrGetter<readonly string[]>;
+    topics?: MaybeRefOrGetter<readonly (readonly string[])[] | undefined>;
+    startLedger?: MaybeRefOrGetter<number | undefined>;
+    interval?: MaybeRefOrGetter<number | undefined>;
+    bufferSize?: MaybeRefOrGetter<number | undefined>;
+    enabled?: MaybeRefOrGetter<boolean | undefined>;
+}
+interface UseContractEventsReturn {
+    events: ShallowRef<ContractEvent[]>;
+    latestLedger: ComputedRef<number | null>;
+    loading: ComputedRef<boolean>;
+    error: ComputedRef<StellarError | null>;
+    clear: () => void;
+}
+/**
+ * Polls Soroban contract events through the framework-neutral core poller and
+ * binds its lifetime to the current Vue effect scope.
+ */
+declare function useContractEvents(options: UseContractEventsOptions): UseContractEventsReturn;
+
+interface UseSendPaymentReturn {
+    send: (options: SendPaymentOptions) => Promise<SendPaymentResult & {
+        error?: string;
+    }>;
+    loading: Ref<boolean>;
+    error: ShallowRef<StellarError | null>;
+    result: ShallowRef<SendPaymentResult | null>;
+    reset: () => void;
+}
+/**
+ * Sends a Stellar payment through the framework-neutral core action while
+ * keeping Vue state scoped to the calling component.
+ */
+declare function useSendPayment(): UseSendPaymentReturn;
+
+interface UseAddTrustlineReturn {
+    addTrustline: (options: AddTrustlineOptions) => Promise<TransactionResult>;
+    loading: Ref<boolean>;
+    error: ShallowRef<StellarError | null>;
+    result: ShallowRef<TransactionResult | null>;
+    reset: () => void;
+}
+/** Adds an issued-asset trustline through the shared core transaction action. */
+declare function useAddTrustline(): UseAddTrustlineReturn;
+
+interface UsePathPaymentReturn {
+    pathPayment: (options: PathPaymentOptions) => Promise<TransactionResult>;
+    loading: Ref<boolean>;
+    error: ShallowRef<StellarError | null>;
+    result: ShallowRef<TransactionResult | null>;
+    reset: () => void;
+}
+/** Submits a slippage-bounded path payment through the shared core action. */
+declare function usePathPayment(): UsePathPaymentReturn;
+
+interface UseClaimableBalanceOptions {
+    address?: MaybeRefOrGetter<string | null | undefined>;
+    staleTime?: MaybeRefOrGetter<number | undefined>;
+}
+interface UseClaimableBalanceReturn {
+    balances: ComputedRef<ClaimableBalance[]>;
+    loading: ComputedRef<boolean>;
+    error: ComputedRef<StellarError | null>;
+    refetch: () => Promise<void>;
+}
+declare function useClaimableBalance(options?: UseClaimableBalanceOptions): UseClaimableBalanceReturn;
+
+interface UsePaymentsOptions {
+    address?: MaybeRefOrGetter<string | null | undefined>;
+    limit?: MaybeRefOrGetter<number | undefined>;
+    order?: MaybeRefOrGetter<"asc" | "desc" | undefined>;
+    cursor?: MaybeRefOrGetter<string | undefined>;
+    maxRetries?: MaybeRefOrGetter<number | undefined>;
+}
+interface UsePaymentsReturn {
+    payments: ComputedRef<NormalizedPayment[]>;
+    loading: ComputedRef<boolean>;
+    error: ComputedRef<StellarError | null>;
+    isStale: ComputedRef<boolean>;
+    refetch: () => Promise<void>;
+    fetchNext: () => Promise<void>;
+    fetchPrev: () => Promise<void>;
+    hasNext: ComputedRef<boolean>;
+    hasPrev: ComputedRef<boolean>;
+}
+declare function usePayments(options?: UsePaymentsOptions): UsePaymentsReturn;
+
+interface UsePaymentHistoryOptions extends UsePaymentsOptions {
+    direction?: MaybeRefOrGetter<"incoming" | "outgoing" | "all" | undefined>;
+    asset?: MaybeRefOrGetter<Asset | "all" | undefined>;
+}
+interface UsePaymentHistoryReturn {
+    payments: ComputedRef<NormalizedPayment[]>;
+    loading: ComputedRef<boolean>;
+    error: ComputedRef<StellarError | null>;
+    isStale: ComputedRef<boolean>;
+    refetch: () => Promise<void>;
+    fetchNext: () => Promise<void>;
+    fetchPrev: () => Promise<void>;
+    hasNext: ComputedRef<boolean>;
+    hasPrev: ComputedRef<boolean>;
+}
+/**
+ * Filters the current `usePayments` page without issuing another request.
+ * Filtering is intentionally page-local; pagination continues to follow the
+ * unfiltered Horizon result set.
+ */
+declare function usePaymentHistory(options?: UsePaymentHistoryOptions): UsePaymentHistoryReturn;
+
+interface QueryStoreConfig {
+    /** How long (ms) data is considered fresh. Defaults to 30 000 (30s). */
+    staleTime?: number;
+    /** How long (ms) an entry is kept after its last subscriber leaves. Defaults to 300 000 (5min). */
+    gcTime?: number;
+}
+/** The reactive shape a composable reads. Mutating it directly is not supported — go through the store. */
+interface QueryEntry<T = unknown> {
+    data: T | null;
+    updatedAt: number | null;
+    loading: boolean;
+    error: unknown;
+}
+interface RunOptions {
+    /** Overrides the store's default staleTime for this call. */
+    staleTime?: number;
+    /** Bypasses both the in-flight dedup check and the staleTime check. */
+    force?: boolean;
+}
+declare class VueQueryStore {
+    private entries;
+    private staleTime;
+    private gcTime;
+    constructor(config?: QueryStoreConfig);
+    private ensure;
+    /**
+     * The live, reactive entry for a key. Read its fields inside a `computed`
+     * or `watchEffect` — Vue tracks the read and re-runs when the store writes
+     * to it.
+     */
+    getEntry<T>(key: string): QueryEntry<T>;
+    /**
+     * Registers a subscriber for `key` and cancels any pending GC eviction.
+     * Returns the unsubscribe function — call it from `onCleanup` /
+     * `onScopeDispose` so an idle entry is eventually evicted.
+     */
+    subscribe(key: string): () => void;
+    /** Number of active subscribers for a key. Exposed for tests. */
+    subscriberCount(key: string): number;
+    private scheduleGc;
+    isFresh(key: string, staleTime?: number): boolean;
+    /**
+     * Runs `queryFn` for `key`, deduplicated: a call made while a fetch for the
+     * same key is already in flight awaits that same promise instead of
+     * issuing a second request — this is what lets two Vue scopes reading the
+     * same query share one network call. Skipped entirely when cached data is
+     * still within `staleTime`, unless `force` is set.
+     */
+    run<T>(key: string, queryFn: () => Promise<T>, opts?: RunOptions): Promise<T>;
+    /** Marks a cached query stale so its next read fetches fresh data. */
+    invalidate(key: string | readonly unknown[]): void;
+    /** Empties the store. Useful in tests; not meant for app code. */
+    clear(): void;
+}
+
+export { type QueryEntry, type QueryStoreConfig, type RunOptions, type UseAddTrustlineReturn, type UseBalanceOptions, type UseBalanceReturn, type UseClaimableBalanceOptions, type UseClaimableBalanceReturn, type UseContractEventsOptions, type UseContractEventsReturn, type UsePathPaymentReturn, type UsePaymentHistoryOptions, type UsePaymentHistoryReturn, type UsePaymentsOptions, type UsePaymentsReturn, type UseSendPaymentReturn, type UseSorobanContractOptions, type UseSorobanContractReturn, VueQueryStore, useAddTrustline, useBalance, useClaimableBalance, useContractEvents, usePathPayment, usePaymentHistory, usePayments, useSendPayment, useSorobanContract };

package/dist/index.d.ts

@@ -0,0 +1,212 @@
+export { A as Asset, B as Balance, N as NETWORK_CONFIGS, a as NetworkConfig, S as STELLAR_RUNTIME_KEY, b as StellarNetwork, c as StellarPluginOptions, d as StellarRuntime, e as createStellarPlugin, f as createStellarRuntime, u as useStellarRuntime } from './plugin-bXIRDH8_.js';
+import { MaybeRefOrGetter, ComputedRef, ShallowRef, Ref } from 'vue';
+export { MaybeRefOrGetter } from 'vue';
+import { Asset, Balance, StellarError, ContractSpecLike, ContractEvent, SendPaymentOptions, SendPaymentResult, AddTrustlineOptions, TransactionResult, PathPaymentOptions, ClaimableBalance, NormalizedPayment } from 'use-stellar/core';
+export { ANONYMOUS_SIMULATION_SOURCE, AddTrustlineOptions, PathPaymentOptions, SendPaymentOptions, SendPaymentResult, accountKey, claimableBalanceKey, paymentsKey } from 'use-stellar/core';
+
+interface UseBalanceOptions {
+    address: MaybeRefOrGetter<string | null | undefined>;
+    asset?: Asset;
+    staleTime?: MaybeRefOrGetter<number | undefined>;
+    /**
+     * Retries after a rate limit (429), honouring `Retry-After`. Defaults to 3,
+     * as in the React hook; 0 disables retrying.
+     */
+    maxRetries?: MaybeRefOrGetter<number | undefined>;
+}
+interface UseBalanceReturn {
+    balance: ComputedRef<string | null>;
+    balances: ComputedRef<Balance[]>;
+    loading: ComputedRef<boolean>;
+    error: ComputedRef<StellarError | null>;
+    refetch: () => Promise<void>;
+}
+declare function useBalance(options: UseBalanceOptions): UseBalanceReturn;
+
+interface UseSorobanContractOptions {
+    contractId: MaybeRefOrGetter<string | null | undefined>;
+    method: MaybeRefOrGetter<string | null | undefined>;
+    args?: MaybeRefOrGetter<readonly unknown[] | null | undefined>;
+    spec?: MaybeRefOrGetter<ContractSpecLike | null | undefined>;
+    sourceAccount?: MaybeRefOrGetter<string | null | undefined>;
+    staleTime?: number;
+}
+interface UseSorobanContractReturn<T = unknown> {
+    data: ComputedRef<T | null>;
+    loading: ComputedRef<boolean>;
+    error: ComputedRef<StellarError | null>;
+    refetch: () => void;
+}
+/**
+ * Simulates a read-only Soroban contract call through the shared core query.
+ * Every input may be static or reactive; cache identity follows the canonical
+ * serialized arguments rather than Vue proxy identity.
+ */
+declare function useSorobanContract<T = unknown>(options: UseSorobanContractOptions): UseSorobanContractReturn<T>;
+
+interface UseContractEventsOptions {
+    contractIds: MaybeRefOrGetter<readonly string[]>;
+    topics?: MaybeRefOrGetter<readonly (readonly string[])[] | undefined>;
+    startLedger?: MaybeRefOrGetter<number | undefined>;
+    interval?: MaybeRefOrGetter<number | undefined>;
+    bufferSize?: MaybeRefOrGetter<number | undefined>;
+    enabled?: MaybeRefOrGetter<boolean | undefined>;
+}
+interface UseContractEventsReturn {
+    events: ShallowRef<ContractEvent[]>;
+    latestLedger: ComputedRef<number | null>;
+    loading: ComputedRef<boolean>;
+    error: ComputedRef<StellarError | null>;
+    clear: () => void;
+}
+/**
+ * Polls Soroban contract events through the framework-neutral core poller and
+ * binds its lifetime to the current Vue effect scope.
+ */
+declare function useContractEvents(options: UseContractEventsOptions): UseContractEventsReturn;
+
+interface UseSendPaymentReturn {
+    send: (options: SendPaymentOptions) => Promise<SendPaymentResult & {
+        error?: string;
+    }>;
+    loading: Ref<boolean>;
+    error: ShallowRef<StellarError | null>;
+    result: ShallowRef<SendPaymentResult | null>;
+    reset: () => void;
+}
+/**
+ * Sends a Stellar payment through the framework-neutral core action while
+ * keeping Vue state scoped to the calling component.
+ */
+declare function useSendPayment(): UseSendPaymentReturn;
+
+interface UseAddTrustlineReturn {
+    addTrustline: (options: AddTrustlineOptions) => Promise<TransactionResult>;
+    loading: Ref<boolean>;
+    error: ShallowRef<StellarError | null>;
+    result: ShallowRef<TransactionResult | null>;
+    reset: () => void;
+}
+/** Adds an issued-asset trustline through the shared core transaction action. */
+declare function useAddTrustline(): UseAddTrustlineReturn;
+
+interface UsePathPaymentReturn {
+    pathPayment: (options: PathPaymentOptions) => Promise<TransactionResult>;
+    loading: Ref<boolean>;
+    error: ShallowRef<StellarError | null>;
+    result: ShallowRef<TransactionResult | null>;
+    reset: () => void;
+}
+/** Submits a slippage-bounded path payment through the shared core action. */
+declare function usePathPayment(): UsePathPaymentReturn;
+
+interface UseClaimableBalanceOptions {
+    address?: MaybeRefOrGetter<string | null | undefined>;
+    staleTime?: MaybeRefOrGetter<number | undefined>;
+}
+interface UseClaimableBalanceReturn {
+    balances: ComputedRef<ClaimableBalance[]>;
+    loading: ComputedRef<boolean>;
+    error: ComputedRef<StellarError | null>;
+    refetch: () => Promise<void>;
+}
+declare function useClaimableBalance(options?: UseClaimableBalanceOptions): UseClaimableBalanceReturn;
+
+interface UsePaymentsOptions {
+    address?: MaybeRefOrGetter<string | null | undefined>;
+    limit?: MaybeRefOrGetter<number | undefined>;
+    order?: MaybeRefOrGetter<"asc" | "desc" | undefined>;
+    cursor?: MaybeRefOrGetter<string | undefined>;
+    maxRetries?: MaybeRefOrGetter<number | undefined>;
+}
+interface UsePaymentsReturn {
+    payments: ComputedRef<NormalizedPayment[]>;
+    loading: ComputedRef<boolean>;
+    error: ComputedRef<StellarError | null>;
+    isStale: ComputedRef<boolean>;
+    refetch: () => Promise<void>;
+    fetchNext: () => Promise<void>;
+    fetchPrev: () => Promise<void>;
+    hasNext: ComputedRef<boolean>;
+    hasPrev: ComputedRef<boolean>;
+}
+declare function usePayments(options?: UsePaymentsOptions): UsePaymentsReturn;
+
+interface UsePaymentHistoryOptions extends UsePaymentsOptions {
+    direction?: MaybeRefOrGetter<"incoming" | "outgoing" | "all" | undefined>;
+    asset?: MaybeRefOrGetter<Asset | "all" | undefined>;
+}
+interface UsePaymentHistoryReturn {
+    payments: ComputedRef<NormalizedPayment[]>;
+    loading: ComputedRef<boolean>;
+    error: ComputedRef<StellarError | null>;
+    isStale: ComputedRef<boolean>;
+    refetch: () => Promise<void>;
+    fetchNext: () => Promise<void>;
+    fetchPrev: () => Promise<void>;
+    hasNext: ComputedRef<boolean>;
+    hasPrev: ComputedRef<boolean>;
+}
+/**
+ * Filters the current `usePayments` page without issuing another request.
+ * Filtering is intentionally page-local; pagination continues to follow the
+ * unfiltered Horizon result set.
+ */
+declare function usePaymentHistory(options?: UsePaymentHistoryOptions): UsePaymentHistoryReturn;
+
+interface QueryStoreConfig {
+    /** How long (ms) data is considered fresh. Defaults to 30 000 (30s). */
+    staleTime?: number;
+    /** How long (ms) an entry is kept after its last subscriber leaves. Defaults to 300 000 (5min). */
+    gcTime?: number;
+}
+/** The reactive shape a composable reads. Mutating it directly is not supported — go through the store. */
+interface QueryEntry<T = unknown> {
+    data: T | null;
+    updatedAt: number | null;
+    loading: boolean;
+    error: unknown;
+}
+interface RunOptions {
+    /** Overrides the store's default staleTime for this call. */
+    staleTime?: number;
+    /** Bypasses both the in-flight dedup check and the staleTime check. */
+    force?: boolean;
+}
+declare class VueQueryStore {
+    private entries;
+    private staleTime;
+    private gcTime;
+    constructor(config?: QueryStoreConfig);
+    private ensure;
+    /**
+     * The live, reactive entry for a key. Read its fields inside a `computed`
+     * or `watchEffect` — Vue tracks the read and re-runs when the store writes
+     * to it.
+     */
+    getEntry<T>(key: string): QueryEntry<T>;
+    /**
+     * Registers a subscriber for `key` and cancels any pending GC eviction.
+     * Returns the unsubscribe function — call it from `onCleanup` /
+     * `onScopeDispose` so an idle entry is eventually evicted.
+     */
+    subscribe(key: string): () => void;
+    /** Number of active subscribers for a key. Exposed for tests. */
+    subscriberCount(key: string): number;
+    private scheduleGc;
+    isFresh(key: string, staleTime?: number): boolean;
+    /**
+     * Runs `queryFn` for `key`, deduplicated: a call made while a fetch for the
+     * same key is already in flight awaits that same promise instead of
+     * issuing a second request — this is what lets two Vue scopes reading the
+     * same query share one network call. Skipped entirely when cached data is
+     * still within `staleTime`, unless `force` is set.
+     */
+    run<T>(key: string, queryFn: () => Promise<T>, opts?: RunOptions): Promise<T>;
+    /** Marks a cached query stale so its next read fetches fresh data. */
+    invalidate(key: string | readonly unknown[]): void;
+    /** Empties the store. Useful in tests; not meant for app code. */
+    clear(): void;
+}
+
+export { type QueryEntry, type QueryStoreConfig, type RunOptions, type UseAddTrustlineReturn, type UseBalanceOptions, type UseBalanceReturn, type UseClaimableBalanceOptions, type UseClaimableBalanceReturn, type UseContractEventsOptions, type UseContractEventsReturn, type UsePathPaymentReturn, type UsePaymentHistoryOptions, type UsePaymentHistoryReturn, type UsePaymentsOptions, type UsePaymentsReturn, type UseSendPaymentReturn, type UseSorobanContractOptions, type UseSorobanContractReturn, VueQueryStore, useAddTrustline, useBalance, useClaimableBalance, useContractEvents, usePathPayment, usePaymentHistory, usePayments, useSendPayment, useSorobanContract };