@forgecart/cli 2.202606151453.0 → 2.202607070306.0

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

@@ -1,16 +1,22 @@
 import { ForgeCartShopClient } from '@forgecart/sdk';
-import type { Product, ProductList } from '@forgecart/sdk/shop';
+import type {
+  ShopProductFieldFragment as Product,
+  ShopSellingPlanFieldFragment as SellingPlan,
+  ShopSellingPlanGroupFieldFragment as SellingPlanGroup,
+} 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.
+ * channel through the SDK's generated, typed operations — every read here is a
+ * typed method on the client (no hand-written query documents), and every type
+ * the components render is the SDK's own (`@forgecart/sdk/shop`).
  *
- * Both values come from the environment (`.env.local`, written by
- * `forgecart init`):
+ * 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
  *
@@ -26,10 +32,12 @@ const CHANNEL_TOKEN = process.env.FORGECART_CHANNEL_TOKEN ?? '';
 let client: ForgeCartShopClient | null = null;
 
 /**
- * Lazily construct and memoize the shop client.
+ * Lazily construct and memoize the channel-scoped 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.
+ * All reads here are anonymous (channel scope only), so one client instance
+ * serves the whole server process. Per-shopper session state lives in
+ * `cart-actions.ts`, which constructs a per-request client around the session
+ * cookie instead.
  */
 export function getShopClient(): ForgeCartShopClient {
   if (!SHOP_API_URL) {
@@ -54,73 +62,20 @@ export function getShopClient(): ForgeCartShopClient {
 /** 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;
-}
+// The SDK's operation-shaped fragment types, re-exported under their domain
+// names so components import them from one place. These are exactly what the
+// typed operations return: `Product`/`ProductVariant` carry the storefront
+// display fields (name, slug, assets, priced variants); `Order`/`OrderLine`
+// the live cart incl. the subscription fields; the selling-plan pair backs the
+// subscription selector and the whole-cart subscribe box.
+export type {
+  ShopOrderFieldFragment as Order,
+  ShopOrderLineFieldFragment as OrderLine,
+  ShopProductFieldFragment as Product,
+  ShopProductVariantFieldFragment as ProductVariant,
+  ShopSellingPlanFieldFragment as SellingPlan,
+  ShopSellingPlanGroupFieldFragment as SellingPlanGroup,
+} from '@forgecart/sdk/shop';
 
 /**
  * Fetch a page of products for the channel.
@@ -131,29 +86,20 @@ 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,
-  };
+  const { products } = await getShopClient().product.shopProducts({ options: { take, skip } });
+  return { items: products.items, totalItems: 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;
+  const { product } = await getShopClient().product.shopProduct({ slug });
+  return 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;
+  const { product } = await getShopClient().product.shopProduct({ id });
+  return product ?? null;
 }
 
 /**
@@ -164,6 +110,63 @@ export async function getFeaturedProducts(count = 4): Promise<Product[]> {
   return items;
 }
 
+/** Fetch the subscription groups a given variant is eligible for (per-line subscribe). */
+export async function getSellingPlanGroupsForVariant(
+  variantId: string,
+): Promise<SellingPlanGroup[]> {
+  const { sellingPlanGroupsForVariant } = await getShopClient().sellingPlan.sellingPlanGroupsForVariant({ variantId });
+  return sellingPlanGroupsForVariant;
+}
+
+/** Fetch the channel-wide subscription groups (whole-cart subscribe box). */
+export async function getChannelSellingPlanGroups(): Promise<SellingPlanGroup[]> {
+  const { channelSellingPlanGroups } = await getShopClient().sellingPlan.channelSellingPlanGroups();
+  return channelSellingPlanGroups;
+}
+
+/**
+ * Preview the per-unit price a plan yields from the one-time `priceWithTax`.
+ *
+ * Mirrors the server's pricing policy: `none` keeps the price, `percentage`
+ * applies the percent discount (rounded to whole minor units), `fixed_amount`
+ * subtracts the minor-unit adjustment (floored at zero). A `null`
+ * `adjustmentValue` (only valid for `none`) is treated as no adjustment.
+ */
+export function getPlanPreviewPrice(basePrice: number, plan: SellingPlan): number {
+  if (plan.pricingPolicy === 'percentage') {
+    const adjustment = plan.adjustmentValue ?? 0;
+    // `adjustmentValue` is a whole-number percent (e.g. 15 -> 15% off).
+    const PERCENT_BASE = 100;
+    return Math.round(basePrice * (1 - adjustment / PERCENT_BASE));
+  }
+  if (plan.pricingPolicy === 'fixed_amount') {
+    return Math.max(0, basePrice - (plan.adjustmentValue ?? 0));
+  }
+  return basePrice;
+}
+
+/**
+ * A short human-readable savings hint for a plan, or `null` when it offers no
+ * discount (policy `none`, a zero adjustment, or a non-positive percentage).
+ */
+export function getPlanSavingsLabel(plan: SellingPlan, currency = 'USD'): string | null {
+  if (plan.pricingPolicy === 'percentage' && (plan.adjustmentValue ?? 0) > 0) {
+    return `Save ${plan.adjustmentValue}%`;
+  }
+  if (plan.pricingPolicy === 'fixed_amount' && (plan.adjustmentValue ?? 0) > 0) {
+    return `Save ${formatPrice(plan.adjustmentValue ?? 0, currency)}`;
+  }
+  return null;
+}
+
+/**
+ * The billing cadence as a phrase, e.g. "every 1 monthly" or "every 2 weekly",
+ * built from the plan's interval count and the (lower-cased) billing interval.
+ */
+export function getPlanCadenceLabel(plan: SellingPlan): string {
+  return `every ${plan.intervalCount} ${plan.billingInterval.toLowerCase()}`;
+}
+
 /** 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) {