commerce-kit

TypeScript SDK for the Your Next Store API.

Installation

bun add commerce-kit
# or
npm install commerce-kit

Quick Start

import { Commerce } from 'commerce-kit';

const commerce = Commerce();

That's it! The SDK reads YNS_API_KEY from environment and auto-detects the correct store and API base URL: https://yns.store

Products

// List products
const { data, meta } = await commerce.productBrowse({
  limit: 10,
  offset: 0,
  category: 'shoes',
  query: 'running',
  active: true,
  orderBy: 'createdAt',
  orderDirection: 'desc',
});

// Get single product by ID or slug
const product = await commerce.productGet({ idOrSlug: 'running-shoes' });

Cart

// Create or update cart
const cart = await commerce.cartUpsert({
  cartId: 'cart_123', // optional, creates new if omitted
  variantId: 'variant_456',
  quantity: 2,
});

// Get cart
const cart = await commerce.cartGet({ cartId: 'cart_123' });

// Remove item from cart
await commerce.cartRemoveItem({
  cartId: 'cart_123',
  variantId: 'variant_456',
});

Orders

// List orders
const { data, meta } = await commerce.orderBrowse({
  limit: 10,
  offset: 0,
});

// Get single order
const order = await commerce.orderGet({ id: 'order_789' });

Raw API Requests

For endpoints not yet implemented in the SDK, use the request() method:

// GET request
const webhooks = await commerce.request<Webhook[]>('/webhooks');

// POST with body
const webhook = await commerce.request<Webhook, CreateWebhookBody>('/webhooks', {
  method: 'POST',
  body: { url: 'https://example.com/hook', events: ['order.created'] },
});

// GET with query parameters
const results = await commerce.request<SearchResult>('/search', {
  query: { q: 'shoes', limit: 5 },
});

// Path parameters via template literals
const variant = await commerce.request<Variant>(`/products/${productId}/variants/${variantId}`);

TypeScript

All API types are exported:

import type {
  APIProductsBrowseResult,
  APIProductGetByIdResult,
  APICartCreateBody,
  APIOrderGetByIdResult,
  CommerceConfig,
} from 'commerce-kit';

License

AGPL-3.0-only