@delopay/sdk 0.188.0 → 0.190.0

package/README.md

@@ -330,6 +330,67 @@ const all = await delopay.subscriptions.list({ limit: 20 }, opts);
 Each billing cycle raises an invoice (`sub.invoice`) with its own payment leg
 (`sub.payment`); track cycle outcomes via the subscription/invoice webhooks.
 
+**Bill on a catalog product.** Instead of the processor's `item_price_id`, name a
+recurring product of the shop (and optionally one of its prices). The server
+resolves it to the reference the billing account holds and refuses the request
+before anything is charged when the processor's price no longer matches. Check
+first which prices can start a subscription:
+
+```typescript
+const { prices } = await delopay.products.billingReadiness(['prd_pro'], profileId);
+// state: 'ready' | 'unverified' | 'other_environment' | 'needs_reference'
+
+await delopay.subscriptions.createAndConfirm(
+  { product_id: 'prd_pro', customer_id: 'cus_abc123', payment_details: { payment_method_id: pm } },
+  opts,
+);
+await delopay.subscriptions.update(sub.id, { product_id: 'prd_pro', price_id: 'prc_yearly' }, opts);
+```
+
+**Mirror the processor.** `subscriptions.sync({ subscription_ids })` (1 to 50) and
+`subscriptions.syncOne(id)` read subscriptions back from the processor and mirror
+what it reports; nothing is written there.
+
+**Take existing processor subscriptions over.** `subscriptions.importPreview`
+lists what a billing account holds and classifies each row; `importApply` adopts
+up to 25 of them. Word `capabilities.reason_code` and each row's `note_code`
+yourself; the English `reason` / `note` beside them are for API callers.
+
+```typescript
+const preview = await delopay.subscriptions.importPreview({ merchant_connector_id: mca }, opts);
+
+if (!preview.capabilities.listing || !preview.capabilities.adoption) {
+  // PayPal cannot be listed (`reason_code: 'listing_unsupported'`); an
+  // account may list without allowing adoption. Say why, and stop.
+  showUnavailable(preview.capabilities.reason_code);
+} else {
+  // Rows whose buyer is already a DeloPay customer can be taken over as they
+  // are; `needs_customer` rows need a customer named first.
+  const picks = preview.items.flatMap((row) =>
+    row.classification === 'new' && row.customer_id
+      ? [{ external_subscription_id: row.external_subscription_id, customer_id: row.customer_id }]
+      : [],
+  );
+  // The route takes 1 to 25 selections: send nothing when there is nothing
+  // to take over, and batch anything larger.
+  for (let i = 0; i < picks.length; i += 25) {
+    const { results } = await delopay.subscriptions.importApply(
+      { merchant_connector_id: mca, items: picks.slice(i, i + 25) },
+      opts,
+    );
+    // One result per selection: `adopted`, `already_held`, or `failed` with a `reason_code`.
+  }
+}
+```
+
+**A buyer returning from the processor's checkout** can read the subscription's
+status with the return token (`rt`) the return URL carried, from the browser:
+
+```typescript
+const session = new CheckoutSession({ merchantId, paymentId: subscriptionId });
+const { status, awaiting_processor } = await session.subscriptionReturnStatus(rt);
+```
+
 ### Platform fee rules
 
 Price the platform fee by payment method, connector, amount, currency or card

package/dist/{chunk-7M6HDH2Q.js → chunk-YNJUCISZ.js}

@@ -5036,6 +5036,25 @@ var Products = class {
       query: { ...query }
     });
   }
+  /**
+   * Which active prices of the named recurring products can start a
+   * subscription on the shop's billing processor account, in the environment
+   * the account is in now. `GET /products/billing-readiness`
+   *
+   * Reads only; subscribing still checks the processor's price before
+   * anything is billed. Unknown ids, one-time products and archived prices
+   * are left out of the answer.
+   *
+   * @param productIds - 1 to 100 product ids.
+   * @param profileId - The shop the products belong to.
+   */
+  async billingReadiness(productIds, profileId, options) {
+    return this.request("GET", "/products/billing-readiness", {
+      ...this.scoped(profileId, options),
+      // One comma-separated value, as the route reads it — not repeated keys.
+      query: { product_ids: productIds.join(",") }
+    });
+  }
   /**
    * Change a product's name, description, image, metadata or category
    * (`category_id: null` makes it uncategorized).
@@ -5685,6 +5704,31 @@ var Subscriptions = class {
       ...options
     });
   }
+  /**
+   * {@link getItems}, with whether the list is only the first part of what the
+   * processor holds. `GET /subscriptions/items`
+   *
+   * The backend states that in the `X-Delopay-Items-Truncated` response
+   * header (Stripe Billing lists its first 100 products), which the plain
+   * {@link getItems} cannot return. Without `limit` and `offset` every item
+   * the billing account offers is listed, up to 500.
+   */
+  async getItemsPage(params, options) {
+    let truncated = false;
+    const items = await this.request(
+      "GET",
+      "/subscriptions/items",
+      {
+        query: params,
+        ...options,
+        onDownloadProgress: (event) => {
+          truncated = event.headers.get("x-delopay-items-truncated")?.toLowerCase() === "true";
+          options?.onDownloadProgress?.(event);
+        }
+      }
+    );
+    return { items, truncated };
+  }
   /**
    * Pause a subscription. `POST /subscriptions/{subscriptionId}/pause`
    *
@@ -5705,13 +5749,64 @@ var Subscriptions = class {
       ...options
     });
   }
-  /** Cancel a subscription. `POST /subscriptions/{subscriptionId}/cancel` */
+  /**
+   * Cancel a subscription. `POST /subscriptions/{subscriptionId}/cancel`
+   *
+   * A subscription in a state it cannot be cancelled from is refused with
+   * `DE_11`; `error.data.reason` then names why (`SubscriptionActionRefusal`).
+   */
   async cancel(subscriptionId, params, options) {
     return this.request("POST", `/subscriptions/${encodeURIComponent(subscriptionId)}/cancel`, {
       body: params ?? {},
       ...options
     });
   }
