@thepayulink/checkout 1.0.0 → 2.0.1

package/README.md

@@ -1,8 +1,8 @@
 # @thepayulink/checkout
 
-A drop-in **UPI payment checkout** for Elite Yatra — the same Razorpay-style modal used on eliteyatra.vip, packaged so any website or web app can open it in one call. Payments run through the Elite Yatra pay server and settle to Elite Yatra's PayuLink account.
-
-![Payment Options modal](https://eliteyatra.vip/assets/payulink-logo.png)
+Browser checkout for the [PayuLink](https://payulink.io) Checkout API. Open an
+order your server created, using only your **publishable key**. If you've used
+Razorpay's `checkout.js`, this will feel familiar.
 
 ## Install
 
@@ -10,97 +10,87 @@ A drop-in **UPI payment checkout** for Elite Yatra — the same Razorpay-style m
 npm install @thepayulink/checkout
 ```
 
-Or load it straight from the Elite Yatra server / a CDN — no build step:
+Or with no build step, from the CDN:
 
 ```html
-<script src="https://eliteyatra.vip/sdk/v1/checkout.js"></script>
+<!-- pinned (recommended: immutable, cached a year) -->
+<script src="https://assetcdn.payulink.io/checkout/v1/checkout-2.0.0.js"></script>
+
+<!-- or float on the latest v1 (cached 5 min) -->
+<script src="https://assetcdn.payulink.io/checkout/v1/checkout.js"></script>
 ```
 
 ## Quick start
 
-### With a bundler (React, Vue, Vite, Next.js, plain ESM)
+Your backend creates the order with
+[`@thepayulink/server`](https://www.npmjs.com/package/@thepayulink/server) and
+hands the client an `order_id`:
 
 ```js
-import PayulinkCheckout from '@thepayulink/checkout';
-
-const checkout = new PayulinkCheckout({
-  apiBase: 'https://eliteyatra.vip',   // your Elite Yatra pay server
-  name: 'Elite Yatra',
-  logo: 'https://eliteyatra.vip/brand-logo.png',
-  brandColor: '#0b3068',
-});
-
-checkout.open({
-  amount: 19900,                        // rupees
-  item: 'Kailash Mansarovar Yatra — 2 travellers',
-  prefill: { name: 'Asha', contact: '9876543210', email: 'asha@example.com' },
-  handler: (res) => {
-    // Fired once the server confirms the payment (webhook-verified).
-    console.log('Paid!', res.merchant_order_no, res.utr);
+import PayuLink from '@thepayulink/checkout';
+
+const pl = new PayuLink({ key: 'pl_live_…' });   // publishable key ONLY
+
+pl.open({
+  order_id: orderId,
+  prefill: { name: 'A Kumar', contact: '9876543210' },
+  handler: async (r) => {
+    // Send the handoff to YOUR server and verify it there before delivering anything.
+    await fetch('/verify', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(r),   // payulink_order_id / payulink_payment_id / payulink_signature
+    });
   },
-  onDismiss: () => console.log('closed without paying'),
+  onDismiss: () => {},
 });
 ```
 
-### With a plain `<script>` tag
-
-```html
-<script src="https://eliteyatra.vip/sdk/v1/checkout.js"></script>
-<script>
-  new PayulinkCheckout({ apiBase: 'https://eliteyatra.vip' })
-    .open({ amount: 19900, item: 'Tour booking', handler: (r) => alert(r.merchant_order_no) });
-</script>
-```
-
-## How it works
-
-1. `open()` renders the modal and (once contact details are known) calls **`POST {apiBase}/api/checkout`** to create a real PayuLink PayIn order.
-2. It shows the UPI QR + intent links and streams live status over **`GET {apiBase}/api/order/:id/events`** (Server-Sent Events), falling back to polling.
-3. When the payment is verified by PayuLink's webhook, the modal shows the success screen and your `handler` fires.
-
-Your server (`eliteyatra_pay`) is the source of truth — the SDK never sees PayuLink secrets.
+Via `<script>`, the same class is available as the global `PayuLink`.
 
 ## Options
 
-Constructor options (shared defaults) and `open()` options are merged; anything valid in one works in the other.
+| Option | Type | Description |
+| --- | --- | --- |
+| `key` | string | **Required.** Publishable `pl_live_…` / `pl_test_…` key. |
+| `order_id` | string | **Required.** From `POST /v1/orders` on your server. |
+| `prefill` | object | `{ name, contact, email }` — saves the customer typing. |
+| `handler` | function | Called on success with the signed handoff. |
+| `onDismiss` | function | Called if the customer closes without paying. |
+| `onError` | function | Called on failure. |
+| `theme` | object | `{ color: '#38BDF8' }` |
+| `apiBase` | string | Default `https://payulink.io/api`. |
 
-| Option | Type | Default | Description |
-| --- | --- | --- | --- |
-| `apiBase` | string | `https://eliteyatra.vip` | Elite Yatra pay server base URL. |
-| `assetBase` | string | `${apiBase}/assets` | Where `/upi/*.png` and `/payulink-logo.png` are served. |
-| `name` | string | `Elite Yatra` | Business name on the left panel. |
-| `logo` | string | payulink logo | Left-panel logo URL. |
-| `brandColor` | string | `#0b3068` | Left-panel gradient accent. |
-| `amount` | number | — | **Required.** Amount in rupees. |
-| `item` | string | `name` | What the customer is paying for. |
-| `note` | string | — | Sub-line under the price summary. |
-| `prefill` | object | `{}` | `{ name, contact, email }`. If `name` + 10-digit `contact` are present, the contact form is skipped. |
-| `handler` | function | — | `({ merchant_order_no, utr, amount }) => void` on success. |
-| `onDismiss` | function | — | Called when the modal is closed without paying. |
-| `key` | string | — | Optional public key, sent as the `x-payulink-key` header. |
-
-`open()` returns `{ close() }` so you can dismiss the modal programmatically.
-
-## React Native
+## How it works
 
-This package renders a DOM modal and runs in **browsers only**. In a React Native app, use a `WebView` pointed at the hosted checkout page instead:
+1. `open()` calls **`POST /v1/checkout/session`** with your `key_id` + `order_id`.
+2. PayuLink verifies the order belongs to you and returns the hosted payment page.
+   **The amount comes from the stored order** — the browser cannot change it.
+3. The customer pays by UPI. The hosted page handles the QR and auto-verification.
+4. Once PayuLink verifies the payment, your `handler` fires with the signed handoff.
 
-```jsx
-import { WebView } from 'react-native-webview';
+## Security
 
-<WebView source={{ uri: 'https://eliteyatra.vip/pay?amount=19900&item=Tour%20booking&name=Asha&phone=9876543210' }} />
-```
+- **Never put a `key_secret` here.** This SDK throws if you pass one. Only the
+  publishable `key_id` belongs in client code.
+- **There is no client-supplied amount.** The client can only reference an order
+  your server already created and priced.
+- **`handler` firing is not proof of payment** — it's a browser claiming success.
+  Verify `payulink_signature` on your server with
+  `@thepayulink/server` → `verifyPaymentSignature()`, or act on the webhook.
+  Webhooks are the record that survives the customer closing the tab.
 
-## Server requirements
+## Upgrading from 1.x
 
-The `apiBase` server must expose (already implemented in `eliteyatra_pay/server.js`):
+1.x talked to a self-hosted proxy and let the client pass an `amount`. 2.x talks
+to PayuLink directly and removes that.
 
-- `POST /api/checkout` → `{ merchant_order_no, amount, qr_data_url, upi_intent_url, payment_link, expires_at, server_now }`
-- `GET /api/order/:id` → order status
-- `GET /api/order/:id/events` → SSE status stream
-- Static `/assets/upi/*.png` and `/assets/payulink-logo.png`
-- **CORS** allowing the embedding origin (see `server.js`).
+| 1.x | 2.x |
+| --- | --- |
+| `new PayulinkCheckout({ apiBase })` | `new PayuLink({ key })` |
+| `open({ amount, item })` | `open({ order_id })` — priced server-side |
+| `handler({ merchant_order_no, utr })` | `handler({ payulink_order_id, payulink_payment_id, payulink_signature })` |
 
-## License
+`window.PayulinkCheckout` remains aliased for existing `<script>` embeds.
 
-UNLICENSED — internal to Elite Yatra.
+Full guide: <https://payulink.io> · License: MIT

package/dist/index.d.ts

@@ -1,66 +1,61 @@
-export interface PayulinkPrefill {
+// Type definitions for @thepayulink/checkout
+
+export interface PayuLinkPrefill {
   name?: string;
   /** 10-digit Indian mobile number. */
   contact?: string;
   email?: string;
 }
 
-export interface PayulinkSuccess {
-  merchant_order_no: string;
-  utr: string | null;
-  amount: number;
+/** The signed handoff. Send this to YOUR server and verify it there. */
+export interface PayuLinkSuccess {
+  payulink_order_id: string;
+  payulink_payment_id: string;
+  /** HMAC_SHA256(order_id + "|" + payment_id, key_secret) — verify server-side. */
+  payulink_signature: string;
+  utr?: string | null;
+  /** PAISE */
+  amount?: number;
 }
 
-export interface PayulinkOptions {
-  /** Elite Yatra pay server base URL. Default: https://eliteyatra.vip */
+export interface PayuLinkOptions {
+  /** Your PUBLISHABLE key: pl_live_… / pl_test_…. Never a key_secret. */
+  key: string;
+  /** Gateway base URL. Default https://payulink.io/api */
   apiBase?: string;
-  /** Base URL serving /upi/*.png and /payulink-logo.png. Default: `${apiBase}/assets`. */
-  assetBase?: string;
-  /** Business name shown on the left panel. */
+  /** Overrides the merchant name shown in the header. */
   name?: string;
-  /** Logo URL for the left panel. */
-  logo?: string;
-  /** Accent color for the left panel gradient, e.g. '#0b3068'. */
-  brandColor?: string;
-  /** Optional public key, sent as the `x-payulink-key` request header. */
-  key?: string;
+  /** Accent colour, e.g. { color: '#38BDF8' } */
+  theme?: { color?: string };
+  /** Status poll interval in ms. Default 2500. */
+  pollMs?: number;
 }
 
-export interface PayulinkPayment extends PayulinkOptions {
-  /**
-   * SECURE flow: id of an order created by your backend via
-   * `POST /api/orders` (secret key). The amount is fixed server-side; when set,
-   * `amount` is ignored.
-   */
-  orderId?: string;
-  /** Amount in rupees. Required unless `orderId` is given. */
-  amount?: number;
-  /** What the customer is paying for. */
-  item?: string;
-  /** Optional sub-line under the price summary. */
-  note?: string;
-  prefill?: PayulinkPrefill;
-  /** Called on a successful payment. */
-  handler?: (result: PayulinkSuccess) => void;
-  /** Called when the modal is dismissed without paying. */
+export interface PayuLinkOpenOptions extends Partial<PayuLinkOptions> {
+  /** Required. Created by YOUR server via POST /v1/orders. */
+  order_id: string;
+  prefill?: PayuLinkPrefill;
+  /** Called on success with the signed handoff. */
+  handler?: (result: PayuLinkSuccess) => void;
+  /** Called if the customer closes the checkout without paying. */
   onDismiss?: () => void;
-  /** Called if the order can't be opened (e.g. unknown/expired orderId). */
   onError?: (error: Error) => void;
 }
 
-export interface PayulinkInstance {
-  /** Programmatically close the modal. */
+export interface PayuLinkHandle {
   close(): void;
 }
 
-export default class PayulinkCheckout {
-  constructor(options?: PayulinkOptions);
-  open(payment: PayulinkPayment): PayulinkInstance;
-  static open(options: PayulinkPayment): PayulinkInstance;
+export default class PayuLink {
+  constructor(options: PayuLinkOptions);
+  open(options: PayuLinkOpenOptions): PayuLinkHandle;
+  static open(options: PayuLinkOptions & PayuLinkOpenOptions): PayuLinkHandle;
 }
 
 declare global {
   interface Window {
-    PayulinkCheckout: typeof PayulinkCheckout;
+    PayuLink: typeof PayuLink;
+    /** Back-compat alias for pre-2.x <script> embeds. */
+    PayulinkCheckout: typeof PayuLink;
   }
 }