@forgecart/cli 1.1.0 → 2.1.0

package/templates/storefront/src/components/Header.tsx

@@ -0,0 +1,47 @@
+'use client';
+
+import Link from 'next/link';
+import { useEffect, useState } from 'react';
+
+import { useCart } from '../lib/cart-context';
+
+/** Top navigation: Home / Products / Cart, with a live cart item count. */
+export function Header() {
+  const { itemCount } = useCart();
+
+  // The count is seeded from the server's `initialCart`, but a cookie set after
+  // that render can leave the client with a different count — rendering the
+  // badge on the server would then hydration-mismatch. Gate it on a
+  // post-hydration mount flag so the server emits no badge; it appears with the
+  // live count only once the client takes over.
+  const [mounted, setMounted] = useState(false);
+  useEffect(() => {
+    setMounted(true);
+  }, []);
+
+  return (
+    <header className="border-b border-gray-200 bg-white">
+      <div className="mx-auto flex max-w-6xl items-center justify-between px-4 py-4">
+        <Link href="/" className="text-lg font-bold tracking-tight text-gray-900">
+          Storefront
+        </Link>
+        <nav className="flex items-center gap-6 text-sm font-medium text-gray-600">
+          <Link href="/" className="hover:text-gray-900">
+            Home
+          </Link>
+          <Link href="/products" className="hover:text-gray-900">
+            Products
+          </Link>
+          <Link href="/cart" className="relative hover:text-gray-900">
+            Cart
+            {mounted && itemCount > 0 && (
+              <span className="ml-1 inline-flex h-5 min-w-5 items-center justify-center rounded-full bg-gray-900 px-1.5 text-xs font-semibold text-white">
+                {itemCount}
+              </span>
+            )}
+          </Link>
+        </nav>
+      </div>
+    </header>
+  );
+}

package/templates/storefront/src/components/ProductCard.tsx

@@ -0,0 +1,40 @@
+import type { Product } from '@forgecart/sdk/shop';
+import Link from 'next/link';
+
+import { formatPrice, getStartingPrice } from '../lib/forgecart';
+
+/** A product tile linking to its detail page. Used by the home and grid pages. */
+export function ProductCard({ product }: { product: Product }) {
+  const startingPrice = getStartingPrice(product);
+
+  return (
+    <Link
+      href={`/products/${product.slug}`}
+      className="group flex flex-col overflow-hidden rounded-lg border border-gray-200 bg-white transition hover:shadow-md"
+    >
+      <div className="aspect-square overflow-hidden bg-gray-100">
+        {product.featuredAsset ? (
+          // Plain <img> keeps the template dependency-free of next/image config.
+          // eslint-disable-next-line @next/next/no-img-element
+          <img
+            src={product.featuredAsset.preview}
+            alt={product.name}
+            className="h-full w-full object-cover transition group-hover:scale-105"
+          />
+        ) : (
+          <div className="flex h-full w-full items-center justify-center text-sm text-gray-400">
+            No image
+          </div>
+        )}
+      </div>
+      <div className="flex flex-1 flex-col gap-1 p-4">
+        <h3 className="font-medium text-gray-900">{product.name}</h3>
+        {startingPrice !== null && (
+          <p className="text-sm text-gray-600">
+            From {formatPrice(startingPrice)}
+          </p>
+        )}
+      </div>
+    </Link>
+  );
+}

package/templates/storefront/src/components/ProductPurchase.tsx

