npm - create-cartbase - Versions diffs - 0.1.4 → 0.1.6 - Mend

create-cartbase 0.1.4 → 0.1.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/package.json +21 -21
package/template/app/docs/components.md +1134 -1090
package/template/app/docs/integrations.md +15 -3
package/template/app/docs/products.md +6 -0
package/template/app/package.json +1 -1
package/template/app/src/app/layout.tsx +14 -0
package/template/app/src/app/order/[id]/confirmed/page.tsx +92 -78
package/template/app/tsconfig.tsbuildinfo +1 -1

package/template/app/docs/integrations.md CHANGED Viewed

@@ -56,6 +56,10 @@ key-by-key.
     "ga4": { "measurementId": "G-…" },
     "klaviyo": { "publicKey": "…" },
     "googleAds": { "conversionId": "AW-…", "conversionLabel": "…" },
+    // Pixel id only. The TikTok Events API token stays on the platform
+    // and is used by the order.placed forwarder, exactly like Meta's
+    // CAPI token, which has never appeared on this endpoint.
+    "tiktok": { "pixelId": "C…" },
     "consent_required": true     // always present — mirrors the consent CMP's enabled
   }
 }
@@ -64,7 +68,10 @@ key-by-key.
 - **Errors**: `400 missing_client_id` · `400 invalid_publishable_key`.
 - **SDK**: `integrations.getIntegrationsConfig(client)`
 - **Components**: carrier/locker pickers, COD fee row in checkout, tracking
-  mounts (`<MetaPixel>/<GA4>/<Gtm>` behind the consent gate).
+  mounts (`<MetaPixel>/<GoogleTag>/<TikTokPixel>/<Gtm>` behind the consent
+  gate). `<GoogleTag measurementId adsConversionId>` takes BOTH Google
+  destinations: one loader, two `config` calls, which is Google's own
+  instruction and is what lets Consent Mode gate the Ads tag for free.
 - **Settings**: admin → Settings → Integrations (per-provider enable +
   config); consent settings drive `tracking.consent_required`; Rybbit is
   deliberately ABSENT (platform analytics, not a tenant integration).
@@ -72,8 +79,13 @@ key-by-key.
 Tracking wiring contract: mount tags only through the consent gate when
 `consent_required` (see [consent.md](consent.md)); Purchase events MUST use
 `eventID = "purchase_" + order.display_id` so Meta dedupes browser Pixel vs
