## What is the Commerce SDK?

The Commerce SDK (`commerce-kit`) is a lightweight TypeScript client that wraps the YNS REST API. It provides typed methods for every endpoint, automatic environment detection, and zero-config initialization.

## Installation

```bash
npm install commerce-kit
```

## Quick Start

```ts
import { Commerce } from "commerce-kit";

const commerce = Commerce();

// Browse products
const products = await commerce.productBrowse({ limit: 10 });

// Get a single product
const product = await commerce.productGet({ idOrSlug: "classic-tee" });

// Create a cart
const cart = await commerce.cartUpsert({
  items: [{ variantId: "var_123", quantity: 1 }],
});
```

## Configuration

The SDK reads `YNS_API_KEY` from your environment by default:

```ts
// Zero-config – reads from process.env.YNS_API_KEY
const commerce = Commerce();

// Explicit configuration
const commerce = Commerce({
  token: "sk-your-api-key",
  endpoint: "https://yns.store",
});
```

### Environment Detection

The SDK automatically detects staging vs production based on your API key prefix:

- `sk-...` connects to `yns.store` (production)
- `sk-s-...` connects to `yns.cx` (staging/sandbox)

## Available Methods

Every method is typed against the REST API it wraps – see the [API Reference](/docs/api-reference/overview) for parameters and response shapes.

| Category | Methods |
|----------|---------|
| Store | `meGet`, `socialsGet` |
| Products | `productBrowse`, `productGet`, `productCreate`, `productUpdate`, `productDelete`, `productBatch`, `productFilters` |
| Variants | `variantGet`, `variantCreate`, `variantUpdate`, `variantDelete` |
| Inventory | `inventoryBrowse`, `inventoryAdjust` |
| Collections | `collectionBrowse`, `collectionGet`, `collectionCreate`, `collectionUpdate`, `collectionDelete`, `collectionImportMemberships` |
| Categories | `categoriesBrowse`, `categoryGet`, `categoryCreate`, `categoryUpdate`, `categoryDelete` |
| Brands | `brandBrowse`, `brandGet`, `brandCreate`, `brandUpdate`, `brandDelete`, `brandAssignProducts` |
| Search | `search` |
| Reviews | `productReviewsBrowse`, `productReviewCreate` |
| Cart | `cartUpsert`, `cartGet`, `cartAddBundle`, `cartRemoveItem`, `cartDelete` |
| Orders | `orderBrowse`, `orderGet`, `orderUpdate`, `orderRefundsBrowse`, `orderRefundGet` |
| Customers | `customerBrowse`, `customerGet`, `customerUpdate`, `customerAddressCreate`, `customerAddressDelete`, `customerOrdersBrowse` |
| Coupons | `couponBrowse`, `couponGet`, `couponCreate`, `couponUpdate`, `couponDelete` |
| Events & tickets | `eventBrowse`, `eventGet`, `eventCreate`, `eventUpdate`, `eventAttendeesBrowse`, `ticketsGet`, `ticketsUpdate`, `ticketAttendeeGet` |
| Blog | `postBrowse`, `postGet`, `postCreate`, `postUpdate`, `postDelete`, `postCommentsBrowse`, `postCommentCreate`, `blogCategoryBrowse`, `blogCategoryGet`, `blogCategoryCreate`, `blogCategoryUpdate`, `blogCategoryDelete` |
| Marketing | `subscriberCreate`, `subscriberDelete`, `contactMessageCreate` |
| Legal pages | `legalPageBrowse`, `legalPageGet`, `legalPageCreate`, `legalPageUpdate` |
| Support | `supportCaseBrowse`, `supportCaseGet`, `supportCaseCreate`, `supportCaseUpdate`, `supportCaseReply` |
| Add-ons | `instaviewImagesBrowse` |
| Utility | `request` |

`Browse` methods list and paginate, `Get` fetches one record, and `Create`/`Update`/`Delete` do what they say.

## Raw Requests

For endpoints not yet wrapped, use the escape hatch:

```ts
const result = await commerce.request<MyType>("/v1/custom-endpoint", {
  method: "POST",
  body: { key: "value" },
});
```