@@ -0,0 +1,91 @@
+'use client';
+
+import type { Product, ProductVariant } from '@forgecart/sdk/shop';
+import { useMemo, useState } from 'react';
+
+import { useCart } from '../lib/cart-context';
+import { formatPrice } from '../lib/forgecart';
+
+/**
+ * Variant picker + add-to-cart for the product detail page.
+ *
+ * The customer picks one value per option group (Size, Color, …); the matching
+ * variant drives the displayed price and what gets added to the cart — you add a
+ * **variant**, never the product. Single-variant products skip the selectors.
+ */
+export function ProductPurchase({ product }: { product: Product }) {
+  const { add, pending } = useCart();
+  const [added, setAdded] = useState(false);
+
+  // Default selection = the first variant's option values, so a price shows
+  // immediately. Keyed by option group id -> selected option id.
+  const [selected, setSelected] = useState<Record<string, string>>(() => {
+    const sel: Record<string, string> = {};
+    for (const option of product.variants[0]?.options ?? []) {
+      sel[option.groupId] = option.id;
+    }
+    return sel;
+  });
+
+  const variant: ProductVariant | undefined = useMemo(() => {
+    if (product.variants.length <= 1) {
+      return product.variants[0];
+    }
+    return product.variants.find(
+      (v) => v.options.length > 0 && v.options.every((o) => selected[o.groupId] === o.id),
+    );
+  }, [product.variants, selected]);
+
+  const onAdd = () => {
+    if (!variant) {
+      return;
+    }
+    add(variant.id, 1);
+    setAdded(true);
+    window.setTimeout(() => setAdded(false), 1500);
+  };
+
+  return (
+    <div className="space-y-4">
+      {variant ? (
+        <p className="text-xl font-semibold text-gray-900">{formatPrice(variant.priceWithTax)}</p>
+      ) : (
+        <p className="text-sm text-gray-500">Select options to see the price.</p>
+      )}
+
+      {product.optionGroups.map((group) => (
+        <div key={group.id}>
+          <h3 className="mb-1 text-sm font-medium text-gray-700">{group.name}</h3>
+          <div className="flex flex-wrap gap-2">
+            {group.options.map((opt) => {
+              const active = selected[group.id] === opt.id;
+              return (
+                <button
+                  key={opt.id}
+                  type="button"
+                  onClick={() => setSelected((s) => ({ ...s, [group.id]: opt.id }))}
+                  className={`rounded-md border px-3 py-1.5 text-sm transition ${
+                    active
+                      ? 'border-gray-900 bg-gray-900 text-white'
+                      : 'border-gray-300 text-gray-700 hover:border-gray-900'
+                  }`}
+                >
+                  {opt.name}
+                </button>
+              );
+            })}
+          </div>
+        </div>
+      ))}
+
+      <button
+        type="button"
+        onClick={onAdd}
+        disabled={!variant || pending}
+        className="rounded-md bg-gray-900 px-5 py-2.5 text-sm font-medium text-white transition hover:bg-gray-700 disabled:cursor-not-allowed disabled:opacity-50"
+      >
+        {pending ? 'Adding…' : added ? 'Added!' : variant ? 'Add to cart' : 'Unavailable'}
+      </button>
+    </div>
+  );
+}

package/templates/storefront/src/lib/cart-actions.ts

