chore: add unit tests for client, setup requirements, webhooks

Signed-off-by: Frederik Bußmann <frederik@bussmann.io>

Author: freb97

test/unit/client-api-url.test.ts

@@ -0,0 +1,136 @@
+import { describe, expect, it } from 'vitest'
+
+import { configSchema } from '../../src/schemas'
+import { createAdminConfig } from '../../src/runtime/utils/clients/admin'
+import { createCustomerAccountConfig } from '../../src/runtime/utils/clients/customer-account'
+import { createStorefrontConfig } from '../../src/runtime/utils/clients/storefront'
+import { createClient } from '../../src/runtime/utils/clients/create'
+import {
+  PROXY_API_VERSION_HEADER,
+  createTransport,
+  isVersionedApiUrl,
+  withApiVersion,
+} from '../../src/runtime/utils/clients/transport'
+
+const storefront = { name: 'shop', clients: { storefront: { apiVersion: '2026-04', publicAccessToken: 'tok', retries: 0 } } }
+
+const proxiedStorefront = configSchema.parse({ name: 'shop', clients: { storefront: { apiVersion: '2026-04', publicAccessToken: 'tok' } } })
+const admin = { name: 'shop', clients: { admin: { apiVersion: '2026-04', accessToken: 'shpat_x', retries: 0 } } }
+const mock = { name: 'shop', clients: { storefront: { apiVersion: '2026-04', mock: true, retries: 0 } } }
+
+const customerAccount = {
+  name: 'shop',
+  clients: {
+    customerAccount: {
+      apiVersion: '2026-04',
+      clientId: 'cid',
+      apiUrl: 'https://shopify.com/1234/account/customer/api/2026-04/graphql',
+      retries: 0,
+    },
+  },
+}
+
+describe('withApiVersion', () => {
+  it('replaces the version segment of every Shopify API url shape', () => {
+    expect(withApiVersion('https://shop.myshopify.com/api/2026-04/graphql.json', '2026-01'))
+      .toBe('https://shop.myshopify.com/api/2026-01/graphql.json')
+
+    expect(withApiVersion('https://shop.myshopify.com/admin/api/2026-04/graphql.json', '2026-01'))
+      .toBe('https://shop.myshopify.com/admin/api/2026-01/graphql.json')
+
+    expect(withApiVersion('https://shopify.com/1234/account/customer/api/2026-04/graphql', '2026-01'))
+      .toBe('https://shopify.com/1234/account/customer/api/2026-01/graphql')
+
+    expect(withApiVersion('https://mock.shop/api/2026-04/graphql.json', '2026-01'))
+      .toBe('https://mock.shop/api/2026-01/graphql.json')
+  })
+
+  it('leaves a proxy url untouched', () => {
+    expect(withApiVersion('http://localhost:3000/_proxy/storefront', '2026-01'))
+      .toBe('http://localhost:3000/_proxy/storefront')
+
+    expect(isVersionedApiUrl('http://localhost:3000/_proxy/storefront')).toBe(false)
+    expect(isVersionedApiUrl('https://shop.myshopify.com/admin/api/2026-04/graphql.json')).toBe(true)
+  })
+})
+
+describe('per-request apiVersion override', () => {
+  it('keeps the storefront endpoint', () => {
+    const transport = createTransport(createStorefrontConfig(storefront as never))
+
+    expect(transport.getApiUrl()).toBe('https://shop.myshopify.com/api/2026-04/graphql.json')
+    expect(transport.getApiUrl('2026-01')).toBe('https://shop.myshopify.com/api/2026-01/graphql.json')
+  })
+
+  it('keeps the admin prefix', () => {
+    const transport = createTransport(createAdminConfig(admin as never))
+
+    expect(transport.getApiUrl('2026-01')).toBe('https://shop.myshopify.com/admin/api/2026-01/graphql.json')
+  })
+
+  it('keeps the customer account host', () => {
+    const transport = createTransport(createCustomerAccountConfig(customerAccount as never))
+
+    expect(transport.getApiUrl('2026-01')).toBe('https://shopify.com/1234/account/customer/api/2026-01/graphql')
+  })
+
+  it('keeps the mock storefront host', () => {
+    const transport = createTransport(createStorefrontConfig(mock as never))
+
+    expect(transport.getApiUrl('2026-01')).toBe('https://mock.shop/api/2026-01/graphql.json')
+  })
+})
+
+describe('client-level apiVersion option', () => {
+  const definition = { kind: 'storefront', createConfig: createStorefrontConfig, cache: true } as never
+
+  it('rewrites the request url, not just the reported version', () => {
+    const client = createClient(definition, storefront as never, { apiVersion: '2026-01' } as never)
+
+    expect(client.config.apiVersion).toBe('2026-01')
+    expect(client.config.apiUrl).toBe('https://shop.myshopify.com/api/2026-01/graphql.json')
+  })
+
+  it('asks the proxy for the version instead of bypassing it', () => {
+    const client = createClient(definition, proxiedStorefront as never, {
+      apiVersion: '2026-01',
+      origin: 'http://localhost:3000',
+    } as never)
+
+    expect(client.config.apiUrl).toBe('http://localhost:3000/_proxy/storefront')
+    expect(client.config.headers[PROXY_API_VERSION_HEADER]).toBe('2026-01')
+  })
+
+  it('does not set the proxy version header when no override is given', () => {
+    const client = createClient(definition, proxiedStorefront as never, { origin: 'http://localhost:3000' } as never)
+
+    expect(client.config.apiUrl).toBe('http://localhost:3000/_proxy/storefront')
+    expect(client.config.headers[PROXY_API_VERSION_HEADER]).toBeUndefined()
+  })
+})
+
+describe('client config resolution', () => {
+  it('sends the private token in preference to the public one', () => {
+    const config = createStorefrontConfig({
+      name: 'shop',
+      clients: { storefront: { apiVersion: '2026-04', publicAccessToken: 'public', privateAccessToken: 'private', retries: 0 } },
+    } as never)
+
+    expect(config.headers).toMatchObject({ 'Shopify-Storefront-Private-Token': 'private' })
+    expect(config.headers['X-Shopify-Storefront-Access-Token']).toBeUndefined()
+  })
+
+  it('refuses to build a storefront config without a token', () => {
+    expect(() => createStorefrontConfig({
+      name: 'shop',
+      clients: { storefront: { apiVersion: '2026-04', retries: 0 } },
+    } as never)).toThrow(/missing access token/)
+  })
+
+  it('refuses to build a client config without a shop name', () => {
+    expect(() => createStorefrontConfig({
+      name: '',
+      clients: { storefront: { apiVersion: '2026-04', publicAccessToken: 'tok', retries: 0 } },
+    } as never)).toThrow(/missing shop name/)
+  })
+})

