@decocms/apps 0.20.1

package/vtex/invoke.ts

@@ -0,0 +1,202 @@
+/**
+ * Typed invoke object for VTEX actions — same DX as deco-cx/deco.
+ *
+ * Client-side components call `invoke.vtex.actions.*({ data: ... })`.
+ * Under the hood, each call is a `createServerFn` that executes
+ * on the server with full VTEX credentials (appKey/appToken).
+ *
+ * @example
+ * ```tsx
+ * import { invoke } from "@decocms/apps/vtex/invoke";
+ *
+ * // Add to cart
+ * const cart = await invoke.vtex.actions.addItemsToCart({
+ *   data: { orderFormId: "abc", orderItems: [{ id: "1", seller: "1", quantity: 1 }] }
+ * });
+ *
+ * // Subscribe to newsletter
+ * await invoke.vtex.actions.subscribe({ data: { email: "user@example.com" } });
+ *
+ * // Notify me when back in stock
+ * await invoke.vtex.actions.notifyMe({ data: { email: "u@e.com", skuId: "123" } });
+ * ```
+ */
+import { createInvokeFn } from "@decocms/start/sdk/createInvoke";
+import {
+  getOrCreateCart,
+  addItemsToCart,
+  updateCartItems,
+  addCouponToCart,
+  simulateCart,
+  getSellersByRegion,
+  setShippingPostalCode,
+  type SimulationItem,
+} from "./actions/checkout";
+import {
+  createDocument,
+  getDocument,
+  patchDocument,
+  searchDocuments,
+  uploadAttachment,
+  type UploadAttachmentOpts,
+  type CreateDocumentResult,
+} from "./actions/masterData";
+import { createSession } from "./actions/session";
+import { subscribe, type SubscribeProps } from "./actions/newsletter";
+import { notifyMe, type NotifyMeProps } from "./actions/misc";
+import type { OrderForm } from "./types";
+import type { RegionResult } from "./actions/checkout";
+
+// ---------------------------------------------------------------------------
+// invoke.vtex.actions — typed server functions callable from client
+// ---------------------------------------------------------------------------
+
+export const invoke = {
+  vtex: {
+    actions: {
+      // -- Cart (unwrap VtexFetchResult -> OrderForm) -----------------------
+
+      getOrCreateCart: createInvokeFn(
+        (input: { orderFormId?: string }) =>
+          getOrCreateCart(input.orderFormId),
+        { unwrap: true },
+      ) as unknown as (ctx: { data: { orderFormId?: string } }) => Promise<OrderForm>,
+
+      addItemsToCart: createInvokeFn(
+        (input: {
+          orderFormId: string;
+          orderItems: Array<{
+            id: string;
+            seller: string;
+            quantity: number;
+          }>;
+        }) => addItemsToCart(input.orderFormId, input.orderItems),
+        { unwrap: true },
+      ) as unknown as (ctx: {
+        data: {
+          orderFormId: string;
+          orderItems: Array<{
+            id: string;
+            seller: string;
+            quantity: number;
+          }>;
+        };
+      }) => Promise<OrderForm>,
+
+      updateCartItems: createInvokeFn(
+        (input: {
+          orderFormId: string;
+          orderItems: Array<{ index: number; quantity: number }>;
+        }) => updateCartItems(input.orderFormId, input.orderItems),
+        { unwrap: true },
+      ) as unknown as (ctx: {
+        data: {
+          orderFormId: string;
+          orderItems: Array<{ index: number; quantity: number }>;
+        };
+      }) => Promise<OrderForm>,
+
+      addCouponToCart: createInvokeFn(
+        (input: { orderFormId: string; text: string }) =>
+          addCouponToCart(input.orderFormId, input.text),
+        { unwrap: true },
+      ) as unknown as (ctx: {
+        data: { orderFormId: string; text: string };
+      }) => Promise<OrderForm>,
+
+      simulateCart: createInvokeFn(
+        (input: {
+          items: SimulationItem[];
+          postalCode: string;
+          country?: string;
+        }) => simulateCart(input.items, input.postalCode, input.country),
+      ),
+
+      // -- Shipping / Region ------------------------------------------------
+
+      getSellersByRegion: createInvokeFn(
+        (input: { postalCode: string; salesChannel?: string }) =>
+          getSellersByRegion(input.postalCode, input.salesChannel),
+      ) as (ctx: {
+        data: { postalCode: string; salesChannel?: string };
+      }) => Promise<RegionResult | null>,
+
+      setShippingPostalCode: createInvokeFn(
+        (input: {
+          orderFormId: string;
+          postalCode: string;
+          country?: string;
+        }) =>
+          setShippingPostalCode(
+            input.orderFormId,
+            input.postalCode,
+            input.country,
+          ),
+      ) as (ctx: {
+        data: {
+          orderFormId: string;
+          postalCode: string;
+          country?: string;
+        };
+      }) => Promise<boolean>,
+
+      // -- Session ----------------------------------------------------------
+
+      createSession: createInvokeFn(
+        (input: Record<string, any>) => createSession(input),
+        { unwrap: true },
+      ),
+
+      // -- MasterData -------------------------------------------------------
+
+      createDocument: createInvokeFn(
+        (input: { entity: string; data: Record<string, any> }) =>
+          createDocument(input.entity, input.data),
+      ) as (ctx: {
+        data: { entity: string; data: Record<string, any> };
+      }) => Promise<CreateDocumentResult>,
+
+      getDocument: createInvokeFn(
+        (input: { entity: string; documentId: string }) =>
+          getDocument(input.entity, input.documentId),
+      ),
+
+      patchDocument: createInvokeFn(
+        (input: {
+          entity: string;
+          documentId: string;
+          data: Record<string, any>;
+        }) => patchDocument(input.entity, input.documentId, input.data),
+      ) as (ctx: {
+        data: {
+          entity: string;
+          documentId: string;
+          data: Record<string, any>;
+        };
+      }) => Promise<void>,
+
+      searchDocuments: createInvokeFn(
+        (input: { entity: string; filter: string }) =>
+          searchDocuments(input.entity, input.filter),
+      ),
+
+      uploadAttachment: createInvokeFn(
+        (input: UploadAttachmentOpts) => uploadAttachment(input),
+      ) as (ctx: {
+        data: UploadAttachmentOpts;
+      }) => Promise<{ ok: true }>,
+
+      // -- Newsletter -------------------------------------------------------
+
+      subscribe: createInvokeFn(
+        (input: SubscribeProps) => subscribe(input),
+      ) as (ctx: { data: SubscribeProps }) => Promise<void>,
+
+      // -- Misc -------------------------------------------------------------
+
+      notifyMe: createInvokeFn(
+        (input: NotifyMeProps) => notifyMe(input),
+      ) as (ctx: { data: NotifyMeProps }) => Promise<void>,
+    },
+  },
+} as const;

