# @playbasis-ai/qwikcard-sdk

> Official React Native SDK for Playbasis gamification integration

[![npm version](https://img.shields.io/npm/v/@playbasis-ai/qwikcard-sdk.svg)](https://www.npmjs.com/package/@playbasis-ai/qwikcard-sdk)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
[![React Native](https://img.shields.io/badge/React%20Native-0.70+-green.svg)](https://reactnative.dev/)

## Features

- 🎮 **Full Gamification Suite** - Points, quests, badges, rewards, leaderboards
- ⚡ **Real-time Updates** - React hooks with automatic state management
- 🔒 **Secure by Design** - No credentials stored, idempotent requests
- 🧩 **Widget UI via WebView** - Full Playbasis Widget experience embedded in RN
- 🔄 **Offline-Friendly** - Graceful error handling

## Installation

```bash
npm install @playbasis-ai/qwikcard-sdk
```

### Peer Dependencies

You must install the following dependencies in your project:

```bash
npm install react-native-linear-gradient react-native-svg react-native-webview
```

### Local Installation (if not published to npm)

If this package is not published to npm, you can install it locally in your project using one of the following methods:

#### 1. From a Local Folder (Symlink for Development)

Unzip or place the SDK folder (with `package.json`) somewhere on your machine, e.g., `~/playbasis-sdk/`.
In your project, run:

```bash
yarn add /absolute/path/to/playbasis-sdk
# or
npm install /absolute/path/to/playbasis-sdk
```

#### 2. From a Tarball (.tgz or .zip)

If you have a file like `playbasis-qwikcard-sdk-1.0.0.zip` or `.tgz`, you can install directly:

```bash
yarn add ./client-sdks/qwikcard-sdk/playbasis-qwikcard-sdk-1.0.0.zip
# or
npm install ./client-sdks/qwikcard-sdk/playbasis-qwikcard-sdk-1.0.0.zip
```

#### 3. npm/yarn link (for active development)

In the SDK folder:

```bash
npm link
# or
yarn link
```

In your project folder:

```bash
npm link @playbasis-ai/qwikcard-sdk
# or
yarn link @playbasis-ai/qwikcard-sdk
```

#### 4. From a Git Repository

If the SDK is hosted in a private Git repo:

```bash
yarn add git+https://github.com/your-org/playbasis-qwikcard-sdk.git
# or
npm install git+https://github.com/your-org/playbasis-qwikcard-sdk.git
```

---

If the package is published to npm, you can install as usual:

```bash
npm install @playbasis-ai/qwikcard-sdk
# or
yarn add @playbasis-ai/qwikcard-sdk
```

## Requirements

- React Native >= 0.70.0
- React >= 18.0.0

## Quick Start

### 1. One-Line Integration (Recommended)

`QwikCardApp` renders the full Playbasis experience using a WebView-embedded Widget UI, while keeping API calls on the React Native side.

```tsx
import { QwikCardApp } from '@playbasis-ai/qwikcard-sdk';

export default function RewardsAndGamificationScreen() {
  return (
    <QwikCardApp
      apiKey="YOUR_SUBSCRIPTION_KEY"
      tenantId="YOUR_TENANT_ID"
      playerId={currentUser.playbasisPlayerId}
      baseUrl="https://api.playbasis.com" // optional
      leaderboardId="YOUR_LEADERBOARD_ID" // optional
    />
  );
}
```

Notes:

- `leaderboardId` is optional because the Playbasis API requires a concrete leaderboard identifier. If omitted, the widget will render with an empty leaderboard section.
- Activity charts are returned as an empty array in v1.3.0 unless/until an activity endpoint is added to the API.

### 2. Provider + Hooks (Optional / Advanced)

If you need direct access to the API client for custom UI/logic, you can still use the provider + hooks.

#### Wrap Your App

```tsx
import { PlaybasisProvider } from '@playbasis-ai/qwikcard-sdk';

export default function App() {
  return (
    <PlaybasisProvider
      apiKey="YOUR_SUBSCRIPTION_KEY"
      tenantId="qwikcard"
      playerId={currentUser.playbasisPlayerId}
    >
      <YourApp />
    </PlaybasisProvider>
  );
}
```

### 2. Use Hooks (with your own screens)

```tsx
import { useQuests, useRewards, useBadges, usePoints } from '@playbasis-ai/qwikcard-sdk';

function RewardsScreen() {
  const { rewards } = useRewards();
  const { badges } = useBadges();
  const { xp, qwikCoins } = usePoints();

  return (
    <View>
      <Text>XP: {xp}</Text>
      <Text>Qwik Coins: {qwikCoins}</Text>
      {/* Render rewards + badges here */}
    </View>
  );
}
```

### 3. Use Components (with your own screens)

```tsx
import { QuestProgress, RewardCard, BadgeIcon, PointsBalance } from '@playbasis-ai/qwikcard-sdk';

function QuestsScreen() {
  const { quests } = useQuests();
  const { balances } = usePoints();

  return (
    <ScrollView>
      <PointsBalance balances={balances} />
      {quests.map((quest) => (
        <QuestProgress key={quest.id} quest={quest} />
      ))}
    </ScrollView>
  );
}
```

## API Client (Direct Access)

For custom operations:

```tsx
import { usePlaybasis } from '@playbasis-ai/qwikcard-sdk';

function TransactionLogger() {
  const { client, playerId } = usePlaybasis();

  const logPurchase = async (transaction) => {
    await client.trackEvent({
      type: 'card.purchase',
      playerId,
      referenceId: transaction.i2c_trans_id,
      data: {
        amount: transaction.amount,
        mcc: transaction.mcc,
        category: transaction.category,
      },
    });
  };

  return { logPurchase };
}
```

## Event Types

```typescript
// XP values follow the QwikCard XP rulebook in QWIK_PLAYBASIS_GAMIFICATION_DESIGN.md.
type QwikCardEventType =
  | 'auth.signup' // Account created (+50 XP, once)
  | 'auth.login' // Daily login (+5 XP, 1/day)
  | 'profile.updated' // Profile progress (+25 XP, max 3 lifetime)
  | 'card.activated' // Card activation (+150 XP, once)
  | 'card.deposit' // Funding action (+40 XP, 1/day)
  | 'budget.created' // Budget created (+120 XP, 1/quarter)
  | 'transactions.viewed' // Transaction review (+10 XP, 1/day)
  | 'credit.score_viewed' // Credit score check (+40 XP, 1/week)
  | 'qwikit.sent' // P2P transfer sent (+20 XP, max 5/day)
  | 'qwikit.received' // P2P transfer received (+10 XP, max 5/day)
  | 'qwikit.requested' // P2P transfer requested (+10 XP, max 5/day)
  | 'referral.completed' // Referral success (+250 XP, max 10 lifetime)
  | 'learning.lesson_started' // Lesson started (+10 XP, max 3/day)
  | 'learning.lesson_completed' // Lesson completed (+75 XP, max 3/day)
  | 'offers.map_viewed'; // Offers map viewed (+5 XP, 1/day)
```

## API Reference

### Hooks

| Hook             | Description                        |
| ---------------- | ---------------------------------- |
| `usePoints()`    | Player point balances, earn points |
| `useQuests()`    | Active and completed quests        |
| `useBadges()`    | Earned and available badges        |
| `useRewards()`   | Reward catalog and redemption      |
| `usePlaybasis()` | Direct client access               |

### Components

| Component             | Description                     |
| --------------------- | ------------------------------- |
| `<PlaybasisProvider>` | Context provider (required)     |
| `<PointsBalance>`     | Display point balances          |
| `<QuestProgress>`     | Quest progress card             |
| `<RewardCard>`        | Reward item with redeem button  |
| `<BadgeIcon>`         | Badge display with earned state |

## Security

- ✅ No credentials stored in SDK
- ✅ All requests use HTTPS
- ✅ Idempotency keys prevent duplicate operations
- ✅ Safe JSON parsing (handles malformed responses)

## Support

Contact Playbasis support for:

- API credentials
- Integration assistance
- Custom implementations

---

© 2025 Playbasis. All rights reserved.