@hook-sdk/template 0.18.0 → 0.19.0

package/dist/index.d.cts

@@ -55,6 +55,22 @@ type DeepLinks = {
     passwordReset?: string;
     emailVerify?: string;
 };
+type I18nConfig = {
+    defaultLocale: string;
+    supportedLocales: string[];
+    resources: Record<string, Record<string, string>>;
+};
+type InstallPromptConfig = {
+    /**
+     * Position of the InstallGate splash in the AppRoot render tree.
+     * - 'pre-auth': renders before AuthGate (legacy behavior up to template 0.18.x).
+     * - 'post-paywall': renders inside SubscriptionGate's children path,
+     *   only after the user is past the paywall (trialing/active/past_due).
+     *
+     * Default: 'post-paywall' (changed in template 0.19.0 — see ADR-017 amendment).
+     */
+    position?: 'pre-auth' | 'post-paywall';
+};
 type AppConfig = {
     slug: string;
     name: string;
@@ -75,8 +91,23 @@ type AppConfig = {
     persistedKeys: PersistedKey[];
     onboarding?: OnboardingConfig;
     deepLinks?: DeepLinks;
+    i18n?: I18nConfig;
     features_enabled?: string[];
+    install_prompt?: InstallPromptConfig;
     theme?: Record<string, unknown>;
+    /**
+     * G133 — Allowlist de keys em /app-data/* liberadas pré-paywall (read+write).
+     * Provisionado via `admin-register-app.ts` para `apps.public_app_data_keys`
+     * (column adicionada na migration 0044). Apps que não declarar usam canonical
+     * 6 (`onboarding_data`/`notifications`/`pending_unlocks`/`physical_baseline`/
+     * `preferences`/`user_progress`) pelo backfill da migration.
+     *
+     * Apps com keys próprias (ex: keniafitnesss usa `profile`,
+     * `<slug>_onboarding_buffer`, `workout_music_on`) precisam declarar aqui
+     * — sem isso, post-signup o SubscriptionGate 402's nesses keys e o user
+     * fica em loop visual no Paywall slot.
+     */
+    publicKeys?: string[];
 };
 
 interface AuthScreenProps {
@@ -149,8 +180,14 @@ declare function PushPrompt({ texts, onSubscribed, onDeclined, onInstallRequeste
 
 interface InstallGateProps {
     children: ReactNode;
+    /**
+     * Position of the gate in the AppRoot render tree.
+     * Forwarded to `pwa_install_splash_shown` analytics for funnel analysis.
+     * AppRoot reads `config.install_prompt?.position` and passes it here.
+     */
+    position?: 'pre-auth' | 'post-paywall';
 }
-declare function InstallGate({ children }: InstallGateProps): react_jsx_runtime.JSX.Element;
+declare function InstallGate({ children, position }: InstallGateProps): react_jsx_runtime.JSX.Element;
 
 interface InstallSplashProps {
     children: ReactNode;
@@ -159,6 +196,24 @@ interface InstallSplashProps {
 }
 declare function InstallSplash({ children, title, subtitle }: InstallSplashProps): react_jsx_runtime.JSX.Element;
 
+type LanguageSwitcherProps = {
+    /** Optional id for label association. */
+    id?: string;
+    /** Optional CSS class for app styling. */
+    className?: string;
+    /** Optional label text; defaults to 'Language'. */
+    label?: string;
+};
+declare function LanguageSwitcher({ id, className, label }: LanguageSwitcherProps): react_jsx_runtime.JSX.Element | null;
+
+interface I18nProviderProps {
+    defaultLocale: string;
+    supportedLocales: string[];
+    resources: Record<string, Record<string, string>>;
+    children: ReactNode;
+}
+declare function I18nProvider({ defaultLocale, supportedLocales, resources, children, }: I18nProviderProps): react_jsx_runtime.JSX.Element;
+
 declare function LoadingState({ message }: {
     message?: string;
 }): react_jsx_runtime.JSX.Element;
@@ -448,7 +503,7 @@ declare function usePlan(): PlanState;
  * Lovable→Hook: (a) strings hardcoded "R$ 19,90" no JSX, (b) divisões ad-hoc
  * por 100 + `toFixed(2)` que ignoram locale.
  *
- * Ver G72 em .claude/skills/lovable-to-hook/catalog/known-gotchas.md.
+ * Ver G72 em .claude/skills/hook-conversion-shared/catalog/known-gotchas.md.
  */
 /**
  * Formata centavos como BRL no locale pt-BR. Aceita null pra conveniência
@@ -723,7 +778,21 @@ declare function shouldBlockInstall(state: InstallState, now?: number): boolean;
  */
 declare function shouldShowPermanentOption(state: InstallState): boolean;
 
-declare function asaasErrorMessage(code: string): string;
+/**
+ * Map Asaas error → PT-BR user-facing message.
+ *
+ * Two inputs because backend folds Asaas's specific error code into a
+ * compound code (`payments.capture_card.tokenize_failed:invalid_holderInfo`)
+ * and only the *description* string ("O CEP informado é inválido.")
+ * distinguishes between sub-cases of `invalid_holderInfo` (CEP, phone, name).
+ *
+ * Asaas keeps a snapshot of Correios CEPs that lags real registrations by
+ * months — CEPs of recently-cadastrated streets (ex: bairros novos) get
+ * rejected even though they're valid in ViaCEP/BrasilAPI. We don't suggest
+ * a fictitious CEP (would mess up nota fiscal/comms); we explain the issue
+ * is on the processor's side and ask user to try a nearby street's CEP.
+ */
+declare function asaasErrorMessage(code: string, description?: string): string;
 
 type RouteBoundaryProps = {
     children: ReactNode;
@@ -864,9 +933,21 @@ declare const AppConfigSchema: z.ZodObject<{
         passwordReset: z.ZodOptional<z.ZodString>;
         emailVerify: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;
+    i18n: z.ZodOptional<z.ZodObject<{
+        defaultLocale: z.ZodString;
+        supportedLocales: z.ZodArray<z.ZodString>;
+        resources: z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strict>>;
     features_enabled: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    install_prompt: z.ZodOptional<z.ZodObject<{
+        position: z.ZodOptional<z.ZodEnum<{
+            "pre-auth": "pre-auth";
+            "post-paywall": "post-paywall";
+        }>>;
+    }, z.core.$strict>>;
     theme: z.ZodOptional<z.ZodObject<{}, z.core.$loose>>;
+    publicKeys: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strict>;
 declare function parseAppConfig(input: unknown): AppConfig;
 
-export { type AndroidBrowser, type AppConfig, AppConfigProvider, AppConfigSchema, AppRoot, type AppRootProps, type AppRootSlots, type AuthFlowConfig, type AuthFormError, type AuthFormErrorCode, type AuthScreenProps, type CheckoutMethod, type Cycle, DeepLinkHandler, type DeepLinks, EmptyState, ErrorBoundary, type IOSBrowser, type InAppApp, type InstallActions, InstallGate, InstallSplash, type InstallState, type InstallVariant, LoadingState, type OnboardingConfig, OnboardingFlow, type OnboardingFlowProps, type OnboardingStep, type OnboardingStepCtx, type OnboardingStepDef, type PaymentMethod, PaymentReturnHandler, type PaywallConfig, type PersistedKey, PersistenceRegistry, type PersistenceRegistryProps, type PixPending, type Platform, PreAuthShell, type PreAuthShellProps, PushPrompt, type PushPromptProps, type PushPromptTexts, type PushUiState, RouteBoundary, type RouteBoundaryProps, type SubscriptionStatus, type ToastItem, type UseLoginFormResult, type UseResetFormResult, asaasErrorMessage, computeAnchorCents, dailyFromYearly, detectAndroidBrowser, detectIOSBrowser, detectInAppApp, detectPlatform, detectStandalone, discountPercent, formatBRL, monthlyFromYearly, parseAppConfig, shouldBlockInstall, shouldShowPermanentOption, useAppConfig, useAuth, useAuthPrimitives, useFeature, useForgotForm, useInstallPrompt, useLoginForm, useOnboardingStep, usePaywallState, usePlan, usePush, useReminders, useResetForm, useSignupForm, useSubscription, useToast };
+export { type AndroidBrowser, type AppConfig, AppConfigProvider, AppConfigSchema, AppRoot, type AppRootProps, type AppRootSlots, type AuthFlowConfig, type AuthFormError, type AuthFormErrorCode, type AuthScreenProps, type CheckoutMethod, type Cycle, DeepLinkHandler, type DeepLinks, EmptyState, ErrorBoundary, type I18nConfig, I18nProvider, type I18nProviderProps, type IOSBrowser, type InAppApp, type InstallActions, InstallGate, InstallSplash, type InstallState, type InstallVariant, LanguageSwitcher, type LanguageSwitcherProps, LoadingState, type OnboardingConfig, OnboardingFlow, type OnboardingFlowProps, type OnboardingStep, type OnboardingStepCtx, type OnboardingStepDef, type PaymentMethod, PaymentReturnHandler, type PaywallConfig, type PersistedKey, PersistenceRegistry, type PersistenceRegistryProps, type PixPending, type Platform, PreAuthShell, type PreAuthShellProps, PushPrompt, type PushPromptProps, type PushPromptTexts, type PushUiState, RouteBoundary, type RouteBoundaryProps, type SubscriptionStatus, type ToastItem, type UseLoginFormResult, type UseResetFormResult, asaasErrorMessage, computeAnchorCents, dailyFromYearly, detectAndroidBrowser, detectIOSBrowser, detectInAppApp, detectPlatform, detectStandalone, discountPercent, formatBRL, monthlyFromYearly, parseAppConfig, shouldBlockInstall, shouldShowPermanentOption, useAppConfig, useAuth, useAuthPrimitives, useFeature, useForgotForm, useInstallPrompt, useLoginForm, useOnboardingStep, usePaywallState, usePlan, usePush, useReminders, useResetForm, useSignupForm, useSubscription, useToast };

package/dist/index.d.ts

@@ -55,6 +55,22 @@ type DeepLinks = {
     passwordReset?: string;
     emailVerify?: string;
 };
+type I18nConfig = {
+    defaultLocale: string;
+    supportedLocales: string[];
+    resources: Record<string, Record<string, string>>;
+};
+type InstallPromptConfig = {
+    /**
+     * Position of the InstallGate splash in the AppRoot render tree.
+     * - 'pre-auth': renders before AuthGate (legacy behavior up to template 0.18.x).
+     * - 'post-paywall': renders inside SubscriptionGate's children path,
+     *   only after the user is past the paywall (trialing/active/past_due).
+     *
+     * Default: 'post-paywall' (changed in template 0.19.0 — see ADR-017 amendment).
+     */
+    position?: 'pre-auth' | 'post-paywall';
+};
 type AppConfig = {
     slug: string;
     name: string;
@@ -75,8 +91,23 @@ type AppConfig = {
     persistedKeys: PersistedKey[];
     onboarding?: OnboardingConfig;
     deepLinks?: DeepLinks;
+    i18n?: I18nConfig;
     features_enabled?: string[];
+    install_prompt?: InstallPromptConfig;
     theme?: Record<string, unknown>;
+    /**
+     * G133 — Allowlist de keys em /app-data/* liberadas pré-paywall (read+write).
+     * Provisionado via `admin-register-app.ts` para `apps.public_app_data_keys`
+     * (column adicionada na migration 0044). Apps que não declarar usam canonical
+     * 6 (`onboarding_data`/`notifications`/`pending_unlocks`/`physical_baseline`/
+     * `preferences`/`user_progress`) pelo backfill da migration.
+     *
+     * Apps com keys próprias (ex: keniafitnesss usa `profile`,
+     * `<slug>_onboarding_buffer`, `workout_music_on`) precisam declarar aqui
+     * — sem isso, post-signup o SubscriptionGate 402's nesses keys e o user
+     * fica em loop visual no Paywall slot.
+     */
+    publicKeys?: string[];
 };
 
 interface AuthScreenProps {
@@ -149,8 +180,14 @@ declare function PushPrompt({ texts, onSubscribed, onDeclined, onInstallRequeste
 
 interface InstallGateProps {
     children: ReactNode;
+    /**
+     * Position of the gate in the AppRoot render tree.
+     * Forwarded to `pwa_install_splash_shown` analytics for funnel analysis.
+     * AppRoot reads `config.install_prompt?.position` and passes it here.
+     */
+    position?: 'pre-auth' | 'post-paywall';
 }
-declare function InstallGate({ children }: InstallGateProps): react_jsx_runtime.JSX.Element;
+declare function InstallGate({ children, position }: InstallGateProps): react_jsx_runtime.JSX.Element;
 
 interface InstallSplashProps {
     children: ReactNode;
@@ -159,6 +196,24 @@ interface InstallSplashProps {
 }
 declare function InstallSplash({ children, title, subtitle }: InstallSplashProps): react_jsx_runtime.JSX.Element;
 
+type LanguageSwitcherProps = {
+    /** Optional id for label association. */
+    id?: string;
+    /** Optional CSS class for app styling. */
+    className?: string;
+    /** Optional label text; defaults to 'Language'. */
+    label?: string;
+};
+declare function LanguageSwitcher({ id, className, label }: LanguageSwitcherProps): react_jsx_runtime.JSX.Element | null;
+
+interface I18nProviderProps {
+    defaultLocale: string;
+    supportedLocales: string[];
+    resources: Record<string, Record<string, string>>;
+    children: ReactNode;
+}
+declare function I18nProvider({ defaultLocale, supportedLocales, resources, children, }: I18nProviderProps): react_jsx_runtime.JSX.Element;
+
 declare function LoadingState({ message }: {
     message?: string;
 }): react_jsx_runtime.JSX.Element;
@@ -448,7 +503,7 @@ declare function usePlan(): PlanState;
  * Lovable→Hook: (a) strings hardcoded "R$ 19,90" no JSX, (b) divisões ad-hoc
  * por 100 + `toFixed(2)` que ignoram locale.
  *
- * Ver G72 em .claude/skills/lovable-to-hook/catalog/known-gotchas.md.
+ * Ver G72 em .claude/skills/hook-conversion-shared/catalog/known-gotchas.md.
  */
 /**
  * Formata centavos como BRL no locale pt-BR. Aceita null pra conveniência
@@ -723,7 +778,21 @@ declare function shouldBlockInstall(state: InstallState, now?: number): boolean;
  */
 declare function shouldShowPermanentOption(state: InstallState): boolean;
 
-declare function asaasErrorMessage(code: string): string;
+/**
+ * Map Asaas error → PT-BR user-facing message.
+ *
+ * Two inputs because backend folds Asaas's specific error code into a
+ * compound code (`payments.capture_card.tokenize_failed:invalid_holderInfo`)
+ * and only the *description* string ("O CEP informado é inválido.")
+ * distinguishes between sub-cases of `invalid_holderInfo` (CEP, phone, name).
+ *
+ * Asaas keeps a snapshot of Correios CEPs that lags real registrations by
+ * months — CEPs of recently-cadastrated streets (ex: bairros novos) get
+ * rejected even though they're valid in ViaCEP/BrasilAPI. We don't suggest
+ * a fictitious CEP (would mess up nota fiscal/comms); we explain the issue
+ * is on the processor's side and ask user to try a nearby street's CEP.
+ */
+declare function asaasErrorMessage(code: string, description?: string): string;
 
 type RouteBoundaryProps = {
     children: ReactNode;
@@ -864,9 +933,21 @@ declare const AppConfigSchema: z.ZodObject<{
         passwordReset: z.ZodOptional<z.ZodString>;
         emailVerify: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;
+    i18n: z.ZodOptional<z.ZodObject<{
+        defaultLocale: z.ZodString;
+        supportedLocales: z.ZodArray<z.ZodString>;
+        resources: z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strict>>;
     features_enabled: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    install_prompt: z.ZodOptional<z.ZodObject<{
+        position: z.ZodOptional<z.ZodEnum<{
+            "pre-auth": "pre-auth";
+            "post-paywall": "post-paywall";
+        }>>;
+    }, z.core.$strict>>;
     theme: z.ZodOptional<z.ZodObject<{}, z.core.$loose>>;
+    publicKeys: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strict>;
 declare function parseAppConfig(input: unknown): AppConfig;
 
-export { type AndroidBrowser, type AppConfig, AppConfigProvider, AppConfigSchema, AppRoot, type AppRootProps, type AppRootSlots, type AuthFlowConfig, type AuthFormError, type AuthFormErrorCode, type AuthScreenProps, type CheckoutMethod, type Cycle, DeepLinkHandler, type DeepLinks, EmptyState, ErrorBoundary, type IOSBrowser, type InAppApp, type InstallActions, InstallGate, InstallSplash, type InstallState, type InstallVariant, LoadingState, type OnboardingConfig, OnboardingFlow, type OnboardingFlowProps, type OnboardingStep, type OnboardingStepCtx, type OnboardingStepDef, type PaymentMethod, PaymentReturnHandler, type PaywallConfig, type PersistedKey, PersistenceRegistry, type PersistenceRegistryProps, type PixPending, type Platform, PreAuthShell, type PreAuthShellProps, PushPrompt, type PushPromptProps, type PushPromptTexts, type PushUiState, RouteBoundary, type RouteBoundaryProps, type SubscriptionStatus, type ToastItem, type UseLoginFormResult, type UseResetFormResult, asaasErrorMessage, computeAnchorCents, dailyFromYearly, detectAndroidBrowser, detectIOSBrowser, detectInAppApp, detectPlatform, detectStandalone, discountPercent, formatBRL, monthlyFromYearly, parseAppConfig, shouldBlockInstall, shouldShowPermanentOption, useAppConfig, useAuth, useAuthPrimitives, useFeature, useForgotForm, useInstallPrompt, useLoginForm, useOnboardingStep, usePaywallState, usePlan, usePush, useReminders, useResetForm, useSignupForm, useSubscription, useToast };
+export { type AndroidBrowser, type AppConfig, AppConfigProvider, AppConfigSchema, AppRoot, type AppRootProps, type AppRootSlots, type AuthFlowConfig, type AuthFormError, type AuthFormErrorCode, type AuthScreenProps, type CheckoutMethod, type Cycle, DeepLinkHandler, type DeepLinks, EmptyState, ErrorBoundary, type I18nConfig, I18nProvider, type I18nProviderProps, type IOSBrowser, type InAppApp, type InstallActions, InstallGate, InstallSplash, type InstallState, type InstallVariant, LanguageSwitcher, type LanguageSwitcherProps, LoadingState, type OnboardingConfig, OnboardingFlow, type OnboardingFlowProps, type OnboardingStep, type OnboardingStepCtx, type OnboardingStepDef, type PaymentMethod, PaymentReturnHandler, type PaywallConfig, type PersistedKey, PersistenceRegistry, type PersistenceRegistryProps, type PixPending, type Platform, PreAuthShell, type PreAuthShellProps, PushPrompt, type PushPromptProps, type PushPromptTexts, type PushUiState, RouteBoundary, type RouteBoundaryProps, type SubscriptionStatus, type ToastItem, type UseLoginFormResult, type UseResetFormResult, asaasErrorMessage, computeAnchorCents, dailyFromYearly, detectAndroidBrowser, detectIOSBrowser, detectInAppApp, detectPlatform, detectStandalone, discountPercent, formatBRL, monthlyFromYearly, parseAppConfig, shouldBlockInstall, shouldShowPermanentOption, useAppConfig, useAuth, useAuthPrimitives, useFeature, useForgotForm, useInstallPrompt, useLoginForm, useOnboardingStep, usePaywallState, usePlan, usePush, useReminders, useResetForm, useSignupForm, useSubscription, useToast };