Stealpk

Pakistan's #1 Digital Bazaar for Discounted Subscriptions, Software Licences, Streaming Deals & BOGO Bundles.
Engineered around physical price tags, payment slips, and official printed paper receipts.

StealPK is a full-stack, mobile-first e-commerce web application designed for publishing, purchasing, and tracking discounted digital subscriptions and digital vouchers in Pakistan. Built with a 100% static frontend (React + Vite + Tailwind CSS) and powered directly by Firebase Realtime Database (RTDB) and Firebase Authentication — requiring zero paid servers, zero Firestore, and zero Firebase Storage.

🏷️ Deal Tag Types Explained

In StealPK, every product listing is modeled as a physical marketplace Price Tag with a distinct deal structure and visual badge:

| Tag Type | Badge / Stamp | Meaning & Customer Experience | |---|---|---| | 1. Standard Discount (standard) | 🟡 Mustard Tag (-67% OFF) | A standalone digital subscription or tool offered at a steep markdown from retail market price (e.g., Netflix 1-Month for Rs. 499 instead of Rs. 1,500). Displays the original price crossed out with a red slash line and highlights the exact cash savings (e.g., SAVE Rs. 1,001). | | 2. BOGO Bundle Deal (bogo) | 🔴 Cherry Red Stamp (BOGO DEAL) | "Buy One, Get One" (or Buy N, Get M Free) promotional bundle. When a customer purchases the primary deal (e.g., YouTube Premium 6 Months), they automatically receive an attached bonus digital subscription (e.g., Prime Video 1 Month) included at Rs. 0. The card and receipt explicitly show the included bonus item. | | 3. 100% Free Giveaway (free) | 🟢 Bazaar Green Stamp (100% FREE) | A zero-cost community giveaway, free trial key, or promotional offer priced at Rs. 0. Displays a bold FREE label. Customers can claim it through the checkout docket without uploading bank payment proof. Ideal for giveaways and user acquisition. |

✨ Features Overview

🛍️ 1. Public Storefront (Bazaar Price-Tag Design)

