astro-tractstack 2.2.10 → 2.3.1

package/templates/src/stores/shopify.ts

@@ -0,0 +1,266 @@
+import { atom, map, onMount } from 'nanostores';
+import { persistentAtom } from '@nanostores/persistent';
+
+export interface ShopifyVariant {
+  id: string;
+  title: string;
+  price: {
+    amount: string;
+    currencyCode: string;
+  };
+  compareAtPrice?: {
+    amount: string;
+    currencyCode: string;
+  };
+  sku?: string;
+  availableForSale: boolean;
+  requiresShipping: boolean;
+  selectedOptions: {
+    name: string;
+    value: string;
+  }[];
+}
+
+export const modalState = atom<{
+  isOpen: boolean;
+  type: 'success' | 'restriction';
+  title: string;
+  message: string;
+}>({
+  isOpen: false,
+  type: 'success',
+  title: '',
+  message: '',
+});
+
+export interface ShopifyOption {
+  name: string;
+  values: string[];
+}
+
+export interface ShopifyImage {
+  url: string;
+  altText?: string;
+}
+
+export interface ShopifyProduct {
+  id: string;
+  title: string;
+  handle: string;
+  description: string;
+  options: ShopifyOption[];
+  images: ShopifyImage[];
+  variants: ShopifyVariant[];
+}
+
+export interface ShopifyPageInfo {
+  hasNextPage: boolean;
+  endCursor: string;
+}
+
+export type CartActionType = 'add' | 'remove';
+
+export interface CartAction {
+  resourceId: string;
+  gid?: string;
+  variantId?: string;
+  variantIdShipped?: string;
+  variantIdPickup?: string;
+  boundResourceId?: string;
+  action: CartActionType;
+  suppressModal?: boolean;
+}
+
+export interface CartItemState {
+  resourceId: string;
+  quantity: number;
+  variantId?: string;
+  gid?: string;
+  variantIdShipped?: string;
+  variantIdPickup?: string;
+  boundResourceId?: string;
+}
+
+export const QUEUE_STATES = {
+  READY: 'READY',
+  ADDING: 'ADDING',
+  HAS_REQUIREMENTS: 'HAS_REQUIREMENTS',
+} as const;
+
+export type QueueState = (typeof QUEUE_STATES)[keyof typeof QUEUE_STATES];
+
+export const CART_STATES = {
+  INIT: 'INIT',
+  READY: 'READY',
+  LOADED: 'LOADED',
+  CHECKOUT: 'CHECKOUT',
+  BOOKING: 'BOOKING',
+  SHOPIFY_HANDOFF: 'SHOPIFY_HANDOFF',
+} as const;
+
+export type CartState = (typeof CART_STATES)[keyof typeof CART_STATES];
+
+export const isShopifyHandoff = atom<boolean>(false);
+export const shopifyActiveTabStore = atom<string>('dashboards');
+
+export const shopifyData = atom<{
+  products: ShopifyProduct[];
+  pageInfo?: ShopifyPageInfo;
+  lastFetched: number;
+}>({
+  products: [],
+  lastFetched: 0,
+});
+
+export const shopifyStatus = map<{
+  isLoading: boolean;
+  error: string | null;
+}>({
+  isLoading: false,
+  error: null,
+});
+
+export const addQueue = persistentAtom<CartAction[]>(
+  'tractstack_shopify_queue',
+  [],
+  {
+    encode: JSON.stringify,
+    decode: JSON.parse,
+  }
+);
+
+export const cartPersistence = persistentAtom<Record<string, CartItemState>>(
+  'tractstack_shopify_cart',
+  {},
+  {
+    encode: JSON.stringify,
+    decode: JSON.parse,
+  }
+);
+
+export const cartStore = map<Record<string, CartItemState>>(
+  cartPersistence.get()
+);
+
+onMount(cartStore, () => {
+  cartStore.set(cartPersistence.get());
+
+  const unbind = cartStore.listen((value) => {
+    cartPersistence.set(value);
+  });
+
+  return () => unbind();
+});
+
+export const queueState = persistentAtom<QueueState>(
+  'tractstack_shopify_queue_state',
+  QUEUE_STATES.READY
+);
+export const cartState = persistentAtom<CartState>(
+  'tractstack_shopify_cart_state',
+  CART_STATES.INIT
+);
+
+let currentAbortController: AbortController | null = null;
+
+export async function fetchShopifyProducts(
+  q: string = '',
+  cursor: string | null = null
+) {
+  if (currentAbortController) {
+    currentAbortController.abort();
+  }
+  currentAbortController = new AbortController();
+  const signal = currentAbortController.signal;
+
+  shopifyStatus.set({ isLoading: true, error: null });
+
+  try {
+    const params = new URLSearchParams();
+    if (q) params.set('q', q);
+    if (cursor) params.set('cursor', cursor);
+
+    const queryString = params.toString();
+    const url = `/api/shopify/getProducts${queryString ? `?${queryString}` : ''}`;
+
+    const response = await fetch(url, { signal });
+    const result = await response.json();
+
+    if (!response.ok) {
+      throw new Error(result.error || 'Failed to fetch products');
+    }
+
+    shopifyData.set({
+      products: result.products || [],
+      pageInfo: result.pageInfo,
+      lastFetched: Date.now(),
+    });
+
+    shopifyStatus.set({ isLoading: false, error: null });
+  } catch (error: unknown) {
+    if (error instanceof DOMException && error.name === 'AbortError') {
+      return;
+    }
+
+    console.error('Shopify fetch failed:', error);
+    shopifyStatus.set({
+      isLoading: false,
+      error:
+        error instanceof Error ? error.message : 'Failed to fetch products',
+    });
+  }
+}
+
+export function clearShopifySearch() {
+  if (currentAbortController) {
+    currentAbortController.abort();
+  }
+  shopifyData.set({
+    products: [],
+    pageInfo: undefined,
+    lastFetched: 0,
+  });
+  shopifyStatus.set({ isLoading: false, error: null });
+}
+
+export const transactionTraceId = persistentAtom<string>(
+  'tractstack_shopify_trace_id',
+  ''
+);
+
+export interface CustomerDetails {
+  name: string;
+  email: string;
+  leadId: string;
+}
+
+export const customerDetails = persistentAtom<CustomerDetails>(
+  'tractstack_shopify_customer',
+  {
+    name: '',
+    email: '',
+    leadId: '',
+  },
+  {
+    encode: JSON.stringify,
+    decode: JSON.parse,
+  }
+);
+
+export function setCustomerDetails(details: Partial<CustomerDetails>) {
+  customerDetails.set({
+    ...customerDetails.get(),
+    ...details,
+  });
+}
+
+export function clearCommerceState() {
+  cartStore.set({});
+  customerDetails.set({
+    name: '',
+    email: '',
+    leadId: '',
+  });
+  transactionTraceId.set('');
+  cartState.set(CART_STATES.READY);
+}

