@hanzo/commerce 7.6.1 → 7.6.4

package/dist/metering.js

@@ -0,0 +1,204 @@
+/**
+ * @hanzo/commerce/metering
+ *
+ * The ONE way every Hanzo product meters usage to commerce — the single
+ * billing source of truth — so that everything (not only the LLM/cloud path)
+ * can be paid for. This is the TypeScript counterpart of
+ * github.com/hanzoai/go-sdk/metering; the two share an identical wire contract.
+ *
+ * It provides two operations against commerce's canonical billing API:
+ *
+ *   - authorize(): a pre-request balance gate. Fail-closed by default — if the
+ *     balance cannot be determined the request is denied, exactly like the
+ *     gateway's prepaid-balance gate. With tierAware it consults the effective
+ *     balance (prepaid + included plan allotment, e.g. the free-tier daily
+ *     credit) so included usage is honored before prepaid funds.
+ *
+ *   - record(): a post-request usage write that debits the user's balance.
+ *
+ * Composition over duplication: this wraps the existing {@link Commerce}
+ * client (GET /v1/billing/balance, GET /v1/billing/tier, POST /v1/billing/usage)
+ * rather than re-implementing the HTTP layer.
+ *
+ * Auth is the commerce service token (admin-scoped S2S), sent as
+ * `Authorization: Bearer <token>` plus the tenant org as `X-IAM-Org-Id`. The
+ * token is a secret and MUST come from KMS (the operator wires it into
+ * COMMERCE_SERVICE_TOKEN); this module never reads it from disk.
+ *
+ * @example
+ * ```ts
+ * import { Metering } from '@hanzo/commerce/metering'
+ *
+ * const meter = Metering.fromEnv()  // COMMERCE_URL + COMMERCE_SERVICE_TOKEN (KMS) + COMMERCE_SERVICE_ORG
+ *
+ * // Pre-request gate (fail-closed).
+ * const gate = await meter.authorize({ user: 'hanzo/alice' })
+ * if (!gate.allowed) {
+ *   res.status(gate.reason === 'insufficient_balance' ? 402 : 503).end()
+ *   return
+ * }
+ *
+ * // ... do the work, compute cost ...
+ *
+ * // Post-request record (best-effort).
+ * await meter.record({ user: 'hanzo/alice', amount: 5, provider: 'search' })
+ * ```
+ */
+import { Commerce, CommerceApiError } from './client';
+/** Canonical in-cluster commerce address (matches the gateway default). */
+export const DEFAULT_COMMERCE_URL = 'http://commerce.hanzo.svc.cluster.local:8001';
+/**
+ * Metering is the server-side hook a product uses to charge for usage. It is
+ * safe to share a single instance across requests.
+ */
+export class Metering {
+    constructor(config = {}) {
+        const baseUrl = (config.baseUrl ?? '').replace(/\/+$/, '');
+        this.commerce = baseUrl
+            ? new Commerce({ baseUrl, token: config.token, timeoutMs: config.timeoutMs ?? 5000 })
+            : null;
+        this.org = (config.org ?? '').trim();
+        this.tierAware = config.tierAware ?? false;
+        this.failOpen = config.failOpen ?? false;
+    }
+    /**
+     * Build a Metering instance from the canonical environment variables. This
+     * is the one-liner products use at startup. Honors METERING_DISABLED for
+     * local dev.
+     */
+    static fromEnv(env = readEnv()) {
+        if (truthy(env.METERING_DISABLED))
+            return new Metering({});
+        return new Metering({
+            baseUrl: (env.COMMERCE_URL ?? '').trim() || DEFAULT_COMMERCE_URL,
+            token: env.COMMERCE_SERVICE_TOKEN,
+            org: (env.COMMERCE_SERVICE_ORG ?? '').trim() || 'hanzo',
+            tierAware: truthy(env.METERING_TIER_AWARE),
+            failOpen: truthy(env.METERING_FAIL_OPEN),
+        });
+    }
+    /** Whether a commerce base URL is configured. */
+    get enabled() {
+        return this.commerce !== null;
+    }
+    /**
+     * Pre-request balance gate. Never throws — returns a decision so callers map
+     * it to a status code. When not configured it always allows.
+     *
+     * Outcomes (matching the gateway):
+     *   { allowed: true }                                    -> allow.
+     *   { allowed: false, reason: 'insufficient_balance' }   -> 402 (out of funds).
+     *   { allowed: false, reason: 'balance_unavailable' }    -> 503 (fail-closed).
+     */
+    async authorize(id) {
+        if (!this.commerce)
+            return { allowed: true };
+        const user = (id.user ?? '').trim();
+        if (!user) {
+            return this.failOpen ? { allowed: true } : { allowed: false, reason: 'balance_unavailable' };
+        }
+        const headers = orgHeader(id.org ?? this.org);
+        try {
+            const available = this.tierAware
+                ? (await this.commerce.getTier(user, { headers })).balance.effectiveAvailable
+                : (await this.commerce.getBalance(user, id.currency ?? 'usd', undefined, headers)).available;
+            if (available > 0)
+                return { allowed: true, available };
+            return { allowed: false, reason: 'insufficient_balance', available };
+        }
+        catch {
+            // Balance unknown (commerce unreachable / non-2xx).
+            if (this.failOpen)
+                return { allowed: true };
+            return { allowed: false, reason: 'balance_unavailable' };
+        }
+    }
+    /**
+     * Record a usage event, debiting the user's balance. No-op when not
+     * configured or amount <= 0 (commerce treats zero-cost usage as skipped).
+     * Decoupled from gating: the work already happened, so balance is not
+     * re-checked here. Returns null on no-op.
+     */
+    async record(usage) {
+        if (!this.commerce || usage.amount <= 0)
+            return null;
+        if (!usage.user?.trim())
+            throw new Error('metering: record requires a user');
+        const headers = orgHeader(usage.org ?? this.org);
+        // Commerce's usageRequest field names map one-for-one; org travels via the
+        // header, never the body.
+        const body = {
+            user: usage.user,
+            currency: usage.currency ?? 'usd',
+            amount: usage.amount,
+            model: usage.model,
+            provider: usage.provider,
+            promptTokens: usage.promptTokens,
+            completionTokens: usage.completionTokens,
+            totalTokens: usage.totalTokens,
+            requestId: usage.requestId,
+            premium: usage.premium,
+            stream: usage.stream,
+            status: usage.status,
+            clientIp: usage.clientIp,
+        };
+        const tx = await this.commerce.addUsageRecord(body, undefined, headers);
+        // Commerce returns { transactionId, user, amount, currency, type }.
+        return tx;
+    }
+    /**
+     * Convenience for products that prefer to throw on denial. Throws a
+     * {@link CommerceApiError} with status 402 (insufficient) or 503 (unknown).
+     */
+    async authorizeOrThrow(id) {
+        const decision = await this.authorize(id);
+        if (decision.allowed)
+            return;
+        if (decision.reason === 'insufficient_balance') {
+            throw new CommerceApiError(402, 'Insufficient balance. Please add credits at console.hanzo.ai');
+        }
+        throw new CommerceApiError(503, 'Billing temporarily unavailable');
+    }
+}
+// ---------------------------------------------------------------------------
+// Identity from gateway-minted headers (the trust boundary)
+// ---------------------------------------------------------------------------
+/** Gateway-minted identity headers. */
+export const HEADER_USER_ID = 'x-user-id';
+export const HEADER_ORG_ID = 'x-org-id';
+/**
+ * Build a {@link MeteringIdentity} from gateway-minted identity headers. The
+ * user is "{org}/{sub}" (commerce's iam-user form) when both are present.
+ * Accepts a header bag with string | string[] | undefined values (Node http,
+ * Next.js, fetch Headers via Object.fromEntries).
+ */
+export function identityFromHeaders(headers) {
+    const get = (k) => {
+        if (typeof headers.get === 'function') {
+            return (headers.get(k) ?? '').trim();
+        }
+        const v = headers[k];
+        return (Array.isArray(v) ? v[0] : v ?? '').trim();
+    };
+    const org = get(HEADER_ORG_ID);
+    const sub = get(HEADER_USER_ID);
+    const user = org && sub ? `${org}/${sub}` : sub;
+    return { user, org };
+}
+// ---------------------------------------------------------------------------
+// internals
+// ---------------------------------------------------------------------------
+function orgHeader(org) {
+    const o = (org ?? '').trim();
+    return o ? { 'X-IAM-Org-Id': o } : undefined;
+}
+function truthy(v) {
+    const s = (v ?? '').trim().toLowerCase();
+    return s === 'true' || s === '1' || s === 'yes';
+}
+function readEnv() {
+    // Node/edge: process.env when present, else empty (browser).
+    const g = globalThis;
+    return g.process?.env ?? {};
+}
+//# sourceMappingURL=metering.js.map

