Hyperrr Commerce Engine & Core Platform

Hyperrr is a declarative, runtime-discoverable, capability-driven domain composition engine for modern headless commerce, built on Python 3.12+, FastAPI, Async SQLAlchemy 2.0+, Pydantic v2, and the Universal TypeScript Client SDK (@hyperrr/sdk).

🌟 Architecture Highlights

1. Capability-Driven Decoupled Architecture

Hyperrr decouples core commerce business logic from third-party vendor APIs. The frontend and domain workflows interact exclusively with standard, vendor-agnostic capabilities:

• payment.gateway (Fulfilled by razorpay, stripe, etc.)
• tax.calculator (Fulfilled by india_gst, avalara, taxjar, etc.)
• shipping.carrier (Fulfilled by delhivery, fedex, shiprocket, etc.)
• auth.provider (Fulfilled by google_auth, webauthn, otp, etc.)
• storage.driver (Fulfilled by s3_storage, gcs, minio, etc.)
• email.sender (Fulfilled by smtp_email, resend, sendgrid, etc.)

Frontends remain 100% vendor-agnostic: Swapping payment or tax vendors requires 0 frontend code modifications.

2. Universal TypeScript Client SDK (@hyperrr/sdk)

A unified client library (packages/sdk/) for building modern Storefronts, Admin Panels, Mobile Apps, or Headless integrations (Next.js, Remix, React Native):

npm install @hyperrr/sdk

import { HyperrrClient } from "@hyperrr/sdk";

const hyperrr = new HyperrrClient({
  baseUrl: "https://api.yourstore.com",
  apiKey: "pk_live_...",
});

// Standard Commerce Primitives (Vendor-Agnostic)
const products = await hyperrr.catalog.listProducts();
const cart = await hyperrr.cart.create();
const tax = await hyperrr.tax.calculate({ destinationStateCode: "29", items: [...] });
const rates = await hyperrr.shipping.getRates({ postalCode: "560103" });

3. Dual-Package Standalone Extensions

Every extension is structured as a self-contained dual package ready to be extracted into standalone GitHub repositories:

• Python Backend: Published to PyPI (hyperrr-razorpay, hyperrr-india-gst, etc.) and installed on the server with hyperrr add <name>.
• TypeScript Client Plugin: Published to npm (@hyperrr-extension/razorpay, @hyperrr-extension/india-gst, etc.) and chained into HyperrrClient with .use():

import { HyperrrClient } from "@hyperrr/sdk";
import { razorpayPlugin } from "@hyperrr-extension/razorpay";
import { indiaGstPlugin } from "@hyperrr-extension/india-gst";

const hyperrr = new HyperrrClient({ ... })
  .use(razorpayPlugin())
  .use(indiaGstPlugin());

// Typed extension-specific operations & settings
await hyperrr.indiaGst.generateEWayBill({ orderId: "ord_9204" });
await hyperrr.razorpay.updateSettings({ auto_capture: true });

🛠️ Developer CLI Commands

# Add/install a package from Git, ZIP, Marketplace, or Local directory
hyperrr add https://github.com/GoHyperrr/hyperrr-india-gst#v1.0.0
hyperrr add ./razorpay.zip
hyperrr add customer

# Display dependency graph & runtime status
hyperrr tree
hyperrr packages

# Manage runtime capability bindings
hyperrr enable razorpay
hyperrr disable stripe

# Run database schema migrations & health checks
hyperrr migrate --export
hyperrr health

# Launch HTTP ASGI server
hyperrr serve --host 127.0.0.1 --port 8000 --reload

📚 Documentation & Developer Guides

Detailed guides and architecture specifications:

• Developer & SDK Guide: Universal TypeScript SDK usage, client architecture, and CLI workflows.
• Package Development Guide: Creating core domain packages, objects, workflows, and routes.
• Provider & Extension Guide: Building standalone dual-package provider extensions with typed TypeScript plugins.
• Core Services Specification: Security guardrails, SSRF protection, AST scanners, and database transactions.
• Commerce API Specification: REST endpoints and schema definitions across catalog, checkout, orders, tax, and payments.