@delopay/sdk 0.34.0 → 0.35.0

package/README.md

@@ -171,6 +171,108 @@ const gateway = await delopay.shops.gateways.connect(merchantId, shop.shop_id, {
 const gateways = await delopay.shops.gateways.list(merchantId, shop.shop_id);
 ```
 
+### Subscriptions
+
+Recurring billing runs through a billing processor connected to the shop (Stripe
+Billing or PayPal). Every subscription call is **profile-scoped** — pass the
+shop's `X-Profile-Id` so the backend can resolve the billing processor (you get
+`IR_04` otherwise):
+
+```typescript
+const opts = { headers: { 'X-Profile-Id': profileId } };
+```
+
+**Browse plans and estimate cost** before creating anything:
+
+```typescript
+// List purchasable plans (or addons) with their prices
+const plans = await delopay.subscriptions.getItems({ item_type: 'plan' }, opts);
+const priceId = plans[0]?.price_id[0]?.price_id;
+
+// Preview what the customer will be charged
+const estimate = await delopay.subscriptions.getEstimate({ item_price_id: priceId }, opts);
+console.log(estimate.amount, estimate.currency, estimate.interval); // 1500 'EUR' 'Month'
+```
+
+> **Never send raw card numbers.** The subscription API rejects
+> `payment_method_data.card` with a raw PAN. Cards are collected client-side by
+> the connector's hosted fields (Stripe Elements) so the card never touches your
+> server, keeping raw card data out of your PCI scope. Confirm with a hosted
+> checkout session or a previously-saved token, as shown below.
+
+**Recommended: hosted checkout.** Create the subscription server-side, then send
+the buyer to the Delopay hosted checkout with the returned `client_secret`. The
+buyer enters their card in the connector iframe; you never handle the PAN:
+
+```typescript
+const pending = await delopay.subscriptions.create(
+  {
+    item_price_id: priceId,
+    customer_id: 'cus_abc123',
+    payment_details: { return_url: 'https://example.com/subscription/complete' },
+  },
+  opts,
+);
+
+// Redirect the buyer to the hosted checkout to enter their card.
+const checkoutUrl =
+  `https://checkout.delopay.net/pay/${merchantId}/${pending.id}` +
+  `?cs=${encodeURIComponent(pending.client_secret ?? '')}`;
+// → res.redirect(checkoutUrl)
+
+// Activation arrives via the subscription/invoice webhooks; never trust the
+// client. Reconcile with subscriptions.retrieve(pending.id, opts).
+```
+
+**Saved payment method (off-session).** If the customer already has a saved,
+tokenized payment method, confirm server-side with the token — still no PAN:
+
+```typescript
+const sub = await delopay.subscriptions.createAndConfirm(
+  {
+    item_price_id: priceId,
+    customer_id: 'cus_abc123',
+    payment_details: {
+      payment_method: 'card',
+      payment_method_id: savedPaymentMethodId, // token, not a card number
+      setup_future_usage: 'off_session',
+      return_url: 'https://example.com/subscription/complete',
+    },
+  },
+  opts,
+);
+
+if (sub.redirect_url) {
+  // Some processors (e.g. PayPal) still need buyer approval — redirect there.
+} else {
+  console.log(sub.status); // 'active'
+}
+```
+
+You can also split create and confirm — call `subscriptions.confirm(id, …)` with
+the `client_secret` and a `payment_token` once the buyer has a token. Same rule:
+a `payment_token` / `payment_method_id`, never a raw card.
+
+**Manage the lifecycle.** Pause, resume, and cancel take optional timing and
+proration controls; called with no body they act immediately:
+
+```typescript
+await delopay.subscriptions.pause(sub.id, { pause_option: 'end_of_term' }, opts);
+await delopay.subscriptions.resume(sub.id, undefined, opts);
+await delopay.subscriptions.cancel(
+  sub.id,
+  { cancel_option: 'immediately', credit_option_for_current_term_charges: 'prorate' },
+  opts,
+);
+
+// Retrieve one, or list for the profile
+const current = await delopay.subscriptions.retrieve(sub.id, opts);
+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.
+
 ### Webhook verification
 
 Delopay signs each outgoing webhook with HMAC-SHA512 over the raw request body and delivers the hex-encoded digest in the `X-Webhook-Signature-512` header. Use `express.raw()` (not `express.json()`) so the bytes reach the verifier unchanged.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@delopay/sdk",
-  "version": "0.34.0",
+  "version": "0.35.0",
   "description": "Official Delopay TypeScript SDK",
   "type": "module",
   "sideEffects": false,