npm package: @rajeev02/app-shell
Description: Feature-Slice app architecture — API client, navigation, onboarding, chat, video, forms, cart, state, analytics
Author: Rajeev Kumar Joshi
Latest version: 0.2.1

# @rajeev02/app-shell

[![npm version](https://img.shields.io/npm/v/@rajeev02/app-shell.svg)](https://www.npmjs.com/package/@rajeev02/app-shell)
[![license](https://img.shields.io/npm/l/@rajeev02/app-shell.svg)](https://github.com/Rajeev02/rajeev-sdk/blob/main/LICENSE)

**Feature-slice app architecture** with API client, onboarding, chat, cart & checkout (GST), feature flags, multi-step forms with Indian ID validation, and analytics.

Part of [Rajeev SDK](https://github.com/Rajeev02/rajeev-sdk) — cross-platform infrastructure libraries for building apps that work everywhere.

## Why use this?

- **API client** — Offline-first HTTP client with caching (cache-first, stale-while-revalidate), retry, interceptors
- **Cart & checkout** — Add items, apply coupons, calculate GST, generate order summaries
- **Feature flags** — Enable/disable features at runtime with percentage rollouts, user targeting, A/B variants
- **Onboarding** — Configurable onboarding slides with progress tracking and completion callbacks
- **Chat engine** — Real-time messaging with typing indicators, read receipts, and message history
- **Form engine** — Multi-step forms with Indian ID validation (Aadhaar, PAN, IFSC, GSTIN, pincode)
- **Analytics** — Event tracking with session management, user properties, and batched uploads

## ⚠️ Important: Backend Services Required

This is a **client-side orchestration layer** — it manages state, caching, and offline queues. Several modules require your own backend services:

| Module               | Backend required? | What you need                                                                                                                                   |
| -------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `ApiClient`          | **Yes**           | Your REST API server (set as `baseUrl`)                                                                                                         |
| `ChatEngine`         | **Yes**           | WebSocket or real-time server ([Firebase](https://firebase.google.com), [Ably](https://ably.com), [Socket.io](https://socket.io))               |
| `AnalyticsEngine`    | **Yes**           | Analytics endpoint or service ([Mixpanel](https://mixpanel.com), [Amplitude](https://amplitude.com), [PostHog](https://posthog.com), or custom) |
| `FeatureFlagManager` | **Yes**           | Feature flag service ([LaunchDarkly](https://launchdarkly.com), [Unleash](https://www.getunleash.io/), or custom API)                           |
| `FormEngine`         | **Yes**           | Form submission endpoint (`onSubmit` callback)                                                                                                  |
| `CartManager`        | **No**            | Client-side state only (GST calculation, coupons)                                                                                               |
| `OnboardingManager`  | **No**            | Client-side state only (slide progress, completion)                                                                                             |

**How callbacks work:** Modules like `ApiClient`, `ChatEngine`, and `AnalyticsEngine` accept configuration callbacks (`onRefreshToken`, `onFlush`, `onSubmit`) that call **your backend endpoints**. The library manages retry, caching, and offline queuing around them.

## Platform Support

| Platform   | Engine     | Status |
| ---------- | ---------- | ------ |
| iOS 16+    | TypeScript | ✅     |
| Android 7+ | TypeScript | ✅     |
| Web        | TypeScript | ✅     |

## Installation

```bash
npm install @rajeev02/app-shell
```

### Peer Dependencies

- `react` >= 18.3.0
- `react-native` >= 0.84.0 _(optional)_

## Quick Start

### API Client

```typescript
import { ApiClient } from "@rajeev02/app-shell";

const api = new ApiClient({
  baseUrl: "https://api.example.com",
  timeout: 30_000,
  retries: 3,
  cacheStrategy: "stale-while-revalidate",
});

// Add auth interceptor
api.addRequestInterceptor((config) => ({
  ...config,
  headers: { ...config.headers, Authorization: `Bearer ${token}` },
}));

// Make requests
const users = await api.get("/users", { page: 1 });
const order = await api.post("/orders", { items: [...] });
```

### Cart & Checkout

```typescript
import { CartManager } from "@rajeev02/app-shell";

const cart = new CartManager({ gstRate: 0.18, currency: "INR" });

cart.addItem({ id: "1", name: "iPhone 16", price: 79_999, quantity: 1 });
cart.addItem({ id: "2", name: "AirPods Pro", price: 24_999, quantity: 1 });

cart.applyCoupon({ code: "SAVE10", discountPercent: 10 });

const summary = cart.getSummary();
// → {
//     items: 2,
//     subtotal: 104998,
//     gst: 18899,
//     discount: -10499,
//     total: 113398
//   }
```

### Feature Flags

```typescript
import { FeatureFlagManager } from "@rajeev02/app-shell";

const flags = new FeatureFlagManager();

flags.register({
  id: "new_checkout",
  name: "New Checkout Flow",
  enabled: true,
  rolloutPercentage: 50, // 50% of users
  targetUsers: ["beta-group"],
  variants: {
    control: { buttonColor: "blue" },
    treatment: { buttonColor: "green" },
  },
});

if (flags.isEnabled("new_checkout", userId)) {
  const variant = flags.getVariant("new_checkout", userId);
  // → "control" or "treatment"
}
```

### Forms with Indian ID Validation

```typescript
import { FormEngine, getKycFormConfig } from "@rajeev02/app-shell";

const form = new FormEngine(getKycFormConfig());

// Built-in Indian ID validators
form.validateField("aadhaar", "1234 5678 9012"); // → { valid: true }
form.validateField("pan", "ABCPE1234F"); // → { valid: true }
form.validateField("ifsc", "SBIN0001234"); // → { valid: true }
form.validateField("gstin", "22ABCDE1234F1Z5"); // → { valid: true }
form.validateField("pincode", "560001"); // → { valid: true }

// Multi-step form navigation
form.nextStep();
form.prevStep();
const progress = form.getProgress(); // → { current: 2, total: 4, percent: 50 }
```

### Chat Engine

```typescript
import { ChatEngine } from "@rajeev02/app-shell";

const chat = new ChatEngine({
  userId: "user-123",
  onMessageReceived: (msg) => updateUI(msg),
  onTypingStatusChanged: (userId, isTyping) =>
    showTypingIndicator(userId, isTyping),
});

chat.sendMessage({
  roomId: "support",
  text: "Hi, I need help with my order",
  type: "text",
});

chat.markAsRead("support", "msg-001");
chat.setTyping("support", true);
```

### Analytics

```typescript
import { AnalyticsEngine } from "@rajeev02/app-shell";

const analytics = new AnalyticsEngine({
  endpoint: "https://analytics.example.com/events",
  batchSize: 20,
  flushIntervalMs: 30_000,
});

analytics.setUserId("user-123");
analytics.setUserProperties({ plan: "pro", city: "Bengaluru" });

analytics.track("purchase_completed", {
  amount: 999,
  currency: "INR",
  method: "upi",
});

analytics.trackScreen("HomeScreen");
```

## Modules

| Module               | Description                                   |
| -------------------- | --------------------------------------------- |
| `ApiClient`          | HTTP client with caching, retry, interceptors |
| `CartManager`        | Cart with GST, coupons, order summaries       |
| `FeatureFlagManager` | Feature flags, A/B testing, rollouts          |
| `OnboardingManager`  | Configurable onboarding flow                  |
| `ChatEngine`         | Real-time messaging                           |
| `FormEngine`         | Multi-step forms with Indian ID validation    |
| `AnalyticsEngine`    | Event tracking and session management         |

## Indian ID Validators

| Validator | Format        | Example           |
| --------- | ------------- | ----------------- |
| Aadhaar   | 12 digits     | `1234 5678 9012`  |
| PAN       | `AAAAA0000A`  | `ABCPE1234F`      |
| IFSC      | `AAAA0000000` | `SBIN0001234`     |
| GSTIN     | 15 chars      | `22ABCDE1234F1Z5` |
| Pincode   | 6 digits      | `560001`          |
| Phone     | 10 digits     | `9876543210`      |

## Full Documentation

📖 [Complete API docs with all modules and types](https://github.com/Rajeev02/rajeev-sdk/blob/main/docs/usage/APP-SHELL.md)

## License

MIT © 2026 [Rajeev Kumar Joshi](https://rajeev02.github.io)