@rajeev02/app-shell 0.1.0

package/src/analytics/index.ts

@@ -0,0 +1,92 @@
+/**
+ * @rajeev02/app-shell — Analytics Pipeline
+ * Event tracking, user properties, funnel analysis, offline buffer
+ */
+
+export interface AnalyticsEvent {
+  name: string;
+  properties?: Record<string, unknown>;
+  timestamp: number;
+  sessionId: string;
+}
+
+export interface AnalyticsConfig {
+  /** Flush events to server handler */
+  onFlush: (events: AnalyticsEvent[]) => Promise<void>;
+  /** Flush interval in ms (default: 30000) */
+  flushIntervalMs?: number;
+  /** Max batch size (default: 50) */
+  maxBatchSize?: number;
+  /** Whether to track automatically (screen views, etc.) */
+  autoTrack?: boolean;
+}
+
+export class AnalyticsEngine {
+  private config: AnalyticsConfig;
+  private buffer: AnalyticsEvent[] = [];
+  private userProperties: Record<string, unknown> = {};
+  private sessionId: string;
+  private flushTimer: ReturnType<typeof setInterval> | null = null;
+
+  constructor(config: AnalyticsConfig) {
+    this.config = {
+      flushIntervalMs: 30000,
+      maxBatchSize: 50,
+      autoTrack: true,
+      ...config,
+    };
+    this.sessionId = `sess_${Date.now()}_${Math.random().toString(36).substr(2, 6)}`;
+    this.startFlushTimer();
+  }
+
+  /** Track an event */
+  track(name: string, properties?: Record<string, unknown>): void {
+    this.buffer.push({
+      name,
+      properties: { ...this.userProperties, ...properties },
+      timestamp: Date.now(),
+      sessionId: this.sessionId,
+    });
+    if (this.buffer.length >= (this.config.maxBatchSize ?? 50)) this.flush();
+  }
+
+  /** Set user properties (included in all future events) */
+  setUserProperties(props: Record<string, unknown>): void {
+    Object.assign(this.userProperties, props);
+  }
+
+  /** Track screen view */
+  trackScreen(screenName: string, properties?: Record<string, unknown>): void {
+    this.track("screen_view", { screen_name: screenName, ...properties });
+  }
+
+  /** Flush events to server */
+  async flush(): Promise<void> {
+    if (this.buffer.length === 0) return;
+    const batch = [...this.buffer];
+    this.buffer = [];
+    try {
+      await this.config.onFlush(batch);
+    } catch {
+      this.buffer = [...batch, ...this.buffer];
+    }
+  }
+
+  /** Get buffer size */
+  getBufferSize(): number {
+    return this.buffer.length;
+  }
+
+  /** Destroy — flush and stop timer */
+  async destroy(): Promise<void> {
+    if (this.flushTimer) clearInterval(this.flushTimer);
+    await this.flush();
+  }
+
+  private startFlushTimer(): void {
+    this.flushTimer = setInterval(
+      () => this.flush(),
+      this.config.flushIntervalMs ?? 30000,
+    );
+  }
+}

package/src/api/index.ts

