create-nymbal-app 0.3.0 → 0.5.0

package/scaffold/templates/astro/src/lib/api.ts

@@ -1,6 +1,11 @@
-import type { DenormalisedProduct, ProductListResult, ReviewsListResult } from '@nymbalhq/sdk'
+import type {
+  DenormalisedProduct,
+  ProductListResult,
+  ProductSearchResult,
+  ReviewsListResult,
+} from '@nymbalhq/sdk'
 import { DEFAULT_PRODUCT_SORT, PRODUCT_SORT_KEYS } from '@nymbalhq/types'
-import type { Category, Order, ProductSortKey } from '@nymbalhq/types'
+import type { Cart, Category, Order, ProductSortKey, StoreCapabilities } from '@nymbalhq/types'
 
 const API_URL = import.meta.env.NYMBAL_API_URL ?? 'http://localhost:3001'
 
@@ -27,40 +32,78 @@ export async function fetchProducts(params?: {
   }
 }
 
-/** The sort a listing URL asks for; a missing or unknown `?sort=` is the default. */
-export function sortFromUrl(url: URL): ProductSortKey {
+/** The API failed: it did not answer, answered an error other than a 404, or answered with no data. */
+export class ApiUnavailableError extends Error {
+  override name = 'ApiUnavailableError'
+}
+
+/** `GET <path>`'s data; null on a 404; rejects with ApiUnavailableError (or fetch's own error) on any other failure. */
+async function apiData<T>(path: string): Promise<T | null> {
+  const res = await fetch(`${API_URL}${path}`)
+  if (res.status === 404) return null
+  if (!res.ok) throw new ApiUnavailableError(`GET ${path} answered ${res.status}`)
+  const envelope = (await res.json()) as { data?: T | null }
+  if (envelope.data === undefined || envelope.data === null) {
+    throw new ApiUnavailableError(`GET ${path} answered no data`)
+  }
+  return envelope.data
+}
+
+/** What the store can do, as the API sent it; rejects when the API fails. */
+export async function loadCapabilities(): Promise<StoreCapabilities> {
+  const capabilities = await apiData<StoreCapabilities>('/api/capabilities')
+  if (capabilities === null) throw new ApiUnavailableError('GET /api/capabilities answered 404')
+  return capabilities
+}
+
+/** What the store can do, which decides what the page renders; null when the API did not answer. */
+export async function fetchCapabilities(): Promise<StoreCapabilities | null> {
+  try {
+    return await loadCapabilities()
+  } catch (err) {
+    console.error('[api] fetchCapabilities failed', err)
+    return null
+  }
+}
+
+/** The sort a listing URL asks for, among the store's keys; a missing or unknown `?sort=` is the store's default. */
+export function sortFromUrl(url: URL, catalog?: StoreCapabilities['catalog']): ProductSortKey {
   const sort = url.searchParams.get('sort')
-  return PRODUCT_SORT_KEYS.find((key) => key === sort) ?? DEFAULT_PRODUCT_SORT
+  const keys = catalog?.sortKeys ?? PRODUCT_SORT_KEYS
+  return keys.find((key) => key === sort) ?? catalog?.defaultSort ?? DEFAULT_PRODUCT_SORT
+}
+
+/** A product as the API sent it; null when the API has none (a 404); rejects when the API fails. */
+export async function loadProduct(slug: string): Promise<DenormalisedProduct | null> {
+  return apiData<DenormalisedProduct>(`/api/products/${encodeURIComponent(slug)}`)
 }
 
 export async function fetchProduct(slug: string): Promise<DenormalisedProduct | null> {
   try {
-    const res = await fetch(`${API_URL}/api/products/${encodeURIComponent(slug)}`)
-    if (!res.ok) return null
-    const envelope = (await res.json()) as { data: DenormalisedProduct }
-    return envelope.data ?? null
+    return await loadProduct(slug)
   } catch (err) {
     console.error('[api] fetchProduct failed', err)
     return null
   }
 }
 
-const SEED_CATEGORIES: Category[] = [
-  { id: 'cat_apparel', parentId: null, name: 'Apparel', slug: 'apparel', description: 'Clothing and accessories', position: 0, createdAt: '2024-01-01T00:00:00Z' },
-  { id: 'cat_home', parentId: null, name: 'Home', slug: 'home', description: 'Home goods and decor', position: 1, createdAt: '2024-01-01T00:00:00Z' },
-  { id: 'cat_electronics', parentId: null, name: 'Electronics', slug: 'electronics', description: 'Gadgets and devices', position: 2, createdAt: '2024-01-01T00:00:00Z' },
-  { id: 'cat_books', parentId: null, name: 'Books', slug: 'books', description: 'Books and reading', position: 3, createdAt: '2024-01-01T00:00:00Z' },
-]
+/** The store's categories as the API sent them; rejects when the API fails. */
+export async function loadCategories(): Promise<Category[]> {
+  const categories = await apiData<Category[]>('/api/categories')
+  if (categories === null) throw new ApiUnavailableError('GET /api/categories answered 404')
+  return categories
+}
 
+/**
+ * The store's categories, or none when the API failed: a page renders per request and no shared cache keeps it, so
+ * the next request shows the store's own; a list the API did not send would link to categories the store lacks.
+ */
 export async function fetchCategories(): Promise<Category[]> {
   try {
-    const res = await fetch(`${API_URL}/api/categories`)
-    if (!res.ok) return SEED_CATEGORIES
-    const envelope = (await res.json()) as { data: Category[] }
-    return envelope.data ?? SEED_CATEGORIES
+    return await loadCategories()
   } catch (err) {
     console.error('[api] fetchCategories failed', err)
-    return SEED_CATEGORIES
+    return []
   }
 }
 
@@ -87,3 +130,66 @@ export async function fetchReviews(productId: string): Promise<ReviewsListResult
     return { items: [], nextCursor: null }
   }
 }
