astro-tractstack 2.3.0 → 2.3.2

package/templates/src/types/tractstack.ts

@@ -1,3 +1,4 @@
+import type { CSSProperties, ReactNode } from 'react';
 import type { StoragePane } from './compositorTypes';
 
 export type DesignLibraryEntry = {
@@ -13,7 +14,7 @@ export type DesignLibraryConfig = DesignLibraryEntry[];
 
 export interface BaseComponentProps {
   class?: string;
-  style?: React.CSSProperties | string;
+  style?: CSSProperties | string;
   id?: string;
 }
 
@@ -74,7 +75,7 @@ export interface FragmentProps
   eager?: boolean;
 
   /** Fallback content while loading */
-  fallback?: React.ReactNode;
+  fallback?: ReactNode;
 }
 
 // Utility type for extracting props from Astro components
@@ -152,6 +153,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 +198,13 @@ 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;
+  ADMIN_EMAIL?: string;
 }
 
 export interface BrandConfigState {
@@ -220,8 +239,11 @@ export interface BrandConfigState {
   designLibrary?: DesignLibraryConfig;
   hasAAI: boolean;
   hasShopify: boolean;
+  showShopifyHelper: boolean;
   hasResend: boolean;
   hasHydrationToken: boolean;
+  scheduling: SchedulingConfig;
+  adminEmail: string;
 }
 
 // Form validation types
@@ -261,6 +283,8 @@ export interface AdvancedConfigStatus {
   shopifyApiVersion: string;
   shopifyStoreDomainSet: boolean;
   resendApiKeySet: boolean;
+  shopifyAdminSlugSet: boolean;
+  userSetupWebhooks: boolean;
 }
 
 export interface AdvancedConfigState {
@@ -274,6 +298,8 @@ export interface AdvancedConfigState {
   shopifyApiSecret: string;
   shopifyApiVersion: string;
   shopifyStoreDomain: string;
+  shopifyAdminSlug: string;
+  userSetupWebhooks: boolean;
   resendApiKey: string;
 }
 
@@ -289,6 +315,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 +518,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/brandConfig.ts

@@ -66,6 +66,7 @@ export async function getBrandConfig(tenantId: string): Promise<BrandConfig> {
           KNOWN_RESOURCES: {},
           DESIGN_LIBRARY: [],
           HAS_AAI: false,
+          ADMIN_EMAIL: '',
         } as BrandConfig;
       }
       throw new Error(response.error || 'Failed to get brand configuration');
@@ -100,6 +101,7 @@ export async function getBrandConfig(tenantId: string): Promise<BrandConfig> {
         KNOWN_RESOURCES: {},
         DESIGN_LIBRARY: [],
         HAS_AAI: false,
+        ADMIN_EMAIL: '',
       } as BrandConfig;
     }
     throw error;

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

@@ -41,8 +41,17 @@ 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,
+    adminEmail: brandConfig.ADMIN_EMAIL ?? '',
+    scheduling: brandConfig.SCHEDULING ?? {
+      timezone: 'UTC',
+      bufferGapsMinutes: 15,
+      maxLengthMinutes: 0,
+      businessHours: {},
+      unavailableHours: [],
+    },
   };
 }
 
@@ -75,7 +84,10 @@ 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,
+    ADMIN_EMAIL: localState.adminEmail,
 
     // ALWAYS send asset paths (current state)
     LOGO: localState.logo,
@@ -114,6 +126,12 @@ export function validateBrandConfig(state: BrandConfigState): FieldErrors {
     errors.footer = 'Site footer is required';
   }
 
+  if (!state.adminEmail?.trim()) {
+    errors.adminEmail = 'Admin Email is required';
+  } else if (!isValidEmail(state.adminEmail)) {
+    errors.adminEmail = 'Please enter a valid email address';
+  }
+
   // Validate brand colors (must have exactly 8)
   if (!state.brandColours || state.brandColours.length !== 8) {
     errors.brandColours = 'Must have exactly 8 brand colors';
@@ -162,3 +180,11 @@ function isValidHexColor(color: string): boolean {
   const hex = color.startsWith('#') ? color.slice(1) : color;
   return /^([0-9A-Fa-f]{3}|[0-9A-Fa-f]{6})$/.test(hex);
 }
+
+/**
+ * Helper function to validate email addresses
+ */
+function isValidEmail(email: string): boolean {
+  const re = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+  return re.test(email);
+}

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

@@ -0,0 +1,105 @@
+import { TractStackAPI } from '../api';
+
+export interface TextBlock {
+  type: 'text';
+  content: string;
+  align: 'left' | 'center' | 'right';
+  color: string;
+  isBold: boolean;
+}
+
+export interface ButtonBlock {
+  type: 'button';
+  label: string;
+  url: string;
+  bgColor: string;
+  textColor: string;
+}
+
+export interface DividerBlock {
+  type: 'divider';
+  color: string;
+}
+
+export type EmailBlock = TextBlock | ButtonBlock | DividerBlock;
+
+export interface EmailTemplate {
+  subject: string;
+  blocks: EmailBlock[];
+}
+
+export interface PreviewResponse {
+  subject: string;
+  html: string;
+}
+
+/** One row from GET /api/v1/emails/templates (merged manifests). */
+export interface EmailTemplateListEntry {
+  name: string;
+  adminTitle: string;
+}
+
+const getApi = () => {
+  return new TractStackAPI(
+    typeof window !== 'undefined'
+      ? (window as any).TRACTSTACK_CONFIG?.tenantId || 'default'
+      : 'default'
+  );
+};
+
+export const emailHelpers = {
+  getTemplates: async (): Promise<Record<string, EmailTemplateListEntry[]>> => {
+    const api = getApi();
+    const response = await api.get<Record<string, EmailTemplateListEntry[]>>(
+      '/api/v1/emails/templates'
+    );
+    if (!response.success || !response.data) {
+      throw new Error(response.error || 'Failed to fetch templates');
+    }
+    return response.data;
+  },
+
+  getTemplate: async (
+    category: string,
+    template: string
+  ): Promise<EmailTemplate> => {
+    const api = getApi();
+    const response = await api.get<EmailTemplate>(
+      `/api/v1/emails/templates/${category}/${template}`
+    );
+    if (!response.success || !response.data) {
+      throw new Error(response.error || 'Failed to fetch template');
+    }
+    return response.data;
+  },
+
+  saveTemplate: async (
+    category: string,
+    template: string,
+    data: EmailTemplate
+  ): Promise<void> => {
+    const api = getApi();
+    const response = await api.post(
+      `/api/v1/emails/templates/${category}/${template}`,
+      data
+    );
+    if (!response.success) {
+      throw new Error(response.error || 'Failed to save template');
+    }
+  },
+
+  previewTemplate: async (
+    template: EmailTemplate,
+    mockData: Record<string, any>
+  ): Promise<PreviewResponse> => {
+    const api = getApi();
+    const response = await api.post<PreviewResponse>('/api/v1/emails/preview', {
+      template,
+      data: mockData,
+    });
+    if (!response.success || !response.data) {
+      throw new Error(response.error || 'Failed to generate preview');
+    }
+    return response.data;
+  },
+};

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',
     },
   };