@hook-sdk/template 0.3.0 → 0.4.0

package/dist/index.d.cts

@@ -23,6 +23,7 @@ declare const AppConfigSchema: z.ZodObject<{
         leaderboard: "leaderboard";
         push: "push";
         subscription: "subscription";
+        install_prompt: "install_prompt";
     }>>;
     persistedKeys: z.ZodOptional<z.ZodArray<z.ZodString>>;
     dependencies_allowlist: z.ZodArray<z.ZodString>;
@@ -105,6 +106,18 @@ interface PushPromptProps {
 }
 declare function PushPrompt({ texts, onSubscribed, onDeclined, onInstallRequested, className }: PushPromptProps): react_jsx_runtime.JSX.Element | null;
 
+interface InstallGateProps {
+    children: ReactNode;
+}
+declare function InstallGate({ children }: InstallGateProps): react_jsx_runtime.JSX.Element;
+
+interface InstallSplashProps {
+    children: ReactNode;
+    title: string;
+    subtitle?: string;
+}
+declare function InstallSplash({ children, title, subtitle }: InstallSplashProps): react_jsx_runtime.JSX.Element;
+
 declare function DefaultSignupScreen({ onNavigate }: AuthScreenProps): react_jsx_runtime.JSX.Element;
 
 declare function DefaultForgotScreen({ onNavigate }: AuthScreenProps): react_jsx_runtime.JSX.Element;
@@ -393,4 +406,91 @@ declare function useToast(): {
     dismiss: (id: string) => void;
 };
 
-export { AppRoot, type AppRootProps, type AuthFormError, type AuthFormErrorCode, type AuthScreen, type AuthScreenProps, DefaultForgotScreen, DefaultLoginScreen, DefaultPaywall, DefaultResetScreen, DefaultSignupScreen, EmptyState, ErrorBoundary, LoadingState, PushPrompt, type PushPromptProps, type PushPromptTexts, type PushUiState, type SubscriptionStatus, type ToastItem, type UseLoginFormResult, type UseResetFormResult, useAuth, useAuthPrimitives, useForgotForm, useLoginForm, usePaywallState, usePush, useReminders, useResetForm, useSignupForm, useSubscription, useToast };
+/**
+ * useInstallPrompt — headless hook pra PWA install prompt.
+ *
+ * Responsabilidades:
+ *   - Detectar plataforma (Android / iOS Safari / iOS outros / in-app / desktop)
+ *   - Detectar browser específico (Chrome, Firefox, Samsung, Instagram, ...)
+ *   - Detectar standalone mode (PWA já instalado)
+ *   - Gerenciar dismissal graduada (session → permanente 14d)
+ *   - Expor `promptInstall()` que dispara `window.__pwaInstallPrompt.prompt()`
+ *
+ * Não renderiza UI. Componente `<InstallGate>` consome o hook e renderiza.
+ *
+ * Porta regexes + lógica de `hook-old/src/hooks/usePWAInstall.ts` com
+ * divergências deliberadas (ver docs/adr/017 + P20 plan):
+ *   - enum InAppApp granular pra copy por rede social (G60 amendment)
+ *   - dismissal graduada em vez de permanente direto
+ *   - TTL de 14d no permanent dismiss
+ *   - tracking `skipCount` separado
+ *
+ * Gotchas de referência:
+ *   - G61: beforeinstallprompt capturado pré-React (shell main.tsx faz)
+ *   - G62: distinção ios-safari vs ios-other (Chrome iOS não instala)
+ *   - G63: in-app browsers checados ANTES de Android/iOS
+ */
+type Platform = 'android' | 'ios-safari' | 'ios-other' | 'in-app' | 'desktop' | 'unknown';
+type IOSBrowser = 'safari' | 'chrome' | 'firefox' | 'edge' | 'other';
+type AndroidBrowser = 'chrome' | 'firefox' | 'opera' | 'samsung' | 'edge' | 'other';
+type InAppApp = 'instagram' | 'facebook' | 'tiktok' | 'whatsapp' | 'twitter' | 'linkedin' | 'telegram' | 'line' | 'snapchat' | 'pinterest' | 'wechat' | 'other';
+type InstallVariant = 'android-native' | 'android-manual' | 'ios-safari' | 'ios-other' | 'in-app' | 'desktop' | 'none';
+interface BeforeInstallPromptEvent extends Event {
+    prompt: () => Promise<void>;
+    userChoice: Promise<{
+        outcome: 'accepted' | 'dismissed';
+        platform: string;
+    }>;
+}
+declare global {
+    interface Window {
+        __pwaInstallPrompt?: BeforeInstallPromptEvent | null;
+        posthog?: {
+            capture?: (event: string, props?: Record<string, unknown>) => void;
+        };
+    }
+}
+interface InstallState {
+    platform: Platform;
+    iosBrowser: IOSBrowser | null;
+    androidBrowser: AndroidBrowser | null;
+    inAppApp: InAppApp | null;
+    isInstallable: boolean;
+    isInstalled: boolean;
+    isDismissedSession: boolean;
+    isDismissedPermanent: boolean;
+    skipCount: number;
+    variant: InstallVariant;
+}
+interface InstallActions {
+    promptInstall: () => Promise<boolean>;
+    dismissSession: () => void;
+    dismissPermanent: () => void;
+    redirectToSafari: () => void;
+    copyLink: () => Promise<void>;
+    reset: () => void;
+}
+declare function detectPlatform(ua: string): Platform;
+declare function detectIOSBrowser(ua: string): IOSBrowser | null;
+declare function detectAndroidBrowser(ua: string): AndroidBrowser | null;
+declare function detectInAppApp(ua: string): InAppApp | null;
+declare function detectStandalone(): {
+    installed: boolean;
+    source: 'match_media' | 'navigator_standalone' | 'storage_marker' | null;
+};
+/**
+ * Hook principal. Passar o slug do app (usado pra namespacing de storage +
+ * analytics). Componentes do template pegam via useTemplateConfig().slug.
+ */
+declare function useInstallPrompt(slug: string): InstallState & InstallActions;
+/**
+ * Exposto pra InstallGate decidir se renderiza splash (não faz parte do hook
+ * retornado pra manter surface pequena — componente usa).
+ */
+declare function shouldBlockInstall(state: InstallState, now?: number): boolean;
+/**
+ * Exposto pra decidir se mostra "Não me pergunte mais".
+ */
+declare function shouldShowPermanentOption(state: InstallState): boolean;
+
+export { type AndroidBrowser, AppRoot, type AppRootProps, type AuthFormError, type AuthFormErrorCode, type AuthScreen, type AuthScreenProps, DefaultForgotScreen, DefaultLoginScreen, DefaultPaywall, DefaultResetScreen, DefaultSignupScreen, EmptyState, ErrorBoundary, type IOSBrowser, type InAppApp, type InstallActions, InstallGate, InstallSplash, type InstallState, type InstallVariant, LoadingState, type Platform, PushPrompt, type PushPromptProps, type PushPromptTexts, type PushUiState, type SubscriptionStatus, type ToastItem, type UseLoginFormResult, type UseResetFormResult, detectAndroidBrowser, detectIOSBrowser, detectInAppApp, detectPlatform, detectStandalone, shouldBlockInstall, shouldShowPermanentOption, useAuth, useAuthPrimitives, useForgotForm, useInstallPrompt, useLoginForm, usePaywallState, usePush, useReminders, useResetForm, useSignupForm, useSubscription, useToast };

