@rocapine/react-native-onboarding 1.0.0

package/src/infra/hooks/useOnboardingStep.ts

@@ -0,0 +1,66 @@
+import { useCallback, useContext } from "react";
+import { useSuspenseQuery } from "@tanstack/react-query";
+import { useFocusEffect } from "expo-router";
+import { OnboardingProgressContext } from "../provider/OnboardingProvider";
+import { getOnboardingQuery } from "../queries/getOnboarding.query";
+import { BaseStepType, Onboarding, OnboardingMetadata } from "../../types";
+import { OnboardingStepType } from "../../steps/types";
+
+export const useOnboardingStep = <
+  StepType extends BaseStepType = OnboardingStepType
+>({
+  stepNumber,
+}: {
+  stepNumber: number;
+}): {
+  step: StepType;
+  isLastStep: boolean;
+  stepsLength: number;
+  onboardingMetadata: OnboardingMetadata;
+  steps: StepType[];
+} => {
+  // Get all config from context
+  const {
+    client,
+    locale,
+    customAudienceParams,
+    setActiveStep,
+    setTotalSteps,
+    setOnboarding,
+  } = useContext(OnboardingProgressContext);
+
+  // Build query with config from context
+  const { data } = useSuspenseQuery<Onboarding<StepType>>(
+    getOnboardingQuery<StepType>(
+      client,
+      locale,
+      customAudienceParams,
+      setOnboarding as (onboarding: Onboarding<StepType>) => void
+    )
+  );
+  const steps = data.steps;
+  const onboardingMetadata = data.metadata;
+
+  useFocusEffect(
+    useCallback(() => {
+      const currentStep = steps[stepNumber - 1];
+      setActiveStep({
+        number: stepNumber,
+        displayProgressHeader: currentStep?.displayProgressHeader ?? true,
+      });
+      setTotalSteps(steps.length);
+    }, [stepNumber, steps, setActiveStep, setTotalSteps])
+  );
+
+  const step = steps[stepNumber - 1];
+  const isLastStep = stepNumber >= steps.length;
+  const stepsLength = steps.length;
+
+  return {
+    step,
+    isLastStep,
+    stepsLength,
+    onboardingMetadata,
+    steps,
+  };
+};

package/src/infra/index.ts

@@ -0,0 +1,2 @@
+export * from "./provider";
+export * from "./hooks";

package/src/infra/provider/OnboardingProvider.tsx

@@ -0,0 +1,80 @@
+import { createContext, useState } from "react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { OnboardingStudioClient } from "../../OnboardingStudioClient";
+import { getOnboardingQuery } from "../queries/getOnboarding.query";
+import { Onboarding } from "../../types";
+import { OnboardingStepType } from "../../steps/types";
+
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: Infinity,
+    },
+  },
+})
+
+interface OnboardingProviderProps {
+  children: React.ReactNode;
+  client: OnboardingStudioClient;
+  locale?: string;
+  customAudienceParams?: Record<string, any>;
+}
+
+export const OnboardingProvider = ({
+  children,
+  client,
+  locale = "en",
+  customAudienceParams = {},
+}: OnboardingProviderProps) => {
+  const [activeStep, setActiveStep] = useState({
+    number: 0,
+    displayProgressHeader: false,
+  });
+  const [totalSteps, setTotalSteps] = useState(0);
+  const [onboarding, setOnboarding] = useState<Onboarding<OnboardingStepType> | null>(null);
+
+  queryClient.prefetchQuery(getOnboardingQuery(client, locale, customAudienceParams, setOnboarding))
+
+  return (
+    <QueryClientProvider client={queryClient}>
+
+      <OnboardingProgressContext.Provider
+        value={{
+          activeStep,
+          setActiveStep,
+          totalSteps,
+          setTotalSteps,
+          client,
+          locale,
+          customAudienceParams,
+          onboarding,
+          setOnboarding,
+        }}
+      >
+        {children}
+      </OnboardingProgressContext.Provider>
+    </QueryClientProvider>
+  );
+};
+
+export const OnboardingProgressContext = createContext<{
+  activeStep: { number: number; displayProgressHeader: boolean };
+  setActiveStep: (step: { number: number; displayProgressHeader: boolean }) => void;
+  totalSteps: number;
+  setTotalSteps: (steps: number) => void;
+  client: OnboardingStudioClient;
+  locale: string;
+  customAudienceParams: Record<string, any>;
+  onboarding: Onboarding<OnboardingStepType> | null;
+  setOnboarding: (onboarding: Onboarding<OnboardingStepType>) => void;
+}>({
+  activeStep: { number: 0, displayProgressHeader: false },
+  setActiveStep: () => { },
+  totalSteps: 0,
+  setTotalSteps: () => { },
+  client: new OnboardingStudioClient('', {}),
+  locale: "en",
+  customAudienceParams: {},
+  onboarding: null,
+  setOnboarding: () => { },
+});

