> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackfront.digital/llms.txt
> Use this file to discover all available pages before exploring further.

# Core Concepts

# Core Concepts

## Architecture

The SDK operates as a **headless-first** layer between your React Native app and two Shopify APIs:

* **Stackfront REST API** — managed services (loyalty, reviews, stories, push notifications, events, billing, config). Handled by the `ApiClient` service.
* **Shopify Storefront GraphQL API** — commerce primitives (products, cart, checkout, customer, orders). Handled by the `StorefrontClient` service.

The SDK abstracts this so your code never needs to know which API is being called.

## Provider & Context

Wrap your root component in `StackfrontProvider`. On mount, it fetches remote config, initializes all services, and exposes them via React context.

All hooks and services access this context through the `useStackfront()` hook:

```tsx theme={null}
import { useStackfront } from 'react-native-stackfront-sdk';

function MyComponent() {
  const { ready, config, products, cart, events } = useStackfront();

  if (!ready) return <Loading />;
  // ...
}
```

## Services vs Hooks

The SDK provides two layers of API:

**Services** — direct imperative access to underlying functionality (API calls, storage, GraphQL queries). Accessible via `useStackfront()`.

**Hooks** — opinionated React wrappers over services with built-in state management (`data`, `loading`, `error`). Prefer hooks for most UI work.

| Layer                      | Example                 | When to use            |
| -------------------------- | ----------------------- | ---------------------- |
| `useStackfront().products` | Service — raw API calls | Composing custom logic |
| `useProducts()`            | Hook — reactive state   | Standard UI rendering  |

## Available Hooks (25)

| Hook                 | Returns                               | Description                                           |
| -------------------- | ------------------------------------- | ----------------------------------------------------- |
| `useStackfront()`    | Context value                         | Access every service, config, and lifecycle state     |
| `useProducts()`      | `Product[]`                           | Paginated product listing                             |
| `useProduct(handle)` | `Product \| null`                     | Single product by handle                              |
| `useSearch(query)`   | `Product[]`                           | Full-text product search                              |
| `useCollections()`   | `Collection[]`                        | Collection listing                                    |
| `useCart()`          | `Cart \| null`                        | Current cart with line mutations                      |
| `useCheckout()`      | `{ url, loading }`                    | Checkout URL for web checkout                         |
| `useCustomer()`      | `Customer \| null`                    | Logged-in customer profile                            |
| `useOrders()`        | `Order[]`                             | Customer order history                                |
| `usePush()`          | `{ permission, token }`               | Push notification registration state                  |
| `useConfig()`        | `SdkConfigResponse`                   | Remote SDK configuration                              |
| `useFeatureFlags()`  | `FeatureFlag[]`                       | Remote feature flags                                  |
| `useBranding()`      | `BrandingConfig`                      | Store branding settings                               |
| `useBanners()`       | `Banner[]`                            | Active banners                                        |
| `useAnnouncements()` | `Announcement[]`                      | Announcement bar config                               |
| `usePopups()`        | `Popup[]`                             | Popup/overlay config                                  |
| `useStories()`       | `Story[]`                             | Story/collection highlights                           |
| `useReviews()`       | `Review[]`                            | Product reviews                                       |
| `useSocialProof()`   | `SocialProof[]`                       | Live social proof notifications                       |
| `useWishlist()`      | `WishlistItem[]`                      | User's wishlist                                       |
| `useLoyalty()`       | `LoyaltyData`                         | Points, tiers, and rewards                            |
| `useBilling()`       | `BillingStatus`                       | App subscription/billing info                         |
| `useIntegrations()`  | `Integration[]`                       | Third-party integration status                        |
| `useAbandonedCart()` | `{ enabled, optedIn, optIn, optOut }` | Abandoned cart notification opt-in state and controls |

## Available Services (15)

| Service              | Description                                   |
| -------------------- | --------------------------------------------- |
| `ApiClient`          | HTTP client for the Stackfront REST API       |
| `StorefrontClient`   | GraphQL client for the Shopify Storefront API |
| `StorageService`     | AsyncStorage wrapper for local persistence    |
| `EventService`       | Event tracking and batching pipeline          |
| `DeviceService`      | Push notification device registration         |
| `ConfigService`      | Remote config fetching                        |
| `ProductService`     | Product and collection GraphQL queries        |
| `CartService`        | Cart CRUD via Storefront GraphQL mutations    |
| `CustomerService`    | Customer auth, profile, and orders            |
| `LoyaltyService`     | Points, tiers, and rewards API                |
| `ReviewService`      | Product review API                            |
| `StoryService`       | Story management API                          |
| `SocialProofService` | Live social proof feed API                    |
| `IntegrationService` | Third-party integration data API              |
| `BillingService`     | App subscription billing API                  |
| `WishlistService`    | Local wishlist persistence                    |

## GraphQL Operations

The SDK bundles pre-written GraphQL queries and mutations for the Shopify Storefront API. These are used internally by the `ProductService`, `CartService`, and `CustomerService`, and are also exported directly:

```ts theme={null}
import { GET_PRODUCTS, CART_CREATE, CUSTOMER_GET } from 'react-native-stackfront-sdk';
```

Available operations:

| Operation                      | Type     | Description                     |
| ------------------------------ | -------- | ------------------------------- |
| `GET_PRODUCTS`                 | Query    | Paginated product list          |
| `GET_PRODUCT`                  | Query    | Single product by handle        |
| `GET_PRODUCT_BY_ID`            | Query    | Single product by ID            |
| `GET_COLLECTIONS`              | Query    | Paginated collection list       |
| `GET_COLLECTION`               | Query    | Single collection with products |
| `SEARCH_PRODUCTS`              | Query    | Full-text product search        |
| `CART_CREATE`                  | Mutation | Create a new cart               |
| `CART_GET`                     | Query    | Fetch cart by ID                |
| `CART_LINES_ADD`               | Mutation | Add lines to cart               |
| `CART_LINES_UPDATE`            | Mutation | Update cart line quantities     |
| `CART_LINES_REMOVE`            | Mutation | Remove lines from cart          |
| `CART_BUYER_IDENTITY_UPDATE`   | Mutation | Set customer identity on cart   |
| `CUSTOMER_CREATE`              | Mutation | Register a new customer         |
| `CUSTOMER_ACCESS_TOKEN_CREATE` | Mutation | Log in (create access token)    |
| `CUSTOMER_ACCESS_TOKEN_DELETE` | Mutation | Log out (delete access token)   |
| `CUSTOMER_GET`                 | Query    | Fetch customer profile + orders |
| `CUSTOMER_RECOVER`             | Mutation | Password reset email            |
| `CUSTOMER_UPDATE`              | Mutation | Update customer profile         |

## Lifecycle

1. App starts → `StackfrontProvider` mounts
2. Config fetched from Stackfront API (storefront token, OneSignal ID, feature flags)
3. Storefront GraphQL client initialized
4. Storage initialized (AsyncStorage)
5. OneSignal initialized if configured
6. `ready = true`
7. `app_opened` event tracked
8. App renders

Access `ready` and `error` from `useStackfront()` to gate your UI:

```tsx theme={null}
const { ready, error } = useStackfront();
if (error) return <ErrorScreen error={error} />;
if (!ready) return <SplashScreen />;
return <AppContent />;
```