@usequeek/theme-kit 0.1.5 → 0.1.7

package/tests/storefront-client-scope.test.ts

@@ -0,0 +1,43 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { request } from '../sdk/client';
+
+/**
+ * The storefront must ONLY ever call the `/v1/client/*` backend scope. That scope's
+ * ResolveClientContext middleware resolves the vendor AND forces the platform
+ * (storefront/instore_qr) — so prices are always the storefront's, never the
+ * marketplace commission-inclusive price. Legacy v1 routes (/products, /vendors/*,
+ * /categories, ...) bypass that middleware → wrong platform → wrong price.
+ *
+ * This guard prevents that whole class of bug from ever returning.
+ */
+describe('storefront API scope guard', () => {
+  afterEach(() => vi.unstubAllGlobals());
+
+  it('refuses any backend route outside /v1/client', async () => {
+    for (const badPath of ['/products/abc', '/vendors/foo/products', '/categories', '/vendors/foo/collections/x/products']) {
+      await expect(request('http://api/api/v1', badPath)).rejects.toThrow(/only call \/v1\/client/);
+    }
+  });
+
+  it('allows /client/* routes through', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({ ok: true, json: async () => ({ data: [] }) });
+    vi.stubGlobal('fetch', fetchMock);
+
+    await expect(request('http://api/api/v1', '/client/store/products')).resolves.toEqual({ data: [] });
+    expect(fetchMock).toHaveBeenCalledOnce();
+  });
+
+  it('does not reintroduce a raw v1-route client (createServerClient)', () => {
+    const root = process.cwd();
+    const sdk = readFileSync(join(root, 'sdk/client.ts'), 'utf8');
+    expect(sdk).not.toContain('export function createServerClient');
+
+    const apiDir = join(root, 'api');
+    for (const file of readdirSync(apiDir).filter((name) => name.endsWith('.ts'))) {
+      const src = readFileSync(join(apiDir, file), 'utf8');
+      expect(src, `${file} must not use the removed createServerClient (v1 routes)`).not.toContain('createServerClient');
+    }
+  });
+});

package/types/block.ts

@@ -1,5 +1,5 @@
 import type { DesignTokens } from './vendor';
-import type { Product } from './product';
+import type { MetaobjectEntry, Product } from './product';
 
 export type BlockType =
   | 'content'
@@ -18,7 +18,8 @@ export type BlockType =
   | 'reviews'
   | 'faq'
   | 'product_qa'