test/unit/client-cache.test.ts

@@ -0,0 +1,126 @@
+import type { Storage, StorageValue } from 'unstorage'
+
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import useCache from '../../src/runtime/utils/clients/cache'
+
+const options = {
+  short: { maxAge: 1, staleMaxAge: 9, swr: true },
+  long: { maxAge: 3600, staleMaxAge: 82800, swr: true },
+}
+
+let store: Map<string, unknown>
+let ttls: Map<string, unknown>
+
+function createStorage() {
+  return {
+    hasItem: async (key: string) => store.has(key),
+    getItem: async (key: string) => store.get(key) ?? null,
+    setItem: async (key: string, value: unknown, opts?: unknown) => {
+      store.set(key, value)
+      ttls.set(key, opts)
+    },
+  } as unknown as Storage<StorageValue>
+}
+
+function createRequest(data: unknown = { product: { id: '1' } }) {
+  return vi.fn(async (..._args: unknown[]) => ({ data, headers: new Headers() }))
+}
+
+function requestOptions(request: ReturnType<typeof createRequest>) {
+  return request.mock.calls[0]?.[1]
+}
+
+beforeEach(() => {
+  store = new Map()
+  ttls = new Map()
+})
+
+describe('client cache', () => {
+  it('serves a repeated request from the cache', async () => {
+    const storage = createStorage()
+    const request = createRequest()
+
+    const first = await useCache(storage, request as never, 'query X { a }' as never, { cache: 'short' } as never, options)
+    const second = await useCache(storage, request as never, 'query X { a }' as never, { cache: 'short' } as never, options)
+
+    expect(request).toHaveBeenCalledTimes(1)
+    expect(second).toStrictEqual(first)
+  })
+
+  it('derives the ttl from the named cache tier', async () => {
+    const storage = createStorage()
+
+    await useCache(storage, createRequest() as never, 'query X { a }' as never, { cache: 'short' } as never, options)
+    await useCache(storage, createRequest() as never, 'query Y { b }' as never, { cache: 'long' } as never, options)
+
+    expect([...ttls.values()]).toStrictEqual([{ ttl: 10_000 }, { ttl: 86_400_000 }])
+  })
+
+  it('keys separately per operation and per variables', async () => {
+    const storage = createStorage()
+    const request = createRequest()
+
+    await useCache(storage, request as never, 'query X { a }' as never, { cache: 'short' } as never, options)
+    await useCache(storage, request as never, 'query Y { b }' as never, { cache: 'short' } as never, options)
+    await useCache(storage, request as never, 'query X { a }' as never, { cache: 'short', variables: { handle: 'a' } } as never, options)
+    await useCache(storage, request as never, 'query X { a }' as never, { cache: 'short', variables: { handle: 'b' } } as never, options)
+
+    expect(request).toHaveBeenCalledTimes(4)
+    expect(store.size).toBe(4)
+  })
+
+  it('does not cache when no storage is available', async () => {
+    const request = createRequest()
+
+    await useCache(undefined, request as never, 'query X { a }' as never, { cache: 'short' } as never, options)
+    await useCache(undefined, request as never, 'query X { a }' as never, { cache: 'short' } as never, options)
+
+    expect(request).toHaveBeenCalledTimes(2)
+  })
+
+  it('does not cache an unknown cache tier', async () => {
+    const storage = createStorage()
+    const request = createRequest()
+
+    await useCache(storage, request as never, 'query X { a }' as never, { cache: 'nope' } as never, options)
+    await useCache(storage, request as never, 'query X { a }' as never, { cache: 'nope' } as never, options)
+
+    expect(request).toHaveBeenCalledTimes(2)
+    expect(store.size).toBe(0)
+  })
+
+  it('does not cache a response that carries errors', async () => {
+    const storage = createStorage()
+    const request = vi.fn(async () => ({ data: undefined, errors: { message: 'boom' }, headers: new Headers() }))
+
+    await useCache(storage, request as never, 'query X { a }' as never, { cache: 'short' } as never, options)
+    await useCache(storage, request as never, 'query X { a }' as never, { cache: 'short' } as never, options)
+
+    expect(request).toHaveBeenCalledTimes(2)
+    expect(store.size).toBe(0)
+  })
+
+  it('asks the proxy for the same tier it caches under', async () => {
+    const request = createRequest()
+
+    await useCache(createStorage(), request as never, 'query X { a }' as never, { cache: 'long' } as never, options)
+
+    expect(requestOptions(request)).toMatchObject({ headers: { 'X-Shopify-Proxy-Cache': 'long' } })
+  })
+
+  it('supports split client and proxy cache tiers', async () => {
+    const request = createRequest()
+
+    await useCache(
+      createStorage(),
+      request as never,
+      'query X { a }' as never,
+      { cache: { client: 'short', proxy: 'long' } } as never,
+      options,
+    )
+
+    expect(requestOptions(request)).toMatchObject({ headers: { 'X-Shopify-Proxy-Cache': 'long' } })
+    expect([...ttls.values()]).toStrictEqual([{ ttl: 10_000 }])
+  })
+})

