@decocms/apps 0.20.1

package/vtex/loaders/logistics.ts

@@ -0,0 +1,115 @@
+/**
+ * VTEX Logistics & Sales-Channel API loaders.
+ * Pure async functions — require configureVtex() to have been called.
+ *
+ * Ported from deco-cx/apps:
+ *   vtex/loaders/logistics/getSalesChannelById.ts
+ *   vtex/loaders/logistics/listPickupPoints.ts
+ *   vtex/loaders/logistics/listPickupPointsByLocation.ts
+ *   vtex/loaders/logistics/listSalesChannelById.ts  (actually lists all)
+ *   vtex/loaders/logistics/listStockByStore.ts
+ *
+ * @see https://developers.vtex.com/docs/api-reference/logistics-api
+ */
+import { vtexFetch } from "../client";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface ProductBalance {
+  warehouseId: string;
+  warehouseName: string;
+  totalQuantity: number;
+  reservedQuantity: number;
+  hasUnlimitedQuantity: boolean;
+}
+
+export interface PickupPointsByLocationOpts {
+  geoCoordinates?: number[];
+  postalCode?: string;
+  countryCode?: string;
+}
+
+export interface PickupPointsResponse<T = any> {
+  paging: { page: number; pageSize: number; total: number; pages: number };
+  items: Array<{ distance: number; pickupPoint: T }>;
+}
+
+// ---------------------------------------------------------------------------
+// Sales Channels
+// ---------------------------------------------------------------------------
+
+/**
+ * Get a single sales channel by ID (public API).
+ * @see https://developers.vtex.com/docs/api-reference/catalog-api#get-/api/catalog_system/pub/saleschannel/-salesChannelId-
+ */
+export async function getSalesChannelById<T = any>(id: string): Promise<T> {
+  return vtexFetch<T>(`/api/catalog_system/pub/saleschannel/${id}`);
+}
+
+/**
+ * List all sales channels (private API — requires appKey/appToken).
+ * @see https://developers.vtex.com/docs/api-reference/catalog-api#get-/api/catalog_system/pvt/saleschannel/list
+ */
+export async function listSalesChannels<T = any>(): Promise<T[]> {
+  return vtexFetch<T[]>("/api/catalog_system/pvt/saleschannel/list");
+}
+
+// ---------------------------------------------------------------------------
+// Pickup Points
+// ---------------------------------------------------------------------------
+
+/**
+ * List all configured pickup points (private API — requires appKey/appToken).
+ * @see https://developers.vtex.com/docs/api-reference/logistics-api#get-/api/logistics/pvt/configuration/pickuppoints
+ */
+export async function listPickupPoints<T = any>(): Promise<T[]> {
+  return vtexFetch<T[]>("/api/logistics/pvt/configuration/pickuppoints");
+}
+
+/**
+ * Search pickup points near a geographic location (public API).
+ * Pass either `geoCoordinates` (lon/lat array) **or** `postalCode` + `countryCode`.
+ *
+ * @see https://developers.vtex.com/docs/api-reference/checkout-api#get-/api/checkout/pub/pickup-points
+ */
+export async function listPickupPointsByLocation<T = any>(
+  opts: PickupPointsByLocationOpts,
+): Promise<PickupPointsResponse<T>> {
+  const params = new URLSearchParams();
+  if (opts.geoCoordinates) {
+    params.set("geoCoordinates", opts.geoCoordinates.join(","));
+  } else {
+    if (opts.postalCode) params.set("postalCode", opts.postalCode);
+    if (opts.countryCode) params.set("countryCode", opts.countryCode);
+  }
+
+  return vtexFetch<PickupPointsResponse<T>>(
+    `/api/checkout/pub/pickup-points?${params}`,
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Stock / Inventory
+// ---------------------------------------------------------------------------
+
+/**
+ * List inventory balances for a SKU across all warehouses.
+ * @see https://developers.vtex.com/docs/api-reference/logistics-api#get-/api/logistics/pvt/inventory/skus/-skuId-
+ */
+export async function listStockByStore(
+  skuId: number,
+): Promise<ProductBalance[]> {
+  try {
+    const result = await vtexFetch<{
+      skuId?: string;
+      balance?: ProductBalance[];
+    }>(`/api/logistics/pvt/inventory/skus/${skuId}`);
+
+    return result.balance ?? [];
+  } catch (error) {
+    console.error("[listStockByStore]", error);
+    return [];
+  }
+}

package/vtex/loaders/navbar.ts

@@ -0,0 +1,29 @@
+/**
+ * VTEX Navbar (category tree) loader.
+ * Pure async function — requires configureVtex() to have been called.
+ *
+ * Ported from deco-cx/apps:
+ *   vtex/loaders/navbar.ts
+ *
+ * @see https://developers.vtex.com/docs/api-reference/catalog-api#get-/api/catalog_system/pub/category/tree/-categoryLevels-
+ */
+import { vtexFetch } from "../client";
+import { categoryTreeToNavbar } from "../utils/transform";
+import type { Category } from "../utils/types";
+import type { SiteNavigationElement } from "../../commerce/types/commerce";
+
+/**
+ * Fetch the category tree and transform it into an array of
+ * `SiteNavigationElement` nodes suitable for navigation menus.
+ *
+ * @param levels - Depth of the category tree (default: 2)
+ */
+export async function getNavbar(
+  levels: number = 2,
+): Promise<SiteNavigationElement[]> {
+  const tree = await vtexFetch<Category[]>(
+    `/api/catalog_system/pub/category/tree/${levels}`,
+  );
+
+  return categoryTreeToNavbar(tree);
+}

package/vtex/loaders/orders.ts

@@ -0,0 +1,103 @@
+/**
+ * VTEX Orders API loaders.
+ * Pure async functions — require configureVtex() to have been called.
+ *
+ * Ported from deco-cx/apps:
+ *   vtex/loaders/orders/getById.ts
+ *   vtex/loaders/orders/list.ts
+ *
+ * @see https://developers.vtex.com/docs/api-reference/orders-api
+ */
+import { vtexFetch } from "../client";
+
+// ---------------------------------------------------------------------------
+// getOrderById (authenticated — REST)
+// ---------------------------------------------------------------------------
+
+/**
+ * Fetch a single user order by its ID.
+ * The user must be authenticated or the caller must have OMS permissions.
+ *
+ * @see https://developers.vtex.com/docs/api-reference/orders-api#get-/api/oms/user/orders/-orderId-
+ */
+export async function getOrderById<T = any>(
+  orderId: string,
+  authCookie: string,
+): Promise<T> {
+  return vtexFetch<T>(`/api/oms/user/orders/${orderId}`, {
+    headers: { cookie: authCookie },
+  });
+}
+
+// ---------------------------------------------------------------------------
+// listOrders (authenticated — REST)
+// ---------------------------------------------------------------------------
+
+export interface ListOrdersOpts {
+  clientEmail: string;
+  page?: string;
+  perPage?: string;
+}
+
+/**
+ * List orders for a given client e-mail.
+ * The user must be authenticated or the caller must have OMS permissions.
+ *
+ * @see https://developers.vtex.com/docs/api-reference/orders-api#get-/api/oms/user/orders
+ */
+export async function listOrders<T = any>(
+  opts: ListOrdersOpts,
+  authCookie: string,
+): Promise<T> {
+  const { clientEmail, page = "0", perPage = "15" } = opts;
+  const params = new URLSearchParams({
+    clientEmail,
+    page,
+    per_page: perPage,
+  });
+
+  return vtexFetch<T>(`/api/oms/user/orders?${params}`, {
+    headers: { cookie: authCookie },
+  });
+}
+
+// ---------------------------------------------------------------------------
+// getOrderPlaced (order confirmation — Checkout API)
+// ---------------------------------------------------------------------------
+
+/**
+ * Fetch order details for the order-placed / confirmation page.
+ *
+ * Accepts either:
+ *  - An **order group ID** (no hyphen) → returns all orders in the group
+ *  - A single **order ID** (contains hyphen) → returns that order wrapped in an array
+ *
+ * The caller must supply an `authCookie` containing at least the
+ * VtexIdclientAutCookie, CheckoutDataAccess, and Vtex_CHKO_Auth cookies
+ * that VTEX sets after checkout.
+ *
+ * Ported from deco-cx/apps:
+ *   vtex/loaders/orderplaced.ts
+ *
+ * @see https://developers.vtex.com/docs/api-reference/checkout-api#get-/api/checkout/pub/orders/order-group/-orderGroupId-
+ */
+export async function getOrderPlaced<T = any>(
+  orderId: string,
+  authCookie: string,
+): Promise<T[]> {
+  const isOrderGroup = !orderId.includes("-");
+
+  if (isOrderGroup) {
+    return vtexFetch<T[]>(
+      `/api/checkout/pub/orders/order-group/${orderId}`,
+      { headers: { cookie: authCookie } },
+    );
+  }
+
+  const order = await vtexFetch<T>(
+    `/api/checkout/pub/orders/${orderId}`,
+    { headers: { cookie: authCookie } },
+  );
+
+  return [order];
+}

package/vtex/loaders/pageType.ts

@@ -0,0 +1,62 @@
+/**
+ * VTEX page type resolver.
+ *
+ * Given a URL path, determines if it corresponds to a product, category,
+ * brand, department, collection, search, or 404 in VTEX's catalog.
+ *
+ * @see https://developers.vtex.com/docs/api-reference/catalog-api#get-/api/catalog_system/pub/portal/pagetype/-path-
+ */
+import { vtexFetch, type PageType } from "../client";
+
+export type { PageType };
+
+export type VtexPageKind =
+  | "product"
+  | "category"
+  | "department"
+  | "subcategory"
+  | "brand"
+  | "collection"
+  | "search"
+  | "fulltext"
+  | "notfound";
+
+/**
+ * Resolve a URL path to a VTEX page type.
+ *
+ * @param urlPath - The path to resolve (e.g., "/shoes/running")
+ * @returns The page type with kind normalization, or null on error
+ */
+export async function resolvePageType(
+  urlPath: string,
+): Promise<{ pageType: PageType; kind: VtexPageKind } | null> {
+  const cleanPath = urlPath.replace(/^\//, "").replace(/\/$/, "");
+  if (!cleanPath) return null;
+
+  try {
+    const pt = await vtexFetch<PageType>(
+      `/api/catalog_system/pub/portal/pagetype/${cleanPath}`,
+    );
+
+    const kind = normalizeKind(pt.pageType);
+    return { pageType: pt, kind };
+  } catch {
+    return null;
+  }
+}
+
+function normalizeKind(pageType: PageType["pageType"]): VtexPageKind {
+  switch (pageType) {
+    case "Product": return "product";
+    case "Category": return "category";
+    case "Department": return "department";
+    case "SubCategory": return "subcategory";
+    case "Brand": return "brand";
+    case "Collection":
+    case "Cluster": return "collection";
+    case "Search": return "search";
+    case "FullText": return "fulltext";
+    case "NotFound":
+    default: return "notfound";
+  }
+}

package/vtex/loaders/payment.ts

@@ -0,0 +1,107 @@
+/**
+ * VTEX Payment API loaders.
+ * Pure async functions — require configureVtex() to have been called.
+ *
+ * Ported from deco-cx/apps:
+ *   vtex/loaders/payment/paymentSystems.ts
+ *   vtex/loaders/payment/userPayments.ts
+ */
+import { vtexIOGraphQL } from "../client";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface PaymentSystem {
+  name: string;
+  groupName: string;
+  requiresDocument: boolean;
+  displayDocument: boolean;
+  validator: {
+    regex: string | null;
+    mask: string | null;
+    cardCodeMask: string | null;
+    cardCodeRegex: string | null;
+  };
+}
+
+export interface Payment {
+  accountStatus: string | null;
+  cardNumber: string;
+  expirationDate: string;
+  id: string;
+  isExpired: boolean;
+  paymentSystem: string;
+  paymentSystemName: string;
+}
+
+// ---------------------------------------------------------------------------
+// getPaymentSystems (authenticated — VTEX IO GraphQL)
+// ---------------------------------------------------------------------------
+
+const PAYMENT_SYSTEMS_QUERY = `query getPaymentSystems {
+  paymentSystems {
+    name
+    groupName
+    requiresDocument
+    displayDocument
+    validator {
+      regex
+      mask
+      cardCodeMask
+      cardCodeRegex
+    }
+  }
+}`;
+
+/**
+ * List available payment systems for the authenticated user.
+ * Requires a valid VTEX auth cookie.
+ */
+export async function getPaymentSystems(
+  authCookie: string,
+): Promise<PaymentSystem[]> {
+  const { paymentSystems } = await vtexIOGraphQL<{
+    paymentSystems: PaymentSystem[];
+  }>(
+    { query: PAYMENT_SYSTEMS_QUERY },
+    { cookie: authCookie },
+  );
+
+  return paymentSystems;
+}
+
+// ---------------------------------------------------------------------------
+// getUserPayments (authenticated — VTEX IO GraphQL)
+// ---------------------------------------------------------------------------
+
+const USER_PAYMENTS_QUERY = `query getUserPayments {
+  profile {
+    payments {
+      accountStatus
+      cardNumber
+      expirationDate
+      id
+      isExpired
+      paymentSystem
+      paymentSystemName
+    }
+  }
+}`;
+
+/**
+ * List saved payment methods for the authenticated user.
+ * Requires a valid VTEX auth cookie.
+ */
+export async function getUserPayments(
+  authCookie: string,
+): Promise<Payment[]> {
+  const data = await vtexIOGraphQL<{
+    profile: { payments: Payment[] } | null;
+  }>(
+    { query: USER_PAYMENTS_QUERY },
+    { cookie: authCookie },
+  );
+
+  return data.profile?.payments ?? [];
+}

package/vtex/loaders/profile.ts

@@ -0,0 +1,138 @@
+/**
+ * VTEX Profile API loaders.
+ * Pure async functions — require configureVtex() to have been called.
+ *
+ * Ported from deco-cx/apps:
+ *   vtex/loaders/profile/getCurrentProfile.ts
+ *   vtex/loaders/profile/getProfileByEmail.ts
+ *
+ * @see https://developers.vtex.com/docs/api-reference/checkout-api
+ */
+import { vtexFetch, vtexIOGraphQL } from "../client";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+const ADDRESS_FIELDS = `
+  addressType
+  receiverName
+  addressId
+  postalCode
+  city
+  state
+  country
+  street
+  number
+  neighborhood
+  complement
+  reference
+  geoCoordinates
+`;
+
+export interface Profile {
+  id: string;
+  cacheId: string;
+  email: string;
+  firstName: string;
+  lastName: string;
+  document: string;
+  userId: string;
+  birthDate: string;
+  gender: string;
+  homePhone: string;
+  businessPhone: string;
+  addresses: Record<string, unknown>[];
+  isCorporate: boolean;
+  tradeName: string;
+  corporateName: string;
+  corporateDocument: string;
+  stateRegistration: string;
+  payments: Record<string, unknown>[];
+  customFields: Array<{ key: string; value: string }>;
+  passwordLastUpdate: string;
+}
+
+// ---------------------------------------------------------------------------
+// getCurrentProfile (authenticated — VTEX IO GraphQL)
+// ---------------------------------------------------------------------------
+
+const PROFILE_QUERY = `query getUserProfile($customFields: String) {
+  profile(customFields: $customFields) {
+    id
+    cacheId
+    email
+    firstName
+    lastName
+    document
+    userId
+    birthDate
+    gender
+    homePhone
+    businessPhone
+    addresses { ${ADDRESS_FIELDS} }
+    isCorporate
+    tradeName
+    corporateName
+    corporateDocument
+    stateRegistration
+    payments {
+      cacheId
+      id
+      paymentSystem
+      paymentSystemName
+      cardNumber
+      address { ${ADDRESS_FIELDS} }
+      isExpired
+      expirationDate
+      accountStatus
+    }
+    customFields {
+      key
+      value
+    }
+    passwordLastUpdate
+  }
+}`;
+
+/**
+ * Fetch the full profile for the currently authenticated user.
+ * Requires a valid VTEX auth cookie.
+ */
+export async function getCurrentProfile(
+  authCookie: string,
+  customFields?: string[],
+): Promise<Profile> {
+  const { profile } = await vtexIOGraphQL<{ profile: Profile }>(
+    {
+      query: PROFILE_QUERY,
+      variables: { customFields: customFields?.join(",") },
+    },
+    { cookie: authCookie },
+  );
+
+  return profile;
+}
+
+// ---------------------------------------------------------------------------
+// getProfileByEmail (authenticated — REST)
+// ---------------------------------------------------------------------------
+
+/**
+ * Fetch a checkout profile by e-mail.
+ * Requires a valid VTEX auth cookie.
+ *
+ * @see https://developers.vtex.com/docs/api-reference/checkout-api#get-/api/checkout/pub/profiles
+ */
+export async function getProfileByEmail<T = any>(
+  email: string,
+  authCookie: string,
+  ensureComplete?: boolean,
+): Promise<T> {
+  const params = new URLSearchParams({ email });
+  if (ensureComplete) params.set("ensureComplete", "true");
+
+  return vtexFetch<T>(`/api/checkout/pub/profiles?${params}`, {
+    headers: { cookie: authCookie },
+  });
+}

package/vtex/loaders/promotion.ts

@@ -0,0 +1,33 @@
+/**
+ * VTEX Promotion loader.
+ * Pure async function — requires configureVtex() to have been called.
+ *
+ * Ported from deco-cx/apps:
+ *   vtex/loaders/getPromotionById.ts
+ *
+ * @see https://developers.vtex.com/docs/api-reference/promotions-and-taxes-api
+ */
+import { vtexFetch } from "../client";
+import type { Document } from "../utils/types";
+
+/**
+ * Fetch a promotion / calculator-configuration by its ID.
+ *
+ * Note: uses the **pvt** (private) endpoint — requires appKey/appToken
+ * or a valid authentication cookie.
+ *
+ * @param promotionId - The `idCalculatorConfiguration` of the promotion
+ * @param authCookie  - Optional cookie string for authenticated requests
+ */
+export async function getPromotionById(
+  promotionId: string,
+  authCookie?: string,
+): Promise<Document[]> {
+  const headers: Record<string, string> = {};
+  if (authCookie) headers.cookie = authCookie;
+
+  return vtexFetch<Document[]>(
+    `/api/rnb/pvt/calculatorconfiguration/${promotionId}`,
+    { headers },
+  );
+}