astro-tractstack 2.3.0 → 2.3.1

package/templates/src/stores/shopify.ts

@@ -53,6 +53,11 @@ export interface ShopifyProduct {
   variants: ShopifyVariant[];
 }
 
+export interface ShopifyPageInfo {
+  hasNextPage: boolean;
+  endCursor: string;
+}
+
 export type CartActionType = 'add' | 'remove';
 
 export interface CartAction {
@@ -90,30 +95,23 @@ export const CART_STATES = {
   LOADED: 'LOADED',
   CHECKOUT: 'CHECKOUT',
   BOOKING: 'BOOKING',
-  BOOKED: 'BOOKED',
   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 = persistentAtom<{
+export const shopifyData = atom<{
   products: ShopifyProduct[];
+  pageInfo?: ShopifyPageInfo;
   lastFetched: number;
-}>(
-  'tractstack_shopify_data',
-  {
-    products: [],
-    lastFetched: 0,
-  },
-  {
-    encode: JSON.stringify,
-    decode: JSON.parse,
-  }
-);
+}>({
+  products: [],
+  lastFetched: 0,
+});
 
-// Non-persistent Status (Load states should reset on refresh)
 export const shopifyStatus = map<{
   isLoading: boolean;
   error: string | null;
@@ -131,9 +129,7 @@ export const addQueue = persistentAtom<CartAction[]>(
   }
 );
 
-// We use a backing persistentAtom for the cart to ensure data survives reloads,
-// but expose it as a 'map' to preserve the .setKey() API used by consumers.
-const cartPersistence = persistentAtom<Record<string, CartItemState>>(
+export const cartPersistence = persistentAtom<Record<string, CartItemState>>(
   'tractstack_shopify_cart',
   {},
   {
@@ -147,10 +143,8 @@ export const cartStore = map<Record<string, CartItemState>>(
 );
 
 onMount(cartStore, () => {
-  // Sync initial state from persistence (in case of race conditions or hydration delay)
   cartStore.set(cartPersistence.get());
 
-  // Persist any changes made to the map
   const unbind = cartStore.listen((value) => {
     cartPersistence.set(value);
   });
@@ -167,11 +161,29 @@ export const cartState = persistentAtom<CartState>(
   CART_STATES.INIT
 );
 
-export async function fetchShopifyProducts() {
+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 response = await fetch('/api/shopify/getProducts');
+    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) {
@@ -179,12 +191,17 @@ export async function fetchShopifyProducts() {
     }
 
     shopifyData.set({
-      products: result.products,
+      products: result.products || [],
+      pageInfo: result.pageInfo,
       lastFetched: Date.now(),
     });
 
     shopifyStatus.set({ isLoading: false, error: null });
-  } catch (error) {
+  } catch (error: unknown) {
+    if (error instanceof DOMException && error.name === 'AbortError') {
+      return;
+    }
+
     console.error('Shopify fetch failed:', error);
     shopifyStatus.set({
       isLoading: false,
@@ -194,17 +211,56 @@ export async function fetchShopifyProducts() {
   }
 }
 
-export const customerDetails = persistentAtom<{
+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;
@@ -184,8 +197,12 @@ export interface BrandConfig {
   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 {
@@ -220,8 +237,10 @@ export interface BrandConfigState {
   designLibrary?: DesignLibraryConfig;
   hasAAI: boolean;
   hasShopify: boolean;
+  showShopifyHelper: boolean;
   hasResend: boolean;
   hasHydrationToken: boolean;
+  scheduling: SchedulingConfig;
 }
 
 // Form validation types
@@ -261,6 +280,8 @@ export interface AdvancedConfigStatus {
   shopifyApiVersion: string;
   shopifyStoreDomainSet: boolean;
   resendApiKeySet: boolean;
+  shopifyAdminSlugSet: boolean;
+  userSetupWebhooks: boolean;
 }
 
 export interface AdvancedConfigState {
@@ -274,6 +295,8 @@ export interface AdvancedConfigState {
   shopifyApiSecret: string;
   shopifyApiVersion: string;
   shopifyStoreDomain: string;
+  shopifyAdminSlug: string;
+  userSetupWebhooks: boolean;
   resendApiKey: string;
 }
 
@@ -289,6 +312,8 @@ export interface AdvancedConfigUpdateRequest {
   SHOPIFY_API_SECRET?: string;
   SHOPIFY_API_VERSION?: string;
   SHOPIFY_STORE_DOMAIN?: string;
+  SHOPIFY_ADMIN_SLUG?: string;
+  USER_SETUP_WEBHOOKS?: boolean;
   RESEND_API_KEY?: string;
 }
 
@@ -490,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

@@ -32,6 +32,8 @@ export async function getAdvancedConfigStatus(
       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

@@ -25,6 +25,8 @@ export function convertToLocalState(
       shopifyApiVersion: '',
       shopifyStoreDomain: '',
       resendApiKey: '',
+      shopifyAdminSlug: '',
+      userSetupWebhooks: false,
     };
   }
 
@@ -43,6 +45,8 @@ export function convertToLocalState(
     shopifyApiVersion: status.shopifyApiVersion || '',
     shopifyStoreDomain: '',
     resendApiKey: '',
+    shopifyAdminSlug: '',
+    userSetupWebhooks: status.userSetupWebhooks,
   };
 }
 
@@ -92,6 +96,14 @@ export function convertToBackendFormat(
     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();
   }
@@ -107,7 +119,6 @@ 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) {
@@ -125,7 +136,6 @@ export function validateAdvancedConfig(
     }
   }
 
-  // Shopify store domain validation
   if (state.shopifyStoreDomain?.trim()) {
     const domainPattern = /^[a-zA-Z0-9-]+\.myshopify\.com$/;
     if (!domainPattern.test(state.shopifyStoreDomain.trim())) {
@@ -141,7 +151,34 @@ export function validateAdvancedConfig(
     }
   }
 
-  // Password strength validation (optional but recommended)
+  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';

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

@@ -41,8 +41,16 @@ export function convertToLocalState(
     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: [],
+    },
   };
 }
 
@@ -75,7 +83,9 @@ export function convertToBackendFormat(
     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,

package/templates/src/utils/auth.ts

@@ -11,20 +11,30 @@ export interface AdminAuthClaims {
   exp: number;
 }
 
+/**
+ * Helper to get the current expected tenant ID from the Astro context
+ */
+function getExpectedTenantId(astro: any): string {
+  return (
+    astro.locals?.tenant?.id || import.meta.env.PUBLIC_TENANTID || 'default'
+  );
+}
+
 /**
  * Check if user is authenticated (either admin or editor)
  */
 export function isAuthenticated(astro: any): boolean {
+  const expectedTenantId = getExpectedTenantId(astro);
   const adminCookie = astro.cookies.get('admin_auth');
   const editorCookie = astro.cookies.get('editor_auth');
 
   if (adminCookie?.value) {
-    const claims = validateAdminToken(adminCookie.value);
+    const claims = validateAdminToken(adminCookie.value, expectedTenantId);
     if (claims && claims.role === 'admin') return true;
   }
 
   if (editorCookie?.value) {
-    const claims = validateAdminToken(editorCookie.value);
+    const claims = validateAdminToken(editorCookie.value, expectedTenantId);
     if (claims && claims.role === 'editor') return true;
   }
 
@@ -35,10 +45,11 @@ export function isAuthenticated(astro: any): boolean {
  * Check if user has admin role
  */
 export function isAdmin(astro: any): boolean {
+  const expectedTenantId = getExpectedTenantId(astro);
   const adminCookie = astro.cookies.get('admin_auth');
   if (!adminCookie?.value) return false;
 
-  const claims = validateAdminToken(adminCookie.value);
+  const claims = validateAdminToken(adminCookie.value, expectedTenantId);
   return claims?.role === 'admin';
 }
 
@@ -46,10 +57,11 @@ export function isAdmin(astro: any): boolean {
  * Check if user has editor role
  */
 export function isEditor(astro: any): boolean {
+  const expectedTenantId = getExpectedTenantId(astro);
   const editorCookie = astro.cookies.get('editor_auth');
   if (!editorCookie?.value) return false;
 
-  const claims = validateAdminToken(editorCookie.value);
+  const claims = validateAdminToken(editorCookie.value, expectedTenantId);
   return claims?.role === 'editor';
 }
 
@@ -57,15 +69,16 @@ export function isEditor(astro: any): boolean {
  * Get user role (admin, editor, or null)
  */
 export function getUserRole(astro: any): 'admin' | 'editor' | null {
+  const expectedTenantId = getExpectedTenantId(astro);
   const adminCookie = astro.cookies.get('admin_auth');
   if (adminCookie?.value) {
-    const claims = validateAdminToken(adminCookie.value);
+    const claims = validateAdminToken(adminCookie.value, expectedTenantId);
     if (claims?.role === 'admin') return 'admin';
   }
 
   const editorCookie = astro.cookies.get('editor_auth');
   if (editorCookie?.value) {
-    const claims = validateAdminToken(editorCookie.value);
+    const claims = validateAdminToken(editorCookie.value, expectedTenantId);
     if (claims?.role === 'editor') return 'editor';
   }
 
@@ -110,15 +123,16 @@ export function requireAdminOrEditor(astro: any): Response | undefined {
  * Returns the JWT token from the appropriate cookie
  */
 export function getAdminToken(astro: any): string | null {
+  const expectedTenantId = getExpectedTenantId(astro);
   const adminCookie = astro.cookies.get('admin_auth');
   if (adminCookie?.value) {
-    const claims = validateAdminToken(adminCookie.value);
+    const claims = validateAdminToken(adminCookie.value, expectedTenantId);
     if (claims?.role === 'admin') return adminCookie.value;
   }
 
   const editorCookie = astro.cookies.get('editor_auth');
   if (editorCookie?.value) {
-    const claims = validateAdminToken(editorCookie.value);
+    const claims = validateAdminToken(editorCookie.value, expectedTenantId);
     if (claims?.role === 'editor') return editorCookie.value;
   }
 
@@ -130,7 +144,10 @@ export function getAdminToken(astro: any): string | null {
  * Note: This is a simplified client-side validation
  * Real validation happens on the backend
  */
-function validateAdminToken(token: string): AdminAuthClaims | null {
+function validateAdminToken(
+  token: string,
+  expectedTenantId: string
+): AdminAuthClaims | null {
   try {
     // Split JWT token
     const parts = token.split('.');
@@ -146,6 +163,9 @@ function validateAdminToken(token: string): AdminAuthClaims | null {
     if (!claims.role || !['admin', 'editor'].includes(claims.role)) return null;
     if (Date.now() / 1000 > claims.exp) return null; // Token expired
 
+    // Tenant validation
+    if (claims.tenantId !== expectedTenantId) return null; // Must match current environment
+
     return claims;
   } catch {
     return null;

package/templates/src/utils/compositor/aiGeneration.ts

@@ -10,7 +10,7 @@ interface AiGenerationOptions {
   temperature?: number;
 }
 
-export const callAskLemurAPI = async ({
+export const callAaiAPI = async ({
   prompt,
   context,
   expectJson,
@@ -43,7 +43,7 @@ export const callAskLemurAPI = async ({
         'X-Sandbox-Token': token || '',
       },
       credentials: 'include',
-      body: JSON.stringify({ action: 'askLemur', payload: requestBody }),
+      body: JSON.stringify({ action: 'aai', payload: requestBody }),
     });
 
     if (!response.ok) {
@@ -58,7 +58,7 @@ export const callAskLemurAPI = async ({
     resultData = json.data;
   } else {
     const api = new TractStackAPI(tenantId);
-    const response = await api.post('/api/v1/aai/askLemur', requestBody);
+    const response = await api.post('/api/v1/aai/aai', requestBody);
 
     if (!response.success) {
       throw new Error(

package/templates/src/utils/compositor/aiPaneParser.ts

@@ -771,11 +771,11 @@ export function createDefaultShell(layout: 'standard' | 'grid'): ShellJson {
       mobile: 'mb-2',
     },
     a: {
-      mobile: 'text-indigo-600 hover:text-indigo-500 font-semibold',
+      mobile: 'text-cyan-600 hover:text-cyan-500 font-bold',
     },
     button: {
       mobile:
-        'rounded-md bg-indigo-600 px-3.5 py-2.5 text-sm font-semibold text-white shadow-sm hover:bg-indigo-500 focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-indigo-600',
+        'rounded-md bg-cyan-600 px-3.5 py-2.5 text-sm font-bold text-white shadow-sm hover:bg-cyan-500 focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-cyan-600',
     },
   };