@@ -0,0 +1,148 @@
+'use server';
+
+import type { Order } from '@forgecart/sdk/shop';
+import { cookies } from 'next/headers';
+
+/**
+ * Server-side cart, backed by the ForgeCart shop **order** API (the real cart),
+ * not browser storage. Every export here is a Server Action returning the live
+ * `Order` (the SDK type) so callers render straight off it.
+ *
+ * The anonymous active order is tracked by a session token: the shop API returns
+ * a fresh token in the `forgecart-auth-token` response header on the first
+ * mutation, which we persist into the httpOnly `forgecart-session` cookie and
+ * send back as a bearer token on every subsequent request. The channel token and
+ * the session never reach the browser — all cart calls run here, on the server.
+ */
+
+const SHOP_API_URL = process.env.FORGECART_SHOP_API_URL ?? '';
+const CHANNEL_TOKEN = process.env.FORGECART_CHANNEL_TOKEN ?? '';
+const SESSION_COOKIE = 'forgecart-session';
+
+/** The order fields the storefront renders (a subset of the SDK `Order` type). */
+const ORDER_FIELDS = `
+  id
+  totalQuantity
+  subTotalWithTax
+  totalWithTax
+  currencyCode
+  lines {
+    id
+    quantity
+    unitPriceWithTax
+    linePriceWithTax
+    productVariant {
+      id
+      name
+    }
+    featuredAsset {
+      preview
+    }
+  }
+`;
+
+interface GraphQLResponse<T> {
+  data?: T;
+  errors?: { message: string }[];
+}
+
+/**
+ * Call the channel's shop API for a cart operation.
+ *
+ * `persist` MUST be `false` when called from a Server Component (the initial
+ * cart read): Server Components cannot set cookies — only Server Actions (the
+ * mutations) can, so they capture/refresh the session token.
+ */
+async function shopFetch<T>(
+  query: string,
+  variables: Record<string, unknown>,
+  persist: boolean,
+): Promise<GraphQLResponse<T>> {
+  const store = await cookies();
+  const session = store.get(SESSION_COOKIE)?.value;
+
+  const headers: Record<string, string> = {
+    'content-type': 'application/json',
+    'forgecart-token': CHANNEL_TOKEN,
+  };
+  if (session) {
+    headers.authorization = `Bearer ${session}`;
+  }
+
+  const res = await fetch(SHOP_API_URL, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify({ query, variables }),
+    cache: 'no-store',
+  });
+
+  if (persist) {
+    const token = res.headers.get('forgecart-auth-token');
+    if (token && token !== session) {
+      store.set(SESSION_COOKIE, token, {
+        httpOnly: true,
+        sameSite: 'lax',
+        path: '/',
+        maxAge: 60 * 60 * 24 * 30,
+      });
+    }
+  }
+
+  return (await res.json()) as GraphQLResponse<T>;
+}
+
+function unwrap<T>(res: GraphQLResponse<T>): T {
+  if (res.errors?.length) {
+    throw new Error(res.errors[0].message);
+  }
+  if (!res.data) {
+    throw new Error('Empty response from shop API');
+  }
+  return res.data;
+}
+
+/** Read the active order (cart). Safe to call from a Server Component. */
+export async function getCart(): Promise<Order | null> {
+  const res = await shopFetch<{ activeOrder: Order | null }>(
+    `query { activeOrder { ${ORDER_FIELDS} } }`,
+    {},
+    false,
+  );
+  return res.data?.activeOrder ?? null;
+}
+
+/** Add a variant to the cart (creates the order + session on first call). */
+export async function addToCart(variantId: string, quantity = 1): Promise<Order | null> {
+  const data = unwrap(
+    await shopFetch<{ addItemToOrder: Order }>(
+      `mutation($input: ShopAddItemToOrderInput!) { addItemToOrder(input: $input) { ${ORDER_FIELDS} } }`,
+      { input: { variantId, quantity } },
+      true,
+    ),
+  );
+  return data.addItemToOrder;
+}
+
+/** Set the quantity of a cart line (0 removes it). */
+export async function updateLine(lineId: string, quantity: number): Promise<Order | null> {
+  const data = unwrap(
+    await shopFetch<{ adjustOrderLine: Order }>(
+      `mutation($input: ShopAdjustOrderLineInput!) { adjustOrderLine(input: $input) { ${ORDER_FIELDS} } }`,
+      { input: { lineId, quantity } },
+      true,
+    ),
+  );
+  return data.adjustOrderLine;
+}
+
+/** Remove a line from the cart. */
+export async function removeLine(lineId: string): Promise<Order | null> {
+  const data = unwrap(
+    await shopFetch<{ removeOrderLine: Order }>(
+      `mutation($lineId: ID!) { removeOrderLine(lineId: $lineId) { ${ORDER_FIELDS} } }`,
+      { lineId },
+      true,
+    ),
+  );
+  return data.removeOrderLine;
+}

package/templates/storefront/src/lib/cart-context.tsx