+
+/** The cart the cart elements take as their `cart` attribute: its lines and sums, never the cart token. */
+export interface CartProjection {
+  items: Cart['items']
+  subtotalMinor: number
+  currency: string
+  itemCount: number
+}
+
+const CART_COOKIE = 'nymbal.cart'
+
+/** The `nymbal.cart` value in a request's Cookie header, or null. */
+function cartToken(cookie: string | null): string | null {
+  for (const pair of (cookie ?? '').split(';')) {
+    const [name, ...value] = pair.trim().split('=')
+    if (name === CART_COOKIE && value.length > 0) return value.join('=')
+  }
+  return null
+}
+
+/**
+ * The shopper's cart, read with the request's `nymbal.cart` cookie, as the projection the elements take. Null without
+ * the cookie: `GET /api/cart` with none would make a cart the page could not keep, so the element renders its shell
+ * and the browser fills it. The cookie reaches this server when the store and the API share a host or a proxy.
+ */
+export async function fetchCart(cookie: string | null): Promise<CartProjection | null> {
+  const token = cartToken(cookie)
+  if (token === null) return null
+  try {
+    const res = await fetch(`${API_URL}/api/cart`, {
+      headers: { Cookie: `${CART_COOKIE}=${token}` },
+    })
+    if (!res.ok) return null
+    const { items, subtotalMinor, currency } = ((await res.json()) as { data: Cart }).data
+    return {
+      items,
+      subtotalMinor,
+      currency,
+      itemCount: items.reduce((n, item) => n + item.qty, 0),
+    }
+  } catch (err) {
+    console.error('[api] fetchCart failed', err)
+    return null
+  }
+}
+
+/** The search the search page shows for `q` (and its category), as the search store would hold it. */
+export async function fetchSearch(
+  q: string,
+  category: string | null,
+): Promise<ProductSearchResult | null> {
+  const url = new URL('/api/products/search', API_URL)
+  url.searchParams.set('q', q)
+  if (category) url.searchParams.set('category', category)
+  try {
+    const res = await fetch(url.toString())
+    if (!res.ok) return null
+    return ((await res.json()) as { data: ProductSearchResult }).data ?? null
+  } catch (err) {
+    console.error('[api] fetchSearch failed', err)
+    return null
+  }
+}

package/scaffold/templates/astro/src/lib/chrome.ts

