# @moonbase.sh/storefront-api

Browser-first Moonbase SDK for storefront and customer flows: storefront data, identity, carts/orders, vouchers, inventory, and activation requests.
Learn more about our storefront API in our official docs: https://moonbase.sh/docs/storefronts/api/

## Install

```bash
pnpm add @moonbase.sh/storefront-api
```

## Create a client

```ts
import { MoonbaseClient } from '@moonbase.sh/storefront-api'

const client = new MoonbaseClient({
  endpoint: 'https://demo.moonbase.sh',
  persistUtm: true,
})
```

Configuration notes:

- `endpoint`: your Moonbase storefront URL.
- `includeManifests`: include downloadable file manifests when available.
- `persistUtm`: store detected UTM values in localStorage instead of sessionStorage.

## Common usage

### Load storefront and create an order

```ts
const storefront = await client.storefront.get()

const order = await client.orders.pushContent(
  {
    id: crypto.randomUUID(),
    currency: storefront.suggestedCurrency,
    items: [
      {
        type: 'Product',
        productId: storefront.products[0].id,
        variationId: storefront.products[0].defaultVariation?.id ?? '',
        quantity: 1,
      },
    ],
  },
  {
    returnUrl: `${window.location.origin}/checkout-complete`,
  },
)

const redirectUrl = order.hostedCheckoutUrl ?? order.checkoutUrl
if (redirectUrl)
  window.location.href = redirectUrl
```

### Sign in a customer

```ts
await client.identity.signIn('jane@example.com', 'password')

const user = await client.identity.get()
console.log(user.email)
```

### Redeem a voucher

```ts
const preview = await client.vouchers.peek('MY-CODE')
console.log(preview)

await client.identity.signIn('jane@example.com', 'password')
const redeemed = await client.vouchers.redeem('MY-CODE')
console.log(redeemed)
```

## Inventory flow

Most inventory endpoints require an authenticated user:

```ts
const products = await client.inventory.products.getOwned()
const licenses = await client.inventory.licenses.get()
```

Pagination on inventory endpoints is done by passing the `next` URL back into the same method:

```ts
let page = await client.inventory.products.getOwned()

while (page.hasMore && page.next) {
  page = await client.inventory.products.getOwned(page.next)
}
```

## Endpoint groups

`client.storefront`, `client.identity`, `client.orders`, `client.vouchers`, `client.inventory`, `client.activationRequests`, `client.vendor`.

## Token storage and logging

By default, credentials are stored in localStorage (or in-memory if localStorage is unavailable).

You can inject your own storage/logger implementations:

```ts
import { ConsoleLogger, InMemoryStore, LogLevel, MoonbaseClient } from '@moonbase.sh/storefront-api'

const client = new MoonbaseClient({
  endpoint: 'https://demo.moonbase.sh',
  store: new InMemoryStore(),
  logger: new ConsoleLogger(LogLevel.Debug),
})
```