package/templates/src/types/tractstack.ts

@@ -152,6 +152,19 @@ export interface FullContentMapItem {
   scale?: string;
 }
 
+export interface TimeBlock {
+  start: string; // "09:00" for business hours or ISO-8601 for unavailable blocks
+  end: string;
+}
+
+export interface SchedulingConfig {
+  timezone: string;
+  bufferGapsMinutes: number;
+  maxLengthMinutes: number;
+  businessHours: Record<string, TimeBlock>;
+  unavailableHours: TimeBlock[];
+}
+
 export interface BrandConfig {
   TENANT_ID: string;
   SITE_INIT?: boolean;
@@ -183,7 +196,13 @@ export interface BrandConfig {
   KNOWN_RESOURCES?: KnownResourcesConfig;
   DESIGN_LIBRARY?: DesignLibraryConfig;
   HAS_AAI?: boolean;
+  HAS_SHOPIFY?: boolean;
+  SHOW_SHOPIFY_HELPER?: boolean;
+  SHOPIFY_ADMIN_SLUG?: string;
+  USER_SETUP_WEBHOOKS?: boolean;
+  HAS_RESEND?: boolean;
   HAS_HYDRATION_TOKEN?: boolean;
+  SCHEDULING?: SchedulingConfig;
 }
 
 export interface BrandConfigState {
@@ -217,7 +236,11 @@ export interface BrandConfigState {
   knownResources: KnownResourcesConfig;
   designLibrary?: DesignLibraryConfig;
   hasAAI: boolean;
+  hasShopify: boolean;
+  showShopifyHelper: boolean;
+  hasResend: boolean;
   hasHydrationToken: boolean;
+  scheduling: SchedulingConfig;
 }
 
 // Form validation types
@@ -251,6 +274,14 @@ export interface AdvancedConfigStatus {
   editorPasswordSet: boolean;
   aaiAPIKeySet: boolean;
   tursoEnabled: boolean;
+  shopifyStorefrontTokenSet: boolean;
+  shopifyAdminApiKeySet: boolean;
+  shopifyApiSecretSet: boolean;
+  shopifyApiVersion: string;
+  shopifyStoreDomainSet: boolean;
+  resendApiKeySet: boolean;
+  shopifyAdminSlugSet: boolean;
+  userSetupWebhooks: boolean;
 }
 
 export interface AdvancedConfigState {
@@ -259,6 +290,14 @@ export interface AdvancedConfigState {
   adminPassword: string;
   editorPassword: string;
   aaiApiKey: string;
+  shopifyStorefrontToken: string;
+  shopifyAdminApiKey: string;
+  shopifyApiSecret: string;
+  shopifyApiVersion: string;
+  shopifyStoreDomain: string;
+  shopifyAdminSlug: string;
+  userSetupWebhooks: boolean;
+  resendApiKey: string;
 }
 
 export interface AdvancedConfigUpdateRequest {
@@ -269,6 +308,13 @@ export interface AdvancedConfigUpdateRequest {
   AAI_API_KEY?: string;
   HOME_SLUG?: string;
   TRACTSTACK_HOME_SLUG?: string;
+  SHOPIFY_STOREFRONT_TOKEN?: string;
+  SHOPIFY_API_SECRET?: string;
+  SHOPIFY_API_VERSION?: string;
+  SHOPIFY_STORE_DOMAIN?: string;
+  SHOPIFY_ADMIN_SLUG?: string;
+  USER_SETUP_WEBHOOKS?: boolean;
+  RESEND_API_KEY?: string;
 }
 
 export interface MenuNodeState {
@@ -469,3 +515,32 @@ export interface CategorizedResults {
   contextPaneResults: FTSResult[];
   resourceResults: FTSResult[];
 }
+
+export type BookingStatus = 'PENDING' | 'CONFIRMED' | 'CANCELLED';
+
+export interface BookingEntity {
+  id: string; // traceId
+  resourceIds: string[];
+  leadId: string;
+  startTime: string; // ISO-8601 UTC string
+  endTime: string; // ISO-8601 UTC string
+  status: BookingStatus;
+  shopifyOrderId?: string;
+  createdAt: string; // ISO-8601 UTC string
+  leadEmail?: string;
+  leadName?: string;
+}
+
+export interface BookingListResponse {
+  data: BookingEntity[];
+  totalCount: number;
+}
+
+export interface BookingMetricsResponse {
+  totalMonthlyConfirmed: number;
+  totalAnnualConfirmed: number;
+  totalWeeklyConfirmed: number;
+  leadConversionAnchor: number;
+  pendingLast24h: number;
+  confirmedLast24h: number;
+}

package/templates/src/utils/api/advancedConfig.ts

@@ -28,7 +28,13 @@ export async function getAdvancedConfigStatus(
       typeof data.tursoTokenSet !== 'boolean' ||
       typeof data.adminPasswordSet !== 'boolean' ||
       typeof data.editorPasswordSet !== 'boolean' ||
-      typeof data.aaiAPIKeySet !== 'boolean'
+      typeof data.aaiAPIKeySet !== 'boolean' ||
+      typeof data.shopifyStorefrontTokenSet !== 'boolean' ||
+      typeof data.shopifyApiSecretSet !== 'boolean' ||
+      typeof data.shopifyStoreDomainSet !== 'boolean' ||
+      typeof data.shopifyAdminSlugSet !== 'boolean' ||
+      typeof data.userSetupWebhooks !== 'boolean' ||
+      typeof data.resendApiKeySet !== 'boolean'
     ) {
       throw new Error('Invalid response format from server');
     }

package/templates/src/utils/api/advancedHelpers.ts

@@ -19,6 +19,14 @@ export function convertToLocalState(
       adminPassword: '',
       editorPassword: '',
       aaiApiKey: '',
+      shopifyStorefrontToken: '',
+      shopifyAdminApiKey: '',
+      shopifyApiSecret: '',
+      shopifyApiVersion: '',
+      shopifyStoreDomain: '',
+      resendApiKey: '',
+      shopifyAdminSlug: '',
+      userSetupWebhooks: false,
     };
   }
 
@@ -31,6 +39,14 @@ export function convertToLocalState(
     adminPassword: '',
     editorPassword: '',
     aaiApiKey: '',
+    shopifyStorefrontToken: '',
+    shopifyAdminApiKey: '',
+    shopifyApiSecret: '',
+    shopifyApiVersion: status.shopifyApiVersion || '',
+    shopifyStoreDomain: '',
+    resendApiKey: '',
+    shopifyAdminSlug: '',
+    userSetupWebhooks: status.userSetupWebhooks,
   };
 }
 
@@ -64,6 +80,34 @@ export function convertToBackendFormat(
     request.AAI_API_KEY = state.aaiApiKey.trim();
   }
 
+  if (state.shopifyStorefrontToken?.trim()) {
+    request.SHOPIFY_STOREFRONT_TOKEN = state.shopifyStorefrontToken.trim();
+  }
+
+  if (state.shopifyApiSecret?.trim()) {
+    request.SHOPIFY_API_SECRET = state.shopifyApiSecret.trim();
+  }
+
+  if (state.shopifyApiVersion?.trim()) {
+    request.SHOPIFY_API_VERSION = state.shopifyApiVersion.trim();
+  }
+
+  if (state.shopifyStoreDomain?.trim()) {
+    request.SHOPIFY_STORE_DOMAIN = state.shopifyStoreDomain.trim();
+  }
+
+  if (state.shopifyAdminSlug?.trim()) {
+    request.SHOPIFY_ADMIN_SLUG = state.shopifyAdminSlug.trim();
+  }
+
+  if (state.userSetupWebhooks !== undefined) {
+    request.USER_SETUP_WEBHOOKS = state.userSetupWebhooks;
+  }
+
+  if (state.resendApiKey?.trim()) {
+    request.RESEND_API_KEY = state.resendApiKey.trim();
+  }
+
   return request;
 }
 
@@ -75,21 +119,16 @@ export function validateAdvancedConfig(
 ): FieldErrors {
   const errors: FieldErrors = {};
 
-  // Turso validation: both URL and token must be provided together
   const hasTursoUrl = Boolean(state.tursoUrl?.trim());
   const hasTursoToken = Boolean(state.tursoToken?.trim());
-
   if (hasTursoUrl && !hasTursoToken) {
     errors.tursoToken =
       'Turso Auth Token is required when Turso URL is provided';
   }
-
   if (hasTursoToken && !hasTursoUrl) {
     errors.tursoUrl =
       'Turso Database URL is required when Turso Token is provided';
   }
-
-  // Basic URL validation for Turso
   if (hasTursoUrl && state.tursoUrl) {
     const urlPattern = /^libsql:\/\/.+/;
     if (!urlPattern.test(state.tursoUrl.trim())) {
@@ -97,12 +136,53 @@ export function validateAdvancedConfig(
     }
   }
 
-  // Password strength validation (optional but recommended)
+  if (state.shopifyStoreDomain?.trim()) {
+    const domainPattern = /^[a-zA-Z0-9-]+\.myshopify\.com$/;
+    if (!domainPattern.test(state.shopifyStoreDomain.trim())) {
+      errors.shopifyStoreDomain =
+        'Store domain must be in the format "your-shop.myshopify.com"';
+    }
+  }
+
+  if (state.shopifyApiVersion?.trim()) {
+    if (!/^\d{4}-\d{2}$/.test(state.shopifyApiVersion.trim())) {
+      errors.shopifyApiVersion =
+        'Version must match YYYY-MM format (e.g. 2026-01)';
+    }
+  }
+
+  if (state.shopifyAdminSlug?.trim()) {
+    if (
+      state.shopifyAdminSlug.includes('/') ||
+      state.shopifyAdminSlug.includes('.')
+    ) {
+      errors.shopifyAdminSlug =
+        'Please enter only the store slug, not the full URL';
+    }
+  }
+
+  const isConfiguringShopify = Boolean(
+    state.shopifyStoreDomain?.trim() ||
+    state.shopifyStorefrontToken?.trim() ||
+    state.shopifyApiSecret?.trim() ||
+    state.shopifyAdminSlug?.trim()
+  );
+
+  if (isConfiguringShopify) {
+    if (!state.shopifyAdminSlug?.trim()) {
+      errors.shopifyAdminSlug =
+        'Admin slug is required to generate webhook links.';
+    }
+    if (!state.userSetupWebhooks) {
+      errors.userSetupWebhooks =
+        'You must confirm webhooks are configured to ensure synchronization.';
+    }
+  }
+
   if (state.adminPassword && state.adminPassword.length < 8) {
     errors.adminPassword =
       'Admin password should be at least 8 characters long';
   }
-
   if (state.editorPassword && state.editorPassword.length < 8) {
     errors.editorPassword =
       'Editor password should be at least 8 characters long';

package/templates/src/utils/api/bookingHelpers.ts

@@ -0,0 +1,125 @@
+import { customerDetails } from '@/stores/shopify';
+
+export const bookingHelpers = {
+  /**
+   * Checks if a user profile already exists for a given email via the BFF.
+   */
+  lookupLead: async (email: string) => {
+    const response = await fetch('/api/auth/lookup-lead', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({ email }),
+    });
+    return await response.json();
+  },
+
+  /**
+   * Asks backend for availability slots
+   */
+  getAvailability: async (start: string, end: string) => {
+    const query = new URLSearchParams({
+      start,
+      end,
+    });
+    const response = await fetch(
+      `/api/booking/availability?${query.toString()}`
+    );
+    return await response.json();
+  },
+
+  /**
+   * Places a temporary hold on a specific slot for the manifest of services and pickup products.
+   */
+  holdSlot: async (
+    traceId: string,
+    startTime: string,
+    endTime: string,
+    resourceIds: string[]
+  ) => {
+    const details = customerDetails.get();
+
+    const response = await fetch('/api/booking/hold', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        traceId,
+        leadId: details.leadId,
+        resourceIds,
+        startTime,
+        endTime,
+      }),
+    });
+    return await response.json();
+  },
+
+  /**
+   * Releases a temporary hold, typically used when a user abandons checkout.
+   */
+  releaseHold: async (traceId: string) => {
+    const response = await fetch('/api/booking/release', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({ traceId }),
+    });
+    return await response.json();
+  },
+
+  /**
+   * Confirms a pending hold, finalizing the booking for free services.
+   */
+  confirmBooking: async (traceId: string) => {
+    const response = await fetch('/api/booking/confirm', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({ traceId }),
+    });
+    return await response.json();
+  },
+
+  /**
+   * Retrieves a paginated list of all bookings for the administrative dashboard.
+   */
+  listBookings: async (
+    limit: number = 50,
+    offset: number = 0,
+    status: string = 'ALL'
+  ) => {
+    const query = new URLSearchParams({
+      limit: limit.toString(),
+      offset: offset.toString(),
+      status,
+    });
+    const response = await fetch(`/api/booking/list?${query.toString()}`);
+    return await response.json();
+  },
+
+  /**
+   * Retrieves aggregated booking volume and conversion statistics.
+   */
+  getMetrics: async () => {
+    const response = await fetch('/api/booking/metrics');
+    return await response.json();
+  },
+
+  /**
+   * Manually cancels an existing booking from the administrative dashboard.
+   */
+  cancelBooking: async (traceId: string) => {
+    const response = await fetch('/api/booking/cancel', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({ traceId }),
+    });
+    return await response.json();
+  },
+};

