@sdg.la/wishlist-stack-sdk 0.13.0 → 0.14.0

package/README.md

@@ -34,8 +34,9 @@ TypeScript/JavaScript SDK for the Wishlist Stack API.
 - **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
+- **Built-in error handling** — Structured `WishlistStackApiError` with status codes, `Retry-After` / rate-limit headers, and API error messages
+- **Pagination support** — List endpoints support `page` and `pageSize` (max **25**); helpers fetch all pages when needed
+- **Batch helpers** — `lists.addItemsBatched` chunks adds to the max of 25 items per request
 - **Sort support** — Collection endpoints accept `sortBy` (`position` | `createdAt` | `updatedAt`) and `sortDirection` (`asc` | `desc`)
 
 ## Requirements
@@ -65,6 +66,9 @@ import { createWishlistStackClient } from '@sdg.la/wishlist-stack-sdk';
 const client = createWishlistStackClient({
   apiKey: 'your-merchant-api-key',
   customerAccessToken: 'customer-access-token', // required for authenticated endpoints
+  // optional:
+  // defaultTimeoutMs: 10_000,
+  // retryOnRateLimit: true, // single retry with jitter on HTTP 429
 });
 
 // Fetch all groups
@@ -74,6 +78,30 @@ const { groups } = await client.groups.getAll();
 const { lists } = await client.lists.getAll();
 ```
 
+### Pagination, batching, and add responses
+
+The API paginates list detail (max `pageSize` **25**) and returns an add **delta** (`{ listId, addedItems, addedCount }`).
+
+| Concern | Guidance |
+|---------|----------|
+| List detail | Prefer `page` / `pageSize` ≤ 25, or `lists.getByIdAllItems` for every item |
+| Adding many items | Use `lists.addItemsBatched` (chunks of ≤ 25) |
+| Add response | `{ listId, addedItems, addedCount }` |
+| Create + items | Do not send `variantIds` on create; create the list, then `addItems` |
+| `quantity` on add | Supported **1–999** |
+| `includeLists` | Cap of **10 lists × 25 items**; use `getById` helpers for full data |
+| Groups | May return **503** until enabled for the merchant |
+
+```ts
+import { clampPageSize } from '@sdg.la/wishlist-stack-sdk';
+
+const res = await client.lists.addItemsBatched(id, { items: many });
+// res.addedItems / res.addedCount — then refresh if needed:
+const full = await client.lists.getByIdAllItems(id, {
+  pageSize: clampPageSize(25),
+});
+```
+
 ## Usage
 
 ### Server / Node.js / Workers
@@ -175,26 +203,38 @@ try {
     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
+    console.log(error.retryAfter);       // Retry-After header (429)
+    console.log(error.rateLimit);        // X-RateLimit-* headers when present
   }
 }
 ```
 
+Groups endpoints may return **503** with message `Groups API disabled for this merchant` until the Groups API is enabled.
+
 ## Pagination
 
-Endpoints that return lists support pagination via query parameters:
+Endpoints that return lists support pagination via query parameters. Keep `pageSize` in **1–25** (use `clampPageSize()`). Prefer `lists.getByIdAllItems()` when you need every item.
 
 ```ts
+import { clampPageSize } from '@sdg.la/wishlist-stack-sdk';
+
 // Paginate groups
 await client.groups.getAll({ page: 2, pageSize: 10 });
 
-// Include lists + hydrated items on groups.getAll
+// includeLists is capped at 10 lists × 25 items
 await client.groups.getAll({ includeLists: true });
 
 // 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 });
+await client.lists.getById('list-id', {
+  page: 1,
+  pageSize: clampPageSize(25),
+});
+
+// Or fetch every page:
+await client.lists.getByIdAllItems('list-id', { pageSize: 25 });
 ```
 
 **Pagination response structure:**
@@ -242,7 +282,7 @@ Fetch all groups for the authenticated customer.
 - **Parameters:** `query?` — `{ page?: number; pageSize?: number; query?: string; includeLists?: boolean | 1 | "1"; sortBy?: 'position' | 'createdAt' | 'updatedAt'; sortDirection?: 'asc' | 'desc' }`
 - **Returns:** `Promise<GetGroupsResponse>`
 
