npm package: @reviewtrackr/shopify-sdk
Description: ReviewTrackr SDK for Shopify apps — auto-detects merchant details and tracks presence
Author: ReviewTrackr
Latest version: 0.4.0

# @reviewtrackr/shopify-sdk

The official [ReviewTrackr](https://reviewtrackr.app) SDK for Shopify apps. One server-side call auto-detects merchant details and tracks when they're online — zero client-side code, zero merchant configuration.

## What it does

- **Auto-registers merchants** by calling Shopify's Shop API using your app's existing OAuth token
- **Captures full merchant details**: store name, owner, email, phone, address, Shopify plan, domain, timezone, and more
- **Tracks merchant presence** — every page load updates "last seen", so you always know who's online
- **No extra Shopify permissions** — uses your app's existing access token
- **One function call** — no client-side code, no heartbeat setup, no configuration

## Installation

```bash
npm install @reviewtrackr/shopify-sdk
```

```bash
yarn add @reviewtrackr/shopify-sdk
```

## Quick Start

Add `registerMerchant()` to your root loader or middleware. That's it.

**Remix apps** — pass the `admin` client:

```typescript
import { registerMerchant } from '@reviewtrackr/shopify-sdk/server';

export async function loader({ request }) {
  const { admin } = await authenticate.admin(request);

  await registerMerchant({
    apiKey: 'rtk_your_api_key',
    admin,
  });

  // ... rest of your loader
}
```

**Any Node.js backend** — pass a raw access token:

```typescript
import { registerMerchant } from '@reviewtrackr/shopify-sdk/server';

await registerMerchant({
  apiKey: 'rtk_your_api_key',
  accessToken: 'shpat_your_shopify_token',
  shopDomain: 'store.myshopify.com',
});
```

Every time a merchant opens your app, their details are automatically captured and their online status is updated.

## What merchant data is captured

When `registerMerchant()` is called, the following is automatically fetched from Shopify and sent to ReviewTrackr:

| Field | Source |
|-------|--------|
| Store name | `shop.name` |
| Shop domain | `shop.myshopify_domain` |
| Primary domain | `shop.domain` |
| Owner name | `shop.shop_owner` |
| Email | `shop.email` |
| Phone | `shop.phone` |
| Address, City, Province, Country | `shop.address1`, `shop.city`, etc. |
| Shopify plan | `shop.plan_display_name` |
| Currency | `shop.currency` |
| Timezone | `shop.iana_timezone` |

## API Reference

### `registerMerchant(options)`

Fetches merchant details from Shopify and registers/updates them on ReviewTrackr. Each call also updates the merchant's "last seen" timestamp.

| Option | Type | Required | Description |
|--------|------|----------|-------------|
| `apiKey` | `string` | Yes | Your ReviewTrackr API key |
| `admin` | `ShopifyAdminClient` | One of `admin` or `accessToken` | Shopify admin client from `authenticate.admin()` |
| `accessToken` | `string` | One of `admin` or `accessToken` | Raw Shopify access token (`shpat_...`) |
| `shopDomain` | `string` | Required with `accessToken` | The merchant's `.myshopify.com` domain |
| `baseUrl` | `string` | No | ReviewTrackr API URL (defaults to `https://api.reviewtrackr.app`) |

Returns: `Promise<{ success: boolean; merchantId: string; isNew: boolean }>`

## How online tracking works

There's no separate heartbeat or client-side code. `registerMerchant()` runs in your server loader on every page load. Each call updates the merchant's `lastSeenAt` timestamp on ReviewTrackr. If a merchant hasn't been seen in 24+ hours, they're marked as offline.

## Requirements

- Node.js 18+ (uses native `fetch`)
- Shopify app with OAuth access token (any scope that grants access to the Shop API)

## GDPR Compliance

The SDK uses your app's existing Shopify OAuth token — no cookies, no fingerprinting. Merchant data comes directly from Shopify's Admin API, which the merchant has already consented to by installing your app.

## License

MIT