+  /**
+   * Read 1 to 50 subscriptions back from their billing processor and mirror
+   * what it reports. `POST /subscriptions/sync`
+   *
+   * Nothing is written at the processor. A status is mirrored only with the
+   * time the processor stamped it with, and never over a newer event already
+   * recorded; a plan only with its own stamp. One result per id, in request
+   * order; one that fails does not stop the others.
+   */
+  async sync(params, options) {
+    return this.request("POST", "/subscriptions/sync", { body: params, ...options });
+  }
+  /**
+   * Read one subscription back from its billing processor and mirror what it
+   * reports, as {@link sync} does, with what the processor reported beside
+   * what the mirror now holds. `POST /subscriptions/{subscriptionId}/sync`
+   */
+  async syncOne(subscriptionId, options) {
+    return this.request("POST", `/subscriptions/${encodeURIComponent(subscriptionId)}/sync`, {
+      ...options
+    });
+  }
+  /**
+   * List the subscriptions a billing account holds at its processor, and how
+   * each relates to DeloPay's: already held, new (its buyer is a DeloPay
+   * customer), needing a customer, ended, or not adoptable here.
+   * `POST /subscriptions/import/preview`
+   *
+   * Reads only; nothing is written here or at the processor. Creem and
+   * Stripe Billing can be listed; PayPal cannot, which `capabilities` states
+   * (`reason_code: 'listing_unsupported'`).
+   */
+  async importPreview(params, options) {
+    return this.request("POST", "/subscriptions/import/preview", { body: params, ...options });
+  }
+  /**
+   * Take 1 to 25 processor subscriptions over, each through {@link adopt}
+   * with every one of its checks, one after another.
+   * `POST /subscriptions/import/apply`
+   *
+   * One result per selection, in request order; one refused does not stop
+   * the others.
+   */
+  async importApply(params, options) {
+    return this.request("POST", "/subscriptions/import/apply", { body: params, ...options });
+  }
   /**
    * Resolve which of the given payments were raised by a subscription.
    * `POST /subscriptions/payments/lookup`
@@ -9971,6 +10066,38 @@ var CheckoutSession = class {
       }
     );
   }
+  /**
+   * The status a buyer coming back from the processor's checkout may read:
+   * the subscription's status, and whether the processor has reported it yet
+   * (`awaiting_processor`). Construct the session with the `sub_…` id in the
+   * `paymentId` slot.
+   *
+   * Authenticated with the return token (`rt`) the return URL carried, sent as
+   * `Authorization: Bearer <rt>`. That token reads only this, for a day; it is
+   * never the client secret, which this call does not send.
+   *
+   * `GET /subscriptions/return-status/{merchantId}/{subscriptionId}`
+   */
+  async subscriptionReturnStatus(returnToken, options) {
+    if (!returnToken) {
+      throw new DelopayError("This call requires the return token (rt) from the return URL", {
+        status: 0,
+        code: "MISSING_CREDENTIAL",
+        type: "invalid_request"
+      });
+    }
+    return this.client.request(
+      "GET",
+      `/subscriptions/return-status/${encodeURIComponent(this.merchantId)}/${encodeURIComponent(this.paymentId)}`,
+      {
+        ...options,
+        headers: {
+          ...withoutCredentialHeaders(options?.headers),
+          Authorization: `Bearer ${returnToken}`
+        }
+      }
+    );
+  }
   /**
    * Confirm a subscription (PayPal approval rail). The client secret is
    * attached automatically; the shop's profile id travels as the
@@ -10938,4 +11065,4 @@ export {
   decodeNativePanes,
   encodeNativePanes
 };
-//# sourceMappingURL=chunk-7M6HDH2Q.js.map
+//# sourceMappingURL=chunk-YNJUCISZ.js.map