package/src/infra/provider/index.ts

@@ -0,0 +1,4 @@
+export {
+  OnboardingProvider,
+  OnboardingProgressContext,
+} from "./OnboardingProvider";

package/src/infra/queries/getOnboarding.query.ts

@@ -0,0 +1,58 @@
+import AsyncStorage from "@react-native-async-storage/async-storage";
+import { OnboardingStudioClient } from "../../OnboardingStudioClient";
+import { BaseStepType, Onboarding, OnboardingMetadata } from "../../types";
+import type { UseQueryOptions } from "@tanstack/react-query";
+
+const cacheKey = "rocapine-onboarding-studio";
+
+export const getOnboardingQuery = <StepType extends BaseStepType>(
+  client: OnboardingStudioClient,
+  locale: string,
+  customAudienceParams: Record<string, any>,
+  setOnboarding?: (onboarding: Onboarding<StepType>) => void
+) => {
+  return {
+    queryKey: [
+      "onboardingQuestions",
+      client.projectId,
+      client.options.isSandbox,
+      client.options.baseUrl,
+      locale,
+      JSON.stringify(customAudienceParams),
+    ],
+    queryFn: async (): Promise<Onboarding<StepType>> => {
+      // Try to get data from AsyncStorage first for production
+      if (!(client?.options?.isSandbox || false)) {
+        try {
+          const cachedData = await AsyncStorage.getItem(cacheKey);
+          if (cachedData) {
+            setOnboarding && setOnboarding(JSON.parse(cachedData));
+            return JSON.parse(cachedData);
+          }
+        } catch (error) {
+          console.warn("Failed to load cached onboarding questions:", error);
+        }
+      }
+
+      // Fetch from API
+      const { data, headers } = await client!.getSteps<StepType>(
+        { locale },
+        customAudienceParams
+      );
+
+      console.info("onbs-onboarding-name", headers["ONBS-Onboarding-Name"]);
+      console.info("onbs-onboarding-id", headers["ONBS-Onboarding-Id"]);
+      setOnboarding && setOnboarding(data);
+
+      // Cache the steps
+      try {
+        await AsyncStorage.setItem(cacheKey, JSON.stringify(data));
+      } catch (error) {
+        console.warn("Failed to cache onboarding questions:", error);
+      }
+
+      return data;
+    },
+    staleTime: Infinity,
+  };
+};

package/src/steps/Carousel/types.ts

@@ -0,0 +1,26 @@
+import { z } from "zod";
+import { CustomPayloadSchema } from "../common.types";
+
+export const CarouselScreenSchema = z.object({
+  mediaUrl: z.string(),
+  title: z.string(),
+  subtitle: z.string().nullish(),
+});
+
+export const CarouselStepPayloadSchema = z.object({
+  screens: z.array(CarouselScreenSchema),
+});
+
+export const CarouselStepTypeSchema = z.object({
+  id: z.string(),
+  type: z.literal("Carousel"),
+  name: z.string(),
+  displayProgressHeader: z.boolean(),
+  payload: CarouselStepPayloadSchema,
+  customPayload: CustomPayloadSchema,
+  continueButtonLabel: z.string().optional().default("Continue"),
+  figmaUrl: z.string().nullish(),
+});
+
+export type CarouselStepType = z.infer<typeof CarouselStepTypeSchema>;
+export type CarouselScreenType = z.infer<typeof CarouselScreenSchema>;

package/src/steps/Commitment/types.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+import { CustomPayloadSchema } from "../common.types";
+
+export const CommitmentItemSchema = z.object({
+  text: z.string(),
+});
+
+export const CommitmentStepPayloadSchema = z.object({
+  title: z.string(),
+  subtitle: z.string().nullish(),
+  description: z.string().nullish(),
+  commitments: z.array(CommitmentItemSchema).nullish(),
+  signatureCaption: z.string().default("Your signature is not recorded"),
+  variant: z.enum(["signature", "simple"]).default("signature"),
+});
+
+export const CommitmentStepTypeSchema = z.object({
+  id: z.string(),
+  type: z.literal("Commitment"),
+  name: z.string(),
+  displayProgressHeader: z.boolean(),
+  payload: CommitmentStepPayloadSchema,
+  customPayload: CustomPayloadSchema,
+  continueButtonLabel: z.string().optional().default("Continue"),
+  figmaUrl: z.string().nullish(),
+});
+
+export type CommitmentStepType = z.infer<typeof CommitmentStepTypeSchema>;

