@doswiftly/cli 0.1.18 → 0.1.20

package/templates/storefront-nextjs-shadcn/lib/graphql/query-keys.ts

@@ -0,0 +1,88 @@
+/**
+ * Centralized React Query key definitions.
+ *
+ * All query keys in one place ensures:
+ * - Consistent cache invalidation across hooks
+ * - No key collisions or typos
+ * - Easy discovery of all cached data
+ * - Currency-aware and language-aware keys for automatic refetch on change
+ *
+ * Convention:
+ * - `all()` — matches ALL queries in this domain (for broad invalidation)
+ * - `list(...)` — paginated/filtered lists
+ * - `detail(...)` — single entity by ID/handle
+ * - Currency and language are included as flat strings for stable reference
+ *
+ * @example
+ * ```typescript
+ * // In a hook:
+ * const currency = useCurrencyStore((s) => s.currency);
+ * const language = useLanguageStore((s) => s.language);
+ * useQuery({ queryKey: queryKeys.products.detail(slug, currency, language), ... });
+ *
+ * // Invalidation:
+ * queryClient.invalidateQueries({ queryKey: queryKeys.cart.all() });
+ * ```
+ */
+/** Currency/Language type — can be null before initialization */
+type Currency = string | null;
+type Language = string | null;
+
+export const queryKeys = {
+  products: {
+    all: () => ['Product'] as const,
+    list: (vars?: Record<string, unknown>, currency?: Currency, language?: Language) =>
+      ['Products', vars, currency, language] as const,
+    detail: (handleOrId: string, currency: Currency, language?: Language) =>
+      ['Product', handleOrId, currency, language] as const,
+    search: (query: string, currency: Currency, language?: Language) =>
+      ['ProductSearch', query, currency, language] as const,
+  },
+
+  collections: {
+    all: () => ['Collection'] as const,
+    list: (vars?: Record<string, unknown>, currency?: Currency, language?: Language) =>
+      ['Collections', vars, currency, language] as const,
+    detail: (handleOrId: string, currency: Currency, language?: Language) =>
+      ['Collection', handleOrId, currency, language] as const,
+  },
+
+  categories: {
+    all: () => ['Category'] as const,
+    list: (currency: Currency, language?: Language) => ['Categories', currency, language] as const,
+    detail: (slugOrId: string, language?: Language) => ['Category', slugOrId, language] as const,
+  },
+
+  filters: {
+    all: () => ['AvailableFilters'] as const,
+    forContext: (input?: Record<string, unknown> | null, currency?: Currency, language?: Language) =>
+      ['AvailableFilters', input, currency, language] as const,
+  },
+
+  cart: {
+    all: () => ['Cart'] as const,
+    detail: (cartId: string | null, currency: Currency) =>
+      ['Cart', cartId, currency] as const,
+  },
+
+  checkout: {
+    all: () => ['Checkout'] as const,
+    detail: (checkoutId: string | null, currency: Currency) =>
+      ['Checkout', checkoutId, currency] as const,
+  },
+
+  customer: {
+    all: () => ['Customer'] as const,
+    detail: (token: string) => ['Customer', token] as const,
+    order: (orderId: string, currency: Currency) => ['CustomerOrder', orderId, currency] as const,
+  },
+
+  loyalty: {
+    member: (currency: Currency) => ['LoyaltyMember', currency] as const,
+    rewards: (currency: Currency) => ['LoyaltyRewards', currency] as const,
+    transactions: (vars?: Record<string, unknown>, currency?: Currency) =>
+      ['LoyaltyTransactions', vars, currency] as const,
+    settings: () => ['LoyaltySettings'] as const,
+    referralStats: () => ['ReferralStats'] as const,
+  },
+} as const;

package/templates/storefront-nextjs-shadcn/lib/graphql/server.ts

@@ -1,67 +1,83 @@
 import { cache } from 'react';