package/templates/src/utils/api/brandHelpers.ts

@@ -40,7 +40,17 @@ export function convertToLocalState(
     knownResources: brandConfig.KNOWN_RESOURCES ?? {},
     designLibrary: brandConfig.DESIGN_LIBRARY ?? undefined,
     hasAAI: brandConfig.HAS_AAI ?? false,
+    hasShopify: brandConfig.HAS_SHOPIFY ?? false,
+    showShopifyHelper: brandConfig.SHOW_SHOPIFY_HELPER ?? false,
+    hasResend: brandConfig.HAS_RESEND ?? false,
     hasHydrationToken: brandConfig.HAS_HYDRATION_TOKEN ?? false,
+    scheduling: brandConfig.SCHEDULING ?? {
+      timezone: 'UTC',
+      bufferGapsMinutes: 15,
+      maxLengthMinutes: 0,
+      businessHours: {},
+      unavailableHours: [],
+    },
   };
 }
 
@@ -72,6 +82,10 @@ export function convertToBackendFormat(
     KNOWN_RESOURCES: localState.knownResources,
     DESIGN_LIBRARY: localState.designLibrary,
     HAS_AAI: localState.hasAAI,
+    HAS_SHOPIFY: localState.hasShopify,
+    SHOW_SHOPIFY_HELPER: localState.showShopifyHelper,
+    HAS_RESEND: localState.hasResend,
+    SCHEDULING: localState.scheduling,
 
     // ALWAYS send asset paths (current state)
     LOGO: localState.logo,