npm package: @makerinc/react-sdk
Description: React hooks library for Maker Connected Store Product API
Latest version: 1.2.1

# @makerinc/react-sdk

React hooks library for the Maker Connected Store Product API.

Maker connects to multiple ecommerce platforms (Shopify, FeedSync, and more) through a unified API. This library provides a simple, type-safe way to fetch and manage product data from any connected store using your `store_id`.

## Installation

```bash
npm install @makerinc/react-sdk
# or
yarn add @makerinc/react-sdk
```

## Quick Start

### 1. Wrap your app with MakerProvider

```tsx
import { MakerProvider } from '@makerinc/react-sdk';

function App() {
  return (
    <MakerProvider accountId="your-account-id">
      <YourApp />
    </MakerProvider>
  );
}
```

### 2. Use hooks in your components

```tsx
import { useProduct } from '@makerinc/react-sdk';

function ProductDetail({ productId }) {
  const { product, isLoading, error } = useProduct(productId);

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;
  if (!product) return <div>Not found</div>;

  return (
    <div>
      <h1>{product.name}</h1>
      <p>{product.description}</p>
    </div>
  );
}
```

## API Reference

### `<MakerProvider>`

```tsx
<MakerProvider accountId="your-account-id">
  {children}
</MakerProvider>
```

### `useProduct(productId, options?)`

Fetch a single product by ID.

**Parameters:**

- `productId` (string) - Product ID to fetch
- `options` (object, optional):
  - `inStock` (boolean) - Only return if in stock
  - `fmt` ('google') - Return Google Product Feed format
  - `currency` (string) - Currency for prices
  - `country` (string) - Country for contextual pricing
  - `language` (string) - Language for localization
  - `enabled` (boolean) - Enable/disable query execution

**Returns:** `{ product, isLoading, error, isError }`

```tsx
function ProductPage({ id }) {
  const { product, isLoading, error } = useProduct(id, {
    inStock: true,
    country: 'US',
  });

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error</div>;

  return <div>{product?.name}</div>;
}
```

### `useProducts(options)`

Fetch multiple products by IDs (max 100).

**Options:**

- `productIds` (string[], required) - Array of product IDs to fetch
- `inStock` (boolean)
- `fmt` ('google')
- `currency` (string)
- `country` (string)
- `language` (string)
- `enabled` (boolean)

```tsx
function ProductList() {
  const { data, isLoading } = useProducts({
    productIds: ['prod_123', 'prod_456', 'prod_789'],
    inStock: true,
  });

  return (
    <div>
      {data?.map((product) => (
        <ProductCard key={product.id} product={product} />
      ))}
    </div>
  );
}
```

### `useProductsByCategory(options)`

Fetch products from a category with filtering, sorting, and pagination. This hook can be used to build both full **Product Listing Pages (PLPs)** and individual **category sliders/carousels**.

**Options:**

- `categoryId` (string, required) - Category identifier
- `limit` (number) - Results per page (default: 20)
- `sort` (SortOrder) - Sort order
- `inStock` (boolean) - Filter to in-stock only
- `facets` (string[]) - Facet filters (e.g., ['color=Blue', 'size=Large'])
- `createdWithin` (string) - Date range (e.g., "7d", "30d")
- `minPrice` (number) - Minimum price filter
- `maxPrice` (number) - Maximum price filter
- `currency`, `country`, `language` (string)
- `enabled` (boolean)

**Returns:** `{ data, error, isLoading, isFetchingMore, isError, loadMore, hasMore }`

```tsx
function CategoryPage({ categoryId }) {
  const { data, isLoading, loadMore, hasMore, isFetchingMore } = useProductsByCategory({
    categoryId,
    limit: 24,
  });

  return (
    <div>
      {data?.products.map((product) => (
        <ProductCard key={product.id} product={product} />
      ))}
      {hasMore && (
        <button onClick={loadMore} disabled={isFetchingMore}>
          {isFetchingMore ? 'Loading...' : 'Load More'}
        </button>
      )}
    </div>
  );
}
```

### `useSearchProducts(options?)`

Search products.

```tsx
const { data, isLoading } = useSearchProducts({ query: 'shirt', limit: 20 });
```

### `useCategories(options?)`

Fetch categories.

```tsx
const { data, isLoading } = useCategories({ limit: 10 });
```

### `useRelatedProducts(options)`

Fetch related products.

```tsx
const { data, isLoading } = useRelatedProducts({ productId: '123' });
```

### `useCategoriesByProduct(options)`

Get categories for a product.

```tsx
const { data, isLoading } = useCategoriesByProduct({ productId: '123' });
```

### `useProductsByFacet(options)`

Fetch products by facet.

```tsx
const { data, isLoading } = useProductsByFacet({ facet: 'category=Women_Accessories' });
```

### `useMarkets()`

Fetch available markets for user selection. Returns currencies OR countries based on store configuration.

```tsx
function MarketPicker() {
  const { data } = useMarkets();

  if (data?.choices?.[0] === 'Currencies') {
    const [, { suggestedCurrency, availableCurrencies }] = data.choices;
    return (
      <select defaultValue={suggestedCurrency}>
        {availableCurrencies.map(c => <option key={c}>{c}</option>)}
      </select>
    );
  }

  return null;
}
```


## Development

```bash
npm install --legacy-peer-deps
npm test
npm run build
npm run dev
```

## Releasing

```bash
npm version patch   # or minor, major, prerelease --preid=beta
```

This runs tests, builds, pushes, and publishes automatically via `preversion`/`postversion` scripts.

For beta releases via GitHub Actions, create a prerelease at github.com/makerinc/react-sdk/releases.

## Contributing

See [CONTRIBUTING.md](./CONTRIBUTING.md) for development guidelines.

## License

MIT