@@ -0,0 +1,59 @@
+import { renderElement } from '@nymbalhq/web-components/ssr'
+import './server-elements'
+
+// The store's header and footer, rendered by nymbal-site-header and nymbal-site-footer: edit the links here.
+
+export const HEADER = {
+  logo: 'Nymbal',
+  'account-href': '/account',
+  links: JSON.stringify([
+    { label: 'Apparel', href: '/category/apparel' },
+    { label: 'Home', href: '/category/home' },
+    { label: 'Electronics', href: '/category/electronics' },
+    { label: 'Books', href: '/category/books' },
+    { label: 'All Products', href: '/products' },
+  ]),
+}
+
+export const FOOTER = {
+  columns: JSON.stringify([
+    {
+      heading: 'Shop',
+      links: [
+        { label: 'All Products', href: '/products' },
+        { label: 'Apparel', href: '/category/apparel' },
+        { label: 'Home', href: '/category/home' },
+        { label: 'Electronics', href: '/category/electronics' },
+        { label: 'Books', href: '/category/books' },
+      ],
+    },
+    {
+      heading: 'Account',
+      links: [
+        { label: 'Login', href: '/account/login' },
+        { label: 'Register', href: '/account/register' },
+        { label: 'Orders', href: '/account/orders' },
+      ],
+    },
+    {
+      heading: 'About',
+      text: 'Nymbal is a modern headless commerce platform built for developers. Fast, flexible, and fully customisable.',
+    },
+  ]),
+}
+
+/**
+ * The header's light-DOM children, each rendered by the server with the slot it fills: the search bar (when the store
+ * searches) and the mini-cart with the shopper's count (none in a shared, cached header). HTML, not markup: Astro
+ * would take `slot` on a component's child as a slot of NymbalElement's own.
+ */
+export function headerSlots(canSearch: boolean, cartCount?: number): string {
+  const search = canSearch
+    ? renderElement('nymbal-search-bar', {
+        attributes: { slot: 'search', placeholder: 'Search products...', 'debounce-ms': '300' },
+      })
+    : ''
+  const attributes: Record<string, string> = { slot: 'cart' }
+  if (cartCount !== undefined) attributes['count'] = String(cartCount)
+  return search + renderElement('nymbal-mini-cart', { attributes })
+}

package/scaffold/templates/astro/src/lib/client.ts

@@ -1,5 +1,6 @@
+import '../elements/index.js'
 import { createNymbalClient } from '@nymbalhq/sdk'