package/dist/metering.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metering.js","sourceRoot":"","sources":["../metering.ts"],"names":[],"mappings":"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"}

package/dist/metering.test.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Contract tests for @hanzo/commerce/metering.
+ *
+ * Self-contained: mocks global fetch and asserts the exact commerce wire
+ * contract, mirroring github.com/hanzoai/go-sdk/metering's tests so the two
+ * clients gate on the identical balance source. Runnable standalone with:
+ *
+ *   npx -y -p typescript@5.9.3 -p tsx tsx pkgs/commerce/metering.test.ts
+ *
+ * It uses no test-runner dependency (the package ships none); a tiny harness
+ * below prints PASS/FAIL and exits non-zero on failure.
+ */
+export {};

package/dist/metering.test.js

@@ -0,0 +1,181 @@
+/**
+ * Contract tests for @hanzo/commerce/metering.
+ *
+ * Self-contained: mocks global fetch and asserts the exact commerce wire
+ * contract, mirroring github.com/hanzoai/go-sdk/metering's tests so the two
+ * clients gate on the identical balance source. Runnable standalone with:
+ *
+ *   npx -y -p typescript@5.9.3 -p tsx tsx pkgs/commerce/metering.test.ts
+ *
+ * It uses no test-runner dependency (the package ships none); a tiny harness
+ * below prints PASS/FAIL and exits non-zero on failure.
+ */
+import { Metering, identityFromHeaders } from './metering';
+// ---- tiny assert harness ----
+let failures = 0;
+let count = 0;
+function test(name, fn) {
+    count++;
+    Promise.resolve()
+        .then(fn)
+        .then(() => console.log(`ok   - ${name}`))
+        .catch((err) => {
+        failures++;
+        console.error(`FAIL - ${name}\n       ${err?.message ?? err}`);
+    });
+}
+function eq(actual, expected, msg = '') {
+    if (actual !== expected)
+        throw new Error(`${msg} expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`);
+}
+function ok(cond, msg = '') {
+    if (!cond)
+        throw new Error(msg || 'expected true');
+}
+function mockFetch(status, json) {
+    const original = globalThis.fetch;
+    let last = null;
+    globalThis.fetch = (async (input, init) => {
+        const hdrs = {};
+        const h = init?.headers;
+        if (h)
+            for (const [k, v] of Object.entries(h))
+                hdrs[k.toLowerCase()] = v;
+        last = {
+            url: input.toString(),
+            method: init?.method ?? 'GET',
+            headers: hdrs,
+            body: init?.body ? JSON.parse(init.body) : undefined,
+        };
+        return {
+            ok: status >= 200 && status < 300,
+            status,
+            statusText: `HTTP ${status}`,
+            json: async () => json,
+            text: async () => JSON.stringify(json),
+        };
+    });
+    return { restore: () => { globalThis.fetch = original; }, last: () => last };
+}
+const BASE = 'http://commerce.test';
+test('authorize allows when available > 0 and hits the canonical contract', async () => {
+    const fx = mockFetch(200, { user: 'hanzo/alice', currency: 'usd', balance: 5000, holds: 0, available: 5000 });
+    const meter = new Metering({ baseUrl: BASE, token: 'svc-token', org: 'hanzo' });
+    const d = await meter.authorize({ user: 'hanzo/alice' });
+    fx.restore();
+    ok(d.allowed, 'should allow');
+    eq(d.available, 5000, 'available');
+    const c = fx.last();
+    eq(c.method, 'GET', 'method');
+    ok(c.url.startsWith(`${BASE}/v1/billing/balance?`), `url=${c.url}`);
+    ok(c.url.includes('user=hanzo%2Falice'), `url must url-encode user: ${c.url}`);
+    ok(c.url.includes('currency=usd'), `url must carry currency: ${c.url}`);
+    eq(c.headers['authorization'], 'Bearer svc-token', 'bearer');
+    eq(c.headers['x-iam-org-id'], 'hanzo', 'org header');
+});
+test('authorize denies (insufficient) when available == 0', async () => {
+    const fx = mockFetch(200, { available: 0 });
+    const meter = new Metering({ baseUrl: BASE, token: 't', org: 'hanzo' });
+    const d = await meter.authorize({ user: 'hanzo/alice' });
+    fx.restore();
+    ok(!d.allowed, 'should deny');
+    eq(d.reason, 'insufficient_balance', 'reason');
+});
+test('authorize fail-closed on commerce error (503/unavailable)', async () => {
+    const fx = mockFetch(500, { error: 'boom' });
+    const meter = new Metering({ baseUrl: BASE, token: 't', org: 'hanzo' });
+    const d = await meter.authorize({ user: 'hanzo/alice' });
+    fx.restore();
+    ok(!d.allowed, 'fail-closed must deny on 500');
+    eq(d.reason, 'balance_unavailable', 'reason');
+});
+test('authorize fail-open allows on commerce error when configured', async () => {
+    const fx = mockFetch(503, { error: 'down' });
+    const meter = new Metering({ baseUrl: BASE, token: 't', org: 'hanzo', failOpen: true });
+    const d = await meter.authorize({ user: 'hanzo/alice' });
+    fx.restore();
+    ok(d.allowed, 'fail-open must allow');
+});
+test('authorize not-configured allows', async () => {
+    const meter = new Metering({}); // no baseUrl
+    ok(!meter.enabled, 'enabled should be false');
+    const d = await meter.authorize({ user: 'hanzo/alice' });
+    ok(d.allowed, 'not-configured must allow');
+});
+test('tier-aware authorize uses effectiveAvailable and hits /v1/billing/tier', async () => {
+    const fx = mockFetch(200, { user: 'hanzo/alice', tier: { name: 'free' }, balance: { currency: 'usd', prepaidAvailable: 0, dailyRemaining: 100, effectiveAvailable: 100 } });
+    const meter = new Metering({ baseUrl: BASE, token: 't', org: 'hanzo', tierAware: true });
+    const d = await meter.authorize({ user: 'hanzo/alice' });
+    fx.restore();
+    ok(d.allowed, 'included allotment should allow');
+    eq(d.available, 100, 'effective available');
+    ok(fx.last().url.startsWith(`${BASE}/v1/billing/tier?`), `tier url=${fx.last().url}`);
+});
+test('tier-aware authorize denies when effectiveAvailable == 0', async () => {
+    const fx = mockFetch(200, { balance: { effectiveAvailable: 0, prepaidAvailable: 0, dailyRemaining: 0, currency: 'usd' } });
+    const meter = new Metering({ baseUrl: BASE, token: 't', org: 'hanzo', tierAware: true });
+    const d = await meter.authorize({ user: 'hanzo/alice' });
+    fx.restore();
+    ok(!d.allowed && d.reason === 'insufficient_balance', 'exhausted must deny insufficient');
+});
+test('per-call org overrides default', async () => {
+    const fx = mockFetch(200, { available: 1 });
+    const meter = new Metering({ baseUrl: BASE, token: 't', org: 'hanzo' });
+    await meter.authorize({ user: 'zoo/bob', org: 'zoo' });
+    fx.restore();
+    eq(fx.last().headers['x-iam-org-id'], 'zoo', 'per-call org override');
+});
+test('record posts canonical payload', async () => {
+    const fx = mockFetch(201, { transactionId: 'tx_123', user: 'hanzo/alice', amount: 250, currency: 'usd', type: 'withdraw' });
+    const meter = new Metering({ baseUrl: BASE, token: 'svc-token', org: 'hanzo' });
+    const res = await meter.record({ user: 'hanzo/alice', amount: 250, provider: 'search', requestId: 'req-9', status: 'success' });
+    fx.restore();
+    ok(res !== null && res.transactionId === 'tx_123' && res.amount === 250, 'record result');
+    const c = fx.last();
+    eq(c.method, 'POST', 'method');
+    eq(c.url, `${BASE}/v1/billing/usage`, 'usage url');
+    eq(c.headers['authorization'], 'Bearer svc-token', 'bearer');
+    eq(c.headers['x-iam-org-id'], 'hanzo', 'org header');
+    const b = c.body;
+    eq(b.user, 'hanzo/alice', 'body.user');
+    eq(b.amount, 250, 'body.amount');
+    eq(b.currency, 'usd', 'body.currency defaulted');
+    eq(b.provider, 'search', 'body.provider');
+    eq(b.requestId, 'req-9', 'body.requestId');
+    ok(!('org' in b), 'org must not leak into the body');
+});
+test('record zero-amount is a no-op (no fetch)', async () => {
+    const fx = mockFetch(200, {});
+    const meter = new Metering({ baseUrl: BASE, token: 't', org: 'hanzo' });
+    const res = await meter.record({ user: 'hanzo/alice', amount: 0 });
+    fx.restore();
+    ok(res === null, 'zero-amount returns null');
+    ok(fx.last() === null, 'zero-amount must not call commerce');
+});
+test('record not-configured is a no-op', async () => {
+    const meter = new Metering({});
+    const res = await meter.record({ user: 'hanzo/alice', amount: 100 });
+    ok(res === null, 'not-configured returns null');
+});
+test('fromEnv applies defaults and reads KMS-sourced token', () => {
+    const meter = Metering.fromEnv({ COMMERCE_SERVICE_TOKEN: 'kms-token', METERING_TIER_AWARE: 'true' });
+    ok(meter.enabled, 'fromEnv default base URL enables the meter');
+});
+test('fromEnv honors METERING_DISABLED', () => {
+    const meter = Metering.fromEnv({ METERING_DISABLED: 'true', COMMERCE_URL: BASE });
+    ok(!meter.enabled, 'disabled must not be enabled');
+});
+test('identityFromHeaders builds org/sub from gateway headers', () => {
+    const id = identityFromHeaders({ 'x-org-id': 'zoo', 'x-user-id': 'bob' });
+    eq(id.user, 'zoo/bob', 'user');
+    eq(id.org, 'zoo', 'org');
+});
+// summary
+setTimeout(() => {
+    if (failures > 0) {
+        console.error(`\n${failures}/${count} tests FAILED`);
+        process.exit(1);
+    }
+    console.log(`\nall ${count} tests passed`);
+}, 200);
+//# sourceMappingURL=metering.test.js.map