-Pass `includeLists: true` (sent as `includeLists=1`) to embed every list under each group with fully hydrated items — useful for loading projects/boards in one call instead of per-group `getById` fan-out. Without it, `lists` is an empty array and only `featuredItems` are populated.
+Pass `includeLists: true` (sent as `includeLists=1`) to embed lists under each group with hydrated items. Expect at most **10 lists × 25 items** per group — use `groups.getById` + `lists.getById` / `lists.getByIdAllItems` for full data. Without `includeLists`, `lists` is an empty array and only `featuredItems` are populated. Groups may return **503** until enabled for the merchant.
 
 ```ts
 const { groups, pagination } = await client.groups.getAll({ page: 1, pageSize: 10, query: 'holiday', sortBy: 'updatedAt', sortDirection: 'desc' });
@@ -544,18 +584,17 @@ const copy = await client.groups.duplicate('group-id');
 
 ---
 
-#### `groups.reorder(groupId, body)`
+#### `groups.reorder(body)`
 
-Reorder lists within a group.
+Reorder the customer's groups.
 
-- **Endpoint:** `POST /api/groups/{groupId}/reorder`
+- **Endpoint:** `POST /api/groups/reorder`
 - **Parameters:**
-  - `groupId` — `string`
-  - `body` — `{ listIds?: string[] }`
-- **Returns:** `Promise<ReorderGroupResponse>`
+  - `body` — `{ groupIds: string[] }` (group CUIDs in the desired order)
+- **Returns:** `Promise<ReorderGroupsResponse>`
 
 ```ts
-await client.groups.reorder('group-id', { listIds: ['list-3', 'list-1', 'list-2'] });
+await client.groups.reorder({ groupIds: ['group-3', 'group-1', 'group-2'] });
 ```
 
 ---
@@ -683,16 +722,17 @@ const { lists, pagination } = await client.lists.getAll({ page: 1, pageSize: 10,
 
 #### `lists.getById(listId, query?)`
 
-Fetch a single list by ID. Items are hydrated with Shopify product data and paginated.
+Fetch a single list by ID. Items are hydrated with Shopify product data and paginated. The response includes `pagination` (max `pageSize` **25**).
 
 - **Endpoint:** `GET /api/lists/{listId}`
 - **Parameters:**
   - `listId` — `string`
   - `query?` — `{ page?: number; pageSize?: number; sortBy?: 'position' | 'createdAt' | 'updatedAt'; sortDirection?: 'asc' | 'desc' }`
-- **Returns:** `Promise<GetListResponse>`
+- **Returns:** `Promise<GetListResponse>` (`ListDetail & { pagination: Pagination }`)
 
 ```ts
 const list = await client.lists.getById('list-id', { page: 1, pageSize: 25, sortBy: 'updatedAt', sortDirection: 'desc' });
+// list.pagination.totalPages
 ```
 
 <details>
@@ -757,9 +797,19 @@ const list = await client.lists.getById('list-id', { page: 1, pageSize: 25, sort
 
 ---
 
+#### `lists.getByIdAllItems(listId, opts?)`
+
+Walk every page of `lists.getById` and return one list with all items concatenated. Use when you need the full wishlist.
+
+```ts
+const full = await client.lists.getByIdAllItems('list-id', { pageSize: 25 });
+```
+
+---
+
 #### `lists.create(body)`
 
-Create a new list, optionally assigned to a group.
+Create a new list, optionally assigned to a group. Do **not** send `variantIds` on create (the API rejects them). Create the list, then call `addItems` / `addItemsBatched`.
 
 - **Endpoint:** `POST /api/lists`
 - **Parameters:** `body` — `{ name?: string; description?: string; groupId?: string }`
@@ -767,6 +817,9 @@ Create a new list, optionally assigned to a group.
 
 ```ts
 const list = await client.lists.create({ name: 'Gift Ideas', groupId: 'group-id' });
+await client.lists.addItems(list.id, {
+  items: [{ variantId: 'gid://shopify/ProductVariant/123', quantity: 2 }],
+});
 ```
 
 <details>
@@ -889,7 +942,7 @@ const ungrouped = await client.lists.duplicate('list-id', { groupId: null });
 
 #### `lists.addItems(listId, body)`
 
-Add one or more items to a list.
+Add one or more items to a list. Prefer `lists.addItemsBatched` when sending more than **25** items.
 
 - **Endpoint:** `POST /api/lists/{listId}/add`
 - **Parameters:**
@@ -900,6 +953,7 @@ Add one or more items to a list.
 type AddItemsToListBody = {
   items?: Array<{
     variantId?: string;
+    /** Quantity 1–999. */
     quantity?: number;
     note?: string;
     properties?: Record<string, unknown> | null;
@@ -907,15 +961,25 @@ type AddItemsToListBody = {
 };
 ```
 