package/dist/index.d.ts

@@ -23,6 +23,7 @@ declare const AppConfigSchema: z.ZodObject<{
         leaderboard: "leaderboard";
         push: "push";
         subscription: "subscription";
+        install_prompt: "install_prompt";
     }>>;
     persistedKeys: z.ZodOptional<z.ZodArray<z.ZodString>>;
     dependencies_allowlist: z.ZodArray<z.ZodString>;
@@ -105,6 +106,18 @@ interface PushPromptProps {
 }
 declare function PushPrompt({ texts, onSubscribed, onDeclined, onInstallRequested, className }: PushPromptProps): react_jsx_runtime.JSX.Element | null;
 
+interface InstallGateProps {
+    children: ReactNode;
+}
+declare function InstallGate({ children }: InstallGateProps): react_jsx_runtime.JSX.Element;
+
+interface InstallSplashProps {
+    children: ReactNode;
+    title: string;
+    subtitle?: string;
+}
+declare function InstallSplash({ children, title, subtitle }: InstallSplashProps): react_jsx_runtime.JSX.Element;
+
 declare function DefaultSignupScreen({ onNavigate }: AuthScreenProps): react_jsx_runtime.JSX.Element;
 
 declare function DefaultForgotScreen({ onNavigate }: AuthScreenProps): react_jsx_runtime.JSX.Element;
@@ -393,4 +406,91 @@ declare function useToast(): {
     dismiss: (id: string) => void;
 };
 
