@hifilabs/pixel 0.7.1 → 0.8.0

package/dist/index.esm.d.ts

@@ -617,3 +617,259 @@ export interface ConsentBridgeProps {
  * props happens in your app code, not in the SDK.
  */
 export declare function ConsentBridge(props: ConsentBridgeProps): null;
+
+// ============================================
+// ArtistOS - Unified Component (Recommended)
+// ============================================
+
+/**
+ * Consent mode for ArtistOS
+ */
+export type ConsentMode = 'built-in' | 'c15t' | 'external' | 'disabled';
+
+/**
+ * Consent configuration for ArtistOS
+ */
+export interface ConsentConfig {
+  /**
+   * How consent is managed
+   * - 'built-in': Use ArtistOS built-in consent manager (default)
+   * - 'c15t': Use c15t consent manager (requires @c15t/react)
+   * - 'external': Consent managed by external system (use ConsentBridge)
+   * - 'disabled': No consent management
+   */
+  mode?: ConsentMode;
+  /** Show consent banner */
+  showBanner?: boolean;
+  /** Delay before showing banner in ms */
+  bannerDelay?: number;
+  /** Show "Manage Preferences" button on banner */
+  showManageButton?: boolean;
+}
+
+/**
+ * Resolved config after merging props with env vars
+ */
+export interface ResolvedConfig {
+  artistId: string | undefined;
+  gtmId: string | undefined;
+  endpoint: string | undefined;
+  consent: Required<ConsentConfig>;
+  debug: boolean;
+  disabled: boolean;
+  scriptUrl: string;
+  useEmulator: boolean;
+  projectId: string | undefined;
+}
+
+/**
+ * Consent state from built-in consent manager
+ */
+export interface ConsentState {
+  /** Current consent preferences */
+  consent: ConsentPreferences | null;
+  /** Whether consent is still loading */
+  loading: boolean;
+  /** Whether user has made a consent choice */
+  hasConsented: boolean;
+  /** Whether to show the consent banner */
+  showBanner: boolean;
+  /** Set banner visibility */
+  setShowBanner: (show: boolean) => void;
+  /** Whether to show the consent dialog */
+  showDialog: boolean;
+  /** Set dialog visibility */
+  setShowDialog: (show: boolean) => void;
+  /** Accept all consent */
+  acceptAll: () => void;
+  /** Decline all consent */
+  declineAll: () => void;
+  /** Update specific consent preferences */
+  updateConsent: (prefs: ConsentPreferences) => void;
+  /** Check if specific consent type is granted */
+  hasConsent: (type: 'analytics' | 'marketing' | 'personalization') => boolean;
+}
+
+/**
+ * ArtistOS Context Value
+ */
+export interface ArtistOSContextValue {
+  config: ResolvedConfig;
+  consentState: ConsentState;
+}
+
+/**
+ * ArtistOS Props - Zero-config unified component
+ */
+export interface ArtistOSProps {
+  /** Artist ID (reads from NEXT_PUBLIC_ARTIST_ID if not provided) */
+  artistId?: string;
+  /** GTM container ID (reads from NEXT_PUBLIC_GTM_ID if not provided) */
+  gtmId?: string;
+  /** Pixel endpoint (reads from NEXT_PUBLIC_PIXEL_ENDPOINT if not provided) */
+  endpoint?: string;
+  /** Consent configuration */
+  consent?: ConsentConfig;
+  /** Enable debug logging */
+  debug?: boolean;
+  /** Disable tracking entirely */
+  disabled?: boolean;
+  /** Custom pixel script URL */
+  scriptUrl?: string;
+  /** Use Firebase emulator */
+  useEmulator?: boolean;
+  /** Project ID for multi-project tracking */
+  projectId?: string;
+  /** Optional children */
+  children?: React.ReactNode;
+}
+
+/**
+ * ArtistOS - Unified component for pixel loading, consent management, and GTM integration
+ *
+ * Zero-config usage:
+ * ```tsx
+ * <ArtistOS />
+ * ```
+ *
+ * With explicit artistId:
+ * ```tsx
+ * <ArtistOS artistId="artist_123" />
+ * ```
+ */
+export declare function ArtistOS(props: ArtistOSProps): JSX.Element;
+
+/**
+ * Hook to access ArtistOS context
+ * @throws Error if used outside ArtistOS
+ */
+export declare function useArtistOS(): ArtistOSContextValue;
+
+/**
+ * Hook to optionally access ArtistOS context
+ * Returns null if not inside ArtistOS
+ */
+export declare function useArtistOSOptional(): ArtistOSContextValue | null;
+
+/**
+ * Built-in consent hook for ArtistOS
+ */
+export declare function useBuiltInConsent(config: Required<ConsentConfig>): ConsentState;
+
+/**
+ * @deprecated Use ArtistOS with consent={{ mode: 'c15t' }} instead
+ */
+export declare function useC15tConsent(config: Required<ConsentConfig>): ConsentState;
+
+/**
+ * ArtistOS with Built-in Consent (used internally by ArtistOS)
+ */
+export declare function ArtistOSWithBuiltIn(props: {
+  config: ResolvedConfig;
+  children?: React.ReactNode;
+}): JSX.Element;
+
+/**
+ * ArtistOS Core - No consent UI (used for external/disabled modes)
+ */
+export declare function ArtistOSCore(props: {
+  config: ResolvedConfig;
+  children?: React.ReactNode;
+}): JSX.Element;
+
+/**
+ * ArtistOS with c15t Integration
+ * Requires @c15t/react to be installed
+ */
+export declare function ArtistOSWithC15t(props: {
+  config: ResolvedConfig;
+  children?: React.ReactNode;
+}): JSX.Element;
+
+/**
+ * ArtistOS Context - for building custom integrations
+ */
+export declare const ArtistOSContext: React.Context<ArtistOSContextValue | null>;
+
+/**
+ * Pixel Script Loader component
+ */
+export declare function PixelScriptLoader(props: { config: ResolvedConfig }): JSX.Element | null;
+
+/**
+ * GTM Script Loader component
+ */
+export declare function GTMScriptLoader(props: { config: ResolvedConfig }): JSX.Element | null;
+
+/**
+ * Consent UI Manager component
+ */
+export declare function ConsentUIManager(props: {
+  config: ResolvedConfig;
+  consentState: ConsentState;
+}): JSX.Element | null;
+
+/**
+ * Hook to sync GTM consent with Balance consent
+ */
+export declare function useGTMConsentSync(
+  config: ResolvedConfig,
+  consentState: ConsentState
+): void;
+
+// ============================================
+// c15t Integration Types
+// ============================================
+
+/**
+ * c15t Consent Manager interface (from @c15t/react)
+ */
+export interface C15tConsentManager {
+  consents: Record<string, boolean> | null;
+  hasConsented: () => boolean;
+  hasConsentFor: (category: string) => boolean;
+  setConsent: (category: string, value: boolean) => void;
+  saveConsents: (source?: string) => void;
+  acceptAll: () => void;
+  rejectAll: () => void;
+}
+
+/**
+ * Hook that bridges c15t consent to ArtistOS ConsentState
+ */
+export declare function useC15tConsentState(
+  c15tManager: C15tConsentManager,
+  config: Required<ConsentConfig>
+): ConsentState;
+
+// ============================================
+// Consent Mapping Helpers
+// ============================================
+
+/**
+ * Mapping from c15t consent categories to Balance consent types
+ */
+export declare const C15T_TO_BALANCE_MAP: {
+  measurement: 'analytics';
+  marketing: 'marketing';
+  experience: 'personalization';
+};
+
+/**
+ * Mapping from Balance consent types to c15t categories
+ */
+export declare const BALANCE_TO_C15T_MAP: {
+  analytics: 'measurement';
+  marketing: 'marketing';
+  personalization: 'experience';
+};
+
+/**
+ * Convert c15t consent state to Balance format
+ */
+export declare function toBalanceConsent(c15tConsents: Record<string, boolean>): ConsentPreferences;
+
+/**
+ * Convert Balance consent to c15t format
+ */
+export declare function fromBalanceConsent(balanceConsent: ConsentPreferences): Record<string, boolean>;