@decocms/apps 0.20.1

package/vtex/actions/misc.ts

@@ -0,0 +1,196 @@
+/**
+ * Miscellaneous VTEX actions that don't warrant their own module.
+ * Ported from deco-cx/apps:
+ *   - vtex/actions/notifyme.ts
+ *   - vtex/actions/analytics/sendEvent.ts
+ *   - vtex/actions/review/submit.ts
+ *   - vtex/actions/payment/deletePaymentToken.ts
+ * @see https://developers.vtex.com/docs/api-reference
+ */
+import { vtexFetch, getVtexConfig } from "../client";
+import { buildAuthCookieHeader, VTEX_AUTH_COOKIE } from "../utils/vtexId";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface NotifyMeProps {
+  email: string;
+  skuId: string;
+  name?: string;
+}
+
+export interface ReviewData {
+  productId: string;
+  rating: number;
+  title: string;
+  text: string;
+  reviewerName: string;
+  approved: boolean;
+}
+
+export type AnalyticsEvent =
+  | {
+      type: "session.ping";
+      url: string;
+    }
+  | {
+      type: "page.cart";
+      products: { productId: string; quantity: number }[];
+    }
+  | {
+      type: "page.empty_cart";
+      products: Record<string, never>;
+    }
+  | {
+      type: "page.confirmation";
+      order: string;
+      products: { productId: string; quantity: number; price: number }[];
+    }
+  | {
+      type: "search.click";
+      position: number;
+      text: string;
+      productId: string;
+      url: string;
+    }
+  | {
+      type: "search.query";
+      url: string;
+      text: string;
+      misspelled: boolean;
+      match: number;
+      operator: string;
+      locale: string;
+    };
+
+export interface ISCookies {
+  anonymous: string;
+  session: string;
+}
+
+export interface DeletePaymentTokenResult {
+  deletePaymentToken: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// GraphQL helper (myvtex.com private graphql)
+// ---------------------------------------------------------------------------
+
+interface GqlResponse<T> {
+  data: T;
+  errors?: Array<{ message: string }>;
+}
+
+async function gql<T>(
+  query: string,
+  variables: Record<string, unknown>,
+  authCookie: string,
+): Promise<T> {
+  const { account } = getVtexConfig();
+  const result = await vtexFetch<GqlResponse<T>>(
+    `https://${account}.myvtex.com/_v/private/graphql/v1`,
+    {
+      method: "POST",
+      body: JSON.stringify({ query, variables }),
+      headers: { Cookie: buildAuthCookieHeader(authCookie, account) },
+    },
+  );
+  if (result.errors?.length) {
+    throw new Error(`GraphQL error: ${result.errors[0].message}`);
+  }
+  return result.data;
+}
+
+// ---------------------------------------------------------------------------
+// Mutation
+// ---------------------------------------------------------------------------
+
+const DELETE_PAYMENT_TOKEN = `mutation DeleteCreditCardToken($tokenId: ID!) {
+  deletePaymentToken(tokenId: $tokenId) @context(provider: "vtex.my-cards-graphql@2.x")
+}`;
+
+// ---------------------------------------------------------------------------
+// Actions
+// ---------------------------------------------------------------------------
+
+/**
+ * Register a "notify me when back in stock" request.
+ * Uses the legacy VTEX .aspx form endpoint (FormData, not JSON).
+ */
+export async function notifyMe(props: NotifyMeProps): Promise<void> {
+  const { account } = getVtexConfig();
+  const { email, skuId, name = "" } = props;
+
+  const form = new FormData();
+  form.append("notifymeClientName", name);
+  form.append("notifymeClientEmail", email);
+  form.append("notifymeIdSku", skuId);
+
+  await fetch(
+    `https://${account}.vtexcommercestable.com.br/no-cache/AviseMe.aspx`,
+    { method: "POST", body: form },
+  );
+}
+
+/**
+ * Send an Intelligent Search analytics event to sp.vtex.com.
+ *
+ * @param event     - The typed event payload.
+ * @param isCookies - IS session tracking IDs (anonymous + session).
+ *                    In the original, these came from getISCookiesFromBag(ctx).
+ * @param userAgent - Forwarded user-agent string.
+ */
+export async function sendEvent(
+  event: AnalyticsEvent,
+  isCookies: ISCookies,
+  userAgent?: string,
+): Promise<void> {
+  const { account } = getVtexConfig();
+
+  await fetch(`https://sp.vtex.com/event-api/v1/${account}/event`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      ...event,
+      ...isCookies,
+      agent: userAgent || "deco-sites/apps",
+    }),
+  });
+}
+
+/**
+ * Submit a product review via the Reviews & Ratings API.
+ * Hits POST https://{account}.myvtex.com/reviews-and-ratings/api/review.
+ * Auth is passed via the `VtexIdclientAutCookie` header (not a Cookie header).
+ */
+export async function submitReview(
+  data: ReviewData,
+  authCookie: string,
+): Promise<unknown> {
+  const { account } = getVtexConfig();
+
+  return vtexFetch<unknown>(
+    `https://${account}.myvtex.com/reviews-and-ratings/api/review`,
+    {
+      method: "POST",
+      body: JSON.stringify(data),
+      headers: { [VTEX_AUTH_COOKIE]: authCookie },
+    },
+  );
+}
+
+/**
+ * Delete a saved payment token (credit card) for the authenticated user.
+ * Uses the my-cards-graphql VTEX IO app.
+ */
+export async function deletePaymentToken(
+  tokenId: string,
+  authCookie: string,
+): Promise<DeletePaymentTokenResult> {
+  return gql<DeletePaymentTokenResult>(
+    DELETE_PAYMENT_TOKEN,
+    { tokenId },
+    authCookie,
+  );
+}