-import { GraphQLClient } from 'graphql-request';
-import type { TypedDocumentNode } from '@graphql-typed-document-node/core';
-import { getCurrencyFromCookieAsync } from '@/lib/currency/';
+import { getStorefrontClient } from '@doswiftly/storefront-sdk/react/server';
+import { getCurrencyFromCookieAsync } from '@doswiftly/storefront-sdk/react';
+import { CURRENCY_HEADER_NAME } from '@doswiftly/storefront-sdk';
+import type { NormalizedProductsResult, NormalizedCollectionsResult } from './types';
+import type { TypedDocumentString } from '@/generated/graphql';
+import { graphqlConfig } from './config';
 
-// Import config - will be injected by CLI during template generation
-let config: {
-  shop: { slug: string };
-  api: { url: string };
-} | null = null;
+// Static imports — Documents
+import {
+  ShopDocument,
+  ProductDocument,
+  ProductsDocument,
+  CollectionsDocument,
+  CollectionDocument,
+  CategoriesDocument,
+  CategoryDocument,
+  AvailableFiltersDocument,
+  CustomerDocument,
+} from '@/generated/graphql';
 
-try {
-  // Dynamic import to handle cases where config doesn't exist yet
-  const configModule = require('@/doswiftly.config');
-  config = configModule.default || configModule;
-} catch (error) {
-  // Fallback to environment variables if config file doesn't exist
-  config = {
-    shop: {
-      slug: process.env.NEXT_PUBLIC_SHOP_SLUG || 'demo-shop',
-    },
-    api: {
-      url: process.env.NEXT_PUBLIC_API_URL || 'http://localhost:8000',
-    },
-  };
-}
+// Static imports — Types
+import type {
+  ShopQuery,
+  ProductQuery,
+  ProductQueryVariables,
+  ProductsQuery,
+  ProductsQueryVariables,
+  ProductSortKeys,
+  CollectionsQuery,
+  CollectionsQueryVariables,
+  CollectionSortKeys,
+  CollectionQuery,
+  CollectionQueryVariables,
+  CategoriesQuery,
+  CategoryQuery,
+  CategoryQueryVariables,
+  AvailableFiltersQuery,
+  AvailableFiltersQueryVariables,
+  AvailableFiltersInput,
+  CustomerQuery,
+  CustomerQueryVariables,
+} from '@/generated/graphql';
 
-/**
- * Cached GraphQL client factory for Server Components
- * 
- * Uses React cache() to deduplicate requests within a single render pass.
- * Server-side requests now include X-Preferred-Currency header from cookie
- * for SSR currency consistency.
- * 
- * Note: This is an async function in Next.js 15+ because cookies() is async.
- * 
- * @returns GraphQL client configured for server-side usage with currency support
- */
-export const getClient = cache(async () => {
-  // Read currency from cookie (SSR-safe, async in Next.js 15+)
-  const currency = await getCurrencyFromCookieAsync();
-  
-  return new GraphQLClient(`${config!.api.url}/storefront/graphql`, {
-    headers: {
-      'X-Shop-Slug': config!.shop.slug,
-      // Include X-Preferred-Currency from cookie for SSR consistency
-      ...(currency && { 'X-Preferred-Currency': currency }),
-    },
-  });
-});
+// ---------------------------------------------------------------------------
+// Generic request helper with React cache
+// ---------------------------------------------------------------------------
 
 /**
- * Generic request helper with React cache
- * 
- * @param document - TypedDocumentNode from codegen
- * @param variables - Query variables
- * @returns Query result
+ * Generic request helper with React cache.
+ *
+ * Uses React cache() to deduplicate requests within a single render pass.
+ * Server-side requests include X-Preferred-Currency header from cookie.
  */
 export const request = cache(async <TResult, TVariables>(
-  document: TypedDocumentNode<TResult, TVariables>,
-  variables?: TVariables
+  document: TypedDocumentString<TResult, TVariables>,
+  variables?: TVariables,
+  extraHeaders?: Record<string, string>,
 ): Promise<TResult> => {
-  const client = await getClient();
-  return client.request(document, variables as any);
+  // Get currency from cookie for server-side requests
+  let currency: string | null = null;
+  try {
+    currency = await getCurrencyFromCookieAsync();
+  } catch {
+    // cookies() unavailable outside request scope (generateStaticParams, build time)
+  }
+
+  const headers: Record<string, string> = {
+    ...(currency && { [CURRENCY_HEADER_NAME]: currency }),
+    ...extraHeaders,
+  };
+
+  // Use a fresh client with currency header for this request
+  const requestClient = getStorefrontClient({
+    apiUrl: graphqlConfig.apiUrl,
+    shopSlug: graphqlConfig.shopSlug,
+    defaultHeaders: headers,
+  });
+
+  return requestClient.query<TResult>(document.toString(), variables as Record<string, unknown>);
 });
 
 // ============================================================================
