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

package/dist/index.d.ts

@@ -12,6 +12,8 @@ type RequestArgs<TBody> = {
     headers?: Record<string, string>;
     signal?: AbortSignal;
     timeoutMs?: number;
+    /** Marks a non-GET operation as safe to retry once on HTTP 429. */
+    retryable?: boolean;
 };
 
 type PaginationParams = {
@@ -51,8 +53,12 @@ declare function withPagination<TExtra extends Query>(query?: TExtra, pagination
  */
 declare function withSort<TExtra extends Query>(query?: TExtra, sort?: SortParams): (TExtra & SortParams) | undefined;
 
+/**
+ * Create a new list. Do **not** send `variantIds` — the API may reject them.
+ * Create the list, then call `lists.addItems` or `lists.addItemsBatched`.
+ */
 type CreateListBody = {
-    name?: string;
+    name: string;
     description?: string;
     groupId?: string;
 };
@@ -62,13 +68,18 @@ type UpdateListBody = {
     groupId?: string;
 };
 type AddItemsToListBody = {
-    items?: Array<{
-        variantId?: string;
+    items: Array<{
+        variantId: string;
+        /** Quantity for the item (1–999). */
         quantity?: number;
         note?: string;
         properties?: Record<string, unknown> | null;
     }>;
 };
+/** Check membership for 1–100 Shopify product variant IDs. */
+type ContainsVariantsBody = {
+    variantIds: string[];
+};
 type UpdateListItemBody = {
     variantId?: string;
     quantity?: number;
@@ -96,6 +107,17 @@ type Pagination = {
     totalCount: number;
     totalPages: number;
 };
+/** Pagination metadata returned by list-detail endpoints. */
+type ListDetailPagination = {
+    page: number;
+    pageSize: number;
+    totalItems: number;
+    /** Compatibility alias for `totalItems`. */
+    totalCount: number;
+    totalPages: number;
+    hasNextPage: boolean;
+    hasPreviousPage: boolean;
+};
 type Image = {
     altText?: string | null;
     url: string;
@@ -174,14 +196,37 @@ type GetListsResponse = {
     lists: ListSummary[];
     pagination: Pagination;
 };
-/** GET `/api/lists/:listId` */
-type GetListResponse = ListDetail;
+/** GET `/api/lists/:listId` — items are paginated (max pageSize 25). */
+type GetListResponse = ListDetail & {
+    pagination: ListDetailPagination;
+};
 type ListMutationResponse = Omit<ListSummary, "featuredProducts">;
 type CreateListResponse = ListMutationResponse;
 type DuplicateListResponse = ListMutationResponse;
 type UpdateListDetailsResponse = ListMutationResponse;
 type RemoveListResponse = OkResponse;
-type AddItemsToListResponse = unknown;
+/** POST `/api/lists/:listId/add` — newly added items only. */
+type AddItemsToListResponse = {
+    listId: string;
+    addedItems: HydratedWishlistItem[];
+    addedCount: number;
+};
+/** POST `/api/lists/:listId/contains` */
+type VariantMembershipMatch = {
+    id: string;
+    variantId: string;
+    quantity: number;
+    position: number;
+    note: string | null;
+    properties: Record<string, unknown> | null;
+};
+type ContainsVariantsResponse = {
+    listId: string;
+    present: Record<string, boolean>;
+    matches: Record<string, VariantMembershipMatch[]>;
+};
+/** @deprecated Use `AddItemsToListResponse`. */
+type AddItemsToListDeltaResponse = AddItemsToListResponse;
 type UpdateListItemResponse = unknown;
 type RemoveItemFromListResponse = OkResponse;
 type ReorderListItemsResponse = {
@@ -196,12 +241,29 @@ type RevokeListSharedResponse = ListMutationResponse;
 type RequestFn$2 = <TResponse = unknown, TBody = unknown>(args: RequestArgs<TBody>) => Promise<TResponse>;
 type GetListsQuery = PaginatedQuery;
 type GetListQuery = Omit<PaginatedQuery, "query">;
+type AddItemsBatchedOptions = {
+    /** Max items per POST (API hard max is 25). */
+    batchSize?: number;
+};
+type GetByIdAllItemsOptions = {
+    pageSize?: number;
+    sortBy?: GetListQuery["sortBy"];
+    sortDirection?: GetListQuery["sortDirection"];
+};
 declare function createListsResource(request: RequestFn$2): {
     /** Returns all lists for the authenticated customer under the current merchant. */
     getAll: (query?: GetListsQuery) => Promise<GetListsResponse>;
     /** Fetch list details by id. */
-    getById: (listId: string, query?: GetListQuery) => Promise<ListDetail>;
-    /** Create a new list. */
+    getById: (listId: string, query?: GetListQuery) => Promise<GetListResponse>;
+    /**
+     * Fetch every item on a list by walking pages (list detail is paginated;
+     * max pageSize 25).
+     */
+    getByIdAllItems: (listId: string, opts?: GetByIdAllItemsOptions) => Promise<GetListResponse>;
+    /**
+     * Create a new list. Do not send `variantIds` — add items via `addItems`
+     * or `addItemsBatched` after create.
+     */
     create: (body: CreateListBody) => Promise<ListMutationResponse>;
     /** Update list name/description. */
     update: (listId: string, body: UpdateListBody) => Promise<ListMutationResponse>;
@@ -214,8 +276,22 @@ declare function createListsResource(request: RequestFn$2): {
      * The copy is named `Copy of {original name}` and is not shared.
      */
     duplicate: (listId: string, body?: DuplicateListBody) => Promise<ListMutationResponse>;
-    /** Add one or more items to a list. */
-    addItems: (listId: string, body: AddItemsToListBody) => Promise<unknown>;
+    /**
+     * Add one or more items to a list.
+     * Returns `{ listId, addedItems, addedCount }`. Prefer `addItemsBatched`
+     * when sending more than 25 items.
+     */
+    addItems: (listId: string, body: AddItemsToListBody) => Promise<AddItemsToListResponse>;
+    /**
+     * Check whether up to 100 variants are present without hydrating or
+     * paging through the list. Response keys preserve the supplied IDs.
+     */
+    containsVariants: (listId: string, body: ContainsVariantsBody) => Promise<ContainsVariantsResponse>;
+    /**
+     * Add items in sequential batches of ≤25 (API hard max).
+     * Merges `{ addedItems, addedCount }` across batches.
+     */
+    addItemsBatched: (listId: string, body: AddItemsToListBody, opts?: AddItemsBatchedOptions) => Promise<AddItemsToListResponse>;
     /** Update an item on a list. */
     updateItem: (listId: string, itemId: string, body: UpdateListItemBody) => Promise<unknown>;
     /** Remove an item from a list. */
@@ -230,7 +306,7 @@ declare function createListsResource(request: RequestFn$2): {
      * 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: string, body: AddItemsToListBody) => Promise<unknown>;
+    addItemsLegacy: (id: string, body: AddItemsToListBody) => Promise<AddItemsToListResponse>;
 };
 
 type CreateGroupBody = {
@@ -241,13 +317,20 @@ type UpdateGroupBody = {
     name?: string;
     description?: string;
 };
-type ReorderGroupBody = {
-    listIds?: string[];
+/**
+ * Body for `POST /api/groups/reorder` — reorder the customer's groups.
+ * `groupIds` must list every group CUID in the desired order.
+ */
+type ReorderGroupsBody = {
+    groupIds: string[];
 };
+/** @deprecated Use `ReorderGroupsBody` (`groupIds` on `POST /api/groups/reorder`). */
+type ReorderGroupBody = ReorderGroupsBody;
 
 /**
  * List embedded on a group when `includeLists=1` is passed to `groups.getAll()`.
- * Items are fully hydrated (same shape as `lists.getById`).
+ * Items are hydrated (same shape as `lists.getById` items).
+ * Expect at most **10 lists × 25 items** per group.
  */
 type GroupSummaryList = {
     id: string;
@@ -267,7 +350,10 @@ type GroupSummary = {
     position: number;
     shared: boolean;
     listCount: number;
-    /** Empty unless `includeLists=1` was requested. */
+    /**
+     * Empty unless `includeLists=1` was requested.
+     * Cap: 10 lists × 25 items each.
+     */
     lists: GroupSummaryList[];
     featuredItems: FeaturedItem[];
     createdAt: string;
@@ -317,23 +403,40 @@ type CreateGroupResponse = GroupMutationResponse;
 type DuplicateGroupResponse = GroupMutationResponse;
 type UpdateGroupDetailsResponse = GroupMutationResponse;
 type RemoveGroupResponse = OkResponse;
-type ReorderGroupResponse = unknown;
+type ReorderGroupsResponse = {
+    updated: Array<{
+        id: string;
+        position: number;
+    }>;
+};
+/** @deprecated Prefer `ReorderGroupsResponse`. */
+type ReorderGroupResponse = ReorderGroupsResponse;
 type MarkGroupSharedResponse = GroupMutationResponse;
 type RevokeGroupSharedResponse = GroupMutationResponse;
 
 type RequestFn$1 = <TResponse = unknown, TBody = unknown>(args: RequestArgs<TBody>) => Promise<TResponse>;
 type GetGroupsQuery = PaginatedQuery<{
     /**
-     * When truthy (`true`, `1`, or `"1"`), each group includes its full `lists`
-     * array with hydrated items. Sent to the API as `includeLists=1`.
+     * When truthy (`true`, `1`, or `"1"`), each group includes embedded `lists`
+     * with hydrated items (`includeLists=1`).
+     *
+     * Expect at most **10 lists × 25 items** per group. For full data use
+     * `groups.getById` plus `lists.getById` / `lists.getByIdAllItems`. Groups
+     * endpoints may return **503** until the Groups API is enabled for the merchant.
      */
     includeLists?: boolean | 1 | "1";
 }>;
 type GetGroupQuery = PaginatedQuery;
 declare function createGroupsResource(request: RequestFn$1): {
-    /** 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?: GetGroupsQuery) => Promise<GetGroupsResponse>;
-    /** Fetch group details by id. */
+    /**
+     * Fetch group details by id.
+     * May return **503** when the Groups API is disabled for this merchant.
+     */
     getById: (groupId: string, query?: GetGroupQuery) => Promise<GroupDetail>;
     /** Create a new group. */
     create: (body: CreateGroupBody) => Promise<GroupMutationResponse>;
@@ -346,8 +449,12 @@ declare function createGroupsResource(request: RequestFn$1): {
      * The copy is named `Copy of {original name}` and is not shared.
      */
     duplicate: (groupId: string) => Promise<GroupMutationResponse>;
-    /** Reorder a group (spec uses listIds payload). */
-    reorder: (groupId: string, body: ReorderGroupBody) => Promise<unknown>;
+    /**
+     * 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: ReorderGroupsBody) => Promise<ReorderGroupsResponse>;
     /** Mark group as shared (public read-only). */
     share: (groupId: string) => Promise<GroupMutationResponse>;
     /** Revoke group sharing. */
@@ -359,7 +466,7 @@ type GetSharedListQuery = Omit<PaginatedQuery, "query">;
 type GetSharedGroupQuery = PaginatedQuery;
 declare function createSharedResource(request: RequestFn): {
     /** Public read-only view of a shared list. Requires only merchant apiKey. */
-    getSharedList: (listId: string, query?: GetSharedListQuery) => Promise<ListDetail>;
+    getSharedList: (listId: string, query?: GetSharedListQuery) => Promise<GetListResponse>;
     /** Public read-only view of a shared group. Requires only merchant apiKey. */
     getSharedGroup: (groupId: string, query?: GetSharedGroupQuery) => Promise<GroupDetail>;
 };
@@ -369,6 +476,10 @@ type CreateWishlistStackClientOptions = {
     apiKey: string;
     customerAccessToken?: string;
     fetch?: FetchLike;
+    /** Default request timeout in ms when a call does not pass `timeoutMs`. */
+    defaultTimeoutMs?: number;
+    /** When true, retry safe reads once on HTTP 429 (default: false). */
+    retryOnRateLimit?: boolean;
 };
 type WishlistStackClient$1 = {
     lists: ReturnType<typeof createListsResource>;
@@ -389,6 +500,12 @@ type ApiErrorResponse = {
 type GetSharedListResponse = GetListResponse;
 type GetSharedGroupResponse = GetGroupResponse;
 
+/**
+ * True when the value matches the add-items response shape
+ * (`{ listId, addedItems, addedCount }`).
+ */
+declare function isAddItemsDeltaResponse(value: AddItemsToListResponse | unknown): value is AddItemsToListResponse;
+
 /**
  * Class wrapper around `createWishlistStackClient()` for users who prefer `new`.
  * Exposes `lists`, `groups`, and `shared` resources.
@@ -412,6 +529,14 @@ type WishlistStackApiErrorDetails<TBody = unknown> = {
     method: string;
     requestId?: string;
     body?: TBody;
+    /** Value of the `Retry-After` response header when present (seconds or HTTP-date). */
+    retryAfter?: string;
+    /** Selected rate-limit response headers when present. */
+    rateLimit?: {
+        limit?: string;
+        remaining?: string;
+        reset?: string;
+    };
 };
 declare class WishlistStackApiError<TBody = unknown> extends Error {
     readonly name = "WishlistStackApiError";
@@ -420,6 +545,8 @@ declare class WishlistStackApiError<TBody = unknown> extends Error {
     readonly method: string;
     readonly requestId?: string;
     readonly body?: TBody;
+    readonly retryAfter?: string;
+    readonly rateLimit?: WishlistStackApiErrorDetails["rateLimit"];
     constructor(message: string, details: WishlistStackApiErrorDetails<TBody>);
     /**
      * Best-effort extraction of API error items from the response body.
@@ -439,4 +566,14 @@ declare class WishlistStackApiError<TBody = unknown> extends Error {
  */
 declare function isWishlistStackApiError(value: unknown): value is WishlistStackApiError<unknown>;
 
-export { type AddItemsToListBody, type AddItemsToListResponse, type ApiErrorItem, type ApiErrorResponse, type CreateGroupBody, type CreateGroupResponse, type CreateListBody, type CreateListResponse, type CreateWishlistStackClientOptions, DEFAULT_PAGE, DEFAULT_PAGE_SIZE, type DuplicateGroupResponse, type DuplicateListBody, type DuplicateListResponse, type FeaturedItem, type GetGroupResponse, type GetGroupsResponse, type GetListResponse, type GetListsResponse, type GetSharedGroupResponse, type GetSharedListResponse, type GroupDetail, type GroupDetailList, type GroupMutationResponse, type GroupSummary, type GroupSummaryList, type HydratedProduct, type HydratedVariant, type HydratedWishlistItem, type Id, type Image, type ListDetail, type ListMutationResponse, type ListSummary, type MarkGroupSharedResponse, type MarkListSharedResponse, type Metafield, type Money, type OkResponse, type PaginatedQuery, type Pagination, type PaginationParams, type RemoveGroupResponse, type RemoveItemFromListResponse, type RemoveListResponse, type ReorderGroupBody, type ReorderGroupResponse, type ReorderListItemsBody, type ReorderListItemsResponse, type RevokeGroupSharedResponse, type RevokeListSharedResponse, SORT_DIRECTIONS, SORT_FIELDS, type SelectedOption, type SortDirection, type SortField, type SortParams, type UpdateGroupBody, type UpdateGroupDetailsResponse, type UpdateListBody, type UpdateListDetailsResponse, type UpdateListItemBody, type UpdateListItemResponse, WishlistStackApiError, type WishlistStackClient$1 as WishlistStackClient, WishlistStackClient as WishlistStackSDK, createWishlistStackClient, isWishlistStackApiError, withPagination, withSort };
+/**
+ * Clamp a page size to the API-allowed range (1–25) so requests
+ * do not send invalid `pageSize` values.
+ */
+declare function clampPageSize(n: number): number;
+/**
+ * Clamp a 1-based page index to at least 1.
+ */
+declare function clampPage(n: number): number;
+
+export { type AddItemsToListBody, type AddItemsToListDeltaResponse, type AddItemsToListResponse, type ApiErrorItem, type ApiErrorResponse, type ContainsVariantsBody, type ContainsVariantsResponse, type CreateGroupBody, type CreateGroupResponse, type CreateListBody, type CreateListResponse, type CreateWishlistStackClientOptions, DEFAULT_PAGE, DEFAULT_PAGE_SIZE, type DuplicateGroupResponse, type DuplicateListBody, type DuplicateListResponse, type FeaturedItem, type GetGroupResponse, type GetGroupsResponse, type GetListResponse, type GetListsResponse, type GetSharedGroupResponse, type GetSharedListResponse, type GroupDetail, type GroupDetailList, type GroupMutationResponse, type GroupSummary, type GroupSummaryList, type HydratedProduct, type HydratedVariant, type HydratedWishlistItem, type Id, type Image, type ListDetail, type ListDetailPagination, type ListMutationResponse, type ListSummary, type MarkGroupSharedResponse, type MarkListSharedResponse, type Metafield, type Money, type OkResponse, type PaginatedQuery, type Pagination, type PaginationParams, type RemoveGroupResponse, type RemoveItemFromListResponse, type RemoveListResponse, type ReorderGroupBody, type ReorderGroupResponse, type ReorderGroupsBody, type ReorderGroupsResponse, type ReorderListItemsBody, type ReorderListItemsResponse, type RevokeGroupSharedResponse, type RevokeListSharedResponse, SORT_DIRECTIONS, SORT_FIELDS, type SelectedOption, type SortDirection, type SortField, type SortParams, type UpdateGroupBody, type UpdateGroupDetailsResponse, type UpdateListBody, type UpdateListDetailsResponse, type UpdateListItemBody, type UpdateListItemResponse, type VariantMembershipMatch, WishlistStackApiError, type WishlistStackClient$1 as WishlistStackClient, WishlistStackClient as WishlistStackSDK, clampPage, clampPageSize, createWishlistStackClient, isAddItemsDeltaResponse, isWishlistStackApiError, withPagination, withSort };

package/dist/index.js

@@ -55,11 +55,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.
@@ -91,6 +95,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)}`;
@@ -107,25 +147,40 @@ 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();
+    const retryable = args.method === "GET" || args.retryable === true;
+    if (!res.ok && res.status === 429 && ctx.retryOnRateLimit && retryable) {
+      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;
@@ -138,8 +193,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({
@@ -149,13 +234,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",
@@ -187,13 +306,47 @@ function createListsResource(request) {
       auth: "authenticated",
       body
     }),
-    /** Add one or more items to a list. */
-    addItems: (listId, body) => request({
+    /**
+     * Add one or more items to a list.
+     * Returns `{ listId, addedItems, addedCount }`. Prefer `addItemsBatched`
+     * when sending more than 25 items.
+     */
+    addItems,
+    /**
+     * Check whether up to 100 variants are present without hydrating or
+     * paging through the list. Response keys preserve the supplied IDs.
+     */
+    containsVariants: (listId, body) => request({
       method: "POST",
-      path: `/api/lists/${encodeURIComponent(listId)}/add`,
+      path: `/api/lists/${encodeURIComponent(listId)}/contains`,
       auth: "authenticated",
-      body
+      body,
+      retryable: true
     }),
+    /**
+     * Add items in sequential batches of ≤25 (API hard max).
+     * Merges `{ addedItems, addedCount }` across batches.
+     */
+    addItemsBatched: async (listId, body, opts) => {
+      const items = body.items ?? [];
+      if (items.length === 0) {
+        throw new Error("lists.addItemsBatched requires at least one item");
+      }
+      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",
@@ -250,14 +403,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)}`,
@@ -293,10 +452,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
     }),
@@ -352,7 +515,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),
@@ -402,6 +567,15 @@ function withSort(query, sort) {
   return { ...query ?? {}, ...sort ?? {} };
 }
 
-export { DEFAULT_PAGE, DEFAULT_PAGE_SIZE, SORT_DIRECTIONS, SORT_FIELDS, WishlistStackApiError, WishlistStackClient as WishlistStackSDK, createWishlistStackClient, isWishlistStackApiError, withPagination, withSort };
+// 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";
+}
+
+export { DEFAULT_PAGE, DEFAULT_PAGE_SIZE, SORT_DIRECTIONS, SORT_FIELDS, WishlistStackApiError, WishlistStackClient as WishlistStackSDK, clampPage, clampPageSize, createWishlistStackClient, isAddItemsDeltaResponse, isWishlistStackApiError, withPagination, withSort };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map