@iqworksai/consentiq-react 0.1.0

package/README.md

@@ -0,0 +1,158 @@
+# @consentiq/react
+
+React SDK for ConsentIQ consent management platform.
+
+## Installation
+
+```bash
+npm install @consentiq/react
+# or
+yarn add @consentiq/react
+# or
+pnpm add @consentiq/react
+```
+
+## Quick Start
+
+```tsx
+import { ConsentIQProvider, CookieBanner, PreferenceCenter } from '@consentiq/react';
+
+function App() {
+  return (
+    <ConsentIQProvider propertyKey="YOUR_PROPERTY_KEY">
+      <CookieBanner />
+      <PreferenceCenter />
+      <YourApp />
+    </ConsentIQProvider>
+  );
+}
+```
+
+## Usage
+
+### Provider Configuration
+
+```tsx
+<ConsentIQProvider
+  propertyKey="YOUR_PROPERTY_KEY"
+  apiUrl="https://api.consentiq.io" // Optional: custom API URL
+  autoShow={true} // Optional: show banner automatically
+  language="en" // Optional: override detected language
+  debug={false} // Optional: enable debug logging
+  onConsentChange={(consent) => {
+    console.log('Consent updated:', consent);
+  }}
+>
+  {children}
+</ConsentIQProvider>
+```
+
+### Using the Consent Hook
+
+```tsx
+import { useConsentIQ } from '@consentiq/react';
+
+function Analytics() {
+  const { hasConsent } = useConsentIQ();
+
+  if (!hasConsent('analytics')) {
+    return null;
+  }
+
+  return <GoogleAnalytics />;
+}
+```
+
+### Simplified Consent Check
+
+```tsx
+import { useConsent } from '@consentiq/react';
+
+function MarketingScript() {
+  const hasMarketing = useConsent('marketing');
+
+  if (!hasMarketing) return null;
+
+  return <FacebookPixel />;
+}
+```
+
+### Consent Gate Component
+
+```tsx
+import { ConsentGate } from '@consentiq/react';
+
+function App() {
+  return (
+    <ConsentGate
+      category="analytics"
+      fallback={<p>Enable analytics for better experience</p>}
+    >
+      <AnalyticsProvider />
+    </ConsentGate>
+  );
+}
+```
+
+### Manual Control
+
+```tsx
+import { useConsentIQ } from '@consentiq/react';
+
+function SettingsPage() {
+  const { showPreferenceCenter, resetConsent } = useConsentIQ();
+
+  return (
+    <>
+      <button onClick={showPreferenceCenter}>
+        Manage Cookies
+      </button>
+      <button onClick={resetConsent}>
+        Reset All Preferences
+      </button>
+    </>
+  );
+}
+```
+
+## Consent Categories
+
+| Category | Description |
+|----------|-------------|
+| `necessary` | Essential cookies (always enabled) |
+| `analytics` | Analytics and measurement |
+| `marketing` | Advertising and targeting |
+| `preferences` | User preferences |
+| `social` | Social media integration |
+
+## API Reference
+
+### `useConsentIQ()`
+
+Returns the full consent context:
+
+```typescript
+{
+  consent: ConsentState;           // Current consent state
+  marketingConsent: MarketingConsentState;
+  config: PropertyConfig | null;   // Property configuration
+  isLoading: boolean;              // SDK loading state
+  isBannerVisible: boolean;        // Banner visibility
+  isPreferenceCenterVisible: boolean;
+  language: string;                // Current language
+  regulation: string | null;       // Detected regulation
+  hasConsent(category): boolean;   // Check consent
+  acceptAll(): Promise<void>;      // Accept all
+  rejectAll(): Promise<void>;      // Reject all
+  updateConsent(updates): Promise<void>;
+  showBanner(): void;
+  hideBanner(): void;
+  showPreferenceCenter(): void;
+  hidePreferenceCenter(): void;
+  resetConsent(): void;
+}
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,298 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React from 'react';
+
+/**
+ * ConsentIQ React SDK Types
+ */
+type ConsentCategory = 'necessary' | 'analytics' | 'marketing' | 'preferences' | 'social';
+type ConsentMethod = 'banner' | 'preference_center' | 'api' | 'sdk';
+type BannerPosition = 'bottom' | 'bottom-left' | 'bottom-right' | 'top' | 'center';
+type BannerLayout = 'banner' | 'floating' | 'modal';
+type BannerTheme = 'light' | 'dark' | 'auto';
+interface ConsentState {
+    necessary: boolean;
+    analytics: boolean;
+    marketing: boolean;
+    preferences: boolean;
+    social: boolean;
+    [key: string]: boolean;
+}
+interface MarketingConsentState {
+    email?: boolean;
+    sms?: boolean;
+    whatsapp?: boolean;
+    push?: boolean;
+    [key: string]: boolean | undefined;
+}
+interface ConsentIQConfig {
+    /** Property public key from ConsentIQ dashboard */
+    propertyKey: string;
+    /** API endpoint URL (defaults to production) */
+    apiUrl?: string;
+    /** Unique identifier for the user/visitor */
+    subjectId?: string;
+    /** Auto-generate subjectId if not provided */
+    autoGenerateSubjectId?: boolean;
+    /** Callback when consent is updated */
+    onConsentChange?: (consent: ConsentState, marketing?: MarketingConsentState) => void;
+    /** Callback when consent modal opens */
+    onOpen?: () => void;
+    /** Callback when consent modal closes */
+    onClose?: () => void;
+    /** Whether to show the banner automatically on load */
+    autoShow?: boolean;
+    /** Custom language code (overrides auto-detection) */
+    language?: string;
+    /** Debug mode for development */
+    debug?: boolean;
+}
+interface PropertyConfig {
+    property: {
+        id: string;
+        name: string;
+        domain: string;
+        defaultLanguage: string;
+        supportedLanguages: string[];
+    };
+    banner: {
+        position: BannerPosition;
+        theme: BannerTheme;
+        layout: BannerLayout;
+        showLogo: boolean;
+        logoUrl?: string;
+        primaryColor?: string;
+    };
+    categories: CategoryInfo[];
+    marketingChannels: MarketingChannelInfo[];
+    geoRules: GeoRule[];
+    translations: Record<string, TranslationSet>;
+}
+interface CategoryInfo {
+    code: string;
+    enabled: boolean;
+    defaultState: boolean;
+    name: string;
+    description?: string;
+    isRequired: boolean;
+}
+interface MarketingChannelInfo {
+    code: string;
+    name: string;
+    description?: string;
+    requiresDoubleOptin: boolean;
+}
+interface GeoRule {
+    countries: string[];
+    regulation: 'DPDPA' | 'GDPR' | 'CCPA' | 'none';
+    requireExplicitConsent: boolean;
+}
+interface TranslationSet {
+    bannerTitle?: string;
+    bannerDescription?: string;
+    acceptAllText: string;
+    rejectAllText: string;
+    customizeText: string;
+    savePreferencesText: string;
+    categories: Record<string, {
+        title: string;
+        description: string;
+    }>;
+}
+interface SavedConsent {
+    id: string;
+    cookieConsents: ConsentState;
+    marketingConsents?: MarketingConsentState;
+    consentedAt: string;
+    expiresAt?: string;
+    regulationApplied: string;
+    consentVersion?: string;
+}
+interface ConsentIQContextValue {
+    /** Current consent state */
+    consent: ConsentState;
+    /** Current marketing consent state */
+    marketingConsent: MarketingConsentState;
+    /** Property configuration from server */
+    config: PropertyConfig | null;
+    /** Whether the SDK is still loading */
+    isLoading: boolean;
+    /** Whether the banner is currently visible */
+    isBannerVisible: boolean;
+    /** Whether the preference center is visible */
+    isPreferenceCenterVisible: boolean;
+    /** Current language */
+    language: string;
+    /** Detected regulation */
+    regulation: string | null;
+    /** Check if a specific category has consent */
+    hasConsent: (category: ConsentCategory | string) => boolean;
+    /** Check if a specific marketing channel has consent */
+    hasMarketingConsent: (channel: string) => boolean;
+    /** Accept all consent categories */
+    acceptAll: () => Promise<void>;
+    /** Reject all non-essential consent categories */
+    rejectAll: () => Promise<void>;
+    /** Update specific consent categories */
+    updateConsent: (updates: Partial<ConsentState>) => Promise<void>;
+    /** Update marketing consent */
+    updateMarketingConsent: (updates: Partial<MarketingConsentState>) => Promise<void>;
+    /** Show the consent banner */
+    showBanner: () => void;
+    /** Hide the consent banner */
+    hideBanner: () => void;
+    /** Show the preference center */
+    showPreferenceCenter: () => void;
+    /** Hide the preference center */
+    hidePreferenceCenter: () => void;
+    /** Reset all consent (for debugging) */
+    resetConsent: () => void;
+}
+
+interface ConsentIQProviderProps extends ConsentIQConfig {
+    children: React.ReactNode;
+}
+declare function ConsentIQProvider({ children, propertyKey, apiUrl, subjectId: providedSubjectId, autoGenerateSubjectId, onConsentChange, onOpen, onClose, autoShow, language: preferredLanguage, debug, }: ConsentIQProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Hook to access ConsentIQ context
+ */
+declare function useConsentIQ(): ConsentIQContextValue;
+/**
+ * Simplified hook for checking consent status
+ */
+declare function useConsent(category: ConsentCategory | string): boolean;
+/**
+ * Hook for conditional rendering based on consent
+ */
+declare function useConsentGate(category: ConsentCategory | string): {
+    hasConsent: boolean;
+    isLoading: boolean;
+};
+
+interface CookieBannerProps {
+    /** Custom class name for the banner container */
+    className?: string;
+    /** Override banner position */
+    position?: 'bottom' | 'bottom-left' | 'bottom-right' | 'top' | 'center';
+    /** Override banner theme */
+    theme?: 'light' | 'dark' | 'auto';
+    /** Custom styles */
+    style?: React.CSSProperties;
+}
+declare function CookieBanner({ className, position, theme, style }: CookieBannerProps): react_jsx_runtime.JSX.Element | null;
+
+interface PreferenceCenterProps {
+    /** Custom class name */
+    className?: string;
+    /** Override theme */
+    theme?: 'light' | 'dark' | 'auto';
+    /** Custom styles */
+    style?: React.CSSProperties;
+}
+declare function PreferenceCenter({ className, theme, style }: PreferenceCenterProps): react_jsx_runtime.JSX.Element | null;
+
+interface ConsentGateProps {
+    /** The consent category required to show children */
+    category: ConsentCategory | string;
+    /** Content to show when consent is granted */
+    children: React.ReactNode;
+    /** Content to show when consent is not granted (optional) */
+    fallback?: React.ReactNode;
+    /** Content to show while loading (optional) */
+    loading?: React.ReactNode;
+}
+/**
+ * ConsentGate - Conditionally render content based on consent status
+ *
+ * @example
+ * ```tsx
+ * <ConsentGate category="analytics">
+ *   <GoogleAnalytics />
+ * </ConsentGate>
+ *
+ * <ConsentGate
+ *   category="marketing"
+ *   fallback={<p>Enable marketing cookies for personalized ads</p>}
+ * >
+ *   <FacebookPixel />
+ * </ConsentGate>
+ * ```
+ */
+declare function ConsentGate({ category, children, fallback, loading, }: ConsentGateProps): react_jsx_runtime.JSX.Element;
+/**
+ * Higher-order component version of ConsentGate
+ *
+ * @example
+ * ```tsx
+ * const ProtectedAnalytics = withConsentGate(GoogleAnalytics, 'analytics');
+ * ```
+ */
+declare function withConsentGate<P extends object>(Component: React.ComponentType<P>, category: ConsentCategory | string, FallbackComponent?: React.ComponentType<P>): (props: P) => react_jsx_runtime.JSX.Element | null;
+
+/**
+ * ConsentIQ API Client
+ * Handles all communication with the ConsentIQ backend
+ */
+
+declare class ConsentIQApiClient {
+    private apiUrl;
+    private propertyKey;
+    private debug;
+    constructor(propertyKey: string, apiUrl?: string, debug?: boolean);
+    private log;
+    private fetch;
+    /**
+     * Fetch property configuration including banner settings and translations
+     */
+    getConfig(): Promise<PropertyConfig>;
+    /**
+     * Get existing consent for a subject
+     */
+    getConsent(subjectId: string): Promise<SavedConsent | null>;
+    /**
+     * Submit consent to the server
+     */
+    submitConsent(data: {
+        subjectId: string;
+        subjectType?: 'visitor' | 'user' | 'subscriber';
+        cookieConsents: ConsentState;
+        marketingConsents?: MarketingConsentState;
+        geoCountry?: string;
+        geoRegion?: string;
+        geoSource?: 'ip' | 'user_override' | 'browser';
+        consentMethod?: 'banner' | 'preference_center' | 'api' | 'sdk';
+        consentVersion?: string;
+    }): Promise<{
+        success: boolean;
+        consentId: string;
+        proofHash: string;
+    }>;
+    /**
+     * Verify a consent record
+     */
+    verifyConsent(consentId: string): Promise<{
+        verified: boolean;
+        consent: {
+            id: string;
+            consentedAt: string;
+            proofHash: string;
+        };
+    }>;
+}
+/**
+ * Generate a unique subject ID for anonymous visitors
+ */
+declare function generateSubjectId(): string;
+/**
+ * Get or create subject ID from localStorage
+ */
+declare function getOrCreateSubjectId(): string;
+/**
+ * Detect user's country from browser
+ */
+declare function detectCountry(): string | undefined;
+/**
+ * Detect user's preferred language
+ */
+declare function detectLanguage(supportedLanguages: string[]): string;
+
+export { type BannerLayout, type BannerPosition, type BannerTheme, type CategoryInfo, type ConsentCategory, ConsentGate, type ConsentGateProps, ConsentIQApiClient, type ConsentIQConfig, type ConsentIQContextValue, ConsentIQProvider, type ConsentMethod, type ConsentState, CookieBanner, type CookieBannerProps, type GeoRule, type MarketingChannelInfo, type MarketingConsentState, PreferenceCenter, type PreferenceCenterProps, type PropertyConfig, type SavedConsent, type TranslationSet, detectCountry, detectLanguage, generateSubjectId, getOrCreateSubjectId, useConsent, useConsentGate, useConsentIQ, withConsentGate };