infra-sdk-typescript 0.3.0 → 0.4.0

package/dist/index.d.cts

@@ -352,7 +352,7 @@ 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">;
+type TokenTransactionType = LooseUnion<"MINT" | "BURN" | "TRANSFER" | "DEPLOY" | "REDEEM" | "SNAPSHOT" | "FORCED_TRANSFER">;
 type TokenTransactionStatus = LooseUnion<"PENDING" | "CONFIRMED" | "FAILED">;
 /**
  * Chain id a token is deployed on, e.g. `84532` (Base Sepolia). The API accepts it as a number
@@ -566,6 +566,8 @@ 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 ListTokenTransactionsParams {
     tokenId?: string;
@@ -616,6 +618,7 @@ interface UpdateYieldResult {
     currentRate: number;
     /** Annual rate after the update, as a percentage. */
     newRate: number;
+    operationRef: string;
     txHash: string;
 }
 interface DistributeYieldParams {
@@ -654,12 +657,89 @@ interface RedeemPrincipalParams {
     tokenId: string;
     chainId: TokenChainId;
 }
-/** Result of {@link TokenizationResource.redeemPrincipal} — one transaction per redemption payout. */
+/**
+ * Why a holder was left out of a redemption. Their principal is still owed once the cause is resolved.
+ *
+ * - `NOT_VERIFIED` — not KYC-verified in the token's identity registry.
+ * - `FROZEN` — the wallet is frozen.
+ * - `NOT_ALLOWLISTED` — removed from the compliance allowlist.
+ * - `SKIPPED_BY_CONTRACT` — eligible when read, but the contract skipped it when the batch executed
+ *   (e.g. it became ineligible in between).
+ */
+type RedemptionSkipReason = LooseUnion<"NOT_VERIFIED" | "FROZEN" | "NOT_ALLOWLISTED" | "SKIPPED_BY_CONTRACT">;
+/** A holder {@link TokenizationResource.redeemPrincipal} did not redeem. */
+interface RedemptionSkippedHolder {
+    address: string;
+    /** Unredeemed balance in the token's smallest unit, as an integer string. */
+    balance: string;
+    reasons: RedemptionSkipReason[];
+}
+/** Result of {@link TokenizationResource.redeemPrincipal}. */
 interface RedeemPrincipalResult {
     tokenId: string;
     operationRef: string;
+    /** Transaction records created by this run: the issuer-token burn (if any), then one per redemption batch. */
     transactionIds: string[];
+    /** Hashes in send order: the burn, each batch, then the seal that marks the principal repaid (if one was needed). */
     txHashes: string[];
+    /** Holders actually paid, from the contract's `PrincipalRedeemed` events. */
+    redeemedHolders: number;
+    /** Principal actually paid, in cNGN base units (6 decimals), as an integer string. */
+    paidPrincipal: string;
+    /** {@link paidPrincipal} as a decimal cNGN string, e.g. `"100000.0"`. */
+    paidPrincipalFormatted: string;
+    /**
+     * Indexes of batches whose receipt couldn't be read. Their transactions landed, but their paid amounts
+     * are the pre-transaction estimate rather than the on-chain events.
+     */
+    unreconciledBatches: number[];
+    /** Holders that were not redeemed, with their balances and why. */
+    skipped: RedemptionSkippedHolder[];
+    /** Issuer-held (treasury) tokens burned without a payout, or `null` when there were none. Frozen tokens are never burned. */
+    treasuryBurned: {
+        amount: string;
+        txHash: string;
+    } | null;
+    /** Supply left after the run, in the token's smallest unit, as an integer string. */
+    outstandingSupply: string;
+    /**
+     * `true` once supply is zero and the bond is marked principal-repaid. While `false`, the remaining
+     * supply belongs to {@link skipped} holders, frozen issuer tokens or the yield distributor.
+     */
+    closed: boolean;
+}
+interface GetNextCouponParams {
+    tokenId: string;
+    chainId: TokenChainId;
+}
+/**
+ * Where a bond stands on its coupon schedule.
+ *
+ * - `SCHEDULED` — the next coupon isn't due yet.
+ * - `DUE` — the coupon can be paid now with {@link TokenizationResource.payCoupon}.
+ * - `GRACE_EXPIRED` — the coupon was missed and its grace period has passed; it is still payable,
+ *   but anyone can now flag the bond as defaulted.
+ * - `DEFAULTED` — the bond is in default; no further coupons can be scheduled.
+ * - `NO_MORE_COUPONS` — the schedule has run past maturity; only principal redemption remains.
+ * - `CLOSED` — principal has been repaid and the bond is closed.
+ */
+type NextCouponStatus = LooseUnion<"SCHEDULED" | "DUE" | "GRACE_EXPIRED" | "DEFAULTED" | "NO_MORE_COUPONS" | "CLOSED">;
+/** Result of {@link TokenizationResource.getNextCoupon}. Dates are ISO 8601 strings in UTC. */
+interface NextCoupon {
+    tokenId: string;
+    chainId: string;
+    status: NextCouponStatus;
+    /** When the next coupon falls due. `null` once there are no more coupons (`NO_MORE_COUPONS` or `CLOSED`). */
+    nextCouponDate: string | null;
+    /** `nextCouponDate` plus the bond's grace period; after this a missed coupon allows a default. `null` with it. */
+    graceEndsAt: string | null;
+    /** `true` when a coupon can be paid now (`DUE` or `GRACE_EXPIRED`). */
+    isDue: boolean;
+    /** Seconds between coupons. */
+    couponPeriodSeconds: number;
+    maturityDate: string;
+    /** Coupon paid per whole token, in cNGN, as a decimal string. */
+    couponPerToken: string;
 }
 interface ReclaimUnclaimedYieldParams {
     tokenId: string;
@@ -679,6 +759,7 @@ interface ReclaimUnclaimedYieldResult {
 }
 /** Result of {@link TokenizationResource.claimYield}. */
 interface YieldTxResult {
+    operationRef: string;
     txHash: string;
 }
 /** Result of {@link TokenizationResource.distributeYield} / {@link TokenizationResource.payCoupon}. */
@@ -730,21 +811,43 @@ 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. */
+    /** Returns a single wallet's balance of a token on a chain, plus its cNGN (payout token) balance. */
     getWalletBalance(params: GetWalletBalanceParams, overrides?: RequestOverrides): Promise<TokenWalletBalance>;
     /** Fetches a single token transaction by its reference. */
     getTokenTransaction(ref: string, overrides?: RequestOverrides): Promise<TokenTransactionRecord>;
     /** Returns token transactions, optionally filtered by token. */
     listTokenTransactions(params?: ListTokenTransactionsParams, overrides?: RequestOverrides): Promise<Page<TokenTransactionRecord>>;
-    /** Updates the annual yield rate for a yield-bearing token. */
-    updateYield(params: UpdateTokenYieldParams, overrides?: RequestOverrides): Promise<UpdateYieldResult>;
+    /**
+     * Updates the annual yield rate for a yield-bearing token. An `Idempotency-Key` is generated
+     * per call unless you pass your own.
+     */
+    updateYield(params: UpdateTokenYieldParams, overrides?: IdempotentRequestOverrides): Promise<UpdateYieldResult>;
     /** Funds and distributes a yield payout to holders. Unclaimed funds may be reclaimed after `reclaimAfter`. */
     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. */
     claimYield(params: ClaimYieldParams, overrides?: IdempotentRequestOverrides): Promise<YieldTxResult>;
-    /** Redeems principal to holders at maturity. */
+    /**
+     * Returns the bond's next coupon date and where it stands on its schedule. Whether a coupon is
+     * due is decided by the chain's clock, not yours, so check `status` (or `isDue`) rather than
+     * comparing `nextCouponDate` with local time. Works for paused tokens too.
+     *
+     * ```ts
+     * const next = await client.tokenization.getNextCoupon({ tokenId, chainId: "84532" });
+     * if (next.status === "DUE") await client.tokenization.payCoupon({ tokenId, chainId: "84532", ... });
+     * ```
+     */
+    getNextCoupon(params: GetNextCouponParams, overrides?: RequestOverrides): Promise<NextCoupon>;
+    /**
+     * 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.
+     * Holders that can't be redeemed (frozen, unverified, not allowlisted) are left alone and listed in
+     * `skipped`; check `closed` to see whether the bond is done.
+     *
+     * If a run fails part-way, call it again: holders already redeemed are skipped, so it carries on
+     * where it stopped. Reusing the same `idempotencyKey` only replays the earlier response.
+     */
     redeemPrincipal(params: RedeemPrincipalParams, overrides?: IdempotentRequestOverrides): Promise<RedeemPrincipalResult>;
     /**
      * Returns a snapshot's unclaimed yield to the issuer once its `reclaimAfter` window has
@@ -1005,4 +1108,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 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, NotFoundError, type OffsetPaginatedResponse, Page, type PayCouponParams, PaymentRequiredError, PermissionDeniedError, type QueryValue, RateLimitError, type ReclaimUnclaimedYieldParams, type ReclaimUnclaimedYieldResult, type RedeemPrincipalParams, type RedeemPrincipalResult, 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 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 };

package/dist/index.d.ts

@@ -352,7 +352,7 @@ 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">;
+type TokenTransactionType = LooseUnion<"MINT" | "BURN" | "TRANSFER" | "DEPLOY" | "REDEEM" | "SNAPSHOT" | "FORCED_TRANSFER">;
 type TokenTransactionStatus = LooseUnion<"PENDING" | "CONFIRMED" | "FAILED">;
 /**
  * Chain id a token is deployed on, e.g. `84532` (Base Sepolia). The API accepts it as a number
@@ -566,6 +566,8 @@ 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 ListTokenTransactionsParams {
     tokenId?: string;
@@ -616,6 +618,7 @@ interface UpdateYieldResult {
     currentRate: number;
     /** Annual rate after the update, as a percentage. */
     newRate: number;
+    operationRef: string;
     txHash: string;
 }
 interface DistributeYieldParams {
@@ -654,12 +657,89 @@ interface RedeemPrincipalParams {
     tokenId: string;
     chainId: TokenChainId;
 }
-/** Result of {@link TokenizationResource.redeemPrincipal} — one transaction per redemption payout. */
+/**
+ * Why a holder was left out of a redemption. Their principal is still owed once the cause is resolved.
+ *
+ * - `NOT_VERIFIED` — not KYC-verified in the token's identity registry.
+ * - `FROZEN` — the wallet is frozen.
+ * - `NOT_ALLOWLISTED` — removed from the compliance allowlist.
+ * - `SKIPPED_BY_CONTRACT` — eligible when read, but the contract skipped it when the batch executed
+ *   (e.g. it became ineligible in between).
+ */
+type RedemptionSkipReason = LooseUnion<"NOT_VERIFIED" | "FROZEN" | "NOT_ALLOWLISTED" | "SKIPPED_BY_CONTRACT">;
+/** A holder {@link TokenizationResource.redeemPrincipal} did not redeem. */
+interface RedemptionSkippedHolder {
+    address: string;
+    /** Unredeemed balance in the token's smallest unit, as an integer string. */
+    balance: string;
+    reasons: RedemptionSkipReason[];
+}
+/** Result of {@link TokenizationResource.redeemPrincipal}. */
 interface RedeemPrincipalResult {
     tokenId: string;
     operationRef: string;
+    /** Transaction records created by this run: the issuer-token burn (if any), then one per redemption batch. */
     transactionIds: string[];
+    /** Hashes in send order: the burn, each batch, then the seal that marks the principal repaid (if one was needed). */
     txHashes: string[];
+    /** Holders actually paid, from the contract's `PrincipalRedeemed` events. */
+    redeemedHolders: number;
+    /** Principal actually paid, in cNGN base units (6 decimals), as an integer string. */
+    paidPrincipal: string;
+    /** {@link paidPrincipal} as a decimal cNGN string, e.g. `"100000.0"`. */
+    paidPrincipalFormatted: string;
+    /**
+     * Indexes of batches whose receipt couldn't be read. Their transactions landed, but their paid amounts
+     * are the pre-transaction estimate rather than the on-chain events.
+     */
+    unreconciledBatches: number[];
+    /** Holders that were not redeemed, with their balances and why. */
+    skipped: RedemptionSkippedHolder[];
+    /** Issuer-held (treasury) tokens burned without a payout, or `null` when there were none. Frozen tokens are never burned. */
+    treasuryBurned: {
+        amount: string;
+        txHash: string;
+    } | null;
+    /** Supply left after the run, in the token's smallest unit, as an integer string. */
+    outstandingSupply: string;
+    /**
+     * `true` once supply is zero and the bond is marked principal-repaid. While `false`, the remaining
+     * supply belongs to {@link skipped} holders, frozen issuer tokens or the yield distributor.
+     */
+    closed: boolean;
+}
+interface GetNextCouponParams {
+    tokenId: string;
+    chainId: TokenChainId;
+}
+/**
+ * Where a bond stands on its coupon schedule.
+ *
+ * - `SCHEDULED` — the next coupon isn't due yet.
+ * - `DUE` — the coupon can be paid now with {@link TokenizationResource.payCoupon}.
+ * - `GRACE_EXPIRED` — the coupon was missed and its grace period has passed; it is still payable,
+ *   but anyone can now flag the bond as defaulted.
+ * - `DEFAULTED` — the bond is in default; no further coupons can be scheduled.
+ * - `NO_MORE_COUPONS` — the schedule has run past maturity; only principal redemption remains.
+ * - `CLOSED` — principal has been repaid and the bond is closed.
+ */
+type NextCouponStatus = LooseUnion<"SCHEDULED" | "DUE" | "GRACE_EXPIRED" | "DEFAULTED" | "NO_MORE_COUPONS" | "CLOSED">;
+/** Result of {@link TokenizationResource.getNextCoupon}. Dates are ISO 8601 strings in UTC. */
+interface NextCoupon {
+    tokenId: string;
+    chainId: string;
+    status: NextCouponStatus;
+    /** When the next coupon falls due. `null` once there are no more coupons (`NO_MORE_COUPONS` or `CLOSED`). */
+    nextCouponDate: string | null;
+    /** `nextCouponDate` plus the bond's grace period; after this a missed coupon allows a default. `null` with it. */
+    graceEndsAt: string | null;
+    /** `true` when a coupon can be paid now (`DUE` or `GRACE_EXPIRED`). */
+    isDue: boolean;
+    /** Seconds between coupons. */
+    couponPeriodSeconds: number;
+    maturityDate: string;
+    /** Coupon paid per whole token, in cNGN, as a decimal string. */
+    couponPerToken: string;
 }
 interface ReclaimUnclaimedYieldParams {
     tokenId: string;
@@ -679,6 +759,7 @@ interface ReclaimUnclaimedYieldResult {
 }
 /** Result of {@link TokenizationResource.claimYield}. */
 interface YieldTxResult {
+    operationRef: string;
     txHash: string;
 }
 /** Result of {@link TokenizationResource.distributeYield} / {@link TokenizationResource.payCoupon}. */
@@ -730,21 +811,43 @@ 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. */
+    /** Returns a single wallet's balance of a token on a chain, plus its cNGN (payout token) balance. */
     getWalletBalance(params: GetWalletBalanceParams, overrides?: RequestOverrides): Promise<TokenWalletBalance>;
     /** Fetches a single token transaction by its reference. */
     getTokenTransaction(ref: string, overrides?: RequestOverrides): Promise<TokenTransactionRecord>;
     /** Returns token transactions, optionally filtered by token. */
     listTokenTransactions(params?: ListTokenTransactionsParams, overrides?: RequestOverrides): Promise<Page<TokenTransactionRecord>>;
-    /** Updates the annual yield rate for a yield-bearing token. */
-    updateYield(params: UpdateTokenYieldParams, overrides?: RequestOverrides): Promise<UpdateYieldResult>;
+    /**
+     * Updates the annual yield rate for a yield-bearing token. An `Idempotency-Key` is generated
+     * per call unless you pass your own.
+     */
+    updateYield(params: UpdateTokenYieldParams, overrides?: IdempotentRequestOverrides): Promise<UpdateYieldResult>;
     /** Funds and distributes a yield payout to holders. Unclaimed funds may be reclaimed after `reclaimAfter`. */
     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. */
     claimYield(params: ClaimYieldParams, overrides?: IdempotentRequestOverrides): Promise<YieldTxResult>;
-    /** Redeems principal to holders at maturity. */
+    /**
+     * Returns the bond's next coupon date and where it stands on its schedule. Whether a coupon is
+     * due is decided by the chain's clock, not yours, so check `status` (or `isDue`) rather than
+     * comparing `nextCouponDate` with local time. Works for paused tokens too.
+     *
+     * ```ts
+     * const next = await client.tokenization.getNextCoupon({ tokenId, chainId: "84532" });
+     * if (next.status === "DUE") await client.tokenization.payCoupon({ tokenId, chainId: "84532", ... });
+     * ```
+     */
+    getNextCoupon(params: GetNextCouponParams, overrides?: RequestOverrides): Promise<NextCoupon>;
+    /**
+     * 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.
+     * Holders that can't be redeemed (frozen, unverified, not allowlisted) are left alone and listed in
+     * `skipped`; check `closed` to see whether the bond is done.
+     *
+     * If a run fails part-way, call it again: holders already redeemed are skipped, so it carries on
+     * where it stopped. Reusing the same `idempotencyKey` only replays the earlier response.
+     */
     redeemPrincipal(params: RedeemPrincipalParams, overrides?: IdempotentRequestOverrides): Promise<RedeemPrincipalResult>;
     /**
      * Returns a snapshot's unclaimed yield to the issuer once its `reclaimAfter` window has
@@ -1005,4 +1108,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 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, NotFoundError, type OffsetPaginatedResponse, Page, type PayCouponParams, PaymentRequiredError, PermissionDeniedError, type QueryValue, RateLimitError, type ReclaimUnclaimedYieldParams, type ReclaimUnclaimedYieldResult, type RedeemPrincipalParams, type RedeemPrincipalResult, 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 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 };

package/dist/index.js

@@ -1,7 +1,7 @@
 import { randomUUID, createHmac, timingSafeEqual } from 'crypto';
 
 // src/core/version.ts
-var SDK_VERSION = "0.1.0";
+var SDK_VERSION = "0.4.0";
 
 // src/core/errors.ts
 var InfraError = class extends Error {
@@ -673,7 +673,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. */
+  /** Returns a single wallet's balance of a token on a chain, plus its cNGN (payout token) balance. */
   async getWalletBalance(params, overrides = {}) {
     return this.client.request({
       method: "GET",
@@ -700,13 +700,18 @@ var TokenizationResource = class extends APIResource {
     }).then((raw) => pageFromFlatResponse(raw, fetchPage));
     return fetchPage({ page: params.page, pageSize: params.pageSize });
   }
-  /** Updates the annual yield rate for a yield-bearing token. */
+  /**
+   * Updates the annual yield rate for a yield-bearing token. An `Idempotency-Key` is generated
+   * per call unless you pass your own.
+   */
   async updateYield(params, overrides = {}) {
+    const { idempotencyKey, ...rest } = overrides;
     return this.client.request({
       method: "PATCH",
       path: "/v1/tokens/yield",
       body: params,
-      ...overrides
+      idempotencyKey: idempotencyKey ?? generateIdempotencyKey(),
+      ...rest
     });
   }
   /** Funds and distributes a yield payout to holders. Unclaimed funds may be reclaimed after `reclaimAfter`. */
@@ -742,7 +747,33 @@ var TokenizationResource = class extends APIResource {
       ...rest
     });
   }
-  /** Redeems principal to holders at maturity. */
+  /**
+   * Returns the bond's next coupon date and where it stands on its schedule. Whether a coupon is
+   * due is decided by the chain's clock, not yours, so check `status` (or `isDue`) rather than
+   * comparing `nextCouponDate` with local time. Works for paused tokens too.
+   *
+   * ```ts
+   * const next = await client.tokenization.getNextCoupon({ tokenId, chainId: "84532" });
+   * if (next.status === "DUE") await client.tokenization.payCoupon({ tokenId, chainId: "84532", ... });
+   * ```
+   */
+  async getNextCoupon(params, overrides = {}) {
+    return this.client.request({
+      method: "GET",
+      path: "/v1/tokens/yield/next-coupon",
+      query: { ...params },
+      ...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.
+   * Holders that can't be redeemed (frozen, unverified, not allowlisted) are left alone and listed in
+   * `skipped`; check `closed` to see whether the bond is done.
+   *
+   * If a run fails part-way, call it again: holders already redeemed are skipped, so it carries on
+   * where it stopped. Reusing the same `idempotencyKey` only replays the earlier response.
+   */
   async redeemPrincipal(params, overrides = {}) {
     const { idempotencyKey, ...rest } = overrides;
     return this.client.request({