package/dist/metering.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metering.test.js","sourceRoot":"","sources":["../metering.test.ts"],"names":[],"mappings":"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"}

package/dist/product-card.test.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Annotation contract test for @hanzo/commerce ProductCard + AddToCartWidget.
+ *
+ * Proves the zero-app-config promise: rendering <ProductCard item={...}/> emits
+ * NEUTRAL, STANDARD self-description — schema.org Product/Offer microdata plus a
+ * schema.org AddAction on the add control — with no analytics code in the app.
+ * A tracker (track.js `annotate`, GA4 Merchant, any reader) captures the item
+ * and the add-to-cart intent from the DOM alone.
+ *
+ * Self-contained, mirroring metering.test.ts: no test-runner dependency. Run with:
+ *
+ *   npx -y tsx pkgs/commerce/product-card.test.tsx
+ */
+export {};

package/dist/product-card.test.js

@@ -0,0 +1,96 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Annotation contract test for @hanzo/commerce ProductCard + AddToCartWidget.
+ *
+ * Proves the zero-app-config promise: rendering <ProductCard item={...}/> emits
+ * NEUTRAL, STANDARD self-description — schema.org Product/Offer microdata plus a
+ * schema.org AddAction on the add control — with no analytics code in the app.
+ * A tracker (track.js `annotate`, GA4 Merchant, any reader) captures the item
+ * and the add-to-cart intent from the DOM alone.
+ *
+ * Self-contained, mirroring metering.test.ts: no test-runner dependency. Run with:
+ *
+ *   npx -y tsx pkgs/commerce/product-card.test.tsx
+ */
+import React from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import ProductCard from './components/item/product-card';
+// ---- tiny assert harness (mirrors metering.test.ts) ----
+let failures = 0;
+let count = 0;
+function test(name, fn) {
+    count++;
+    try {
+        fn();
+        console.log(`ok   - ${name}`);
+    }
+    catch (err) {
+        failures++;
+        console.error(`FAIL - ${name}`);
+        console.error(err.message);
+    }
+}
+function ok(cond, msg) {
+    if (!cond)
+        throw new Error(msg);
+}
+// A minimal LineItem-shaped mock: getters + cart methods, no media (MediaStack
+// renders empty). Enough to drive the microdata the card carries.
+const item = {
+    id: 'x1',
+    sku: 'LXB-AU-B',
+    familyId: 'LXB',
+    familyTitle: 'Bar',
+    optionLabel: '1oz',
+    price: 99.5,
+    get title() {
+        return 'Gold Bar, 1oz';
+    },
+    get quantity() {
+        return 0;
+    },
+    get isInCart() {
+        return false;
+    },
+    increment() { },
+    decrement() { },
+};
+const html = renderToStaticMarkup(_jsx(ProductCard, { item: item }));
+// Attribute names are matched case-insensitively: HTML parsing and setAttribute
+// both lowercase attribute names in the HTML namespace, so React's camelCase SSR
+// serialization (itemType="…") becomes itemtype in the live DOM that annotate
+// queries. The DOM-capture contract is proven end-to-end in track.js's tests.
+const H = html.toLowerCase();
+const has = (needle) => H.includes(needle.toLowerCase());
+test('card is a schema.org Product', () => {
+    ok(has('itemtype="https://schema.org/Product"'), 'Product itemtype present');
+    ok(has('data-slot="card"'), 'shadcn data-slot preserved');
+});
+test('product name is machine-readable', () => {
+    ok(has('itemprop="name"'), 'name itemprop present');
+    ok(has('content="Gold Bar, 1oz"'), 'name value present');
+});
+test('product sku is machine-readable', () => {
+    ok(has('itemprop="sku"'), 'sku itemprop present');
+    ok(has('content="LXB-AU-B"'), 'sku value present');
+});
+test('price is a schema.org Offer with currency', () => {
+    ok(has('itemtype="https://schema.org/Offer"'), 'Offer itemtype present');
+    ok(has('itemprop="price"'), 'price itemprop present');
+    ok(has('content="99.5"'), 'raw price value present');
+    ok(has('itemprop="priceCurrency"'), 'priceCurrency itemprop present');
+    ok(has('content="USD"'), 'currency value present');
+});
+test('add control is a schema.org AddAction (maps to GA4 add_to_cart)', () => {
+    ok(has('itemtype="https://schema.org/AddAction"'), 'AddAction itemtype present');
+    ok(has('itemprop="potentialAction"'), 'action linked to the Product');
+});
+// summary
+setTimeout(() => {
+    if (failures > 0) {
+        console.error(`\n${failures}/${count} tests FAILED`);
+        process.exit(1);
+    }
+    console.log(`\nall ${count} tests passed`);
+}, 200);
+//# sourceMappingURL=product-card.test.js.map

