cashfree-pg-api-contract/CLAUDE.md

This package contains the contract for Cashfree PG

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Commands

```bash
# Build (compiles TypeScript to dist/)
npm run build
```

No tests are configured (`npm test` exits with error).

## Architecture

This is a **single-file TypeScript contract library** (`src/index.ts`) that defines shared data structures and validation rules used across Cashfree JS/React Native SDKs. It compiles to CommonJS ES5 with type declarations (`dist/`).

### Session Types

- **`CFSession`** — Standard payment session; requires `sessionID`, `orderID`, `CFEnvironment`
- **`CFSubscriptionSession`** — Subscription session; requires `subscriptionSessionId`, `subscriptionId`, `CFEnvironment`

### Payment Classes (all implement `CheckoutPayment`)

**Standard flows:**
- `CFDropCheckoutPayment(session, components|null, theme|null)` — Drop-in UI; defaults to all payment modes and default theme
- `CFWebCheckoutPayment(session, theme|null)` — Web checkout
- `CFUPIIntentCheckoutPayment(session, theme|null)` — UPI Intent
- `CFCardPayment(session, card)` — Direct card (accepts `Card`, `SavedCard`, or `ElementCard`)
- `CFUPIPayment(session, upi)` — Direct UPI collect/intent

**Subscription flows:**
- `CFSubsCardPayment(session, card)`
- `CFSubsUPIPayment(session, upi)`
- `CFSubsNBPayment(session, nb)` — Net banking via `CFSubsNB`
- `CFSubscriptionCheckoutPayment(session, theme|null)` — Subscription drop-in

### Card Variants (`CFCard` interface)

- `Card` — Full PCI card (number, holder name, expiry MM/YY, CVV, saveCard flag)
- `SavedCard` — Stored card via `instrumentId` + CVV
- `ElementCard` — Non-PCI component card; extends `Card` with hardcoded `"CF"` as cardNumber

### Builder Pattern

- **`CFPaymentComponentBuilder`** — Chainable `.add(CFPaymentModes.X)`. If nothing is added, `.build()` enables all 7 modes automatically.
- **`CFThemeBuilder`** — Full theme (nav bar, button, background, primary/secondary text). Default brand color: `#6A3FD3`.
- **`CFIntentThemeBuilder`** — Only exposes `backgroundColor` and `primaryTextColor`; delegates remaining fields to `CFThemeBuilder`.
- **`CFWebThemeBuilder`** — Only exposes `navigationBarBackgroundColor` and `navigationBarTextColor`; delegates rest to `CFThemeBuilder`.

### Design Notes

- All required fields are validated in constructors and throw descriptive errors. `CFSubsNB` uses a loop-based validation pattern; other classes use individual checks.
- The `version` field on `CheckoutPayment` is declared public but never set in constructors — it is set by consuming SDKs.
- `package.json` declares `"type": "module"` but `tsconfig.json` compiles to `commonjs`. The published `dist/` output is CommonJS.
- `src/` is excluded from the npm package via `.npmignore`; only `dist/` is published.