• 5-Column Wide Grid Layout: Optimized 5-item-per-row responsive grid (xl:grid-cols-5) inside an expanded 1600px container.
• Physical Price-Tag Cards: Warm paper cream card surfaces (#FAF6ED), punched string-holes, rotated stamped discount stickers (-67% OFF), and red hand-slashed original prices.
• Day / Night Theme Switcher: 2-segment high-contrast capsule toggle in the Navbar:
  • 🌙 Pine-Ink Night Market (Dark): Deep pine background (#0F2E22), warm paper cards, and mustard accents.
  • ☀️ Parchment Day Market (Light): Warm ivory background (#F7F4EC), white cards, and high-contrast dark ink text (#111827).
• Clean Humanist Typography: Clean, comfortable Inter font for headings, body copy, and labels, with Space Mono strictly reserved for numerical values, order numbers, and timestamps.
• Filter Tape & Category Rolls: Instant filtering by All Deals, Discounted Items, BOGO Bundles, and 100% Free Giveaways, with category tabs and multi-criteria sorting.
• Product Details Ticket: High-resolution image preview, terms of service, live stock counter, and direct WhatsApp inquiry triggers.
• Itemized Shopping Bag: Persistent cart with live inventory reconciliation and motivating "Total Savings" calculator.

💳 2. Pakistan-Optimized Checkout Flow

• Guest Checkout Docket: No mandatory account creation—customers checkout using Full Name, WhatsApp Mobile Number, and optional Email.
• Multiple Payment Channels:
  • 🏛️ Bank Transfer (IBAN): List of admin-configured bank accounts (Bank Name, Account Title, Account #, IBAN) with 1-click copy buttons.
  • ⚡ Raast Dynamic EMVCo QR: Generates real-time State Bank of Pakistan Raast/EMVCo-compliant QR codes via sendkardo-qr, encoding the exact cart total and receiver IBAN for instant scanning in Meezan, HBL, EasyPaisa, JazzCash, Nayapay, and SadaPay.
  • 💳 Card Payments: Sandbox card gateway simulation.
• Mandatory Payment Proof: Requires uploading a payment receipt screenshot OR entering a bank Transaction / Reference ID (TXN ID) before order placement.
• 100% Free In-Database Image Storage: Payment screenshots are automatically compressed to lightweight Base64 JPEG data URLs (~60-120KB) and saved directly into RTDB.

📦 3. Public Order Tracking (/track)

• Official Printed Receipt Strip: Styled with top & bottom perforated edges, barcode dividers, dot leaders, and monospace order numbers.
• Live Status Timeline: Real-time status progression (Pending Verification ➔ Processing ➔ Delivered or Cancelled).
• Merchant Dispatch Notes: Direct credentials and PIN delivery thread between store owner and customer on the tracking receipt.
• 1-Click WhatsApp Support: Pre-filled WhatsApp chat link with order details.

🛡️ 4. Merchant Admin Control Center (/admin)

• Secure Role-Based Access Control: Only users whose UID is explicitly granted true under /admins/{uid} in the Firebase Console can access the merchant panel.
• Performance Dashboard: 6 flattened price-tag metric cards (Total Orders, Pending Verification, Today's Sales, Low Stock, Active Offers, Expired Deals) + Recent Orders table.
• Catalog Management (CRUD):
  • Add/Edit items with live two-way price / discount % auto-calculators.
  • Unlimited stock toggle or exact inventory tracking.
  • BOGO ("Buy N Get M Free") and Free Giveaway rules.
  • Expiry Date/Time picker with automated expiration handling.
  • Bulk Discount Action: Apply mass percentage discounts across all items or specific categories in one click.
  • Fast Renewal: Re-publish expired deals with extended dates without losing historical analytics or item IDs.
• Order Management & Verification:
  • Filter by status, payment method, date range, or search by Order Number / Customer Name / Phone / TXN ID.
  • Inspect full-screen zoomable screenshot receipts and transaction IDs.
  • Change status with automated timestamped logging.
  • Post customer-visible notes and automatic stock return on cancellation.
• Payment Methods Manager: Full CRUD for Bank Transfer IBAN accounts, Raast QR settings, and card gateway toggles.
• Storefront Settings: Configure WhatsApp business support phone, processing time notice, low stock thresholds, and promotional tape banners.

🛠️ Technology Stack

| Layer | Technology | |---|---| | Frontend Framework | React 18 + Vite 6 (100% Static Single Page App) | | Routing | React Router DOM v6 | | Styling & Icons | Tailwind CSS + Lucide React Icons | | Typography | Inter (Headings & Body), Space Mono (Prices/Receipts/IDs) | | Database | Firebase Realtime Database (RTDB) (100% Free) | | Authentication | Firebase Auth (Email / Password) | | Image Storage | Client-Side Canvas Base64 Compression stored directly in RTDB (100% Free) | | QR Engine | sendkardo-qr (Official State Bank Raast EMVCo Standard) | | Deployment Target | Render Static Sites, Firebase Hosting, Netlify, or Vercel (Free Tier) |

🚀 Quick Start (Local Development)

1. Prerequisites

• Node.js v18 or higher
• npm v9 or higher

2. Installation

# Clone the repository
git clone https://github.com/your-username/stealpk.git
cd "Agnific - StealPK"

# Install dependencies
npm install

3. Environment Setup (Firebase Connection)

Copy .env.example to .env:

cp .env.example .env

Fill in your Firebase credentials in .env:

VITE_FIREBASE_API_KEY=AIzaSyBW8lnfHYpiyOery34Uqq-XYRcrA8XZ8NU
VITE_FIREBASE_AUTH_DOMAIN=stealpk-feb0f.firebaseapp.com
VITE_FIREBASE_DATABASE_URL=https://stealpk-feb0f-default-rtdb.firebaseio.com
VITE_FIREBASE_PROJECT_ID=stealpk-feb0f
VITE_FIREBASE_STORAGE_BUCKET=stealpk-feb0f.firebasestorage.app
VITE_FIREBASE_MESSAGING_SENDER_ID=160204602380
VITE_FIREBASE_APP_ID=1:160204602380:web:006b2b261b1a148ef58229

(If no .env is provided, StealPK automatically boots in interactive Local / Demo Mode with pre-seeded Pakistani subscription products, banks, and sample orders).

4. Run Locally

npm run dev

Open your browser at http://localhost:3000.

5. Build for Production

npm run build

The optimized static bundle will be built in the dist/ directory, ready to deploy.

📖 Deployment & Firebase Setup

For full instructions on configuring Firebase Realtime Database rules, setting up admin privileges, and deploying to Render Static Sites for free, refer to DEPLOY.md.

📄 License

MIT License. Built for StealPK Digital Deals Platform.