package/dist/product-card.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"product-card.test.js","sourceRoot":"","sources":["../product-card.test.tsx"],"names":[],"mappings":"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"}

package/dist/service/context.d.ts

@@ -0,0 +1,8 @@
+import React, { type PropsWithChildren } from 'react';
+import type CommerceService from '../types/commerce-service';
+import type { CommerceConfig } from '../types';
+declare const useCommerce: () => CommerceService;
+declare const CommerceProvider: React.FC<PropsWithChildren & {
+    config: CommerceConfig;
+}>;
+export { useCommerce, CommerceProvider };

package/dist/service/context.js

@@ -0,0 +1,19 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import React, { createContext, useContext, useRef, } from 'react';
+// https://dev.to/ivandotv/mobx-server-side-rendering-with-next-js-4m18
+import { enableStaticRendering } from 'mobx-react-lite';
+enableStaticRendering(typeof window === "undefined");
+import { getInstance } from './impls/standalone';
+const CommerceContext = createContext(undefined);
+const useCommerce = () => {
+    return useContext(CommerceContext);
+};
+const CommerceProvider = ({ children, config }) => {
+    // TODO: Inject Promo fixture here from siteDef
+    const service = getInstance(config);
+    const valueRef = useRef(service);
+    return (_jsx(CommerceContext.Provider, { value: valueRef.current, children: children }));
+};
+export { useCommerce, CommerceProvider };
+//# sourceMappingURL=context.js.map