-server CAPI; write TrackingAttribution keys into `cart.metadata`
-(consent-gated) so server events inherit fbp/fbc/anon-id/ga signals.
+server CAPI, and `event_id = "tt_purchase_" + order.display_id` for TikTok;
+write TrackingAttribution keys into `cart.metadata` (consent-gated) so
+server events inherit fbp/fbc/anon-id/ga signals AND the ad-click ids
+(`tt_ttclid`, `tt_ttp`, `google_gclid`, `google_gbraid`, `google_wbraid`)
+that let TikTok and Google tie a conversion back to the click that caused
+it. Capture those with `captureClickIdsFromUrl()` beside
+`captureUtmsFromUrl()`.
 ```bash
 BODY=$(curl -sf "$BASE/api/store/integrations" -H "x-client-id: $CLIENT_ID")

package/template/app/docs/products.md CHANGED Viewed

@@ -86,6 +86,12 @@ foreign key → 400 `invalid_publishable_key`.
       "thumbnail": null,
       "allow_backorder": false,
       "manage_inventory": true,
+      // Computed server-side by the platform's availability predicate:
+      // untracked or backorderable variants are always true; otherwise true
+      // iff available stock (kit-aware, reservations subtracted) is above
+      // zero. Read this — never re-derive stock client-side (the exact
+      // quantity is deliberately not exposed).
+      "in_stock": true,
       "variant_rank": 0,
       "metadata": null,
       "options": [

package/template/app/package.json CHANGED Viewed

@@ -8,7 +8,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@cartbase/storefront": "^0.5.0",
+    "@cartbase/storefront": "^0.7.0",
     "next": "16.2.4",
     "react": "19.2.4",
     "react-dom": "19.2.4"

package/template/app/src/app/layout.tsx CHANGED Viewed

@@ -5,6 +5,8 @@ import { retrieveCart, type Cart } from "@cartbase/storefront/api/carts"
 import { getConsent } from "@cartbase/storefront/api/consent"
 import { getMenu, type Menu } from "@cartbase/storefront/api/menus"
 import { ConsentInit } from "@cartbase/storefront/tracking/consent-init"
+import { StorefrontTags } from "@cartbase/storefront/tracking/storefront-tags"
+import { TrackInit } from "@cartbase/storefront/tracking/track-init"
 import { CartButtonClient } from "@cartbase/storefront/common/cart-button-client"
 import { createStorefrontMetadata, PlatformInit } from "@cartbase/storefront/platform"
 import { BARTER_CLIENT_ID, readCartCookie } from "@/lib/config"
@@ -80,6 +82,18 @@ export default async function RootLayout({
     <html lang="en">
       <body>
         <ConsentInit />
+        {/* Every marketing tag the store configured in the admin, mounted
+            from its own config: Meta, TikTok, Google (GA4 + Ads on one
+            tag), GTM. Nothing to wire per vendor — saving the ids in
+            Settings → Integrations is the whole merchant-side act. Order
+            matters: ConsentInit sets the Consent Mode defaults
+            synchronously ABOVE this, so every tag below inherits the
+            gate. */}
+        <StorefrontTags client={client} />
+        {/* Captures UTMs and the ad-click ids (ttclid / gclid / gbraid /
+            wbraid) that exist ONLY on an ad's landing URL — miss them
+            here and no platform can attribute the order to the click. */}
+        <TrackInit />
         <PlatformInit storeId={BARTER_CLIENT_ID} />
         <Providers cart={cart} consent={consentRes.consent}>
           <header className="border-b border-border">

package/template/app/src/app/order/[id]/confirmed/page.tsx CHANGED Viewed

@@ -1,78 +1,92 @@
-"use client"
-import { useEffect, useState } from "react"
-import Link from "next/link"
-import type { CompletedOrder, CartLineItem } from "@cartbase/storefront/api/carts"
-import {
-  OrderCompletedTemplate,
-} from "@cartbase/storefront/order/order-completed-template"
-import {
-  displayItemFromCartLine,
-} from "@cartbase/storefront/order/order-item"
-import {
-  orderTotalsFromSummary,
-} from "@cartbase/storefront/order/order-totals"
-import { LAST_ORDER_STORAGE_KEY } from "../../../checkout/checkout-page-client"
-/**
- * Order confirmation (runbook step 8.6 + orders.md): guests have NO
- * anonymous order read — the `completeCart()` response is the only order
- * handle, so the checkout page stashes it in sessionStorage and this page
- * renders it through the order family. Totals come from the order's
- * summary snapshot (`orderTotalsFromSummary`); items keep the decorated
- * cart lines' server-computed totals (`displayItemFromCartLine`).
- */
-type Stash = { order: CompletedOrder; cartItems: CartLineItem[] }
-export default function OrderConfirmedPage() {
-  const [stash, setStash] = useState<Stash | null | "missing">(null)
-  useEffect(() => {
-    try {
-      const raw = sessionStorage.getItem(LAST_ORDER_STORAGE_KEY)
-      setStash(raw ? (JSON.parse(raw) as Stash) : "missing")
-    } catch {
-      setStash("missing")
-    }
-  }, [])
-  if (stash === null) return null // first paint before sessionStorage read
-  if (stash === "missing") {
-    return (
-      <div className="max-w-xl mx-auto px-4 py-16 text-center">
-        <h1 className="text-xl font-semibold mb-2">Order placed</h1>
-        <p className="text-muted-foreground mb-6">
-          Your order was placed successfully. A confirmation email is on its
-          way.
-        </p>
-        <Link href="/" className="underline">
-          Continue shopping
-        </Link>
-      </div>
-    )
-  }
-  const { order, cartItems } = stash
-  const totals = orderTotalsFromSummary(order.summary) ?? {
-    total: null,
-  }
-  // The completeCart() order carries FLATTENED items (checkout.md), not the
-  // order-detail pivot shape the template's default converter expects —
-  // pass the normalized cart-line items instead and drop `order.items`.
-  const orderForTemplate = { ...order, items: undefined }
-  return (
-    <OrderCompletedTemplate
-      order={orderForTemplate}
-      totals={totals}
-      items={cartItems.map(displayItemFromCartLine)}
-      // This reference store checks out via one merchant method (pp_* kill:
-      // methods are merchant-named, provider-less); a multi-tender store
-      // should stash the chosen tender from its checkout state alongside
-      // the order.
-      paymentMethodName={"Cash on delivery"}
-      storeHref="/"
-    />
-  )
-}
+"use client"
+import { useEffect, useState } from "react"
+import Link from "next/link"
+import type { CompletedOrder, CartLineItem } from "@cartbase/storefront/api/carts"
+import {
+  OrderCompletedTemplate,
+} from "@cartbase/storefront/order/order-completed-template"
+import {
+  displayItemFromCartLine,
+} from "@cartbase/storefront/order/order-item"
+import {
+  orderTotalsFromSummary,
+} from "@cartbase/storefront/order/order-totals"
+import { TrackOrderPurchase } from "@cartbase/storefront/tracking/track-order-purchase"
+import { useTrackingConfig } from "@cartbase/storefront/tracking/use-tracking-config"
+import { browserClient } from "@/lib/browser-client"
+import { LAST_ORDER_STORAGE_KEY } from "../../../checkout/checkout-page-client"
+/**
+ * Order confirmation (runbook step 8.6 + orders.md): guests have NO
+ * anonymous order read — the `completeCart()` response is the only order
+ * handle, so the checkout page stashes it in sessionStorage and this page
+ * renders it through the order family. Totals come from the order's
+ * summary snapshot (`orderTotalsFromSummary`); items keep the decorated
+ * cart lines' server-computed totals (`displayItemFromCartLine`).
+ */
+type Stash = { order: CompletedOrder; cartItems: CartLineItem[] }
+export default function OrderConfirmedPage() {
+  const [stash, setStash] = useState<Stash | null | "missing">(null)
+  // The store's public tag config — Google Ads needs the account id
+  // and the purchase label from it, and null means the conversion is
+  // skipped rather than fired malformed.
+  const tracking = useTrackingConfig(browserClient)
+  useEffect(() => {
+    try {
+      const raw = sessionStorage.getItem(LAST_ORDER_STORAGE_KEY)
+      setStash(raw ? (JSON.parse(raw) as Stash) : "missing")
+    } catch {
+      setStash("missing")
+    }
+  }, [])
+  if (stash === null) return null // first paint before sessionStorage read
+  if (stash === "missing") {
+    return (
+      <div className="max-w-xl mx-auto px-4 py-16 text-center">
+        <h1 className="text-xl font-semibold mb-2">Order placed</h1>
+        <p className="text-muted-foreground mb-6">
+          Your order was placed successfully. A confirmation email is on its
+          way.
+        </p>
+        <Link href="/" className="underline">
+          Continue shopping
+        </Link>
+      </div>
+    )
+  }
+  const { order, cartItems } = stash
+  const totals = orderTotalsFromSummary(order.summary) ?? {
+    total: null,
+  }
+  // The completeCart() order carries FLATTENED items (checkout.md), not the
+  // order-detail pivot shape the template's default converter expects —
+  // pass the normalized cart-line items instead and drop `order.items`.
+  const orderForTemplate = { ...order, items: undefined }
+  return (
+    <>
+      {/* The purchase event, every configured vendor at once, fired once
+          per order per browser. Dedup keys match the platform's
+          server-side Purchase exactly, so the browser event and the
+          server event collapse into ONE conversion. */}
+      <TrackOrderPurchase order={order} items={cartItems} config={tracking} />
+      <OrderCompletedTemplate
+      order={orderForTemplate}
+      totals={totals}
+      items={cartItems.map(displayItemFromCartLine)}
+      // This reference store checks out via one merchant method (pp_* kill:
+      // methods are merchant-named, provider-less); a multi-tender store
+      // should stash the chosen tender from its checkout state alongside
+      // the order.
+      paymentMethodName={"Cash on delivery"}
+      storeHref="/"
+      />
+    </>
+  )
+}