@doswiftly/storefront-sdk 4.0.0

package/src/__tests__/contract/storefront-api.contract.test.ts

@@ -0,0 +1,450 @@
+/**
+ * Contract Tests for Storefront GraphQL API (v4 SDK).
+ *
+ * These tests validate that the backend API responses match expected
+ * shapes when accessed through the v4 SDK (createStorefrontClient,
+ * CartClient, AuthClient).
+ *
+ * REQUIRES: Running backend at STOREFRONT_API_URL.
+ *
+ * Run: pnpm run test:contract
+ */
+
+import { describe, it, expect, beforeAll } from 'vitest';
+import { createStorefrontClient } from '../../core/client/create-client';
+import { errorMiddleware } from '../../core/middleware/errors';
+import { CartClient } from '../../core/cart/cart-client';
+import { AuthClient } from '../../core/auth/auth-client';
+import { StorefrontError, ErrorCodes } from '../../core/errors';
+import type { StorefrontClient } from '../../core/client/types';
+
+// ============================================
+// Configuration
+// ============================================
+
+const API_URL = process.env.STOREFRONT_API_URL || 'http://localhost:8000';
+const SHOP_SLUG = process.env.TEST_SHOP_SLUG || 'test-shop';
+
+const PRODUCT_QUERY = `
+  query Product($handle: String!) {
+    product(handle: $handle) {
+      id handle title description
+      variants { id title sku quantityAvailable }
+      priceRange { minVariantPrice { amount currencyCode } }
+    }
+  }
+`;
+
+const PRODUCTS_QUERY = `
+  query Products($first: Int!) {
+    products(first: $first) {
+      edges { node { id handle title } }
+      pageInfo { hasNextPage endCursor }
+      totalCount
+    }
+  }
+`;
+
+const SHOP_QUERY = `
+  query Shop {
+    shop { id name currencyCode supportedCurrencies }
+  }
+`;
+
+const CATEGORIES_QUERY = `
+  query Categories {
+    categories { roots { id slug name } totalCount }
+  }
+`;
+
+const COLLECTIONS_QUERY = `
+  query Collections($first: Int!) {
+    collections(first: $first) {
+      edges { node { id handle title } }
+      pageInfo { hasNextPage endCursor }
+    }
+  }
+`;
+
+// ============================================
+// Setup
+// ============================================
+
+describe('Storefront API Contract Tests (v4 SDK)', () => {
+  let client: StorefrontClient;
+  let cartClient: CartClient;
+  let authClient: AuthClient;
+  let variantId: string | undefined;
+
+  beforeAll(async () => {
+    client = createStorefrontClient({
+      apiUrl: API_URL,
+      shopSlug: SHOP_SLUG,
+      middleware: [errorMiddleware()],
+    });
+
+    cartClient = new CartClient(client);
+    authClient = new AuthClient(client);
+
+    // Get a variant ID for cart tests
+    try {
+      const data = await client.query<{
+        products: { edges: Array<{ node: { id: string; handle: string } }> };
+      }>(PRODUCTS_QUERY, { first: 1 });
+
+      if (data.products.edges.length > 0) {
+        const handle = data.products.edges[0].node.handle;
+        const productData = await client.query<{
+          product: { variants: Array<{ id: string; quantityAvailable: number }> } | null;
+        }>(PRODUCT_QUERY, { handle });
+
+        const variant = productData.product?.variants?.[0];
+        if (variant && variant.quantityAvailable > 0) {
+          variantId = variant.id;
+        }
+      }
+    } catch (e) {
+      console.warn('Could not fetch variant for cart tests:', e);
+    }
+  });
+
+  // ============================================
+  // Query Contract Tests
+  // ============================================
+
+  describe('Queries', () => {
+    it('Shop — should return shop info with currency', async () => {
+      const data = await client.query<{
+        shop: { id: string; name: string; currencyCode: string; supportedCurrencies: string[] };
+      }>(SHOP_QUERY);
+
+      expect(data.shop).toBeDefined();
+      expect(data.shop.id).toBeDefined();
+      expect(data.shop.name).toBeDefined();
+      expect(data.shop.currencyCode).toBeDefined();
+      expect(Array.isArray(data.shop.supportedCurrencies)).toBe(true);
+    });
+
+    it('Product — should return product by handle', async () => {
+      const data = await client.query<{
+        product: { id: string; handle: string; title: string } | null;
+      }>(PRODUCT_QUERY, { handle: 'test-product' });
+
+      // Product may or may not exist — just validate shape
+      if (data.product) {
+        expect(data.product.id).toBeDefined();
+        expect(data.product.handle).toBeDefined();
+        expect(data.product.title).toBeDefined();
+      }
+    });
+
+    it('Product — should return null for non-existent handle', async () => {
+      const data = await client.query<{
+        product: { id: string } | null;
+      }>(PRODUCT_QUERY, { handle: 'definitely-non-existent-product-xyz-12345' });
+
+      expect(data.product).toBeNull();
+    });
+
+    it('Products — should return paginated list', async () => {
+      const data = await client.query<{
+        products: {
+          edges: Array<{ node: { id: string } }>;
+          pageInfo: { hasNextPage: boolean; endCursor: string | null };
+          totalCount: number;
+        };
+      }>(PRODUCTS_QUERY, { first: 5 });
+
+      expect(data.products).toBeDefined();
+      expect(Array.isArray(data.products.edges)).toBe(true);
+      expect(data.products.pageInfo).toBeDefined();
+      expect(typeof data.products.pageInfo.hasNextPage).toBe('boolean');
+      expect(typeof data.products.totalCount).toBe('number');
+    });
+
+    it('Products — should support cursor pagination', async () => {
+      const page1 = await client.query<{
+        products: {
+          edges: Array<{ node: { id: string } }>;
+          pageInfo: { hasNextPage: boolean; endCursor: string | null };
+        };
+      }>(PRODUCTS_QUERY, { first: 2 });
+
+      if (page1.products.pageInfo.hasNextPage && page1.products.pageInfo.endCursor) {
+        const PRODUCTS_AFTER = `
+          query ProductsAfter($first: Int!, $after: String) {
+            products(first: $first, after: $after) {
+              edges { node { id } }
+              pageInfo { hasNextPage endCursor }
+            }
+          }
+        `;
+
+        const page2 = await client.query<{
+          products: { edges: Array<{ node: { id: string } }> };
+        }>(PRODUCTS_AFTER, { first: 2, after: page1.products.pageInfo.endCursor });
+
+        expect(page2.products.edges).toBeDefined();
+      }
+    });
+
+    it('Categories — should return category tree', async () => {
+      const data = await client.query<{
+        categories: { roots: Array<{ id: string; slug: string; name: string }>; totalCount: number };
+      }>(CATEGORIES_QUERY);
+
+      expect(data.categories).toBeDefined();
+      expect(Array.isArray(data.categories.roots)).toBe(true);
+      expect(typeof data.categories.totalCount).toBe('number');
+    });
+
+    it('Collections — should return paginated list', async () => {
+      const data = await client.query<{
+        collections: {
+          edges: Array<{ node: { id: string } }>;
+          pageInfo: { hasNextPage: boolean };
+        };
+      }>(COLLECTIONS_QUERY, { first: 5 });
+
+      expect(data.collections).toBeDefined();
+      expect(Array.isArray(data.collections.edges)).toBe(true);
+    });
+  });
+
+  // ============================================
+  // CartClient Contract Tests
+  // ============================================
+
+  describe('CartClient', () => {
+    it('should create empty cart', async () => {
+      const cart = await cartClient.create();
+
+      expect(cart.id).toBeDefined();
+      expect(cart.totalQuantity).toBe(0);
+      expect(cart.lines).toHaveLength(0);
+    });
+
+    it('should get existing cart by ID', async () => {
+      const created = await cartClient.create();
+      const fetched = await cartClient.get(created.id);
+
+      expect(fetched).not.toBeNull();
+      expect(fetched!.id).toBe(created.id);
+    });
+
+    it('should return null for non-existent cart', async () => {
+      const cart = await cartClient.get('non-existent-cart-id');
+      expect(cart).toBeNull();
+    });
+
+    it('should complete full cart lifecycle', async () => {
+      if (!variantId) {
+        console.warn('Skipping cart lifecycle — no variant with stock');
+        return;
+      }
+
+      // 1. Create
+      const cart = await cartClient.create();
+      expect(cart.id).toBeDefined();
+
+      // 2. Add item
+      const afterAdd = await cartClient.addItems(cart.id, [
+        { merchandiseId: variantId, quantity: 1 },
+      ]);
+      expect(afterAdd.lines).toHaveLength(1);
+      expect(afterAdd.totalQuantity).toBe(1);
+
+      const lineId = afterAdd.lines[0].id;
+
+      // 3. Update quantity
+      const afterUpdate = await cartClient.updateItems(cart.id, [
+        { id: lineId, quantity: 2 },
+      ]);
+      expect(afterUpdate.lines[0].quantity).toBe(2);
+
+      // 4. Remove
+      const afterRemove = await cartClient.removeItems(cart.id, [lineId]);
+      expect(afterRemove.lines).toHaveLength(0);
+      expect(afterRemove.totalQuantity).toBe(0);
+    });
+
+    it('should update cart note', async () => {
+      const cart = await cartClient.create();
+      const updated = await cartClient.updateNote(cart.id, 'Gift wrap please');
+
+      expect(updated.note).toBe('Gift wrap please');
+    });
+
+    it('should handle discount codes', async () => {
+      const cart = await cartClient.create();
+
+      // Apply (may fail if code doesn't exist — that's OK, we test the API shape)
+      try {
+        const updated = await cartClient.updateDiscountCodes(cart.id, ['TESTCODE10']);
+        expect(updated).toBeDefined();
+      } catch (err) {
+        // User errors are expected if discount code is invalid
+        if (err instanceof StorefrontError) {
+          expect(err.code).toBe(ErrorCodes.USER_ERROR);
+        } else {
+          throw err;
+        }
+      }
+    });
+  });
+
+  // ============================================
+  // AuthClient Contract Tests
+  // ============================================
+
+  describe('AuthClient', () => {
+    const testEmail = `contract-v4-${Date.now()}@example.com`;
+    const testPassword = 'ContractTest123!';
+
+    it('should register new customer', async () => {
+      const result = await authClient.register({
+        email: testEmail,
+        password: testPassword,
+        firstName: 'Contract',
+        lastName: 'Test',
+      });
+
+      expect(result.accessToken).toBeDefined();
+      expect(result.expiresAt).toBeDefined();
+    });
+
+    it('should throw on duplicate registration', async () => {
+      try {
+        await authClient.register({
+          email: testEmail,
+          password: testPassword,
+        });
+        expect.fail('Should have thrown on duplicate email');
+      } catch (err) {
+        expect(err).toBeInstanceOf(StorefrontError);
+        expect((err as StorefrontError).code).toBe(ErrorCodes.USER_ERROR);
+      }
+    });
+
+    it('should login with valid credentials', async () => {
+      const result = await authClient.login(testEmail, testPassword);
+
+      expect(result.accessToken).toBeDefined();
+      expect(result.expiresAt).toBeDefined();
+    });
+
+    it('should throw on invalid credentials', async () => {
+      try {
+        await authClient.login('nonexistent@example.com', 'WrongPassword123!');
+        expect.fail('Should have thrown');
+      } catch (err) {
+        expect(err).toBeInstanceOf(StorefrontError);
+        expect((err as StorefrontError).code).toBe(ErrorCodes.USER_ERROR);
+      }
+    });
+
+    it('should fetch customer profile', async () => {
+      const { accessToken } = await authClient.login(testEmail, testPassword);
+
+      // Create authenticated client
+      const authSfClient = createStorefrontClient({
+        apiUrl: API_URL,
+        shopSlug: SHOP_SLUG,
+        middleware: [errorMiddleware()],
+        defaultHeaders: { 'X-Customer-Token': accessToken },
+      });
+      const authCustomerClient = new AuthClient(authSfClient);
+
+      const customer = await authCustomerClient.getCustomer(accessToken);
+
+      expect(customer).not.toBeNull();
+      expect(customer!.email).toBe(testEmail);
+    });
+
+    it('should renew token', async () => {
+      const { accessToken } = await authClient.login(testEmail, testPassword);
+
+      const renewed = await authClient.renewToken(accessToken);
+
+      expect(renewed.accessToken).toBeDefined();
+      expect(renewed.expiresAt).toBeDefined();
+    });
+
+    it('should logout without error', async () => {
+      const { accessToken } = await authClient.login(testEmail, testPassword);
+
+      // Should not throw
+      await authClient.logout(accessToken);
+    });
+
+    it('should handle logout with expired token gracefully', async () => {
+      // Should not throw
+      await authClient.logout('definitely-expired-token');
+    });
+  });
+
+  // ============================================
+  // Error Handling Contract Tests
+  // ============================================
+
+  describe('Error Handling', () => {
+    it('should throw StorefrontError for invalid GraphQL', async () => {
+      try {
+        await client.query('{ invalidField { nope } }');
+        expect.fail('Should have thrown');
+      } catch (err) {
+        expect(err).toBeInstanceOf(StorefrontError);
+      }
+    });
+
+    it('should handle product not found as null, not error', async () => {
+      const data = await client.query<{ product: unknown | null }>(
+        PRODUCT_QUERY,
+        { handle: 'absolutely-nonexistent-product-12345' },
+      );
+      expect(data.product).toBeNull();
+    });
+  });
+
+  // ============================================
+  // Middleware Integration Contract Tests
+  // ============================================
+
+  describe('Middleware Integration', () => {
+    it('should pass custom headers through middleware', async () => {
+      const clientWithCurrency = createStorefrontClient({
+        apiUrl: API_URL,
+        shopSlug: SHOP_SLUG,
+        middleware: [
+          (req, next) => {
+            req.headers['X-Preferred-Currency'] = 'EUR';
+            return next(req);
+          },
+          errorMiddleware(),
+        ],
+      });
+
+      // Should not throw — backend accepts the header
+      const data = await clientWithCurrency.query<{
+        shop: { currencyCode: string };
+      }>(SHOP_QUERY);
+
+      expect(data.shop).toBeDefined();
+    });
+
+    it('should support imperative use() API', async () => {
+      const freshClient = createStorefrontClient({
+        apiUrl: API_URL,
+        shopSlug: SHOP_SLUG,
+      });
+
+      freshClient.use(errorMiddleware());
+
+      const data = await freshClient.query<{
+        shop: { id: string };
+      }>(SHOP_QUERY);
+
+      expect(data.shop.id).toBeDefined();
+    });
+  });
+});

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

