create-nextblock 0.13.7 → 0.13.9

package/templates/nextblock-template/lib/auth/twoFactor.ts

@@ -16,20 +16,32 @@ const EMAIL_CODE_TTL_MS = 5 * 60 * 1000; // 5 minutes
 const TWO_FACTOR_SESSION_TTL_SECONDS = 12 * 60 * 60; // 12 hours
 
 /**
- * Create and persist a hashed 6-digit email code and return the RAW code so the
- * caller can email it. Prior unconsumed codes for the user are invalidated.
+ * How many of a user's most recent codes stay usable at once.
+ *
+ * Relays (SMTP2GO, SES, …) do not preserve send order and can take minutes to deliver, so
+ * a user who clicks "resend" often receives the ORIGINAL code first. Hard-invalidating on
+ * every request made that first-arriving code fail — the classic "the code you emailed me
+ * doesn't work" loop. Keeping a short window of concurrently valid codes removes the race;
+ * the guess surface stays bounded because only this many are ever checked and all of them
+ * die on first successful use (and after EMAIL_CODE_TTL_MS regardless).
+ */
+const MAX_LIVE_EMAIL_CODES = 3;
+
+/**
+ * Minimum gap between user-requested codes. Deliberately shorter than the UI countdown so a
+ * normal user never sees the server refusal — the client timer is a courtesy that a crafted
+ * request ignores, and this is what actually bounds how fast one session can drive the mailer.
+ */
+const RESEND_COOLDOWN_MS = 20_000;
+
+/**
+ * Create and persist a hashed 6-digit email code and return the RAW code so the caller can
+ * email it. Earlier codes are deliberately left alive — see MAX_LIVE_EMAIL_CODES. Kept to a
+ * single round trip: this sits directly in front of the SMTP handoff on a click path.
  */
 export async function createEmailChallenge(userId: string): Promise<string> {
   const code = generateNumericCode(6);
   const svc = getServiceRoleSupabaseClient();
-  const nowIso = new Date().toISOString();
-
-  // Invalidate any earlier pending codes so only the newest one works.
-  await svc
-    .from('email_2fa_challenges')
-    .update({ consumed_at: nowIso })
-    .eq('user_id', userId)
-    .is('consumed_at', null);
 
   await svc.from('email_2fa_challenges').insert({
     user_id: userId,
@@ -40,6 +52,27 @@ export async function createEmailChallenge(userId: string): Promise<string> {
   return code;
 }
 
+/**
+ * Seconds the caller must wait before another code may be requested, or 0 when a send is
+ * allowed. Considers consumed rows too — this measures time since the last SEND, not since
+ * the last still-usable code.
+ */
+export async function getEmailResendCooldownSeconds(userId: string): Promise<number> {
+  const svc = getServiceRoleSupabaseClient();
+  const { data } = await svc
+    .from('email_2fa_challenges')
+    .select('created_at')
+    .eq('user_id', userId)
+    .order('created_at', { ascending: false })
+    .limit(1);
+
+  const latest = data?.[0]?.created_at;
+  if (!latest) return 0;
+  const elapsed = Date.now() - new Date(latest).getTime();
+  if (!Number.isFinite(elapsed) || elapsed >= RESEND_COOLDOWN_MS) return 0;
+  return Math.ceil((RESEND_COOLDOWN_MS - elapsed) / 1000);
+}
+
 /** True when the user has an unconsumed, unexpired email code awaiting entry. */
 export async function hasPendingEmailChallenge(userId: string): Promise<boolean> {
   const svc = getServiceRoleSupabaseClient();
@@ -53,7 +86,11 @@ export async function hasPendingEmailChallenge(userId: string): Promise<boolean>
   return Boolean(data && data.length > 0);
 }
 
-/** Verify a submitted email code against the newest live challenge. */
+/**
+ * Verify a submitted email code against the user's live challenges. Any of the newest
+ * MAX_LIVE_EMAIL_CODES is accepted, so a code that arrives out of order still works;
+ * anything older than that window is unreachable even though its row lingers until expiry.
+ */
 export async function verifyEmailChallenge(userId: string, code: string): Promise<boolean> {
   const trimmed = (code || '').trim();
   if (!/^\d{6}$/.test(trimmed)) return false;
@@ -67,14 +104,20 @@ export async function verifyEmailChallenge(userId: string, code: string): Promis
     .is('consumed_at', null)
     .gt('expires_at', nowIso)
     .order('created_at', { ascending: false })
-    .limit(5);
+    .limit(MAX_LIVE_EMAIL_CODES);
 
   if (!data || data.length === 0) return false;
   const candidateHash = sha256Hex(trimmed);
   const match = data.find((row) => safeEqual(row.token_hash, candidateHash));
   if (!match) return false;
 
-  await svc.from('email_2fa_challenges').update({ consumed_at: nowIso }).eq('id', match.id);
+  // Burn every live code for this user, not just the matched row: the siblings from a
+  // resend have served their purpose and must not stay redeemable after a success.
+  await svc
+    .from('email_2fa_challenges')
+    .update({ consumed_at: nowIso })
+    .eq('user_id', userId)
+    .is('consumed_at', null);
   return true;
 }
 

package/templates/nextblock-template/lib/blocks/ProductGridBlock.tsx

@@ -1,139 +1,78 @@
-import { ProductGrid } from '@nextblock-cms/ecommerce/components/ProductGrid';
-import { getProducts } from '@nextblock-cms/ecommerce/server';
-import { normalizePriceMap, normalizeSalePriceMap } from '@nextblock-cms/ecommerce/currency';
-import { getVariantEffectivePriceRange } from '@nextblock-cms/ecommerce/variation-utils';
-
-
-import type { ProductGridBlockContent } from './ecommerce-block-schemas';
-
-import { getSsgSupabaseClient } from '@nextblock-cms/db/server';
-
-interface ProductGridBlockProps {
-  content: ProductGridBlockContent;
-  languageId?: number;
-  excludeProductId?: string;
-  excludeTranslationGroupId?: string | null;
-}
-
-// Component (Server Component)
-export const ProductGridBlock = async ({ 
-  content, 
-  languageId,
-  excludeProductId,
-  excludeTranslationGroupId,
-}: ProductGridBlockProps) => {
-  const supabase = getSsgSupabaseClient();
-  // Fetch products filtered by language
-  // We fetch more to ensure we have enough after manual checks
-  const { data: products } = await getProducts(supabase, {
-    languageId,
-    categoryId: content.type === 'category' ? content.categoryId : undefined,
-    limit: content.limit + 2, 
-  }); 
-  
-  const productRows = (products || []) as any[];
-
-  if (productRows.length === 0) {
-      return null; // Silent fail if no products
-  }
-
-  // 1. Filter out current product and its translations
-  const filteredProducts = productRows.filter((p) => {
-    if (excludeProductId && p.id === excludeProductId) return false;
-    if (excludeTranslationGroupId && p.translation_group_id === excludeTranslationGroupId) return false;
-    return true;
-  });
-
-  // 2. Hide if no products remain
-  if (filteredProducts.length === 0) {
-      return null;
-  }
-
-  // 3. Transform DB products to UI products
-  const uiProducts = filteredProducts.slice(0, content.limit).map(p => {
-      const productRecord = p as any;
-      let imageUrl = undefined;
-      // Accessing the nested media object correctly (array of objects with media property)
-      // The type from getProducts select is: product_media: { media: { file_path: string | null } | null }[]
-      const mediaItem = p.product_media?.[0]?.media;
-      if (mediaItem?.file_path) {
-         if (mediaItem.file_path.startsWith('http')) {
-           imageUrl = mediaItem.file_path;
-         } else if (process.env.NEXT_PUBLIC_R2_BASE_URL) {
-           imageUrl = `${process.env.NEXT_PUBLIC_R2_BASE_URL}/${mediaItem.file_path}`;
-         } else {
-           imageUrl = `${process.env.NEXT_PUBLIC_SUPABASE_URL ?? ''}/storage/v1/object/public/media/${mediaItem.file_path}`;
-         }
-      }
-
-      const variantPriceRange = getVariantEffectivePriceRange(
-        (p.product_variants || []).map((variant: any) => ({
-          price: variant.price,
-          sale_price: variant.sale_price,
-          sale_start_at: variant.sale_start_at ?? null,
-          sale_end_at: variant.sale_end_at ?? null,
-        }))
-      );
-
-      return {
-        id: p.id,
-        title: p.title,
-        slug: p.slug,
-        sku: p.sku,
-        average_rating: p.average_rating,
-        total_reviews: p.total_reviews,
-        upc: p.upc || undefined,
-        price: p.price,
-        prices: normalizePriceMap(p.prices),
-        sale_price: typeof p.sale_price === 'number' ? p.sale_price : undefined,
-        sale_prices: normalizeSalePriceMap(p.sale_prices),
-        sale_start_at: p.sale_start_at ?? null,
-        sale_end_at: p.sale_end_at ?? null,
-        scheduled_price: typeof p.scheduled_price === 'number' ? p.scheduled_price : undefined,
-        scheduled_prices: normalizePriceMap(p.scheduled_prices),
-        scheduled_price_at: p.scheduled_price_at ?? null,
-        is_taxable: p.is_taxable ?? true,
-        product_type: productRecord.product_type ?? undefined,
-        payment_provider: productRecord.payment_provider ?? undefined,
-        price_range_min: variantPriceRange?.min ?? null,
-        price_range_max: variantPriceRange?.max ?? null,
-        image_url: imageUrl,
-        short_description: p.short_description || undefined,
-        categories: (p.product_categories || []).map((pc: any) => pc.category).filter(Boolean),
-        language_id: p.language_id as number,
-        translation_group_id: p.translation_group_id || "",
-        freemius_product_id: productRecord.freemius_product_id || undefined,
-        freemius_plan_id: productRecord.freemius_plan_id || undefined,
-        trial_period_days: productRecord.trial_period_days ?? 0,
-        trial_requires_payment_method:
-          productRecord.trial_requires_payment_method ?? false,
-        freemius_plans: productRecord.freemius_plans,
-        has_variants: (p.product_variants?.length || 0) > 0,
-        product_variants: (p.product_variants || []).map((variant: any) => ({
-          id: variant.id,
-          price: variant.price,
-          prices: normalizePriceMap(variant.prices),
-          sale_price: variant.sale_price,
-          sale_prices: normalizeSalePriceMap(variant.sale_prices),
-          sale_start_at: variant.sale_start_at ?? null,
-          sale_end_at: variant.sale_end_at ?? null,
-          scheduled_price: variant.scheduled_price ?? null,
-          scheduled_prices: normalizePriceMap(variant.scheduled_prices),
-          scheduled_price_at: variant.scheduled_price_at ?? null,
-        })),
-      };
-  });
-
-  return (
-    <section className="py-12">
-       {content.title && (
-         <div className="container mb-8">
-            <h2 className="text-3xl font-bold tracking-tight">{content.title}</h2>
-         </div>
-       )}
-       <div className="container">
-          <ProductGrid products={uiProducts} />
-       </div>
-    </section>
-  );
-};
+import ProductGridClient from '../../components/blocks/ProductGridClient';
+
+import {
+  PRODUCT_GRID_UNLIMITED,
+  resolveProductGridCategoryIds,
+  resolveProductGridLimit,
+  resolveProductGridProductIds,
+  resolveProductGridShowPagination,
+  type ProductGridBlockContent,
+} from './ecommerce-block-schemas';
+import { loadProductGridPage, type ProductGridQuery } from './product-grid-data';
+
+interface ProductGridBlockProps {
+  content: ProductGridBlockContent;
+  languageId?: number;
+  excludeProductId?: string;
+  excludeTranslationGroupId?: string | null;
+}
+
+// Component (Server Component)
+export const ProductGridBlock = async ({
+  content,
+  languageId,
+  excludeProductId,
+  excludeTranslationGroupId,
+}: ProductGridBlockProps) => {
+  const isManual = content.type === 'manual';
+  const handPickedIds = isManual ? resolveProductGridProductIds(content) : [];
+
+  // A hand-picked grid with nothing picked has nothing to say — render nothing
+  // rather than silently falling back to unrelated products.
+  if (isManual && handPickedIds.length === 0) {
+    return null;
+  }
+
+  const paginate = resolveProductGridShowPagination(content);
+  // A hand-picked list is already exactly what the author asked for, so `limit`
+  // acts purely as a page size there — never as a cap.
+  const limit = isManual && !paginate ? PRODUCT_GRID_UNLIMITED : resolveProductGridLimit(content);
+
+  const query: ProductGridQuery = {
+    type: content.type ?? 'latest',
+    // With no category selected this resolves to an empty filter, i.e. latest products.
+    categoryIds: content.type === 'category' ? resolveProductGridCategoryIds(content) : undefined,
+    productIds: isManual ? handPickedIds : undefined,
+    limit,
+    page: 1,
+    languageId,
+    excludeProductId,
+    excludeTranslationGroupId,
+  };
+
+  const { products, totalCount } = await loadProductGridPage(query);
+
+  if (products.length === 0) {
+    return null; // Silent fail if no products
+  }
+
+  const showPagination = paginate && totalCount > limit;
+
+  return (
+    <section className="py-12">
+      {content.title && (
+        <div className="container mb-8">
+          <h2 className="text-3xl font-bold tracking-tight">{content.title}</h2>
+        </div>
+      )}
+      <div className="container">
+        <ProductGridClient
+          initialProducts={products}
+          totalCount={totalCount}
+          query={query}
+          showPagination={showPagination}
+        />
+      </div>
+    </section>
+  );
+};

package/templates/nextblock-template/lib/blocks/blockRegistry.ts

@@ -491,13 +491,13 @@ export const blockRegistry: Record<BlockType, BlockDefinition> = {
     type: "product_grid",
     label: "Product Grid",
     icon: "ShoppingBag", // Lucide icon
-    initialContent: { type: 'latest', limit: 6 } as ProductGridBlockContent,
+    initialContent: { type: 'latest', limit: 6, showPagination: false } as ProductGridBlockContent,
     editorComponentFilename: "ProductGridBlockEditor.tsx", // Assuming standard naming
     rendererComponentFilename: "ProductGridBlockRenderer.tsx", // Assuming mapping to ProductGridBlock.tsx handled by renderer map not shown here, or we need to ensure the renderer map uses the file we created. The prompt implies creating the file in `lib/blocks` serves as the component. I will assume the system maps it.
     schema: ProductGridBlockSchema,
     documentation: {
-        description: 'Displays a grid of products.',
-        useCases: ['Homepage featured products', 'Category pages']
+        description: 'Displays a grid of products: the latest ones, everything in one or more categories, or a hand-picked list.',
+        useCases: ['Homepage featured products', 'Category pages', 'Curated collections']
     }
   },
 

package/templates/nextblock-template/lib/blocks/blockTypes.ts

@@ -16,3 +16,22 @@ export const availableBlockTypes = [
 ] as const;
 
 export type BlockType = (typeof availableBlockTypes)[number];
+
+/**
+ * Block types provided by the premium `ecommerce` package. They are hidden from
+ * the block picker when the package is not activated — see
+ * `app/cms/blocks/components/BlockTypeSelector.tsx`.
+ */
+export const ecommerceBlockTypes = [
+  "product_grid",
+  "featured_product",
+  "cart",
+  "checkout",
+  "product_details",
+] as const satisfies readonly BlockType[];
+
+export type EcommerceBlockType = (typeof ecommerceBlockTypes)[number];
+
+export function isEcommerceBlockType(type: string): type is EcommerceBlockType {
+  return (ecommerceBlockTypes as readonly string[]).includes(type);
+}

package/templates/nextblock-template/lib/blocks/ecommerce-block-schemas.ts

@@ -1,14 +1,73 @@
 import { z } from '../zod-config';
 
+/** Upper bound for how many categories / products a single grid can reference. */
+export const PRODUCT_GRID_MAX_CATEGORIES = 20;
+export const PRODUCT_GRID_MAX_PRODUCTS = 24;
+export const PRODUCT_GRID_MAX_LIMIT = 48;
+/** `limit: 0` means "no cap" — show every matching product on one page. */
+export const PRODUCT_GRID_UNLIMITED = 0;
+/** Page size applied when pagination is switched on from an unlimited grid. */
+export const PRODUCT_GRID_DEFAULT_PAGE_SIZE = 12;
+
 // Product Grid Block Schema
 export const ProductGridBlockSchema = z.object({
-  type: z.enum(['latest', 'category']).default('latest'),
+  /**
+   * Where the grid gets its products:
+   * - `latest`   newest active products
+   * - `category` every product in any of `categoryIds`
+   * - `manual`   exactly the products in `productIds`, in that order
+   */
+  type: z.enum(['latest', 'category', 'manual']).default('latest'),
+  /** Legacy single-category field, superseded by `categoryIds`. Still read so blocks saved before multi-select keep working. */
   categoryId: z.string().optional(),
-  limit: z.number().min(1).max(20).default(6),
+  categoryIds: z.array(z.string()).max(PRODUCT_GRID_MAX_CATEGORIES).optional(),
+  productIds: z.array(z.string()).max(PRODUCT_GRID_MAX_PRODUCTS).optional(),
+  /** Products per page when paginating, otherwise the display cap. `0` means unlimited. */
+  limit: z.number().min(PRODUCT_GRID_UNLIMITED).max(PRODUCT_GRID_MAX_LIMIT).default(6),
+  /** Page through everything that matches instead of stopping at `limit`. */
+  showPagination: z.boolean().default(false),
   title: z.string().optional(),
 });
 export type ProductGridBlockContent = z.infer<typeof ProductGridBlockSchema>;
 
+/**
+ * Selected categories, reading the legacy single `categoryId` when a block was
+ * saved before multi-select existed.
+ */
+export function resolveProductGridCategoryIds(
+  content: Partial<ProductGridBlockContent>
+): string[] {
+  const ids = (content.categoryIds ?? []).filter(Boolean);
+  if (ids.length > 0) return Array.from(new Set(ids));
+  return content.categoryId ? [content.categoryId] : [];
+}
+
+/** Hand-picked products, in the order the author chose them. */
+export function resolveProductGridProductIds(
+  content: Partial<ProductGridBlockContent>
+): string[] {
+  return Array.from(new Set((content.productIds ?? []).filter(Boolean)));
+}
+
+/**
+ * Page size / display cap, clamped to the supported range. Returns
+ * `PRODUCT_GRID_UNLIMITED` (0) when the author asked for every match.
+ */
+export function resolveProductGridLimit(
+  content: Partial<ProductGridBlockContent>
+): number {
+  const raw = typeof content.limit === 'number' ? content.limit : 6;
+  if (!Number.isFinite(raw) || raw < 0) return 6;
+  return Math.min(Math.floor(raw), PRODUCT_GRID_MAX_LIMIT);
+}
+
+/** Pagination needs a page size, so an unlimited grid is always a single page. */
+export function resolveProductGridShowPagination(
+  content: Partial<ProductGridBlockContent>
+): boolean {
+  return Boolean(content.showPagination) && resolveProductGridLimit(content) > 0;
+}
+
 // Featured Product Block Schema
 export const FeaturedProductBlockSchema = z.object({
   productId: z.string().min(1, 'Product is required'),

package/templates/nextblock-template/lib/blocks/product-grid-data.ts

@@ -0,0 +1,210 @@
+import { getProducts } from '@nextblock-cms/ecommerce/server';
+import { normalizePriceMap, normalizeSalePriceMap } from '@nextblock-cms/ecommerce/currency';
+import { getVariantEffectivePriceRange } from '@nextblock-cms/ecommerce/variation-utils';
+import type { Product } from '@nextblock-cms/ecommerce/types';
+import { getSsgSupabaseClient } from '@nextblock-cms/db/server';
+
+import { PRODUCT_GRID_MAX_LIMIT } from './ecommerce-block-schemas';
+
+type SupabaseClientLike = ReturnType<typeof getSsgSupabaseClient>;
+
+export interface ProductGridQuery {
+  type?: 'latest' | 'category' | 'manual';
+  categoryIds?: string[];
+  productIds?: string[];
+  /** Products per page, or `0` for every match on a single page. */
+  limit: number;
+  /** 1-based page number. */
+  page?: number;
+  languageId?: number;
+  excludeProductId?: string;
+  excludeTranslationGroupId?: string | null;
+}
+
+export interface ProductGridPage {
+  products: Product[];
+  /** Total matches across all pages, before exclusions. */
+  totalCount: number;
+}
+
+/** Turn a `getProducts` row into the shape `<ProductGrid />` renders. */
+export function mapProductRowToUiProduct(p: any): Product {
+  const productRecord = p as any;
+  let imageUrl = undefined;
+  // Accessing the nested media object correctly (array of objects with media property)
+  // The type from getProducts select is: product_media: { media: { file_path: string | null } | null }[]
+  const mediaItem = p.product_media?.[0]?.media;
+  if (mediaItem?.file_path) {
+    if (mediaItem.file_path.startsWith('http')) {
+      imageUrl = mediaItem.file_path;
+    } else if (process.env.NEXT_PUBLIC_R2_BASE_URL) {
+      imageUrl = `${process.env.NEXT_PUBLIC_R2_BASE_URL}/${mediaItem.file_path}`;
+    } else {
+      imageUrl = `${process.env.NEXT_PUBLIC_SUPABASE_URL ?? ''}/storage/v1/object/public/media/${mediaItem.file_path}`;
+    }
+  }
+
+  const variantPriceRange = getVariantEffectivePriceRange(
+    (p.product_variants || []).map((variant: any) => ({
+      price: variant.price,
+      sale_price: variant.sale_price,
+      sale_start_at: variant.sale_start_at ?? null,
+      sale_end_at: variant.sale_end_at ?? null,
+    }))
+  );
+
+  return {
+    id: p.id,
+    title: p.title,
+    slug: p.slug,
+    sku: p.sku,
+    average_rating: p.average_rating,
+    total_reviews: p.total_reviews,
+    upc: p.upc || undefined,
+    price: p.price,
+    prices: normalizePriceMap(p.prices),
+    sale_price: typeof p.sale_price === 'number' ? p.sale_price : undefined,
+    sale_prices: normalizeSalePriceMap(p.sale_prices),
+    sale_start_at: p.sale_start_at ?? null,
+    sale_end_at: p.sale_end_at ?? null,
+    scheduled_price: typeof p.scheduled_price === 'number' ? p.scheduled_price : undefined,
+    scheduled_prices: normalizePriceMap(p.scheduled_prices),
+    scheduled_price_at: p.scheduled_price_at ?? null,
+    is_taxable: p.is_taxable ?? true,
+    product_type: productRecord.product_type ?? undefined,
+    payment_provider: productRecord.payment_provider ?? undefined,
+    price_range_min: variantPriceRange?.min ?? null,
+    price_range_max: variantPriceRange?.max ?? null,
+    image_url: imageUrl,
+    short_description: p.short_description || undefined,
+    categories: (p.product_categories || []).map((pc: any) => pc.category).filter(Boolean),
+    language_id: p.language_id as number,
+    translation_group_id: p.translation_group_id || "",
+    freemius_product_id: productRecord.freemius_product_id || undefined,
+    freemius_plan_id: productRecord.freemius_plan_id || undefined,
+    trial_period_days: productRecord.trial_period_days ?? 0,
+    trial_requires_payment_method:
+      productRecord.trial_requires_payment_method ?? false,
+    freemius_plans: productRecord.freemius_plans,
+    has_variants: (p.product_variants?.length || 0) > 0,
+    product_variants: (p.product_variants || []).map((variant: any) => ({
+      id: variant.id,
+      price: variant.price,
+      prices: normalizePriceMap(variant.prices),
+      sale_price: variant.sale_price,
+      sale_prices: normalizeSalePriceMap(variant.sale_prices),
+      sale_start_at: variant.sale_start_at ?? null,
+      sale_end_at: variant.sale_end_at ?? null,
+      scheduled_price: variant.scheduled_price ?? null,
+      scheduled_prices: normalizePriceMap(variant.scheduled_prices),
+      scheduled_price_at: variant.scheduled_price_at ?? null,
+    })),
+  } as Product;
+}
+
+/**
+ * Load hand-picked products in the author's chosen order. Selections are made
+ * against a single language, so when the page renders in another language each
+ * pick is swapped for its translation (falling back to the picked row when the
+ * product has not been translated yet).
+ */
+async function fetchHandPickedProducts(
+  supabase: SupabaseClientLike,
+  productIds: string[],
+  languageId?: number
+): Promise<any[]> {
+  const { data: pickedRows } = await getProducts(supabase, {
+    productIds,
+    limit: productIds.length,
+  });
+
+  const picked = (pickedRows || []) as any[];
+  if (picked.length === 0) return [];
+
+  const rowById = new Map(picked.map((row) => [row.id, row]));
+  let ordered = productIds
+    .map((id) => rowById.get(id))
+    .filter(Boolean) as any[];
+
+  if (languageId && ordered.some((row) => row.language_id !== languageId)) {
+    const groupIds = Array.from(
+      new Set(ordered.map((row) => row.translation_group_id).filter(Boolean))
+    ) as string[];
+
+    if (groupIds.length > 0) {
+      const { data: translatedRows } = await getProducts(supabase, {
+        translationGroupIds: groupIds,
+        languageId,
+        limit: groupIds.length,
+      });
+      const rowByGroup = new Map(
+        ((translatedRows || []) as any[]).map((row) => [row.translation_group_id, row])
+      );
+      ordered = ordered.map((row) => rowByGroup.get(row.translation_group_id) ?? row);
+    }
+  }
+
+  // Picking two translations of the same product resolves to one product here.
+  const seen = new Set<string>();
+  return ordered.filter((row) => {
+    const key = row.translation_group_id || row.id;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+/** Drop the product the grid is embedded under (related-products placements). */
+function applyExclusions(rows: any[], query: ProductGridQuery): any[] {
+  const { excludeProductId, excludeTranslationGroupId } = query;
+  if (!excludeProductId && !excludeTranslationGroupId) return rows;
+  return rows.filter((row) => {
+    if (excludeProductId && row.id === excludeProductId) return false;
+    if (excludeTranslationGroupId && row.translation_group_id === excludeTranslationGroupId) {
+      return false;
+    }
+    return true;
+  });
+}
+
+/**
+ * One page of a product grid. Shared by the block's server render (page 1) and
+ * the pagination server action (page N) so both agree on ordering and shape.
+ */
+export async function loadProductGridPage(query: ProductGridQuery): Promise<ProductGridPage> {
+  const supabase = getSsgSupabaseClient();
+  const page = Math.max(1, Math.floor(query.page ?? 1));
+  const limit = Math.min(Math.max(0, Math.floor(query.limit ?? 6)), PRODUCT_GRID_MAX_LIMIT);
+  const hasExclusions = Boolean(query.excludeProductId || query.excludeTranslationGroupId);
+
+  if (query.type === 'manual') {
+    const productIds = query.productIds ?? [];
+    if (productIds.length === 0) return { products: [], totalCount: 0 };
+
+    // The whole hand-picked list is at most PRODUCT_GRID_MAX_PRODUCTS rows, so
+    // it is cheaper to resolve it once and page in memory than to re-query.
+    const rows = applyExclusions(
+      await fetchHandPickedProducts(supabase, productIds, query.languageId),
+      query
+    );
+    const paged = limit > 0 ? rows.slice((page - 1) * limit, page * limit) : rows;
+    return { products: paged.map(mapProductRowToUiProduct), totalCount: rows.length };
+  }
+
+  // Over-fetch just enough to refill a page after the excluded product is dropped.
+  const overFetch = hasExclusions ? 2 : 0;
+  const { data, count } = await getProducts(supabase, {
+    languageId: query.languageId,
+    categoryIds: query.type === 'category' ? query.categoryIds : undefined,
+    offset: limit > 0 ? (page - 1) * limit : undefined,
+    limit: limit > 0 ? limit + overFetch : 0,
+  });
+
+  const rows = applyExclusions((data || []) as any[], query);
+  const visible = limit > 0 ? rows.slice(0, limit) : rows;
+
+  return {
+    products: visible.map(mapProductRowToUiProduct),
+    totalCount: count ?? rows.length,
+  };
+}

package/templates/nextblock-template/lib/cms/action-result.ts

@@ -0,0 +1,12 @@
+/**
+ * Standard result shape for CMS settings server actions.
+ *
+ * Next replaces the message of an uncaught Server Action error with a generic string in
+ * production builds, so anything the operator has to be able to read — a permission
+ * refusal, a relay's rejection, a validation complaint — must come back as data rather
+ * than as a throw. Actions that only ever fail in ways nobody needs to read (pure data
+ * readers rendered by a Server Component) can still throw and hit the error boundary.
+ */
+export type SettingsActionResult =
+  | { ok: true; message: string }
+  | { ok: false; error: string };