@@ -0,0 +1,88 @@
+'use client';
+
+import type { Order } from '@forgecart/sdk/shop';
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useMemo,
+  useState,
+  useTransition,
+  type ReactNode,
+} from 'react';
+
+import { addToCart, getCart, removeLine as removeLineAction, updateLine } from './cart-actions';
+
+/**
+ * Cart state backed by the ForgeCart shop order API (see `cart-actions.ts`).
+ *
+ * `cart` is the live `Order` (the SDK type). The provider is seeded with the
+ * server-fetched active order (`initialCart`) so the first paint is correct,
+ * then every mutation calls a Server Action and replaces it with the order the
+ * API returns. `pending` is true while a cart mutation is in flight.
+ */
+interface CartContextValue {
+  cart: Order | null;
+  itemCount: number;
+  subtotal: number;
+  pending: boolean;
+  add: (variantId: string, quantity?: number) => void;
+  setQuantity: (lineId: string, quantity: number) => void;
+  remove: (lineId: string) => void;
+  refresh: () => void;
+}
+
+const CartContext = createContext<CartContextValue | null>(null);
+
+export function CartProvider({
+  initialCart,
+  children,
+}: {
+  initialCart: Order | null;
+  children: ReactNode;
+}) {
+  const [cart, setCart] = useState<Order | null>(initialCart);
+  const [pending, startTransition] = useTransition();
+
+  const run = useCallback((op: () => Promise<Order | null>) => {
+    startTransition(async () => {
+      setCart(await op());
+    });
+  }, []);
+
+  const add = useCallback(
+    (variantId: string, quantity = 1) => run(() => addToCart(variantId, quantity)),
+    [run],
+  );
+  const setQuantity = useCallback(
+    (lineId: string, quantity: number) => run(() => updateLine(lineId, quantity)),
+    [run],
+  );
+  const remove = useCallback((lineId: string) => run(() => removeLineAction(lineId)), [run]);
+  const refresh = useCallback(() => run(() => getCart()), [run]);
+
+  const value = useMemo<CartContextValue>(
+    () => ({
+      cart,
+      itemCount: cart?.totalQuantity ?? 0,
+      subtotal: cart?.subTotalWithTax ?? 0,
+      pending,
+      add,
+      setQuantity,
+      remove,
+      refresh,
+    }),
+    [cart, pending, add, setQuantity, remove, refresh],
+  );
+
+  return <CartContext.Provider value={value}>{children}</CartContext.Provider>;
+}
+
+/** Access the cart. Must be used inside a `<CartProvider>`. */
+export function useCart(): CartContextValue {
+  const ctx = useContext(CartContext);
+  if (!ctx) {
+    throw new Error('useCart must be used within a CartProvider');
+  }
+  return ctx;
+}

package/templates/storefront/src/lib/forgecart.ts

