@sdg.la/wishlist-stack-sdk 0.10.1 → 0.12.0

package/AUTH_EXAMPLE.md

@@ -0,0 +1,209 @@
+# Getting a customer access token (Shopify Liquid storefront)
+
+Authenticated SDK endpoints require a `customerAccessToken`. In a Liquid theme, you typically run client-side JavaScript (theme asset or inline script) to perform the OAuth 2.0 + PKCE flow and pass the resulting `access_token` into `createWishlistStackClient({ customerAccessToken })`.
+
+**Official Shopify documentation:**
+
+- [Getting started with the Customer Account API](https://shopify.dev/docs/storefronts/headless/building-with-the-customer-account-api/getting-started) — setup, credentials, OAuth overview
+- [Customer Account API reference (OAuth)](https://shopify.dev/docs/api/customer/latest) — authorize/token endpoints, PKCE, `prompt=none` silent auth
+
+> **Example only.** This snippet is adapted from Shopify's documentation for illustration. It is not maintained or supported by this SDK. Your theme, Customer Account API settings, and Shopify session behavior may differ — mileage may vary. For Hydrogen storefronts, use [`@sdg.la/wishlist-stack-hydrogen`](../hydrogen/README.md) instead.
+
+## Flow
+
+1. Handle OAuth callback — exchange `code` for tokens
+2. Refresh existing tokens when possible
+3. Otherwise redirect with `prompt=none` for silent auth (requires an existing Shopify login session)
+
+## Prerequisites
+
+- Store ID and client ID from Customer Account API settings in Shopify admin
+- Redirect URI registered in admin (must match `redirectUri` in the script)
+- Customer logged in via the account link for silent auth to succeed
+
+## Example
+
+```js
+(async function () {
+  const storeId = "YOUR_STORE_ID";
+  const clientId = ""; // Client id from headless environment
+  const redirectUri = window.location.origin;
+
+  function generateRandomCode() {
+    const array = new Uint8Array(32);
+    crypto.getRandomValues(array);
+    return String.fromCharCode.apply(null, Array.from(array));
+  }
+
+  function base64UrlEncode(str) {
+    const base64 = btoa(str);
+    return base64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+  }
+
+  function convertBufferToString(hash) {
+    const uintArray = new Uint8Array(hash);
+    const numberArray = Array.from(uintArray);
+    return String.fromCharCode(...numberArray);
+  }
+
+  async function generateCodeVerifier() {
+    const rando = generateRandomCode();
+    return base64UrlEncode(rando);
+  }
+
+  async function generateCodeChallenge(codeVerifier) {
+    const digestOp = await crypto.subtle.digest(
+      { name: "SHA-256" },
+      new TextEncoder().encode(codeVerifier),
+    );
+    const hash = convertBufferToString(digestOp);
+    return base64UrlEncode(hash);
+  }
+
+  async function generateState() {
+    const timestamp = Date.now().toString();
+    const randomString = Math.random().toString(36).substring(2);
+    return timestamp + randomString;
+  }
+
+  async function generateNonce(length) {
+    const characters =
+      "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+    let nonce = "";
+    for (let i = 0; i < length; i++) {
+      const randomIndex = Math.floor(Math.random() * characters.length);
+      nonce += characters.charAt(randomIndex);
+    }
+    return nonce;
+  }
+
+  // ── Step 1: Check for authorization code in URL (callback handler) ──
+
+  const urlParams = new URLSearchParams(window.location.search);
+  const code = urlParams.get("code");
+
+  if (code) {
+    console.log("Authorization code found, exchanging for tokens...");
+
+    const codeVerifier = localStorage.getItem("code-verifier");
+    if (!codeVerifier) {
+      console.error("No code-verifier found in localStorage. Cannot exchange code.");
+      return;
+    }
+
+    // Clean up URL
+    urlParams.delete("code");
+    urlParams.delete("state");
+    const newUrl = `${window.location.pathname}${urlParams.toString() ? `?${urlParams.toString()}` : ""}${window.location.hash}`;
+    window.history.replaceState({}, "", newUrl);
+    localStorage.removeItem("code-verifier");
+
+    // Exchange code for tokens
+    const body = new URLSearchParams();
+    body.append("grant_type", "authorization_code");
+    body.append("client_id", clientId);
+    body.append("redirect_uri", redirectUri);
+    body.append("code", code);
+    body.append("code_verifier", codeVerifier);
+
+    try {
+      const response = await fetch(
+        `https://shopify.com/authentication/${storeId}/oauth/token`,
+        {
+          method: "POST",
+          headers: { "content-type": "application/x-www-form-urlencoded" },
+          body,
+        },
+      );
+      const data = await response.json();
+
+      if (!data.access_token) {
+        console.error("Token exchange failed:", data);
+        return;
+      }
+
+      const { access_token, expires_in, id_token, refresh_token } = data;
+      localStorage.setItem(
+        "customer-access-data",
+        JSON.stringify({ access_token, expires_in, id_token, refresh_token }),
+      );
+      console.log("Access token obtained successfully!");
+      console.log("Access Token:", access_token);
+
+      return;
+    } catch (error) {
+      console.error("Error exchanging code for tokens:", error);
+      return;
+    }
+  }
+
+  // ── Step 2: Check for existing tokens and try refresh ──
+
+  const existingData = localStorage.getItem("customer-access-data");
+  if (existingData) {
+    const parsed = JSON.parse(existingData);
+    if (parsed.refresh_token) {
+      console.log("Found existing refresh token, attempting refresh...");
+
+      const body = new URLSearchParams();
+      body.append("grant_type", "refresh_token");
+      body.append("client_id", clientId);
+      body.append("refresh_token", parsed.refresh_token);
+
+      try {
+        const response = await fetch(
+          `https://shopify.com/authentication/${storeId}/oauth/token`,
+          {
+            method: "POST",
+            headers: { "content-type": "application/x-www-form-urlencoded" },
+            body,
+          },
+        );
+        const data = await response.json();
+
+        if (data.access_token) {
+          localStorage.setItem(
+            "customer-access-data",
+            JSON.stringify({
+              access_token: data.access_token,
+              expires_in: data.expires_in,
+              id_token: data.id_token || parsed.id_token,
+              refresh_token: data.refresh_token,
+            }),
+          );
+          console.log("Token refreshed successfully!");
+          console.log("Access Token:", data.access_token);
+          return;
+        }
+      } catch (error) {
+        console.warn("Refresh failed, will attempt silent auth:", error);
+      }
+    }
+  }
+
+  const state = await generateState();
+  const nonce = await generateNonce(16);
+  const verifier = await generateCodeVerifier();
+  const challenge = await generateCodeChallenge(verifier);
+  localStorage.setItem("code-verifier", verifier);
+
+  const authUrl = new URL(
+    `https://shopify.com/authentication/${storeId}/oauth/authorize`,
+  );
+  authUrl.searchParams.append("scope", "openid email customer-account-api:full");
+  authUrl.searchParams.append("client_id", clientId);
+  authUrl.searchParams.append("response_type", "code");
+  authUrl.searchParams.append("redirect_uri", redirectUri);
+  authUrl.searchParams.append("state", state);
+  authUrl.searchParams.append("nonce", nonce);
+  authUrl.searchParams.append("code_challenge", challenge);
+  authUrl.searchParams.append("code_challenge_method", "S256");
+  authUrl.searchParams.append("prompt", "none"); // Silent auth - no login UI
+
+  console.log("Redirecting for silent auth...");
+  console.log("If you see a login_required error in the URL after redirect,");
+  console.log("it means no Shopify session exists - log in via the account link first.");
+
+  window.location.href = authUrl.toString();
+})();
+```

package/README.md

@@ -14,9 +14,12 @@ TypeScript/JavaScript SDK for the Wishlist Stack API.
 - [Usage](#usage)
   - [Server / Node.js / Workers](#server--nodejs--workers)
   - [Browser](#browser)
+  - [Raw HTML (script module)](#raw-html-script-module)
+  - [Shopify Liquid authentication](#shopify-liquid-authentication)
   - [Class API](#class-api)
 - [Error Handling](#error-handling)
 - [Pagination](#pagination)
+- [Sorting](#sorting)
 - [API Reference](#api-reference)
   - [Groups](#groups)
   - [Lists](#lists)
@@ -33,6 +36,7 @@ TypeScript/JavaScript SDK for the Wishlist Stack API.
 - **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
+- **Sort support** — Collection endpoints accept `sortBy` (`position` | `createdAt` | `updatedAt`) and `sortDirection` (`asc` | `desc`)
 
 ## Requirements
 
@@ -102,6 +106,35 @@ 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`.
 