@@ -0,0 +1,322 @@
+/**
+ * @rajeev02/app-shell — API Client
+ * Offline-first API layer with interceptors, token refresh, retry, cache-first strategy
+ */
+
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+export type CacheStrategy =
+  | "network_first"
+  | "cache_first"
+  | "network_only"
+  | "cache_only"
+  | "stale_while_revalidate";
+
+export interface ApiConfig {
+  baseUrl: string;
+  timeout?: number;
+  defaultHeaders?: Record<string, string>;
+  /** Get current access token */
+  getToken?: () => Promise<string | null>;
+  /** Refresh token when 401 received */
+  onRefreshToken?: () => Promise<string | null>;
+  /** Called on network error (for queueing) */
+  onNetworkError?: (request: ApiRequest) => void;
+  /** Default cache strategy */
+  defaultCacheStrategy?: CacheStrategy;
+  /** Default cache TTL in seconds */
+  defaultCacheTtl?: number;
+}
+
+export interface ApiRequest {
+  method: HttpMethod;
+  path: string;
+  body?: unknown;
+  headers?: Record<string, string>;
+  query?: Record<string, string>;
+  cacheStrategy?: CacheStrategy;
+  cacheTtl?: number;
+  retryCount?: number;
+  maxRetries?: number;
+  tag?: string;
+}
+
+export interface ApiResponse<T = unknown> {
+  data: T;
+  status: number;
+  headers: Record<string, string>;
+  fromCache: boolean;
+  duration: number;
+}
+
+export interface RequestInterceptor {
+  name: string;
+  onRequest: (request: ApiRequest) => ApiRequest | Promise<ApiRequest>;
+}
+
+export interface ResponseInterceptor {
+  name: string;
+  onResponse: (response: ApiResponse) => ApiResponse | Promise<ApiResponse>;
+  onError?: (error: unknown, request: ApiRequest) => unknown;
+}
+
+/**
+ * Offline-First API Client
+ */
+export class ApiClient {
+  private config: ApiConfig;
+  private requestInterceptors: RequestInterceptor[] = [];
+  private responseInterceptors: ResponseInterceptor[] = [];
+  private pendingRequests: Map<string, ApiRequest> = new Map();
+  private cache: Map<string, { response: ApiResponse; expiresAt: number }> =
+    new Map();
+  private isRefreshing: boolean = false;
+  private refreshQueue: ((token: string | null) => void)[] = [];
+
+  constructor(config: ApiConfig) {
+    this.config = {
+      timeout: 15000,
+      defaultCacheStrategy: "network_first",
+      defaultCacheTtl: 300,
+      ...config,
+    };
+  }
+
+  /** Add request interceptor */
+  addRequestInterceptor(interceptor: RequestInterceptor): void {
+    this.requestInterceptors.push(interceptor);
+  }
+
+  /** Add response interceptor */
+  addResponseInterceptor(interceptor: ResponseInterceptor): void {
+    this.responseInterceptors.push(interceptor);
+  }
+
+  /** Main request method */
+  async request<T = unknown>(req: ApiRequest): Promise<ApiResponse<T>> {
+    let request = {
+      ...req,
+      retryCount: req.retryCount ?? 0,
+      maxRetries: req.maxRetries ?? 2,
+    };
+    const strategy =
+      request.cacheStrategy ??
+      this.config.defaultCacheStrategy ??
+      "network_first";
+    const cacheKey = this.getCacheKey(request);
+
+    // Run request interceptors
+    for (const interceptor of this.requestInterceptors) {
+      const intercepted = await interceptor.onRequest(request);
+      request = {
+        ...intercepted,
+        retryCount: intercepted.retryCount ?? request.retryCount,
+        maxRetries: intercepted.maxRetries ?? request.maxRetries,
+      };
+    }
+
+    // Cache strategies
+    if (strategy === "cache_only" || strategy === "cache_first") {
+      const cached = this.getFromCache<T>(cacheKey);
+      if (cached) return cached;
+      if (strategy === "cache_only") {
+        throw new Error("No cached response available");
+      }
+    }
+
+    if (strategy === "stale_while_revalidate") {
+      const cached = this.getFromCache<T>(cacheKey);
+      // Return stale cache immediately, revalidate in background
+      if (cached) {
+        this.fetchFromNetwork<T>(request, cacheKey).catch(() => {});
+        return cached;
+      }
+    }
+
+    try {
+      const response = await this.fetchFromNetwork<T>(request, cacheKey);
+      return response;
+    } catch (error) {
+      // On network error, try cache as fallback
+      if (strategy === "network_first") {
+        const cached = this.getFromCache<T>(cacheKey);
+        if (cached) return cached;
+      }
+      // Queue for later if offline
+      if (this.config.onNetworkError && request.method !== "GET") {
+        this.config.onNetworkError(request);
+      }
+      throw error;
+    }
+  }
+
+  // Convenience methods
+  async get<T = unknown>(
+    path: string,
+    query?: Record<string, string>,
+    options?: Partial<ApiRequest>,
+  ): Promise<ApiResponse<T>> {
+    return this.request<T>({ method: "GET", path, query, ...options });
+  }
+  async post<T = unknown>(
+    path: string,
+    body?: unknown,
+    options?: Partial<ApiRequest>,
+  ): Promise<ApiResponse<T>> {
+    return this.request<T>({ method: "POST", path, body, ...options });
+  }
+  async put<T = unknown>(
+    path: string,
+    body?: unknown,
+    options?: Partial<ApiRequest>,
+  ): Promise<ApiResponse<T>> {
+    return this.request<T>({ method: "PUT", path, body, ...options });
+  }
+  async patch<T = unknown>(
+    path: string,
+    body?: unknown,
+    options?: Partial<ApiRequest>,
+  ): Promise<ApiResponse<T>> {
+    return this.request<T>({ method: "PATCH", path, body, ...options });
+  }
+  async delete<T = unknown>(
+    path: string,
+    options?: Partial<ApiRequest>,
+  ): Promise<ApiResponse<T>> {
+    return this.request<T>({ method: "DELETE", path, ...options });
+  }
+
+  /** Clear API cache */
+  clearCache(): void {
+    this.cache.clear();
+  }
+
+  /** Get pending (queued) requests count */
+  getPendingCount(): number {
+    return this.pendingRequests.size;
+  }
+
+  private async fetchFromNetwork<T>(
+    request: ApiRequest,
+    cacheKey: string,
+  ): Promise<ApiResponse<T>> {
+    const start = Date.now();
+    const url = this.buildUrl(request);
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+      ...this.config.defaultHeaders,
+      ...request.headers,
+    };
+
+    // Add auth token
+    if (this.config.getToken) {
+      const token = await this.config.getToken();
+      if (token) headers["Authorization"] = `Bearer ${token}`;
+    }
+
+    const fetchOptions: RequestInit = { method: request.method, headers };
+    if (request.body && request.method !== "GET") {
+      fetchOptions.body = JSON.stringify(request.body);
+    }
+
+    const httpResponse = await fetch(url, fetchOptions);
+
+    // Handle 401 — token expired
+    if (httpResponse.status === 401 && this.config.onRefreshToken) {
+      const newToken = await this.handleTokenRefresh();
+      if (newToken) {
+        headers["Authorization"] = `Bearer ${newToken}`;
+        const retryResponse = await fetch(url, { ...fetchOptions, headers });
+        return this.processResponse<T>(retryResponse, cacheKey, start);
+      }
+    }
+
+    return this.processResponse<T>(httpResponse, cacheKey, start);
+  }
+
+  private async processResponse<T>(
+    httpResponse: Response,
+    cacheKey: string,
+    start: number,
+  ): Promise<ApiResponse<T>> {
+    const data = (await httpResponse.json()) as T;
+    const responseHeaders: Record<string, string> = {};
+    httpResponse.headers.forEach((v, k) => {
+      responseHeaders[k] = v;
+    });
+
+    let response: ApiResponse<T> = {
+      data,
+      status: httpResponse.status,
+      headers: responseHeaders,
+      fromCache: false,
+      duration: Date.now() - start,
+    };
+
+    // Run response interceptors
+    for (const interceptor of this.responseInterceptors) {
+      response = (await interceptor.onResponse(
+        response as ApiResponse,
+      )) as ApiResponse<T>;
+    }
+
+    // Cache successful GET responses
+    if (httpResponse.ok) {
+      const ttl = this.config.defaultCacheTtl ?? 300;
+      this.cache.set(cacheKey, {
+        response: response as ApiResponse,
+        expiresAt: Date.now() + ttl * 1000,
+      });
+    }
+
+    if (!httpResponse.ok) {
+      throw {
+        status: httpResponse.status,
+        data,
+        message: `HTTP ${httpResponse.status}`,
+      };
+    }
+
+    return response;
+  }
+
+  private async handleTokenRefresh(): Promise<string | null> {
+    if (this.isRefreshing) {
+      return new Promise((resolve) => {
+        this.refreshQueue.push(resolve);
+      });
+    }
+    this.isRefreshing = true;
+    try {
+      const token = await this.config.onRefreshToken!();
+      this.refreshQueue.forEach((cb) => cb(token));
+      this.refreshQueue = [];
+      return token;
+    } finally {
+      this.isRefreshing = false;
+    }
+  }
+
+  private getFromCache<T>(key: string): ApiResponse<T> | null {
+    const entry = this.cache.get(key);
+    if (!entry) return null;
+    if (entry.expiresAt < Date.now()) {
+      this.cache.delete(key);
+      return null;
+    }
+    return { ...entry.response, fromCache: true } as ApiResponse<T>;
+  }
+
+  private getCacheKey(req: ApiRequest): string {
+    const queryStr = req.query ? JSON.stringify(req.query) : "";
+    return `${req.method}:${req.path}:${queryStr}`;
+  }
+
+  private buildUrl(req: ApiRequest): string {
+    let url = `${this.config.baseUrl}${req.path}`;
+    if (req.query) {
+      const params = new URLSearchParams(req.query).toString();
+      if (params) url += `?${params}`;
+    }
+    return url;
+  }
+}

