npm package: @kamalnayanupadhyay/flexxy-react
Description: React SDK widget for Flexxy billing and session access
Latest version: 0.1.0

# @flexxy/react

React SDK for Flexxy pricing widgets, checkout, and session-gated access.

## Quick Start

```tsx
import { FllexyProvider, FllexyPricingWidget } from '@flexxy/react'

export function Pricing() {
  return (
    <FllexyProvider publicKey="fx_pub_xxx" saasId="your_saas_id" userId="user_123">
      <FllexyPricingWidget />
    </FllexyProvider>
  )
}
```

## Installation

```bash
pnpm add @flexxy/react
```

## FllexyProvider Setup

```tsx
import { FllexyProvider } from '@flexxy/react'

<FllexyProvider
  publicKey="fx_pub_xxx"
  saasId="your_saas_id"
  userId={user.id}
  userEmail={user.email}
  onSessionStart={(session) => console.log('started', session.plan_name)}
  onSessionExpiring={() => console.log('expiring soon')}
  onSessionExpired={() => console.log('expired')}
>
  {children}
</FllexyProvider>
```

## FllexyPricingWidget Usage

```tsx
import { FllexyPricingWidget } from '@flexxy/react'

<FllexyPricingWidget
  publicKey="fx_pub_xxx"
  saasId="your_saas_id"
  userId="user_123"
  theme={{
    brandColor: '#FF6B35',
    layout: 'grid',
    showPoweredBy: true,
  }}
/>
```

## FllexyGate Usage

```tsx
import { FllexyGate, FllexyPricingWidget } from '@flexxy/react'

<FllexyGate userToken={sessionToken} fallback={<FllexyPricingWidget />}>
  <ProtectedArea />
</FllexyGate>
```

## useFllexySession Hook

```tsx
import { useFllexySession } from '@flexxy/react'

const state = useFllexySession({
  userToken: sessionToken,
  refreshToken,
  pollIntervalMs: 30_000,
})
```

## Session Timer

```tsx
import { SessionTimer } from '@flexxy/react'

<SessionTimer expiresAt={session.expires_at} />
```

## Event Callbacks

- `onSessionStart(session)` fires when a session becomes active.
- `onSessionExpiring(session)` fires when <= 5 minutes remain.
- `onSessionExpired()` fires after expiry.

## Theming

```tsx
<FllexyPricingWidget
  publicKey="fx_pub_xxx"
  saasId="your_saas_id"
  theme={{
    brandColor: '#1A56DB',
    borderRadius: '14px',
    fontFamily: 'inherit',
    darkMode: true,
    cardStyle: 'outlined',
    layout: 'list',
    buttonText: 'Buy Access',
    showPoweredBy: false,
  }}
/>
```

## Test Mode

Use keys with `fx_test_` prefix.

Behavior:
- No real payment redirect.
- Session is simulated instantly.
- `TestModeBanner` appears.
- Session callbacks still fire.

## TypeScript Types

```ts
import type {
  FllexyConfig,
  FllexyPlan,
  FllexySession,
  FllexyTheme,
  FllexyPricingWidgetProps,
  FllexyGateProps,
  SessionTimerProps,
  CheckoutOptions,
} from '@flexxy/react'
```

## API Notes

- Default API base URL: `https://api.fllexy.com`
- Plans endpoint used by SDK: `GET /v1/public/plans/:saas_id`
- Checkout endpoint used by SDK: `POST /v1/checkout/create`
- Session check endpoint used by gate/hook: `GET /v1/sessions/check?token=...`

## CDN Fallback (Non-React)

```html
<script
  src="https://js.flexxy.com/widget.js"
  data-key="fx_pub_xxx"
  data-saas-id="your_saas_id"
  data-user-id="user_123"
  data-brand-color="#FF6B35"
></script>
```

Or with bundle from npm package:

```html
<script src="./node_modules/@flexxy/react/dist/vanilla/widget.js"></script>
```

## Examples

- `examples/nextjs-example`
- `examples/cra-example`