@usequeek/theme-kit 0.1.0

package/README.md

@@ -0,0 +1,37 @@
+# @usequeek/theme-kit
+
+The framework a Queek storefront theme is built against: hooks, stores, headless
+flows (auth, cart, checkout), types and the block renderer.
+
+**Ships TypeScript source, not a build.** 78 of its 115 modules carry a
+`'use client'` directive, and that directive is the whole contract with the React
+Server Components boundary — bundlers routinely strip or hoist it when a library
+is pre-compiled, which turns a client module into a server one silently. The
+consumer transpiles instead (`transpilePackages: ['@usequeek/theme-kit']`), so the
+directives survive to the bundler that actually enforces them.
+
+Deep subpaths resolve off the filesystem — there is deliberately NO `exports`
+map. One was tried: with source-shipped `.ts`/`.tsx` an extensionless wildcard
+target does not resolve, and spelling out extensions cannot cover both. Legacy
+resolution under `moduleResolution: bundler` handles it. The cost is that the
+package has no subpath encapsulation, so what a theme may import is enforced by
+`tests/core-public-surface.test.ts` in the storefront repo instead — which is
+where the real contract lives anyway. Revisit if this is ever published.
+
+## Use
+
+```ts
+import { useCart } from '@usequeek/theme-kit/hooks/use-cart';
+import type { ThemeModule } from '@usequeek/theme-kit/types/theme';
+```
+
+Deep paths, mirroring the old `@/lib/core/*`. Barrels exist (`.` and `./client`)
+to DECLARE the public surface — what a theme is allowed to build against — but
+importing through them pulls every client module into one chunk and was measured
+to break the app's build. Import the module you want.
+
+## Boundary
+
+The kit must never import the storefront app, its themes, or `lib/storefront`.
+That one-way rule is enforced by `tests/core-storefront-boundary.test.ts` in the
+storefront repo, and it is why this package can be extracted at all.

package/api/collections.ts

@@ -0,0 +1,93 @@
+import { createServerStoreClient, getRequestOrigin } from '../sdk/server-store-client';
+import { swallowNotFound } from '../sdk/client';
+import type { Collection, Pagination } from '../types/page';
+import type { ApiResponse } from '../types/product';
+import { extractProducts, normalizeProduct } from '../utils/product-normalizer';
+
+/** Matches `VendorCollectionProductsRequest`'s validated `sort` values exactly
+ *  (queek_backend) — a value outside this list gets a 422 from the backend. */
+export type CollectionSort = 'newest' | 'popular' | 'price_low' | 'price_high';
+
+export interface FetchCollectionProductsOptions {
+  page?: number;
+  perPage?: number;
+  sort?: CollectionSort;
+  keyword?: string;
+}
+
+// SSR collection reads go through `/client/store/*` so ResolveClientContext forces
+// X-Platform=storefront (base prices, no marketplace commission) — never the
+// legacy v1 routes shared with the commission-bearing marketplace.
+export async function fetchCollections(vendorSlug: string, storefrontOnly = true): Promise<Collection[]> {
+  const client = createServerStoreClient(vendorSlug, await getRequestOrigin());
+
+  try {
+    const response = await client.get<ApiResponse<Collection[]>>(`/collections`, {
+      storefront: storefrontOnly ? 1 : 0,
+    });
+
+    return response.data ?? [];
+  } catch (error) {
+    // A timeout here cascades: the collection page reads null and calls
+    // notFound(), 404-ing a collection that exists.
+    return swallowNotFound(error) ?? [];
+  }
+}
+
+export async function fetchCollection(vendorSlug: string, slug: string): Promise<Collection | null> {
+  const collections = await fetchCollections(vendorSlug);
+
+  return collections.find((collection) => collection.slug === slug) ?? null;
+}
+
+export async function fetchCollectionProducts(
+  vendorSlug: string,
+  slug: string,
+  options?: FetchCollectionProductsOptions,
+): Promise<{
+  collection: Collection | null;
+  products: ReturnType<typeof normalizeProduct>[];
+  pagination?: Pagination;
+}> {
+  const client = createServerStoreClient(vendorSlug, await getRequestOrigin());
+
+  const query: Record<string, string | number> = {};
+  if (options?.sort) query.sort = options.sort;
+  if (options?.keyword?.trim()) query.keyword = options.keyword.trim();
+  if (options?.perPage) query.per_page = options.perPage;
+  // Laravel's paginator reads the CURRENT page off the `page` query param
+  // implicitly (there is no `page` field in VendorCollectionProductsRequest's
+  // own validation rules) — it must be sent as a plain query param, not
+  // folded into the validated filters the backend actually reads.
+  if (options?.page && options.page > 1) query.page = options.page;
+
+  try {
+    const [collection, response] = await Promise.all([
+      fetchCollection(vendorSlug, slug),
+      client.get<ApiResponse<unknown, Record<string, unknown>>>(`/collections/${slug}/products`, query),
+    ]);
+
+    const meta = response.meta ?? {};
+
+    return {
+      collection,
+      products: extractProducts(response.data).map((product) => normalizeProduct(product)),
+      pagination: {
+        current_page: (meta.current_page as number) ?? options?.page ?? 1,
+        per_page: (meta.per_page as number) ?? options?.perPage,
+        // No `total`/`last_page` — this endpoint uses `simplePaginate()`
+        // (deliberately, to avoid a COUNT query on large catalogues), so
+        // `links.next` (a URL or null) is the only real "is there another
+        // page" signal. `CollectionPager` already treats total/last_page as
+        // optional and falls back to a plain "Page N" label without them.
+        has_more: Boolean(response.links?.next),
+        next_page_url: response.links?.next ?? null,
+        prev_page_url: response.links?.prev ?? null,
+      },
+    };
+  } catch (error) {
+    swallowNotFound(error);
+
+    return { collection: null, products: [] };
+  }
+}