@@ -0,0 +1,210 @@
+/**
+ * Unit tests for AuthClient — plain async auth API.
+ *
+ * Tests login, logout, renewToken, register, getCustomer.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { AuthClient } from '../../core/auth/auth-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 () => responses),
+    mutate: vi.fn(async () => responses),
+    use: vi.fn(),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('AuthClient', () => {
+  describe('login()', () => {
+    it('should return accessToken and expiresAt on success', async () => {
+      const client = createMockClient({
+        customerAccessTokenCreate: {
+          customerAccessToken: {
+            accessToken: 'token-123',
+            expiresAt: '2026-04-01T00:00:00Z',
+          },
+          userErrors: [],
+        },
+      });
+      const authClient = new AuthClient(client);
+
+      const result = await authClient.login('user@example.com', 'password');
+
+      expect(result.accessToken).toBe('token-123');
+      expect(result.expiresAt).toBe('2026-04-01T00:00:00Z');
+      expect(client.mutate).toHaveBeenCalledWith(
+        expect.any(String),
+        { input: { email: 'user@example.com', password: 'password' } },
+      );
+    });
+
+    it('should throw StorefrontError on invalid credentials', async () => {
+      const client = createMockClient({
+        customerAccessTokenCreate: {
+          customerAccessToken: null,
+          userErrors: [{ message: 'Invalid email or password' }],
+        },
+      });
+      const authClient = new AuthClient(client);
+
+      try {
+        await authClient.login('bad@example.com', 'wrong');
+        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.message).toBe('Invalid email or password');
+        expect(sfErr.hasUserErrors).toBe(true);
+      }
+    });
+  });
+
+  describe('logout()', () => {
+    it('should call mutate with token', async () => {
+      const client = createMockClient({
+        customerAccessTokenDelete: {
+          deletedAccessToken: 'token-123',
+          userErrors: [],
+        },
+      });
+      const authClient = new AuthClient(client);
+
+      await authClient.logout('token-123');
+
+      expect(client.mutate).toHaveBeenCalledWith(
+        expect.any(String),
+        { customerAccessToken: 'token-123' },
+      );
+    });
+
+    it('should NOT throw on failure (token may be expired)', async () => {
+      const client: StorefrontClient = {
+        query: vi.fn(),
+        mutate: vi.fn(async () => { throw new Error('Server error'); }),
+        use: vi.fn(),
+      };
+      const authClient = new AuthClient(client);
+
+      // Should not throw
+      await authClient.logout('expired-token');
+    });
+  });
+
+  describe('renewToken()', () => {
+    it('should return renewed token', async () => {
+      const client = createMockClient({
+        customerAccessTokenRenew: {
+          customerAccessToken: {
+            accessToken: 'new-token-456',
+            expiresAt: '2026-05-01T00:00:00Z',
+          },
+          userErrors: [],
+        },
+      });
+      const authClient = new AuthClient(client);
+
+      const result = await authClient.renewToken('old-token');
+
+      expect(result.accessToken).toBe('new-token-456');
+      expect(result.expiresAt).toBe('2026-05-01T00:00:00Z');
+    });
+
+    it('should throw on user errors', async () => {
+      const client = createMockClient({
+        customerAccessTokenRenew: {
+          customerAccessToken: null,
+          userErrors: [{ message: 'Token expired' }],
+        },
+      });
+      const authClient = new AuthClient(client);
+
+      await expect(authClient.renewToken('expired')).rejects.toThrow(StorefrontError);
+    });
+  });
+
+  describe('register()', () => {
+    it('should return token and customer on success', async () => {
+      const client = createMockClient({
+        customerCreate: {
+          customer: { id: 'cust-1', email: 'new@example.com', firstName: 'John', lastName: 'Doe' },
+          customerAccessToken: {
+            accessToken: 'reg-token',
+            expiresAt: '2026-04-01T00:00:00Z',
+          },
+          userErrors: [],
+        },
+      });
+      const authClient = new AuthClient(client);
+
+      const result = await authClient.register({
+        email: 'new@example.com',
+        password: 'SecurePass123!',
+        firstName: 'John',
+        lastName: 'Doe',
+      });
+
+      expect(result.accessToken).toBe('reg-token');
+      expect(result.customer?.email).toBe('new@example.com');
+    });
+
+    it('should throw on duplicate email', async () => {
+      const client = createMockClient({
+        customerCreate: {
+          customer: null,
+          customerAccessToken: null,
+          userErrors: [{ message: 'Email already taken', field: ['email'] }],
+        },
+      });
+      const authClient = new AuthClient(client);
+
+      try {
+        await authClient.register({ email: 'existing@example.com', password: 'Pass123!' });
+        expect.fail('Should have thrown');
+      } catch (err) {
+        expect(err).toBeInstanceOf(StorefrontError);
+        expect((err as StorefrontError).userErrors[0].field).toEqual(['email']);
+      }
+    });
+  });
+
+  describe('getCustomer()', () => {
+    it('should return customer data', async () => {
+      const mockCustomer = {
+        id: 'cust-1',
+        email: 'user@example.com',
+        firstName: 'Jane',
+        lastName: 'Smith',
+      };
+      const client = createMockClient({ customer: mockCustomer });
+      const authClient = new AuthClient(client);
+
+      const customer = await authClient.getCustomer('token-123');
+
+      expect(customer).toEqual(mockCustomer);
+      expect(client.query).toHaveBeenCalledWith(
+        expect.any(String),
+        { customerAccessToken: 'token-123' },
+      );
+    });
+
+    it('should return null for invalid token', async () => {
+      const client = createMockClient({ customer: null });
+      const authClient = new AuthClient(client);
+
+      const customer = await authClient.getCustomer('invalid-token');
+      expect(customer).toBeNull();
+    });
+  });
+});