+### Raw HTML (script module)
+
+You can load the SDK in plain HTML without a bundler by using a `<script type="module">` tag and importing from a CDN:
+
+```html
+<script type="module">
+  import { createWishlistStackClient } from "https://cdn.jsdelivr.net/npm/@sdg.la/wishlist-stack-sdk@0.10.1/+esm";
+
+  window.wishlistClient = createWishlistStackClient({
+    apiKey: "YOUR_MERCHANT_API_KEY",
+    customerAccessToken: "...",
+  });
+
+  // Example usage:
+  await window.wishlistClient.groups.getAll();
+  await window.wishlistClient.lists.getAll();
+</script>
+```
+
+Pin the version in the CDN URL (as shown above) so updates do not break your integration unexpectedly.
+
+> **Note:** With a strict CSP, allow `https://cdn.jsdelivr.net` in `script-src` (for the module import) and your API domain in `connect-src`.
+
+### Shopify Liquid authentication
+
+Authenticated SDK calls require a customer access token. For Liquid themes, obtain one via Shopify's Customer Account API OAuth flow in the browser.
+
+See [AUTH_EXAMPLE.md](./AUTH_EXAMPLE.md) for an example-only reference implementation adapted from Shopify's docs.
+
 ### Class API
 
 If you prefer a class-based API, use `WishlistStackSDK`:
@@ -154,6 +187,9 @@ Endpoints that return lists support pagination via query parameters:
 // Paginate groups
 await client.groups.getAll({ page: 2, pageSize: 10 });
 
+// Include lists + hydrated items on groups.getAll
+await client.groups.getAll({ includeLists: true });
+
 // Paginate lists within a group
 await client.groups.getById('group-id', { page: 1, pageSize: 25 });
 
@@ -172,6 +208,24 @@ await client.lists.getById('list-id', { page: 1, pageSize: 25 });
 }
 ```
 
+## Sorting
+
+Collection endpoints accept optional sort parameters. Defaults match historical behavior (`sortBy=position`, `sortDirection=asc`). Sorting applies only to the primary collection returned by the endpoint.
+
+```ts
+// Recently updated groups first
+await client.groups.getAll({ sortBy: 'updatedAt', sortDirection: 'desc' });
+
+// Newest lists first
+await client.lists.getAll({ sortBy: 'createdAt', sortDirection: 'desc' });
+
+// Sort items in a list by updatedAt
+await client.lists.getById('list-id', { sortBy: 'updatedAt', sortDirection: 'desc' });
+
+// Shared endpoints support the same params
+await client.shared.getSharedList('list-id', { sortBy: 'createdAt', sortDirection: 'asc' });
+```
+
 ## API Reference
 
 ### Groups
@@ -185,11 +239,16 @@ await client.lists.getById('list-id', { page: 1, pageSize: 25 });
 Fetch all groups for the authenticated customer.
 
 - **Endpoint:** `GET /api/groups`
-- **Parameters:** `query?` — `{ page?: number; pageSize?: number, query?: string }`
+- **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.
+
 ```ts
-const { groups, pagination } = await client.groups.getAll({ page: 1, pageSize: 10, query: 'holiday' });
+const { groups, pagination } = await client.groups.getAll({ page: 1, pageSize: 10, query: 'holiday', sortBy: 'updatedAt', sortDirection: 'desc' });
+
+// Include lists + hydrated items
+const { groups: withLists } = await client.groups.getAll({ includeLists: true });
 ```
 
 <details>
@@ -205,6 +264,7 @@ const { groups, pagination } = await client.groups.getAll({ page: 1, pageSize: 1
       "position": 1,
       "shared": false,
       "listCount": 2,
+      "lists": [],
       "createdAt": "2025-01-10T08:00:00.000Z",
       "updatedAt": "2025-01-18T12:00:00.000Z",
       "featuredItems": [
@@ -231,6 +291,75 @@ const { groups, pagination } = await client.groups.getAll({ page: 1, pageSize: 1
 
 </details>
 
+<details>
+<summary>Example response with <code>includeLists: true</code></summary>
+
+```json
+{
+  "groups": [
+    {
+      "id": "cml8drad90001js09weonjojg",
+      "name": "Holiday Lists",
+      "description": "All my holiday wishlists",
+      "position": 1,
+      "shared": false,
+      "listCount": 1,
+      "lists": [
+        {
+          "id": "cml8drg8x0003js093j4ua6p8",
+          "name": "Gift Ideas",
+          "description": "Birthday gift ideas",
+          "position": 1,
+          "shared": false,
+          "itemCount": 1,
+          "items": [
+            {
+              "id": "item_1",
+              "quantity": 1,
+              "position": 1,
+              "userNote": null,
+              "product": {
+                "id": "gid://shopify/Product/1",
+                "title": "Example Product",
+                "description": "",
+                "availableForSale": true,
+                "handle": "example-product",
+                "productType": null,
+                "category": null,
+                "tags": [],
+                "onlineStoreUrl": null,
+                "metafields": [],
+                "vendor": null,
+                "variant": {
+                  "id": "46932429275374",
+                  "title": "Default",
+                  "price": { "amount": "10.00", "currencyCode": "USD" },
+                  "availableForSale": true,
+                  "currentlyNotInStock": false,
+                  "selectedOptions": [],
+                  "metafields": []
+                }
+              }
+            }
+          ]
+        }
+      ],
+      "featuredItems": [],
+      "createdAt": "2025-01-10T08:00:00.000Z",
+      "updatedAt": "2025-01-18T12:00:00.000Z"
+    }
+  ],
+  "pagination": {
+    "page": 1,
+    "pageSize": 10,
+    "totalCount": 1,
+    "totalPages": 1
+  }
+}
+```
+
+</details>
+
 ---
 
 #### `groups.getById(groupId, query?)`
@@ -240,11 +369,11 @@ Fetch a single group by ID. Lists within the group are paginated.
 - **Endpoint:** `GET /api/groups/{groupId}`
 - **Parameters:**
   - `groupId` — `string`
-  - `query?` — `{ page?: number; pageSize?: number, query?: string }`
+  - `query?` — `{ page?: number; pageSize?: number; query?: string; sortBy?: 'position' | 'createdAt' | 'updatedAt'; sortDirection?: 'asc' | 'desc' }`
 - **Returns:** `Promise<GetGroupResponse>`
 
 ```ts
