@decocms/start 0.19.0

package/.cursor/skills/deco-apps-vtex-porting/adaptation-patterns.md

@@ -0,0 +1,335 @@
+# Adaptation Patterns: deco-cx/apps → apps-start
+
+How to convert each Deno/Fresh/Deco pattern to TanStack/Node equivalents.
+
+## 1. App Factory → configureVtex()
+
+### Original (apps/vtex/mod.ts)
+```typescript
+import { createHttpClient } from "../utils/http.ts";
+import { createGraphqlClient } from "../utils/graphql.ts";
+
+export default function VTEX({ account, publicUrl, salesChannel, appKey, appToken }: Props) {
+  const vcsDeprecated = createHttpClient<VTEXCommerceStable>({
+    base: publicUrl,
+    processHeaders: removeDirtyCookies,
+    fetcher: fetchSafe,
+  });
+  const io = createGraphqlClient({
+    endpoint: `${publicUrl}/api/io/_v/private/graphql/v1`,
+  });
+  const state = { account, publicUrl, salesChannel, vcsDeprecated, io, /* 5 more clients */ };
+  return { state, manifest, middleware };
+}
+```
+
+### Port (apps-start/vtex/client.ts)
+```typescript
+let vtexConfig: VtexConfig;
+
+export function configureVtex(config: VtexConfig) {
+  vtexConfig = config;
+}
+
+export function getVtexConfig(): VtexConfig {
+  return vtexConfig;
+}
+
+export async function vtexFetch<T>(path: string, init?: RequestInit): Promise<T> {
+  const { account, publicUrl } = getVtexConfig();
+  const baseUrl = publicUrl || `https://${account}.vtexcommercestable.com.br`;
+  const res = await fetch(`${baseUrl}${path}`, init);
+  return res.json();
+}
+```
+
+**Key difference**: No typed Proxy, no processHeaders, no fetchSafe retry. Consider adding:
+- URL sanitization from `fetchVTEX.ts`
+- Retry on connection closed
+- removeDirtyCookies for cookie headers
+
+## 2. Loader Signature
+
+### Original
+```typescript
+// loaders/intelligentSearch/productDetailsPage.ts
+import { AppContext } from "../../mod.ts";
+import type { ProductDetailsPage } from "../../../commerce/types.ts";
+
+export interface Props { slug: string; }
+
+const loader = async (props: Props, req: Request, ctx: AppContext): Promise<ProductDetailsPage | null> => {
+  const { vcsDeprecated, salesChannel } = ctx;
+  const segment = getSegmentFromBag(ctx);
+  // Use typed client: ctx.vcsDeprecated["GET /api/..."]({...})
+};
+export default loader;
+```
+
+### Port
+```typescript
+// inline-loaders/productDetailsPage.ts
+import { vtexFetch, getVtexConfig } from "../client";
+import type { ProductDetailsPage } from "../../commerce/types/commerce";
+
+interface Props { slug?: string; }
+
+export default async function vtexProductDetailsPage(props: Props): Promise<ProductDetailsPage | null> {
+  const config = getVtexConfig();
+  // Use vtexFetch: await vtexFetch<T>("/api/...");
+}
+```
+
+**Key differences**:
+- No `req`, no `ctx` params
+- Named export function instead of anonymous `const loader = ...`
+- Config from `getVtexConfig()` instead of `ctx`
+- No segment from bag — must pass explicitly or read from cookies
+
+## 3. Action Signature
+
+### Original
+```typescript
+// actions/cart/addItems.ts
+export interface Props {
+  orderItems: Array<{ id: string; quantity: number; seller: string }>;
+}
+const action = async (props: Props, req: Request, ctx: AppContext): Promise<OrderForm> => {
+  const { orderFormId, cookie } = parseCookie(req.headers);
+  const segment = getSegmentFromBag(ctx);
+  const response = await ctx.vcsDeprecated["POST /api/checkout/pub/orderForm/:orderFormId/items"](
+    { orderFormId, sc: segment?.payload?.channel, allowedOutdatedData: ["paymentData"] },
+    { body: { orderItems: props.orderItems }, headers: { cookie } },
+  );
+  proxySetCookie(response.headers, ctx.response.headers, req.url);
+  return response.json();
+};
+export default action;
+```
+
+### Port
+```typescript
+// actions/checkout.ts
+export async function addItems(
+  orderFormId: string, cookie: string, orderItems: OrderItem[], sc?: string,
+): Promise<VtexFetchResult<OrderForm>> {
+  const params = new URLSearchParams();
+  if (sc) params.set("sc", sc);
+  params.set("allowedOutdatedData", "paymentData");
+  return vtexFetchWithCookies<OrderForm>(
+    `/api/checkout/pub/orderForm/${orderFormId}/items?${params}`,
+    {
+      method: "POST",
+      headers: { cookie, "Content-Type": "application/json" },
+      body: JSON.stringify({ orderItems, expectedOrderFormSections: DEFAULT_EXPECTED_SECTIONS }),
+    },
+  );
+}
+```
+
+**Key differences**:
+- Returns `VtexFetchResult<T>` with `{ data, setCookies }` (caller handles cookie propagation)
+- No `proxySetCookie` — the storefront layer decides how to set cookies
+- Parameters are explicit (no `req.headers` parsing inside — caller provides them)
+
+## 4. Middleware (ctx.bag → Function Params)
+
+### Original
+```typescript
+// middleware.ts — sets per-request state in ctx.bag
+export const middleware = (_props: unknown, req: Request, ctx: AppMiddlewareContext) => {
+  const cookies = getCookies(req.headers);
+  setSegmentBag(cookies, req, ctx);        // ctx.bag.set(SEGMENT, wrappedSegment)
+  setISCookiesBag(cookies, ctx);           // ctx.bag.set(IS_COOKIES, { session, anonymous })
+  return ctx.next!();
+};
+
+// Then in loaders:
+const segment = getSegmentFromBag(ctx);    // ctx.bag.get(SEGMENT)
+```
+
+### Port
+```typescript
+// middleware.ts — extracts context for downstream use
+export function extractVtexContext(cookieHeader: string) {
+  const config = getVtexConfig();
+  const cookies = parseCookieString(cookieHeader);
+  const segment = buildSegmentFromCookies(cookies);
+  const isSession = cookies.get("vtex_is_session") ?? crypto.randomUUID();
+  const isAnonymous = cookies.get("vtex_is_anonymous") ?? crypto.randomUUID();
+  return { ...config, segment, isSession, isAnonymous };
+}
+
+// In loaders — pass context explicitly:
+export default async function productList(props: Props) {
+  const config = getVtexConfig();
+  const data = await intelligentSearch<T>(path, params, {
+    cookieHeader: `vtex_is_session=${session}`,
+  });
+}
+```
+
+**Key difference**: No global per-request storage. Context is either:
+1. Passed explicitly through function params
+2. Read from singleton config (for static values like `account`, `salesChannel`)
+
+## 5. Hooks (Signals → React Query)
+
+### Original (Preact Signals + Serial Queue)
+```typescript
+// hooks/context.ts
+import { signal } from "@preact/signals";
+const cart = signal<OrderForm | null>(null);
+const loading = signal(true);
+
+const enqueue = (cb) => {
+  abort();
+  loading.value = true;
+  queue = queue.then(async () => {
+    const result = await cb(controller.signal);
+    cart.value = result.cart || cart.value;
+    loading.value = false;
+  });
+};
+
+// hooks/useCart.ts
+const addItems = enqueue("vtex/actions/cart/addItems.ts");
+export const useCart = () => ({ cart, loading, addItems });
+```
+
+### Port (React Query)
+```typescript
+// hooks/useCart.ts
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+
+export function useCart() {
+  const queryClient = useQueryClient();
+
+  const { data: cart, isLoading } = useQuery({
+    queryKey: ["vtex-cart"],
+    queryFn: fetchCart,
+    staleTime: 0,
+  });
+
+  const addItems = useMutation({
+    mutationFn: addItemsToCart,
+    onSuccess: (newCart) => {
+      queryClient.setQueryData(["vtex-cart"], newCart);
+    },
+  });
+
+  return { cart, loading: isLoading, addItems };
+}
+```
+
+**Key advantages of React Query version**:
+- Built-in loading/error/success states
+- Automatic refetching on mount/focus
+- Optimistic updates via `setQueryData`
+- No manual abort controller management
+- Devtools integration
+
+## 6. Typed HTTP Client → vtexFetch
+
+### Original
+```typescript
+// Uses Proxy-based typed client
+const response = await ctx.vcsDeprecated
+  ["POST /api/checkout/pub/orderForm/:orderFormId/coupons"](
+    { orderFormId: cart.orderFormId, sc: channel },
+    { body: { text: couponCode } },
+  );
+```
+
+### Port
+```typescript
+// Direct fetch with string URL
+const orderForm = await vtexFetch<OrderForm>(
+  `/api/checkout/pub/orderForm/${orderFormId}/coupons?sc=${sc}`,
+  {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ text: couponCode }),
+  },
+);
+```
+
+**Lost**: Type safety on URL params, response type, and body type. Mitigate by keeping the same function structure as the original.
+
+## 7. GraphQL Client
+
+### Original
+```typescript
+const { io } = ctx;
+const data = await io.query<WishlistResponse, Variables>({
+  query: MY_QUERY,
+  variables: { id },
+}, { headers: { cookie } });
+```
+
+### Port
+```typescript
+import { vtexIOGraphQL } from "../client";
+const data = await vtexIOGraphQL<WishlistResponse>(
+  { query: MY_QUERY, variables: { id } },
+  { cookie: buildAuthCookieHeader(authCookie, account) },
+);
+```
+
+## 8. Cookie Propagation
+
+### Original
+```typescript
+import { proxySetCookie } from "../utils/cookies.ts";
+const response = await ctx.vcsDeprecated["POST /api/..."](params, opts);
+proxySetCookie(response.headers, ctx.response.headers, req.url);
+return response.json();
+```
+
+### Port
+```typescript
+import { vtexFetchWithCookies } from "../client";
+const result = await vtexFetchWithCookies<OrderForm>(url, opts);
+// result.data = the JSON response
+// result.setCookies = string[] of Set-Cookie headers
+// Caller (storefront) is responsible for setting these cookies on the response
+return result;
+```
+
+## 9. Deno Standard Library
+
+| Original (Deno std) | Port (Node/Browser) |
+|---------------------|---------------------|
+| `getCookies(headers)` from `std/http/cookie.ts` | Manual parsing or `cookie` npm package |
+| `setCookie(headers, cookie)` from `std/http/cookie.ts` | `res.headers.append("Set-Cookie", ...)` |
+| `getSetCookies(headers)` from `std/http/cookie.ts` | `response.headers.getSetCookie()` |
+| `btoa(str)` / `atob(str)` | Same (global in Node 16+) |
+| `crypto.randomUUID()` | Same (global in Node 19+) |
+| `Deno.env.get("VAR")` | `process.env.VAR` |
+
+## 10. Import Specifiers
+
+| Original | Port |
+|----------|------|
+| `from "./mod.ts"` | `from "./mod"` (no .ts extension) |
+| `from "../../commerce/types.ts"` | `from "../../commerce/types/commerce"` |
+| `from "std/http/mod.ts"` | Remove, use built-in or npm |
+| `from "@deco/deco"` | Remove — no framework |
+| `from "$fresh/runtime.ts"` | Remove — `typeof document !== "undefined"` |
+
+## Summary: Porting Checklist Per File
+
+When porting any file from `deco-cx/apps/vtex/` to `apps-start/vtex/`:
+
+1. [ ] Copy the business logic (API calls, data transformations)
+2. [ ] Replace `ctx.*` with `getVtexConfig().*` or explicit params
+3. [ ] Replace typed client calls with `vtexFetch`/`vtexFetchWithCookies`
+4. [ ] Replace `io.query` with `vtexIOGraphQL`
+5. [ ] Replace `proxySetCookie` with returning `{ data, setCookies }`
+6. [ ] Replace Deno std cookie functions with manual parsing
+7. [ ] Remove `.ts` from import paths
+8. [ ] Remove `@deco/deco` and `$fresh` imports
+9. [ ] Keep the same VTEX API URLs and parameters
+10. [ ] Keep the same schema.org transform.ts usage
+11. [ ] Add `salesChannel` where original has it
+12. [ ] Add `expectedOrderFormSections` where original has it

package/.cursor/skills/deco-apps-vtex-porting/commerce-porting.md

@@ -0,0 +1,155 @@
+# Commerce Module Porting
+
+How the shared `commerce/` module from `deco-cx/apps` maps to `apps-start/commerce/`.
+
+## Structure Comparison
+
+```
+Original (apps/commerce/)           apps-start (commerce/)
+═══════════════════════            ════════════════════════
+types.ts (786 lines)          →    types/commerce.ts (same types)
+mod.ts (app factory)          →    Not needed
+manifest.gen.ts               →    Not needed
+
+utils/canonical.ts            →    utils/canonical.ts ✅
+utils/constants.ts            →    utils/constants.ts ✅
+utils/filters.ts              →    utils/filters.ts ✅
+utils/productToAnalyticsItem  →    utils/productToAnalyticsItem.ts ✅
+utils/stateByZip.ts           →    utils/stateByZip.ts ✅
+
+loaders/navbar.ts             →    Part of vtex/loaders/navbar.ts (platform-specific)
+loaders/extensions/*          →    Not needed (Deco block system)
+loaders/product/*             →    Not needed (Deco block system)
+
+sections/Seo/*                →    Storefront handles SEO locally
+
+N/A (was in site sdk/)        →    sdk/useOffer.ts ✅ (NEW)
+N/A                           →    sdk/useVariantPossibilities.ts ✅ (NEW)
+N/A                           →    sdk/formatPrice.ts ✅ (NEW)
+N/A                           →    sdk/url.ts ✅ (NEW)
+N/A                           →    sdk/analytics.ts ✅ (NEW)
+N/A                           →    components/Image.tsx ✅ (NEW)
+N/A                           →    components/JsonLd.tsx ✅ (NEW)
+```
+
+## Key Improvement: SDK in Library
+
+In the original architecture, utilities like `useOffer`, `formatPrice`, `useVariantPossibilities` lived in each site's `sdk/` folder. This meant every store had its own copy that could drift.
+
+In apps-start, these are centralized in `commerce/sdk/` and imported as:
+
+```typescript
+import { useOffer } from "@decocms/apps/commerce/sdk/useOffer";
+import { formatPrice } from "@decocms/apps/commerce/sdk/formatPrice";
+import { useVariantPossibilities } from "@decocms/apps/commerce/sdk/useVariantPossibilities";
+import { relative } from "@decocms/apps/commerce/sdk/url";
+import { sendEvent } from "@decocms/apps/commerce/sdk/analytics";
+```
+
+## Types Mapping
+
+The `commerce/types/commerce.ts` in apps-start should be a direct port of `commerce/types.ts` from the original. All schema.org types must match exactly.
+
+### Verification
+
+```bash
+# Compare type names between original and port
+rg "export (interface|type|enum)" apps/commerce/types.ts | sort
+rg "export (interface|type|enum)" apps-start/commerce/types/commerce.ts | sort
+```
+
+## Utils Porting
+
+### canonical.ts — Direct Copy
+```typescript
+export const canonicalFromBreadcrumblist = (b?: BreadcrumbList) => {
+  const items = b?.itemListElement ?? [];
+  if (!Array.isArray(items) || items.length === 0) return undefined;
+  return items.reduce((acc, curr) => acc.position < curr.position ? curr : acc).item;
+};
+```
+
+### constants.ts — Direct Copy
+```typescript
+export const DEFAULT_IMAGE: ImageObject = {
+  "@type": "ImageObject",
+  encodingFormat: "image",
+  alternateName: "Default Image Placeholder",
+  url: "https://ozksgdmyrqcxcwhnbepg.supabase.co/storage/v1/object/public/assets/1818/ff6bb37e-...",
+};
+```
+
+### filters.ts — Direct Copy
+```typescript
+export const parseRange = (price: string) => { /* ... */ };
+export const formatRange = (from: number, to: number) => `${from}:${to}`;
+```
+
+### productToAnalyticsItem.ts — Adapt Imports Only
+Change `from "../types.ts"` to `from "../types/commerce"`.
+
+### stateByZip.ts — Direct Copy
+No dependencies.
+
+## SDK Utilities
+
+These are new to apps-start — they came from individual site repos:
+
+### useOffer.ts
+Extracts price/installment/seller from AggregateOffer:
+```typescript
+export function useOffer(aggregateOffer?: AggregateOffer) {
+  const offer = aggregateOffer?.offers?.[0]; // Best offer
+  return {
+    price: offer?.price,
+    listPrice: /* ... */,
+    seller: offer?.seller,  // MUST be sellerId
+    installment: /* find best installment */,
+    availability: offer?.availability,
+  };
+}
+```
+
+### useVariantPossibilities.ts
+Groups product variants by property name:
+```typescript
+export function useVariantPossibilities(product: ProductGroup) {
+  // Returns Map<propertyName, Map<propertyValue, ProductLeaf>>
+}
+```
+
+### formatPrice.ts
+Formats currency values:
+```typescript
+export function formatPrice(price?: number, currency = "BRL", locale = "pt-BR") {
+  return price?.toLocaleString(locale, { style: "currency", currency });
+}
+```
+
+## Components
+
+### Image.tsx
+Thin wrapper around `<img>` with optimization hints:
+```typescript
+export function Image(props: ImageProps) {
+  // Handles: width/height, loading="lazy", fetchPriority, src transformation
+  return <img {...adaptedProps} />;
+}
+```
+
+### JsonLd.tsx
+Structured data renderer:
+```typescript
+export function JsonLd<T>(props: { data: T }) {
+  return <script type="application/ld+json" dangerouslySetInnerHTML={{ __html: JSON.stringify(props.data) }} />;
+}
+```
+
+## What the Storefront Provides Locally
+
+These are NOT in apps-start — each site creates its own:
+
+- `components/Picture.tsx` — `<picture>` with `<source>` for responsive images
+- `components/Seo.tsx` — Head meta tags (title, description, og:*, etc.)
+- `components/Theme.tsx` — CSS variable injection
+- `types/widgets.ts` — CMS widget type aliases (ImageWidget = string, etc.)

package/.cursor/skills/deco-apps-vtex-porting/cookie-auth-patterns.md

@@ -0,0 +1,148 @@
+# Cookie & Auth Patterns for VTEX apps-start
+
+Reference for cookie propagation and authentication patterns in the TanStack Start port.
+
+## vtexFetchWithCookies
+
+Standard `vtexFetch` discards response headers. For any mutation that generates `Set-Cookie`:
+
+```typescript
+export interface VtexFetchResult<T> {
+  data: T;
+  setCookies: string[];
+}
+
+export async function vtexFetchWithCookies<T>(
+  path: string,
+  init?: RequestInit,
+): Promise<VtexFetchResult<T>> {
+  const response = await vtexFetchResponse(path, init);
+  const data = await response.json() as T;
+  const setCookies: string[] = [];
+  response.headers.forEach((value, key) => {
+    if (key.toLowerCase() === "set-cookie") setCookies.push(value);
+  });
+  if (setCookies.length === 0 && typeof response.headers.getSetCookie === "function") {
+    setCookies.push(...response.headers.getSetCookie());
+  }
+  return { data, setCookies };
+}
+```
+
+Use in: `checkout.ts`, `auth.ts`, `session.ts` (create/edit).
+
+## buildAuthCookieHeader
+
+VTEX IO GraphQL at `{account}.myvtex.com` requires both cookie names:
+
+```typescript
+// vtexId.ts
+export const VTEX_AUTH_COOKIE = "VtexIdclientAutCookie";
+
+export function buildAuthCookieHeader(authCookie: string, account: string): string {
+  if (authCookie.includes("=")) return authCookie;
+  return `${VTEX_AUTH_COOKIE}=${authCookie}; ${VTEX_AUTH_COOKIE}_${account}=${authCookie}`;
+}
+```
+
+Usage in any authenticated GraphQL action:
+
+```typescript
+import { buildAuthCookieHeader } from "../utils/vtexId";
+import { getVtexConfig } from "../client";
+
+const { account } = getVtexConfig();
+const result = await vtexIOGraphQL<T>(
+  { query: MY_MUTATION, variables },
+  { cookie: buildAuthCookieHeader(authCookie, account) },
+);
+```
+
+Files that use this pattern:
+- `actions/address.ts` — gql helper
+- `actions/misc.ts` — gql helper
+- `actions/newsletter.ts` — gql helper
+- `actions/profile.ts` — gql helper
+- `actions/wishlist.ts` — buildCookieHeader
+- `actions/session.ts` — deleteSession
+- `utils/enrichment.ts` — simulation auth
+
+Files that use `VTEX_AUTH_COOKIE` directly (as header name, not cookie):
+- `actions/misc.ts` — submitReview sends `{ [VTEX_AUTH_COOKIE]: authCookie }` as HTTP header (Reviews API quirk)
+
+## DEFAULT_EXPECTED_SECTIONS
+
+VTEX returns incomplete OrderForm without explicit sections. Always include:
+
+```typescript
+export const DEFAULT_EXPECTED_SECTIONS = [
+  "items",
+  "totalizers",
+  "clientProfileData",
+  "shippingData",
+  "paymentData",
+  "sellers",
+  "messages",
+  "marketingData",
+  "clientPreferencesData",
+  "storePreferencesData",
+  "giftRegistryData",
+  "ratesAndBenefitsData",
+  "openTextField",
+  "commercialConditionData",
+  "customData",
+];
+```
+
+Used in:
+- `actions/checkout.ts` — all cart mutations
+- `loaders/cart.ts` — getCart POST body
+- `hooks/useCart.ts` — client-side fetchCart POST body
+
+## Intelligent Search Cookies
+
+VTEX Intelligent Search requires tracking cookies. Generate in middleware if missing:
+
+```typescript
+// middleware.ts
+const vtexIsSession = cookies.get("vtex_is_session") ?? crypto.randomUUID();
+const vtexIsAnonymous = cookies.get("vtex_is_anonymous") ?? crypto.randomUUID();
+```
+
+Pass to `intelligentSearch()` via `opts.cookieHeader`:
+
+```typescript
+const data = await intelligentSearch<T>(path, params, {
+  cookieHeader: `vtex_is_session=${session}; vtex_is_anonymous=${anonymous}`,
+  locale: "pt-BR",
+});
+```
+
+## HttpOnly Cookie Rule
+
+`VtexIdclientAutCookie` is HttpOnly — invisible to `document.cookie`.
+
+Client-side hooks must NOT check for this cookie. Instead:
+
+```typescript
+// useUser.ts — correct pattern
+async function fetchUser(): Promise<VtexUser> {
+  const res = await fetch(
+    "/api/sessions?items=profile.email,profile.firstName,profile.lastName,profile.id",
+    { credentials: "include" },
+  );
+  // Parse session response for user data
+}
+```
+
+## salesChannel Injection Points
+
+| Component | How sc is injected |
+|-----------|-------------------|
+| `client.ts` intelligentSearch | Auto from `getVtexConfig().salesChannel` |
+| `hooks/useCart.ts` | Reads `VTEXSC` cookie via `document.cookie` |
+| `loaders/cart.ts` | From `getVtexConfig().salesChannel` |
+| `loaders/catalog.ts` | From `getVtexConfig().salesChannel` |
+| `loaders/legacy.ts` | `buildSearchParams()` includes `sc` |
+| `actions/checkout.ts` | Helper `scParam()` / `appendSc()` |
+| `middleware.ts` | Reads `VTEXSC` cookie from request |