-export { AppRoot, type AppRootProps, type AuthFormError, type AuthFormErrorCode, type AuthScreen, type AuthScreenProps, DefaultForgotScreen, DefaultLoginScreen, DefaultPaywall, DefaultResetScreen, DefaultSignupScreen, EmptyState, ErrorBoundary, LoadingState, PushPrompt, type PushPromptProps, type PushPromptTexts, type PushUiState, type SubscriptionStatus, type ToastItem, type UseLoginFormResult, type UseResetFormResult, useAuth, useAuthPrimitives, useForgotForm, useLoginForm, usePaywallState, usePush, useReminders, useResetForm, useSignupForm, useSubscription, useToast };
+/**
+ * useInstallPrompt — headless hook pra PWA install prompt.
+ *
+ * Responsabilidades:
+ *   - Detectar plataforma (Android / iOS Safari / iOS outros / in-app / desktop)
+ *   - Detectar browser específico (Chrome, Firefox, Samsung, Instagram, ...)
+ *   - Detectar standalone mode (PWA já instalado)
+ *   - Gerenciar dismissal graduada (session → permanente 14d)
+ *   - Expor `promptInstall()` que dispara `window.__pwaInstallPrompt.prompt()`
+ *
+ * Não renderiza UI. Componente `<InstallGate>` consome o hook e renderiza.
+ *
+ * Porta regexes + lógica de `hook-old/src/hooks/usePWAInstall.ts` com
+ * divergências deliberadas (ver docs/adr/017 + P20 plan):
+ *   - enum InAppApp granular pra copy por rede social (G60 amendment)
+ *   - dismissal graduada em vez de permanente direto
+ *   - TTL de 14d no permanent dismiss
+ *   - tracking `skipCount` separado
+ *
+ * Gotchas de referência:
+ *   - G61: beforeinstallprompt capturado pré-React (shell main.tsx faz)
+ *   - G62: distinção ios-safari vs ios-other (Chrome iOS não instala)
+ *   - G63: in-app browsers checados ANTES de Android/iOS
+ */
+type Platform = 'android' | 'ios-safari' | 'ios-other' | 'in-app' | 'desktop' | 'unknown';
+type IOSBrowser = 'safari' | 'chrome' | 'firefox' | 'edge' | 'other';
+type AndroidBrowser = 'chrome' | 'firefox' | 'opera' | 'samsung' | 'edge' | 'other';
+type InAppApp = 'instagram' | 'facebook' | 'tiktok' | 'whatsapp' | 'twitter' | 'linkedin' | 'telegram' | 'line' | 'snapchat' | 'pinterest' | 'wechat' | 'other';
+type InstallVariant = 'android-native' | 'android-manual' | 'ios-safari' | 'ios-other' | 'in-app' | 'desktop' | 'none';
+interface BeforeInstallPromptEvent extends Event {
+    prompt: () => Promise<void>;
+    userChoice: Promise<{
+        outcome: 'accepted' | 'dismissed';
+        platform: string;
+    }>;
+}
+declare global {
+    interface Window {
+        __pwaInstallPrompt?: BeforeInstallPromptEvent | null;
+        posthog?: {
+            capture?: (event: string, props?: Record<string, unknown>) => void;
+        };
+    }
+}
+interface InstallState {
+    platform: Platform;
+    iosBrowser: IOSBrowser | null;
+    androidBrowser: AndroidBrowser | null;
+    inAppApp: InAppApp | null;
+    isInstallable: boolean;
+    isInstalled: boolean;
+    isDismissedSession: boolean;
+    isDismissedPermanent: boolean;
+    skipCount: number;
+    variant: InstallVariant;
+}
+interface InstallActions {
+    promptInstall: () => Promise<boolean>;
+    dismissSession: () => void;
+    dismissPermanent: () => void;
+    redirectToSafari: () => void;
+    copyLink: () => Promise<void>;
+    reset: () => void;
+}
+declare function detectPlatform(ua: string): Platform;
+declare function detectIOSBrowser(ua: string): IOSBrowser | null;
+declare function detectAndroidBrowser(ua: string): AndroidBrowser | null;
+declare function detectInAppApp(ua: string): InAppApp | null;
+declare function detectStandalone(): {
+    installed: boolean;
+    source: 'match_media' | 'navigator_standalone' | 'storage_marker' | null;
+};
+/**
+ * Hook principal. Passar o slug do app (usado pra namespacing de storage +
+ * analytics). Componentes do template pegam via useTemplateConfig().slug.
+ */
+declare function useInstallPrompt(slug: string): InstallState & InstallActions;
+/**
+ * Exposto pra InstallGate decidir se renderiza splash (não faz parte do hook
+ * retornado pra manter surface pequena — componente usa).
+ */
+declare function shouldBlockInstall(state: InstallState, now?: number): boolean;
+/**
+ * Exposto pra decidir se mostra "Não me pergunte mais".
+ */
+declare function shouldShowPermanentOption(state: InstallState): boolean;
+
+export { type AndroidBrowser, AppRoot, type AppRootProps, type AuthFormError, type AuthFormErrorCode, type AuthScreen, type AuthScreenProps, DefaultForgotScreen, DefaultLoginScreen, DefaultPaywall, DefaultResetScreen, DefaultSignupScreen, EmptyState, ErrorBoundary, type IOSBrowser, type InAppApp, type InstallActions, InstallGate, InstallSplash, type InstallState, type InstallVariant, LoadingState, type Platform, PushPrompt, type PushPromptProps, type PushPromptTexts, type PushUiState, type SubscriptionStatus, type ToastItem, type UseLoginFormResult, type UseResetFormResult, detectAndroidBrowser, detectIOSBrowser, detectInAppApp, detectPlatform, detectStandalone, shouldBlockInstall, shouldShowPermanentOption, useAuth, useAuthPrimitives, useForgotForm, useInstallPrompt, useLoginForm, usePaywallState, usePush, useReminders, useResetForm, useSignupForm, useSubscription, useToast };