-const group = await client.groups.getById('group-id', { page: 1, pageSize: 25, query: 'gift' });
+const group = await client.groups.getById('group-id', { page: 1, pageSize: 25, query: 'gift', sortBy: 'updatedAt', sortDirection: 'desc' });
 ```
 
 <details>
@@ -383,6 +512,38 @@ await client.groups.remove('group-id');
 
 ---
 
+#### `groups.duplicate(groupId)`
+
+Duplicate a group in a single call, including all of its lists and items. The copy is named `Copy of {original name}` and is not shared.
+
+- **Endpoint:** `POST /api/groups/{groupId}/duplicate`
+- **Parameters:** `groupId` — `string`
+- **Returns:** `Promise<DuplicateGroupResponse>`
+
+```ts
+const copy = await client.groups.duplicate('group-id');
+```
+
+<details>
+<summary>Example response</summary>
+
+```json
+{
+  "id": "cmlbe49qk0001ju094x1ya9co",
+  "name": "Copy of Holiday Lists",
+  "description": "All my holiday wishlists",
+  "position": 2,
+  "shared": false,
+  "listCount": 2,
+  "createdAt": "2025-01-22T09:15:00.000Z",
+  "updatedAt": "2025-01-22T09:15:00.000Z"
+}
+```
+
+</details>
+
+---
+
 #### `groups.reorder(groupId, body)`
 
 Reorder lists within a group.
@@ -472,11 +633,11 @@ await client.groups.unshare('group-id');
 Fetch all lists for the authenticated customer.
 
 - **Endpoint:** `GET /api/lists`
-- **Parameters:** `query?` — `{ page?: number; pageSize?: number, query?: string }`
+- **Parameters:** `query?` — `{ page?: number; pageSize?: number; query?: string; sortBy?: 'position' | 'createdAt' | 'updatedAt'; sortDirection?: 'asc' | 'desc' }`
 - **Returns:** `Promise<GetListsResponse>`
 
 ```ts
-const { lists, pagination } = await client.lists.getAll({ page: 1, pageSize: 10 });
+const { lists, pagination } = await client.lists.getAll({ page: 1, pageSize: 10, sortBy: 'updatedAt', sortDirection: 'desc' });
 ```
 
 <details>
@@ -527,11 +688,11 @@ Fetch a single list by ID. Items are hydrated with Shopify product data and pagi
 - **Endpoint:** `GET /api/lists/{listId}`
 - **Parameters:**
   - `listId` — `string`
-  - `query?` — `{ page?: number; pageSize?: number }`
+  - `query?` — `{ page?: number; pageSize?: number; sortBy?: 'position' | 'createdAt' | 'updatedAt'; sortDirection?: 'asc' | 'desc' }`
 - **Returns:** `Promise<GetListResponse>`
 
 ```ts
