@phygitallabs/phygital-consent 1.0.0

package/src/components/CookieConsentBanner.tsx

@@ -0,0 +1,163 @@
+"use client";
+
+import { useState } from "react";
+import { setConsentPreferenceCookie } from "../helpers/cookie";
+import { useCreateDeviceCookieConsent } from "../hooks/useConsent";
+
+const PREFERENCES = ["essential", "analytics", "advertising"] as const;
+
+const MOCK_CONTENT = {
+  title: "Cookie preferences",
+  description:
+    "We use cookies to improve your experience, remember your settings, and understand how you use our site. You can accept all, or reject non-essential cookies.",
+  essentialLabel: "Essential",
+  essentialDesc: "Required for the site to work (e.g. security, preferences).",
+  analyticsLabel: "Analytics",
+  analyticsDesc: "Help us improve by collecting anonymous usage data.",
+  advertisingLabel: "Advertising",
+  advertisingDesc: "Used to show you relevant ads and measure campaigns.",
+};
+
+export interface CookieConsentBannerProps {
+  /** Device ID (consumer app must provide; will be hashed by app before API if required). */
+  deviceId: string;
+  /** Called after consent is submitted successfully (Reject or Accept). */
+  onSubmitted?: () => void;
+  /** Called when the banner is dismissed (e.g. hide from UI). */
+  onDismiss?: () => void;
+  /** Optional class name for the root container. */
+  className?: string;
+}
+
+export function CookieConsentBanner({
+  deviceId,
+  onSubmitted,
+  onDismiss,
+  className = "",
+}: CookieConsentBannerProps) {
+  const [dismissed, setDismissed] = useState(false);
+
+  const createConsent = useCreateDeviceCookieConsent({
+    onSuccess: (_data, variables) => {
+      setConsentPreferenceCookie(deviceId, variables.selected_preferences ?? []);
+      onSubmitted?.();
+      onDismiss?.();
+      setDismissed(true);
+    },
+  });
+
+  const handleReject = () => {
+    createConsent.mutate({
+      device_id: deviceId,
+      status: "REJECTED",
+      selected_preferences: ["essential"],
+    });
+  };
+
+  const handleAccept = () => {
+    createConsent.mutate({
+      device_id: deviceId,
+      status: "ACCEPTED",
+      selected_preferences: [...PREFERENCES],
+    });
+  };
+
+  if (dismissed) return null;
+
+  return (
+    <div
+      role="dialog"
+      aria-label={MOCK_CONTENT.title}
+      className={`consent:fixed consent:bottom-0 consent:left-0 consent:right-0 consent:z-50 consent:flex consent:flex-col consent:gap-4 consent:rounded-t-xl consent:border consent:border-b-0 consent:border-gray-200 consent:bg-white consent:p-4 consent:shadow-lg consent:md:left-4 consent:md:right-auto consent:md:bottom-4 consent:md:max-w-md consent:md:rounded-xl consent:md:border consent:md:border-gray-200 ${className}`}
+      style={{
+        position: "fixed",
+        bottom: 0,
+        left: 0,
+        right: 0,
+        zIndex: 50,
+        display: "flex",
+        flexDirection: "column",
+        gap: "1rem",
+        borderRadius: "0.75rem 0.75rem 0 0",
+        borderWidth: "1px 1px 0 1px",
+        borderColor: "#e5e7eb",
+        backgroundColor: "#fff",
+        padding: "1rem",
+        boxShadow: "0 -4px 6px -1px rgb(0 0 0 / 0.1)",
+      }}
+    >
+      <h2
+        className="consent:text-lg consent:font-semibold consent:text-gray-900"
+        style={{ fontSize: "1.125rem", fontWeight: 600, color: "#111827" }}
+      >
+        {MOCK_CONTENT.title}
+      </h2>
+      <p
+        className="consent:text-sm consent:text-gray-600"
+        style={{ fontSize: "0.875rem", color: "#4b5563" }}
+      >
+        {MOCK_CONTENT.description}
+      </p>
+      <ul
+        className="consent:text-sm consent:text-gray-600 consent:space-y-2"
+        style={{ fontSize: "0.875rem", color: "#4b5563", margin: 0, paddingLeft: "1.25rem" }}
+      >
+        <li>
+          <strong>{MOCK_CONTENT.essentialLabel}</strong> — {MOCK_CONTENT.essentialDesc}
+        </li>
+        <li>
+          <strong>{MOCK_CONTENT.analyticsLabel}</strong> — {MOCK_CONTENT.analyticsDesc}
+        </li>
+        <li>
+          <strong>{MOCK_CONTENT.advertisingLabel}</strong> — {MOCK_CONTENT.advertisingDesc}
+        </li>
+      </ul>
+      <div
+        className="consent:flex consent:flex-wrap consent:gap-2"
+        style={{ display: "flex", flexWrap: "wrap", gap: "0.5rem" }}
+      >
+        <button
+          type="button"
+          onClick={handleReject}
+          disabled={createConsent.isPending}
+          className="consent:rounded-lg consent:border consent:border-gray-300 consent:bg-white consent:px-4 consent:py-2 consent:text-sm consent:font-medium consent:text-gray-700 consent:shadow-sm hover:consent:bg-gray-50 disabled:consent:opacity-50"
+          style={{
+            borderRadius: "0.5rem",
+            border: "1px solid #d1d5db",
+            background: "#fff",
+            padding: "0.5rem 1rem",
+            fontSize: "0.875rem",
+            fontWeight: 500,
+            color: "#374151",
+          }}
+        >
+          Reject
+        </button>
+        <button
+          type="button"
+          onClick={handleAccept}
+          disabled={createConsent.isPending}
+          className="consent:rounded-lg consent:bg-gray-900 consent:px-4 consent:py-2 consent:text-sm consent:font-medium consent:text-white consent:shadow-sm hover:consent:bg-gray-800 disabled:consent:opacity-50"
+          style={{
+            borderRadius: "0.5rem",
+            background: "#111827",
+            padding: "0.5rem 1rem",
+            fontSize: "0.875rem",
+            fontWeight: 500,
+            color: "#fff",
+          }}
+        >
+          Accept
+        </button>
+      </div>
+      {createConsent.isError && (
+        <p
+          className="consent:text-sm consent:text-red-600"
+          style={{ fontSize: "0.875rem", color: "#dc2626" }}
+        >
+          Something went wrong. Please try again.
+        </p>
+      )}
+    </div>
+  );
+}

