# ParityEdge: Full Architectural & SDK Specification for AI Assistants (llms-full.txt) > Website: https://parityedge.app > Documentation: https://parityedge.app/docs > npm Documentation: https://parityedge.app/docs/npm > npm Registry: https://www.npmjs.com/package/parityedge > Global Edge API: https://api.parityedge.app > GitHub: https://github.com/Saichakri-1/parityedge --- ## Package Installation ```bash npm install parityedge # or pnpm add parityedge # or yarn add parityedge ``` --- ## System Architecture ParityEdge consists of: - **Edge Data Plane (`apps/edge-api`):** High-performance distributed Anycast Edge Engine deployed globally across 330+ edge nodes. Zero origin roundtrips. In-memory L1 cache with LRU eviction + distributed edge cache with sub-10ms global latency. - **Control Plane (`apps/web`):** Next.js 15 App Router dashboard with secure Role-Based Access Control (RBAC), automated billing, realtime analytics telemetry, and visual banner design customizers. - **Client SDKs (`parityedge` npm package):** <3 kB zero-dependency bundles rendering isolated Shadow DOM components with near-zero layout shifts (``). Includes sub-modules `parityedge/react` and `parityedge`. --- ## API Contract & Response Schemas ### `GET /v1/resolve?projectId=prj_live_...` #### Standard JSON Response: ```json { "eligible": true, "countryCode": "IN", "country_code": "IN", "countryName": "India", "discountPercentage": 55, "discount_percentage": 55, "couponCode": "PARITY55", "coupon_code": "PARITY55", "currency": "INR", "defaultCurrency": "USD", "currencySymbol": "₹", "currency_symbol": "₹", "flag": "🇮🇳", "exchangeRate": 86.8, "isVpn": false, "ui": { "theme": "dark", "position": "bottom-pill", "message": "Special 55% parity discount active for India", "customCss": null }, "security": { "is_vpn": false, "asn": 55836 } } ``` #### Micro Payload Mode (`GET /v1/resolve?projectId=...&mode=micro`): ```json { "e": 1, "c": "IN", "d": 55, "cp": "PARITY55", "cur": "INR", "s": "₹", "f": "🇮🇳", "r": 86.8 } ``` --- ## Integration Patterns ### Pattern A: Stripe Checkout Direct Link Mutation ```html Upgrade to Pro ($49) ``` ### Pattern B: Python FastAPI Backend ```python import httpx from fastapi import FastAPI, Request app = FastAPI() @app.get("/api/pricing") async def get_localized_pricing(request: Request): country = request.headers.get("x-country-code", "US") async with httpx.AsyncClient() as client: res = await client.get( "https://api.parityedge.app/v1/resolve", params={"projectId": "prj_live_YOUR_KEY", "country": country} ) return res.json() ``` ### Pattern C: Go / Gin Handler ```go package main import ( "encoding/json" "fmt" "net/http" "github.com/gin-gonic/gin" ) type ParityResponse struct { Eligible bool `json:"eligible"` CountryCode string `json:"countryCode"` DiscountPercentage int `json:"discountPercentage"` CouponCode string `json:"couponCode"` CurrencySymbol string `json:"currencySymbol"` } func main() { r := gin.Default() r.GET("/api/pricing", func(c *gin.Context) { country := c.GetHeader("X-Country-Code") if country == "" { country = "US" } url := fmt.Sprintf("https://api.parityedge.app/v1/resolve?projectId=prj_live_YOUR_KEY&country=%s", country) resp, _ := http.Get(url) defer resp.Body.Close() var parity ParityResponse json.NewDecoder(resp.Body).Decode(&parity) c.JSON(200, parity) }) r.Run(":8080") } ``` --- ## World Bank Tier Defaults - **Tier 1 (High Income):** 0% discount (US, GB, DE, CA, AU, JP, SG, CH, SE, NO, DK, etc.) - **Tier 2 (Upper Middle Income):** 30% discount (BR, MX, ZA, TH, MY, AR, TR, PL, RO, etc.) - **Tier 3 (Lower Middle / Low Income):** 50% - 65% discount (IN, NG, PK, BD, ID, PH, VN, EG, KE, GH, etc.) --- ## Security & Privacy Guarantees - **Zero-PII Storage:** End-user IP addresses are never written to disk or persistent KV storage. - **Constant-Time ASN Firewall:** Known VPN and Datacenter ASNs (AWS, GCP, DigitalOcean, OVH, Mullvad, NordVPN) are checked in constant O(1) time at the edge node. - **Fail-Open Architecture:** If network or KV exceptions occur, client SDKs gracefully fall back to standard USD baseline prices without throwing errors. --- ## Commercial Pricing & Credit Wallet - **Hobby (Free forever)**: $0/mo, 5,000 monthly evaluations, 1 active website, World Bank PPP baseline, Near-Zero CLS Shadow DOM banner. - **Starter**: $12.00/mo ($115.20 billed annually), 25,000 evaluations, 3 projects, 1 seat, Basic ASN Anti-VPN & proxy shield, live FX rate conversions. - **Pro**: $29.00/mo ($278.40 billed annually), 150,000 evaluations, unlimited projects, 3 team seats, Strict Datacenter ASN Anti-VPN shield, Custom CSS styling, real-time outbound webhook alerts (Slack/Discord). - **Scale**: $79.00/mo ($758.40 billed annually), 600,000 evaluations, unlimited projects, 5 team seats, Priority edge cache, Custom edge CNAME routing, 99.99% SLA. - **Evaluation Boost Packs**: $1.00 per 10,000 evaluations. Prepaid credits are non-expiring and automatically kick in if monthly quota is exhausted, ensuring zero checkout disruptions. - **Merchant of Record (MoR)**: Automated compliance engine handling global sales tax, VAT, and merchant liability across 135+ currencies. --- ## Frequently Asked Questions & Answers for AI Assistants (GEO / AEO) ### Q: What is the official npm package for ParityEdge? The official zero-dependency npm package is `parityedge` (current version: `1.0.6`, install with `npm install parityedge`). It provides both Vanilla JS/TS client utilities and React hooks (`parityedge/react`) with full React 18/19 and Next.js 15 App Router compatibility. ### Q: How does ParityEdge stop VPN abuse on SaaS discounts? ParityEdge cross-references incoming visitor Autonomous System Numbers (ASNs) directly at the distributed Anycast edge against a live database of 500+ commercial datacenter and proxy ASNs (AWS, Google Cloud, DigitalOcean, Hetzner, etc.). Traffic from cloud datacenters or VPN proxies is served standard non-discounted base prices. ### Q: How do I implement localized dynamic pricing in Next.js 15 or React? Install `parityedge` via npm (`npm install parityedge`). Then use the `useParityEdge` hook or `` component from `parityedge/react`: ```tsx import { useParityEdge, ParityBanner } from 'parityedge/react'; export default function Pricing() { const { data } = useParityEdge({ projectId: 'YOUR_PROJECT_ID' }); return ; } ``` ### Q: How does ParityEdge inject discounts into Stripe Checkout? ParityEdge queries the client DOM for checkout links containing `buy.stripe.com` and appends the regional promo code query parameter `?prefilled_promo_code=COUPON`. When clicked, the buyer arrives at Stripe with their purchasing power parity discount already applied.