@storeos/storefront-client

The official TypeScript SDK for StoreOS storefronts. Browse products, manage customer accounts, and run checkout — with full types and zero runtime dependencies.

Works anywhere fetch runs: React, Next.js, Remix, React Native, Cloudflare Workers, Node 18+.

Install

npm install @storeos/storefront-client

yarn add @storeos/storefront-client

pnpm add @storeos/storefront-client

bun add @storeos/storefront-client

Quick start

import { StoreFront } from '@storeos/storefront-client';

const store = new StoreFront({
  tenant: 'your-store-id',
});

const { nodes: products, meta } = await store.getProducts({
  page: 1,
  limit: 24,
});

const product = await store.getProduct({ handle: 'blue-widget' });

Configuration

const store = new StoreFront({
  /** Your StoreOS store identifier */
  tenant: 'your-store-id',

  /** Optional — restore a session from storage */
  accessToken: sessionToken,

  /** Optional — custom fetch for tests or edge runtimes */
  fetch: customFetch,
});

Customer sessions

Sign-in methods automatically keep the session on the client. Persist the token in your app and restore it on load:

await store.login({
  user: '[email protected]',
  password: '••••••••',
});

// Save store.getAccessToken() to cookies, localStorage, etc.

store.setAccessToken(savedToken);
const me = await store.getMe();

Phone OTP is supported too:

await store.sendOtp({ phoneNumber: '+8801…' });
await store.verifyOtp({ phoneNumber: '+8801…', otp: '123456' });

What you can build

Catalog

await store.getTenant();
await store.getProducts({ search: 'shirt', collectionIds: ['…'] });
await store.getProduct({ handle: 'linen-shirt' });
await store.getCollections();
await store.getCollection('collection-id');

Checkout

const coupon = await store.verifyCoupon({
  code: 'SAVE10',
  lineItems: [{ productId: '…', quantity: 2 }],
});

const { order } = await store.createOrder({
  lineItems: [{ productId: '…', quantity: 2 }],
  shippingAddress: { /* … */ },
  paymentMethod: 'COD',
  couponCode: coupon.valid ? 'SAVE10' : undefined,
});

Guest checkout works out of the box. If the API returns a token, the client picks it up so the customer can track the order immediately.

Order history

const { nodes: orders } = await store.getMyOrders({ page: 1 });
await store.getOrder('order-id');
await store.cancelOrder('order-id', 'Changed my mind');

Pagination

List methods return { nodes, meta }:

const { nodes, meta } = await store.getProducts({ page: 2, limit: 12 });

meta.totalCount;
meta.hasNextPage;
meta.totalPages;

Supported query params: page, limit, sort, sortBy, search, and collectionIds (products).

Errors

Non-2xx responses throw StoreFrontApiError with status, message, and body:

import { StoreFront, StoreFrontApiError } from '@storeos/storefront-client';

try {
  await store.getProduct({ handle: 'sold-out' });
} catch (error) {
  if (error instanceof StoreFrontApiError) {
    console.error(error.status, error.body);
  }
}

Types

Every method is fully typed. Import request and response shapes directly:

import type {
  Product,
  Collection,
  Order,
  StorefrontUser,
  CreateOrderInput,
  PaginatedResponse,
} from '@storeos/storefront-client';

API surface

| Area | Methods | |------|---------| | Store | getTenant | | Products | getProducts, getProduct, getProductById, getProductByHandle | | Collections | getCollections, getCollection | | Auth | getMe, register, login, logout, updateProfile, changePassword, sendOtp, verifyOtp | | Orders | getMyOrders, getOrder, createOrder, verifyCoupon, cancelOrder | | Session | getAccessToken, setAccessToken |

License

Private / see storeos.dev for terms.