@xoxno/sdk-js 1.0.224 → 1.0.226

package/README.md

@@ -8,10 +8,49 @@ npm install @xoxno/sdk-js
 
 ## Basic usage
 
+For render-ready Stellar lending data in browsers or React Native, use the
+read subpath. It has no Stellar, MultiversX or Node runtime imports:
+
+```typescript
+import { createStellarLendingReadClient } from '@xoxno/sdk-js/stellar-lending/read'
+
+const lending = createStellarLendingReadClient({ baseUrl: 'https://api.xoxno.com' })
+const assets = await lending.assets({ usage: 'collateral' })
+const positions = await lending.positions(owner)
+```
+
+`baseUrl` selects the API deployment, which must expose the new
+`/stellar-lending/v1` read routes. Supply `fetch` if the host has no global
+implementation. Both methods accept `signal`; positions follows every `Link`
+page, including empty pages. APYs are fractions, raw amounts are exact integer
+token base-unit strings, and unavailable data stays null. Capacities are indexed
+estimates; prepare/simulate before signing. Public response types and inline
+OpenAPI schemas are exported from the same subpath.
+
+The Stellar peer is optional for REST reads. Install `@stellar/stellar-sdk`
+when using transaction builders, RPC reads or swap decoders.
+
 For Stellar lending, start with the [integration guide](md/stellar-lending.md)
 and [checked example](examples/stellar-lending.ts). They cover typed market
 discovery and unsigned XDR preparation, wallet signing, submission and confirmation.
 Generate focused API documentation with `npm run docs:stellar`.
+Decode direct XOXNO swap history synchronously with
+`decodeStellarSwapEnvelope` from `@xoxno/sdk-js/stellar-swap`:
+
+```typescript
+import { decodeStellarSwapEnvelope } from '@xoxno/sdk-js/stellar-swap'
+
+const swap = decodeStellarSwapEnvelope({
+  envelopeXdr, networkPassphrase, routerAddress, viewer, operationIndex,
+})
+// swap: { tokenIn, tokenOut, amountInAtoms, operationIndex } | null
+```
+
+Pin `routerAddress` for the selected network. Fee bumps use inner operation
+indices; omit the index only when there is one matching swap. The input amount
+is an exact base-unit string. Actual output must come from ledger effects;
+the route minimum is not the received amount. This decoder makes no network requests.
+
 `XOXNOClient` requires an application-supplied `apiUrl`; the SDK does not read
 environment variables or select an API deployment for you.
 For Stellar infrastructure, use the exported `STELLAR_NETWORKS` manifest and

package/dist/cjs/sdk/stellar/index.d.ts

@@ -9,6 +9,7 @@ export type { OurRequestInit, XOXNOClientOptions } from '../../utils/api.js';
 export * from './contracts.js';
 export * from './lending.js';
 export * from './lending-read.js';
+export * from './read/index.js';
 export * from './admin.js';
 export * from './governance.js';
 export * from './events/index.js';

package/dist/cjs/sdk/stellar/read/__tests__/client.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cjs/sdk/stellar/read/client.d.ts

@@ -0,0 +1,19 @@
+import type { LendingAsset, LendingAssetUsage, LendingPosition } from './types.js';
+export interface StellarLendingReadClientOptions {
+    /** API root, for example https://api.xoxno.com. May include a deployment prefix. */
+    baseUrl: string;
+    /** Inject the host's fetch implementation when unavailable globally; it must honor redirect: 'error'. */
+    fetch?: typeof globalThis.fetch;
+}
+export interface StellarLendingReadOptions {
+    signal?: AbortSignal;
+}
+export interface StellarLendingReadClient {
+    /** Omitted usage defaults to collateral on the API. */
+    assets(options?: StellarLendingReadOptions & {
+        usage?: LendingAssetUsage;
+    }): Promise<LendingAsset[]>;
+    /** Collect every page, including a next link on an empty page. */
+    positions(owner: string, options?: StellarLendingReadOptions): Promise<LendingPosition[]>;
+}
+export declare function createStellarLendingReadClient(options: StellarLendingReadClientOptions): StellarLendingReadClient;

package/dist/cjs/sdk/stellar/read/index.d.ts

@@ -0,0 +1,4 @@
+/** Dependency-free Stellar lending REST reads and public response contracts. */
+export * from './types.js';
+export * from './schemas.js';
+export * from './client.js';

package/dist/cjs/sdk/stellar/read/schemas.d.ts

