From 681cfd1c37e48ea311e374ad75c6a52defc01ca5 Mon Sep 17 00:00:00 2001
From: Jaafar <mostafajaafar9869@gmail.com>
Date: Thu, 6 Aug 2026 13:08:15 +0300
Subject: [PATCH] feat: add optional iframe init option to invoices.create

Adds an optional `iframe` field to CreateInvoiceParams, mirroring the
existing unsigned `paymentMode` passthrough. It is sent in the request
body (as a Laravel-boolean-truthy "1") but excluded from the HMAC
signature. Set `iframe: true` to request a checkout suitable for
embedding.

Boolean coercion is already handled correctly by coerceToString
(true -> "1", false -> "0"), so no coercion changes were needed.

Bumps version 0.1.1 -> 0.2.0.
---
 CHANGELOG.md                |  1 +
 README.md                   | 16 ++++++++++++++++
 package.json                |  2 +-
 src/internal/fieldOrders.ts |  1 +
 src/types.ts                |  7 +++++--
 src/version.ts              |  2 +-
 test/sign-request.test.ts   | 23 +++++++++++++++++++++++
 test/type-safety.test.ts    |  1 +
 8 files changed, 49 insertions(+), 4 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f6e9a64..4c4899a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,7 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ### Added
 
+- Optional `iframe` field on `invoices.create` (`iframe?: boolean | number`). Like `paymentMode`, it is an unsigned passthrough — sent in the request body but excluded from the HMAC signature. Set `iframe: true` to request a checkout suitable for embedding.
 - Retry with exponential backoff and full jitter for transient failures (429, 5xx, network errors, timeouts), honoring `Retry-After`. Only replay-safe requests are retried — GETs, calls carrying an `Idempotency-Key`, and pure reads such as `payments.checkStatus`. Charges are never replayed.
 - `maxRetries` client option (default `2`; `0` disables).
 - `PaylinkApiError.retryAfterMs` and `PaylinkApiError.isRateLimited`.
diff --git a/README.md b/README.md
index fe2afc1..601dc09 100644
--- a/README.md
+++ b/README.md
@@ -61,6 +61,22 @@ const checkout = await paylink.invoices.create({
 console.log(checkout.checkoutUrl, checkout.invoiceId, checkout.expiresAt);
 ```
 
+Pass `iframe: true` to receive a `checkoutUrl` suitable for embedding — for
+example rendering the hosted checkout inside an `<iframe>` on your own page
+instead of a full-page redirect:
+
+```ts
+const embedded = await paylink.invoices.create({
+  firstName: 'John',
+  lastName: 'Doe',
+  email: 'john@example.com',
+  orderTitle: 'Gold Plan',
+  orderAmount: '250.00',
+  currency: 'USD',
+  iframe: true, // optional, unsigned passthrough (like paymentMode)
+});
+```
+
 Both credentials are issued in the PayLink dashboard under
 **Settings → Payment Integrations**. `publicToken` is sent on every request;
 `hashToken` is the secret used only to sign — it never leaves your server.
diff --git a/package.json b/package.json
index a5c1f7d..5f43899 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@getpayin/paylink",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Official server-side Node.js/TypeScript SDK for the PayLink payment integration API (checkouts, payment operations, card tokens, recurring mandates, webhook verification).",
   "keywords": [
     "paylink",
diff --git a/src/internal/fieldOrders.ts b/src/internal/fieldOrders.ts
index 5d4e287..36639a3 100644
--- a/src/internal/fieldOrders.ts
+++ b/src/internal/fieldOrders.ts
@@ -73,6 +73,7 @@ export const INVOICE_CREATE: EndpointSpec<CreateInvoiceParams> = {
     { sdk: 'webhookUrl', wire: 'webhook_url' },
     { sdk: 'orderDetails', wire: 'order_details' },
     { sdk: 'paymentMode', wire: 'payment_mode', signed: false },
+    { sdk: 'iframe', wire: 'iframe', signed: false },
   ],
 };
 
diff --git a/src/types.ts b/src/types.ts
index 8dab065..44248ad 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -33,8 +33,10 @@ export interface BillingAddress {
 
 /**
  * Parameters for `invoices.create`. `redirectionUrl` and `webhookUrl` must be
- * HTTPS URLs on the integration's registered domain; `paymentMode` is an
- * optional passthrough that is sent to the API but excluded from the signature.
+ * HTTPS URLs on the integration's registered domain; `paymentMode` and `iframe`
+ * are optional passthroughs that are sent to the API but excluded from the
+ * signature. Set `iframe: true` to have the API return a checkout suitable for
+ * embedding.
  */
 export interface CreateInvoiceParams {
   firstName: string;
@@ -51,6 +53,7 @@ export interface CreateInvoiceParams {
   webhookUrl?: string;
   orderDetails?: string;
   paymentMode?: string;
+  iframe?: boolean | number;
 }
 
 export interface CreateInvoiceResult {
diff --git a/src/version.ts b/src/version.ts
index 6a0e493..8e1492f 100644
--- a/src/version.ts
+++ b/src/version.ts
@@ -1 +1 @@
-export const VERSION = '0.1.1';
+export const VERSION = '0.2.0';
diff --git a/test/sign-request.test.ts b/test/sign-request.test.ts
index 65a9794..3403d41 100644
--- a/test/sign-request.test.ts
+++ b/test/sign-request.test.ts
@@ -145,6 +145,29 @@ describe('buildSignedBody — body construction rules', () => {
     expect(withMode.signature).toBe(withoutMode.signature);
   });
 
+  it('sends iframe in the body but excludes it from the signature', () => {
+    const withIframe = create(INVOICE_CREATE, {
+      firstName: 'A',
+      lastName: 'B',
+      email: 'a@b.com',
+      orderTitle: 'T',
+      orderAmount: 1,
+      currency: 'USD',
+      iframe: true,
+    });
+    const withoutIframe = create(INVOICE_CREATE, {
+      firstName: 'A',
+      lastName: 'B',
+      email: 'a@b.com',
+      orderTitle: 'T',
+      orderAmount: 1,
+      currency: 'USD',
+    });
+
+    expect(withIframe.iframe).toBe('1');
+    expect(withIframe.signature).toBe(withoutIframe.signature);
+  });
+
   it('appends the US state block (us_state, postal_code) after city', () => {
     const body = create(VCC_CHARGE, {
       firstName: 'S',
diff --git a/test/type-safety.test.ts b/test/type-safety.test.ts
index 45597cd..efc4c67 100644
--- a/test/type-safety.test.ts
+++ b/test/type-safety.test.ts
@@ -46,6 +46,7 @@ describe('field registry type-linking', () => {
       fields: [
         { sdk: 'orderTitle', wire: 'order_title' },
         { sdk: 'paymentMode', wire: 'payment_mode', signed: false },
+        { sdk: 'iframe', wire: 'iframe', signed: false },
       ],
     };