npm package: @mnrq/sdk
Description: Official MNRQ JavaScript/TypeScript SDK
Author: Menuraq
Latest version: 1.1.1

# MNRQ JavaScript SDK (`@mnrq/sdk`)

Official JavaScript/TypeScript SDK for the Menuraq Developer API.

## Version

`1.1.1`

## Install

```bash
npm install @mnrq/sdk
```

## Quick Start

```ts
import { MnrqClient } from '@mnrq/sdk';

const client = new MnrqClient({
  apiKey: process.env.MNRQ_API_KEY!,
  baseUrl: 'https://menuraq.com',
});

const business = await client.getBusiness();
console.log(business.data.business.name);
```

## Client Configuration

```ts
const client = new MnrqClient({
  apiKey: process.env.MNRQ_API_KEY!,
  baseUrl: 'https://menuraq.com',
  timeoutMs: 20_000, // optional
});
```

- `apiKey` required
- `baseUrl` required
- `timeoutMs` optional (defaults to `20000`)
- `fetchImpl` optional for custom runtimes/tests

Auth headers sent automatically on each request:

- `Authorization: Bearer <api_key>`
- `x-api-key: <api_key>`

## API Coverage

### System

- `getApiInfo()` -> `GET /api/v1`

### Business and Branches

- `getBusiness()` -> `GET /api/v1/business`
- `getBranches({ includeInactive? })` -> `GET /api/v1/branches`

### Menus

- `getMenus({ limit?, offset?, status?, includeItems? })` -> `GET /api/v1/menus`
- `getMenu(menuId, { includeAnalytics? })` -> `GET /api/v1/menus/:menuId`
- `getMenuItems({ menuId?, categoryId?, available?, limit?, offset? })` -> `GET /api/v1/menu-items`

### Analytics

- `getAnalytics({ menuId?, dateFrom?, dateTo?, includeDaily? })` -> `GET /api/v1/analytics`

### Promotions

- `getPromotions({ menuId?, activeOnly?, limit?, offset? })` -> `GET /api/v1/promotions`
- `getPromotion(promotionId)` -> `GET /api/v1/promotions/:promotionId`

### Templates

- `getTemplateRender({ menuId?, menuSlug?, mode?, hideHeader? })` -> `GET /api/v1/templates/render`
- `getTemplateIframe({ menuId?, menuSlug?, hideHeader? })` convenience wrapper
- `getTemplateHtml({ menuId?, menuSlug?, hideHeader? })` convenience wrapper

`hideHeader: true` makes returned public/iframe URL use embed mode so `/m/[slug]` header is hidden.

### Menu Item Writes

- `updateMenuItem(itemId, patch)` -> `PATCH /api/v1/menu-items/:itemId`

## Examples

### Read menus

```ts
const menus = await client.getMenus({ limit: 20, status: 'live' });
console.log(menus.data);
```

### Get template iframe embed response

```ts
const render = await client.getTemplateIframe({
  menuSlug: 'main-menu',
  hideHeader: true,
});

console.log(render.data.public_url);
console.log(render.data.embed_code);
```

### Update a menu item

```ts
await client.updateMenuItem('item_uuid_here', {
  title: 'Spicy Chicken Deluxe',
  price: 18.5,
  available: true,
  tags: ['spicy', 'popular'],
});
```

## Error Handling

The SDK throws `MnrqApiError` for non-2xx or `ok: false` responses.

```ts
import { MnrqApiError } from '@mnrq/sdk';

try {
  await client.getBusiness();
} catch (error) {
  if (error instanceof MnrqApiError) {
    console.error(error.status, error.code, error.requestId, error.details);
  }
}
```

## Backward Compatibility

Legacy aliases are preserved:

- `MenuraqClient` alias for `MnrqClient`
- `MenuraqApiError` alias for `MnrqApiError`

## Test

```bash
cd sdk/javascript
npm install
npm test
```

The suite validates constructor behavior, every SDK method route mapping, payload formatting, and error translation.

## Build and Publish

```bash
cd sdk/javascript
npm install
npm run build
npm publish --access public
```