keystone-design-bootstrap 1.0.55 → 1.0.57

package/src/design_system/portal/RowThumbnail.tsx

@@ -0,0 +1,76 @@
+'use client';
+
+import React from 'react';
+import type { PhotoAttachment } from '../../types/api/photos';
+import { useImageCycle, CROSSFADE_DURATION_MS } from '../../lib/hooks/use-image-cycle';
+
+const CROSSFADE_STYLE = { transitionDuration: `${CROSSFADE_DURATION_MS}ms` };
+
+interface RowThumbnailProps {
+  photoAttachments?: PhotoAttachment[];
+  seed: string;
+  alt: string;
+  /** Tailwind size classes. Defaults to w-14 h-14. */
+  sizeClassName?: string;
+}
+
+export function RowThumbnail({
+  photoAttachments,
+  seed,
+  alt,
+  sizeClassName = 'w-14 h-14',
+}: RowThumbnailProps) {
+  const { list, currentIndex, nextIndex, transitioning } = useImageCycle(photoAttachments, seed);
+
+  const displayAlt = list[currentIndex]?.alt || alt;
+
+  if (list.length === 0) {
+    return (
+      <div className={`${sizeClassName} shrink-0 rounded-lg bg-secondary border border-tertiary flex items-center justify-center`}>
+        <svg className="size-5 text-quaternary" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={1.5}>
+          <path strokeLinecap="round" strokeLinejoin="round" d="M2.25 15.75l5.159-5.159a2.25 2.25 0 013.182 0l5.159 5.159m-1.5-1.5l1.409-1.409a2.25 2.25 0 013.182 0l2.909 2.909m-18 3.75h16.5a1.5 1.5 0 001.5-1.5V6a1.5 1.5 0 00-1.5-1.5H3.75A1.5 1.5 0 002.25 6v12a1.5 1.5 0 001.5 1.5zm10.5-11.25h.008v.008h-.008V8.25zm.375 0a.375.375 0 11-.75 0 .375.375 0 01.75 0z" />
+        </svg>
+      </div>
+    );
+  }
+
+  if (list.length === 1) {
+    return (
+      <div className={`${sizeClassName} shrink-0 rounded-lg overflow-hidden`}>
+        {/* eslint-disable-next-line @next/next/no-img-element */}
+        <img
+          src={list[0]!.url}
+          alt={list[0]!.alt || alt}
+          className="w-full h-full object-cover transition-transform duration-300 group-hover:scale-105"
+        />
+      </div>
+    );
+  }
+
+  return (
+    <div className={`${sizeClassName} shrink-0 rounded-lg overflow-hidden relative`}>
+      <div
+        className={`absolute inset-0 ${transitioning ? 'transition-opacity ease-in-out' : 'transition-none'}`}
+        style={{ opacity: transitioning ? 0 : 1, ...(transitioning ? CROSSFADE_STYLE : {}) }}
+      >
+        {/* eslint-disable-next-line @next/next/no-img-element */}
+        <img
+          src={list[currentIndex]!.url}
+          alt={list[currentIndex]?.alt ?? displayAlt}
+          className="w-full h-full object-cover transition-transform duration-300 group-hover:scale-105"
+        />
+      </div>
+      <div
+        className={`absolute inset-0 ${transitioning ? 'transition-opacity ease-in-out' : 'transition-none'}`}
+        style={{ opacity: transitioning ? 1 : 0, ...(transitioning ? CROSSFADE_STYLE : {}) }}
+      >
+        {/* eslint-disable-next-line @next/next/no-img-element */}
+        <img
+          src={list[nextIndex]!.url}
+          alt={list[nextIndex]?.alt ?? displayAlt}
+          className="w-full h-full object-cover transition-transform duration-300 group-hover:scale-105"
+        />
+      </div>
+    </div>
+  );
+}

package/src/design_system/portal/index.ts

@@ -0,0 +1,5 @@
+export { PortalPage } from './PortalPage';
+export type { PortalPageProps } from './PortalPage';
+export { LoginForm } from './LoginForm';
+export { LogoutButton } from './LogoutButton';
+export { LoginModalController } from './LoginModalController';

package/src/design_system/sections/index.tsx

@@ -184,7 +184,7 @@ export type { EmailSignupSectionProps } from './email-signup-section';
 
 // Service Menu: packages + treatments; nested specials as badges / modal callouts
 export { ServiceMenuSection } from './service-menu-section';