package/vtex/actions/newsletter.ts

@@ -0,0 +1,108 @@
+/**
+ * VTEX Newsletter actions.
+ * Ported from deco-cx/apps:
+ *   - vtex/actions/newsletter/subscribe.ts
+ *   - vtex/actions/newsletter/updateNewsletterOptIn.ts
+ * @see https://developers.vtex.com/docs/guides/newsletter
+ */
+import { vtexFetch, getVtexConfig } from "../client";
+import { buildAuthCookieHeader } from "../utils/vtexId";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface SubscribeProps {
+  email: string;
+  name?: string;
+  page?: string;
+  part?: string;
+  /** Intentionally preserving the original typo from the VTEX legacy form field. */
+  campaing?: string;
+}
+
+// ---------------------------------------------------------------------------
+// GraphQL helper (myvtex.com private graphql)
+// ---------------------------------------------------------------------------
+
+interface GqlResponse<T> {
+  data: T;
+  errors?: Array<{ message: string }>;
+}
+
+async function gql<T>(
+  query: string,
+  variables: Record<string, unknown>,
+  authCookie: string,
+): Promise<T> {
+  const { account } = getVtexConfig();
+  const result = await vtexFetch<GqlResponse<T>>(
+    `https://${account}.myvtex.com/_v/private/graphql/v1`,
+    {
+      method: "POST",
+      body: JSON.stringify({ query, variables }),
+      headers: { Cookie: buildAuthCookieHeader(authCookie, account) },
+    },
+  );
+  if (result.errors?.length) {
+    throw new Error(`GraphQL error: ${result.errors[0].message}`);
+  }
+  return result.data;
+}
+
+// ---------------------------------------------------------------------------
+// Mutation
+// ---------------------------------------------------------------------------
+
+const SUBSCRIBE_NEWSLETTER = `mutation SubscribeNewsletter($email: String!, $isNewsletterOptIn: Boolean!) {
+  subscribeNewsletter(email: $email, isNewsletterOptIn: $isNewsletterOptIn) @context(provider: "vtex.store-graphql@2.x")
+}`;
+
+// ---------------------------------------------------------------------------
+// Actions
+// ---------------------------------------------------------------------------
+
+/**
+ * Subscribe to the newsletter via the legacy VTEX .aspx form endpoint.
+ * Uses raw fetch because the body is FormData (not JSON).
+ */
+export async function subscribe(props: SubscribeProps): Promise<void> {
+  const { account } = getVtexConfig();
+  const {
+    email,
+    name = "",
+    part = "newsletter",
+    page = "_",
+    campaing = "newsletter:opt-in",
+  } = props;
+
+  const form = new FormData();
+  form.append("newsletterClientName", name);
+  form.append("newsletterClientEmail", email);
+  form.append("newsInternalPage", page);
+  form.append("newsInternalPart", part);
+  form.append("newsInternalCampaign", campaing);
+
+  await fetch(
+    `https://${account}.vtexcommercestable.com.br/no-cache/Newsletter.aspx`,
+    { method: "POST", body: form },
+  );
+}
+
+/**
+ * Toggle the newsletter opt-in flag for an authenticated user.
+ * The original Deco action extracted `email` from the auth cookie payload.
+ * Here the caller must provide it explicitly.
+ */
+export async function updateNewsletterOptIn(
+  subscribed: boolean,
+  email: string,
+  authCookie: string,
+): Promise<{ subscribed: boolean }> {
+  await gql<unknown>(
+    SUBSCRIBE_NEWSLETTER,
+    { email, isNewsletterOptIn: subscribed },
+    authCookie,
+  );
+  return { subscribed };
+}