package/dist/service/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../service/context.tsx"],"names":[],"mappings":"AAAA,YAAY,CAAA;;AACZ,OAAO,KAAK,EAAE,EACZ,aAAa,EACb,UAAU,EACV,MAAM,GAEP,MAAM,OAAO,CAAA;AAEd,uEAAuE;AACvE,OAAO,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAA;AACvD,qBAAqB,CAAC,OAAO,MAAM,KAAK,WAAW,CAAC,CAAA;AAIpD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAEhD,MAAM,eAAe,GAAG,aAAa,CAA8B,SAAS,CAAC,CAAA;AAE7E,MAAM,WAAW,GAAG,GAAoB,EAAE;IACxC,OAAO,UAAU,CAAC,eAAe,CAAoB,CAAA;AACvD,CAAC,CAAA;AAED,MAAM,gBAAgB,GAEjB,CAAC,EACJ,QAAQ,EACR,MAAM,EACP,EAAE,EAAE;IAED,+CAA+C;IACjD,MAAM,OAAO,GAAG,WAAW,CAAC,MAAM,CAAC,CAAA;IACnC,MAAM,QAAQ,GAAG,MAAM,CAAkB,OAAO,CAAC,CAAA;IAEjD,OAAO,CACL,KAAC,eAAe,CAAC,QAAQ,IAAC,KAAK,EAAE,QAAQ,CAAC,OAAO,YAC9C,QAAQ,GACgB,CAC5B,CAAA;AACH,CAAC,CAAA;AAED,OAAO,EACL,WAAW,EACX,gBAAgB,EACjB,CAAA"}

