astro-tractstack 2.0.0-rc.0

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

@@ -0,0 +1,87 @@
+import { TractStackAPI } from '../api';
+import { convertToBackendFormat, convertToLocalState } from './beliefHelpers';
+import type { BeliefNode, BeliefNodeState } from '@/types/tractstack';
+
+/**
+ * Save an existing belief
+ */
+export async function saveBelief(
+  tenantId: string,
+  beliefState: BeliefNodeState
+): Promise<BeliefNode> {
+  const api = new TractStackAPI(tenantId);
+  const beliefData = convertToBackendFormat(beliefState);
+
+  const response = await api.put(
+    `/api/v1/nodes/beliefs/${beliefState.id}`,
+    beliefData
+  );
+  return response.data as BeliefNode;
+}
+
+/**
+ * Create a new belief
+ */
+export async function createBelief(
+  tenantId: string,
+  beliefState: BeliefNodeState
+): Promise<BeliefNode> {
+  const api = new TractStackAPI(tenantId);
+  const beliefData = convertToBackendFormat(beliefState);
+
+  const response = await api.post('/api/v1/nodes/beliefs/create', beliefData);
+  return response.data as BeliefNode;
+}
+
+/**
+ * Delete a belief
+ */
+export async function deleteBelief(
+  tenantId: string,
+  beliefId: string
+): Promise<void> {
+  const api = new TractStackAPI(tenantId);
+  await api.request(`/api/v1/nodes/beliefs/${beliefId}`, { method: 'DELETE' });
+}
+
+/**
+ * Get a belief by ID
+ */
+export async function getBeliefById(
+  tenantId: string,
+  beliefId: string
+): Promise<BeliefNode> {
+  const api = new TractStackAPI(tenantId);
+  const response = await api.get(`/api/v1/nodes/beliefs/${beliefId}`);
+  return response.data as BeliefNode;
+}
+
+/**
+ * Main save workflow with state update
+ * Following the exact pattern from menuConfig.ts
+ */
+export async function saveBeliefWithStateUpdate(
+  tenantId: string,
+  currentState: BeliefNodeState
+): Promise<BeliefNodeState> {
+  try {
+    let savedBelief: BeliefNode;
+
+    // Determine if this is a create or update operation
+    const isCreate = !currentState.id || currentState.id === '';
+
+    if (isCreate) {
+      // Generate temporary ID for create (backend will assign real ID)
+      const tempState = { ...currentState, id: crypto.randomUUID() };
+      savedBelief = await createBelief(tenantId, tempState);
+    } else {
+      savedBelief = await saveBelief(tenantId, currentState);
+    }
+
+    // Convert the saved belief back to state format
+    return convertToLocalState(savedBelief);
+  } catch (error) {
+    console.error('Belief save failed:', error);
+    throw error;
+  }
+}

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