test/unit/client-errors.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import useErrors from '../../src/runtime/utils/clients/errors'
+
+const graphQLErrors = [{ message: 'Field `nope` doesn\'t exist', path: ['products', 'nope'] }]
+
+describe('client errors', () => {
+  it('does nothing when there are no errors', async () => {
+    await expect(useErrors(undefined as never, true)).resolves.toBeUndefined()
+  })
+
+  it('reports graphql errors with their path', async () => {
+    await expect(useErrors({ graphQLErrors } as never, true)).rejects.toMatchObject({
+      statusCode: 500,
+      statusMessage: 'Internal Server Error',
+      message: expect.stringContaining('(at `products.nope`)'),
+    })
+  })
+
+  it('keeps the upstream status when Shopify returns one', async () => {
+    await expect(useErrors({ graphQLErrors, networkStatusCode: 429 } as never, true)).rejects.toMatchObject({
+      statusCode: 429,
+      statusMessage: 'Too Many Requests',
+    })
+  })
+
+  it('falls back to 500 for a success-range network status', async () => {
+    await expect(useErrors({ graphQLErrors, networkStatusCode: 200 } as never, true)).rejects.toMatchObject({ statusCode: 500 })
+  })
+
+  it('reports a transport error without graphql errors', async () => {
+    await expect(useErrors({ message: 'network down', networkStatusCode: 503 } as never, true)).rejects.toMatchObject({
+      statusCode: 503,
+      statusMessage: 'Service Unavailable',
+      message: expect.stringContaining('Request failed: network down'),
+    })
+  })
+
+  it('swallows errors when throwing is disabled', async () => {
+    await expect(useErrors({ graphQLErrors } as never, false)).resolves.toBeUndefined()
+  })
+
+  it('always notifies the callback, throwing or not', async () => {
+    const onErrors = vi.fn()
+
+    await useErrors({ graphQLErrors } as never, false, onErrors)
+    await useErrors({ graphQLErrors } as never, true, onErrors).catch(() => {})
+
+    expect(onErrors).toHaveBeenCalledTimes(2)
+    expect(onErrors).toHaveBeenCalledWith({ errors: { graphQLErrors } })
+  })
+})