package/vtex/actions/orders.ts

@@ -0,0 +1,37 @@
+/**
+ * VTEX Order management actions.
+ * Ported from deco-cx/apps:
+ *   - vtex/actions/orders/cancel.ts
+ * @see https://developers.vtex.com/docs/api-reference/orders-api
+ */
+import { vtexFetch, getVtexConfig } from "../client";
+import { buildAuthCookieHeader } from "../utils/vtexId";
+
+// ---------------------------------------------------------------------------
+// Action
+// ---------------------------------------------------------------------------
+
+/**
+ * Cancel an order on behalf of the authenticated user.
+ * Hits POST /api/checkout/pub/orders/{orderId}/user-cancel-request
+ * on vtexcommercestable.com.br.
+ */
+export async function cancelOrder(
+  orderId: string,
+  reason: string,
+  authCookie?: string,
+): Promise<void> {
+  const headers: Record<string, string> = {};
+  if (authCookie) {
+    headers.Cookie = buildAuthCookieHeader(authCookie, getVtexConfig().account);
+  }
+
+  await vtexFetch<unknown>(
+    `/api/checkout/pub/orders/${orderId}/user-cancel-request`,
+    {
+      method: "POST",
+      body: JSON.stringify({ reason }),
+      headers,
+    },
+  );
+}

package/vtex/actions/profile.ts