package/src/steps/Loader/types.ts

@@ -0,0 +1,32 @@
+import { z } from "zod";
+import { CustomPayloadSchema, MediaSourceSchema } from "../common.types";
+
+export const LoaderStepSchema = z.object({
+  label: z.string(),
+  completed: z.string(),
+});
+
+export const LoaderStepPayloadSchema = z.object({
+  title: z.string(),
+  steps: z.array(LoaderStepSchema),
+  didYouKnowImages: z.array(MediaSourceSchema).nullish(),
+  duration: z.number().optional().default(2000),
+  variant: z
+    .enum(["bars", "circle", "texts_fading"])
+    .optional()
+    .default("bars"),
+});
+
+export const LoaderStepTypeSchema = z.object({
+  id: z.string(),
+  type: z.literal("Loader"),
+  name: z.string(),
+  displayProgressHeader: z.boolean(),
+  payload: LoaderStepPayloadSchema,
+  customPayload: CustomPayloadSchema,
+  continueButtonLabel: z.string().optional().default("Continue"),
+  figmaUrl: z.string().nullish(),
+});
+
+export type LoaderStepType = z.infer<typeof LoaderStepTypeSchema>;
+export type LoaderStep = z.infer<typeof LoaderStepSchema>;

package/src/steps/MediaContent/types.ts

@@ -0,0 +1,26 @@
+import { z } from "zod";
+import {
+  CustomPayloadSchema,
+  MediaSourceSchema,
+  SocialProofSchema,
+} from "../common.types";
+
+export const MediaContentStepPayloadSchema = z.object({
+  mediaSource: MediaSourceSchema,
+  title: z.string(),
+  description: z.string().nullish(),
+  socialProof: SocialProofSchema.nullish(),
+});
+
+export const MediaContentStepTypeSchema = z.object({
+  id: z.string(),
+  type: z.literal("MediaContent"),
+  name: z.string(),
+  displayProgressHeader: z.boolean(),
+  payload: MediaContentStepPayloadSchema,
+  customPayload: CustomPayloadSchema,
+  continueButtonLabel: z.string().optional().default("Continue"),
+  figmaUrl: z.string().nullish(),
+});
+
+export type MediaContentStepType = z.infer<typeof MediaContentStepTypeSchema>;

package/src/steps/Picker/types.ts

@@ -0,0 +1,34 @@
+import { z } from "zod";
+import { CustomPayloadSchema } from "../common.types";
+
+export const PickerTypeEnum = z.enum([
+  "height",
+  "weight",
+  "age",
+  "date",
+  "gender",
+  "coach",
+  "name",
+]);
+
+export const PickerStepPayloadSchema = z.object({
+  title: z.string(),
+  description: z.string().nullish(),
+  pickerType: z.union([PickerTypeEnum, z.string()]),
+});
+
+export const PickerStepTypeSchema = z.object({
+  id: z.string(),
+  type: z.literal("Picker"),
+  name: z.string(),
+  displayProgressHeader: z.boolean(),
+  payload: PickerStepPayloadSchema,
+  customPayload: CustomPayloadSchema,
+  continueButtonLabel: z.string().optional().default("Continue"),
+  figmaUrl: z.string().nullish(),
+});
+
+export type PickerStepType = z.infer<typeof PickerStepTypeSchema>;
+
+export type WeightUnit = "kg" | "lb";
+export type HeightUnit = "cm" | "ft";

package/src/steps/Question/types.ts

@@ -0,0 +1,29 @@
+import { z } from "zod";
+import { CustomPayloadSchema, InfoBoxSchema } from "../common.types";
+
+export const AnswerSchema = z.object({
+  label: z.string(),
+  value: z.string(),
+  icon: z.string().nullish(),
+  description: z.string().nullish(),
+});
+
+export const QuestionStepPayloadSchema = z.object({
+  answers: z.array(AnswerSchema),
+  title: z.string(),
+  subtitle: z.string().nullish(),
+  multipleAnswer: z.boolean(),
+  infoBox: InfoBoxSchema.nullish(),
+});
+
+export const QuestionStepTypeSchema = z.object({
+  id: z.string(),
+  type: z.literal("Question"),
+  name: z.string(),
+  displayProgressHeader: z.boolean(),
+  payload: QuestionStepPayloadSchema,
+  customPayload: CustomPayloadSchema,
+  figmaUrl: z.string().nullish(),
+});
+
+export type QuestionStepType = z.infer<typeof QuestionStepTypeSchema>;

