import { Callout } from "zudoku/ui/Callout";
import { Card, CardDescription, CardHeader, CardTitle } from "zudoku/ui/Card";
import { Link } from "zudoku/components";
import { LayersIcon, RocketIcon, ShoppingCartIcon } from "zudoku/icons";

# Storefront SDK

`@wocart/storefront` is the storefront's connection to Wocart. It reads the
store's catalog, delivery data and saved content, and it sends baskets,
reviews, OTP codes and orders through the server that owns the rules.

Your Astro pages decide how the store looks. The SDK decides what is safe to
read and send. Prices, stock, delivery fees, discounts and whether an order is
accepted stay on the server.

<Callout type="info" title="A fixed storefront is a real choice">
You do not need Wocart's editing tools to build a storefront. An Astro site
with this SDK and your own components is complete. The optional
[Theme SDK](/sdk/theme) adds merchant editing, saved page documents and
preview.
</Callout>

<div className="not-prose my-10 grid gap-4 sm:grid-cols-2">
  <Link to="/sdk/storefront/quickstart" className="group">
    <Card className="h-full transition-colors group-hover:border-primary/40">
      <CardHeader>
        <div className="mb-2 grid size-9 place-items-center rounded-lg bg-primary/10 text-primary">
          <RocketIcon className="size-4" />
        </div>
        <CardTitle>Quick start</CardTitle>
        <CardDescription>
          Install the SDK, create the server-only client, render a catalog and a product page.
        </CardDescription>
      </CardHeader>
    </Card>
  </Link>
  <Link to="/sdk/storefront/how-it-works" className="group">
    <Card className="h-full transition-colors group-hover:border-primary/40">
      <CardHeader>
        <div className="mb-2 grid size-9 place-items-center rounded-lg bg-primary/10 text-primary">
          <LayersIcon className="size-4" />
        </div>
        <CardTitle>How it works</CardTitle>
        <CardDescription>
          Layers, page types, result shapes, caching and the security boundary.
        </CardDescription>
      </CardHeader>
    </Card>
  </Link>
  <Link to="/sdk/storefront/checkout" className="group">
    <Card className="h-full transition-colors group-hover:border-primary/40">
      <CardHeader>
        <div className="mb-2 grid size-9 place-items-center rounded-lg bg-primary/10 text-primary">
          <ShoppingCartIcon className="size-4" />
        </div>
        <CardTitle>Basket and checkout</CardTitle>
        <CardDescription>
          Place an order, verify a phone, track conversions and abandonment.
        </CardDescription>
      </CardHeader>
    </Card>
  </Link>
</div>

## Who this is for

| If you are… | Start with |
| --- | --- |
| New to Wocart | [Quick start](/sdk/storefront/quickstart) |
| Building a custom Astro storefront for one store | [Quick start](/sdk/storefront/quickstart), then [Astro actions and routes](/sdk/storefront/astro) |
| Making an editable theme | The [theme starter](/sdk/theme/starter), then this SDK for the commerce data |
| Looking for one method or type | The [API reference](/sdk/storefront/reference/README) |

The guide begins with one working page and adds one area at a time. You can
stop when your storefront does what you need.

## What the SDK gives you

- **Typed reads.** Products, categories, pages, menus, rates and config arrive
  as the shapes the server validated.
- **Predictable failures.** Reads resolve to `null`, `[]` or `{}` and report
  the cause through `onError`. Writes return a result you can branch on.
- **A browser-safe root.** The root entry has no client factory and no API key.
  Browser code imports it freely; the key stays on the server.
- **Astro adapters.** Same-origin routes, the place-order form engine and the
  middleware that renders a refused form are ready to wire.
- **Browser helpers.** The basket store, OTP state machine, image URLs for any
  media host, money formatting and the store's WhatsApp link are part of the
  package.

## What you install

```bash
npm install --save-exact @wocart/storefront@3.1.0
npm install zod
```