package/src/components/index.ts

@@ -0,0 +1 @@
+export * from "./CookieConsentBanner";

package/src/env/constant.ts

@@ -0,0 +1 @@
+export const CONSENT_API_BASE_URL = "";

package/src/helpers/cookie.ts

@@ -0,0 +1,93 @@
+/**
+ * Browser cookie helpers for phygital-consent.
+ * Cookie name for consent preference: phygital_cookie_consent.
+ * Stored value: { deviceId: string, selected_preferences: string[] } (JSON).
+ * Default: 1 year, path /, SameSite Lax.
+ */
+
+export const COOKIE_CONSENT_NAME = "phygital_cookie_consent";
+
+const ONE_YEAR_SECONDS = 365 * 24 * 60 * 60;
+
+export interface SetCookieOptions {
+  maxAge?: number;
+  path?: string;
+  sameSite?: "Strict" | "Lax" | "None";
+  secure?: boolean;
+}
+
+/**
+ * Get a cookie value by name.
+ */
+export function getCookie(name: string): string | null {
+  if (typeof document === "undefined") return null;
+  const match = document.cookie.match(new RegExp("(?:^|; )" + encodeURIComponent(name) + "=([^;]*)"));
+  return match ? decodeURIComponent(match[1]) : null;
+}
+
+/**
+ * Set a cookie.
+ */
+export function setCookie(
+  name: string,
+  value: string,
+  options: SetCookieOptions = {}
+): void {
+  if (typeof document === "undefined") return;
+  const {
+    maxAge = ONE_YEAR_SECONDS,
+    path = "/",
+    sameSite = "Lax",
+    secure = false,
+  } = options;
+  let cookie = `${encodeURIComponent(name)}=${encodeURIComponent(value)}; path=${path}; max-age=${maxAge}; SameSite=${sameSite}`;
+  if (secure) cookie += "; Secure";
+  document.cookie = cookie;
+}
+
+export interface ConsentPreferenceValue {
+  deviceId: string;
+  selected_preferences: string[];
+}
+
+/**
+ * Read consent preference from cookie. Returns null if missing or invalid.
+ */
+export function getConsentPreferenceCookie(): ConsentPreferenceValue | null {
+  const raw = getCookie(COOKIE_CONSENT_NAME);
+  if (!raw) return null;
+  try {
+    const parsed = JSON.parse(raw) as unknown;
+    if (
+      parsed &&
+      typeof parsed === "object" &&
+      "deviceId" in parsed &&
+      "selected_preferences" in parsed &&
+      typeof (parsed as ConsentPreferenceValue).deviceId === "string" &&
+      Array.isArray((parsed as ConsentPreferenceValue).selected_preferences)
+    ) {
+      return parsed as ConsentPreferenceValue;
+    }
+  } catch {
+    // ignore
+  }
+  return null;
+}
+
+/**
+ * Store consent preference in cookie (hashed device id + selected_preferences).
+ * Uses 1 year max-age and SameSite Lax.
+ */
+export function setConsentPreferenceCookie(
+  deviceId: string,
+  selected_preferences: string[],
+  options?: Partial<SetCookieOptions>
+): void {
+  const value: ConsentPreferenceValue = { deviceId, selected_preferences };
+  setCookie(COOKIE_CONSENT_NAME, JSON.stringify(value), {
+    maxAge: ONE_YEAR_SECONDS,
+    path: "/",
+    sameSite: "Lax",
+    ...options,
+  });
+}