package/vtex/loaders/address.ts

@@ -0,0 +1,120 @@
+/**
+ * VTEX Address API loaders.
+ * Pure async functions — require configureVtex() to have been called.
+ *
+ * Ported from deco-cx/apps:
+ *   vtex/loaders/address/getAddressByPostalCode.ts
+ *   vtex/loaders/address/getUserAddresses.ts
+ *
+ * @see https://developers.vtex.com/docs/api-reference/checkout-api
+ */
+import { vtexFetch, vtexIOGraphQL } from "../client";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface PostalAddress {
+  "@type": "PostalAddress";
+  postalCode?: string;
+  addressLocality?: string;
+  addressRegion?: string;
+  addressCountry?: string;
+  streetAddress?: string;
+  identifier?: string;
+  areaServed?: string;
+  description?: string;
+  disambiguatingDescription?: string;
+  latitude?: number;
+  longitude?: number;
+}
+
+export interface VtexAddress {
+  addressId: string;
+  addressType: string;
+  addressName: string;
+  city: string;
+  complement: string;
+  country: string;
+  neighborhood: string;
+  number: string;
+  postalCode: string;
+  geoCoordinates: number[];
+  receiverName: string;
+  state: string;
+  street: string;
+}
+
+// ---------------------------------------------------------------------------
+// getAddressByPostalCode
+// ---------------------------------------------------------------------------
+
+/**
+ * Look up a postal address by country + postal code (public API).
+ * @see https://developers.vtex.com/docs/api-reference/checkout-api#get-/api/checkout/pub/postal-code/-countryCode-/-postalCode-
+ */
+export async function getAddressByPostalCode(
+  countryCode: string,
+  postalCode: string,
+): Promise<PostalAddress> {
+  const data = await vtexFetch<Record<string, any>>(
+    `/api/checkout/pub/postal-code/${countryCode}/${postalCode}`,
+  );
+
+  return {
+    "@type": "PostalAddress",
+    postalCode: data.postalCode,
+    addressLocality: data.city,
+    addressRegion: data.state,
+    addressCountry: data.country,
+    streetAddress: data.street || undefined,
+    identifier: data.number || undefined,
+    areaServed: data.neighborhood || undefined,
+    description: data.complement || undefined,
+    disambiguatingDescription: data.reference || undefined,
+    latitude: data.geoCoordinates?.[0] || undefined,
+    longitude: data.geoCoordinates?.[1] || undefined,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// getUserAddresses (authenticated — VTEX IO GraphQL)
+// ---------------------------------------------------------------------------
+
+const USER_ADDRESSES_QUERY = `query Addresses @context(scope: "private") {
+  profile {
+    cacheId
+    addresses {
+      addressId: id
+      addressType
+      addressName
+      city
+      complement
+      country
+      neighborhood
+      number
+      postalCode
+      geoCoordinates
+      receiverName
+      state
+      street
+    }
+  }
+}`;
+
+/**
+ * Fetch addresses for the currently authenticated user.
+ * Requires a valid VTEX auth cookie.
+ */
+export async function getUserAddresses(
+  authCookie: string,
+): Promise<VtexAddress[]> {
+  const { profile } = await vtexIOGraphQL<{
+    profile: { addresses: VtexAddress[] };
+  }>(
+    { query: USER_ADDRESSES_QUERY },
+    { cookie: authCookie },
+  );
+
+  return profile?.addresses ?? [];
+}

package/vtex/loaders/brands.ts

@@ -0,0 +1,51 @@
+/**
+ * VTEX brand loaders.
+ * Returns schema.org Brand[] matching the original deco-cx/apps format.
+ *
+ * @see https://developers.vtex.com/docs/api-reference/catalog-api#get-/api/catalog_system/pub/brand/list
+ */
+import { vtexFetch, getVtexConfig } from "../client";
+import { toBrand } from "../utils/transform";
+import type { Brand } from "../../commerce/types/commerce";
+import type { Brand as BrandVTEX } from "../utils/types";
+
+export interface ListBrandsOpts {
+  /** When true, only returns active brands. @default false */
+  filterInactive?: boolean;
+}
+
+/**
+ * List brands from the VTEX catalog, transformed to schema.org Brand format.
+ */
+export async function listBrands(
+  opts?: ListBrandsOpts,
+): Promise<Brand[]> {
+  const config = getVtexConfig();
+  const baseUrl = `https://${config.account}.vteximg.com.br/arquivos/ids`;
+
+  const brands = await vtexFetch<BrandVTEX[]>(
+    "/api/catalog_system/pub/brand/list",
+  );
+
+  const filtered = opts?.filterInactive
+    ? brands.filter((b) => b.isActive)
+    : brands;
+
+  return filtered.map((b) => toBrand(b, baseUrl));
+}
+
+/**
+ * Get a single brand by ID, as schema.org Brand.
+ */
+export async function getBrandById(brandId: number): Promise<Brand | null> {
+  try {
+    const config = getVtexConfig();
+    const baseUrl = `https://${config.account}.vteximg.com.br/arquivos/ids`;
+    const brand = await vtexFetch<BrandVTEX>(
+      `/api/catalog_system/pub/brand/${brandId}`,
+    );
+    return toBrand(brand, baseUrl);
+  } catch {
+    return null;
+  }
+}

package/vtex/loaders/cart.ts

@@ -0,0 +1,49 @@
+/**
+ * VTEX Cart (OrderForm) loader.
+ * Pure async function — requires configureVtex() to have been called.
+ *
+ * Ported from deco-cx/apps:
+ *   vtex/loaders/cart.ts
+ *
+ * @see https://developers.vtex.com/docs/api-reference/checkout-api#get-/api/checkout/pub/orderForm
+ */
+import { vtexFetch, getVtexConfig } from "../client";
+import type { OrderForm } from "../utils/types";
+import { forceHttpsOnAssets } from "../utils/transform";
+import { DEFAULT_EXPECTED_SECTIONS } from "../actions/checkout";
+
+/**
+ * Fetch the current cart (OrderForm).
+ *
+ * When `orderFormId` is provided the existing cart is retrieved;
+ * otherwise a fresh OrderForm is created via POST.
+ *
+ * @param orderFormId - Optional existing orderForm ID (from checkout cookie)
+ * @param salesChannel - Optional sales channel override
+ * @param authCookie - Optional cookie string for authenticated requests
+ */
+export async function getCart(
+  orderFormId?: string,
+  opts?: { salesChannel?: string; authCookie?: string },
+): Promise<OrderForm> {
+  const { salesChannel } = getVtexConfig();
+  const sc = opts?.salesChannel ?? salesChannel;
+  const headers: Record<string, string> = {};
+  if (opts?.authCookie) headers.cookie = opts.authCookie;
+
+  const scParam = sc ? `?sc=${sc}` : "";
+
+  const body = JSON.stringify({ expectedOrderFormSections: DEFAULT_EXPECTED_SECTIONS });
+
+  const cart = orderFormId
+    ? await vtexFetch<OrderForm>(
+        `/api/checkout/pub/orderForm/${orderFormId}${scParam}`,
+        { method: "POST", headers, body },
+      )
+    : await vtexFetch<OrderForm>(
+        `/api/checkout/pub/orderForm${scParam}`,
+        { method: "POST", headers, body },
+      );
+
+  return forceHttpsOnAssets(cart);
+}

package/vtex/loaders/catalog.ts

@@ -0,0 +1,165 @@
+/**
+ * VTEX Catalog System API loaders.
+ * Pure async functions using vtexFetch. Require configureVtex() to have been called.
+ *
+ * Ported from deco-cx/apps vtex/loaders/legacy/*.ts and vtex/utils/client.ts
+ * @see https://developers.vtex.com/docs/api-reference/catalog-api
+ */
+import { vtexFetch, getVtexConfig } from "../client";
+
+// ---------------------------------------------------------------------------
+// Product search (public)
+// ---------------------------------------------------------------------------
+
+export type LegacySort =
+  | ""
+  | "OrderByTopSaleDESC"
+  | "OrderByReleaseDateDESC"
+  | "OrderByBestDiscountDESC"
+  | "OrderByPriceDESC"
+  | "OrderByPriceASC"
+  | "OrderByNameASC"
+  | "OrderByNameDESC"
+  | "OrderByScoreDESC";
+
+export interface SearchProductsOpts {
+  fq?: string | string[];
+  ft?: string;
+  sort?: LegacySort;
+  from?: number;
+  to?: number;
+}
+
+/**
+ * Search products using the VTEX Catalog API.
+ * @see https://developers.vtex.com/docs/api-reference/search-api#get-/api/catalog_system/pub/products/search
+ */
+export async function searchProducts<T = any>(opts: SearchProductsOpts = {}): Promise<T[]> {
+  const params = new URLSearchParams();
+  const fqs = Array.isArray(opts.fq) ? opts.fq : opts.fq ? [opts.fq] : [];
+  for (const f of fqs) params.append("fq", f);
+  if (opts.ft) params.set("ft", opts.ft);
+  if (opts.sort) params.set("O", opts.sort);
+  if (opts.from != null) params.set("_from", String(opts.from));
+  if (opts.to != null) params.set("_to", String(opts.to));
+
+  const { salesChannel } = getVtexConfig();
+  if (salesChannel) params.set("sc", salesChannel);
+
+  return vtexFetch<T[]>(`/api/catalog_system/pub/products/search/?${params}`);
+}
+
+/**
+ * Get a product by productId or skuId.
+ * @see https://developers.vtex.com/docs/api-reference/search-api#get-/api/catalog_system/pub/products/search
+ */
+export async function getProductByIdOrSku<T = any>(opts: {
+  productId?: string;
+  skuId?: string;
+}): Promise<T | null> {
+  let fq: string;
+  if (opts.productId) fq = `productId:${opts.productId}`;
+  else if (opts.skuId) fq = `skuId:${opts.skuId}`;
+  else throw new Error("Neither productId nor skuId provided.");
+
+  const results = await searchProducts<T>({ fq });
+  return results[0] ?? null;
+}
+
+// ---------------------------------------------------------------------------
+// Product variations (public)
+// ---------------------------------------------------------------------------
+
+/**
+ * Get product SKU variations.
+ * @see https://developers.vtex.com/docs/api-reference/catalog-api#get-/api/catalog_system/pub/products/variations/-productId-
+ */
+export async function getProductVariations<T = any>(productId: string): Promise<T> {
+  return vtexFetch<T>(`/api/catalog_system/pub/products/variations/${productId}`);
+}
+
+// ---------------------------------------------------------------------------
+// Product specification (private — requires appKey/appToken)
+// ---------------------------------------------------------------------------
+
+/**
+ * Get product specifications (private API).
+ * @see https://developers.vtex.com/docs/api-reference/catalog-api#get-/api/catalog_system/pvt/products/-productId-/specification
+ */
+export async function getProductSpecification<T = any>(productId: string): Promise<T> {
+  return vtexFetch<T>(`/api/catalog_system/pvt/products/${productId}/Specification`);
+}
+
+// ---------------------------------------------------------------------------
+// Cross-selling
+// ---------------------------------------------------------------------------
+
+export type CrossSellingType =
+  | "similars"
+  | "suggestions"
+  | "accessories"
+  | "whosawalsosaw"
+  | "whosawalsobought"
+  | "whoboughtalsobought"
+  | "showtogether";
+
+/**
+ * Get cross-selling products.
+ * @see https://developers.vtex.com/docs/api-reference/catalog-api#get-/api/catalog_system/pub/products/crossselling/-type-/-productId-
+ */
+export async function getCrossSelling<T = any>(
+  type: CrossSellingType,
+  productId: string,
+): Promise<T[]> {
+  return vtexFetch<T[]>(
+    `/api/catalog_system/pub/products/crossselling/${type}/${productId}`,
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Categories
+// ---------------------------------------------------------------------------
+
+/**
+ * Get the category tree up to a given depth level.
+ * @see https://developers.vtex.com/docs/api-reference/catalog-api#get-/api/catalog_system/pub/category/tree/-categoryLevels-
+ */
+export async function getCategoryTree<T = any>(levels = 3): Promise<T[]> {
+  return vtexFetch<T[]>(`/api/catalog_system/pub/category/tree/${levels}`);
+}
+
+// ---------------------------------------------------------------------------
+// Brands
+// ---------------------------------------------------------------------------
+
+/**
+ * Get all brands.
+ * @see https://developers.vtex.com/docs/api-reference/catalog-api#get-/api/catalog_system/pub/brand/list
+ */
+export async function getBrands<T = any>(): Promise<T[]> {
+  return vtexFetch<T[]>("/api/catalog_system/pub/brand/list");
+}
+
+// ---------------------------------------------------------------------------
+// Page type
+// ---------------------------------------------------------------------------
+
+/**
+ * Get the page type for a given term/path.
+ * @see https://developers.vtex.com/docs/api-reference/catalog-api#get-/api/catalog_system/pub/portal/pagetype/-term-
+ */
+export async function getPageType<T = any>(term: string): Promise<T> {
+  return vtexFetch<T>(`/api/catalog_system/pub/portal/pagetype/${term}`);
+}
+
+// ---------------------------------------------------------------------------
+// Facets (legacy)
+// ---------------------------------------------------------------------------
+
+/**
+ * Get facets/filters for a search term.
+ * @see https://developers.vtex.com/docs/api-reference/search-api#get-/api/catalog_system/pub/facets/search/-term-
+ */
+export async function getFacets<T = any>(term: string): Promise<T> {
+  return vtexFetch<T>(`/api/catalog_system/pub/facets/search/${term}`);
+}

package/vtex/loaders/collections.ts

@@ -0,0 +1,57 @@
+/**
+ * VTEX Collections loader.
+ * Pure async function — requires configureVtex() to have been called.
+ *
+ * Ported from deco-cx/apps:
+ *   vtex/loaders/collections/list.ts
+ *
+ * @see https://developers.vtex.com/docs/api-reference/catalog-api#get-/api/catalog_system/pvt/collection/search
+ */
+import { vtexFetch } from "../client";
+import type { CollectionList } from "../utils/types";
+
+export interface CollectionOption {
+  value: string;
+  label: string;
+}
+
+/**
+ * Fetch collections, optionally filtering by search term.
+ *
+ * Without a term returns up to 3 000 collections; with a term
+ * returns the first 15 matches. Results are mapped to a simple
+ * `{ value, label }` list suitable for dropdowns / selectors.
+ *
+ * Note: uses the **pvt** (private) endpoint — requires appKey/appToken.
+ */
+export async function getCollections(
+  term?: string,
+): Promise<CollectionOption[]> {
+  const params = new URLSearchParams();
+
+  if (term) {
+    params.set("page", "1");
+    params.set("pageSize", "15");
+    const list = await vtexFetch<CollectionList>(
+      `/api/catalog_system/pvt/collection/search/${encodeURIComponent(term)}?${params}`,
+    );
+    return mapToOptions(list);
+  }
+
+  params.set("page", "1");
+  params.set("pageSize", "3000");
+  params.set("orderByAsc", "false");
+  const list = await vtexFetch<CollectionList>(
+    `/api/catalog_system/pvt/collection/search?${params}`,
+  );
+  return mapToOptions(list);
+}
+
+function mapToOptions(list: CollectionList): CollectionOption[] {
+  return (
+    list.items?.map((c) => ({
+      value: `${c.id}`,
+      label: `${c.id} - ${c.name}`,
+    })) ?? []
+  );
+}

package/vtex/loaders/index.ts

@@ -0,0 +1,19 @@
+export * from "./address";
+export * from "./brands";
+export * from "./cart";
+export * from "./catalog";
+export * from "./collections";
+export * from "./legacy";
+export * from "./logistics";
+export * from "./navbar";
+export * from "./orders";
+export * from "./pageType";
+export * from "./payment";
+export * from "./profile";
+export * from "./promotion";
+export * from "./search";
+export * from "./session";
+export * from "./user";
+export * from "./wishlist";
+export * from "./wishlistProducts";
+export * from "./workflow";