@merchi/cart 1.4.5 → 1.4.7

package/src/utilities/job_source.test.ts

@@ -0,0 +1,86 @@
+import {
+  JOB_SOURCE_STORAGE_KEY,
+  captureAndReadJobSource,
+  cartNeedsSourceUpdate,
+  hasPaidClick,
+} from './job_source';
+
+describe('job source capture', () => {
+  const originalLocation = window.location;
+  const originalReferrer = document.referrer;
+
+  beforeEach(() => {
+    window.localStorage.clear();
+    delete (window as any).location;
+    (window as any).location = {
+      search: '',
+      pathname: '/tyvek-wristbands',
+    };
+    Object.defineProperty(document, 'referrer', {
+      configurable: true,
+      value: '',
+    });
+  });
+
+  afterEach(() => {
+    (window as any).location = originalLocation;
+    Object.defineProperty(document, 'referrer', {
+      configurable: true,
+      value: originalReferrer,
+    });
+    window.localStorage.clear();
+  });
+
+  it('captures google ads click ids and landing path', () => {
+    (window as any).location = {
+      search: '?utm_source=google&utm_medium=cpc&gclid=EAIa&utm_campaign=bands',
+      pathname: '/tyvek-wristbands',
+    };
+    const source = captureAndReadJobSource();
+    expect(source.utmSource).toBe('google');
+    expect(source.utmMedium).toBe('cpc');
+    expect(source.utmCampaign).toBe('bands');
+    expect(source.sourceClickId).toBe('EAIa');
+    expect(source.sourceLanding).toBe(
+      '/tyvek-wristbands?utm_source=google&utm_medium=cpc&gclid=EAIa&utm_campaign=bands'
+    );
+    expect(hasPaidClick(source)).toBe(true);
+  });
+
+  it('keeps first-touch UTMs unless a paid click arrives later', () => {
+    (window as any).location = {
+      search: '?utm_source=newsletter&utm_medium=email',
+      pathname: '/',
+    };
+    captureAndReadJobSource();
+    (window as any).location = {
+      search: '?utm_source=google&utm_medium=cpc',
+      pathname: '/product',
+    };
+    expect(captureAndReadJobSource().utmSource).toBe('newsletter');
+    (window as any).location = {
+      search: '?gclid=NEWCLICK&utm_source=google',
+      pathname: '/product',
+    };
+    expect(captureAndReadJobSource().sourceClickId).toBe('NEWCLICK');
+    expect(window.localStorage.getItem(JOB_SOURCE_STORAGE_KEY)).toContain('NEWCLICK');
+  });
+
+  it('knows when an existing cart still needs source fields', () => {
+    expect(
+      cartNeedsSourceUpdate({}, { utmSource: 'google', sourceClickId: 'x' })
+    ).toBe(true);
+    expect(
+      cartNeedsSourceUpdate(
+        { utmSource: 'google' },
+        { utmSource: 'google', sourceClickId: 'x' }
+      )
+    ).toBe(true);
+    expect(
+      cartNeedsSourceUpdate(
+        { utmSource: 'google', sourceClickId: 'x' },
+        { utmSource: 'google', sourceClickId: 'x' }
+      )
+    ).toBe(false);
+  });
+});

package/src/utilities/job_source.ts