package/dist/service/debug.d.ts

@@ -0,0 +1,10 @@
+import type { CategoryNode, CategoryNodeRole, Family, LineItem } from '../types';
+export declare const categoryNodeDump: (node: CategoryNode, level?: number) => void;
+export declare const selectedFamiliesDump: (result: Family[]) => string;
+export declare const peekDump: (result: {
+    role: CategoryNodeRole;
+    family: Family | undefined;
+    families: Family[] | undefined;
+    node: CategoryNode | undefined;
+    item: LineItem | undefined;
+} | string) => string;

package/dist/service/debug.js

@@ -0,0 +1,30 @@
+// Node recursion
+export const categoryNodeDump = (node, level = 0) => {
+    const spacers = [];
+    for (let i = 0; i < level; i++) {
+        spacers.push('----');
+    }
+    console.log("NODE:" + spacers.join(''), node.skuToken);
+    node.subNodes?.forEach((sn) => { categoryNodeDump(sn, level + 1); });
+};
+export const selectedFamiliesDump = (result) => {
+    const toDisplay = result.map((c) => (c.id));
+    return JSON.stringify(toDisplay, null, 2);
+};
+export const peekDump = (result) => {
+    if (typeof result === 'string') {
+        return result;
+    }
+    const toDisplay = {
+        role: result.role,
+        item: result.item ? result.item.sku : 'UNDEF',
+        family: result.family ? result.family.id : 'UNDEF',
+        families: result.families ? result.families.map((f) => (f.id)) : 'UNDEF',
+        node: result.node ?
+            (result.node.skuToken + (result.node.label ? (': ' + result.node.label) : ''))
+            :
+                'UNDEF'
+    };
+    return JSON.stringify(toDisplay, null, 2);
+};
+//# sourceMappingURL=debug.js.map