-- **Returns:** `Promise<AddItemsToListResponse>` — the updated list with hydrated items (same shape as `getById`)
+- **Returns:** `Promise<AddItemsToListResponse>` — `{ listId, addedItems, addedCount }`
 
 ```ts
-await client.lists.addItems('list-id', {
+const res = await client.lists.addItems('list-id', {
   items: [
     { variantId: 'gid://shopify/ProductVariant/123', quantity: 1 },
     { variantId: 'gid://shopify/ProductVariant/456', note: 'Size M' },
   ],
 });
+
+console.log(res.addedCount, res.addedItems);
+```
+
+#### `lists.addItemsBatched(listId, body, opts?)`
+
+Chunks `items` into sequential POSTs of ≤25 (configurable via `opts.batchSize`) and merges `{ addedItems, addedCount }`.
+
+```ts
+const res = await client.lists.addItemsBatched('list-id', { items: many });
 ```
 
 ---
@@ -1163,6 +1227,11 @@ import type {
   // Errors
   WishlistStackApiError,
   WishlistStackApiErrorDetails,
+  isWishlistStackApiError,
+
+  // Helpers
+  clampPageSize,
+  isAddItemsDeltaResponse,
 
   // Groups
   GetGroupsResponse,
@@ -1174,7 +1243,9 @@ import type {
   GroupMutationResponse,
   CreateGroupBody,
   UpdateGroupBody,
+  ReorderGroupsBody,
   ReorderGroupBody,
+  ReorderGroupsResponse,
   DuplicateGroupResponse,
 
   // Lists
@@ -1186,6 +1257,8 @@ import type {
   CreateListBody,
   UpdateListBody,
   AddItemsToListBody,
+  AddItemsToListResponse,
+  AddItemsToListDeltaResponse,
   UpdateListItemBody,
   ReorderListItemsBody,
   ReorderListItemsResponse,

package/dist/index.cjs

@@ -57,11 +57,15 @@ var WishlistStackApiError = class extends Error {
     __publicField(this, "method");
     __publicField(this, "requestId");
     __publicField(this, "body");
+    __publicField(this, "retryAfter");
+    __publicField(this, "rateLimit");
     this.status = details.status;
     this.url = details.url;
     this.method = details.method;
     this.requestId = details.requestId;
     this.body = details.body;
+    this.retryAfter = details.retryAfter;
+    this.rateLimit = details.rateLimit;
   }
   /**
    * Best-effort extraction of API error items from the response body.
@@ -93,6 +97,42 @@ async function safeParseJson(res) {
     return void 0;
   }
 }
+function pickRequestId(res) {
+  return res.headers.get("fly-request-id") ?? res.headers.get("x-request-id") ?? res.headers.get("x-nf-request-id") ?? res.headers.get("x-netlify-request-id") ?? void 0;
+}
+function pickRateLimit(res) {
+  const limit = res.headers.get("x-ratelimit-limit") ?? void 0;
+  const remaining = res.headers.get("x-ratelimit-remaining") ?? void 0;
+  const reset = res.headers.get("x-ratelimit-reset") ?? void 0;
+  if (!limit && !remaining && !reset) return void 0;
+  return { limit, remaining, reset };
+}
+function errorMessageFor(status, path) {
+  if (status === 503 && path.includes("/api/groups")) {
+    return "Groups API disabled for this merchant";
+  }
+  return `Wishlist Stack API request failed (${status})`;
+}
+function parseRetryAfterMs(retryAfter) {
+  if (!retryAfter) return 0;
+  const asSeconds = Number(retryAfter);
+  if (Number.isFinite(asSeconds) && asSeconds >= 0) {
+    return Math.min(asSeconds * 1e3, 3e4);
+  }
+  const asDate = Date.parse(retryAfter);
+  if (!Number.isNaN(asDate)) {
+    return Math.min(Math.max(0, asDate - Date.now()), 3e4);
+  }
+  return 0;
+}
+function jitterDelayMs(baseMs) {
+  const base = Math.max(100, baseMs || 500);
+  const jitter = Math.floor(Math.random() * 250);
+  return Math.min(base + jitter, 3e4);
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
 function createRequest(ctx) {
   return async function request(args) {
     const url = `${ctx.baseUrl}${args.path}${toQueryString(args.query)}`;
@@ -109,25 +149,39 @@ function createRequest(ctx) {
       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);
+    const timeoutMs = args.timeoutMs ?? ctx.defaultTimeoutMs;
+    const doFetch = async () => {
+      const controller = timeoutMs ? new AbortController() : void 0;
+      const timeout = timeoutMs && controller ? setTimeout(() => controller.abort(), timeoutMs) : void 0;
+      const signal = args.signal ? args.signal : controller ? controller.signal : void 0;
+      try {
+        return await ctx.fetch(url, {
+          method: args.method,
+          headers,
+          body,
+          signal
+        });
+      } finally {
+        if (timeout) clearTimeout(timeout);
+      }
+    };
+    let res = await doFetch();
+    if (!res.ok && res.status === 429 && ctx.retryOnRateLimit) {
+      const retryAfter = res.headers.get("retry-after") ?? void 0;
+      await sleep(jitterDelayMs(parseRetryAfterMs(retryAfter)));
+      res = await doFetch();
+    }
     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})`, {
+      const retryAfter = res.headers.get("retry-after") ?? void 0;
+      throw new WishlistStackApiError(errorMessageFor(res.status, args.path), {
         status: res.status,
         url,
         method: args.method,
-        requestId,
-        body: errBody
+        requestId: pickRequestId(res),
+        body: errBody,
+        retryAfter,
+        rateLimit: pickRateLimit(res)
       });
     }
     if (res.status === 204) return void 0;
@@ -140,8 +194,38 @@ function createRequest(ctx) {
   };
 }
 
+// src/helpers/pagination.ts
+function clampPageSize(n) {
+  if (!Number.isFinite(n)) return MAX_PAGINATION_SIZE;
+  return Math.min(MAX_PAGINATION_SIZE, Math.max(1, Math.trunc(n)));
+}
+function clampPage(n) {
+  if (!Number.isFinite(n)) return 1;
+  return Math.max(1, Math.trunc(n));
+}
+
 // src/resources/lists/index.ts
+function chunkItems(items, batchSize) {
+  const size = Math.max(1, Math.min(MAX_PAGINATION_SIZE, Math.trunc(batchSize) || MAX_PAGINATION_SIZE));
+  const chunks = [];
+  for (let i = 0; i < items.length; i += size) {
+    chunks.push(items.slice(i, i + size));
+  }
+  return chunks.length ? chunks : [[]];
+}
 function createListsResource(request) {
+  const getById = (listId, query) => request({
+    method: "GET",
+    path: `/api/lists/${encodeURIComponent(listId)}`,
+    auth: "authenticated",
+    query
+  });
+  const addItems = (listId, body) => request({
+    method: "POST",
+    path: `/api/lists/${encodeURIComponent(listId)}/add`,
+    auth: "authenticated",
+    body
+  });
   return {
     /** Returns all lists for the authenticated customer under the current merchant. */
     getAll: (query) => request({
@@ -151,13 +235,47 @@ function createListsResource(request) {
       query
     }),
     /** Fetch list details by id. */
-    getById: (listId, query) => request({
-      method: "GET",
-      path: `/api/lists/${encodeURIComponent(listId)}`,
-      auth: "authenticated",
-      query
-    }),
-    /** Create a new list. */
+    getById,
+    /**
+     * Fetch every item on a list by walking pages (list detail is paginated;
+     * max pageSize 25).
+     */
+    getByIdAllItems: async (listId, opts) => {
+      const pageSize = clampPageSize(opts?.pageSize ?? MAX_PAGINATION_SIZE);
+      const sortBy = opts?.sortBy;
+      const sortDirection = opts?.sortDirection;
+      const first = await getById(listId, {
+        page: 1,
+        pageSize,
+        ...sortBy ? { sortBy } : {},
+        ...sortDirection ? { sortDirection } : {}
+      });
+      const totalPages = first.pagination.totalPages;
+      const allItems = [...first.items ?? []];
+      for (let page = 2; page <= totalPages; page++) {
+        const next = await getById(listId, {
+          page: clampPage(page),
+          pageSize,
+          ...sortBy ? { sortBy } : {},
+          ...sortDirection ? { sortDirection } : {}
+        });
+        allItems.push(...next.items ?? []);
+      }
+      const pagination = {
+        ...first.pagination,
+        page: 1,
+        pageSize
+      };
+      return {
+        ...first,
+        items: allItems,
+        pagination
+      };
+    },
+    /**
+     * Create a new list. Do not send `variantIds` — add items via `addItems`
+     * or `addItemsBatched` after create.
+     */
     create: (body) => request({
       method: "POST",
       path: "/api/lists",
@@ -189,13 +307,33 @@ function createListsResource(request) {
       auth: "authenticated",
       body
     }),
-    /** Add one or more items to a list. */
-    addItems: (listId, body) => request({
-      method: "POST",
-      path: `/api/lists/${encodeURIComponent(listId)}/add`,
-      auth: "authenticated",
-      body
-    }),
+    /**
+     * Add one or more items to a list.
+     * Returns `{ listId, addedItems, addedCount }`. Prefer `addItemsBatched`
+     * when sending more than 25 items.
+     */
+    addItems,
+    /**
+     * Add items in sequential batches of ≤25 (API hard max).
+     * Merges `{ addedItems, addedCount }` across batches.
+     */
+    addItemsBatched: async (listId, body, opts) => {
+      const items = body.items ?? [];
+      const batchSize = opts?.batchSize ?? MAX_PAGINATION_SIZE;
+      const chunks = chunkItems(items, batchSize);
+      const merged = {
+        listId,
+        addedItems: [],
+        addedCount: 0
+      };
+      for (const chunk of chunks) {
+        const res = await addItems(listId, { items: chunk });
+        merged.listId = res.listId;
+        merged.addedItems.push(...res.addedItems);
+        merged.addedCount += res.addedCount;
+      }
+      return merged;
+    },
     /** Update an item on a list. */
     updateItem: (listId, itemId, body) => request({
       method: "PATCH",
@@ -252,14 +390,20 @@ function normalizeGetGroupsQuery(query) {
 }
 function createGroupsResource(request) {
   return {
-    /** Fetch groups for the authenticated customer. */
+    /**
+     * Fetch groups for the authenticated customer.
+     * May return **503** when the Groups API is disabled for this merchant.
+     */
     getAll: (query) => request({
       method: "GET",
       path: "/api/groups",
       auth: "authenticated",
       query: normalizeGetGroupsQuery(query)
     }),
-    /** Fetch group details by id. */
+    /**
+     * Fetch group details by id.
+     * May return **503** when the Groups API is disabled for this merchant.
+     */
     getById: (groupId, query) => request({
       method: "GET",
       path: `/api/groups/${encodeURIComponent(groupId)}`,
@@ -295,10 +439,14 @@ function createGroupsResource(request) {
       path: `/api/groups/${encodeURIComponent(groupId)}/duplicate`,
       auth: "authenticated"
     }),
-    /** Reorder a group (spec uses listIds payload). */
-    reorder: (groupId, body) => request({
+    /**
+     * Reorder the customer's groups (`POST /api/groups/reorder`).
+     * Body must include `groupIds` in the desired order — not list IDs, and
+     * not a per-group path.
+     */
+    reorder: (body) => request({
       method: "POST",
-      path: `/api/groups/${encodeURIComponent(groupId)}/reorder`,
+      path: "/api/groups/reorder",
       auth: "authenticated",
       body
     }),
@@ -354,7 +502,9 @@ function createWishlistStackClient(opts) {
     baseUrl: opts.baseUrl ?? BASE_URL,
     apiKey: opts.apiKey,
     customerAccessToken: opts.customerAccessToken,
-    fetch: fetchImpl
+    fetch: fetchImpl,
+    defaultTimeoutMs: opts.defaultTimeoutMs,
+    retryOnRateLimit: opts.retryOnRateLimit
   });
   return {
     lists: createListsResource(request),
@@ -404,13 +554,25 @@ function withSort(query, sort) {
   return { ...query ?? {}, ...sort ?? {} };
 }
 
+// src/types/guards.ts
+function isRecord2(value) {
+  return typeof value === "object" && value !== null;
+}
+function isAddItemsDeltaResponse(value) {
+  if (!isRecord2(value)) return false;
+  return typeof value.listId === "string" && Array.isArray(value.addedItems) && typeof value.addedCount === "number";
+}
+
 exports.DEFAULT_PAGE = DEFAULT_PAGE;
 exports.DEFAULT_PAGE_SIZE = DEFAULT_PAGE_SIZE;
 exports.SORT_DIRECTIONS = SORT_DIRECTIONS;
 exports.SORT_FIELDS = SORT_FIELDS;
 exports.WishlistStackApiError = WishlistStackApiError;
 exports.WishlistStackSDK = WishlistStackClient;
+exports.clampPage = clampPage;
+exports.clampPageSize = clampPageSize;
 exports.createWishlistStackClient = createWishlistStackClient;
+exports.isAddItemsDeltaResponse = isAddItemsDeltaResponse;
 exports.isWishlistStackApiError = isWishlistStackApiError;
 exports.withPagination = withPagination;
 exports.withSort = withSort;