@doswiftly/storefront-sdk 4.0.0

package/src/__tests__/unit/cart-client.test.ts

@@ -0,0 +1,233 @@
+/**
+ * Unit tests for CartClient — plain async cart API.
+ *
+ * Tests all cart operations with mocked StorefrontClient.
+ * Verifies assertNoUserErrors integration.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { CartClient } from '../../core/cart/cart-client';
+import { StorefrontError, ErrorCodes } from '../../core/errors';
+import type { StorefrontClient } from '../../core/client/types';
+
+// ---------------------------------------------------------------------------
+// Mock StorefrontClient
+// ---------------------------------------------------------------------------
+
+function createMockClient(responses: Record<string, unknown>): StorefrontClient {
+  return {
+    query: vi.fn(async (_doc: unknown, _vars?: unknown) => responses),
+    mutate: vi.fn(async (_doc: unknown, _vars?: unknown) => responses),
+    use: vi.fn(),
+  };
+}
+
+const MOCK_CART = {
+  id: 'cart-1',
+  lines: [
+    { id: 'line-1', quantity: 2, merchandise: { id: 'var-1', title: 'Test Product' }, cost: { amountPerQuantity: { amount: '10.00', currencyCode: 'PLN' }, totalAmount: { amount: '20.00', currencyCode: 'PLN' } } },
+  ],
+  totalQuantity: 2,
+  cost: { totalAmount: { amount: '20.00', currencyCode: 'PLN' }, subtotalAmount: { amount: '20.00', currencyCode: 'PLN' } },
+};
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('CartClient', () => {
+  describe('get()', () => {
+    it('should query cart by ID', async () => {
+      const client = createMockClient({ cart: MOCK_CART });
+      const cartClient = new CartClient(client);
+
+      const cart = await cartClient.get('cart-1');
+
+      expect(cart).toEqual(MOCK_CART);
+      expect(client.query).toHaveBeenCalledWith(
+        expect.any(String),
+        { id: 'cart-1' },
+      );
+    });
+
+    it('should return null for non-existent cart', async () => {
+      const client = createMockClient({ cart: null });
+      const cartClient = new CartClient(client);
+
+      const cart = await cartClient.get('expired-cart');
+      expect(cart).toBeNull();
+    });
+  });
+
+  describe('create()', () => {
+    it('should create empty cart', async () => {
+      const client = createMockClient({
+        cartCreate: { cart: MOCK_CART, userErrors: [] },
+      });
+      const cartClient = new CartClient(client);
+
+      const cart = await cartClient.create();
+
+      expect(cart).toEqual(MOCK_CART);
+      expect(client.mutate).toHaveBeenCalledWith(
+        expect.any(String),
+        { input: {} },
+      );
+    });
+
+    it('should create cart with initial lines', async () => {
+      const client = createMockClient({
+        cartCreate: { cart: MOCK_CART, userErrors: [] },
+      });
+      const cartClient = new CartClient(client);
+
+      const cart = await cartClient.create({
+        lines: [{ merchandiseId: 'var-1', quantity: 2 }],
+      });
+
+      expect(cart).toEqual(MOCK_CART);
+      expect(client.mutate).toHaveBeenCalledWith(
+        expect.any(String),
+        { input: { lines: [{ merchandiseId: 'var-1', quantity: 2 }] } },
+      );
+    });
+
+    it('should throw StorefrontError on user errors', async () => {
+      const client = createMockClient({
+        cartCreate: {
+          cart: null,
+          userErrors: [{ message: 'Invalid input', field: ['lines', '0', 'merchandiseId'] }],
+        },
+      });
+      const cartClient = new CartClient(client);
+
+      try {
+        await cartClient.create({ lines: [{ merchandiseId: 'bad-id', quantity: 1 }] });
+        expect.fail('Should have thrown');
+      } catch (err) {
+        expect(err).toBeInstanceOf(StorefrontError);
+        const sfErr = err as StorefrontError;
+        expect(sfErr.code).toBe(ErrorCodes.USER_ERROR);
+        expect(sfErr.hasUserErrors).toBe(true);
+        expect(sfErr.userErrors[0].message).toBe('Invalid input');
+      }
+    });
+  });
+
+  describe('addItems()', () => {
+    it('should add lines to cart', async () => {
+      const client = createMockClient({
+        cartLinesAdd: { cart: MOCK_CART, userErrors: [] },
+      });
+      const cartClient = new CartClient(client);
+
+      const cart = await cartClient.addItems('cart-1', [
+        { merchandiseId: 'var-1', quantity: 1 },
+      ]);
+
+      expect(cart).toEqual(MOCK_CART);
+      expect(client.mutate).toHaveBeenCalledWith(
+        expect.any(String),
+        { cartId: 'cart-1', lines: [{ merchandiseId: 'var-1', quantity: 1 }] },
+      );
+    });
+
+    it('should throw on user errors (e.g., out of stock)', async () => {
+      const client = createMockClient({
+        cartLinesAdd: {
+          cart: null,
+          userErrors: [{ message: 'Out of stock', code: 'INSUFFICIENT_INVENTORY' }],
+        },
+      });
+      const cartClient = new CartClient(client);
+
+      await expect(
+        cartClient.addItems('cart-1', [{ merchandiseId: 'var-1', quantity: 100 }]),
+      ).rejects.toThrow(StorefrontError);
+    });
+  });
+
+  describe('updateItems()', () => {
+    it('should update line quantities', async () => {
+      const updatedCart = { ...MOCK_CART, totalQuantity: 5 };
+      const client = createMockClient({
+        cartLinesUpdate: { cart: updatedCart, userErrors: [] },
+      });
+      const cartClient = new CartClient(client);
+
+      const cart = await cartClient.updateItems('cart-1', [
+        { id: 'line-1', quantity: 5 },
+      ]);
+
+      expect(cart.totalQuantity).toBe(5);
+    });
+  });
+
+  describe('removeItems()', () => {
+    it('should remove lines from cart', async () => {
+      const emptyCart = { ...MOCK_CART, lines: [], totalQuantity: 0 };
+      const client = createMockClient({
+        cartLinesRemove: { cart: emptyCart, userErrors: [] },
+      });
+      const cartClient = new CartClient(client);
+
+      const cart = await cartClient.removeItems('cart-1', ['line-1']);
+
+      expect(cart.lines).toHaveLength(0);
+      expect(cart.totalQuantity).toBe(0);
+    });
+  });
+
+  describe('updateDiscountCodes()', () => {
+    it('should apply discount codes', async () => {
+      const client = createMockClient({
+        cartDiscountCodesUpdate: { cart: MOCK_CART, userErrors: [] },
+      });
+      const cartClient = new CartClient(client);
+
+      const cart = await cartClient.updateDiscountCodes('cart-1', ['SAVE10']);
+
+      expect(cart).toEqual(MOCK_CART);
+      expect(client.mutate).toHaveBeenCalledWith(
+        expect.any(String),
+        { cartId: 'cart-1', discountCodes: ['SAVE10'] },
+      );
+    });
+  });
+
+  describe('updateNote()', () => {
+    it('should update cart note', async () => {
+      const client = createMockClient({
+        cartNoteUpdate: { cart: MOCK_CART, userErrors: [] },
+      });
+      const cartClient = new CartClient(client);
+
+      const cart = await cartClient.updateNote('cart-1', 'Gift wrap please');
+
+      expect(cart).toEqual(MOCK_CART);
+      expect(client.mutate).toHaveBeenCalledWith(
+        expect.any(String),
+        { cartId: 'cart-1', note: 'Gift wrap please' },
+      );
+    });
+  });
+
+  describe('updateBuyerIdentity()', () => {
+    it('should update buyer identity', async () => {
+      const client = createMockClient({
+        cartBuyerIdentityUpdate: { cart: MOCK_CART, userErrors: [] },
+      });
+      const cartClient = new CartClient(client);
+
+      const cart = await cartClient.updateBuyerIdentity('cart-1', {
+        email: 'test@example.com',
+      });
+
+      expect(cart).toEqual(MOCK_CART);
+      expect(client.mutate).toHaveBeenCalledWith(
+        expect.any(String),
+        { cartId: 'cart-1', buyerIdentity: { email: 'test@example.com' } },
+      );
+    });
+  });
+});

package/src/__tests__/unit/create-client.test.ts

@@ -0,0 +1,356 @@
+/**
+ * Unit tests for createStorefrontClient — transport factory.
+ *
+ * Tests: query/mutate, middleware pipeline, request deduplication,
+ * lazy pipeline compilation, use() API, TypedDocumentString support.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { createStorefrontClient } from '../../core/client/create-client';
+import { TypedDocumentString } from '../../core/client/types';
+import { createSpyFetch, createMockFetch } from './test-helpers';
+
+const PRODUCT_QUERY = 'query Product($handle: String!) { product(handle: $handle) { id title } }';
+const CART_CREATE = 'mutation CartCreate($input: CartInput!) { cartCreate(input: $input) { cart { id } userErrors { message } } }';
+
+describe('createStorefrontClient', () => {
+  it('should create a client with query and mutate methods', () => {
+    const client = createStorefrontClient({
+      apiUrl: 'https://api.test.com',
+      shopSlug: 'test-shop',
+      fetch: createMockFetch({}),
+    });
+
+    expect(client.query).toBeDefined();
+    expect(client.mutate).toBeDefined();
+    expect(client.use).toBeDefined();
+  });
+
+  describe('query()', () => {
+    it('should send POST request with correct body', async () => {
+      const { fetch, calls } = createSpyFetch({ product: { id: '1', title: 'Test' } });
+
+      const client = createStorefrontClient({
+        apiUrl: 'https://api.test.com',
+        shopSlug: 'my-shop',
+        fetch,
+      });
+
+      await client.query(PRODUCT_QUERY, { handle: 'test-product' });
+
+      expect(calls).toHaveLength(1);
+      expect(calls[0].url).toBe('https://api.test.com/storefront/graphql');
+
+      const body = JSON.parse(calls[0].init.body as string);
+      expect(body.query).toBe(PRODUCT_QUERY);
+      expect(body.variables).toEqual({ handle: 'test-product' });
+      expect(body.operationName).toBe('Product');
+    });
+
+    it('should include X-Shop-Slug header', async () => {
+      const { fetch, calls } = createSpyFetch({ product: null });
+
+      const client = createStorefrontClient({
+        apiUrl: 'https://api.test.com',
+        shopSlug: 'my-shop',
+        fetch,
+      });
+
+      await client.query(PRODUCT_QUERY, { handle: 'test' });
+
+      const headers = calls[0].init.headers as Record<string, string>;
+      expect(headers['X-Shop-Slug']).toBe('my-shop');
+    });
+
+    it('should include X-Operation-Name header for named queries', async () => {
+      const { fetch, calls } = createSpyFetch({ product: null });
+
+      const client = createStorefrontClient({
+        apiUrl: 'https://api.test.com',
+        shopSlug: 'test',
+        fetch,
+      });
+
+      await client.query(PRODUCT_QUERY, { handle: 'test' });
+
+      const headers = calls[0].init.headers as Record<string, string>;
+      expect(headers['X-Operation-Name']).toBe('Product');
+    });
+
+    it('should NOT include X-Operation-Name for anonymous queries', async () => {
+      const { fetch, calls } = createSpyFetch({ something: true });
+
+      const client = createStorefrontClient({
+        apiUrl: 'https://api.test.com',
+        shopSlug: 'test',
+        fetch,
+      });
+
+      await client.query('{ shop { id } }');
+
+      const headers = calls[0].init.headers as Record<string, string>;
+      expect(headers['X-Operation-Name']).toBeUndefined();
+    });
+
+    it('should return data from response', async () => {
+      const mockData = { product: { id: '1', title: 'Cool Shirt' } };
+      const client = createStorefrontClient({
+        apiUrl: 'https://api.test.com',
+        shopSlug: 'test',
+        fetch: createMockFetch(mockData),
+      });
+
+      const result = await client.query(PRODUCT_QUERY, { handle: 'cool-shirt' });
+      expect(result).toEqual(mockData);
+    });
+
+    it('should strip trailing slash from apiUrl', async () => {
+      const { fetch, calls } = createSpyFetch({});
+
+      const client = createStorefrontClient({
+        apiUrl: 'https://api.test.com/',
+        shopSlug: 'test',
+        fetch,
+      });
+
+      await client.query('{ shop { id } }');
+      expect(calls[0].url).toBe('https://api.test.com/storefront/graphql');
+    });
+
+    it('should merge defaultHeaders into request', async () => {
+      const { fetch, calls } = createSpyFetch({});
+
+      const client = createStorefrontClient({
+        apiUrl: 'https://api.test.com',
+        shopSlug: 'test',
+        defaultHeaders: { 'X-Custom': 'value' },
+        fetch,
+      });
+
+      await client.query('{ shop { id } }');
+
+      const headers = calls[0].init.headers as Record<string, string>;
+      expect(headers['X-Custom']).toBe('value');
+    });
+
+    it('should support TypedDocumentString', async () => {
+      const typedDoc = new TypedDocumentString<{ product: { id: string } }, { handle: string }>(PRODUCT_QUERY);
+
+      const { fetch, calls } = createSpyFetch({ product: { id: '1' } });
+
+      const client = createStorefrontClient({
+        apiUrl: 'https://api.test.com',
+        shopSlug: 'test',
+        fetch,
+      });
+
+      const result = await client.query(typedDoc, { handle: 'test' });
+
+      const body = JSON.parse(calls[0].init.body as string);
+      expect(body.query).toBe(PRODUCT_QUERY);
+      expect(result).toEqual({ product: { id: '1' } });
+    });
+
+    it('should not include empty variables in request body', async () => {
+      const { fetch, calls } = createSpyFetch({});
+
+      const client = createStorefrontClient({
+        apiUrl: 'https://api.test.com',
+        shopSlug: 'test',
+        fetch,
+      });
+
+      await client.query('{ shop { id } }');
+
+      const body = JSON.parse(calls[0].init.body as string);
+      expect(body.variables).toBeUndefined();
+    });
+  });
+
+  describe('mutate()', () => {
+    it('should send mutation correctly', async () => {
+      const mockData = { cartCreate: { cart: { id: 'cart-1' }, userErrors: [] } };
+      const { fetch, calls } = createSpyFetch(mockData);
+
+      const client = createStorefrontClient({
+        apiUrl: 'https://api.test.com',
+        shopSlug: 'test',
+        fetch,
+      });
+
+      const result = await client.mutate(CART_CREATE, { input: {} });
+
+      expect(result).toEqual(mockData);
+      const body = JSON.parse(calls[0].init.body as string);
+      expect(body.operationName).toBe('CartCreate');
+    });
+  });
+
+  describe('request deduplication', () => {
+    it('should deduplicate identical concurrent queries', async () => {
+      const { fetch, calls } = createSpyFetch({ product: { id: '1' } });
+
+      const client = createStorefrontClient({
+        apiUrl: 'https://api.test.com',
+        shopSlug: 'test',
+        fetch,
+      });
+
+      // Fire 3 identical queries concurrently
+      const [r1, r2, r3] = await Promise.all([
+        client.query(PRODUCT_QUERY, { handle: 'test' }),
+        client.query(PRODUCT_QUERY, { handle: 'test' }),
+        client.query(PRODUCT_QUERY, { handle: 'test' }),
+      ]);
+
+      // Only 1 actual fetch
+      expect(calls).toHaveLength(1);
+      // All return same data
+      expect(r1).toEqual(r2);
+      expect(r2).toEqual(r3);
+    });
+
+    it('should NOT deduplicate queries with different variables', async () => {
+      const { fetch, calls } = createSpyFetch({ product: { id: '1' } });
+
+      const client = createStorefrontClient({
+        apiUrl: 'https://api.test.com',
+        shopSlug: 'test',
+        fetch,
+      });
+
+      await Promise.all([
+        client.query(PRODUCT_QUERY, { handle: 'product-a' }),
+        client.query(PRODUCT_QUERY, { handle: 'product-b' }),
+      ]);
+
+      expect(calls).toHaveLength(2);
+    });
+
+    it('should NOT deduplicate mutations', async () => {
+      const { fetch, calls } = createSpyFetch({ cartCreate: { cart: { id: '1' }, userErrors: [] } });
+
+      const client = createStorefrontClient({
+        apiUrl: 'https://api.test.com',
+        shopSlug: 'test',
+        fetch,
+      });
+
+      await Promise.all([
+        client.mutate(CART_CREATE, { input: {} }),
+        client.mutate(CART_CREATE, { input: {} }),
+      ]);
+
+      expect(calls).toHaveLength(2);
+    });
+  });
+
+  describe('use() — imperative middleware', () => {
+    it('should add middleware that runs on subsequent requests', async () => {
+      const { fetch, calls } = createSpyFetch({ data: true });
+
+      const client = createStorefrontClient({
+        apiUrl: 'https://api.test.com',
+        shopSlug: 'test',
+        fetch,
+      });
+
+      client.use((req, next) => {
+        req.headers['X-Added'] = 'by-use';
+        return next(req);
+      });
+
+      await client.query('{ shop { id } }');
+
+      const headers = calls[0].init.headers as Record<string, string>;
+      expect(headers['X-Added']).toBe('by-use');
+    });
+
+    it('should invalidate compiled pipeline on use()', async () => {
+      let callOrder: string[] = [];
+
+      const client = createStorefrontClient({
+        apiUrl: 'https://api.test.com',
+        shopSlug: 'test',
+        fetch: createMockFetch({}),
+        middleware: [
+          async (req, next) => { callOrder.push('A'); return next(req); },
+        ],
+      });
+
+      await client.query('{ shop { id } }');
+      expect(callOrder).toEqual(['A']);
+
+      callOrder = [];
+      client.use(async (req, next) => { callOrder.push('B'); return next(req); });
+
+      await client.query('{ shop { id } }');
+      expect(callOrder).toEqual(['A', 'B']);
+    });
+  });
+
+  describe('middleware pipeline', () => {
+    it('should execute middleware in registration order', async () => {
+      const order: string[] = [];
+
+      const client = createStorefrontClient({
+        apiUrl: 'https://api.test.com',
+        shopSlug: 'test',
+        fetch: createMockFetch({}),
+        middleware: [
+          async (req, next) => { order.push('first'); return next(req); },
+          async (req, next) => { order.push('second'); return next(req); },
+          async (req, next) => { order.push('third'); return next(req); },
+        ],
+      });
+
+      await client.query('{ shop { id } }');
+      expect(order).toEqual(['first', 'second', 'third']);
+    });
+
+    it('should allow middleware to modify request headers', async () => {
+      const { fetch, calls } = createSpyFetch({});
+
+      const client = createStorefrontClient({
+        apiUrl: 'https://api.test.com',
+        shopSlug: 'test',
+        fetch,
+        middleware: [
+          async (req, next) => {
+            req.headers['Authorization'] = 'Bearer test-token';
+            return next(req);
+          },
+        ],
+      });
+
+      await client.query('{ shop { id } }');
+
+      const headers = calls[0].init.headers as Record<string, string>;
+      expect(headers['Authorization']).toBe('Bearer test-token');
+    });
+
+    it('should allow middleware to short-circuit', async () => {
+      const { fetch, calls } = createSpyFetch({});
+
+      const client = createStorefrontClient({
+        apiUrl: 'https://api.test.com',
+        shopSlug: 'test',
+        fetch,
+        middleware: [
+          async (_req, _next) => {
+            // Short-circuit — don't call next()
+            return {
+              data: { cached: true },
+              status: 200,
+              headers: new Headers(),
+            };
+          },
+        ],
+      });
+
+      const result = await client.query('{ shop { id } }');
+      expect(result).toEqual({ cached: true });
+      expect(calls).toHaveLength(0); // No fetch call
+    });
+  });
+});