package/src/steps/Ratings/types.ts

@@ -0,0 +1,22 @@
+import z from "zod";
+import { CustomPayloadSchema, SocialProofSchema } from "../common.types";
+
+export const RatingsStepPayloadSchema = z.object({
+  title: z.string(),
+  subtitle: z.string(),
+  socialProofs: z.array(SocialProofSchema),
+  rateTheAppButtonLabel: z.string().optional().default("Rate the app"),
+});
+
+export const RatingsStepTypeSchema = z.object({
+  id: z.string(),
+  type: z.literal("Ratings"),
+  name: z.string(),
+  displayProgressHeader: z.boolean(),
+  payload: RatingsStepPayloadSchema,
+  customPayload: CustomPayloadSchema,
+  continueButtonLabel: z.string().optional().default("Continue"),
+  figmaUrl: z.string().nullish(),
+});
+
+export type RatingsStepType = z.infer<typeof RatingsStepTypeSchema>;

package/src/steps/common.types.ts

@@ -0,0 +1,25 @@
+import { z } from "zod";
+
+export const CustomPayloadSchema = z.record(z.string(), z.any()).nullish();
+
+export const MediaSourceSchema = z.union([
+  z.object({
+    type: z.literal("image").or(z.literal("lottie")).or(z.literal("rive")),
+    localPathId: z.string(),
+  }),
+  z.object({
+    type: z.literal("image").or(z.literal("lottie")).or(z.literal("rive")),
+    url: z.string(),
+  }),
+]);
+
+export const SocialProofSchema = z.object({
+  numberOfStar: z.number(),
+  content: z.string(),
+  authorName: z.string(),
+});
+
+export const InfoBoxSchema = z.object({
+  title: z.string(),
+  content: z.string(),
+});

package/src/steps/types.ts

@@ -0,0 +1,16 @@
+import { CarouselStepType } from "./Carousel/types";
+import { CommitmentStepType } from "./Commitment/types";
+import { LoaderStepType } from "./Loader/types";
+import { MediaContentStepType } from "./MediaContent/types";
+import { PickerStepType } from "./Picker/types";
+import { QuestionStepType } from "./Question/types";
+import { RatingsStepType } from "./Ratings/types";
+
+export type OnboardingStepType =
+  | CarouselStepType
+  | CommitmentStepType
+  | LoaderStepType
+  | MediaContentStepType
+  | PickerStepType
+  | QuestionStepType
+  | RatingsStepType;

package/src/types.ts

@@ -0,0 +1,51 @@
+/**
+ * Base step type that all onboarding steps must conform to.
+ * This is the minimal interface required by the headless SDK.
+ */
+export type BaseStepType = {
+  id: string;
+  type: string;
+  name: string;
+  displayProgressHeader?: boolean;
+  payload?: any;
+  customPayload?: any;
+  continueButtonLabel?: string;
+  figmaUrl?: string | null;
+};
+
+export type OnboardingStudioClientOptions<StepType extends BaseStepType = BaseStepType> = {
+  appVersion?: string;
+  isSandbox?: boolean;
+  baseUrl?: string;
+  fallbackOnboarding?: Onboarding<StepType>;
+};
+
+export type OnboardingOptions = {
+  locale?: string;
+};
+
+export type UserDefinedParams = {
+  [key: string]: string;
+};
+
+export interface OnboardingMetadata {
+  id: string;
+  name?: string;
+  audienceId?: string;
+  audienceName?: string;
+  audienceOrder?: number;
+  locale?: string;
+  draft?: boolean;
+}
+
+export interface Onboarding<StepType extends BaseStepType = BaseStepType> {
+  metadata: OnboardingMetadata;
+  steps: StepType[];
+  configuration: any;
+}
+
+export interface GetStepsResponseHeaders {
+  "ONBS-Onboarding-Id": string | null;
+  "ONBS-Audience-Id": string | null;
+  "ONBS-Onboarding-Name": string | null;
+}