commerce-kit/README.md

# commerce-kit

TypeScript SDK for the [Your Next Store](https://yournextstore.com) API.

## Installation

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

## Quick Start

```typescript
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

```typescript
// 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

```typescript
// 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

```typescript
// 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:

```typescript
// 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:

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

## License

AGPL-3.0-only