package/src/helpers/index.ts

@@ -0,0 +1 @@
+export * from "./cookie";

package/src/hooks/index.ts

@@ -0,0 +1 @@
+export * from "./useConsent";

package/src/hooks/useConsent.ts

@@ -0,0 +1,179 @@
+import {
+  useQuery,
+  useMutation,
+  useQueryClient,
+  UseQueryOptions,
+  UseMutationOptions,
+} from "@tanstack/react-query";
+import { useConsentService } from "../provider/ConsentServiceProvider";
+import { consentService } from "../api/consent";
+import type {
+  GetManyConsentParams,
+  GetManyConsentResponse,
+  GetConsentByIdParams,
+  GetConsentByIdResponse,
+  GetLatestConsentByUserIdParams,
+  GetLatestConsentByUserIdResponse,
+  GetLatestCookieConsentByDeviceIdParams,
+  GetLatestCookieConsentByDeviceIdResponse,
+  CreateUserConsentUpsertDTO,
+  CreateUserConsentResponse,
+  CreateDeviceCookieConsentUpsertDTO,
+  CreateDeviceCookieConsentResponse,
+  HealthResponse,
+} from "../types";
+
+/** Query keys for consent API */
+export const consentQueryKeys = {
+  all: ["consent"] as const,
+  health: () => [...consentQueryKeys.all, "health"] as const,
+  list: (params?: GetManyConsentParams) =>
+    [...consentQueryKeys.all, "list", params] as const,
+  detail: (id: string) => [...consentQueryKeys.all, "detail", id] as const,
+  latestByUserId: (user_id: string) =>
+    [...consentQueryKeys.all, "user-id", user_id] as const,
+  latestCookieByDeviceId: (device_id: string) =>
+    [...consentQueryKeys.all, "cookies", "device-id", device_id] as const,
+};
+
+// --- Queries ---
+
+/** Health check – GET /health */
+export const useHealth = (
+  options?: UseQueryOptions<HealthResponse>
+) => {
+  const { consentApi } = useConsentService();
+  const service = consentService(consentApi);
+
+  return useQuery<HealthResponse>({
+    queryKey: consentQueryKeys.health(),
+    queryFn: () => service.getHealth(),
+    ...options,
+  });
+};
+
+/** Get all consent logs – GET /consent/v1/consent */
+export const useManyConsents = (
+  params?: GetManyConsentParams,
+  options?: UseQueryOptions<GetManyConsentResponse>
+) => {
+  const { consentApi } = useConsentService();
+  const service = consentService(consentApi);
+
+  return useQuery<GetManyConsentResponse>({
+    queryKey: consentQueryKeys.list(params),
+    queryFn: () => service.getManyConsents(params),
+    ...options,
+  });
+};
+
+/** Get consent log by ID – GET /consent/v1/consent/{id} */
+export const useConsentById = (
+  params: GetConsentByIdParams,
+  options?: UseQueryOptions<GetConsentByIdResponse>
+) => {
+  const { consentApi } = useConsentService();
+  const service = consentService(consentApi);
+
+  return useQuery<GetConsentByIdResponse>({
+    queryKey: consentQueryKeys.detail(params.id),
+    queryFn: () => service.getConsentById(params),
+    enabled: !!params.id,
+    ...options,
+  });
+};
+
+/** Get latest consent for a user – GET /consent/v1/user-id */
+export const useLatestConsentByUserId = (
+  params: GetLatestConsentByUserIdParams,
+  options?: UseQueryOptions<GetLatestConsentByUserIdResponse>
+) => {
+  const { consentApi } = useConsentService();
+  const service = consentService(consentApi);
+
+  return useQuery<GetLatestConsentByUserIdResponse>({
+    queryKey: consentQueryKeys.latestByUserId(params.user_id),
+    queryFn: () => service.getLatestConsentByUserId(params),
+    enabled: !!params.user_id,
+    ...options,
+  });
+};
+
+/** Get latest cookie consent for a device – GET /consent/v1/cookies/device-id */
+export const useLatestCookieConsentByDeviceId = (
+  params: GetLatestCookieConsentByDeviceIdParams,
+  options?: UseQueryOptions<GetLatestCookieConsentByDeviceIdResponse>
+) => {
+  const { consentApi } = useConsentService();
+  const service = consentService(consentApi);
+
+  return useQuery<GetLatestCookieConsentByDeviceIdResponse>({
+    queryKey: consentQueryKeys.latestCookieByDeviceId(params.device_id),
+    queryFn: () => service.getLatestCookieConsentByDeviceId(params),
+    enabled: !!params.device_id,
+    ...options,
+  });
+};
+
+// --- Mutations ---
+
+/** Create user consent (account register) – POST /consent/v1/user-id */
+export const useCreateUserConsent = (
+  options?: UseMutationOptions<
+    CreateUserConsentResponse,
+    Error,
+    CreateUserConsentUpsertDTO
+  >
+) => {
+  const { consentApi } = useConsentService();
+  const queryClient = useQueryClient();
+  const service = consentService(consentApi);
+
+  return useMutation<CreateUserConsentResponse, Error, CreateUserConsentUpsertDTO>({
+    mutationFn: (body: CreateUserConsentUpsertDTO) => service.createUserConsent(body),
+    onSuccess: (
+      _data: CreateUserConsentResponse,
+      variables: CreateUserConsentUpsertDTO
+    ) => {
+      if (variables.user_id) {
+        queryClient.invalidateQueries({
+          queryKey: consentQueryKeys.latestByUserId(variables.user_id),
+        });
+      }
+      queryClient.invalidateQueries({ queryKey: consentQueryKeys.list() });
+    },
+    ...options,
+  });
+};
+
+/** Create device cookie consent – POST /consent/v1/cookies/device-id */
+export const useCreateDeviceCookieConsent = (
+  options?: UseMutationOptions<
+    CreateDeviceCookieConsentResponse,
+    Error,
+    CreateDeviceCookieConsentUpsertDTO
+  >
+) => {
+  const { consentApi } = useConsentService();
+  const queryClient = useQueryClient();
+  const service = consentService(consentApi);
+
+  return useMutation<
+    CreateDeviceCookieConsentResponse,
+    Error,
+    CreateDeviceCookieConsentUpsertDTO
+  >({
+    mutationFn: (body: CreateDeviceCookieConsentUpsertDTO) =>
+      service.createDeviceCookieConsent(body),
+    onSuccess: (
+      _data: CreateDeviceCookieConsentResponse,
+      variables: CreateDeviceCookieConsentUpsertDTO
+    ) => {
+      queryClient.invalidateQueries({
+        queryKey: consentQueryKeys.latestCookieByDeviceId(variables.device_id),
+      });
+      queryClient.invalidateQueries({ queryKey: consentQueryKeys.list() });
+    },
+    ...options,
+  });
+};

