infra-sdk-typescript 0.4.0 → 0.6.0

package/dist/index.d.cts

@@ -352,8 +352,27 @@ declare class WalletResource extends APIResource {
 
 type TokenType = "ASSET" | "YIELD_BEARING";
 type TokenStatus = LooseUnion<"PENDING" | "ACTIVE" | "PAUSED" | "RETIRED">;
-type TokenTransactionType = LooseUnion<"MINT" | "BURN" | "TRANSFER" | "DEPLOY" | "REDEEM" | "SNAPSHOT" | "FORCED_TRANSFER">;
+type TokenTransactionType = LooseUnion<"MINT" | "BURN" | "TRANSFER" | "DEPLOY" | "REDEEM" | "SNAPSHOT" | "FORCED_TRANSFER" | "CLAIM" | "RECLAIM">;
 type TokenTransactionStatus = LooseUnion<"PENDING" | "CONFIRMED" | "FAILED">;
+/**
+ * Where pushing a distribution's yield to investors stands, on a `SNAPSHOT` transaction created
+ * with `pushYield: true`.
+ *
+ * - `PENDING` — requested; the push runs once the snapshot confirms.
+ * - `SUBMITTED` — the push transaction was sent but hasn't settled yet.
+ * - `PUSHED` — the push transaction was mined and succeeded.
+ * - `FAILED` — the push failed; see `pushFailureReason`.
+ */
+type YieldPushStatus = LooseUnion<"PENDING" | "SUBMITTED" | "PUSHED" | "FAILED">;
+/**
+ * Outcome of a yield claim or reclaim when the call returns.
+ *
+ * - `COMPLETED` — the transaction was mined and succeeded.
+ * - `SUBMITTED` — the transaction was sent but hasn't settled yet. Poll
+ *   {@link TokenizationResource.getTokenTransaction} with the result's `operationRef`; its `status`
+ *   becomes `CONFIRMED` or `FAILED`.
+ */
+type YieldSettlementStatus = LooseUnion<"COMPLETED" | "SUBMITTED">;
 /**
  * Chain id a token is deployed on, e.g. `84532` (Base Sepolia). The API accepts it as a number
  * or a numeric string; responses always return it as a string.
@@ -522,6 +541,11 @@ interface TokenOperationResult {
 /** Result of {@link TokenizationResource.transferToken}. */
 interface TokenTransferResult {
     tokenId: string;
+    /**
+     * `CONFIRMED` once mined. `FAILED` when the transfer was rejected or reverted on-chain; the call
+     * still resolves in that case, so check this rather than relying on an error. `txHash` is set
+     * when the failed transfer was mined.
+     */
     status: TokenTransactionStatus;
     transactionId: string;
     fromAddressIndex: number;
@@ -566,8 +590,24 @@ interface TokenWalletBalance {
     /** Balance in token units, as a decimal string. */
     balance: string;
     decimals: number;
-    /** The wallet's cNGN (payout token) balance, as a decimal string. Coupons, yield and principal are paid in cNGN. */
-    cNgnBalance: string;
+}
+interface GetPayoutBalanceParams {
+    chainId: TokenChainId;
+    walletAddress: string;
+}
+/**
+ * A wallet's balance of the chain's payout token, returned by
+ * {@link TokenizationResource.getPayoutBalance}. Coupons, yield and principal are all paid in it.
+ */
+interface PayoutBalance {
+    chainId: string;
+    walletAddress: string;
+    payoutToken: YieldPayoutToken;
+    /** The payout token's contract address on this chain. */
+    tokenAddress: string;
+    /** Balance in payout-token units, as a decimal string, e.g. `"1234.56"`. */
+    balance: string;
+    decimals: number;
 }
 interface ListTokenTransactionsParams {
     tokenId?: string;
@@ -581,7 +621,10 @@ interface ListTokenTransactionsParams {
     txHash?: string;
     operationRef?: string;
 }
-/** A recorded on-chain operation against a token (mint, burn, or transfer). */
+/**
+ * A recorded on-chain operation against a token: a mint, burn or transfer, a deployment, a yield
+ * distribution (`SNAPSHOT`), or a yield claim (`CLAIM`) or reclaim (`RECLAIM`).
+ */
 interface TokenTransactionRecord {
     id: string;
     tokenId: string;
@@ -602,8 +645,18 @@ interface TokenTransactionRecord {
     memo?: string;
     createdAt?: string;
     confirmedAt?: string;
-    /** Distribution snapshot id, set on `SNAPSHOT` transactions. */
+    /** Distribution snapshot id, set on `SNAPSHOT`, `CLAIM` and `RECLAIM` transactions. */
     snapshotId?: number;
+    /** Why the transaction failed, when `status` is `FAILED`. */
+    failureReason?: string;
+    /** Whether the distribution pushes yield to investors. Set on `SNAPSHOT` transactions. */
+    pushYield?: boolean;
+    /** Progress of the push, on `SNAPSHOT` transactions with `pushYield`. Absent when no push was requested or made. */
+    pushStatus?: YieldPushStatus;
+    /** Hash of the push transaction, once sent. */
+    pushTxHash?: string;
+    /** Why the push failed, when `pushStatus` is `FAILED`. */
+    pushFailureReason?: string;
 }
 interface UpdateTokenYieldParams {
     /** Yield-bearing token id. */
@@ -708,6 +761,64 @@ interface RedeemPrincipalResult {
      */
     closed: boolean;
 }
+interface GetYieldPositionsParams {
+    tokenId: string;
+    chainId: TokenChainId;
+    /** The holder's wallet. */
+    walletAddress: string;
+    /** Distribution snapshots to read, at most 100. Duplicates are read once. */
+    snapshotIds: number[];
+}
+/**
+ * Where one holder stands on a distribution snapshot.
+ *
+ * - `NOT_ENTITLED` — the wallet had no balance recorded at the snapshot.
+ * - `PAID` — the holder has received their share. A push and a claim both end here; the contract
+ *   records them the same way.
+ * - `RECLAIMED` — unpaid, and the issuer has taken back the snapshot's unclaimed funds.
+ * - `UNCLAIMED` — unpaid and still active. Check `pendingAmount`: it is `0` while the holder is
+ *   ineligible to collect (for example frozen), and {@link TokenizationResource.claimYield} can
+ *   still refuse a wallet that isn't currently verified.
+ */
+type YieldSettlement = LooseUnion<"NOT_ENTITLED" | "PAID" | "RECLAIMED" | "UNCLAIMED">;
+/** One entry of {@link YieldPositions.positions}: the holder's position, or why it couldn't be read. */
+type YieldPosition = YieldPositionRead | YieldPositionError;
+interface YieldPositionRead {
+    snapshotId: number;
+    settlement: YieldSettlement;
+    /** Whether the holder has been paid, by a claim or a push. */
+    claimed: boolean;
+    /** `false` once the snapshot has been reclaimed. */
+    active: boolean;
+    /** ISO 8601. When unclaimed funds become reclaimable. */
+    reclaimDeadline: string;
+    /** The snapshot's whole payout, in cNGN base units (6 decimals), as an integer string. */
+    totalFunds: string;
+    /** The holder's token balance at the snapshot, in the token's smallest unit, as an integer string. */
+    snapshotBalance: string;
+    /** The holder's share of `totalFunds`, in cNGN base units, as an integer string. */
+    entitledAmount: string;
+    /** What the holder has received, in cNGN base units, as an integer string. */
+    paidAmount: string;
+    /** What the holder can collect now, in cNGN base units, as an integer string. */
+    pendingAmount: string;
+    error?: undefined;
+}
+interface YieldPositionError {
+    snapshotId: number;
+    error: {
+        /** `NOT_FOUND_SNAPSHOT`, or `SNAPSHOT_READ_FAILED` when the read can be retried. */
+        code: LooseUnion<"NOT_FOUND_SNAPSHOT" | "SNAPSHOT_READ_FAILED">;
+        message: string;
+    };
+}
+/** Result of {@link TokenizationResource.getYieldPositions}. */
+interface YieldPositions {
+    tokenId: string;
+    chainId: string;
+    walletAddress: string;
+    positions: YieldPosition[];
+}
 interface GetNextCouponParams {
     tokenId: string;
     chainId: TokenChainId;
@@ -750,17 +861,22 @@ interface ReclaimUnclaimedYieldParams {
 /** Result of {@link TokenizationResource.reclaimUnclaimedYield}. */
 interface ReclaimUnclaimedYieldResult {
     tokenId: string;
-    /** Snapshot id, as a numeric string. */
-    snapshotId: string;
-    /** Amount reclaimed, as a decimal string. */
+    snapshotId: number;
+    /** Amount reclaimed, in cNGN base units (6 decimals), as an integer string. */
     reclaimed: string;
     operationRef: string;
+    /** Id of the `RECLAIM` transaction record. */
+    transactionId: string;
     txHash: string;
+    status: YieldSettlementStatus;
 }
 /** Result of {@link TokenizationResource.claimYield}. */
 interface YieldTxResult {
     operationRef: string;
+    /** Id of the `CLAIM` transaction record. */
+    transactionId: string;
     txHash: string;
+    status: YieldSettlementStatus;
 }
 /** Result of {@link TokenizationResource.distributeYield} / {@link TokenizationResource.payCoupon}. */
 interface YieldOperationResult {
@@ -799,7 +915,10 @@ declare class TokenizationResource extends APIResource {
     mintToken(params: MintTokenParams, overrides?: IdempotentRequestOverrides): Promise<TokenOperationResult>;
     /** Burns units of a token from a holder address. */
     burnToken(params: BurnTokenParams, overrides?: IdempotentRequestOverrides): Promise<TokenOperationResult>;
-    /** Transfers token units between holder addresses. */
+    /**
+     * Transfers token units between holder addresses. A transfer that is rejected or reverts
+     * on-chain still resolves, with `status: "FAILED"`, so check `status` rather than relying on an error.
+     */
     transferToken(params: TransferTokenParams, overrides?: IdempotentRequestOverrides): Promise<TokenTransferResult>;
     /**
      * Force-transfers token units out of a holder's address without the holder's signature
@@ -811,8 +930,13 @@ declare class TokenizationResource extends APIResource {
     registerWallet(params: RegisterTokenWalletParams, overrides?: IdempotentRequestOverrides): Promise<RegisterTokenWalletResult>;
     /** Returns the paginated list of holder wallet addresses and balances for a token on a chain. */
     getTokenHolders(params: GetTokenHoldersParams, overrides?: RequestOverrides): Promise<Page<TokenHolder>>;
-    /** Returns a single wallet's balance of a token on a chain, plus its cNGN (payout token) balance. */
+    /** Returns a single wallet's balance of a token on a chain. For its cNGN balance, use {@link getPayoutBalance}. */
     getWalletBalance(params: GetWalletBalanceParams, overrides?: RequestOverrides): Promise<TokenWalletBalance>;
+    /**
+     * Returns a wallet's balance of the chain's payout token (cNGN), in which coupons, yield and
+     * principal are paid. It depends only on the chain and wallet, so no token is needed.
+     */
+    getPayoutBalance(params: GetPayoutBalanceParams, overrides?: RequestOverrides): Promise<PayoutBalance>;
     /** Fetches a single token transaction by its reference. */
     getTokenTransaction(ref: string, overrides?: RequestOverrides): Promise<TokenTransactionRecord>;
     /** Returns token transactions, optionally filtered by token. */
@@ -826,7 +950,11 @@ declare class TokenizationResource extends APIResource {
     distributeYield(params: DistributeYieldParams, overrides?: IdempotentRequestOverrides): Promise<YieldOperationResult>;
     /** Pays the scheduled coupon for a yield-bearing token. Set `pushYield` to push funds rather than let investors claim. */
     payCoupon(params: PayCouponParams, overrides?: IdempotentRequestOverrides): Promise<YieldOperationResult>;
-    /** Claims an investor's yield for a given distribution snapshot. */
+    /**
+     * Claims an investor's yield for a given distribution snapshot. `status` is `COMPLETED` once the
+     * claim is mined. If it's `SUBMITTED`, the outcome isn't known yet: poll
+     * {@link getTokenTransaction} with the result's `operationRef` until its `status` is `CONFIRMED` or `FAILED`.
+     */
     claimYield(params: ClaimYieldParams, overrides?: IdempotentRequestOverrides): Promise<YieldTxResult>;
     /**
      * Returns the bond's next coupon date and where it stands on its schedule. Whether a coupon is
@@ -839,6 +967,19 @@ declare class TokenizationResource extends APIResource {
      * ```
      */
     getNextCoupon(params: GetNextCouponParams, overrides?: RequestOverrides): Promise<NextCoupon>;
+    /**
+     * Returns one holder's position in each of the given distribution snapshots: their share, what
+     * they've been paid and what they can still collect. Works for paused and retired tokens. A
+     * snapshot that can't be read is reported on its own entry, so check `error` on each.
+     *
+     * ```ts
+     * const { positions } = await client.tokenization.getYieldPositions({
+     *   tokenId, chainId: "84532", walletAddress, snapshotIds: [1, 2],
+     * });
+     * for (const p of positions) if (!p.error) console.log(p.snapshotId, p.settlement, p.paidAmount);
+     * ```
+     */
+    getYieldPositions(params: GetYieldPositionsParams, overrides?: RequestOverrides): Promise<YieldPositions>;
     /**
      * Redeems principal to holders at maturity, paying from the cNGN deposited in the token contract.
      * Issuer-held tokens are burned without a payout so the supply can reach zero and the bond close.
@@ -851,7 +992,8 @@ declare class TokenizationResource extends APIResource {
     redeemPrincipal(params: RedeemPrincipalParams, overrides?: IdempotentRequestOverrides): Promise<RedeemPrincipalResult>;
     /**
      * Returns a snapshot's unclaimed yield to the issuer once its `reclaimAfter` window has
-     * passed. An `Idempotency-Key` is generated per call unless you pass your own.
+     * passed. An `Idempotency-Key` is generated per call unless you pass your own. As with
+     * {@link claimYield}, a `SUBMITTED` status means the outcome should be polled by `operationRef`.
      */
     reclaimUnclaimedYield(params: ReclaimUnclaimedYieldParams, overrides?: IdempotentRequestOverrides): Promise<ReclaimUnclaimedYieldResult>;
 }
@@ -1108,4 +1250,4 @@ declare function verifyIndexerWebhookSignature(options: VerifyIndexerWebhookOpti
 /** Generates a UUIDv4 suitable for use as an `Idempotency-Key` header value. */
 declare function generateIdempotencyKey(): string;
 
-export { type AssetClass, AuthenticationError, BadRequestError, type BurnTokenParams, type Chain, type ChainType, type ClaimYieldParams, ConflictError, type CreateSubscriptionParams, type CreateTokenParams, type DeactivateWalletParams, type DistributeYieldParams, type EventCatalogEntry, type EventFamily, type EventKind, type FlatPaginatedResponse, type ForcedTransferTokenParams, type GenerateWalletsParams, type GeneratedWallet, type GetNextCouponParams, type GetTokenHoldersParams, type GetTransactionHistoryParams, type GetWalletBalanceParams, type GetWalletByAddressIndexParams, type GetWalletByAddressParams, type GetWalletCountParams, type HdEnabledStatus, type HttpMethod, type IdempotentRequestOverrides, IndexerResource, type IndexerSubscription, type IndexerSubscriptionWithSecret, InfraAPIError, InfraAuthTokenError, InfraClient, type InfraClientOptions, InfraConnectionError, InfraConnectionTimeoutError, InfraError, type InitiateTransferParams, InternalServerError, type ListEventCatalogParams, type ListSubscriptionsParams, type ListTokenTransactionsParams, type ListTokensParams, type ListWalletsParams, type LooseUnion, type MetaPaginatedResponse, type MintTokenParams, type Network, type NextCoupon, type NextCouponStatus, NotFoundError, type OffsetPaginatedResponse, Page, type PayCouponParams, PaymentRequiredError, PermissionDeniedError, type QueryValue, RateLimitError, type ReclaimUnclaimedYieldParams, type ReclaimUnclaimedYieldResult, type RedeemPrincipalParams, type RedeemPrincipalResult, type RedemptionSkipReason, type RedemptionSkippedHolder, type RegisterTokenWalletParams, type RegisterTokenWalletResult, type RequestOptions, type RequestOverrides, ServiceUnavailableError, type SignTransactionParams, type SignTransactionRequest, type SignedTransactionResult, type SubscriptionStatus, type SupportedChain, type TokenChainDeployment, type TokenChainId, type TokenDeploymentResult, type TokenDetail, type TokenHolder, type TokenOperationResult, type TokenStatus, type TokenSummary, type TokenTransactionRecord, type TokenTransactionStatus, type TokenTransactionType, type TokenTransferResult, type TokenType, type TokenWalletBalance, TokenizationResource, type TransactionStatus, type TransferTokenParams, UnknownAPIError, UnprocessableEntityError, type UpdateSubscriptionParams, type UpdateTokenYieldParams, type UpdateYieldResult, type VerifyIndexerWebhookOptions, type VerifyWalletWebhookOptions, type Wallet, type WalletBalance, type WalletCount, WalletResource, type WalletTransaction, WebhookSignatureVerificationError, type YieldDayCount, type YieldOperationResult, type YieldParams, type YieldPayoutToken, type YieldTxResult, generateIdempotencyKey, verifyIndexerWebhookSignature, verifyWalletWebhookSignature };
+export { type AssetClass, AuthenticationError, BadRequestError, type BurnTokenParams, type Chain, type ChainType, type ClaimYieldParams, ConflictError, type CreateSubscriptionParams, type CreateTokenParams, type DeactivateWalletParams, type DistributeYieldParams, type EventCatalogEntry, type EventFamily, type EventKind, type FlatPaginatedResponse, type ForcedTransferTokenParams, type GenerateWalletsParams, type GeneratedWallet, type GetNextCouponParams, type GetPayoutBalanceParams, type GetTokenHoldersParams, type GetTransactionHistoryParams, type GetWalletBalanceParams, type GetWalletByAddressIndexParams, type GetWalletByAddressParams, type GetWalletCountParams, type GetYieldPositionsParams, type HdEnabledStatus, type HttpMethod, type IdempotentRequestOverrides, IndexerResource, type IndexerSubscription, type IndexerSubscriptionWithSecret, InfraAPIError, InfraAuthTokenError, InfraClient, type InfraClientOptions, InfraConnectionError, InfraConnectionTimeoutError, InfraError, type InitiateTransferParams, InternalServerError, type ListEventCatalogParams, type ListSubscriptionsParams, type ListTokenTransactionsParams, type ListTokensParams, type ListWalletsParams, type LooseUnion, type MetaPaginatedResponse, type MintTokenParams, type Network, type NextCoupon, type NextCouponStatus, NotFoundError, type OffsetPaginatedResponse, Page, type PayCouponParams, PaymentRequiredError, type PayoutBalance, PermissionDeniedError, type QueryValue, RateLimitError, type ReclaimUnclaimedYieldParams, type ReclaimUnclaimedYieldResult, type RedeemPrincipalParams, type RedeemPrincipalResult, type RedemptionSkipReason, type RedemptionSkippedHolder, type RegisterTokenWalletParams, type RegisterTokenWalletResult, type RequestOptions, type RequestOverrides, ServiceUnavailableError, type SignTransactionParams, type SignTransactionRequest, type SignedTransactionResult, type SubscriptionStatus, type SupportedChain, type TokenChainDeployment, type TokenChainId, type TokenDeploymentResult, type TokenDetail, type TokenHolder, type TokenOperationResult, type TokenStatus, type TokenSummary, type TokenTransactionRecord, type TokenTransactionStatus, type TokenTransactionType, type TokenTransferResult, type TokenType, type TokenWalletBalance, TokenizationResource, type TransactionStatus, type TransferTokenParams, UnknownAPIError, UnprocessableEntityError, type UpdateSubscriptionParams, type UpdateTokenYieldParams, type UpdateYieldResult, type VerifyIndexerWebhookOptions, type VerifyWalletWebhookOptions, type Wallet, type WalletBalance, type WalletCount, WalletResource, type WalletTransaction, WebhookSignatureVerificationError, type YieldDayCount, type YieldOperationResult, type YieldParams, type YieldPayoutToken, type YieldPosition, type YieldPositionError, type YieldPositionRead, type YieldPositions, type YieldPushStatus, type YieldSettlement, type YieldSettlementStatus, type YieldTxResult, generateIdempotencyKey, verifyIndexerWebhookSignature, verifyWalletWebhookSignature };

package/dist/index.d.ts

@@ -352,8 +352,27 @@ declare class WalletResource extends APIResource {
 
 type TokenType = "ASSET" | "YIELD_BEARING";
 type TokenStatus = LooseUnion<"PENDING" | "ACTIVE" | "PAUSED" | "RETIRED">;
-type TokenTransactionType = LooseUnion<"MINT" | "BURN" | "TRANSFER" | "DEPLOY" | "REDEEM" | "SNAPSHOT" | "FORCED_TRANSFER">;
+type TokenTransactionType = LooseUnion<"MINT" | "BURN" | "TRANSFER" | "DEPLOY" | "REDEEM" | "SNAPSHOT" | "FORCED_TRANSFER" | "CLAIM" | "RECLAIM">;
 type TokenTransactionStatus = LooseUnion<"PENDING" | "CONFIRMED" | "FAILED">;
+/**
+ * Where pushing a distribution's yield to investors stands, on a `SNAPSHOT` transaction created
+ * with `pushYield: true`.
+ *
+ * - `PENDING` — requested; the push runs once the snapshot confirms.
+ * - `SUBMITTED` — the push transaction was sent but hasn't settled yet.
+ * - `PUSHED` — the push transaction was mined and succeeded.
+ * - `FAILED` — the push failed; see `pushFailureReason`.
+ */
+type YieldPushStatus = LooseUnion<"PENDING" | "SUBMITTED" | "PUSHED" | "FAILED">;
+/**
+ * Outcome of a yield claim or reclaim when the call returns.
+ *
+ * - `COMPLETED` — the transaction was mined and succeeded.
+ * - `SUBMITTED` — the transaction was sent but hasn't settled yet. Poll
+ *   {@link TokenizationResource.getTokenTransaction} with the result's `operationRef`; its `status`
+ *   becomes `CONFIRMED` or `FAILED`.
+ */
+type YieldSettlementStatus = LooseUnion<"COMPLETED" | "SUBMITTED">;
 /**
  * Chain id a token is deployed on, e.g. `84532` (Base Sepolia). The API accepts it as a number
  * or a numeric string; responses always return it as a string.
@@ -522,6 +541,11 @@ interface TokenOperationResult {
 /** Result of {@link TokenizationResource.transferToken}. */
 interface TokenTransferResult {
     tokenId: string;
+    /**
+     * `CONFIRMED` once mined. `FAILED` when the transfer was rejected or reverted on-chain; the call
+     * still resolves in that case, so check this rather than relying on an error. `txHash` is set
+     * when the failed transfer was mined.
+     */
     status: TokenTransactionStatus;
     transactionId: string;
     fromAddressIndex: number;
@@ -566,8 +590,24 @@ interface TokenWalletBalance {
     /** Balance in token units, as a decimal string. */
     balance: string;
     decimals: number;
-    /** The wallet's cNGN (payout token) balance, as a decimal string. Coupons, yield and principal are paid in cNGN. */
-    cNgnBalance: string;
+}
+interface GetPayoutBalanceParams {
+    chainId: TokenChainId;
+    walletAddress: string;
+}
+/**
+ * A wallet's balance of the chain's payout token, returned by
+ * {@link TokenizationResource.getPayoutBalance}. Coupons, yield and principal are all paid in it.
+ */
+interface PayoutBalance {
+    chainId: string;
+    walletAddress: string;
+    payoutToken: YieldPayoutToken;
+    /** The payout token's contract address on this chain. */
+    tokenAddress: string;
+    /** Balance in payout-token units, as a decimal string, e.g. `"1234.56"`. */
+    balance: string;
+    decimals: number;
 }
 interface ListTokenTransactionsParams {
     tokenId?: string;
@@ -581,7 +621,10 @@ interface ListTokenTransactionsParams {
     txHash?: string;
     operationRef?: string;
 }
-/** A recorded on-chain operation against a token (mint, burn, or transfer). */
+/**
+ * A recorded on-chain operation against a token: a mint, burn or transfer, a deployment, a yield
+ * distribution (`SNAPSHOT`), or a yield claim (`CLAIM`) or reclaim (`RECLAIM`).
+ */
 interface TokenTransactionRecord {
     id: string;
     tokenId: string;
@@ -602,8 +645,18 @@ interface TokenTransactionRecord {
     memo?: string;
     createdAt?: string;
     confirmedAt?: string;
-    /** Distribution snapshot id, set on `SNAPSHOT` transactions. */
+    /** Distribution snapshot id, set on `SNAPSHOT`, `CLAIM` and `RECLAIM` transactions. */
     snapshotId?: number;
+    /** Why the transaction failed, when `status` is `FAILED`. */
+    failureReason?: string;
+    /** Whether the distribution pushes yield to investors. Set on `SNAPSHOT` transactions. */
+    pushYield?: boolean;
+    /** Progress of the push, on `SNAPSHOT` transactions with `pushYield`. Absent when no push was requested or made. */
+    pushStatus?: YieldPushStatus;
+    /** Hash of the push transaction, once sent. */
+    pushTxHash?: string;
+    /** Why the push failed, when `pushStatus` is `FAILED`. */
+    pushFailureReason?: string;
 }
 interface UpdateTokenYieldParams {
     /** Yield-bearing token id. */
@@ -708,6 +761,64 @@ interface RedeemPrincipalResult {
      */
     closed: boolean;
 }
+interface GetYieldPositionsParams {
+    tokenId: string;
+    chainId: TokenChainId;
+    /** The holder's wallet. */
+    walletAddress: string;
+    /** Distribution snapshots to read, at most 100. Duplicates are read once. */
+    snapshotIds: number[];
+}
+/**
+ * Where one holder stands on a distribution snapshot.
+ *
+ * - `NOT_ENTITLED` — the wallet had no balance recorded at the snapshot.
+ * - `PAID` — the holder has received their share. A push and a claim both end here; the contract
+ *   records them the same way.
+ * - `RECLAIMED` — unpaid, and the issuer has taken back the snapshot's unclaimed funds.
+ * - `UNCLAIMED` — unpaid and still active. Check `pendingAmount`: it is `0` while the holder is
+ *   ineligible to collect (for example frozen), and {@link TokenizationResource.claimYield} can
+ *   still refuse a wallet that isn't currently verified.
+ */
+type YieldSettlement = LooseUnion<"NOT_ENTITLED" | "PAID" | "RECLAIMED" | "UNCLAIMED">;
+/** One entry of {@link YieldPositions.positions}: the holder's position, or why it couldn't be read. */
+type YieldPosition = YieldPositionRead | YieldPositionError;
+interface YieldPositionRead {
+    snapshotId: number;
+    settlement: YieldSettlement;
+    /** Whether the holder has been paid, by a claim or a push. */
+    claimed: boolean;
+    /** `false` once the snapshot has been reclaimed. */
+    active: boolean;
+    /** ISO 8601. When unclaimed funds become reclaimable. */
+    reclaimDeadline: string;
+    /** The snapshot's whole payout, in cNGN base units (6 decimals), as an integer string. */
+    totalFunds: string;
+    /** The holder's token balance at the snapshot, in the token's smallest unit, as an integer string. */
+    snapshotBalance: string;
+    /** The holder's share of `totalFunds`, in cNGN base units, as an integer string. */
+    entitledAmount: string;
+    /** What the holder has received, in cNGN base units, as an integer string. */
+    paidAmount: string;
+    /** What the holder can collect now, in cNGN base units, as an integer string. */
+    pendingAmount: string;
+    error?: undefined;
+}
+interface YieldPositionError {
+    snapshotId: number;
+    error: {
+        /** `NOT_FOUND_SNAPSHOT`, or `SNAPSHOT_READ_FAILED` when the read can be retried. */
+        code: LooseUnion<"NOT_FOUND_SNAPSHOT" | "SNAPSHOT_READ_FAILED">;
+        message: string;
+    };
+}
+/** Result of {@link TokenizationResource.getYieldPositions}. */
+interface YieldPositions {
+    tokenId: string;
+    chainId: string;
+    walletAddress: string;
+    positions: YieldPosition[];
+}
 interface GetNextCouponParams {
     tokenId: string;
     chainId: TokenChainId;
@@ -750,17 +861,22 @@ interface ReclaimUnclaimedYieldParams {
 /** Result of {@link TokenizationResource.reclaimUnclaimedYield}. */
 interface ReclaimUnclaimedYieldResult {
     tokenId: string;
-    /** Snapshot id, as a numeric string. */
-    snapshotId: string;
-    /** Amount reclaimed, as a decimal string. */
+    snapshotId: number;
+    /** Amount reclaimed, in cNGN base units (6 decimals), as an integer string. */
     reclaimed: string;
     operationRef: string;
+    /** Id of the `RECLAIM` transaction record. */
+    transactionId: string;
     txHash: string;
+    status: YieldSettlementStatus;
 }
 /** Result of {@link TokenizationResource.claimYield}. */
 interface YieldTxResult {
     operationRef: string;
+    /** Id of the `CLAIM` transaction record. */
+    transactionId: string;
     txHash: string;
+    status: YieldSettlementStatus;
 }
 /** Result of {@link TokenizationResource.distributeYield} / {@link TokenizationResource.payCoupon}. */
 interface YieldOperationResult {
@@ -799,7 +915,10 @@ declare class TokenizationResource extends APIResource {
     mintToken(params: MintTokenParams, overrides?: IdempotentRequestOverrides): Promise<TokenOperationResult>;
     /** Burns units of a token from a holder address. */
     burnToken(params: BurnTokenParams, overrides?: IdempotentRequestOverrides): Promise<TokenOperationResult>;
-    /** Transfers token units between holder addresses. */
+    /**
+     * Transfers token units between holder addresses. A transfer that is rejected or reverts
+     * on-chain still resolves, with `status: "FAILED"`, so check `status` rather than relying on an error.
+     */
     transferToken(params: TransferTokenParams, overrides?: IdempotentRequestOverrides): Promise<TokenTransferResult>;
     /**
      * Force-transfers token units out of a holder's address without the holder's signature
@@ -811,8 +930,13 @@ declare class TokenizationResource extends APIResource {
     registerWallet(params: RegisterTokenWalletParams, overrides?: IdempotentRequestOverrides): Promise<RegisterTokenWalletResult>;
     /** Returns the paginated list of holder wallet addresses and balances for a token on a chain. */
     getTokenHolders(params: GetTokenHoldersParams, overrides?: RequestOverrides): Promise<Page<TokenHolder>>;
-    /** Returns a single wallet's balance of a token on a chain, plus its cNGN (payout token) balance. */
+    /** Returns a single wallet's balance of a token on a chain. For its cNGN balance, use {@link getPayoutBalance}. */
     getWalletBalance(params: GetWalletBalanceParams, overrides?: RequestOverrides): Promise<TokenWalletBalance>;
+    /**
+     * Returns a wallet's balance of the chain's payout token (cNGN), in which coupons, yield and
+     * principal are paid. It depends only on the chain and wallet, so no token is needed.
+     */
+    getPayoutBalance(params: GetPayoutBalanceParams, overrides?: RequestOverrides): Promise<PayoutBalance>;
     /** Fetches a single token transaction by its reference. */
     getTokenTransaction(ref: string, overrides?: RequestOverrides): Promise<TokenTransactionRecord>;
     /** Returns token transactions, optionally filtered by token. */
@@ -826,7 +950,11 @@ declare class TokenizationResource extends APIResource {
     distributeYield(params: DistributeYieldParams, overrides?: IdempotentRequestOverrides): Promise<YieldOperationResult>;
     /** Pays the scheduled coupon for a yield-bearing token. Set `pushYield` to push funds rather than let investors claim. */
     payCoupon(params: PayCouponParams, overrides?: IdempotentRequestOverrides): Promise<YieldOperationResult>;
-    /** Claims an investor's yield for a given distribution snapshot. */
+    /**
+     * Claims an investor's yield for a given distribution snapshot. `status` is `COMPLETED` once the
+     * claim is mined. If it's `SUBMITTED`, the outcome isn't known yet: poll
+     * {@link getTokenTransaction} with the result's `operationRef` until its `status` is `CONFIRMED` or `FAILED`.
+     */
     claimYield(params: ClaimYieldParams, overrides?: IdempotentRequestOverrides): Promise<YieldTxResult>;
     /**
      * Returns the bond's next coupon date and where it stands on its schedule. Whether a coupon is
@@ -839,6 +967,19 @@ declare class TokenizationResource extends APIResource {
      * ```
      */
     getNextCoupon(params: GetNextCouponParams, overrides?: RequestOverrides): Promise<NextCoupon>;
+    /**
+     * Returns one holder's position in each of the given distribution snapshots: their share, what
+     * they've been paid and what they can still collect. Works for paused and retired tokens. A
+     * snapshot that can't be read is reported on its own entry, so check `error` on each.
+     *
+     * ```ts
+     * const { positions } = await client.tokenization.getYieldPositions({
+     *   tokenId, chainId: "84532", walletAddress, snapshotIds: [1, 2],
+     * });
+     * for (const p of positions) if (!p.error) console.log(p.snapshotId, p.settlement, p.paidAmount);
+     * ```
+     */
+    getYieldPositions(params: GetYieldPositionsParams, overrides?: RequestOverrides): Promise<YieldPositions>;
     /**
      * Redeems principal to holders at maturity, paying from the cNGN deposited in the token contract.
      * Issuer-held tokens are burned without a payout so the supply can reach zero and the bond close.
@@ -851,7 +992,8 @@ declare class TokenizationResource extends APIResource {
     redeemPrincipal(params: RedeemPrincipalParams, overrides?: IdempotentRequestOverrides): Promise<RedeemPrincipalResult>;
     /**
      * Returns a snapshot's unclaimed yield to the issuer once its `reclaimAfter` window has
-     * passed. An `Idempotency-Key` is generated per call unless you pass your own.
+     * passed. An `Idempotency-Key` is generated per call unless you pass your own. As with
+     * {@link claimYield}, a `SUBMITTED` status means the outcome should be polled by `operationRef`.
      */
     reclaimUnclaimedYield(params: ReclaimUnclaimedYieldParams, overrides?: IdempotentRequestOverrides): Promise<ReclaimUnclaimedYieldResult>;
 }
@@ -1108,4 +1250,4 @@ declare function verifyIndexerWebhookSignature(options: VerifyIndexerWebhookOpti
 /** Generates a UUIDv4 suitable for use as an `Idempotency-Key` header value. */
 declare function generateIdempotencyKey(): string;
 
-export { type AssetClass, AuthenticationError, BadRequestError, type BurnTokenParams, type Chain, type ChainType, type ClaimYieldParams, ConflictError, type CreateSubscriptionParams, type CreateTokenParams, type DeactivateWalletParams, type DistributeYieldParams, type EventCatalogEntry, type EventFamily, type EventKind, type FlatPaginatedResponse, type ForcedTransferTokenParams, type GenerateWalletsParams, type GeneratedWallet, type GetNextCouponParams, type GetTokenHoldersParams, type GetTransactionHistoryParams, type GetWalletBalanceParams, type GetWalletByAddressIndexParams, type GetWalletByAddressParams, type GetWalletCountParams, type HdEnabledStatus, type HttpMethod, type IdempotentRequestOverrides, IndexerResource, type IndexerSubscription, type IndexerSubscriptionWithSecret, InfraAPIError, InfraAuthTokenError, InfraClient, type InfraClientOptions, InfraConnectionError, InfraConnectionTimeoutError, InfraError, type InitiateTransferParams, InternalServerError, type ListEventCatalogParams, type ListSubscriptionsParams, type ListTokenTransactionsParams, type ListTokensParams, type ListWalletsParams, type LooseUnion, type MetaPaginatedResponse, type MintTokenParams, type Network, type NextCoupon, type NextCouponStatus, NotFoundError, type OffsetPaginatedResponse, Page, type PayCouponParams, PaymentRequiredError, PermissionDeniedError, type QueryValue, RateLimitError, type ReclaimUnclaimedYieldParams, type ReclaimUnclaimedYieldResult, type RedeemPrincipalParams, type RedeemPrincipalResult, type RedemptionSkipReason, type RedemptionSkippedHolder, type RegisterTokenWalletParams, type RegisterTokenWalletResult, type RequestOptions, type RequestOverrides, ServiceUnavailableError, type SignTransactionParams, type SignTransactionRequest, type SignedTransactionResult, type SubscriptionStatus, type SupportedChain, type TokenChainDeployment, type TokenChainId, type TokenDeploymentResult, type TokenDetail, type TokenHolder, type TokenOperationResult, type TokenStatus, type TokenSummary, type TokenTransactionRecord, type TokenTransactionStatus, type TokenTransactionType, type TokenTransferResult, type TokenType, type TokenWalletBalance, TokenizationResource, type TransactionStatus, type TransferTokenParams, UnknownAPIError, UnprocessableEntityError, type UpdateSubscriptionParams, type UpdateTokenYieldParams, type UpdateYieldResult, type VerifyIndexerWebhookOptions, type VerifyWalletWebhookOptions, type Wallet, type WalletBalance, type WalletCount, WalletResource, type WalletTransaction, WebhookSignatureVerificationError, type YieldDayCount, type YieldOperationResult, type YieldParams, type YieldPayoutToken, type YieldTxResult, generateIdempotencyKey, verifyIndexerWebhookSignature, verifyWalletWebhookSignature };
+export { type AssetClass, AuthenticationError, BadRequestError, type BurnTokenParams, type Chain, type ChainType, type ClaimYieldParams, ConflictError, type CreateSubscriptionParams, type CreateTokenParams, type DeactivateWalletParams, type DistributeYieldParams, type EventCatalogEntry, type EventFamily, type EventKind, type FlatPaginatedResponse, type ForcedTransferTokenParams, type GenerateWalletsParams, type GeneratedWallet, type GetNextCouponParams, type GetPayoutBalanceParams, type GetTokenHoldersParams, type GetTransactionHistoryParams, type GetWalletBalanceParams, type GetWalletByAddressIndexParams, type GetWalletByAddressParams, type GetWalletCountParams, type GetYieldPositionsParams, type HdEnabledStatus, type HttpMethod, type IdempotentRequestOverrides, IndexerResource, type IndexerSubscription, type IndexerSubscriptionWithSecret, InfraAPIError, InfraAuthTokenError, InfraClient, type InfraClientOptions, InfraConnectionError, InfraConnectionTimeoutError, InfraError, type InitiateTransferParams, InternalServerError, type ListEventCatalogParams, type ListSubscriptionsParams, type ListTokenTransactionsParams, type ListTokensParams, type ListWalletsParams, type LooseUnion, type MetaPaginatedResponse, type MintTokenParams, type Network, type NextCoupon, type NextCouponStatus, NotFoundError, type OffsetPaginatedResponse, Page, type PayCouponParams, PaymentRequiredError, type PayoutBalance, PermissionDeniedError, type QueryValue, RateLimitError, type ReclaimUnclaimedYieldParams, type ReclaimUnclaimedYieldResult, type RedeemPrincipalParams, type RedeemPrincipalResult, type RedemptionSkipReason, type RedemptionSkippedHolder, type RegisterTokenWalletParams, type RegisterTokenWalletResult, type RequestOptions, type RequestOverrides, ServiceUnavailableError, type SignTransactionParams, type SignTransactionRequest, type SignedTransactionResult, type SubscriptionStatus, type SupportedChain, type TokenChainDeployment, type TokenChainId, type TokenDeploymentResult, type TokenDetail, type TokenHolder, type TokenOperationResult, type TokenStatus, type TokenSummary, type TokenTransactionRecord, type TokenTransactionStatus, type TokenTransactionType, type TokenTransferResult, type TokenType, type TokenWalletBalance, TokenizationResource, type TransactionStatus, type TransferTokenParams, UnknownAPIError, UnprocessableEntityError, type UpdateSubscriptionParams, type UpdateTokenYieldParams, type UpdateYieldResult, type VerifyIndexerWebhookOptions, type VerifyWalletWebhookOptions, type Wallet, type WalletBalance, type WalletCount, WalletResource, type WalletTransaction, WebhookSignatureVerificationError, type YieldDayCount, type YieldOperationResult, type YieldParams, type YieldPayoutToken, type YieldPosition, type YieldPositionError, type YieldPositionRead, type YieldPositions, type YieldPushStatus, type YieldSettlement, type YieldSettlementStatus, type YieldTxResult, generateIdempotencyKey, verifyIndexerWebhookSignature, verifyWalletWebhookSignature };

package/dist/index.js

@@ -1,7 +1,7 @@
 import { randomUUID, createHmac, timingSafeEqual } from 'crypto';
 
 // src/core/version.ts
-var SDK_VERSION = "0.4.0";
+var SDK_VERSION = "0.5.0";
 
 // src/core/errors.ts
 var InfraError = class extends Error {
@@ -626,7 +626,10 @@ var TokenizationResource = class extends APIResource {
       ...rest
     });
   }
-  /** Transfers token units between holder addresses. */
+  /**
+   * Transfers token units between holder addresses. A transfer that is rejected or reverts
+   * on-chain still resolves, with `status: "FAILED"`, so check `status` rather than relying on an error.
+   */
   async transferToken(params, overrides = {}) {
     const { idempotencyKey, ...rest } = overrides;
     return this.client.request({
@@ -673,7 +676,7 @@ var TokenizationResource = class extends APIResource {
     }).then((raw) => pageFromFlatResponse(raw, fetchPage));
     return fetchPage({ page: params.page, pageSize: params.pageSize });
   }
-  /** Returns a single wallet's balance of a token on a chain, plus its cNGN (payout token) balance. */
+  /** Returns a single wallet's balance of a token on a chain. For its cNGN balance, use {@link getPayoutBalance}. */
   async getWalletBalance(params, overrides = {}) {
     return this.client.request({
       method: "GET",
@@ -682,6 +685,18 @@ var TokenizationResource = class extends APIResource {
       ...overrides
     });
   }
+  /**
+   * Returns a wallet's balance of the chain's payout token (cNGN), in which coupons, yield and
+   * principal are paid. It depends only on the chain and wallet, so no token is needed.
+   */
+  async getPayoutBalance(params, overrides = {}) {
+    return this.client.request({
+      method: "GET",
+      path: "/v1/tokens/payout-balance",
+      query: { ...params },
+      ...overrides
+    });
+  }
   /** Fetches a single token transaction by its reference. */
   async getTokenTransaction(ref, overrides = {}) {
     return this.client.request({
@@ -736,7 +751,11 @@ var TokenizationResource = class extends APIResource {
       ...rest
     });
   }
-  /** Claims an investor's yield for a given distribution snapshot. */
+  /**
+   * Claims an investor's yield for a given distribution snapshot. `status` is `COMPLETED` once the
+   * claim is mined. If it's `SUBMITTED`, the outcome isn't known yet: poll
+   * {@link getTokenTransaction} with the result's `operationRef` until its `status` is `CONFIRMED` or `FAILED`.
+   */
   async claimYield(params, overrides = {}) {
     const { idempotencyKey, ...rest } = overrides;
     return this.client.request({
@@ -765,6 +784,27 @@ var TokenizationResource = class extends APIResource {
       ...overrides
     });
   }
+  /**
+   * Returns one holder's position in each of the given distribution snapshots: their share, what
+   * they've been paid and what they can still collect. Works for paused and retired tokens. A
+   * snapshot that can't be read is reported on its own entry, so check `error` on each.
+   *
+   * ```ts
+   * const { positions } = await client.tokenization.getYieldPositions({
+   *   tokenId, chainId: "84532", walletAddress, snapshotIds: [1, 2],
+   * });
+   * for (const p of positions) if (!p.error) console.log(p.snapshotId, p.settlement, p.paidAmount);
+   * ```
+   */
+  async getYieldPositions(params, overrides = {}) {
+    const { snapshotIds, ...query } = params;
+    return this.client.request({
+      method: "GET",
+      path: "/v1/tokens/yield/positions",
+      query: { ...query, snapshotIds: snapshotIds.join(",") },
+      ...overrides
+    });
+  }
   /**
    * Redeems principal to holders at maturity, paying from the cNGN deposited in the token contract.
    * Issuer-held tokens are burned without a payout so the supply can reach zero and the bond close.
@@ -786,7 +826,8 @@ var TokenizationResource = class extends APIResource {
   }
   /**
    * Returns a snapshot's unclaimed yield to the issuer once its `reclaimAfter` window has
-   * passed. An `Idempotency-Key` is generated per call unless you pass your own.
+   * passed. An `Idempotency-Key` is generated per call unless you pass your own. As with
+   * {@link claimYield}, a `SUBMITTED` status means the outcome should be polled by `operationRef`.
    */
   async reclaimUnclaimedYield(params, overrides = {}) {
     const { idempotencyKey, ...rest } = overrides;