-  | 'blog';
+  | 'blog'
+  | 'metaobjects';
 
 export interface ContentBlockData {
   markdown: string;
@@ -245,6 +246,25 @@ export interface BlogBlockData {
   limit?: number;
 }
 
+export interface MetaobjectsBlockData {
+  title?: string | null;
+  /** Metaobject definition handle (`designer`, `ingredient`, …). */
+  type: string;
+  limit?: number;
+  layout?: 'grid' | 'list';
+}
+
+/**
+ * Server-seeded resolution for a `metaobjects` block — the entries of
+ * `data.type` plus the definition meta needed to decide whether each card
+ * links out (`definition.has_pages`). Mirrors `MetaobjectsResolved` shape
+ * used by `hydrateProductBlocks` in the storefront.
+ */
+export interface MetaobjectsResolved {
+  entries: MetaobjectEntry[];
+  definition: { type: string; name: string; has_pages: boolean };
+}
+
 export type BlockDataMap = {
   content: ContentBlockData;
   image: ImageBlockData;
@@ -263,6 +283,7 @@ export type BlockDataMap = {
   faq: FaqBlockData;
   product_qa: ProductQaBlockData;
   blog: BlogBlockData;
+  metaobjects: MetaobjectsBlockData;
 };
 
 export type Block<T extends BlockType = BlockType> = {
@@ -289,4 +310,12 @@ export type Block<T extends BlockType = BlockType> = {
    * block type and for any route that hasn't been wired to hydrate.
    */
   productsPromise?: Promise<Product[]>;
+  /**
+   * Server-seeded entries + definition meta for `metaobjects` blocks — set
+   * by `hydrateProductBlocks` alongside `productsPromise`. Same contract:
+   * absent for every other block type and for any route that hasn't been
+   * wired to hydrate; the renderer falls back to rendering nothing (themes
+   * never fetch metaobjects client-side).
+   */
+  metaobjectsPromise?: Promise<MetaobjectsResolved>;
 };

package/types/product.ts

@@ -157,6 +157,32 @@ export interface ProductFlags {
   is_new: boolean;
 }
 
+/** A scalar metafield value (single_line_text, boolean, date, url, …). */
+export type MetafieldScalar = string | number | boolean;
+
+/**
+ * One metaobject entry linked through a `metaobject_reference` /
+ * `list.metaobject_reference` metafield. Presented by the backend
+ * (MetafieldPresenter) as the entry resource minus timestamps — a `draft`
+ * entry, or one whose definition is not storefront-visible, is already
+ * omitted on client surfaces, so the storefront renders whatever arrives.
+ */
+export interface MetaobjectEntry {
+  p_id: number;
+  type: string;
+  handle: string;
+  display_name: string;
+  /** Flat entry values (definitions never nest references). */
+  fields: Record<string, MetafieldScalar | MetafieldScalar[]>;
+}
+
+/** A presented product metafield value: scalar, scalar list, or linked entry/entries. */
+export type MetafieldValue =
+  | MetafieldScalar
+  | MetafieldScalar[]
+  | MetaobjectEntry
+  | MetaobjectEntry[];
+
 export interface Product {
   shop_id: string;
   id: string;
@@ -183,6 +209,9 @@ export interface Product {
   variants: ProductVariant[];
   addons: ProductAddon[];
   reviews: ProductReview[];
+  /** Presented product metafields keyed by definition key (incl. linked
+   *  metaobject entries). Absent when the backend sends none. */
+  metafields?: Record<string, MetafieldValue>;
   created_at: string | null;
   updated_at: string | null;
 }
@@ -271,6 +300,8 @@ export interface LegacyProductLike {
   >;
   addons?: ProductAddon[];
   reviews?: ProductReview[];
+  /** Raw presented metafields — passed through verbatim by the normalizer. */
+  metafields?: Record<string, unknown>;
   review_summary?: Partial<ProductReviewSummary>;
   created_at?: string | null;
   updated_at?: string | null;

package/types/theme.ts

@@ -4,7 +4,7 @@ import type { CartItem as CartLineItem } from './cart';
 import type { ImageVariants } from './media';
 import type { MenuItem } from './menu';
 import type { BlogCategory, Collection, Page, Pagination, Post } from './page';
-import type { Product } from './product';
+import type { MetaobjectEntry, Product } from './product';
 import type { DesignTokenAxisPath, DesignTokens, StorefrontConfig, VendorProfile } from './vendor';
 
 export interface HomePageProps {
@@ -39,6 +39,19 @@ export interface PoliciesPageProps {
   policies: Page[];
 }
 
+/** Field label/type metadata for a metaobject entry page — the same shape
+ *  `GET store/metaobject-definitions` sends, scoped to one definition. */
+export interface MetaobjectPageDefinition {
+  type: string;
+  name: string;
+  fields: Array<{ key: string; name: string; type: string }>;
+}
+
+export interface MetaobjectPageProps {
+  entry: MetaobjectEntry;
+  definition: MetaobjectPageDefinition;
+}
+
 export interface ShopCategory {
   id: string;
   slug: string;
@@ -63,6 +76,13 @@ export interface CollectionPageProps {
 
 export interface ProductPageProps {
   product: Product;
+  /**
+   * Product metafield definitions keyed by metafield key — the labels (and
+   * types) the core-owned `<ProductMetafields />` section renders values
+   * under. OPTIONAL so external themes that destructure `{ product }` keep
+   * compiling; unknown keys fall back to a humanised key label.
+   */
+  metafieldDefinitions?: Record<string, { name: string; type: string }>;
 }
 
 export interface GalleryPageProps {
@@ -336,7 +356,7 @@ export interface ThemeManifest {
  * Block types that are framework-owned (React logic ships in core, themes
  * only style via `.core-block-*` CSS). Themes do NOT implement these.
  */
-export type FrameworkBlockType = 'divider' | 'embed' | 'video' | 'table' | 'button' | 'image' | 'reviews' | 'faq' | 'callout' | 'quote' | 'product_qa';
+export type FrameworkBlockType = 'divider' | 'embed' | 'video' | 'table' | 'button' | 'image' | 'reviews' | 'faq' | 'callout' | 'quote' | 'product_qa' | 'metaobjects';
 
 /**
  * Block types the theme is responsible for implementing. Framework-owned
@@ -376,6 +396,11 @@ export interface ThemeModule {
     Collection: FC<CollectionPageProps>;
     Product: FC<ProductPageProps>;
     Gallery: FC<GalleryPageProps>;
+    /** Optional override for a metaobject entry's own page (`/{type}/{handle}`,
+     *  only routed when the definition has `has_pages`). When absent, core
+     *  renders `DefaultMetaobjectPage` (themeable via `.core-metaobject-page-*`
+     *  CSS), same fallback pattern as `Policies`. */
+    Metaobject?: FC<MetaobjectPageProps>;
   };
   shells?: {
     CartShell?: FC<CartShellProps>;

package/utils/product-normalizer.ts

@@ -1,5 +1,6 @@
 import type {
   LegacyProductLike,
+  MetafieldValue,
   Product,
   ProductCategory,
   ProductOption,
@@ -196,6 +197,18 @@ function normalizeCategories(raw: LegacyProductLike): ProductCategory[] {
   }, []);
 }
 
+function normalizeMetafields(raw: LegacyProductLike): Record<string, MetafieldValue> {
+  // Explicit whitelist like every other field above: without this the
+  // presented metafields (incl. linked metaobject entries) are dropped at
+  // runtime and <ProductMetafields /> renders nothing at every call site.
+  const source = raw.metafields;
+  if (!source || typeof source !== 'object' || Array.isArray(source)) {
+    return {};
+  }
+
+  return source as Record<string, MetafieldValue>;
+}
+
 export function normalizeProduct(raw: LegacyProductLike): Product {
   const shopId = String(raw.shop_id ?? raw.vendor_id ?? raw.shop?.id ?? raw.vendor?.id ?? '');
 
@@ -292,6 +305,7 @@ export function normalizeProduct(raw: LegacyProductLike): Product {
       : [],
     addons: raw.addons ?? [],
     reviews: raw.reviews ?? [],
+    metafields: normalizeMetafields(raw),
     created_at: raw.created_at ?? null,
     updated_at: raw.updated_at ?? null,
   };