@@ -0,0 +1,370 @@
+/** OpenAPI response schema for LendingPosition[]. Every property is required; nullable data remains explicit. */
+export declare const lendingPositionsSchema: {
+    type: "array";
+    items: {
+        type: "object";
+        required: string[];
+        properties: {
+            accountId: {
+                type: "string";
+            };
+            nftContract: {
+                type: "string";
+            };
+            network: {
+                enum: string[];
+                type: "string";
+            };
+            spokeId: {
+                nullable: boolean;
+                type: "number";
+            };
+            spokeName: {
+                nullable: boolean;
+                type: "string";
+            };
+            supplied: {
+                type: "array";
+                items: {
+                    type: "object";
+                    required: string[];
+                    properties: {
+                        hubId: {
+                            type: "number";
+                        };
+                        hubName: {
+                            type: "string";
+                        };
+                        amountRaw: {
+                            description: string;
+                            nullable: boolean;
+                            type: "string";
+                        };
+                        amount: {
+                            nullable: boolean;
+                            type: "string";
+                        };
+                        apy: {
+                            description: string;
+                            nullable: boolean;
+                            type: "number";
+                        };
+                        priceUsd: {
+                            nullable: boolean;
+                            type: "number";
+                        };
+                        valueUsd: {
+                            nullable: boolean;
+                            type: "number";
+                        };
+                        priceStatus: {
+                            type: "object";
+                            required: string[];
+                            properties: {
+                                valid: {
+                                    type: "boolean";
+                                };
+                                stale: {
+                                    type: "boolean";
+                                };
+                                deviation: {
+                                    type: "boolean";
+                                };
+                                timestamp: {
+                                    nullable: boolean;
+                                    type: "number";
+                                };
+                            };
+                        };
+                        indexRay: {
+                            nullable: boolean;
+                            type: "string";
+                        };
+                        indexedAt: {
+                            type: "number";
+                        };
+                        indexedLedger: {
+                            type: "number";
+                        };
+                        sac: {
+                            type: "string";
+                        };
+                        symbol: {
+                            type: "string";
+                        };
+                        name: {
+                            type: "string";
+                        };
+                        decimals: {
+                            nullable: boolean;
+                            type: "number";
+                        };
+                        logoUrl: {
+                            nullable: boolean;
+                            type: "string";
+                        };
+                    };
+                };
+            };
+            borrow: {
+                type: "array";
+                items: {
+                    type: "object";
+                    required: string[];
+                    properties: {
+                        hubId: {
+                            type: "number";
+                        };
+                        hubName: {
+                            type: "string";
+                        };
+                        amountRaw: {
+                            description: string;
+                            nullable: boolean;
+                            type: "string";
+                        };
+                        amount: {
+                            nullable: boolean;
+                            type: "string";
+                        };
+                        apy: {
+                            description: string;
+                            nullable: boolean;
+                            type: "number";
+                        };
+                        priceUsd: {
+                            nullable: boolean;
+                            type: "number";
+                        };
+                        valueUsd: {
+                            nullable: boolean;
+                            type: "number";
+                        };
+                        priceStatus: {
+                            type: "object";
+                            required: string[];
+                            properties: {
+                                valid: {
+                                    type: "boolean";
+                                };
+                                stale: {
+                                    type: "boolean";
+                                };
+                                deviation: {
+                                    type: "boolean";
+                                };
+                                timestamp: {
+                                    nullable: boolean;
+                                    type: "number";
+                                };
+                            };
+                        };
+                        indexRay: {
+                            nullable: boolean;
+                            type: "string";
+                        };
+                        indexedAt: {
+                            type: "number";
+                        };
+                        indexedLedger: {
+                            type: "number";
+                        };
+                        sac: {
+                            type: "string";
+                        };
+                        symbol: {
+                            type: "string";
+                        };
+                        name: {
+                            type: "string";
+                        };
+                        decimals: {
+                            nullable: boolean;
+                            type: "number";
+                        };
+                        logoUrl: {
+                            nullable: boolean;
+                            type: "string";
+                        };
+                    };
+                };
+            };
+            hasDebt: {
+                nullable: boolean;
+                description: string;
+                type: "boolean";
+            };
+            healthFactor: {
+                description: string;
+                nullable: boolean;
+                type: "number";
+            };
+            borrowLimitUsd: {
+                nullable: boolean;
+                type: "number";
+            };
+            availableBorrowUsd: {
+                description: string;
+                nullable: boolean;
+                type: "number";
+            };
+            netApy: {
+                description: string;
+                nullable: boolean;
+                type: "number";
+            };
+            dataStatus: {
+                enum: string[];
+                type: "string";
+            };
+        };
+    };
+};
+/** OpenAPI response schema for LendingAsset[]. Capacities are indexed estimates. */
+export declare const lendingAssetsSchema: {
+    type: "array";
+    items: {
+        type: "object";
+        required: string[];
+        properties: {
+            hubId: {
+                type: "number";
+            };
+            hubName: {
+                type: "string";
+            };
+            network: {
+                enum: string[];
+                type: "string";
+            };
+            supplyApy: {
+                description: string;
+                nullable: boolean;
+                type: "number";
+            };
+            borrowApy: {
+                description: string;
+                nullable: boolean;
+                type: "number";
+            };
+            priceUsd: {
+                nullable: boolean;
+                type: "number";
+            };
+            priceStatus: {
+                type: "object";
+                required: string[];
+                properties: {
+                    valid: {
+                        type: "boolean";
+                    };
+                    stale: {
+                        type: "boolean";
+                    };
+                    deviation: {
+                        type: "boolean";
+                    };
+                    timestamp: {
+                        nullable: boolean;
+                        type: "number";
+                    };
+                };
+            };
+            spokes: {
+                type: "array";
+                items: {
+                    type: "object";
+                    required: string[];
+                    properties: {
+                        spokeId: {
+                            type: "number";
+                        };
+                        spokeName: {
+                            type: "string";
+                        };
+                        ltvBps: {
+                            type: "number";
+                        };
+                        supplyCapacity: {
+                            type: "object";
+                            required: string[];
+                            properties: {
+                                amountRaw: {
+                                    nullable: boolean;
+                                    type: "string";
+                                };
+                                amount: {
+                                    nullable: boolean;
+                                    type: "string";
+                                };
+                                usd: {
+                                    nullable: boolean;
+                                    type: "number";
+                                };
+                            };
+                        };
+                        borrowCapacity: {
+                            type: "object";
+                            required: string[];
+                            properties: {
+                                amountRaw: {
+                                    nullable: boolean;
+                                    type: "string";
+                                };
+                                amount: {
+                                    nullable: boolean;
+                                    type: "string";
+                                };
+                                usd: {
+                                    nullable: boolean;
+                                    type: "number";
+                                };
+                            };
+                        };
+                        canSupply: {
+                            type: "boolean";
+                        };
+                        canBeCollateral: {
+                            type: "boolean";
+                        };
+                        canBorrow: {
+                            type: "boolean";
+                        };
+                        canOpenAccount: {
+                            description: string;
+                            type: "boolean";
+                        };
+                    };
+                };
+            };
+            dataStatus: {
+                enum: string[];
+                type: "string";
+            };
+            indexedAt: {
+                description: string;
+                type: "number";
+            };
+            indexedLedger: {
+                type: "number";
+            };
+            sac: {
+                type: "string";
+            };
+            symbol: {
+                type: "string";
+            };
+            name: {
+                type: "string";
+            };
+            decimals: {
+                nullable: boolean;
+                type: "number";
+            };
+            logoUrl: {
+                nullable: boolean;
+                type: "string";
+            };
+        };
+    };
+};