-export type { ServiceMenuSectionProps, PackagePublic } from './service-menu-section';
+export type { ServiceMenuSectionProps, PackageForMenu } from './service-menu-section';
 
 // Re-export types
 export type { Theme } from '../../themes';

package/src/design_system/sections/service-menu-section.tsx

@@ -1,44 +1,20 @@
 'use client';
 
-import React, { useState, useEffect, useCallback, useMemo } from 'react';
+import React, { useState, useEffect, useCallback } from 'react';
 import { createPortal } from 'react-dom';
 import { PhotoWithFallback, Carousel, Modal, MarkdownRenderer, Button } from '../elements';
 import type { OfferPublic } from '../../types/api/offer';
 import type { Service, ServiceItem } from '../../types/api/service';
+import type { Package } from '../../types/api/package';
 import type { WebsitePhotos } from '../../types/api/website-photos';
 import type { CompanyInformation } from '../../types/api/company-information';
 import type { PhotoAttachment } from '../../types/api/photos';
+import { useImageCycle } from '../../lib/hooks/use-image-cycle';
 
 const SERVICE_MENU_MODAL_ROOT_ID = 'service-menu-modal-root';
-const CYCLE_INTERVAL_MIN_MS = 6000;
-const CYCLE_INTERVAL_MAX_MS = 8000;
-
-/** Returns a stable value in [0, 1) from seed (for per-card random interval). */
-function seedToUnit(seed: string): number {
-  let h = 2166136261 >>> 0;
-  for (let i = 0; i < seed.length; i++) {
-    h ^= seed.charCodeAt(i);
-    h = (Math.imul(h, 16777619) >>> 0) >>> 0;
-  }
-  return (h >>> 0) / 4294967296;
-}
-
-/** Minimal package from public API (id, name, slug, summary, photo_attachments, description_markdown). */
-export interface PackagePublic {
-  id: number;
-  name: string;
-  slug: string;
-  summary?: string | null;
-  description_markdown?: string | null;
-  pricing_info?: string | null;
-  price_cents?: number | null;
-  photo_attachments?: PhotoAttachment[];
-  package_items?: Array<{ quantity: number; service_item?: { id: number; name: string; slug: string; summary?: string | null } }>;
-  offers?: OfferPublic[];
-}
 
 /** Package with category names and first-service description fallback (derived from services). */