@@ -0,0 +1,187 @@
+import { ForgeCartShopClient } from '@forgecart/sdk';
+import type { Product, ProductList } from '@forgecart/sdk/shop';
+
+/**
+ * Server-side ForgeCart shop client.
+ *
+ * The storefront talks to the ForgeCart shop GraphQL API on behalf of a single
+ * channel. The channel token is sent as the `forgecart-token` header on every
+ * request (the SDK adds it from `channelToken`), and the endpoint points at the
+ * channel's shop-api.
+ *
+ * Both values come from the environment (`.env.local`, written by
+ * `forgecart init`):
+ *   - FORGECART_SHOP_API_URL  -> endpoint
+ *   - FORGECART_CHANNEL_TOKEN -> channelToken
+ *
+ * This module is server-only: it is imported exclusively from Server
+ * Components, so the channel token never reaches the browser. The construction
+ * mirrors the dashboard's `SdkClientService` (see
+ * app/dashboard/src/service/sdk-client.service.ts), adapted to read from env.
+ */
+
+const SHOP_API_URL = process.env.FORGECART_SHOP_API_URL ?? '';
+const CHANNEL_TOKEN = process.env.FORGECART_CHANNEL_TOKEN ?? '';
+
+let client: ForgeCartShopClient | null = null;
+
+/**
+ * Lazily construct and memoize the shop client.
+ *
+ * Constructing per-request would open a fresh websocket transport each time, so
+ * we keep a singleton for the lifetime of the server process.
+ */
+export function getShopClient(): ForgeCartShopClient {
+  if (!SHOP_API_URL) {
+    throw new Error(
+      'FORGECART_SHOP_API_URL is not set. Add it to .env.local (forgecart init writes it for you).',
+    );
+  }
+  if (!CHANNEL_TOKEN) {
+    throw new Error(
+      'FORGECART_CHANNEL_TOKEN is not set. Add it to .env.local (forgecart init writes it for you).',
+    );
+  }
+  if (!client) {
+    client = new ForgeCartShopClient({
+      endpoint: SHOP_API_URL,
+      channelToken: CHANNEL_TOKEN,
+    });
+  }
+  return client;
+}
+
+/** Convenience singleton for direct use in Server Components. */
+export const shopClient = (): ForgeCartShopClient => getShopClient();
+
+/* ------------------------------------------------------------------ *
+ * Typed product helpers
+ *
+ * The generated typed operations (`shopClient.product.shopProducts` /
+ * `.shopProduct`) only select `id` + `optionGroups`, which is not enough to
+ * render a storefront. We therefore use the SDK's supported raw-query escape
+ * hatch (`ForgeCartShopClient.query<T>(document, variables)`) with documents
+ * that select the display fields, typed against the SDK's own `Product` /
+ * `ProductList` types (`@forgecart/sdk/shop`).
+ * ------------------------------------------------------------------ */
+
+const PRODUCT_FIELDS = `
+  id
+  name
+  slug
+  description
+  featuredAsset {
+    id
+    preview
+  }
+  optionGroups {
+    id
+    name
+    code
+    options {
+      id
+      name
+      code
+    }
+  }
+  variants {
+    id
+    name
+    sku
+    price
+    priceWithTax
+    options {
+      id
+      name
+      code
+      groupId
+    }
+  }
+`;
+
+const PRODUCTS_QUERY = `query StorefrontProducts($options: ListQueryOptions) {
+  products(options: $options) {
+    items {${PRODUCT_FIELDS}}
+    totalItems
+  }
+}`;
+
+const PRODUCT_BY_SLUG_QUERY = `query StorefrontProduct($slug: String) {
+  product(slug: $slug) {${PRODUCT_FIELDS}}
+}`;
+
+const PRODUCT_BY_ID_QUERY = `query StorefrontProductById($id: ID) {
+  product(id: $id) {${PRODUCT_FIELDS}}
+}`;
+
+interface ProductsQueryResult {
+  products: Pick<ProductList, 'items' | 'totalItems'>;
+}
+
+interface ProductQueryResult {
+  product: Product | null;
+}
+
+/**
+ * Fetch a page of products for the channel.
+ *
+ * `take` / `skip` map onto the shop API's `ListQueryOptions`.
+ */
+export async function getProducts(
+  options: { take?: number; skip?: number } = {},
+): Promise<{ items: Product[]; totalItems: number }> {
+  const { take = 24, skip = 0 } = options;
+  const result = await getShopClient().query<ProductsQueryResult>(PRODUCTS_QUERY, {
+    options: { take, skip },
+  });
+  return {
+    items: result.products.items,
+    totalItems: result.products.totalItems,
+  };
+}
+
+/** Fetch a single product by its URL slug. Returns `null` if not found. */
+export async function getProductBySlug(slug: string): Promise<Product | null> {
+  const result = await getShopClient().query<ProductQueryResult>(PRODUCT_BY_SLUG_QUERY, {
+    slug,
+  });
+  return result.product ?? null;
+}
+
+/** Fetch a single product by id. Returns `null` if not found. */
+export async function getProductById(id: string): Promise<Product | null> {
+  const result = await getShopClient().query<ProductQueryResult>(PRODUCT_BY_ID_QUERY, {
+    id,
+  });
+  return result.product ?? null;
+}
+
+/**
+ * Convenience: fetch a small set of products to feature on the home page.
+ */
+export async function getFeaturedProducts(count = 4): Promise<Product[]> {
+  const { items } = await getProducts({ take: count });
+  return items;
+}
+
+/** Lowest variant price for a product, in minor units, or `null` if none. */
+export function getStartingPrice(product: Product): number | null {
+  if (product.variants.length === 0) {
+    return null;
+  }
+  return product.variants.reduce(
+    (min, v) => (v.priceWithTax < min ? v.priceWithTax : min),
+    product.variants[0].priceWithTax,
+  );
+}
+
+/**
+ * Format a minor-unit price (cents) as a currency string. Defaults to USD;
+ * pass a different ISO currency code as needed.
+ */
+export function formatPrice(minorUnits: number, currency = 'USD'): string {
+  return new Intl.NumberFormat('en-US', {
+    style: 'currency',
+    currency,
+  }).format(minorUnits / 100);
+}

package/{dist/templates/storefront-additions → templates/storefront}/tailwind.config.js

@@ -5,4 +5,4 @@ module.exports = {
     extend: {},
   },
   plugins: [],
-}
+};

package/templates/storefront/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["dom", "dom.iterable", "ES2022"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "plugins": [{ "name": "next" }],
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2022 Vendure
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.