package/src/cart/index.ts

@@ -0,0 +1,213 @@
+/**
+ * @rajeev02/app-shell — Cart & Checkout
+ * Cart management, address, coupons, order tracking
+ */
+
+export interface CartItem {
+  id: string;
+  productId: string;
+  name: string;
+  imageUrl?: string;
+  price: number;
+  quantity: number;
+  maxQuantity?: number;
+  variant?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface CartSummary {
+  items: CartItem[];
+  subtotal: number;
+  discount: number;
+  tax: number;
+  deliveryFee: number;
+  total: number;
+  couponCode?: string;
+  itemCount: number;
+}
+
+export interface Address {
+  id: string;
+  label?: string;
+  fullName: string;
+  phone: string;
+  line1: string;
+  line2?: string;
+  city: string;
+  state: string;
+  pincode: string;
+  isDefault: boolean;
+  latitude?: number;
+  longitude?: number;
+}
+
+export type OrderStatus =
+  | "created"
+  | "confirmed"
+  | "processing"
+  | "shipped"
+  | "out_for_delivery"
+  | "delivered"
+  | "cancelled"
+  | "returned"
+  | "refunded";
+
+export interface Order {
+  id: string;
+  items: CartItem[];
+  address: Address;
+  status: OrderStatus;
+  paymentMethod: string;
+  paymentStatus: "pending" | "paid" | "failed" | "refunded";
+  subtotal: number;
+  discount: number;
+  tax: number;
+  deliveryFee: number;
+  total: number;
+  couponCode?: string;
+  trackingId?: string;
+  createdAt: number;
+  updatedAt: number;
+  estimatedDelivery?: string;
+}
+
+/**
+ * Cart Manager
+ */
+export class CartManager {
+  private items: Map<string, CartItem> = new Map();
+  private couponCode: string | null = null;
+  private couponDiscount: number = 0;
+  private taxRate: number = 0.18; // 18% GST
+  private deliveryFee: number = 0;
+  private listeners: Set<() => void> = new Set();
+
+  /** Add item to cart */
+  add(item: Omit<CartItem, "quantity">, quantity: number = 1): void {
+    const existing = this.items.get(item.id);
+    if (existing) {
+      existing.quantity = Math.min(
+        existing.quantity + quantity,
+        existing.maxQuantity ?? 99,
+      );
+    } else {
+      this.items.set(item.id, { ...item, quantity });
+    }
+    this.notify();
+  }
+
+  /** Update quantity */
+  updateQuantity(itemId: string, quantity: number): void {
+    const item = this.items.get(itemId);
+    if (item) {
+      if (quantity <= 0) {
+        this.items.delete(itemId);
+      } else {
+        item.quantity = Math.min(quantity, item.maxQuantity ?? 99);
+      }
+      this.notify();
+    }
+  }
+
+  /** Remove item */
+  remove(itemId: string): void {
+    this.items.delete(itemId);
+    this.notify();
+  }
+
+  /** Clear cart */
+  clear(): void {
+    this.items.clear();
+    this.couponCode = null;
+    this.couponDiscount = 0;
+    this.notify();
+  }
+
+  /** Apply coupon */
+  applyCoupon(code: string, discountAmount: number): void {
+    this.couponCode = code;
+    this.couponDiscount = discountAmount;
+    this.notify();
+  }
+
+  /** Remove coupon */
+  removeCoupon(): void {
+    this.couponCode = null;
+    this.couponDiscount = 0;
+    this.notify();
+  }
+
+  /** Set delivery fee */
+  setDeliveryFee(fee: number): void {
+    this.deliveryFee = fee;
+  }
+
+  /** Get cart summary */
+  getSummary(): CartSummary {
+    const items = Array.from(this.items.values());
+    const subtotal = items.reduce((sum, i) => sum + i.price * i.quantity, 0);
+    const discount = this.couponDiscount;
+    const taxable = subtotal - discount;
+    const tax = Math.max(0, taxable * this.taxRate);
+    const total = Math.max(0, taxable + tax + this.deliveryFee);
+
+    return {
+      items,
+      subtotal,
+      discount,
+      tax,
+      deliveryFee: this.deliveryFee,
+      total,
+      couponCode: this.couponCode ?? undefined,
+      itemCount: items.reduce((sum, i) => sum + i.quantity, 0),
+    };
+  }
+
+  /** Check if cart is empty */
+  isEmpty(): boolean {
+    return this.items.size === 0;
+  }
+
+  /** Get item count */
+  getItemCount(): number {
+    return Array.from(this.items.values()).reduce(
+      (sum, i) => sum + i.quantity,
+      0,
+    );
+  }
+
+  /** Subscribe to cart changes */
+  onChange(listener: () => void): () => void {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+
+  /** Export cart for persistence */
+  export(): Record<string, unknown> {
+    return {
+      items: Array.from(this.items.values()),
+      couponCode: this.couponCode,
+      couponDiscount: this.couponDiscount,
+    };
+  }
+
+  /** Import cart from persistence */
+  import(data: Record<string, unknown>): void {
+    if (Array.isArray(data.items)) {
+      for (const item of data.items as CartItem[]) {
+        this.items.set(item.id, item);
+      }
+    }
+    if (typeof data.couponCode === "string") this.couponCode = data.couponCode;
+    if (typeof data.couponDiscount === "number")
+      this.couponDiscount = data.couponDiscount;
+  }
+
+  private notify(): void {
+    for (const l of this.listeners) {
+      try {
+        l();
+      } catch {}
+    }
+  }
+}