`zod` 4.x is a peer dependency. The package is ESM-only and its tooling needs
Node 22.12 or newer. `@wocart/storefront` 3.x reads platform v7: a store
updates its platform and its storefront together. The helpers under
`@wocart/storefront/astro` are written for Astro 7; the rest of the package
does not import Astro.

## Four imports, one boundary

| Import | Runs in | What it holds |
| --- | --- | --- |
| `@wocart/storefront` | Browser and server | Types, money and image helpers, reference data, basket, OTP machine, route paths, Meta payloads |
| `@wocart/storefront/server` | Server only | `createStoreClient`, preview and revalidation checks |
| `@wocart/storefront/astro` | Server only | `resolveStoreRequest`, `createStorefrontRoutes`, `createProxyEndpoint`, `placeOrderInput`, `executePlaceOrder`, `runFormAction`, `lookupOrder`, `notFound` |
| `@wocart/storefront/review-media` | Browser only | Photo resizing and voice recording for a review form |

<Callout type="caution" title="The store key has one home">
`@wocart/storefront/server` holds the store API key. Never import it from a
browser script, island or public variable. Browser code calls your own
same-origin routes, and those routes call the SDK on the server.
</Callout>

## What the client covers

| Namespace | Use it for |
| --- | --- |
| `config` | Store identity, languages, checkout policy and feature flags |
| `products` | Product lists, product detail and reviews |
| `collections` | A merchant's curated product lists and collection pages |
| `categories` | Catalog navigation |
| `pages` | Legal and CMS pages, landing pages |
| `menus` | The store's navigation menus |
| `pageData` | The saved page document for an editable theme |
| `shipping` | Default delivery prices per wilaya |
| `geo` | Wilayas and communes |
| `cart` | Server re-pricing, coupons and delivery quotes |
| `orders` | Order creation, OTP, abandoned checkout and tracking |

## What it does not do

The SDK does not render pages, store the browser's basket on the server,
upload images, write page documents, or decide a theme's layout, copy and
motion. It also does not make a stale browser price trustworthy.

Commerce rules live in the server. If a feature needs a new rule, change the
server contract first, then use it here.

## Guide map

| Page | What it covers |
| --- | --- |
| [Quick start](/sdk/storefront/quickstart) | Install, create the client, render a catalog and a product page |
| [How it works](/sdk/storefront/how-it-works) | Layers, page types, results, caching and the security boundary |
| [Store config and languages](/sdk/storefront/config) | Store settings, checkout policy, localization and theme text |
| [Products and collections](/sdk/storefront/catalog) | Lists, detail, variants, offers, quantity pricing and categories |
| [Reviews](/sdk/storefront/reviews) | Read reviews, prove a purchase, upload media and submit |
| [Pages and menus](/sdk/storefront/content) | Legal pages, navigation, landing pages and saved page documents |
| [Basket and quotes](/sdk/storefront/basket) | The browser basket, server validation, coupons and free delivery |
| [Checkout and OTP](/sdk/storefront/checkout) | Place an order, verify a phone, track conversions and abandonment |
| [Delivery and geography](/sdk/storefront/delivery) | Default rates, real quotes, wilayas and communes |
| [Money, images, WhatsApp and Meta events](/sdk/storefront/presentation) | Display helpers and browser events that stay consistent |
| [Astro actions and routes](/sdk/storefront/astro) | Form actions, middleware and the same-origin API |
| [Preview and revalidation](/sdk/storefront/preview) | Draft previews and instant publish for editable themes |
| [Testing a storefront](/sdk/storefront/testing) | What to test, the definition of done and common mistakes |
| [Public API surface](/sdk/storefront/api) | Every export per entry point, the client namespaces and the schemas |

The [API reference](/sdk/storefront/reference/README) is generated from the
published TypeScript declarations. This guide follows `@wocart/storefront`
3.1.0.