@sdg.la/wishlist-stack-sdk 0.9.0

package/README.md

@@ -0,0 +1,279 @@
+# @sdg.la/wishlist-stack-sdk
+
+[![npm version](https://img.shields.io/npm/v/@sdg.la/wishlist-stack-sdk.svg)](https://www.npmjs.com/package/@sdg.la/wishlist-stack-sdk)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
+
+TypeScript/JavaScript SDK for the Wishlist Stack API.
+
+## Table of Contents
+
+- [Features](#features)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Usage](#usage)
+  - [Server / Node.js / Workers](#server--nodejs--workers)
+  - [Browser](#browser)
+  - [Class API](#class-api)
+- [Error Handling](#error-handling)
+- [Pagination](#pagination)
+- [API Reference](#api-reference)
+  - [Groups](#groups)
+  - [Lists](#lists)
+  - [Shared](#shared)
+- [TypeScript Types](#typescript-types)
+- [Related Packages](#related-packages)
+- [License](#license)
+
+## Features
+
+- **TypeScript-first** — Full type definitions with exported types for all requests and responses
+- **Universal** — Works in Node.js, browsers, and edge runtimes (Cloudflare Workers, Deno, etc.)
+- **Flexible API** — Choose between functional `createWishlistStackClient()` or class-based `new WishlistStackClient()`
+- **Built-in error handling** — Structured `WishlistStackApiError` with status codes and API error messages
+- **Pagination support** — All list endpoints support `page` and `pageSize` parameters
+
+## Requirements
+
+- **Node.js 18+** (uses native `fetch`) or provide a custom `fetch` implementation
+- **Modern browsers** with native `fetch` support
+
+## Installation
+
+```bash
+npm install @sdg.la/wishlist-stack-sdk
+```
+
+```bash
+yarn add @sdg.la/wishlist-stack-sdk
+```
+
+```bash
+pnpm add @sdg.la/wishlist-stack-sdk
+```
+
+## Quick Start
+
+```ts
+import { createWishlistStackClient } from '@sdg.la/wishlist-stack-sdk';
+
+const client = createWishlistStackClient({
+  apiKey: 'your-merchant-api-key',
+  customerAccessToken: 'customer-access-token', // required for authenticated endpoints
+});
+
+// Fetch all groups
+const { groups } = await client.groups.getAll();
+
+// Fetch all lists
+const { lists } = await client.lists.getAll();
+```
+
+## Usage
+
+### Server / Node.js / Workers
+
+```ts
+import { createWishlistStackClient } from '@sdg.la/wishlist-stack-sdk';
+
+const client = createWishlistStackClient({
+  apiKey: process.env.WISHLIST_STACK_API_KEY!,
+  baseUrl: process.env.WISHLIST_STACK_BASE_URL, // optional, defaults to production
+  customerAccessToken: '...customer_access_token...',
+});
+
+const { groups } = await client.groups.getAll();
+```
+
+### Browser
+
+```ts
+import { createWishlistStackClient } from '@sdg.la/wishlist-stack-sdk';
+
+const client = createWishlistStackClient({
+  apiKey: 'YOUR_API_KEY',
+  baseUrl: 'https://wishlist-js.fly.dev', // optional
+  customerAccessToken: '...optional...',
+});
+
+const { lists } = await client.lists.getAll();
+```
+
+> **Note:** If you use a strict Content Security Policy (CSP), you must allow your API domain in `connect-src`.
+
+### Class API
+
+If you prefer a class-based API, use `WishlistStackSDK`:
+
+```ts
+import { WishlistStackSDK } from '@sdg.la/wishlist-stack-sdk';
+
+const client = new WishlistStackSDK({
+  apiKey: process.env.WISHLIST_STACK_API_KEY!,
+  baseUrl: process.env.WISHLIST_STACK_BASE_URL,
+  customerAccessToken: '...optional...',
+});
+
+await client.groups.getAll();
+await client.lists.getById('list-id');
+```
+
+**Back-compat aliases** are available on the class:
+
+```ts
+await client.getGroups();        // alias for client.groups.getAll()
+await client.getGroupById('id'); // alias for client.groups.getById('id')
+await client.getLists();         // alias for client.lists.getAll()
+```
+
+## Error Handling
+
+Non-2xx responses throw `WishlistStackApiError`. Use the `isWishlistStackApiError` type guard for safe handling:
+
+```ts
+import { isWishlistStackApiError } from '@sdg.la/wishlist-stack-sdk';
+
+try {
+  await client.groups.getAll();
+} catch (error) {
+  if (isWishlistStackApiError(error)) {
+    console.log(error.status);           // HTTP status code
+    console.log(error.apiErrors);        // Array of { message, field? }
+    console.log(error.apiErrorMessages); // Array of error message strings
+    console.log(error.requestId);        // Request ID for debugging
+  }
+}
+```
+
+## Pagination
+
+Endpoints that return lists support pagination via query parameters:
+
+```ts
+// Paginate groups
+await client.groups.getAll({ page: 2, pageSize: 10 });
+
+// Paginate lists within a group
+await client.groups.getById('group-id', { page: 1, pageSize: 25 });
+
+// Paginate items within a list
+await client.lists.getById('list-id', { page: 1, pageSize: 25 });
+```
+
+**Pagination response structure:**
+
+```ts
+{
+  page: number;
+  pageSize: number;
+  totalCount: number;
+  totalPages: number;
+}
+```
+
+## API Reference
+
+### Groups
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `groups.getAll(query?)` | `GET /api/groups` | Fetch all groups for the authenticated customer |
+| `groups.getById(groupId, query?)` | `GET /api/groups/{groupId}` | Fetch a single group by ID (lists are paginated) |
+| `groups.create(body)` | `POST /api/groups` | Create a new group |
+| `groups.update(groupId, body)` | `PATCH /api/groups/{groupId}` | Update group name/description |
+| `groups.remove(groupId)` | `DELETE /api/groups/{groupId}` | Remove a group |
+| `groups.reorder(groupId, body)` | `POST /api/groups/{groupId}/reorder` | Reorder lists within a group |
+| `groups.share(groupId)` | `POST /api/groups/{groupId}/share` | Mark a group as shared (public read-only) |
+| `groups.unshare(groupId)` | `DELETE /api/groups/{groupId}/share` | Revoke sharing for a group |
+
+**Parameters:**
+
+```ts
+// Query parameters (for getAll, getById)
+{ page?: number; pageSize?: number }
+
+// Create/Update body
+{ name?: string; description?: string }
+
+// Reorder body
+{ listIds: string[] }
+```
+
+### Lists
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `lists.getAll(query?)` | `GET /api/lists` | Fetch all lists for the authenticated customer |
+| `lists.getById(listId, query?)` | `GET /api/lists/{listId}` | Fetch a single list by ID (items are paginated) |
+| `lists.create(body)` | `POST /api/lists` | Create a new list |
+| `lists.update(listId, body)` | `PATCH /api/lists/{listId}` | Update list name/description |
+| `lists.remove(listId)` | `DELETE /api/lists/{listId}` | Remove a list |
+| `lists.addItems(listId, body)` | `POST /api/lists/{listId}/add` | Add items to a list |
+| `lists.updateItem(listId, itemId, body)` | `PATCH /api/lists/{listId}/items/{itemId}` | Update an item on a list |
+| `lists.removeItem(listId, itemId)` | `DELETE /api/lists/{listId}/items/{itemId}` | Remove an item from a list |
+| `lists.share(listId)` | `POST /api/lists/{listId}/share` | Mark a list as shared (public read-only) |
+| `lists.unshare(listId)` | `DELETE /api/lists/{listId}/share` | Revoke sharing for a list |
+
+**Parameters:**
+
+```ts
+// Query parameters (for getAll, getById)
+{ page?: number; pageSize?: number }
+
+// Create/Update body
+{ name?: string; description?: string }
+
+// Add items body
+{ items: Array<{ variantId: string; quantity?: number; note?: string }> }
+
+// Update item body
+{ quantity?: number; note?: string }
+```
+
+### Shared
+
+Public read-only endpoints for accessing shared lists and groups:
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `shared.getSharedList(listId)` | `GET /api/shared/list/{listId}` | Fetch a public shared list |
+| `shared.getSharedGroup(groupId)` | `GET /api/shared/group/{groupId}` | Fetch a public shared group |
+
+## TypeScript Types
+
+The package exports all types for use in your application:
+
+```ts
+import type {
+  // Client types
+  CreateWishlistStackClientOptions,
+  WishlistStackClient,
+
+  // Error types
+  WishlistStackApiError,
+  WishlistStackApiErrorDetails,
+
+  // Response types
+  GetGroupsResponse,
+  GetGroupResponse,
+  GroupSummary,
+  GroupDetail,
+  GetListsResponse,
+  GetListResponse,
+  ListSummary,
+  ListDetail,
+  HydratedWishlistItem,
+  HydratedProduct,
+  HydratedVariant,
+
+  // Common types
+  Pagination,
+  PaginationParams,
+} from '@sdg.la/wishlist-stack-sdk';
+```
+
+## Related Packages
+
+| Package | Description |
+|---------|-------------|
+| [`@sdg.la/wishlist-stack-hydrogen`](https://www.npmjs.com/package/@sdg.la/wishlist-stack-hydrogen) | Hydrogen/Remix integration with React hooks and middleware |

package/dist/index.cjs

@@ -0,0 +1,371 @@
+'use strict';
+
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+
+// src/constants.ts
+var MAX_PAGINATION_SIZE = 25;
+var BASE_URL = "https://wishlist-js.fly.dev";
+
+// src/client/query.ts
+function toQueryString(query) {
+  if (!query) return "";
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(query)) {
+    if (value === void 0 || value === null) continue;
+    if (Array.isArray(value)) {
+      for (const v of value) {
+        if (v === void 0 || v === null) continue;
+        params.append(key, String(v));
+      }
+      continue;
+    }
+    params.set(key, String(value));
+  }
+  const qs = params.toString();
+  return qs ? `?${qs}` : "";
+}
+
+// src/client/errors.ts
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function isApiErrorItemLike(value) {
+  return isRecord(value) && "message" in value;
+}
+function extractApiErrors(body) {
+  if (!isRecord(body)) return void 0;
+  const errors = body.errors;
+  if (!Array.isArray(errors)) return void 0;
+  const out = [];
+  for (const e of errors) {
+    if (!isApiErrorItemLike(e)) continue;
+    const msg = typeof e.message === "string" ? e.message : void 0;
+    if (!msg) continue;
+    const field = typeof e.field === "string" ? e.field : void 0;
+    out.push(field ? { message: msg, field } : { message: msg });
+  }
+  return out.length ? out : void 0;
+}
+var WishlistStackApiError = class extends Error {
+  constructor(message, details) {
+    super(message);
+    __publicField(this, "name", "WishlistStackApiError");
+    __publicField(this, "status");
+    __publicField(this, "url");
+    __publicField(this, "method");
+    __publicField(this, "requestId");
+    __publicField(this, "body");
+    this.status = details.status;
+    this.url = details.url;
+    this.method = details.method;
+    this.requestId = details.requestId;
+    this.body = details.body;
+  }
+  /**
+   * Best-effort extraction of API error items from the response body.
+   * Useful for UI/logging without needing to know the exact response shape.
+   */
+  get apiErrors() {
+    return extractApiErrors(this.body);
+  }
+  /**
+   * Convenience: extracted error messages (if present).
+   */
+  get apiErrorMessages() {
+    const errs = this.apiErrors;
+    return errs?.map((e) => e.message);
+  }
+};
+function isWishlistStackApiError(value) {
+  if (!isRecord(value)) return false;
+  return value.name === "WishlistStackApiError" && typeof value.status === "number" && typeof value.url === "string" && typeof value.method === "string";
+}
+
+// src/client/request.ts
+async function safeParseJson(res) {
+  const contentType = res.headers.get("content-type") ?? "";
+  if (!contentType.toLowerCase().includes("application/json")) return void 0;
+  try {
+    return await res.json();
+  } catch {
+    return void 0;
+  }
+}
+function createRequest(ctx) {
+  return async function request(args) {
+    const url = `${ctx.baseUrl}${args.path}${toQueryString(args.query)}`;
+    const headers = {
+      "X-Wishlist-Stack-Api-Key": ctx.apiKey,
+      ...args.headers ?? {}
+    };
+    if (args.auth === "authenticated") {
+      const token = ctx.customerAccessToken;
+      if (token) headers["X-Shopify-Customer-Access-Token"] = token;
+    }
+    let body;
+    if (args.body !== void 0) {
+      headers["content-type"] ?? (headers["content-type"] = "application/json");
+      body = JSON.stringify(args.body);
+    }
+    const controller = args.timeoutMs ? new AbortController() : void 0;
+    const timeout = args.timeoutMs && controller ? setTimeout(() => controller.abort(), args.timeoutMs) : void 0;
+    const signal = args.signal ? args.signal : controller ? controller.signal : void 0;
+    const res = await ctx.fetch(url, {
+      method: args.method,
+      headers,
+      body,
+      signal
+    });
+    if (timeout) clearTimeout(timeout);
+    if (!res.ok) {
+      const errBody = await safeParseJson(res);
+      const requestId = res.headers.get("fly-request-id") ?? res.headers.get("x-request-id") ?? void 0;
+      throw new WishlistStackApiError(`Wishlist Stack API request failed (${res.status})`, {
+        status: res.status,
+        url,
+        method: args.method,
+        requestId,
+        body: errBody
+      });
+    }
+    if (res.status === 204) return void 0;
+    const parsed = await safeParseJson(res);
+    if (parsed === void 0) {
+      const text = await res.text().catch(() => "");
+      return text;
+    }
+    return parsed;
+  };
+}
+
+// src/resources/lists/index.ts
+function createListsResource(request) {
+  return {
+    /** Returns all lists for the authenticated customer under the current merchant. */
+    getAll: (query) => request({
+      method: "GET",
+      path: "/api/lists",
+      auth: "authenticated",
+      query
+    }),
+    /** Fetch list details by id. */
+    getById: (listId, query) => request({
+      method: "GET",
+      path: `/api/lists/${encodeURIComponent(listId)}`,
+      auth: "authenticated",
+      query
+    }),
+    /** Create a new list. */
+    create: (body) => request({
+      method: "POST",
+      path: "/api/lists",
+      auth: "authenticated",
+      body
+    }),
+    /** Update list name/description. */
+    update: (listId, body) => request({
+      method: "PATCH",
+      path: `/api/lists/${encodeURIComponent(listId)}`,
+      auth: "authenticated",
+      body
+    }),
+    /** Remove a list. */
+    remove: (listId) => request({
+      method: "DELETE",
+      path: `/api/lists/${encodeURIComponent(listId)}`,
+      auth: "authenticated"
+    }),
+    /** Add one or more items to a list. */
+    addItems: (listId, body) => request({
+      method: "POST",
+      path: `/api/lists/${encodeURIComponent(listId)}/add`,
+      auth: "authenticated",
+      body
+    }),
+    /** Update an item on a list. */
+    updateItem: (listId, itemId, body) => request({
+      method: "PATCH",
+      path: `/api/lists/${encodeURIComponent(listId)}/items/${encodeURIComponent(itemId)}`,
+      auth: "authenticated",
+      body
+    }),
+    /** Remove an item from a list. */
+    removeItem: (listId, itemId) => request({
+      method: "DELETE",
+      path: `/api/lists/${encodeURIComponent(listId)}/items/${encodeURIComponent(itemId)}`,
+      auth: "authenticated"
+    }),
+    /** Mark list as shared (public read-only). */
+    share: (listId) => request({
+      method: "POST",
+      path: `/api/lists/${encodeURIComponent(listId)}/share`,
+      auth: "authenticated"
+    }),
+    /** Revoke list sharing. */
+    unshare: (listId) => request({
+      method: "DELETE",
+      path: `/api/lists/${encodeURIComponent(listId)}/share`,
+      auth: "authenticated"
+    }),
+    /**
+     * Legacy endpoint kept in the OpenAPI spec (`/api/wishlists/{id}/add`).
+     * Prefer `addItems(listId, body)` unless your server only supports the legacy route.
+     */
+    addItemsLegacy: (id, body) => request({
+      method: "POST",
+      path: `/api/wishlists/${encodeURIComponent(id)}/add`,
+      auth: "authenticated",
+      body
+    })
+  };
+}
+
+// src/resources/groups/index.ts
+function createGroupsResource(request) {
+  return {
+    /** Fetch groups for the authenticated customer. */
+    getAll: (query) => request({
+      method: "GET",
+      path: "/api/groups",
+      auth: "authenticated",
+      query
+    }),
+    /** Fetch group details by id. */
+    getById: (groupId, query) => request({
+      method: "GET",
+      path: `/api/groups/${encodeURIComponent(groupId)}`,
+      auth: "authenticated",
+      query
+    }),
+    /** Create a new group. */
+    create: (body) => request({
+      method: "POST",
+      path: "/api/groups",
+      auth: "authenticated",
+      body
+    }),
+    /** Update group name/description. */
+    update: (groupId, body) => request({
+      method: "PATCH",
+      path: `/api/groups/${encodeURIComponent(groupId)}`,
+      auth: "authenticated",
+      body
+    }),
+    /** Remove a group. */
+    remove: (groupId) => request({
+      method: "DELETE",
+      path: `/api/groups/${encodeURIComponent(groupId)}`,
+      auth: "authenticated"
+    }),
+    /** Reorder a group (spec uses listIds payload). */
+    reorder: (groupId, body) => request({
+      method: "POST",
+      path: `/api/groups/${encodeURIComponent(groupId)}/reorder`,
+      auth: "authenticated",
+      body
+    }),
+    /** Mark group as shared (public read-only). */
+    share: (groupId) => request({
+      method: "POST",
+      path: `/api/groups/${encodeURIComponent(groupId)}/share`,
+      auth: "authenticated"
+    }),
+    /** Revoke group sharing. */
+    unshare: (groupId) => request({
+      method: "DELETE",
+      path: `/api/groups/${encodeURIComponent(groupId)}/share`,
+      auth: "authenticated"
+    })
+  };
+}
+
+// src/resources/shared/index.ts
+function createSharedResource(request) {
+  return {
+    /** Public read-only view of a shared list. Requires only merchant apiKey. */
+    getSharedList: (listId) => request({
+      method: "GET",
+      path: `/api/shared/list/${encodeURIComponent(listId)}`,
+      auth: "merchant"
+    }),
+    /** Public read-only view of a shared group. Requires only merchant apiKey. */
+    getSharedGroup: (groupId) => request({
+      method: "GET",
+      path: `/api/shared/group/${encodeURIComponent(groupId)}`,
+      auth: "merchant"
+    })
+  };
+}
+
+// src/client/createWishlistStackClient.ts
+function createWishlistStackClient(opts) {
+  if (!opts.apiKey) {
+    throw new Error(
+      "merchant api key is required. Pass it to createWishlistStackClient({ apiKey })"
+    );
+  }
+  const fetchImpl = opts.fetch ?? (typeof globalThis.fetch === "function" ? ((input, init) => globalThis.fetch(input, init)) : void 0);
+  if (!fetchImpl) {
+    throw new Error(
+      "No fetch implementation found. Provide one via createWishlistStackClient({ fetch }) or use Node 18+ / modern browsers."
+    );
+  }
+  const request = createRequest({
+    baseUrl: opts.baseUrl ?? BASE_URL,
+    apiKey: opts.apiKey,
+    customerAccessToken: opts.customerAccessToken,
+    fetch: fetchImpl
+  });
+  return {
+    lists: createListsResource(request),
+    groups: createGroupsResource(request),
+    shared: createSharedResource(request)
+  };
+}
+
+// src/WishlistStackClient.ts
+var WishlistStackClient = class {
+  constructor(opts) {
+    __publicField(this, "lists");
+    __publicField(this, "groups");
+    __publicField(this, "shared");
+    const client = createWishlistStackClient(opts);
+    this.lists = client.lists;
+    this.groups = client.groups;
+    this.shared = client.shared;
+  }
+  /** Back-compat alias: `client.groups.getAll()` */
+  getGroups() {
+    return this.groups.getAll();
+  }
+  /** Back-compat alias: `client.groups.getById(groupId)` */
+  getGroupById(groupId) {
+    return this.groups.getById(groupId);
+  }
+  /** Back-compat alias: `client.lists.getAll()` */
+  getLists() {
+    return this.lists.getAll();
+  }
+};
+
+// src/types/pagination.ts
+var DEFAULT_PAGE = 1;
+var DEFAULT_PAGE_SIZE = MAX_PAGINATION_SIZE;
+
+// src/types/query-options.ts
+function withPagination(query, pagination) {
+  if (!query && !pagination) return void 0;
+  return { ...query ?? {}, ...pagination ?? {} };
+}
+
+exports.DEFAULT_PAGE = DEFAULT_PAGE;
+exports.DEFAULT_PAGE_SIZE = DEFAULT_PAGE_SIZE;
+exports.WishlistStackApiError = WishlistStackApiError;
+exports.WishlistStackSDK = WishlistStackClient;
+exports.createWishlistStackClient = createWishlistStackClient;
+exports.isWishlistStackApiError = isWishlistStackApiError;
+exports.withPagination = withPagination;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map