@usequeek/theme-kit 0.1.19 → 0.1.20

package/README.md

@@ -203,7 +203,10 @@ export default function Footer() {
   it — style the classes in your theme.
 - The href (`https://usequeek.com/business`), `target="_blank"` and
   `rel="noopener noreferrer"` are the contract — never re-implement the
-  markup by hand.
+  markup by hand. The href is tagged for attribution by `poweredByQueekUrl`
+  (`utm_source=powered_by&utm_medium=storefront&utm_campaign=<store slug>`,
+  campaign omitted when the store has no slug); the component reads the slug
+  from the storefront context, so themes pass nothing.
 - `hidden` (default false) takes the component's visibility from a prop as
   the seam for a possible future plan perk. There is no merchant-facing
   toggle for it in v1 — always render it visible.

package/components/powered-by-queek.tsx

@@ -1,4 +1,8 @@
-import type { JSX } from 'react';
+'use client';
+
+import { useContext, type JSX } from 'react';
+import { StorefrontContext } from '../provider';
+import { poweredByQueekUrl } from '../utils/powered-by';
 
 export interface PoweredByQueekProps {
   /** Extra class so a footer can position the link — styling stays theme-owned. */
@@ -17,15 +21,20 @@ export interface PoweredByQueekProps {
  * Required on every footer variant of every theme (enforced by `theme-check`
  * rule `theme/footer-shows-powered-by` in the storefront repo). The link
  * target (`https://usequeek.com/business`) and `rel` are the contract —
- * do not change them. Markup carries `core-powered-by` classes so each theme
+ * do not change them. The href is tagged `utm_source=powered_by`,
+ * `utm_medium=storefront`, `utm_campaign=<store slug>` via `poweredByQueekUrl`
+ * (read from the storefront context, so themes pass nothing; no provider means
+ * no campaign, never an error). Markup carries `core-powered-by` classes so each theme
  * styles it in its own `theme.css`; no kit CSS ships for it.
  */
 export function PoweredByQueek({ className, hidden = false }: PoweredByQueekProps): JSX.Element | null {
+  const vendor = useContext(StorefrontContext)?.vendor;
+
   if (hidden) return null;
 
   return (
     <a
-      href="https://usequeek.com/business"
+      href={poweredByQueekUrl(vendor?.slug)}
       target="_blank"
       rel="noopener noreferrer"
       className={className ? `core-powered-by ${className}` : 'core-powered-by'}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usequeek/theme-kit",
-  "version": "0.1.19",
+  "version": "0.1.20",
   "private": false,
   "license": "MIT",
   "description": "The framework a Queek storefront theme is built against.",

package/tests/powered-by-queek.test.tsx

@@ -2,9 +2,18 @@ import React from 'react';
 import { renderToStaticMarkup } from 'react-dom/server';
 import { describe, expect, it } from 'vitest';
 import { PoweredByQueek } from '../components/powered-by-queek';
+import { StorefrontContext } from '../provider';
 
-function render(props?: { className?: string; hidden?: boolean }): string {
-  return renderToStaticMarkup(React.createElement(PoweredByQueek, props));
+const BASE = 'https://usequeek.com/business?utm_source=powered_by&utm_medium=storefront';
+
+function render(props?: { className?: string; hidden?: boolean }, vendor?: { id: string; slug: string | null }): string {
+  const element = React.createElement(PoweredByQueek, props);
+
+  if (!vendor) return renderToStaticMarkup(element);
+
+  return renderToStaticMarkup(
+    React.createElement(StorefrontContext.Provider, { value: { vendor } as never }, element),
+  );
 }
 
 describe('PoweredByQueek', () => {
@@ -12,11 +21,29 @@ describe('PoweredByQueek', () => {
     const html = render();
 
     expect(html).toContain('<a');
-    expect(html).toContain('href="https://usequeek.com/business"');
+    expect(html).toContain(`href="${BASE}"`);
     expect(html).toContain('target="_blank"');
     expect(html).toContain('rel="noopener noreferrer"');
   });
 
+  it('tags the link with the store slug as utm_campaign', () => {
+    const html = render(undefined, { id: 'uuid-1', slug: 'kili-foods' });
+
+    expect(html).toContain(`href="${BASE}&amp;utm_campaign=kili-foods"`);
+    expect(html).toContain('rel="noopener noreferrer"');
+  });
+
+  it('omits utm_campaign (never the internal UUID) when the store has no slug', () => {
+    const html = render(undefined, { id: 'uuid-1', slug: null });
+
+    expect(html).not.toContain('utm_campaign');
+    expect(html).not.toContain('uuid-1');
+  });
+
+  it('omits utm_campaign (never errors) when no storefront provider is mounted', () => {
+    expect(render()).not.toContain('utm_campaign');
+  });
+
   it('renders "Powered by Queek" with the brand hook for theme styling', () => {
     const html = render();
 
@@ -33,5 +60,6 @@ describe('PoweredByQueek', () => {
 
   it('renders nothing when hidden', () => {
     expect(render({ hidden: true })).toBe('');
+    expect(render({ hidden: true }, { id: 'uuid-1', slug: 'kili-foods' })).toBe('');
   });
 });

package/tests/powered-by-url.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest';
+import { POWERED_BY_QUEEK_URL, poweredByQueekUrl } from '../utils/powered-by';
+
+function params(url: string): Record<string, string> {
+  return Object.fromEntries(new URL(url).searchParams.entries());
+}
+
+describe('poweredByQueekUrl', () => {
+  it('keeps the business-page destination and adds source, medium and campaign', () => {
+    const url = poweredByQueekUrl('kili-foods');
+
+    expect(url.startsWith(`${POWERED_BY_QUEEK_URL}?`)).toBe(true);
+    expect(params(url)).toEqual({
+      utm_source: 'powered_by',
+      utm_medium: 'storefront',
+      utm_campaign: 'kili-foods',
+    });
+  });
+
+  it.each([undefined, null, '', '   '])('omits utm_campaign for a blank campaign (%j)', (campaign) => {
+    expect(params(poweredByQueekUrl(campaign))).toEqual({
+      utm_source: 'powered_by',
+      utm_medium: 'storefront',
+    });
+  });
+
+  it('preserves an existing query and overrides only its own utm keys', () => {
+    const url = poweredByQueekUrl('shop-1', 'https://usequeek.com/business?plan=pro&utm_source=old&utm_campaign=stale');
+
+    expect(params(url)).toEqual({
+      plan: 'pro',
+      utm_source: 'powered_by',
+      utm_medium: 'storefront',
+      utm_campaign: 'shop-1',
+    });
+  });
+
+  it('drops a stale utm_campaign when the new campaign is blank', () => {
+    expect(params(poweredByQueekUrl(null, 'https://usequeek.com/business?utm_campaign=stale'))).not.toHaveProperty('utm_campaign');
+  });
+
+  it('url-encodes the campaign and is deterministic (SSR-safe, no window/Date)', () => {
+    const url = poweredByQueekUrl('a b&c');
+
+    expect(url).toContain('utm_campaign=a+b%26c');
+    expect(params(url).utm_campaign).toBe('a b&c');
+    expect(poweredByQueekUrl('a b&c')).toBe(url);
+  });
+});

package/utils/powered-by.ts

@@ -0,0 +1,31 @@
+/**
+ * The one place the "Powered by Queek" destination is built, so every theme's
+ * footer link carries the same attribution and the affiliate/referral program
+ * can trace a signup back to the store it came from.
+ */
+export const POWERED_BY_QUEEK_URL = 'https://usequeek.com/business';
+
+export const POWERED_BY_UTM_SOURCE = 'powered_by';
+export const POWERED_BY_UTM_MEDIUM = 'storefront';
+
+/**
+ * `campaign` is the store's public slug (never an internal UUID) so signups
+ * are attributable per store. Existing query parameters on the base
+ * URL are kept; the `utm_*` keys are always ours. A blank campaign omits
+ * `utm_campaign` rather than sending an empty value.
+ */
+export function poweredByQueekUrl(campaign?: string | null, base: string = POWERED_BY_QUEEK_URL): string {
+  const url = new URL(base);
+
+  url.searchParams.set('utm_source', POWERED_BY_UTM_SOURCE);
+  url.searchParams.set('utm_medium', POWERED_BY_UTM_MEDIUM);
+
+  const trimmed = campaign?.trim();
+  if (trimmed) {
+    url.searchParams.set('utm_campaign', trimmed);
+  } else {
+    url.searchParams.delete('utm_campaign');
+  }
+
+  return url.toString();
+}