🛒 uCart Universal Widget SDK

Embeddable product cards and uCart drawer for external sites. One script tag, zero dependencies.

Interactive Demo

Configure the widget parameters below and see it update in real-time.

[[Demo:UCartWidget]]

🚀 Getting Started

To use the uCart widget on your external site, you can choose between a declarative (HTML-only) or programmatic (JavaScript) approach.

1. Declarative Approach (HTML)

This is the easiest way to add a product card to your site. Simply include the script and add data attributes to any div.

<!-- 1. Include the widget script -->
<script
	src="https://cdn.ngwenya.io/widget/v1/ucart.js"
	data-base-url="https://api.ngwenya.io"
	data-auth-url="https://auth.ngwenya.io"
></script>

<!-- 2. Place product widgets anywhere -->
<div data-ucart-product="prod_123" data-malet="safari-gear" data-theme="light"></div>

<!-- 3. Optional: floating mini-uCart -->
<div data-ucart-mini-ucart data-theme="light"></div>

2. Programmatic Approach (JavaScript)

For more control, use the UCart global object to render widgets dynamically.

<script src="https://cdn.ngwenya.io/widget/v1/ucart.js"></script>
<script>
  // Configure
  UCart.configure({
    baseUrl: 'https://api.ngwenya.io',
    authUrl: 'https://auth.ngwenya.io'
  });

  // Render a product card
  const widget = UCart.renderProduct({
    container: '#my-product',
    productId: 'prod_123',
    maletId: 'safari-gear',
    theme: 'dark',
    onAddToCart: (item) => console.log('Added:', item),
    onError: (err) => console.error(err),
  });

  // Render floating mini-uCart
  UCart.renderMiniUCart({
    container: '#ucart-root',
    theme: 'dark',
  });

  // Later: clean up
  widget.destroy();
</script>

✨ Features

• 🎨 Light & Dark Themes: Adapts to the host site's design with a simple theme attribute.
• 🔒 Secure Auth: OAuth popup via postMessage — no tokens exposed to host pages.
• 📊 Attribution Tracking: Automatically captures embed domain and campaign parameters.
• 🛡️ Style Isolation: Self-contained CSS — never conflicts with the host site's styles.
• 📱 Mobile Ready: Core logic is framework-agnostic, reusable in React Native.
• ⚡ Lightweight: Single JS file, no dependencies. Just add a script tag.

🏗️ Backend Architecture & Schema

While uCart orchestrates cross-Malet aggregates on the frontends via widgets, its backend subgraph functions as the universal commerce engine.

Distributed Shipping Options (`ShippingOption` payload)

With orders optionally containing items belonging to different physical Malets (merchants), it introduces the necessity to break down logistics into distributed payloads natively inside GraphQL.

• The Cart entity natively calculates and exposes availableShippingOptions for the buyer.
• Secure selections traverse across APIs back into the root Cart via the selectedShippingOptions input array.
• This unlocks multi-tier freight (e.g. Standard delivery for Store A, and Next-Day pickup for Store B), handled directly and synchronously within a single user checkout context.