@moonbase.sh/storefront-api 0.0.0-next-20260526085904

package/README.md

@@ -0,0 +1,116 @@
+# @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),
+})
+```