@@ -0,0 +1,196 @@
+import type {
+  BeliefNode,
+  BeliefNodeState,
+  FieldErrors,
+} from '@/types/tractstack';
+
+/**
+ * Convert backend BeliefNode to frontend BeliefNodeState
+ */
+export function convertToLocalState(beliefNode: BeliefNode): BeliefNodeState {
+  return {
+    id: beliefNode.id,
+    title: beliefNode.title,
+    slug: beliefNode.slug,
+    scale: beliefNode.scale,
+    customValues: beliefNode.customValues || [],
+  };
+}
+
+/**
+ * Convert frontend BeliefNodeState to backend BeliefNode format
+ */
+export function convertToBackendFormat(state: BeliefNodeState): BeliefNode {
+  return {
+    id: state.id,
+    title: state.title,
+    slug: state.slug,
+    scale: state.scale,
+    customValues:
+      state.customValues.length > 0 ? state.customValues : undefined,
+  };
+}
+
+/**
+ * Validate belief node state
+ */
+export function validateBeliefNode(state: BeliefNodeState): FieldErrors {
+  const errors: FieldErrors = {};
+
+  // Validate title
+  if (!state.title?.trim()) {
+    errors.title = 'Title is required';
+  }
+
+  // Validate slug
+  if (!state.slug?.trim()) {
+    errors.slug = 'Slug is required';
+  }
+
+  // Validate scale
+  if (!state.scale?.trim()) {
+    errors.scale = 'Scale is required';
+  }
+
+  // Validate custom values if scale is custom
+  if (state.scale === 'custom') {
+    if (!state.customValues || state.customValues.length === 0) {
+      errors.customValues =
+        'At least one custom value is required for custom scale';
+    } else {
+      state.customValues.forEach((value, index) => {
+        if (!value?.trim()) {
+          errors[`customValues.${index}`] = 'Custom value cannot be empty';
+        }
+      });
+    }
+  }
+
+  return errors;
+}
+
+/**
+ * State interceptor for form state management
+ */
+export function beliefStateIntercept(
+  state: BeliefNodeState,
+  field: keyof BeliefNodeState,
+  value: any
+): BeliefNodeState {
+  const newState = { ...state };
+
+  switch (field) {
+    case 'title':
+      newState.title = value || '';
+      break;
+    case 'slug':
+      newState.slug = value || '';
+      break;
+    case 'scale':
+      newState.scale = value || '';
+      // Clear custom values when scale changes away from custom
+      if (value !== 'custom') {
+        newState.customValues = [];
+      }
+      break;
+    case 'customValues':
+      newState.customValues = value || [];
+      break;
+    default:
+      (newState as any)[field] = value;
+  }
+
+  return newState;
+}
+
+/**
+ * Add a new custom value to the state
+ */
+export function addCustomValue(
+  state: BeliefNodeState,
+  value: string
+): BeliefNodeState {
+  if (!value.trim()) return state;
+
+  return {
+    ...state,
+    customValues: [...state.customValues, value.trim()],
+  };
+}
+
+/**
+ * Remove a custom value from the state
+ */
+export function removeCustomValue(
+  state: BeliefNodeState,
+  index: number
+): BeliefNodeState {
+  return {
+    ...state,
+    customValues: state.customValues.filter((_, i) => i !== index),
+  };
+}
+
+/**
+ * Update a specific custom value in the state
+ */
+export function updateCustomValue(
+  state: BeliefNodeState,
+  index: number,
+  value: string
+): BeliefNodeState {
+  const newCustomValues = [...state.customValues];
+  newCustomValues[index] = value;
+
+  return {
+    ...state,
+    customValues: newCustomValues,
+  };
+}
+
+/**
+ * Scale options for the belief form
+ */
+export const SCALE_OPTIONS = [
+  { value: 'likert', label: 'Likert Scale (1-5)' },
+  { value: 'agreement', label: 'Agreement (Agree/Disagree)' },
+  { value: 'interest', label: 'Interest (Interested/Not Interested)' },
+  { value: 'yn', label: 'Yes/No' },
+  { value: 'tf', label: 'True/False' },
+  { value: 'custom', label: 'Custom Values' },
+];
+
+/**
+ * Get scale preview data for displaying scale options
+ */
+export function getScalePreview(scale: string) {
+  const scalePreviewData: {
+    [key: string]: Array<{ id: number; name: string; color: string }>;
+  } = {
+    likert: [
+      { id: 1, name: 'Strongly agree', color: 'bg-teal-400' },
+      { id: 2, name: 'Agree', color: 'bg-lime-400' },
+      { id: 3, name: 'Neither agree nor disagree', color: 'bg-slate-200' },
+      { id: 4, name: 'Disagree', color: 'bg-amber-400' },
+      { id: 5, name: 'Strongly disagree', color: 'bg-red-400' },
+    ],
+    agreement: [
+      { id: 1, name: 'Agree', color: 'bg-lime-400' },
+      { id: 2, name: 'Disagree', color: 'bg-amber-400' },
+    ],
+    interest: [
+      { id: 1, name: 'Interested', color: 'bg-lime-400' },
+      { id: 2, name: 'Not Interested', color: 'bg-amber-400' },
+    ],
+    yn: [
+      { id: 1, name: 'Yes', color: 'bg-lime-400' },
+      { id: 2, name: 'No', color: 'bg-amber-400' },
+    ],
+    tf: [
+      { id: 1, name: 'True', color: 'bg-lime-400' },
+      { id: 2, name: 'False', color: 'bg-amber-400' },
+    ],
+  };
+
+  return scalePreviewData[scale] || null;
+}

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