package/dist/service/debug.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug.js","sourceRoot":"","sources":["../../service/debug.ts"],"names":[],"mappings":"AAEE,iBAAiB;AACnB,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,IAAkB,EAAE,QAAgB,CAAC,EAAQ,EAAE;IAC9E,MAAM,OAAO,GAAa,EAAE,CAAA;IAC5B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC;QAC/B,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;IACtB,CAAC;IACD,OAAO,CAAC,GAAG,CAAC,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAA;IACtD,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,EAAgB,EAAE,EAAE,GAAE,gBAAgB,CAAC,EAAE,EAAE,KAAK,GAAG,CAAC,CAAC,CAAA,CAAA,CAAC,CAAC,CAAA;AACjF,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,MAAgB,EAAU,EAAE;IAC/D,MAAM,SAAS,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;IAC3C,OAAO,IAAI,CAAC,SAAS,CAAC,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC,CAAA;AAC3C,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,MAMf,EAAU,EAAE;IAEpB,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC/B,OAAO,MAAM,CAAA;IACf,CAAC;IAED,MAAM,SAAS,GAAG;QAChB,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO;QAC7C,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO;QAClD,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO;QACxE,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;YACjB,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YAC9E,CAAC;gBACD,OAAO;KACV,CAAA;IACD,OAAO,IAAI,CAAC,SAAS,CAAC,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC,CAAA;AAC3C,CAAC,CAAA"}