@@ -70,104 +86,49 @@ export const request = cache(async <TResult, TVariables>(
 
 /**
  * Fetch shop data with currency configuration
- * 
- * Used in root layout to initialize currency store.
- * Cached per render to avoid duplicate requests.
- * 
- * @returns Shop query result
- * 
- * @example
- * ```typescript
- * // app/layout.tsx
- * import { fetchShop } from '@/lib/graphql/server';
- * 
- * export default async function RootLayout() {
- *   const data = await fetchShop();
- *   return <CurrencyProvider shopData={data.shop}>...</CurrencyProvider>;
- * }
- * ```
  */
-export const fetchShop = cache(async () => {
-  // Import generated types dynamically to avoid circular dependencies
-  const { ShopDocument } = await import('@/generated/graphql');
-  return request(ShopDocument, {});
+export const fetchShop = cache(async (): Promise<ShopQuery> => {
+  return request(ShopDocument);
 });
 
 /**
  * Fetch single product by handle or ID
- * 
- * Returns product in base currency for SSG compatibility.
- * Client components should refetch with preferred currency if needed.
- * 
- * @param handleOrId - Product handle (string) or ID
- * @returns Product query result
- * 
- * @example
- * ```typescript
- * // app/products/[handle]/page.tsx
- * import { fetchProduct } from '@/lib/graphql/server';
- * 
- * export default async function ProductPage({ params }) {
- *   const data = await fetchProduct(params.handle);
- *   return <ProductClient initialProduct={data.product} />;
- * }
- * ```
  */
-export const fetchProduct = cache(async (handleOrId: string) => {
+export const fetchProduct = cache(async (handleOrId: string): Promise<ProductQuery> => {
   if (!handleOrId) {
     throw new Error('Product handle or ID is required');
   }
-  
-  const { ProductDocument } = await import('@/generated/graphql');
-  
-  // Determine if it's an ID or handle
+
   const isId = handleOrId.startsWith('gid://');
-  
-  return request(ProductDocument, {
-    ...(isId ? { id: handleOrId } : { handle: handleOrId }),
-  });
+  const variables: ProductQueryVariables = isId
+    ? { id: handleOrId }
+    : { handle: handleOrId };
+
+  return request(ProductDocument, variables);
 });
 
 /**
  * Fetch products with pagination and normalization
- * 
- * Automatically normalizes GraphQL edges/nodes structure to flat arrays
- * for easier consumption in components.
- * 
- * @param variables - Query variables (first, after, query, sortKey, reverse)
- * @returns Normalized products response
- * 
- * @example
- * ```typescript
- * // app/products/page.tsx
- * import { fetchProducts } from '@/lib/graphql/server';
- * 
- * export default async function ProductsPage() {
- *   const { products, pageInfo } = await fetchProducts({ first: 20 });
- *   return products.map(product => <ProductCard key={product.id} product={product} />);
- * }
- * ```
  */
 export const fetchProducts = cache(async (variables?: {
   first?: number;
   after?: string;
   query?: string;
-  sortKey?: string;
+  sortKey?: ProductSortKeys;
   reverse?: boolean;
-}) => {
-  const { ProductsDocument } = await import('@/generated/graphql');
-  
-  const data = await request(ProductsDocument, {
+}): Promise<NormalizedProductsResult> => {
+  const graphqlVariables: ProductsQueryVariables = {
     first: variables?.first ?? 20,
     after: variables?.after,
     query: variables?.query,
-    sortKey: variables?.sortKey as any,
+    sortKey: variables?.sortKey,
     reverse: variables?.reverse,
-  });
-  
-  // Normalize: edges/nodes → flat array
+  };
+
+  const data = await request(ProductsDocument, graphqlVariables);
+
   return {
-    products: data.products.edges.map((edge: any) => edge.node),
+    products: data.products.edges.map((edge) => edge.node),
     pageInfo: data.products.pageInfo,
     totalCount: data.products.totalCount,
   };
@@ -175,37 +136,26 @@ export const fetchProducts = cache(async (variables?: {
 
 /**
  * Fetch collections with pagination and normalization
- * 
- * @param variables - Query variables
- * @returns Normalized collections response
- * 
- * @example
- * ```typescript
- * import { fetchCollections } from '@/lib/graphql/server';
- * 
- * const { collections } = await fetchCollections({ first: 10 });
- * ```
  */
 export const fetchCollections = cache(async (variables?: {
   first?: number;
   after?: string;
   query?: string;
-  sortKey?: string;
+  sortKey?: CollectionSortKeys;
   reverse?: boolean;
-}) => {
-  const { CollectionsDocument } = await import('@/generated/graphql');
-  
-  const data = await request(CollectionsDocument, {
+}): Promise<NormalizedCollectionsResult> => {
+  const graphqlVariables: CollectionsQueryVariables = {
     first: variables?.first ?? 20,
     after: variables?.after,
     query: variables?.query,
-    sortKey: variables?.sortKey as any,
+    sortKey: variables?.sortKey,
     reverse: variables?.reverse,
-  });
-  
-  // Normalize: edges/nodes → flat array
+  };
+
+  const data = await request(CollectionsDocument, graphqlVariables);
+
   return {
-    collections: data.collections.edges.map((edge: any) => edge.node),
+    collections: data.collections.edges.map((edge) => edge.node),
     pageInfo: data.collections.pageInfo,
     totalCount: data.collections.totalCount,
   };
@@ -213,55 +163,55 @@ export const fetchCollections = cache(async (variables?: {
 
 /**
  * Fetch single collection by handle or ID
- * 
- * @param handleOrId - Collection handle or ID
- * @returns Collection query result
- * 
- * @example
- * ```typescript
- * import { fetchCollection } from '@/lib/graphql/server';
- * 
- * const data = await fetchCollection('featured-products');
- * ```
  */
-export const fetchCollection = cache(async (handleOrId: string) => {
-  const { CollectionDocument } = await import('@/generated/graphql');
-  
+export const fetchCollection = cache(async (handleOrId: string): Promise<CollectionQuery> => {
   const isId = handleOrId.startsWith('gid://');
-  
-  return request(CollectionDocument, {
-    ...(isId ? { id: handleOrId } : { handle: handleOrId }),
-  });
+  const variables: CollectionQueryVariables = isId
+    ? { id: handleOrId }
+    : { handle: handleOrId };
+
+  return request(CollectionDocument, variables);
 });
 
 /**
  * Fetch categories from GraphQL API
- * 
- * @returns Categories query result with tree structure
  */
-export const fetchCategories = cache(async () => {
-  const { CategoriesDocument } = await import('@/generated/graphql');
-  return request(CategoriesDocument, {});
+export const fetchCategories = cache(async (): Promise<CategoriesQuery> => {
+  return request(CategoriesDocument);
+});
+
+/**
+ * Fetch single category by slug or ID
+ */
+export const fetchCategory = cache(async (slugOrId: string): Promise<CategoryQuery> => {
+  const isId = slugOrId.startsWith('gid://');
+  const variables: CategoryQueryVariables = isId
+    ? { id: slugOrId }
+    : { slug: slugOrId };
+
+  return request(CategoryDocument, variables);
+});
+
+/**
+ * Fetch available filters for product listing (SSR)
+ */
+export const fetchAvailableFilters = cache(async (
+  input?: AvailableFiltersInput,
+): Promise<AvailableFiltersQuery> => {
+  const variables: AvailableFiltersQueryVariables = { input: input || null };
+  return request(AvailableFiltersDocument, variables);
 });
 
 /**
  * Fetch customer data (requires access token)
- * 
- * @param accessToken - Customer access token
- * @returns Customer query result with addresses and orders
  */
-export const fetchCustomer = cache(async (accessToken: string) => {
-  const { CustomerDocument } = await import('@/generated/graphql');
-  return request(CustomerDocument, { customerAccessToken: accessToken });
+export const fetchCustomer = cache(async (accessToken: string): Promise<CustomerQuery> => {
+  const variables: CustomerQueryVariables = { customerAccessToken: accessToken };
+  return request(CustomerDocument, variables);
 });
 
 // ============================================================================
 // TYPE EXPORTS
 // ============================================================================
 
-/**
- * Normalized response types for helper functions
- * These types will be inferred from generated GraphQL types
- */
-export type NormalizedProductsResponse = Awaited<ReturnType<typeof fetchProducts>>;
-export type NormalizedCollectionsResponse = Awaited<ReturnType<typeof fetchCollections>>;
+export type { NormalizedProductsResult, NormalizedCollectionsResult } from './types';

package/templates/storefront-nextjs-shadcn/lib/graphql/types.ts

@@ -0,0 +1,62 @@
+/**
+ * Shared domain types derived from GraphQL codegen.
+ *
+ * Two categories of types:
+ *
+ * 1. **Query-derived types** — extracted from query response shapes.
+ *    Use when you need the EXACT shape returned by a specific query.
+ *
+ * 2. **Fragment-derived types** — from template-local fragments.
+ *    Use for component props to enforce fragment-first architecture.
+ *    Fragment = Component data contract.
+ *
+ * @example
+ * ```typescript
+ * // For a product card component (fragment-first):
+ * import type { ProductCardFields } from '@/lib/graphql/types';
+ * interface Props { product: ProductCardFields }
+ *
+ * // For a server helper return type (query-derived):
+ * import type { NormalizedProductsResult } from '@/lib/graphql/types';
+ * ```
+ */
+import type {
+  ProductsQuery,
+  CollectionsQuery,
+  CategoriesQuery,
+  Category,
+} from '@/generated/graphql';
+
+// Fragment types → see lib/graphql/fragments.ts
+
+// ============================================================================
+// QUERY-DERIVED TYPES (from storefront-operations queries)
+// ============================================================================
+
+/** Single product node from Products list query */
+export type ProductNode = ProductsQuery['products']['edges'][number]['node'];
+
+/** Single collection node from Collections list query */
+export type CollectionNode = CollectionsQuery['collections']['edges'][number]['node'];
+
+// ============================================================================
+// NORMALIZED RESULT TYPES (for server.ts and hooks.ts)
+// ============================================================================
+
+export interface NormalizedProductsResult {
+  products: ProductNode[];
+  pageInfo: ProductsQuery['products']['pageInfo'];
+  totalCount: number;
+}
+
+export interface NormalizedCollectionsResult {
+  collections: CollectionNode[];
+  pageInfo: CollectionsQuery['collections']['pageInfo'];
+  totalCount: number;
+}
+
+export interface NormalizedCategoriesResult {
+  categories: Category[];
+  roots: CategoriesQuery['categories']['roots'];
+  totalCount: number;
+}

package/templates/storefront-nextjs-shadcn/lib/theme/theme-config.ts

@@ -70,20 +70,3 @@ export const themeConfig = {
 } as const;
 
 export type Theme = (typeof themeConfig.themes)[number];
-
-/**
- * Get theme colors for a specific theme
- */
-export function getThemeColors(theme: "light" | "dark") {
-  return themeConfig.colors[theme];
-}
-
-/**
- * Generate CSS variables for theme
- */
-export function generateThemeVariables(theme: "light" | "dark") {
-  const colors = getThemeColors(theme);
-  return Object.entries(colors)
-    .map(([key, value]) => `--${key}: ${value};`)
-    .join("\n  ");
-}