@@ -0,0 +1,165 @@
+export const JOB_SOURCE_STORAGE_KEY = 'merchi_job_source';
+
+const CLICK_ID_PARAMS = ['gclid', 'gbraid', 'wbraid', 'fbclid', 'msclkid'] as const;
+const UTM_PARAMS = [
+  'utm_source',
+  'utm_medium',
+  'utm_campaign',
+  'utm_content',
+  'utm_term',
+] as const;
+
+export interface JobSourceFields {
+  utmSource?: string;
+  utmMedium?: string;
+  utmCampaign?: string;
+  utmContent?: string;
+  utmTerm?: string;
+  sourceClickId?: string;
+  sourceLanding?: string;
+  sourceReferrer?: string;
+}
+
+function trimTo(value: string | null | undefined, limit: number): string | undefined {
+  if (!value) return undefined;
+  const text = value.trim().slice(0, limit);
+  return text || undefined;
+}
+
+function readSearchParams(): URLSearchParams {
+  if (typeof window === 'undefined') return new URLSearchParams();
+  try {
+    return new URLSearchParams(window.location.search);
+  } catch {
+    return new URLSearchParams();
+  }
+}
+
+function readStoredSource(): JobSourceFields | null {
+  if (typeof window === 'undefined') return null;
+  try {
+    const raw = window.localStorage.getItem(JOB_SOURCE_STORAGE_KEY);
+    if (!raw) return null;
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object') return null;
+    return parsed as JobSourceFields;
+  } catch {
+    return null;
+  }
+}
+
+function writeStoredSource(source: JobSourceFields) {
+  if (typeof window === 'undefined') return;
+  try {
+    window.localStorage.setItem(JOB_SOURCE_STORAGE_KEY, JSON.stringify(source));
+  } catch {
+    // Ignore quota / private-mode failures.
+  }
+}
+
+function currentLanding(): string | undefined {
+  if (typeof window === 'undefined') return undefined;
+  try {
+    const path = `${window.location.pathname || '/'}${window.location.search || ''}`;
+    return trimTo(path, 512);
+  } catch {
+    return undefined;
+  }
+}
+
+function currentReferrer(): string | undefined {
+  if (typeof document === 'undefined') return undefined;
+  try {
+    return trimTo(document.referrer, 512);
+  } catch {
+    return undefined;
+  }
+}
+
+export function sourceFromLocation(): JobSourceFields {
+  const params = readSearchParams();
+  const source: JobSourceFields = {
+    utmSource: trimTo(params.get('utm_source'), 256),
+    utmMedium: trimTo(params.get('utm_medium'), 256),
+    utmCampaign: trimTo(params.get('utm_campaign'), 256),
+    utmContent: trimTo(params.get('utm_content'), 256),
+    utmTerm: trimTo(params.get('utm_term'), 256),
+    sourceLanding: currentLanding(),
+    sourceReferrer: currentReferrer(),
+  };
+  for (const key of CLICK_ID_PARAMS) {
+    const value = trimTo(params.get(key), 256);
+    if (value) {
+      source.sourceClickId = value;
+      break;
+    }
+  }
+  return source;
+}
+
+export function hasPaidClick(source: JobSourceFields | null | undefined): boolean {
+  return Boolean(source?.sourceClickId);
+}
+
+export function hasSourceData(source: JobSourceFields | null | undefined): boolean {
+  if (!source) return false;
+  return Boolean(
+    source.utmSource ||
+      source.utmMedium ||
+      source.utmCampaign ||
+      source.utmContent ||
+      source.utmTerm ||
+      source.sourceClickId ||
+      source.sourceLanding ||
+      source.sourceReferrer
+  );
+}
+
+export function captureAndReadJobSource(): JobSourceFields {
+  const incoming = sourceFromLocation();
+  const stored = readStoredSource();
+  if (hasPaidClick(incoming) || !hasSourceData(stored)) {
+    const next = {
+      ...(stored || {}),
+      ...Object.fromEntries(
+        Object.entries(incoming).filter(([, value]) => Boolean(value))
+      ),
+    } as JobSourceFields;
+    if (hasSourceData(next)) writeStoredSource(next);
+    return next;
+  }
+  return stored || incoming;
+}
+
+export function jobSourceFieldsForApi(source?: JobSourceFields | null): JobSourceFields {
+  const resolved = source || captureAndReadJobSource();
+  const out: JobSourceFields = {};
+  (Object.keys(resolved) as Array<keyof JobSourceFields>).forEach((key) => {
+    const value = resolved[key];
+    if (value) out[key] = value;
+  });
+  return out;
+}
+
+export function cartNeedsSourceUpdate(
+  cart: { utmSource?: string; sourceClickId?: string; sourceChannel?: string } | null | undefined,
+  source: JobSourceFields
+): boolean {
+  if (!hasSourceData(source)) return false;
+  if (!cart?.utmSource && !cart?.sourceClickId && !cart?.sourceChannel) return true;
+  return Boolean(source.sourceClickId && !cart?.sourceClickId);
+}
+
+export const JOB_SOURCE_URL_KEYS = [...UTM_PARAMS, ...CLICK_ID_PARAMS];
+
+export function appendJobSourceToFormData(
+  data: FormData,
+  source?: JobSourceFields | null
+): FormData {
+  const fields = jobSourceFieldsForApi(source);
+  (Object.keys(fields) as Array<keyof JobSourceFields>).forEach((key) => {
+    const value = fields[key];
+    if (value) data.append(key, value);
+  });
+  return data;
+}