package/src/index.ts

@@ -0,0 +1,17 @@
+// Export types
+export * from "./types";
+
+// Export provider
+export * from "./provider";
+
+// Export api
+export * from "./api";
+
+// Export hooks
+export * from "./hooks";
+
+// Export helpers
+export * from "./helpers";
+
+// Export components
+export * from "./components";

package/src/provider/ConsentServiceProvider.tsx

@@ -0,0 +1,144 @@
+"use client";
+
+import { QueryClient, QueryClientConfig, QueryClientProvider } from "@tanstack/react-query";
+import axios, {
+  AxiosInstance,
+  AxiosRequestConfig,
+  AxiosResponse,
+  InternalAxiosRequestConfig,
+} from "axios";
+import React, { createContext, useContext, useMemo } from "react";
+
+export interface ConsentService {
+  consentApi: AxiosInstance;
+  queryClient: QueryClient;
+  updateHeaders: (headers: Record<string, string>) => void;
+}
+
+const ConsentServiceContext = createContext<ConsentService | undefined>(undefined);
+
+interface RequestInterceptor {
+  onFulfilled?: (
+    config: InternalAxiosRequestConfig
+  ) => InternalAxiosRequestConfig | Promise<InternalAxiosRequestConfig>;
+  onRejected?: (error: unknown) => unknown;
+}
+
+interface ResponseInterceptor {
+  onFulfilled?: (
+    response: AxiosResponse
+  ) => AxiosResponse | Promise<AxiosResponse>;
+  onRejected?: (error: unknown) => unknown;
+}
+
+export interface ConsentServiceProviderProps {
+  children: React.ReactNode;
+  baseURL?: string;
+  axiosConfig?: AxiosRequestConfig;
+  queryClient?: QueryClient;
+  queryClientConfig?: Partial<QueryClientConfig>;
+  requestInterceptors?: RequestInterceptor;
+  responseInterceptors?: ResponseInterceptor;
+}
+
+interface CreateConsentServiceParams {
+  baseURL?: string;
+  axiosConfig?: AxiosRequestConfig;
+  requestInterceptors?: RequestInterceptor;
+  responseInterceptors?: ResponseInterceptor;
+}
+
+export const createConsentService = ({
+  baseURL = "",
+  axiosConfig = {},
+  requestInterceptors = {},
+  responseInterceptors = {},
+}: CreateConsentServiceParams) => {
+  const instance = axios.create({
+    baseURL,
+    ...axiosConfig,
+  });
+
+  instance.interceptors.request.use(
+    requestInterceptors.onFulfilled,
+    requestInterceptors.onRejected
+  );
+
+  instance.interceptors.response.use(
+    responseInterceptors.onFulfilled,
+    responseInterceptors.onRejected
+  );
+
+  const updateHeaders = (headers: Record<string, string>) => {
+    Object.entries(headers).forEach(([key, value]) => {
+      instance.defaults.headers.common[key] = value;
+    });
+  };
+
+  return {
+    consentApi: instance,
+    updateHeaders,
+  };
+};
+
+export const ConsentServiceProvider: React.FC<ConsentServiceProviderProps> = ({
+  children,
+  baseURL = "",
+  axiosConfig = {},
+  queryClient,
+  queryClientConfig = {},
+  requestInterceptors = {},
+  responseInterceptors = {},
+}) => {
+  const queryClientInstance = useMemo(
+    () =>
+      queryClient ||
+      new QueryClient({
+        defaultOptions: {
+          queries: {
+            refetchOnWindowFocus: false,
+            refetchOnMount: false,
+            refetchOnReconnect: false,
+            ...queryClientConfig?.defaultOptions?.queries,
+          },
+          mutations: {
+            ...queryClientConfig?.defaultOptions?.mutations,
+          },
+        },
+        queryCache: queryClientConfig?.queryCache,
+        mutationCache: queryClientConfig?.mutationCache,
+      }),
+    [queryClient]
+  );
+
+  const consentService = useMemo(() => {
+    const service = createConsentService({
+      baseURL,
+      axiosConfig,
+      requestInterceptors,
+      responseInterceptors,
+    });
+
+    return {
+      consentApi: service.consentApi,
+      updateHeaders: service.updateHeaders,
+      queryClient: queryClientInstance,
+    };
+  }, [baseURL, queryClientInstance, axiosConfig, requestInterceptors, responseInterceptors]);
+
+  return (
+    <ConsentServiceContext.Provider value={consentService}>
+      <QueryClientProvider client={queryClientInstance}>
+        {children}
+      </QueryClientProvider>
+    </ConsentServiceContext.Provider>
+  );
+};
+
+export const useConsentService = () => {
+  const context = useContext(ConsentServiceContext);
+  if (!context) {
+    throw new Error("useConsentService must be used within a ConsentServiceProvider");
+  }
+  return context;
+};