-const list = await client.lists.getById('list-id', { page: 1, pageSize: 25 });
+const list = await client.lists.getById('list-id', { page: 1, pageSize: 25, sortBy: 'updatedAt', sortDirection: 'desc' });
 ```
 
 <details>
@@ -685,6 +846,38 @@ await client.lists.remove('list-id');
 
 ---
 
+#### `lists.duplicate(listId)`
+
+Duplicate a list in a single call, including all of its items. The copy stays in the same group (if any), is named `Copy of {original name}`, and is not shared.
+
+- **Endpoint:** `POST /api/lists/{listId}/duplicate`
+- **Parameters:** `listId` — `string`
+- **Returns:** `Promise<DuplicateListResponse>`
+
+```ts
+const copy = await client.lists.duplicate('list-id');
+```
+
+<details>
+<summary>Example response</summary>
+
+```json
+{
+  "id": "cml8drg8x0003js093j4ua6p8",
+  "name": "Copy of Gift Ideas",
+  "description": "Birthday gift ideas",
+  "position": 2,
+  "shared": false,
+  "itemCount": 3,
+  "createdAt": "2025-01-22T09:15:00.000Z",
+  "updatedAt": "2025-01-22T09:15:00.000Z"
+}
+```
+
+</details>
+
+---
+
 #### `lists.addItems(listId, body)`
 
 Add one or more items to a list.
@@ -918,30 +1111,34 @@ Public read-only endpoints for accessing shared lists and groups. These require
 
 ---
 
-#### `shared.getSharedList(listId)`
+#### `shared.getSharedList(listId, query?)`
 
 Fetch a public shared list with hydrated product details.
 
 - **Endpoint:** `GET /api/shared/list/{listId}`
-- **Parameters:** `listId` — `string`
+- **Parameters:**
+  - `listId` — `string`
+  - `query?` — `{ page?: number; pageSize?: number; sortBy?: 'position' | 'createdAt' | 'updatedAt'; sortDirection?: 'asc' | 'desc' }`
 - **Returns:** `Promise<GetSharedListResponse>` — same response shape as [`lists.getById`](#listsgetbyidlistid-query)
 
 ```ts
-const list = await client.shared.getSharedList('list-id');
+const list = await client.shared.getSharedList('list-id', { sortBy: 'updatedAt', sortDirection: 'desc' });
 ```
 
 ---
 
-#### `shared.getSharedGroup(groupId)`
+#### `shared.getSharedGroup(groupId, query?)`
 
 Fetch a public shared group and its lists.
 
 - **Endpoint:** `GET /api/shared/group/{groupId}`
-- **Parameters:** `groupId` — `string`
+- **Parameters:**
+  - `groupId` — `string`
+  - `query?` — `{ page?: number; pageSize?: number; query?: string; sortBy?: 'position' | 'createdAt' | 'updatedAt'; sortDirection?: 'asc' | 'desc' }`
 - **Returns:** `Promise<GetSharedGroupResponse>` — same response shape as [`groups.getById`](#groupsgetbyidgroupid-query)
 
 ```ts
-const group = await client.shared.getSharedGroup('group-id');
+const group = await client.shared.getSharedGroup('group-id', { sortBy: 'createdAt', sortDirection: 'asc' });
 ```
 
 ## TypeScript Types
@@ -962,23 +1159,28 @@ import type {
   GetGroupsResponse,
   GetGroupResponse,
   GroupSummary,
+  GroupSummaryList,
   GroupDetail,
   GroupDetailList,
+  GroupMutationResponse,
   CreateGroupBody,
   UpdateGroupBody,
   ReorderGroupBody,
+  DuplicateGroupResponse,
 
   // Lists
   GetListsResponse,
   GetListResponse,
   ListSummary,
   ListDetail,
+  ListMutationResponse,
   CreateListBody,
   UpdateListBody,
   AddItemsToListBody,
   UpdateListItemBody,
   ReorderListItemsBody,
   ReorderListItemsResponse,
+  DuplicateListResponse,
 
   // Shared
   GetSharedListResponse,
@@ -1030,10 +1232,22 @@ type GroupSummary = {
   position: number;
   shared: boolean;
   listCount: number;
+  /** Empty unless `includeLists` was requested on `groups.getAll()`. */
+  lists: GroupSummaryList[];
   featuredItems: FeaturedItem[];
   createdAt: string;
   updatedAt: string;
 };
+
+type GroupSummaryList = {
+  id: string;
+  name: string;
+  description: string | null;
+  position: number;
+  shared: boolean;
+  itemCount: number;
+  items: HydratedWishlistItem[];
+};
 ```
 
 </details>