test/unit/client-functions.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from 'vitest'
+
+import { flattenConnection } from '../../src/runtime/utils/functions/flattenConnection'
+import { parseGid } from '../../src/runtime/utils/functions/parseGid'
+
+describe('flattenConnection', () => {
+  it('unwraps an edges connection', () => {
+    expect(flattenConnection({ edges: [{ node: { id: '1' } }, { node: { id: '2' } }] })).toStrictEqual([{ id: '1' }, { id: '2' }])
+  })
+
+  it('passes a nodes connection through', () => {
+    expect(flattenConnection({ nodes: [{ id: '1' }] })).toStrictEqual([{ id: '1' }])
+  })
+
+  it('prefers edges when a connection carries both', () => {
+    expect(flattenConnection({ edges: [{ node: { id: 'edge' } }], nodes: [{ id: 'node' }] })).toStrictEqual([{ id: 'edge' }])
+  })
+
+  it('returns an empty array for empty, missing and null connections', () => {
+    expect(flattenConnection({ edges: [] })).toStrictEqual([])
+    expect(flattenConnection({})).toStrictEqual([])
+    expect(flattenConnection(null)).toStrictEqual([])
+    expect(flattenConnection(undefined)).toStrictEqual([])
+  })
+})
+
+describe('parseGid', () => {
+  it('extracts the numeric id from a global id', () => {
+    expect(parseGid('gid://shopify/Product/1234567890')).toBe('1234567890')
+    expect(parseGid('gid://shopify/HydrogenStorefront/1')).toBe('1')
+  })
+
+  it('ignores query parameters appended by the API', () => {
+    expect(parseGid('gid://shopify/ProductVariant/42?namespace=custom')).toBe('42')
+  })
+
+  it('throws on anything that is not a Shopify global id', () => {
+    expect(() => parseGid('1234567890')).toThrow(/invalid format/)
+    expect(() => parseGid('gid://shopify/Product/')).toThrow(/invalid format/)
+    expect(() => parseGid('')).toThrow(/invalid format/)
+  })
+})