@playbasis-ai/qwikcard-sdk 2.3.4

package/CHANGELOG.md

@@ -0,0 +1,142 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.2.0] - 2025-12-29
+
+### Added
+
+- "How to Play" `RulesModal` component for player guidance.
+- New Header in `DashboardScreen` with Help and Notification icons.
+- `SDK_HANDOVER_GUIDE.md` for easier integration.
+
+### Fixed
+
+- Mobile responsiveness and compact UI refinements across all screens.
+- Web preview modal containment within smartphone frame.
+- Radial gauge aspect ratio for better information density.
+
+## [1.3.0] - 2026-01-03
+
+### Changed
+
+- `QwikCardApp` now renders the Playbasis Widget UI via `react-native-webview` (WebView-embedded Widget SDK).
+- Updated SDK documentation to reflect WebView integration and the recommended one-line integration path.
+
+### Added
+
+- `react-native-webview` as a peer dependency.
+
+## [1.3.1] - 2026-01-04
+
+### Changed
+
+- Updated production handover guidance to use production APIM base path `/v1`.
+- Prepared new-tenant handover workflow for `qwik-prod` without requiring Expo.
+
+## [2.3.3] - 2026-01-19
+
+### Fixed
+
+- Updated `Currency` type and `usePoints` hook to use `coins` (matching API) instead of `qwik-coins`.
+
+## [2.3.2] - 2026-01-17
+
+### Changed
+
+- Pinned Arcade Center banners to the hosted CDN URLs.
+
+## [2.3.1] - 2026-01-17
+
+### Changed
+
+- Fixed Arcade Center banner URL resolution when running inside the widget WebView.
+
+## [2.3.0] - 2026-01-17
+
+### Changed
+
+- Fixed Arcade Center banner URLs for hosted game assets.
+
+## [2.2.9] - 2026-01-17
+
+### Changed
+
+- Added Arcade Center banner rendering with hosted images.
+
+## [2.2.8] - 2026-01-17
+
+### Changed
+
+- Rebuilt the embedded widget assets with the latest Arcade Center updates.
+
+## [2.2.7] - 2026-01-17
+
+### Added
+
+- Play tab with Arcade Center (Match-3 Challenge + Bubble Blast) in the embedded widget.
+
+### Fixed
+
+- `GradientCard` now falls back to `View` when `react-native-linear-gradient` is unavailable.
+
+### Removed
+
+- Legacy React Native screens and Navigator exports (WebView widget is the primary UI).
+
+### Changed
+
+- Added tab collapse/expand control in the widget Play navigation.
+
+### Fixed
+
+- Cleaned unused campaign hooks in widget runtime.
+
+### Fixed
+
+- Arcade Center now returns to the Play tab on back with Qwik light header.
+
+## [1.0.0] - 2024-12-15
+
+### Added
+
+- Initial release of @playbasis/qwikcard-sdk
+
+  (Package name/scope may differ depending on your distribution channel.)
+
+- `PlaybasisProvider` - React context provider for SDK configuration
+- `PlaybasisClient` - Fetch-based API client with idempotency support
+
+#### Hooks
+
+- `usePoints()` - Manage player point balances
+- `useQuests()` - Track quest progress and completion
+- `useBadges()` - Display earned and available badges
+- `useRewards()` - Browse and redeem rewards
+- `usePlaybasis()` - Direct access to client and context
+
+#### Components
+
+- `PointsBalance` - Display multiple currency balances
+- `QuestProgress` - Quest card with progress bar
+- `RewardCard` - Reward item with redemption button
+- `BadgeIcon` - Badge display with earned/locked states
+
+#### Event Types
+
+- `card.purchase` - Debit card transactions
+- `card.deposit` - Direct deposits
+- `card.atm` - ATM withdrawals
+- `qwikit.sent` / `qwikit.received` - P2P transfers
+- `referral.signup` - Referral completions
+- `profile.complete` - Profile completion
+
+### Security
+
+- Fetch-based client (no axios dependency)
+- Safe JSON parsing with error handling
+- UUID-based idempotency keys (collision-resistant)
+- No credentials stored in SDK

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Playbasis Co., Ltd.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,267 @@
+# @foremost-ai/qwikcard-sdk
+
+> Official React Native SDK for Playbasis gamification integration
+
+[![npm version](https://img.shields.io/npm/v/@foremost-ai/qwikcard-sdk.svg)](https://www.npmjs.com/package/@foremost-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 @foremost-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 @foremost-ai/qwikcard-sdk
+# or
+yarn link @foremost-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 @foremost-ai/qwikcard-sdk
+# or
+yarn add @foremost-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 '@foremost-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 '@foremost-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 '@foremost-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 '@foremost-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 '@foremost-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
+type QwikCardEventType =
+  | 'card.purchase' // Debit card transaction
+  | 'card.deposit' // Direct deposit
+  | 'card.atm' // ATM withdrawal
+  | 'qwikit.sent' // P2P transfer sent
+  | 'qwikit.received' // P2P transfer received
+  | 'referral.signup' // Friend signed up
+  | 'profile.complete'; // Profile completed
+```
+
+## 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.

package/SDK_HANDOVER_GUIDE.md

@@ -0,0 +1,129 @@
+# QwikCard SDK Handover Guide (v2.3.2)
+
+> [!NOTE]
+> This SDK is a **React Native Library**, not a standalone application. In v2.3.2, the primary UI is delivered via a **WebView-embedded Widget UI** (the Playbasis Widget SDK), while API calls remain on the React Native side.
+
+This document provides instructions for the Qwik team to integrate the latest Playbasis gamification experience into the QwikCard mobile SDK.
+
+## Overview of Changes
+
+The v2.3.2 update shifts the SDK to a **WebView + bridge** architecture, focused on:
+
+- **One-Line Integration**: Use `<QwikCardApp />` to render the full experience.
+- **Widget UI Parity**: UI comes from the Playbasis Widget SDK (web UI) embedded into the RN SDK.
+- **Direct-to-Tenant Support**: Calls go through APIM using `Ocp-Apim-Subscription-Key` + `X-Tenant-ID` headers (configured via props).
+- **Key Handling**: The APIM subscription key stays in React Native; the WebView requests data via a message bridge.
+- **Bundle Workflow**: See [QWIK_SDK_BUNDLE_WORKFLOW.md](../../QWIK_SDK_BUNDLE_WORKFLOW.md) for the slim bundle + PLAY tab shipping checklist.
+
+## 📦 Changeset Summary
+
+### Key Implementation Notes
+
+- `QwikCardApp` now renders a `react-native-webview` with embedded Widget SDK assets.
+- The WebView requests bootstrap data (player, balances, quests, badges) from React Native via a REQUEST/RESPONSE message bridge.
+
+## 📦 Installation (Private Distribution)
+
+To maintain privacy while ensuring "ease of use," we recommend one of the following methods for integrating the SDK into your project:
+
+### 1. Local Package Installation (Recommended for Testing)
+
+You can install the provided tarball directly into your mSDK project:
+
+```bash
+npm install ./path/to/qwikcard-sdk-v2.3.2.tar.gz
+```
+
+This adds the SDK to your `node_modules` and `package.json` just like a public package.
+
+### 2. Private Git Dependency
+
+If you host this in a private repository, you can install it directly via SSH:
+
+```bash
+npm install git+ssh://git@github.com:your-org/qwikcard-sdk.git#v2.3.2
+```
+
+### 3. Private Registry (GitHub Packages) - RECOMMENDED
+
+For the most professional "NPM experience" without public exposure, use **GitHub Packages**. This allows your team to use standard NPM commands while maintaining 100% privacy:
+
+1.  **Publish to GitHub**: Configure your `package.json` to point to the `@rzforemost` scope on GitHub.
+2.  **Install via NPM**:
+    ```bash
+    npm install @foremost-ai/qwikcard-sdk
+    ```
+    _(Note: Requires a `.npmrc` file with a GitHub Personal Access Token)._
+
+## 🛠️ One-Line Integration (Component as a "Method")
+
+If your team prefers an "invocation" style, simply wrap the `QwikCardApp` in a single screen or a conditional overlay. This effectively "invokes" the entire template library in one line:
+
+```tsx
+import { QwikCardApp } from '@foremost-ai/qwikcard-sdk';
+
+const MyScreen = () => (
+  <QwikCardApp
+    apiKey="YOUR_API_KEY"
+    tenantId="YOUR_TENANT_ID"
+    playerId="USER_123"
+    baseUrl="https://api.playbasis.com" // optional
+    leaderboardId="YOUR_LEADERBOARD_ID" // optional
+  />
+);
+```
+
+## 🛠️ Integration Notes
+
+- Ensure your host app installs `react-native-webview` (peer dependency).
+- If your host app uses strict network allowlists / ATS settings, ensure the APIM base URL is permitted.
+
+## 🌐 Targeting Web (Vite/Next.js)
+
+The SDK exports React Native components/hooks as well. If you use those exports in a web project (like Vite or Next.js), you must use **`react-native-web`** to alias the components:
+
+1.  **Install Aliases**: `npm install react-native-web`
+2.  **Configure Vite**:
+    ```javascript
+    // vite.config.ts
+    resolve: {
+      alias: {
+        'react-native': 'react-native-web',
+      }
+    }
+    ```
+
+## 🧪 Verification Plan
+
+Before deployment, verify the following:
+
+1.  **WebView Renders**: The Widget UI loads and is interactive.
+2.  **Bootstrap Bridge**: Player/balances/quests/badges show up (no infinite loading).
+3.  **Key Safety**: `apiKey` is only provided to the React Native layer (not persisted inside the WebView).
+
+Current limitations (v2.2.7):
+
+- Leaderboard data requires passing a concrete `leaderboardId`. If omitted, the widget will show an empty leaderboard section.
+- Activity chart data is returned as an empty array unless/until an activity endpoint is provided.
+
+## 🚨 Troubleshooting
+
+### "Failed to resolve entry for package"
+
+Ensure you are using v2.3.2 which includes the compiled `dist/` folder. If you are building from source, ensure your bundler is configured to transpile `.ts` files inside `node_modules`.
+
+### "Failed to resolve import 'react-dom/client'"
+
+This typically happens if your web project is missing the `react-dom` dependency. Ensure it is installed:
+
+```bash
+npm install react react-dom
+```
+
+### "Can't find variable: Text/View"
+
+This means `react-native-web` is not correctly aliased in your bundler. Ensure the alias is set up so that the web project knows how to render native components.
+
+---
+
+_For technical support during integration, contact the Playbasis Engineering Team._

package/dist/PlaybasisProvider.d.ts

@@ -0,0 +1,19 @@
+import type { ReactNode } from 'react';
+import { PlaybasisClient } from './api/client';
+interface PlaybasisContextValue {
+    client: PlaybasisClient;
+    tenantId: string;
+    playerId: string | null;
+    baseUrl: string;
+}
+interface PlaybasisProviderProps {
+    children: ReactNode;
+    apiKey: string;
+    tenantId?: string;
+    playerId?: string;
+    baseUrl?: string;
+}
+export declare function PlaybasisProvider({ children, apiKey, tenantId, playerId, baseUrl, }: PlaybasisProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function usePlaybasis(): PlaybasisContextValue;
+export default PlaybasisProvider;
+//# sourceMappingURL=PlaybasisProvider.d.ts.map

package/dist/PlaybasisProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PlaybasisProvider.d.ts","sourceRoot":"","sources":["../src/PlaybasisProvider.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAO/C,UAAU,qBAAqB;IAC7B,MAAM,EAAE,eAAe,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;CACjB;AAQD,UAAU,sBAAsB;IAC9B,QAAQ,EAAE,SAAS,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAMD,wBAAgB,iBAAiB,CAAC,EAChC,QAAQ,EACR,MAAM,EACN,QAAqB,EACrB,QAAQ,EACR,OAAuD,GACxD,EAAE,sBAAsB,2CAgBxB;AAMD,wBAAgB,YAAY,IAAI,qBAAqB,CAMpD;AAED,eAAe,iBAAiB,CAAC"}

package/dist/PlaybasisProvider.js

@@ -0,0 +1,24 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useMemo } from 'react';
+import { PlaybasisClient } from './api/client';
+import { ThemeProvider } from './theme/context';
+const PlaybasisContext = createContext(null);
+// ─────────────────────────────────────────────────────────────────────────────
+// Provider Component
+// ─────────────────────────────────────────────────────────────────────────────
+export function PlaybasisProvider({ children, apiKey, tenantId = 'qwikcard', playerId, baseUrl = 'https://apim-pb-production.azure-api.net/v1', }) {
+    const client = useMemo(() => new PlaybasisClient({ apiKey, tenantId, baseUrl }), [apiKey, tenantId, baseUrl]);
+    const value = useMemo(() => ({ client, tenantId, playerId: playerId ?? null, baseUrl }), [client, tenantId, playerId, baseUrl]);
+    return (_jsx(ThemeProvider, { children: _jsx(PlaybasisContext.Provider, { value: value, children: children }) }));
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Hook
+// ─────────────────────────────────────────────────────────────────────────────
+export function usePlaybasis() {
+    const context = useContext(PlaybasisContext);
+    if (!context) {
+        throw new Error('usePlaybasis must be used within a PlaybasisProvider');
+    }
+    return context;
+}
+export default PlaybasisProvider;

package/dist/QwikCardApp.d.ts

@@ -0,0 +1,9 @@
+export interface QwikCardAppProps {
+    apiKey: string;
+    tenantId: string;
+    playerId: string;
+    baseUrl?: string;
+    leaderboardId?: string;
+}
+export declare function QwikCardApp(props: QwikCardAppProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=QwikCardApp.d.ts.map

package/dist/QwikCardApp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"QwikCardApp.d.ts","sourceRoot":"","sources":["../src/QwikCardApp.tsx"],"names":[],"mappings":"AASA,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAwRD,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,2CAMlD"}