@@ -0,0 +1,119 @@
+/**
+ * VTEX Profile update action (store-graphql).
+ * Ported from deco-cx/apps:
+ *   - vtex/actions/profile/updateProfile.ts
+ * @see https://developers.vtex.com/docs/guides/profile-system
+ */
+import { vtexFetch, getVtexConfig } from "../client";
+import { buildAuthCookieHeader } from "../utils/vtexId";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface ProfileInput {
+  firstName?: string;
+  lastName?: string;
+  birthDate?: string;
+  gender?: string;
+  homePhone?: string;
+  businessPhone?: string;
+  document?: string;
+  email: string;
+  tradeName?: string;
+  corporateName?: string;
+  corporateDocument?: string;
+  stateRegistration?: string;
+  isCorporate?: boolean;
+}
+
+export interface Profile {
+  cacheId: string;
+  firstName: string;
+  lastName: string;
+  birthDate: string;
+  gender: string;
+  homePhone: string;
+  businessPhone: string;
+  document: string;
+  email: string;
+  tradeName: string;
+  corporateName: string;
+  corporateDocument: string;
+  stateRegistration: string;
+  isCorporate: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// GraphQL helper (myvtex.com private graphql)
+// ---------------------------------------------------------------------------
+
+interface GqlResponse<T> {
+  data: T;
+  errors?: Array<{ message: string }>;
+}
+
+async function gql<T>(
+  query: string,
+  variables: Record<string, unknown>,
+  authCookie: string,
+): Promise<T> {
+  const { account } = getVtexConfig();
+  const result = await vtexFetch<GqlResponse<T>>(
+    `https://${account}.myvtex.com/_v/private/graphql/v1`,
+    {
+      method: "POST",
+      body: JSON.stringify({ query, variables }),
+      headers: { Cookie: buildAuthCookieHeader(authCookie, account) },
+    },
+  );
+  if (result.errors?.length) {
+    throw new Error(`GraphQL error: ${result.errors[0].message}`);
+  }
+  return result.data;
+}
+
+// ---------------------------------------------------------------------------
+// Mutation
+// ---------------------------------------------------------------------------
+
+const UPDATE_PROFILE = `mutation UpdateProfile($input: ProfileInput!) {
+  updateProfile(fields: $input) @context(provider: "vtex.store-graphql") {
+    cacheId
+    firstName
+    lastName
+    birthDate
+    gender
+    homePhone
+    businessPhone
+    document
+    email
+    tradeName
+    corporateName
+    corporateDocument
+    stateRegistration
+    isCorporate
+  }
+}`;
+
+// ---------------------------------------------------------------------------
+// Action
+// ---------------------------------------------------------------------------
+
+/**
+ * Update user profile.
+ * The original Deco action extracted `email` from the auth cookie payload.
+ * Here the caller must provide it explicitly.
+ */
+export async function updateProfile(
+  fields: Omit<ProfileInput, "email">,
+  email: string,
+  authCookie: string,
+): Promise<Profile> {
+  const { updateProfile: profile } = await gql<{ updateProfile: Profile }>(
+    UPDATE_PROFILE,
+    { input: { ...fields, email } },
+    authCookie,
+  );
+  return profile;
+}

package/vtex/actions/session.ts

@@ -0,0 +1,87 @@
+/**
+ * VTEX Sessions API actions.
+ * All session-mutating actions return Set-Cookie headers for propagation.
+ */
+import { vtexFetchWithCookies, vtexIOGraphQL, getVtexConfig } from "../client";
+import type { VtexFetchResult } from "../client";
+import { buildAuthCookieHeader } from "../utils/vtexId";
+
+// ---------------------------------------------------------------------------
+// createSession
+// ---------------------------------------------------------------------------
+
+export interface SessionData {
+  id: string;
+  namespaces: Record<string, Record<string, { value: string }>>;
+}
+
+export async function createSession(
+  data: Record<string, any>,
+  cookieHeader?: string,
+): Promise<VtexFetchResult<SessionData>> {
+  const headers: Record<string, string> = {};
+  if (cookieHeader) headers["cookie"] = cookieHeader;
+  return vtexFetchWithCookies<SessionData>("/api/sessions", {
+    method: "POST",
+    body: JSON.stringify(data),
+    headers,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// editSession
+// ---------------------------------------------------------------------------
+
+export interface EditSessionResponse {
+  id: string;
+  namespaces: Record<string, Record<string, { value: string }>>;
+}
+
+/**
+ * Edit the current VTEX session (public properties).
+ * Returns data + Set-Cookie headers.
+ */
+export async function editSession(
+  publicProperties: Record<string, { value: string }>,
+  cookieHeader?: string,
+): Promise<VtexFetchResult<EditSessionResponse>> {
+  const headers: Record<string, string> = {};
+  if (cookieHeader) headers["cookie"] = cookieHeader;
+
+  return vtexFetchWithCookies<EditSessionResponse>("/api/sessions", {
+    method: "PATCH",
+    body: JSON.stringify({ public: { ...publicProperties } }),
+    headers,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// deleteSession
+// ---------------------------------------------------------------------------
+
+export interface DeleteSessionResponse {
+  logOutFromSession: string;
+}
+
+const DELETE_SESSION_MUTATION = `mutation LogOutFromSession($sessionId: ID) {
+  logOutFromSession(sessionId: $sessionId) @context(provider: "vtex.store-graphql@2.x")
+}`;
+
+/**
+ * Log out / delete a VTEX session via the store-graphql mutation.
+ * Requires a valid auth cookie.
+ */
+export async function deleteSession(
+  sessionId: string,
+  authCookie: string,
+): Promise<DeleteSessionResponse> {
+  if (!authCookie) throw new Error("Auth cookie is required to delete session");
+  const { account } = getVtexConfig();
+  return vtexIOGraphQL<DeleteSessionResponse>(
+    {
+      query: DELETE_SESSION_MUTATION,
+      variables: { sessionId },
+    },
+    { cookie: buildAuthCookieHeader(authCookie, account) },
+  );
+}

package/vtex/actions/trigger.ts

@@ -0,0 +1,43 @@
+/**
+ * VTEX SKU change notification (trigger/webhook) types.
+ *
+ * Ported from `vtex/_to-port/actions/trigger.ts`.
+ * The original Deco action forwarded the payload to a Durable Object workflow.
+ * Actual webhook handling is framework-specific, so we only export the
+ * canonical payload interface and a handler signature type here.
+ */
+
+/** Payload sent by VTEX when a SKU changes in the catalog. */
+export interface VTEXNotificationPayload {
+  /** SKU ID in VTEX. */
+  IdSku: string;
+  /** Seller's account name in VTEX (visible in the store's Admin URL). */
+  An: string;
+  /** Affiliate ID generated automatically in the configuration. */
+  IdAffiliate: string;
+  /** Product ID in VTEX. */
+  ProductId: number;
+  /** Date when the item was updated. */
+  DateModified: string;
+  /**
+   * Whether the product is active. `false` means the product was
+   * deactivated and should be blocked / zeroed in the marketplace.
+   */
+  IsActive: boolean;
+  /** Inventory level has changed -- run a Fulfillment Simulation to refresh. */
+  StockModified: boolean;
+  /** Price has changed -- run a Fulfillment Simulation to refresh. */
+  PriceModified: boolean;
+  /** Product/SKU registration data changed (name, description, weight, etc.). */
+  HasStockKeepingUnitModified: boolean;
+  /** Product is no longer associated with the trade policy. */
+  HasStockKeepingUnitRemovedFromAffiliate: boolean;
+}
+
+/**
+ * Generic handler signature for the VTEX trigger webhook.
+ * Implement this in your framework layer (e.g. TanStack Start API route).
+ */
+export type VTEXTriggerHandler = (
+  payload: VTEXNotificationPayload,
+) => Promise<{ id: string } | void>;