-import { registerClient, registerComponents } from '@nymbalhq/web-components'
+import { registerClient } from '@nymbalhq/web-components'
 
 const client = createNymbalClient({
   baseUrl: import.meta.env.PUBLIC_NYMBAL_API_URL ?? 'http://localhost:3001',
@@ -7,7 +8,8 @@ const client = createNymbalClient({
 })
 
 registerClient(client)
-registerComponents()
+// A payment driver of the project's own goes here, before any element is defined: registerPaymentDriver(name, driver)
+// from @nymbalhq/sdk, named by the driver of the payments adapter's client half.
 client.cart.load()
 
 export { client }

package/scaffold/templates/astro/src/lib/fragments.ts

@@ -0,0 +1,48 @@
+import type { DenormalisedProduct } from '@nymbalhq/sdk'
+import type { Category } from '@nymbalhq/types'
+import { loadCapabilities, loadCategories, loadProduct } from './api'
+
+// A fragment is cached by a CDN for hours, so it carries only what the API sent: when the API fails, the fragment
+// answers an error no cache keeps, never a fallback (no categories, no search bar) a CDN would hold for its TTL.
+
+const NOT_STORED = { 'Content-Type': 'text/plain; charset=utf-8', 'Cache-Control': 'no-store' }
+
+function apiFailed(fragment: string, err: unknown): Response {
+  console.error(`[fragments] ${fragment}: the API failed`, err)
+  return new Response('The store API is unavailable', { status: 502, headers: NOT_STORED })
+}
+
+/** The header fragment's data: whether the store searches; a 502 `no-store` response when the API failed. */
+export async function headerFragment(): Promise<{ canSearch: boolean } | Response> {
+  try {
+    const capabilities = await loadCapabilities()
+    return { canSearch: capabilities.search.capabilities.includes('search') }
+  } catch (err) {
+    return apiFailed('header', err)
+  }
+}
+
+/** The nav fragment's data: the API's categories; a 502 `no-store` response when the API failed. */
+export async function navFragment(): Promise<{ categories: Category[] } | Response> {
+  try {
+    return { categories: await loadCategories() }
+  } catch (err) {
+    return apiFailed('nav', err)
+  }
+}
+
+/**
+ * The product fragment's data: the API's product; a 404 `no-store` response for a product the API does not have (a CDN
+ * would apply its default 404 TTL to a 404 with no Cache-Control), a 502 `no-store` one when the API failed.
+ */
+export async function productFragment(
+  slug: string,
+): Promise<{ product: DenormalisedProduct } | Response> {
+  try {
+    const product = await loadProduct(slug)
+    if (product === null) return new Response('Not found', { status: 404, headers: NOT_STORED })
+    return { product }
+  } catch (err) {
+    return apiFailed('product', err)
+  }
+}

package/scaffold/templates/astro/src/lib/server-elements.ts

@@ -0,0 +1,5 @@
+import { registerServerElements } from '@nymbalhq/web-components/ssr'
+import { serverElements } from '../elements/index.js'
+
+// The store's own elements render on the server under their tags, as the browser defines them there.
+registerServerElements(serverElements)

package/scaffold/templates/astro/src/middleware.ts

@@ -0,0 +1,37 @@
+import { defineMiddleware } from 'astro:middleware'
+
+/** Whether an `Accept-Encoding` value accepts gzip: a `gzip` entry (or, without one, `*`) with a q-value above 0. */
+function acceptsGzip(header: string): boolean {
+  let star = false
+  for (const entry of header.split(',')) {
+    const [coding = '', ...params] = entry.split(';').map((part) => part.trim().toLowerCase())
+    const q = params.find((param) => param.startsWith('q='))
+    const accepted = q === undefined || Number(q.slice(2)) > 0
+    if (coding === 'gzip' || coding === 'x-gzip') return accepted
+    if (coding === '*') star = accepted
+  }
+  return star
+}
+
+// The standalone Node adapter compresses nothing, so a page's HTML (its styles inlined) went over the wire whole.
+// An HTML response is gzipped as a stream when the client accepts it; everything else passes through unchanged, and a
+// proxy that compresses sees the encoding and passes it on. Every HTML response varies on Accept-Encoding, the
+// uncompressed one included, so a cache keeps both forms apart.
+export const onRequest = defineMiddleware(async (context, next) => {
+  const response = await next()
+  const type = response.headers.get('content-type') ?? ''
+  if (!type.startsWith('text/html') || response.headers.has('content-encoding')) return response
+  const headers = new Headers(response.headers)
+  headers.append('vary', 'Accept-Encoding')
+  let body = response.body
+  if (body !== null && acceptsGzip(context.request.headers.get('accept-encoding') ?? '')) {
+    headers.set('content-encoding', 'gzip')
+    headers.delete('content-length')
+    body = body.pipeThrough(new CompressionStream('gzip'))
+  }
+  return new Response(body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  })
+})

package/scaffold/templates/astro/src/pages/account/addresses.astro

@@ -1,110 +1,18 @@
 ---
 import '../../styles/pages/account.css'
-import '../../styles/pages/checkout.css'
+import NymbalElement from '@nymbalhq/web-components/astro'
 import AccountLayout from '../../layouts/AccountLayout.astro'
-import AddressForm from '../../components/AddressForm.astro'
 ---
 
 <AccountLayout title="Addresses">
   <h1 class="account-page-title">Addresses</h1>
 
-  <div id="addresses-container" data-testid="addresses-list">
-    <p style="color: var(--nymbal-color-text-muted, #71717a); font-size: var(--nymbal-font-size-sm, 0.875rem);">
-      Loading addresses...
-    </p>
-  </div>
-
-  <div style="margin-top: var(--nymbal-spacing-xl, 2rem);">
-    <h2 class="section-title">Add New Address</h2>
-    <form id="add-address-form" class="account-form" data-testid="add-address-form">
-      <AddressForm id="new-address" />
-      <div class="account-form-actions">
-        <button type="submit" class="btn btn-primary" data-testid="save-address">Save Address</button>
-      </div>
-    </form>
-    <p class="form-message" id="address-form-message" style="display:none; margin-top: var(--nymbal-spacing-md, 1rem); font-size: var(--nymbal-font-size-sm, 0.875rem);"></p>
-  </div>
+  <NymbalElement tag="nymbal-address-book" />
 </AccountLayout>
 
 <script>
-  import type { Address, CustomerAddress } from '@nymbalhq/types'
-  import { client } from '../../lib/client.js'
-  import { escapeHtml } from '../../lib/format.js'
-  import { submitOnce } from '../../lib/submit-once.js'
-
-  const container = document.getElementById('addresses-container')
-  const form = document.getElementById('add-address-form') as HTMLFormElement | null
-  const messageEl = document.getElementById('address-form-message')
-
-  function renderAddress(addr: CustomerAddress): string {
-    const isDefault = addr.isDefaultShipping || addr.isDefaultBilling
-    return `
-      <div class="address-card ${isDefault ? 'default' : ''}" data-testid="address-${escapeHtml(addr.id)}">
-        ${isDefault ? '<span class="address-card-badge">Default</span>' : ''}
-        <div class="address-card-line">${escapeHtml(`${addr.firstName} ${addr.lastName}`)}</div>
-        <div class="address-card-line">${escapeHtml(addr.addressLine1)}</div>
-        ${addr.addressLine2 ? `<div class="address-card-line">${escapeHtml(addr.addressLine2)}</div>` : ''}
-        <div class="address-card-line">${escapeHtml(`${addr.city}, ${addr.region} ${addr.postalCode}`)}</div>
-        <div class="address-card-line">${escapeHtml(addr.country)}</div>
-      </div>
-    `
-  }
-
-  async function loadAddresses() {
-    if (!container) return
-
-    try {
-      const addresses = await client.customer.addresses.list()
-
-      if (addresses.length === 0) {
-        container.innerHTML = `
-          <div class="account-empty">
-            <h2 class="account-empty-title">No saved addresses</h2>
-            <p class="account-empty-text">Add an address below to get started.</p>
-          </div>
-        `
-        return
-      }
-
-      container.innerHTML = `<div class="address-list">${addresses.map(renderAddress).join('')}</div>`
-    } catch {
-      container.innerHTML = `
-        <div class="account-empty">
-          <p class="account-empty-text">Unable to load addresses.</p>
-        </div>
-      `
-    }
-  }
-
-  submitOnce(form, async () => {
-    if (!form || !messageEl) return
-
-    const formData = new FormData(form)
-    const field = (name: string) => String(formData.get(name) ?? '').trim()
-    const address: Address = {
-      firstName: field('firstName'),
-      lastName: field('lastName'),
-      addressLine1: field('addressLine1'),
-      city: field('city'),
-      region: field('region'),
-      postalCode: field('postalCode'),
-      country: field('country'),
-      ...(field('addressLine2') && { addressLine2: field('addressLine2') }),
-    }
-
-    try {
-      await client.customer.addresses.create(address)
-      messageEl.textContent = 'Address saved successfully.'
-      messageEl.style.color = 'var(--nymbal-color-success, #16a34a)'
-      messageEl.style.display = 'block'
-      form.reset()
-      await loadAddresses()
-    } catch {
-      messageEl.textContent = 'Failed to save address. Please try again.'
-      messageEl.style.color = 'var(--nymbal-color-error, #dc2626)'
-      messageEl.style.display = 'block'
-    }
-  })
+  import '../../lib/client.js'
+  import { NymbalAddressBook } from '@nymbalhq/web-components/elements/nymbal-address-book'
 
-  loadAddresses()
+  NymbalAddressBook.define()
 </script>

package/scaffold/templates/astro/src/pages/account/login.astro

@@ -1,5 +1,6 @@
 ---
 import '../../styles/pages/account.css'
+import NymbalElement from '@nymbalhq/web-components/astro'
 import BaseLayout from '../../layouts/BaseLayout.astro'
 ---
 
@@ -9,39 +10,7 @@ import BaseLayout from '../../layouts/BaseLayout.astro'
       <h1 class="auth-card-title">Sign In</h1>
       <p class="auth-card-subtitle">Welcome back. Enter your credentials to continue.</p>
 
-      <div class="checkout-error" id="login-error" style="display:none; margin-bottom: var(--nymbal-spacing-md, 1rem);" role="alert"></div>
-
-      <form id="login-form" data-testid="login-form">
-        <div class="form-group">
-          <label for="login-email">Email</label>
-          <input
-            type="email"
-            id="login-email"
-            name="email"
-            required
-            autocomplete="email"
-            placeholder="you@example.com"
-            data-testid="login-email"
-          />
-        </div>
-
-        <div class="form-group">
-          <label for="login-password">Password</label>
-          <input
-            type="password"
-            id="login-password"
-            name="password"
-            required
-            autocomplete="current-password"
-            placeholder="Your password"
-            data-testid="login-password"
-          />
-        </div>
-
-        <button type="submit" class="btn btn-primary" data-testid="login-submit">
-          Sign In
-        </button>
-      </form>
+      <NymbalElement tag="nymbal-login-form" />
 
       <p class="auth-footer">
         Don't have an account? <a href="/account/register">Create one</a>
@@ -51,5 +20,9 @@ import BaseLayout from '../../layouts/BaseLayout.astro'
 </BaseLayout>
 
 <script>
-  import '../../scripts/auth-forms.js'
+  import '../../lib/client.js'
+  import { NymbalLoginForm } from '@nymbalhq/web-components/elements/nymbal-login-form'
+  import '../../scripts/signed-in-redirect.js'
+
+  NymbalLoginForm.define()
 </script>

package/scaffold/templates/astro/src/pages/account/profile.astro

@@ -1,5 +1,6 @@
 ---
 import '../../styles/pages/account.css'
+import NymbalElement from '@nymbalhq/web-components/astro'
 import AccountLayout from '../../layouts/AccountLayout.astro'
 ---
 
@@ -7,63 +8,12 @@ import AccountLayout from '../../layouts/AccountLayout.astro'
   <h1 class="account-page-title">Profile</h1>
   <p class="account-page-subtitle">Update your personal information.</p>
 
-  <form id="profile-form" class="account-form" data-testid="profile-form">
-    <div class="account-form-row">
-      <div class="form-group">
-        <label for="profile-firstName">First Name</label>
-        <input
-          type="text"
-          id="profile-firstName"
-          name="firstName"
-          autocomplete="given-name"
-          data-testid="profile-firstName"
-        />
-      </div>
-
-      <div class="form-group">
-        <label for="profile-lastName">Last Name</label>
-        <input
-          type="text"
-          id="profile-lastName"
-          name="lastName"
-          autocomplete="family-name"
-          data-testid="profile-lastName"
-        />
-      </div>
-    </div>
-
-    <div class="form-group">
-      <label for="profile-email">Email</label>
-      <input
-        type="email"
-        id="profile-email"
-        name="email"
-        disabled
-        autocomplete="email"
-        data-testid="profile-email"
-        style="opacity: 0.6; cursor: not-allowed;"
-      />
-    </div>
-
-    <div class="form-group">
-      <label for="profile-phone">Phone</label>
-      <input
-        type="tel"
-        id="profile-phone"
-        name="phone"
-        autocomplete="tel"
-        data-testid="profile-phone"
-      />
-    </div>
-
-    <div class="account-form-actions">
-      <button type="submit" class="btn btn-primary" data-testid="profile-save">Save Changes</button>
-    </div>
-
-    <p class="form-message" id="profile-message" style="display:none; margin-top: var(--nymbal-spacing-md, 1rem); font-size: var(--nymbal-font-size-sm, 0.875rem);"></p>
-  </form>
+  <NymbalElement tag="nymbal-profile-form" attributes={{ class: 'account-form' }} />
 </AccountLayout>
 
 <script>
-  import '../../scripts/profile-form.js'
+  import '../../lib/client.js'
+  import { NymbalProfileForm } from '@nymbalhq/web-components/elements/nymbal-profile-form'
+
+  NymbalProfileForm.define()
 </script>