@uengage.io/platform-sdk 2.1.0 → 2.3.0

package/dist/wallet/client.d.ts

@@ -1,5 +1,5 @@
 import { type PlatformAuth, type PlatformAuthInput, type PlatformConfigInput } from '../config';
-import type { CreditInput, Currency, DebitInput, GetWalletOptions, ListTransactionsFilter, TransactionPage, TransactionResult, WalletBalance, WalletInstance, WalletTransaction } from './schema';
+import type { CreditEvent, CreditInput, CreditLine, CreditUtilisationFilter, CreditUtilisationPage, Currency, DebitInput, GetWalletOptions, ListCreditEventsFilter, ListTransactionsFilter, ReverseSettlementInput, SetCreditLimitInput, SetCreditLimitResult, SettleInvoiceInput, SettleInvoiceResult, TransactionPage, TransactionResult, WalletBalance, WalletInstance, WalletOverview, WalletTransaction } from './schema';
 /**
  * A handle to one business wallet. Cheap to create — `getWallet(...)`
  * does no I/O. The wallet is resolved server-side on the first
@@ -7,6 +7,23 @@ import type { CreditInput, Currency, DebitInput, GetWalletOptions, ListTransacti
  * surface from the operation, not from `getWallet()`.
  */
 export interface Wallet {
+    /**
+     * WHICH MODEL IS THIS MERCHANT ON — call this first.
+     *
+     * Returns a discriminated union on `mode`, so a dashboard settles
+     * "wallet balance or credit line?" from a value rather than by
+     * catching a 404, and TypeScript narrows the rest for you:
+     *
+     * ```ts
+     * const o = await wallet.getOverview();
+     * if (o.mode === 'credit') renderCreditWidget(o.creditLine);
+     * else renderWalletPanel(o.balance);
+     * ```
+     *
+     * One request for a prepaid merchant, two for a credit one, and never
+     * a 404 on the happy path — see the implementation for why that order.
+     */
+    getOverview(): Promise<WalletOverview>;
     /** GET /v1/wallet/balance — resolves the wallet and returns its balance + currency. */
     getBalance(): Promise<WalletBalance>;
     /** GET /v1/wallet/instance — wallet identity + currency, without the balance. */
@@ -29,6 +46,39 @@ export interface Wallet {
     listTransactions(filter?: ListTransactionsFilter): Promise<TransactionPage>;
     /** GET /v1/wallet/transactions/:id — scoped to this wallet. */
     getTransaction(id: string): Promise<WalletTransaction>;
+    /**
+     * GET /v1/wallet/credit — everything the merchant widget renders.
+     * Throws `CreditLineNotFoundError` (404) when the merchant is not on
+     * the credit line, which is the normal state for a prepaid merchant.
+     * Requires `wallet.credit:read`.
+     */
+    getCreditLine(): Promise<CreditLine>;
+    /**
+     * GET /v1/wallet/credit/events — the limit-change and settlement
+     * trail, newest first. Requires `wallet.credit:read`.
+     *
+     * Pass a `limit` to widen the page: the service defaults to 50, which
+     * a merchant on the line for a year will have outgrown.
+     */
+    listCreditEvents(filter?: ListCreditEventsFilter): Promise<CreditEvent[]>;
+    /**
+     * PUT /v1/wallet/credit/limit — set the limit, creating the credit
+     * line on first use. Consumption is never touched, so raising a limit
+     * hands back exactly the difference. Requires `wallet.credit:write`.
+     */
+    setCreditLimit(input: SetCreditLimitInput): Promise<SetCreditLimitResult>;
+    /**
+     * POST /v1/wallet/credit/settlements — release the credit an invoice
+     * was holding, on payment IN FULL. Releases the invoice's net figure;
+     * see `SettleInvoiceInput.netMinor`. Requires `wallet.credit:settle`.
+     */
+    settleInvoice(input: SettleInvoiceInput): Promise<SettleInvoiceResult>;
+    /**
+     * POST /v1/wallet/credit/settlements/reversal — undo a settlement
+     * recorded in error, re-holding exactly what it released. Requires
+     * `wallet.credit:settle`.
+     */
+    reverseSettlement(input: ReverseSettlementInput): Promise<SettleInvoiceResult>;
 }
 export interface WalletClient {
     config(input: PlatformConfigInput): WalletClient;
@@ -39,6 +89,16 @@ export interface WalletClient {
      * `wallet.*` scope for the operations on the returned handle.
      */
     getWallet(opts: GetWalletOptions): Wallet;
+    /**
+     * GET /v1/wallet/credit/utilisation — every merchant on the credit
+     * line, most-utilised first.
+     *
+     * On the client rather than on a wallet handle because it is the one
+     * wallet operation that is not scoped to a business, and it carries
+     * its own capability (`wallet.credit:list`) for the same reason: it is
+     * a materially broader grant than reading one merchant's line.
+     */
+    getCreditUtilisation(filter?: CreditUtilisationFilter): Promise<CreditUtilisationPage>;
 }
 export declare class WalletApiError extends Error {
     readonly status: number;
@@ -79,4 +139,148 @@ export declare class UnresolvableWalletError extends WalletApiError {
 export declare class WalletNotFoundError extends WalletApiError {
     constructor(body: string);
 }
+/**
+ * The charge would exceed the merchant's credit limit; nothing was moved
+ * (HTTP 409).
+ *
+ * Distinct from `InsufficientBalanceError` because the merchant's next
+ * step is different — settle an invoice or talk to their account
+ * manager, not top up. The figures also separate two cases that share
+ * this error and need different copy:
+ *
+ *   - `availableMinor === 0` — the limit is used up.
+ *   - `availableMinor > 0` — this one charge is larger than what is
+ *     left, which can happen at any utilisation. Telling that merchant
+ *     their "credit limit is reached" would be wrong.
+ *   - `availableMinor === undefined` — the response carried no figures
+ *     (a trimmed or proxied body). Fall back to generic copy; do not
+ *     read it as zero, which is the sentinel above.
+ *
+ * And a third the fields cannot distinguish on their own: consumption
+ * spans months, so a merchant can be at their ceiling purely because
+ * older invoices are unpaid. `getCreditLine()` tells you which.
+ */
+export declare class CreditLimitReachedError extends WalletApiError {
+    readonly limitMinor?: number;
+    readonly consumedMinor?: number;
+    readonly availableMinor?: number;
+    readonly requestedMinor?: number;
+    constructor(figures: {
+        limitMinor?: number;
+        consumedMinor?: number;
+        availableMinor?: number;
+        requestedMinor?: number;
+    }, body: string);
+}
+/**
+ * A charge on a credit-line merchant arrived without its GST split
+ * (HTTP 400).
+ *
+ * Consumption is tracked net of GST, so `breakup` is required rather
+ * than a rate being inferred. If you hit this, the caller is sending
+ * gross-only amounts and needs to send `breakup` — the same split it
+ * almost certainly already computes.
+ */
+export declare class CreditBreakupRequiredError extends WalletApiError {
+    constructor(body: string);
+}
+/** `allowNegative` was passed for a credit-line merchant (HTTP 400). */
+export declare class CreditOverrideRefusedError extends WalletApiError {
+    constructor(body: string);
+}
+/**
+ * A re-settlement changed an invoice's figures without saying why
+ * (HTTP 400).
+ *
+ * Re-settling a REVERSED invoice with different figures is how a settled
+ * amount is corrected, so the service does not refuse it the way it
+ * refuses a conflicting first settlement. But it releases against the
+ * merchant's whole outstanding consumption rather than the invoice's own
+ * amount, so a mistyped figure can hand back far more than the invoice
+ * held — and a deliberate correction can say what it is correcting where
+ * a replayed webhook cannot. Pass `reason` and retry. Re-settling with
+ * the SAME figures needs none.
+ */
+export declare class CreditCorrectionReasonRequiredError extends WalletApiError {
+    /** What the invoice was previously settled for, in minor units. */
+    readonly previousNetMinor: number | undefined;
+    constructor(
+    /** What the invoice was previously settled for, in minor units. */
+    previousNetMinor: number | undefined, body: string);
+}
+/**
+ * A limit change named a currency the credit line is not denominated in
+ * (HTTP 409).
+ *
+ * The line's currency is fixed when it is created, because it sets the
+ * exponent every stored figure is already scaled by — changing it would
+ * re-denominate the limit and the consumption without touching either
+ * number. Re-denominating a live line is a migration, not a field
+ * update, so this is not something a caller can retry past: send the
+ * currency the line already carries.
+ */
+export declare class CreditCurrencyConflictError extends WalletApiError {
+    readonly storedCurrency: string | undefined;
+    readonly requestedCurrency: string | undefined;
+    constructor(storedCurrency: string | undefined, requestedCurrency: string | undefined, body: string);
+}
+/**
+ * The merchant's credit line and the wallet the charge routed to are in
+ * different currencies (HTTP 409).
+ *
+ * `amountMinor` and `breakup` carry no currency of their own — they are
+ * read with the exponent of the resolved wallet — so when the two
+ * disagree there is no reading of them that is right for both, and the
+ * service refuses rather than mis-scaling by a factor of ten or a
+ * hundred. Not caller-fixable: it means the merchant's routing and their
+ * credit line disagree, which is an ops/data problem.
+ */
+export declare class CreditCurrencyMismatchError extends WalletApiError {
+    constructor(body: string);
+}
+/**
+ * A plain top-up was sent for a credit-line merchant (HTTP 400).
+ *
+ * These merchants have no balance to top up: `wallet_balance` is the
+ * fiction the credit line replaces and is deliberately frozen, so the
+ * write would move nothing while appearing to succeed. Credit is handed
+ * back by settling an invoice (`settleInvoice`), never by crediting the
+ * wallet. A genuine refund is accepted — send it as `reversalOf` or
+ * `isRefund` and it releases the credit the original charge consumed.
+ */
+export declare class CreditTopUpRefusedError extends WalletApiError {
+    constructor(body: string);
+}
+/**
+ * The merchant is not on the credit line (HTTP 404).
+ *
+ * The normal state for a prepaid merchant, so a widget should treat it
+ * as "show the wallet balance instead", not as an error.
+ */
+export declare class CreditLineNotFoundError extends WalletApiError {
+    constructor(body: string);
+}
+/**
+ * `enabled: false` was refused because the merchant still owes for the
+ * credit line (HTTP 409).
+ *
+ * Disabling moves a merchant back to a wallet balance, and doing that
+ * with consumption outstanding abandons it. Show `consumedMinor` and
+ * tell the operator to settle first — or, if the intent was to stop the
+ * merchant trading rather than to move them off the model, set
+ * `limitMinor: 0`, which blocks every charge and keeps the balance.
+ */
+export declare class CreditLineHasOutstandingError extends WalletApiError {
+    readonly consumedMinor: number;
+    readonly gstAccruedMinor: number;
+    constructor(consumedMinor: number, gstAccruedMinor: number, body: string);
+}
+/** A limit `referenceId` or an invoice was reused for different figures (HTTP 409). */
+export declare class CreditIdempotencyConflictError extends WalletApiError {
+    constructor(body: string);
+}
+/** No settlement to reverse for that invoice (HTTP 404). */
+export declare class SettlementNotFoundError extends WalletApiError {
+    constructor(body: string);
+}
 export declare function createWalletClient(input?: PlatformConfigInput): WalletClient;