@@ -0,0 +1,126 @@
+import { TractStackAPI } from '../api';
+import { convertToLocalState, convertToBackendFormat } from './brandHelpers';
+import type { BrandConfig, BrandConfigState } from '@/types/tractstack';
+
+export async function saveBrandConfig(
+  tenantId: string,
+  brandConfig: BrandConfig
+): Promise<BrandConfig> {
+  const api = new TractStackAPI(tenantId);
+  try {
+    const response = await api.put('/api/v1/config/brand', {
+      ...brandConfig,
+      SITE_INIT: true,
+    });
+    if (!response.success) {
+      throw new Error(response.error || 'Failed to save brand configuration');
+    }
+    return response.data;
+  } catch (error) {
+    // If it's a network error (backend down), redirect to maintenance
+    if (error instanceof TypeError && error.message.includes('fetch failed')) {
+      window.location.href = `/maint?from=${encodeURIComponent(window.location.pathname)}`;
+      throw error; // Still throw so caller knows something failed
+    }
+    throw error;
+  }
+}
+
+export async function getBrandConfig(tenantId: string): Promise<BrandConfig> {
+  const api = new TractStackAPI(tenantId);
+  try {
+    const response = await api.get('/api/v1/config/brand');
+    if (!response.success) {
+      // Check if it's a backend down scenario based on error message
+      if (
+        response.error &&
+        (response.error.includes('Network error') ||
+          response.error.includes('fetch failed'))
+      ) {
+        // Return empty/default config when backend is down
+        return {
+          SITE_INIT: false,
+          WORDMARK_MODE: '',
+          BRAND_COLOURS: '',
+          OPEN_DEMO: false,
+          HOME_SLUG: 'hello',
+          TRACTSTACK_HOME_SLUG: 'HELLO',
+          THEME: 'Default',
+          SOCIALS: '',
+          LOGO: '',
+          WORDMARK: '',
+          OG: '',
+          OGLOGO: '',
+          FAVICON: '',
+          SITE_URL: '',
+          SLOGAN: '',
+          FOOTER: '',
+          OGTITLE: '',
+          OGAUTHOR: '',
+          OGDESC: '',
+          GTAG: '',
+          STYLES_VER: 1,
+          KNOWN_RESOURCES: {},
+          HAS_AAI: false,
+        } as BrandConfig;
+      }
+      throw new Error(response.error || 'Failed to get brand configuration');
+    }
+    return response.data;
+  } catch (error) {
+    // If it's a network error (backend down), return default config
+    if (error instanceof TypeError && error.message.includes('fetch failed')) {
+      return {
+        SITE_INIT: false,
+        WORDMARK_MODE: '',
+        BRAND_COLOURS: '',
+        OPEN_DEMO: false,
+        HOME_SLUG: 'hello',
+        TRACTSTACK_HOME_SLUG: 'HELLO',
+        THEME: 'Default',
+        SOCIALS: '',
+        LOGO: '',
+        WORDMARK: '',
+        OG: '',
+        OGLOGO: '',
+        FAVICON: '',
+        SITE_URL: '',
+        SLOGAN: '',
+        FOOTER: '',
+        OGTITLE: '',
+        OGAUTHOR: '',
+        OGDESC: '',
+        GTAG: '',
+        STYLES_VER: 1,
+        KNOWN_RESOURCES: {},
+        HAS_AAI: false,
+      } as BrandConfig;
+    }
+    throw error;
+  }
+}
+
+/**
+ * Handle complete brand config save workflow including state updates
+ */
+export async function saveBrandConfigWithStateUpdate(
+  tenantId: string,
+  currentState: BrandConfigState
+): Promise<BrandConfigState> {
+  const backendFormat = convertToBackendFormat(currentState);
+
+  try {
+    // Send COMPLETE config, not just changed fields
+    await saveBrandConfig(tenantId, backendFormat);
+
+    // Get the complete updated config from backend
+    const freshConfig = await getBrandConfig(tenantId);
+
+    // Convert updated config back to local state format
+    const newLocalState = convertToLocalState(freshConfig);
+
+    return newLocalState;
+  } catch (error) {
+    throw error;
+  }
+}

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