package/dist/cjs/sdk/stellar/read/types.d.ts

@@ -0,0 +1,83 @@
+/** Render-ready REST data. Null means unavailable, never an inferred zero. */
+export type LendingAssetUsage = 'collateral' | 'borrow';
+export type LendingDataStatus = 'ready' | 'stale' | 'incomplete';
+export interface LendingToken {
+    sac: string;
+    symbol: string;
+    name: string;
+    decimals: number | null;
+    logoUrl: string | null;
+}
+export interface LendingPriceStatus {
+    valid: boolean;
+    stale: boolean;
+    deviation: boolean;
+    timestamp: number | null;
+}
+export interface PositionAsset extends LendingToken {
+    hubId: number;
+    hubName: string;
+    /** Integer token base units, never scaled shares. */
+    amountRaw: string | null;
+    amount: string | null;
+    /** Fraction: 0.05 means 5%. */
+    apy: number | null;
+    priceUsd: number | null;
+    valueUsd: number | null;
+    priceStatus: LendingPriceStatus;
+    indexRay: string | null;
+    indexedAt: number;
+    indexedLedger: number;
+}
+export interface LendingPosition {
+    accountId: string;
+    nftContract: string;
+    network: 'mainnet' | 'testnet';
+    spokeId: number | null;
+    spokeName: string | null;
+    supplied: PositionAsset[];
+    borrow: PositionAsset[];
+    /** Null when account rows are unavailable. */
+    hasDebt: boolean | null;
+    /** Null without debt or when risk inputs are unavailable. */
+    healthFactor: number | null;
+    borrowLimitUsd: number | null;
+    /** Account headroom, before per-market constraints. */
+    availableBorrowUsd: number | null;
+    /** Net annual yield divided by positive net equity; fraction. */
+    netApy: number | null;
+    dataStatus: LendingDataStatus;
+}
+export interface Capacity {
+    amountRaw: string | null;
+    amount: string | null;
+    usd: number | null;
+}
+export interface AssetSpoke {
+    spokeId: number;
+    spokeName: string;
+    ltvBps: number;
+    supplyCapacity: Capacity;
+    borrowCapacity: Capacity;
+    canSupply: boolean;
+    canBeCollateral: boolean;
+    canBorrow: boolean;
+    /** Spoke admits new accounts; other entry gates still apply. */
+    canOpenAccount: boolean;
+}
+export interface LendingAsset extends LendingToken {
+    hubId: number;
+    hubName: string;
+    network: 'mainnet' | 'testnet';
+    /** Fraction: 0.05 means 5%. */
+    supplyApy: number | null;
+    /** Fraction: 0.05 means 5%. */
+    borrowApy: number | null;
+    priceUsd: number | null;
+    priceStatus: LendingPriceStatus;
+    spokes: AssetSpoke[];
+    dataStatus: LendingDataStatus;
+    /** Pool timestamp. Capacities are indexed estimates; prepare/simulate before signing. */
+    indexedAt: number;
+    indexedLedger: number;
+}

package/dist/esm/index.js

@@ -0,0 +1,3 @@
+export * from "./utils/api.js";
+export * from "./utils/regex.js";
+export * from "./sdk/index.js";