package/src/utilities/shipment.test.ts

@@ -0,0 +1,68 @@
+import {
+  checkoutShipmentHydrationAction,
+  shipmentGroupsHaveQuotes,
+} from './shipment';
+
+const savedAddress = {
+  lineOne: '32 Bridge St',
+  city: 'Brighton',
+  state: 'VIC',
+  postcode: '3186',
+  country: 'AU',
+};
+
+describe('shipmentGroupsHaveQuotes', () => {
+  it('is false when groups are missing or empty', () => {
+    expect(shipmentGroupsHaveQuotes(undefined)).toBe(false);
+    expect(shipmentGroupsHaveQuotes([])).toBe(false);
+    expect(shipmentGroupsHaveQuotes([{ quotes: [] }])).toBe(false);
+  });
+
+  it('is true when any group has quotes', () => {
+    expect(
+      shipmentGroupsHaveQuotes([{ quotes: [] }, { quotes: [{ id: 1 }] }])
+    ).toBe(true);
+  });
+});
+
+describe('checkoutShipmentHydrationAction', () => {
+  it('applies a localStorage address when the cart has none', () => {
+    expect(
+      checkoutShipmentHydrationAction({
+        cartAddress: {},
+        savedAddress,
+        shipmentGroups: [],
+      })
+    ).toBe('apply-saved-address');
+  });
+
+  it('refreshes quotes when the cart already has an address but no options', () => {
+    expect(
+      checkoutShipmentHydrationAction({
+        cartAddress: savedAddress,
+        savedAddress,
+        shipmentGroups: [],
+      })
+    ).toBe('refresh-quotes');
+  });
+
+  it('does nothing when quotes are already available', () => {
+    expect(
+      checkoutShipmentHydrationAction({
+        cartAddress: savedAddress,
+        savedAddress,
+        shipmentGroups: [{ quotes: [{ id: 9 }] }],
+      })
+    ).toBe(null);
+  });
+
+  it('does nothing when neither cart nor localStorage has an address', () => {
+    expect(
+      checkoutShipmentHydrationAction({
+        cartAddress: {},
+        savedAddress: {},
+        shipmentGroups: [],
+      })
+    ).toBe(null);
+  });
+});

package/src/utilities/shipment.ts

@@ -1,3 +1,5 @@
+import { addressHasContent, SavedCheckoutAddress } from './local_storage';
+
 export const shipmentFormId = '_shipment-address-form-id';
 
 export function cartItemsNeedShipment(cart: any) {
@@ -9,3 +11,35 @@ export function cartItemsNeedShipment(cart: any) {
   }
   return false;
 }
+
+export function shipmentGroupsHaveQuotes(groups?: any[] | null) {
+  if (!groups?.length) return false;
+  return groups.some(
+    (group) => Array.isArray(group?.quotes) && group.quotes.length > 0
+  );
+}
+
+export type CheckoutShipmentHydrationAction =
+  | 'apply-saved-address'
+  | 'refresh-quotes'
+  | null;
+
+/**
+ * When checkout hydrates a saved address (localStorage) the form shows it,
+ * but quotes are only fetched after the user edits the field. Returning
+ * `apply-saved-address` means the cart still needs that address applied so
+ * quotes can be generated; `refresh-quotes` means the cart already has an
+ * address but no usable shipment options.
+ */
+export function checkoutShipmentHydrationAction(options: {
+  cartAddress?: SavedCheckoutAddress | null;
+  savedAddress?: SavedCheckoutAddress | null;
+  shipmentGroups?: any[] | null;
+}): CheckoutShipmentHydrationAction {
+  const hasCartAddress = addressHasContent(options.cartAddress);
+  const hasSavedAddress = addressHasContent(options.savedAddress);
+  const hasQuotes = shipmentGroupsHaveQuotes(options.shipmentGroups);
+  if (!hasCartAddress && hasSavedAddress) return 'apply-saved-address';
+  if (hasCartAddress && !hasQuotes) return 'refresh-quotes';
+  return null;
+}