@delopay/sdk 0.76.0 → 0.78.0

package/dist/index.cjs

@@ -1153,10 +1153,45 @@ var PaymentMethods = class {
     return this.request("DELETE", `/payment-methods/${encodeURIComponent(methodId)}`);
   }
   /**
-   * List payment methods using a client secret.
+   * List the payment methods available for a payment — the discovery endpoint a
+   * custom checkout renders its tiles from.
    *
-   * @param params - Filter by `client_secret`.
-   * @returns Array of payment methods.
+   * Callable with a publishable key plus the payment's `client_secret`, so it
+   * runs from the browser. The returned set is already filtered by country,
+   * order value and the merchant's availability rules, and each entry carries
+   * `display` (name + icon slug) and `amount_limits` (the order values it stays
+   * available for) so you do not have to maintain either alongside.
+   *
+   * This is *not* the customer's saved methods — see {@link listForCustomer}.
+   *
+   * @param params - `client_secret`, plus optional `country`, `amount` and filters.
+   * @returns The methods available for the payment, grouped by payment method.
+   *
+   * @example
+   * ```typescript
+   * const { payment_methods } = await delopay.paymentMethods.list({
+   *   client_secret: 'pay_abc_secret_xyz',
+   *   country: 'DE',
+   *   amount: 25000,
+   * });
+   *
+   * for (const group of payment_methods) {
+   *   for (const method of group.payment_method_types) {
+   *     // Re-check availability yourself as the cart total changes, instead of
+   *     // re-listing on every keystroke.
+   *     const limits = method.amount_limits;
+   *     const available =
+   *       !limits ||
+   *       ((limits.min_amount == null || cartTotal >= limits.min_amount) &&
+   *         (limits.max_amount == null || cartTotal <= limits.max_amount) &&
+   *         !limits.excluded_ranges.some(
+   *           (band) => cartTotal >= band.min_amount && cartTotal <= band.max_amount,
+   *         ));
+   *
+   *     if (available) render(method.display?.display_name, method.display?.icon_slug);
+   *   }
+   * }
+   * ```
    */
   async list(params) {
     return this.request("GET", "/payment-methods", {
@@ -1269,6 +1304,17 @@ var Payments = class {
    *   { headers: { 'Idempotency-Key': 'order_1001' } },
    * );
    * ```
+   *
+   * @example Send `test_mode` to pick the environment per payment, so a staging
+   * deploy cannot charge real cards and a forgotten processor toggle cannot
+   * swallow production traffic:
+   * ```typescript
+   * const payment = await delopay.payments.create({
+   *   amount: 5000,
+   *   currency: 'EUR',
+   *   test_mode: process.env.NODE_ENV !== 'production',
+   * });
+   * ```
    */
   async create(params, options) {
     return this.request("POST", "/payments", { body: params, ...options });