@@ -0,0 +1,155 @@
+import type { FieldErrors } from '@/hooks/useFormState';
+import { getThemeColors } from '@/constants/brandThemes';
+import type { BrandConfig, BrandConfigState } from '@/types/tractstack';
+
+/**
+ * Convert backend BrandConfig to local state format
+ * Splits CSV strings into arrays for easier client-side manipulation
+ * Provides safe defaults for undefined values to prevent controlled input warnings
+ */
+export function convertToLocalState(
+  brandConfig: BrandConfig
+): BrandConfigState {
+  return {
+    siteInit: brandConfig.SITE_INIT ?? false,
+    wordmarkMode: brandConfig.WORDMARK_MODE ?? '',
+    brandColours: brandConfig.BRAND_COLOURS
+      ? brandConfig.BRAND_COLOURS.split(',').map((color) => color.trim())
+      : getThemeColors('Default'), // Fallback to Default theme
+    openDemo: brandConfig.OPEN_DEMO ?? false,
+    homeSlug: brandConfig.HOME_SLUG ?? 'hello',
+    tractstackHomeSlug: brandConfig.TRACTSTACK_HOME_SLUG ?? 'HELLO',
+    theme: brandConfig.THEME ?? 'light-bold',
+    socials: brandConfig.SOCIALS
+      ? brandConfig.SOCIALS.split(',').filter((social) => social.trim())
+      : [],
+    logo: brandConfig.LOGO ?? '',
+    wordmark: brandConfig.WORDMARK ?? '',
+    og: brandConfig.OG ?? '',
+    oglogo: brandConfig.OGLOGO ?? '',
+    favicon: brandConfig.FAVICON ?? '',
+    siteUrl: brandConfig.SITE_URL ?? '',
+    slogan: brandConfig.SLOGAN ?? '',
+    footer: brandConfig.FOOTER ?? '',
+    ogtitle: brandConfig.OGTITLE ?? '',
+    ogauthor: brandConfig.OGAUTHOR ?? '',
+    ogdesc: brandConfig.OGDESC ?? '',
+    gtag: brandConfig.GTAG ?? '',
+    stylesVer: brandConfig.STYLES_VER ?? 1,
+    knownResources: brandConfig.KNOWN_RESOURCES ?? {},
+    hasAAI: brandConfig.HAS_AAI ?? false,
+  };
+}
+
+/**
+ * Convert local state back to backend BrandConfig format
+ * Joins arrays back into CSV/pipe-separated strings
+ */
+export function convertToBackendFormat(
+  localState: BrandConfigState
+): BrandConfig {
+  return {
+    SITE_INIT: localState.siteInit,
+    WORDMARK_MODE: localState.wordmarkMode,
+    BRAND_COLOURS: localState.brandColours.join(','),
+    OPEN_DEMO: localState.openDemo,
+    STYLES_VER: localState.stylesVer,
+    HOME_SLUG: localState.homeSlug,
+    TRACTSTACK_HOME_SLUG: localState.tractstackHomeSlug,
+    THEME: localState.theme,
+    SOCIALS: localState.socials.join(','),
+    SITE_URL: localState.siteUrl,
+    SLOGAN: localState.slogan,
+    FOOTER: localState.footer,
+    OGTITLE: localState.ogtitle,
+    OGAUTHOR: localState.ogauthor,
+    OGDESC: localState.ogdesc,
+    GTAG: localState.gtag,
+    KNOWN_RESOURCES: localState.knownResources,
+    HAS_AAI: localState.hasAAI,
+
+    // ALWAYS send asset paths (current state)
+    LOGO: localState.logo,
+    WORDMARK: localState.wordmark,
+    OG: localState.og,
+    OGLOGO: localState.oglogo,
+    FAVICON: localState.favicon,
+
+    // Only send base64 when uploading
+    LOGO_BASE64: localState.logoBase64,
+    WORDMARK_BASE64: localState.wordmarkBase64,
+    OG_BASE64: localState.ogBase64,
+    OGLOGO_BASE64: localState.oglogoBase64,
+    FAVICON_BASE64: localState.faviconBase64,
+  };
+}
+
+/**
+ * Validation function for brand configuration
+ * Returns field-level error messages
+ */
+export function validateBrandConfig(state: BrandConfigState): FieldErrors {
+  const errors: FieldErrors = {};
+
+  // Validate required fields
+  if (!state.siteUrl?.trim()) {
+    errors.siteUrl = 'Site URL is required';
+  } else if (!isValidUrl(state.siteUrl)) {
+    errors.siteUrl = 'Please enter a valid URL';
+  }
+
+  if (!state.slogan?.trim()) {
+    errors.slogan = 'Site slogan is required';
+  }
+  if (!state.footer?.trim()) {
+    errors.footer = 'Site footer is required';
+  }
+
+  // Validate brand colors (must have exactly 8)
+  if (!state.brandColours || state.brandColours.length !== 8) {
+    errors.brandColours = 'Must have exactly 8 brand colors';
+  } else {
+    // Validate each color is a valid hex
+    const invalidColors = state.brandColours.filter(
+      (color) => !isValidHexColor(color)
+    );
+    if (invalidColors.length > 0) {
+      errors.brandColours = `Invalid hex colors: ${invalidColors.join(', ')}`;
+    }
+  }
+
+  // Validate social links format
+  if (state.socials && state.socials.length > 0) {
+    const invalidSocials = state.socials.filter((social) => {
+      const parts = social.split('|');
+      return parts.length !== 2 || !parts[0].trim() || !isValidUrl(parts[1]);
+    });
+
+    if (invalidSocials.length > 0) {
+      errors.socials = 'Social links must be in format "platform|url"';
+    }
+  }
+
+  return errors;
+}
+
+/**
+ * Helper function to validate URLs
+ */
+function isValidUrl(url: string): boolean {
+  try {
+    new URL(url);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Helper function to validate hex colors
+ * Accepts both 3 and 6 character hex codes (with or without #)
+ */
+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);
+}