package/src/provider/PhygitalConsentProvider.tsx

@@ -0,0 +1,58 @@
+"use client";
+
+import React, { createContext, useCallback, useContext, useEffect, useState } from "react";
+import { getConsentPreferenceCookie } from "../helpers/cookie";
+import { ConsentServiceProvider, ConsentServiceProviderProps } from "./ConsentServiceProvider";
+
+export interface PhygitalConsentContextValue {
+  /** True when cookie phygital_cookie_consent exists and has valid deviceId + selected_preferences. Use to show/hide cookie banner. */
+  hasConsentPreference: boolean;
+  /** Re-read cookie and update hasConsentPreference. Call after storing preference (e.g. from CookieConsentBanner onSuccess). */
+  refreshConsentPreference: () => void;
+}
+
+const PhygitalConsentContext = createContext<PhygitalConsentContextValue | undefined>(undefined);
+
+export interface PhygitalConsentProviderProps extends ConsentServiceProviderProps {
+  children: React.ReactNode;
+}
+
+/**
+ * Main provider for consumer apps. Wraps ConsentServiceProvider and exposes
+ * hasConsentPreference + refreshConsentPreference so the app can show/hide
+ * the cookie banner based on whether the user has already chosen a preference.
+ */
+export function PhygitalConsentProvider(props: PhygitalConsentProviderProps) {
+  const { children, ...consentServiceProps } = props;
+  const [hasConsentPreference, setHasConsentPreference] = useState(false);
+
+  const refreshConsentPreference = useCallback(() => {
+    const stored = getConsentPreferenceCookie();
+    setHasConsentPreference(!!stored);
+  }, []);
+
+  useEffect(() => {
+    refreshConsentPreference();
+  }, [refreshConsentPreference]);
+
+  const value: PhygitalConsentContextValue = {
+    hasConsentPreference,
+    refreshConsentPreference,
+  };
+
+  return (
+    <ConsentServiceProvider {...consentServiceProps}>
+      <PhygitalConsentContext.Provider value={value}>
+        {children}
+      </PhygitalConsentContext.Provider>
+    </ConsentServiceProvider>
+  );
+}
+
+export function usePhygitalConsent() {
+  const context = useContext(PhygitalConsentContext);
+  if (!context) {
+    throw new Error("usePhygitalConsent must be used within a PhygitalConsentProvider");
+  }
+  return context;
+}

package/src/provider/index.ts

@@ -0,0 +1 @@
+export * from "./PhygitalConsentProvider";

package/src/styles.css

@@ -0,0 +1,7 @@
+/**
+ * Phygital Consent package styles.
+ * Uses prefix "consent:" so consumer app Tailwind does not override these utilities.
+ * Consumer: import "@phygitallabs/phygital-consent/styles";
+ * In components, use consent: utilities (e.g. consent:flex consent:p-4).
+ */
+@import "tailwindcss" prefix(consent) source("./");