-export interface PackageForMenu extends PackagePublic {
+export interface PackageForMenu extends Package {
   category_names?: string[];
   first_service_description_markdown?: string | null;
 }
@@ -46,7 +22,7 @@ export interface PackageForMenu extends PackagePublic {
 export interface ServiceMenuSectionProps {
   title?: string;
   subtitle?: string;
-  packages?: PackagePublic[] | null;
+  packages?: Package[] | null;
   /** Services (used to derive service items for the third row). */
   services?: Service[] | null;
   websitePhotos?: WebsitePhotos | null;
@@ -76,54 +52,6 @@ function getActivePublicOffers(offers: OfferPublic[] | undefined | null): OfferP
   return offers.filter((o) => o.active !== false && o.expired !== true);
 }
 
-function photoAttachmentDisplayUrl(pa: PhotoAttachment): string | undefined {
-  return pa.photo?.large_url || pa.photo?.medium_url;
-}
-function photoAttachmentAlt(pa: PhotoAttachment): string {
-  return pa.photo?.alt_text || pa.photo?.title || '';
-}
-
-/** Seeded shuffle: same seed => same order (SSR-safe). Different seeds => very different orders. */
-function shuffleWithSeed<T>(array: T[], seed: string): T[] {
-  if (array.length <= 1) return array;
-  const arr = [...array];
-  // FNV-1a style hash so small seed changes (e.g. index 0 vs 1 vs 2) produce very different values
-  let h = 2166136261 >>> 0;
-  for (let i = 0; i < seed.length; i++) {
-    h ^= seed.charCodeAt(i);
-    h = (Math.imul(h, 16777619) >>> 0) >>> 0;
-  }
-  const next = (step: number) => {
-    h = (Math.imul(1664525, (h + step) >>> 0) + 1013904223) >>> 0;
-    return (h >>> 0) / 4294967296;
-  };
-  for (let i = arr.length - 1; i > 0; i--) {
-    const j = Math.floor(next(i) * (i + 1));
-    [arr[i], arr[j]] = [arr[j], arr[i]];
-  }
-  return arr;
-}
-
-const CROSSFADE_DURATION_MS = 600;
-
-/** Returns shuffled list of { url, alt }. Card owns all cycle/transition state. */
-function useCycledPhotoList(
-  photoAttachments: PhotoAttachment[] | undefined,
-  seed: string
-): Array<{ url: string; alt: string }> {
-  return useMemo(
-    () => {
-      const arr = Array.isArray(photoAttachments) && photoAttachments.length > 0 ? photoAttachments : [];
-      if (arr.length === 0) return [];
-      const shuffled = shuffleWithSeed(arr, seed);
-      return shuffled
-        .map((pa) => ({ url: photoAttachmentDisplayUrl(pa) ?? '', alt: photoAttachmentAlt(pa) }))
-        .filter((x) => x.url);
-    },
-    [photoAttachments, seed]
-  );
-}
-
 /** Card with image area. Cycles through photos every N ms with a simple crossfade. */
 function GridCardWithImage({
   photoAttachments,
@@ -152,38 +80,9 @@ function GridCardWithImage({
   hasSpecial?: boolean;
 }) {
   const seed = cycleSeed ?? String(fallbackId);
-  const list = useCycledPhotoList(photoAttachments, seed);
-  const [currentIndex, setCurrentIndex] = useState(0);
-  const [transitioning, setTransitioning] = useState(false);
-
-  // Per-card random interval 6–8s so cards don't all transition in sync
-  const intervalMs = useMemo(
-    () =>
-      CYCLE_INTERVAL_MIN_MS +
-      Math.floor(seedToUnit(seed) * (CYCLE_INTERVAL_MAX_MS - CYCLE_INTERVAL_MIN_MS + 1)),
-    [seed]
-  );
+  const { list, currentIndex, nextIndex, transitioning } = useImageCycle(photoAttachments, seed);
 
-  // Timer: every N ms, start a crossfade
-  useEffect(() => {
-    if (list.length <= 1) return;
-    const id = setInterval(() => setTransitioning(true), intervalMs);
-    return () => clearInterval(id);
-  }, [list.length, intervalMs]);
-
-  // When transitioning, after crossfade duration advance index and stop transitioning
-  useEffect(() => {
-    if (!transitioning || list.length <= 1) return;
-    const t = setTimeout(() => {
-      setCurrentIndex((i) => (i + 1) % list.length);
-      setTransitioning(false);
-    }, CROSSFADE_DURATION_MS);
-    return () => clearTimeout(t);
-  }, [transitioning, list.length]);
-
-  const nextIndex = list.length > 1 ? (currentIndex + 1) % list.length : 0;
-  const currentItem = list[currentIndex];
-  const displayAlt = currentItem?.alt || fallbackAlt;
+  const displayAlt = list[currentIndex]?.alt || fallbackAlt;
   const singleUrl = list[0]?.url;
 
   return (

package/src/lib/actions.ts

@@ -1,10 +1,10 @@
+'use server';
+
 /**
- * Server Actions for form submissions
- * These run on the server and can safely use API_KEY without exposing it to the browser
+ * Server Actions for form submissions.
+ * Runs on the server — API_KEY is never exposed to the browser.
  */
 
-'use server';
-
 const API_URL = process.env.API_URL || 'http://localhost:3000/api/v1';
 const API_KEY = process.env.API_KEY || '';
 
@@ -16,128 +16,64 @@ interface ContactFormResult {
   eventId?: string;
 }
 
-/**
- * Submit contact form via Server Action
- */
+function extractFormFields(formData: FormData) {
+  return {
+    firstName: formData.get('firstName')?.toString().trim() || '',
+    lastName: formData.get('lastName')?.toString().trim() || '',
+    email: formData.get('email')?.toString().trim() || '',
+    phone: formData.get('phone')?.toString().trim() || '',
+    message: formData.get('message')?.toString().trim() || '',
+  };
+}
+
+async function postFormSubmission(payload: Record<string, unknown>): Promise<Response> {
+  return fetch(`${API_URL}/public/form_submissions`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'X-API-Key': API_KEY,
+    },
+    body: JSON.stringify(payload),
+  });
+}
+
 export async function submitContactFormAction(formData: FormData): Promise<ContactFormResult> {
+  const { firstName, lastName, email, phone, message } = extractFormFields(formData);
+
+  if (!firstName || !lastName || !email || !message) {
+    return { success: false, error: 'Please fill in all required fields.' };
+  }
+
   try {
-    // Extract and validate form data
-    const firstName = formData.get('firstName')?.toString().trim() || '';
-    const lastName = formData.get('lastName')?.toString().trim() || '';
-    const email = formData.get('email')?.toString().trim() || '';
-    const phone = formData.get('phone')?.toString().trim() || '';
-    const message = formData.get('message')?.toString().trim() || '';
-    
-    // Basic validation
-    if (!firstName || !lastName || !email || !message) {
-      return {
-        success: false,
-        error: 'Please fill in all required fields.',
-      };
-    }
-    
-    // Combine first and last name
-    const name = `${firstName} ${lastName}`;
-    
-    const payload = {
-      name,
+    const res = await postFormSubmission({
+      name: `${firstName} ${lastName}`,
       email,
       phone,
       message,
-      source: 'contact_form'
-    };
-    
-    // Make API call server-side
-    const response = await fetch(`${API_URL}/public/form_submissions`, {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        'X-API-Key': API_KEY,
-      },
-      body: JSON.stringify(payload),
+      source: 'contact_form',
     });
-    
-    const data = await response.json();
-    
-    if (!response.ok) {
-      return {
-        success: false,
-        error: data.error || 'Failed to submit contact form. Please try again.',
-      };
-    }
-    
-    return {
-      success: true,
-      message: data.message || 'Thank you for contacting us! We\'ll get back to you soon.',
-    };
-  } catch (error) {
-    console.error('Contact form submission error:', error);
-    return {
-      success: false,
-      error: 'Network error. Please try again later.',
-    };
+    const data = await res.json();
+    if (!res.ok) return { success: false, error: data.error || 'Failed to submit. Please try again.' };
+    return { success: true, message: data.message || "Thank you for contacting us! We'll get back to you soon." };
+  } catch {
+    return { success: false, error: 'Network error. Please try again later.' };
   }
 }
 
-/**
- * Submit lead form via Server Action
- */
 export async function submitLeadFormAction(formData: FormData): Promise<ContactFormResult> {
-  try {
-    // Extract and validate form data
-    const firstName = formData.get('firstName')?.toString().trim() || '';
-    const lastName = formData.get('lastName')?.toString().trim() || '';
-    const email = formData.get('email')?.toString().trim() || '';
-    const phone = formData.get('phone')?.toString().trim() || '';
-    const message = formData.get('message')?.toString().trim() || '';
-    
-    // Basic validation
-    if (!firstName || !lastName || !email || !message) {
-      return {
-        success: false,
-        error: 'Please fill in all required fields.',
-      };
-    }
-    
-    const payload = {
-      formType: 'lead',
-      firstName,
-      lastName,
-      email,
-      phone,
-      message,
-    };
-
-    const response = await fetch(`${API_URL}/public/form_submissions`, {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        'X-API-Key': API_KEY,
-      },
-      body: JSON.stringify(payload),
-    });
-    
-    const data = await response.json();
-    
-    if (!response.ok) {
-      return {
-        success: false,
-        error: data.error || 'Failed to submit lead form. Please try again.',
-      };
-    }
+  const { firstName, lastName, email, phone, message } = extractFormFields(formData);
 
-    const eventId = data.data?.event_id ?? undefined;
+  if (!firstName || !lastName || !email || !message) {
+    return { success: false, error: 'Please fill in all required fields.' };
+  }
 
-    return {
-      success: true,
-      message: data.message || 'Thank you! We\'ll be in touch soon.',
-      ...(eventId && { eventId }),
-    };
-  } catch (error) {
-    console.error('Lead form submission error:', error);
-    return {
-      success: false,
-      error: 'Network error. Please try again later.',
-    };
+  try {
+    const res = await postFormSubmission({ formType: 'lead', firstName, lastName, email, phone, message });
+    const data = await res.json();
+    if (!res.ok) return { success: false, error: data.error || 'Failed to submit. Please try again.' };
+    const eventId: string | undefined = data.data?.event_id ?? undefined;
+    return { success: true, message: data.message || "Thank you! We'll be in touch soon.", ...(eventId && { eventId }) };
+  } catch {
+    return { success: false, error: 'Network error. Please try again later.' };
   }
 }

package/src/lib/consumer-session.ts

@@ -0,0 +1,74 @@
+/**
+ * Server-side consumer session helpers.
+ * Runs on the server only — accepts the JWT token read from cookies by the page component.
+ */
+
+export const CONSUMER_TOKEN_COOKIE = 'ks_consumer_token';
+
+import type { Consumer, ConversationSummary, Message, ContactSummary } from '../types/api/consumer';
+export type { Consumer, ConversationSummary, Message, ContactSummary };
+
+function getApiUrl(): string {
+  return process.env.API_URL || 'http://localhost:3000/api/v1';
+}
+
+async function consumerFetch<T>(path: string, token: string): Promise<T | null> {
+  try {
+    const res = await fetch(`${getApiUrl()}${path}`, {
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${token}`,
+      },
+      cache: 'no-store',
+    });
+    if (!res.ok) return null;
+    const json = await res.json();
+    return (json.data ?? json) as T;
+  } catch {
+    return null;
+  }
+}
+
+export async function fetchConsumerMe(token: string): Promise<Consumer | null> {
+  return consumerFetch<Consumer>('/consumer/me', token);
+}
+
+export async function fetchConsumerConversations(token: string): Promise<ConversationSummary[]> {
+  const apiKey = process.env.API_KEY;
+  const headers: Record<string, string> = {
+    'Content-Type': 'application/json',
+    Authorization: `Bearer ${token}`,
+    ...(apiKey ? { 'X-API-Key': apiKey } : {}),
+  };
+  try {
+    const res = await fetch(`${getApiUrl()}/consumer/me/conversations`, { headers, cache: 'no-store' });
+    if (!res.ok) return [];
+    const json = await res.json();
+    return (json.data ?? []) as ConversationSummary[];
+  } catch {
+    return [];
+  }
+}
+
+export async function fetchConsumerMessages(
+  token: string,
+  contactId: number
+): Promise<{ messages: Message[]; contact: ContactSummary | null }> {
+  try {
+    const res = await fetch(
+      `${getApiUrl()}/consumer/me/contacts/${contactId}/messages?per_page=100`,
+      {
+        headers: { Authorization: `Bearer ${token}` },
+        cache: 'no-store',
+      }
+    );
+    if (!res.ok) return { messages: [], contact: null };
+    const json = await res.json();
+    return {
+      messages: (json.data ?? []) as Message[],
+      contact: (json.contact ?? null) as ContactSummary | null,
+    };
+  } catch {
+    return { messages: [], contact: null };
+  }
+}

package/src/lib/hooks/index.ts

@@ -6,3 +6,5 @@
 export { useBreakpoint } from './use-breakpoint';
 export { useClipboard } from './use-clipboard';
 export { useResizeObserver } from './use-resize-observer';
+export { useImageCycle } from './use-image-cycle';
+export type { CycledImage, UseImageCycleResult } from './use-image-cycle';

package/src/lib/hooks/use-image-cycle.ts

@@ -0,0 +1,105 @@
+'use client';
+
+import { useState, useEffect, useMemo } from 'react';
+import type { PhotoAttachment } from '../../types/api/photos';
+
+const CYCLE_INTERVAL_MIN_MS = 6000;
+const CYCLE_INTERVAL_MAX_MS = 8000;
+export const CROSSFADE_DURATION_MS = 600;
+
+export interface CycledImage {
+  url: string;
+  alt: string;
+}
+
+export interface UseImageCycleResult {
+  list: CycledImage[];
+  currentIndex: number;
+  nextIndex: number;
+  transitioning: boolean;
+}
+
+/** Stable value in [0, 1) derived from seed string (FNV-1a hash). Same seed always produces same value. */
+function seedToUnit(seed: string): number {
+  let h = 2166136261 >>> 0;
+  for (let i = 0; i < seed.length; i++) {
+    h ^= seed.charCodeAt(i);
+    h = (Math.imul(h, 16777619) >>> 0) >>> 0;
+  }
+  return (h >>> 0) / 4294967296;
+}
+
+/** Seeded Fisher-Yates shuffle. Same seed produces same order (SSR-safe). */
+function shuffleWithSeed<T>(array: T[], seed: string): T[] {
+  if (array.length <= 1) return array;
+  const arr = [...array];
+  let h = 2166136261 >>> 0;
+  for (let i = 0; i < seed.length; i++) {
+    h ^= seed.charCodeAt(i);
+    h = (Math.imul(h, 16777619) >>> 0) >>> 0;
+  }
+  const next = (step: number) => {
+    h = (Math.imul(1664525, (h + step) >>> 0) + 1013904223) >>> 0;
+    return (h >>> 0) / 4294967296;
+  };
+  for (let i = arr.length - 1; i > 0; i--) {
+    const j = Math.floor(next(i) * (i + 1));
+    [arr[i], arr[j]] = [arr[j], arr[i]];
+  }
+  return arr;
+}
+
+function photoUrlFromAttachment(pa: PhotoAttachment): string | undefined {
+  return pa.photo?.large_url || pa.photo?.medium_url || pa.photo?.thumbnail_url;
+}
+
+function photoAltFromAttachment(pa: PhotoAttachment): string {
+  return pa.photo?.alt_text || pa.photo?.title || '';
+}
+
+/**
+ * Cycles through a list of photo attachments with a seeded shuffle and crossfade transitions.
+ *
+ * Each card uses a unique seed so intervals are staggered — cards don't all transition in sync.
+ * The shuffle is deterministic (SSR-safe) and the timer only activates when there are 2+ images.
+ */
+export function useImageCycle(
+  photoAttachments: PhotoAttachment[] | undefined,
+  seed: string
+): UseImageCycleResult {
+  const list = useMemo<CycledImage[]>(() => {
+    const arr = Array.isArray(photoAttachments) && photoAttachments.length > 0 ? photoAttachments : [];
+    if (arr.length === 0) return [];
+    return shuffleWithSeed(arr, seed)
+      .map((pa) => ({ url: photoUrlFromAttachment(pa) ?? '', alt: photoAltFromAttachment(pa) }))
+      .filter((x) => x.url);
+  }, [photoAttachments, seed]);
+
+  const [currentIndex, setCurrentIndex] = useState(0);
+  const [transitioning, setTransitioning] = useState(false);
+
+  // Per-card random interval (6–8 s) so cards don't all transition in sync
+  const intervalMs = useMemo(
+    () => CYCLE_INTERVAL_MIN_MS + Math.floor(seedToUnit(seed) * (CYCLE_INTERVAL_MAX_MS - CYCLE_INTERVAL_MIN_MS + 1)),
+    [seed]
+  );
+
+  useEffect(() => {
+    if (list.length <= 1) return;
+    const id = setInterval(() => setTransitioning(true), intervalMs);
+    return () => clearInterval(id);
+  }, [list.length, intervalMs]);
+
+  useEffect(() => {
+    if (!transitioning || list.length <= 1) return;
+    const t = setTimeout(() => {
+      setCurrentIndex((i) => (i + 1) % list.length);
+      setTransitioning(false);
+    }, CROSSFADE_DURATION_MS);
+    return () => clearTimeout(t);
+  }, [transitioning, list.length]);
+
+  const nextIndex = list.length > 1 ? (currentIndex + 1) % list.length : 0;
+
+  return { list, currentIndex, nextIndex, transitioning };
+}

package/src/lib/server-api.ts

@@ -5,6 +5,7 @@
 
 import type { CompanyInformation } from '../types/api/company-information';
 import type { Service } from '../types/api/service';
+import type { Package } from '../types/api/package';
 import type { WebsitePhotos } from '../types/api/website-photos';
 
 const API_URL = process.env.API_URL || 'http://localhost:3000/api/v1';
@@ -77,8 +78,8 @@ export function getMetaPixelId(adsConfig: { meta_pixel_id?: string } | null | un
   return str !== '' && str !== 'null' && /^\d+$/.test(str) ? str : null;
 }
 
-export async function getServices() {
-  return serverFetch('/public/services', defaultOptions);
+export async function getServices(): Promise<Service[] | null> {
+  return serverFetch<Service[]>('/public/services', defaultOptions);
 }
 
 export async function getService(slug: string): Promise<Service | null> {
@@ -130,12 +131,12 @@ export async function getSocialPosts() {
 }
 
 /** Packages (bundles of service items). */
-export async function getPackages() {
-  return serverFetch('/public/packages', defaultOptions);
+export async function getPackages(): Promise<Package[] | null> {
+  return serverFetch<Package[]>('/public/packages', defaultOptions);
 }
 
-export async function getPackage(slug: string) {
-  return serverFetch(`/public/packages/by_slug/${encodeURIComponent(slug)}`, defaultOptions);
+export async function getPackage(slug: string): Promise<Package | null> {
+  return serverFetch<Package>(`/public/packages/by_slug/${encodeURIComponent(slug)}`, defaultOptions);
 }
 
 // Alias for testimonials (API uses "reviews")