package/api/orders.ts

@@ -0,0 +1,23 @@
+import { createBrowserClient } from '../sdk/client';
+import type { OrderListResponse, OrderDetail } from '../types/order';
+
+export async function fetchOrders(
+  vendorSlug: string,
+  page = 1,
+  status?: string,
+): Promise<OrderListResponse> {
+  const client = createBrowserClient(vendorSlug);
+  return client.get<OrderListResponse>('/orders', {
+    page,
+    ...(status && status !== 'all' ? { status } : {}),
+  });
+}
+
+export async function fetchOrderDetail(
+  vendorSlug: string,
+  id: string,
+): Promise<OrderDetail> {
+  const client = createBrowserClient(vendorSlug);
+  const res = await client.get<{ data: OrderDetail }>(`/orders/${id}`);
+  return res.data;
+}

package/apps/analytics-events.ts

@@ -0,0 +1,32 @@
+'use client';
+
+import { gtagPush } from './gtag';
+
+/**
+ * Not gated on consent here — Consent Mode (see analytics.tsx) is what
+ * decides whether gtag.js actually transmits anything for a denied visitor.
+ * Callers push events unconditionally; Google's library filters them.
+ */
+interface GaItem {
+  item_id: string;
+  item_name: string;
+  price: number;
+  quantity?: number;
+}
+
+export function pushViewItem(item: GaItem, currency: string): void {
+  gtagPush('event', 'view_item', { currency, value: item.price, items: [item] });
+}
+
+export function pushAddToCart(item: GaItem, currency: string): void {
+  gtagPush('event', 'add_to_cart', { currency, value: item.price * (item.quantity ?? 1), items: [item] });
+}
+
+export function pushPurchase(args: { transactionId: string; value: number; currency: string; items: GaItem[] }): void {
+  gtagPush('event', 'purchase', {
+    transaction_id: args.transactionId,
+    value: args.value,
+    currency: args.currency,
+    items: args.items,
+  });
+}