@foxpixel/react 0.1.1 → 0.2.1

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { ReactNode, ComponentType } from 'react';
+import React, { ReactNode, ComponentType } from 'react';
+import { QueryClient } from '@tanstack/react-query';
 import { AxiosInstance, AxiosRequestConfig } from 'axios';
 
 /**
@@ -137,10 +138,14 @@ declare class FoxPixelHttpClient {
 interface FoxPixelContextValue {
     client: FoxPixelHttpClient;
     config: FoxPixelConfig;
+    /** Optional: pass QueryClient so edit-mode messaging can invalidate cache without requiring useQueryClient() in SDK (avoids "No QueryClient set" in iframe). */
+    queryClient?: QueryClient | null;
 }
 interface FoxPixelProviderProps {
     children: ReactNode;
     config?: FoxPixelConfig;
+    /** Pass the app's QueryClient so edit-mode (iframe) can update cache on FOXPIXEL_CONTENT_UPDATED. Required for visual editor preview to refresh. */
+    queryClient?: QueryClient | null;
 }
 /**
  * FoxPixelProvider - Wraps your app and provides SDK functionality
@@ -163,7 +168,7 @@ interface FoxPixelProviderProps {
  * }
  * ```
  */
-declare function FoxPixelProvider({ children, config }: FoxPixelProviderProps): react_jsx_runtime.JSX.Element;
+declare function FoxPixelProvider({ children, config, queryClient }: FoxPixelProviderProps): react_jsx_runtime.JSX.Element;
 /**
  * Hook to access FoxPixel context
  * @throws Error if used outside FoxPixelProvider
@@ -188,6 +193,8 @@ interface AuthContextValue {
         phone?: string;
     }) => Promise<void>;
     refetch: () => Promise<void>;
+    /** Stub: returns true when user is logged in and permission is site:content:update. */
+    hasPermission: (permission: string) => boolean;
 }
 interface AuthProviderProps {
     children: ReactNode;
@@ -261,6 +268,55 @@ interface WithAuthOptions {
 }
 declare function withAuth<P extends object>(Component: ComponentType<P>, options?: WithAuthOptions): (props: P) => string | number | true | Iterable<ReactNode> | react_jsx_runtime.JSX.Element | null;
 
+interface EditableProps {
+    contentKey: string;
+    defaultValue: string;
+    as?: keyof JSX.IntrinsicElements;
+    multiline?: boolean;
+    className?: string;
+}
+declare function Editable({ contentKey, defaultValue, as, multiline, className, }: EditableProps): React.ReactElement<{
+    className: string;
+    'aria-busy': boolean;
+    'aria-label': string;
+}, string | React.JSXElementConstructor<any>> | React.DetailedReactHTMLElement<{
+    onMouseEnter: () => void;
+    onMouseLeave: () => void;
+    style: React.CSSProperties;
+} | {
+    onMouseEnter?: undefined;
+    onMouseLeave?: undefined;
+    style: React.CSSProperties;
+}, HTMLElement>;
+/**
+ * Renders rich HTML content from the CMS. Content is sanitized before rendering.
+ */
+declare function EditableHTML({ contentKey, defaultValue, as, className, }: Omit<EditableProps, 'multiline'>): React.ReactElement<{
+    className: string;
+    'aria-busy': boolean;
+}, string | React.JSXElementConstructor<any>> | React.DetailedReactHTMLElement<{
+    onMouseEnter: () => void;
+    onMouseLeave: () => void;
+    style: React.CSSProperties;
+} | {
+    onMouseEnter?: undefined;
+    onMouseLeave?: undefined;
+    style: React.CSSProperties;
+}, HTMLElement>;
+interface EditableImageProps {
+    contentKey: string;
+    defaultValue: string;
+    alt: string;
+    className?: string;
+    width?: number;
+    height?: number;
+    priority?: boolean;
+}
+/**
+ * Renders an image from a CMS-managed URL. Uses native img (no Next.js Image in SDK).
+ */
+declare function EditableImage({ contentKey, defaultValue, alt, className, width, height, priority, }: EditableImageProps): react_jsx_runtime.JSX.Element;
+
 /**
  * Hook to fetch and manage services (Projects module)
  */
@@ -405,6 +461,254 @@ interface UseContactCaptureReturn {
  */
 declare function useContactCapture(): UseContactCaptureReturn;
 
+/**
+ * Hook for managing editable site content (CMS Visual)
+ *
+ * Allows non-developers to edit text content directly on the site.
+ */
+
+interface SiteContent {
+    id: string;
+    contentKey: string;
+    value: string | null;
+    contentType: string;
+    defaultValue: string | null;
+    description: string | null;
+    section: string | null;
+    sortOrder: number;
+    isActive: boolean;
+    updatedAt: string | null;
+}
+interface UseSiteContentOptions {
+    /**
+     * Default value to use if content is not found
+     */
+    defaultValue?: string;
+    /**
+     * Whether to fetch on mount (default: true)
+     */
+    fetchOnMount?: boolean;
+}
+interface UseSiteContentReturn {
+    /**
+     * The content object (null if not found or loading)
+     */
+    data: SiteContent | null;
+    /**
+     * The content value (or defaultValue if not found)
+     */
+    value: string;
+    /**
+     * Whether content is being loaded
+     */
+    isLoading: boolean;
+    /**
+     * Error if request failed
+     */
+    error: ApiError$1 | null;
+    /**
+     * Whether the current user can edit this content
+     */
+    canEdit: boolean;
+    /**
+     * Update the content value
+     */
+    update: (newValue: string) => Promise<void>;
+    /**
+     * Refetch the content
+     */
+    refetch: () => Promise<void>;
+}
+/**
+ * Hook for managing a single site content key.
+ *
+ * @example
+ * ```tsx
+ * function HeroSection() {
+ *   const { value, canEdit, update } = useSiteContent('hero.title', {
+ *     defaultValue: 'Welcome to our site'
+ *   });
+ *
+ *   const [isEditing, setIsEditing] = useState(false);
+ *   const [editValue, setEditValue] = useState(value);
+ *
+ *   const handleSave = async () => {
+ *     await update(editValue);
+ *     setIsEditing(false);
+ *   };
+ *
+ *   if (canEdit && isEditing) {
+ *     return (
+ *       <input
+ *         value={editValue}
+ *         onChange={(e) => setEditValue(e.target.value)}
+ *         onBlur={handleSave}
+ *       />
+ *     );
+ *   }
+ *
+ *   return (
+ *     <h1 onClick={() => canEdit && setIsEditing(true)}>
+ *       {value}
+ *     </h1>
+ *   );
+ * }
+ * ```
+ */
+declare function useSiteContent(contentKey: string, options?: UseSiteContentOptions): UseSiteContentReturn;
+interface UseSiteContentsOptions {
+    /**
+     * Default values map
+     */
+    defaults?: Record<string, string>;
+}
+interface UseSiteContentsReturn {
+    /**
+     * Map of content key to content object
+     */
+    data: Record<string, SiteContent>;
+    /**
+     * Get value by key (with default fallback)
+     */
+    getValue: (key: string, defaultValue?: string) => string;
+    /**
+     * Whether contents are being loaded
+     */
+    isLoading: boolean;
+    /**
+     * Error if request failed
+     */
+    error: ApiError$1 | null;
+    /**
+     * Refetch all contents
+     */
+    refetch: () => Promise<void>;
+}
+/**
+ * Hook for fetching multiple site content keys at once.
+ * More efficient than calling useSiteContent multiple times.
+ *
+ * @example
+ * ```tsx
+ * function Footer() {
+ *   const { getValue, isLoading } = useSiteContents(
+ *     ['footer.copyright', 'footer.address', 'footer.phone'],
+ *     { defaults: { 'footer.copyright': '© 2024' } }
+ *   );
+ *
+ *   if (isLoading) return null;
+ *
+ *   return (
+ *     <footer>
+ *       <p>{getValue('footer.copyright')}</p>
+ *       <p>{getValue('footer.address')}</p>
+ *       <p>{getValue('footer.phone')}</p>
+ *     </footer>
+ *   );
+ * }
+ * ```
+ */
+declare function useSiteContents(contentKeys: string[], options?: UseSiteContentsOptions): UseSiteContentsReturn;
+interface UseSiteContentSectionReturn {
+    /**
+     * List of contents in the section
+     */
+    contents: SiteContent[];
+    /**
+     * Whether contents are being loaded
+     */
+    isLoading: boolean;
+    /**
+     * Error if request failed
+     */
+    error: ApiError$1 | null;
+    /**
+     * Refetch section contents
+     */
+    refetch: () => Promise<void>;
+}
+/**
+ * Hook for fetching all content in a section.
+ *
+ * @example
+ * ```tsx
+ * function HeroSection() {
+ *   const { contents, isLoading } = useSiteContentSection('hero');
+ *
+ *   if (isLoading) return <div>Loading...</div>;
+ *
+ *   return (
+ *     <div>
+ *       {contents.map(content => (
+ *         <div key={content.contentKey}>{content.value}</div>
+ *       ))}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useSiteContentSection(section: string): UseSiteContentSectionReturn;
+
+/**
+ * Edit-mode hooks for CMS Visual (iframe communication with Tenant Admin).
+ * When edit-mode=true is in the URL, the site enters edit mode and communicates
+ * with the parent iframe via postMessage.
+ */
+/** Query key used for site content; must match useSiteContentQuery. */
+declare const SITE_CONTENT_QUERY_KEY: "siteContent";
+/**
+ * Returns true when the page is in edit mode (URL has edit-mode=true).
+ * Used to show edit affordances and enable postMessage communication.
+ */
+declare function useEditMode(): boolean;
+/**
+ * Sets up edit-mode messaging: notifies parent when ready and listens for
+ * FOXPIXEL_CONTENT_UPDATED. Uses queryClient from FoxPixelContext (pass it to
+ * FoxPixelProvider) so we don't require useQueryClient() and avoid "No QueryClient set" in iframe.
+ */
+declare function useEditModeMessaging(): boolean;
+/**
+ * Returns a callback to send an edit request to the parent iframe.
+ * Only has effect when in edit mode.
+ */
+declare function useSendEditRequest(): (contentKey: string, currentValue: string, contentType?: string, section?: string, description?: string) => void;
+
+/**
+ * Site content hook for Editable components.
+ * Uses the QueryClient passed via FoxPixelProvider (no useQuery) so it never
+ * depends on QueryClientProvider context — avoids "No QueryClient set" in iframe/SSR.
+ */
+interface UseSiteContentQueryOptions {
+    defaultValue: string;
+}
+interface UseSiteContentQueryReturn {
+    value: string;
+    isLoading: boolean;
+    contentType: string;
+}
+/**
+ * Fetches a single site content by key. Uses the queryClient from FoxPixelContext
+ * (passed by the host) so it never calls useQuery() and never throws "No QueryClient set".
+ */
+declare function useSiteContentQuery(contentKey: string, options: UseSiteContentQueryOptions): UseSiteContentQueryReturn;
+
+/**
+ * Prefetch site content for Next.js getStaticProps (SSG).
+ * Fetches content keys and fills the QueryClient so HydrationBoundary can hydrate the app.
+ */
+
+interface PrefetchSiteContentOptions {
+    apiUrl: string;
+    apiKey?: string;
+    tenantId?: string;
+    contentKeys: string[];
+}
+/**
+ * Prefetch site content keys and set them on the given QueryClient.
+ * Call this in getStaticProps, then pass the dehydrated state to HydrationBoundary in _app.
+ */
+declare function prefetchSiteContent(queryClient: QueryClient, options: PrefetchSiteContentOptions): Promise<void>;
+
 /**
  * Blog module types for FoxPixel SDK
  * Aligned with backend BlogPostResponse, BlogCategoryResponse, BlogTagResponse
@@ -675,6 +979,8 @@ interface UseNewsletterSubscribeReturn {
 declare function useNewsletterSubscribe(): UseNewsletterSubscribeReturn;
 interface UseNewsletterUnsubscribeReturn {
     unsubscribe: (email: string) => Promise<boolean>;
+    /** Cancelar inscrição pelo token (link no email de confirmação). */
+    unsubscribeByToken: (token: string) => Promise<boolean>;
     isSubmitting: boolean;
     error: ApiError$1 | null;
     success: boolean;
@@ -861,4 +1167,4 @@ interface BlogPostSchemaLdOptions {
  */
 declare function getBlogPostSchemaLd(post: BlogPost, options: BlogPostSchemaLdOptions): Record<string, unknown>;
 
-export { type ApiError$1 as ApiError, AuthProvider, type BlogAnalyticsSummary, type BlogAuthor, type BlogCategory, type BlogComment, type BlogCommentAdmin, type BlogCommentPage, type BlogPost, type BlogPostPage, type BlogPostSchemaLdOptions, type BlogPostStatus, type BlogSettings, type BlogTag, type CreateBlogCommentPayload, type CreateBlogPostPayload, type CreateCategoryPayload, type CreateLeadRequest, type CreateTagPayload, type EndUser, type EndUserLoginRequest, type FoxPixelConfig, FoxPixelHttpClient, FoxPixelProvider, GuestOnlyRoute, type Lead, type NewsletterFrequency, type NewsletterStats, type NewsletterStatus, type NewsletterSubscriber, type NewsletterSubscriberPage, type PostAnalyticsRow, ProtectedRoute, type Service, type ServiceCatalogResponse, type SubscribeNewsletterPayload, type UpdateBlogPostPayload, type UseAdminBlogAnalyticsReturn, type UseAdminBlogCategoriesReturn, type UseAdminBlogCommentsOptions, type UseAdminBlogCommentsReturn, type UseAdminBlogPostMutationsReturn, type UseAdminBlogPostReturn, type UseAdminBlogPostsOptions, type UseAdminBlogPostsReturn, type UseAdminBlogSettingsReturn, type UseAdminBlogTagsReturn, type UseAdminNewsletterStatsReturn, type UseAdminNewsletterSubscribersOptions, type UseAdminNewsletterSubscribersReturn, type UseBlogCategoriesReturn, type UseBlogCommentSubmitReturn, type UseBlogCommentsReturn, type UseBlogFeaturedPostsReturn, type UseBlogPostReturn, type UseBlogPostsOptions, type UseBlogPostsReturn, type UseBlogTagsReturn, type UseNewsletterSubscribeReturn, type UseNewsletterUnsubscribeReturn, getBlogPostSchemaLd, useAdminBlogAnalytics, useAdminBlogCategories, useAdminBlogComments, useAdminBlogPost, useAdminBlogPostMutations, useAdminBlogPosts, useAdminBlogSettings, useAdminBlogTags, useAdminNewsletterStats, useAdminNewsletterSubscribers, useAuth, useBlogCategories, useBlogCommentSubmit, useBlogComments, useBlogFeaturedPosts, useBlogPost, useBlogPosts, useBlogTags, useContactCapture, useFoxPixelContext, useLeadCapture, useNewsletterSubscribe, useNewsletterUnsubscribe, useServices, withAuth };
+export { type ApiError$1 as ApiError, AuthProvider, type BlogAnalyticsSummary, type BlogAuthor, type BlogCategory, type BlogComment, type BlogCommentAdmin, type BlogCommentPage, type BlogPost, type BlogPostPage, type BlogPostSchemaLdOptions, type BlogPostStatus, type BlogSettings, type BlogTag, type CreateBlogCommentPayload, type CreateBlogPostPayload, type CreateCategoryPayload, type CreateLeadRequest, type CreateTagPayload, Editable, EditableHTML, EditableImage, type EditableImageProps, type EditableProps, type EndUser, type EndUserLoginRequest, type FoxPixelConfig, FoxPixelHttpClient, FoxPixelProvider, GuestOnlyRoute, type Lead, type NewsletterFrequency, type NewsletterStats, type NewsletterStatus, type NewsletterSubscriber, type NewsletterSubscriberPage, type PostAnalyticsRow, type PrefetchSiteContentOptions, ProtectedRoute, SITE_CONTENT_QUERY_KEY, type Service, type ServiceCatalogResponse, type SiteContent, type SubscribeNewsletterPayload, type UpdateBlogPostPayload, type UseAdminBlogAnalyticsReturn, type UseAdminBlogCategoriesReturn, type UseAdminBlogCommentsOptions, type UseAdminBlogCommentsReturn, type UseAdminBlogPostMutationsReturn, type UseAdminBlogPostReturn, type UseAdminBlogPostsOptions, type UseAdminBlogPostsReturn, type UseAdminBlogSettingsReturn, type UseAdminBlogTagsReturn, type UseAdminNewsletterStatsReturn, type UseAdminNewsletterSubscribersOptions, type UseAdminNewsletterSubscribersReturn, type UseBlogCategoriesReturn, type UseBlogCommentSubmitReturn, type UseBlogCommentsReturn, type UseBlogFeaturedPostsReturn, type UseBlogPostReturn, type UseBlogPostsOptions, type UseBlogPostsReturn, type UseBlogTagsReturn, type UseNewsletterSubscribeReturn, type UseNewsletterUnsubscribeReturn, type UseSiteContentOptions, type UseSiteContentQueryOptions, type UseSiteContentQueryReturn, type UseSiteContentReturn, type UseSiteContentSectionReturn, type UseSiteContentsOptions, type UseSiteContentsReturn, getBlogPostSchemaLd, prefetchSiteContent, useAdminBlogAnalytics, useAdminBlogCategories, useAdminBlogComments, useAdminBlogPost, useAdminBlogPostMutations, useAdminBlogPosts, useAdminBlogSettings, useAdminBlogTags, useAdminNewsletterStats, useAdminNewsletterSubscribers, useAuth, useBlogCategories, useBlogCommentSubmit, useBlogComments, useBlogFeaturedPosts, useBlogPost, useBlogPosts, useBlogTags, useContactCapture, useEditMode, useEditModeMessaging, useFoxPixelContext, useLeadCapture, useNewsletterSubscribe, useNewsletterUnsubscribe, useSendEditRequest, useServices, useSiteContent, useSiteContentQuery, useSiteContentSection, useSiteContents, withAuth };