@greatstore/cli 0.1.1 → 0.1.3

package/dist/gs-skill/references/structured-content.md

@@ -0,0 +1,252 @@
+# `generateStructuredContent` deep dive
+
+AI-generated, catalog-grounded JSON for UI you render yourself — the chat
+panel is not involved.
+
+```js
+const data = await window.GreatStore.generateStructuredContent(schema, prompt);
+```
+
+- `schema` — a JSON Schema describing the output (or a Zod schema exposing
+  `.toJSONSchema()`).
+- `prompt` — what to generate.
+- Resolves to **the generated JSON object itself**, matching the schema.
+  Rejects with an `Error` on any failure.
+
+Code samples here are framework-free reference implementations — re-express
+them in the host repo's framework (React, Vue, Shopify Liquid, …) rather
+than retrofitting them as-is.
+
+## The rules that make it work well
+
+Each is unpacked in the sections below; this is the checklist.
+
+1. **Top level must be an object.** Want a list? Wrap it:
+   `{ type: "object", properties: { items: { type: "array", … } }, required: ["items"] }`.
+2. **Steer with the prompt, not schema `description`s** — free-text schema
+   fields are stripped before the AI sees them. Use self-explanatory
+   property names (`benefitHeadline`, not `text1`).
+3. **Only `require` what's guaranteed.** `required` is strictly enforced; if
+   the catalog can't ground a required field the whole call can fail. Require
+   structural fields, keep per-product details (image URLs, prices) optional,
+   and make rendering tolerate missing values.
+4. **Point, don't paste.** GreatStore researches the store's live catalog on
+   its own — name the entity (`` `…the product "${productName}" (SKU ${sku})` ``)
+   and let it look the facts up. Don't fetch specs/prices/descriptions
+   yourself and paste them into the prompt. The one thing it *can't* see is
+   your page, so page-only context (which page the shopper is on, what the
+   section is for) does belong in the prompt.
+5. **Research is bounded by the store's connectors — validate before you
+   build.** The AI can only look up what the store's MCP connectors actually
+   provide. Ask for something outside them — currency conversion, live
+   shipping rates, review data the store never wired up — and it has nothing
+   to ground on, so it will decline, omit… or hallucinate. Before writing a
+   prompt or schema that depends on a data capability, run `gs connectors`
+   (and `gs connectors health`, [store-admin.md](store-admin.md)) and confirm
+   a connector for it exists; if it doesn't, don't ask for it.
+6. **Responses are cached** for up to ~24h per page + prompt + schema —
+   shared across anonymous visitors, per-shopper for identified ones. Keep
+   prompts deterministic per page — no timestamps, random values, or
+   per-visitor data (GreatStore already knows who the shopper is; see below).
+7. **Progressive enhancement, always.** Generate after the page renders into
+   a hidden container, reveal on success, leave the fallback on error. Render
+   generated strings via `textContent`, never `innerHTML`.
+8. **One rich call beats many small ones** — there's a per-visitor rate limit
+   (~20 requests/minute); fetch multiple surfaces with one combined schema.
+
+## What actually happens
+
+1. The SDK posts your schema + prompt to the store's GreatStore endpoint,
+   along with the current **page URL and page title** (sent automatically —
+   you don't pass them, and you can't override them).
+2. GreatStore first **researches**: it looks up real data from the store's
+   live catalog (products, prices, availability, store info) using read-only
+   lookups. The page URL/title serve as hints about which product or category
+   to look up — they are *not* treated as a source of product data, and the
+   page's DOM is never read. Research happens on GreatStore's side — your
+   prompt only needs to *point* it at the right SKU, product, or collection,
+   not carry the material. Its reach is exactly the store's MCP connectors:
+   validate with `gs connectors` ([store-admin.md](store-admin.md)) that a
+   connector for the data you want actually exists before you build on it —
+   research can't exceed the wired-up connectors, and prompts that assume
+   otherwise invite hallucinated filler.
+3. The AI then fills your schema from the researched data, under a strict
+   grounding contract: it must not invent product names, prices, images, IDs,
+   or descriptions. Fields it can't ground are omitted or `null`. For an
+   identified shopper this step also sees their shopper profile — the same
+   identity the chat assistant has — so the output can be subtly personalized
+   without you passing anything about the visitor.
+4. The output is validated against your schema (with internal retries) before
+   being returned and cached.
+
+GreatStore already knows who's reading: identity rides the request the same
+way it does for chat, and responses for identified shoppers are cached just
+for them (anonymous visitors share one entry). The practical consequence:
+never put shopper data in the prompt — it's redundant, and it poisons the
+cache key.
+
+## Schema support
+
+Top level **must describe an object**: `type: "object"` (or a bare
+`properties` / `anyOf`). To get a list, wrap it in an object property.
+
+Supported keywords (anything else is tolerated but ignored):
+
+- Types: `object`, `array`, `string`, `number`, `integer`, `boolean`, `null`
+- Structure: `properties`, `required`, `items`, `additionalProperties`
+- Choice: `enum`, `const`, `anyOf`, `nullable`
+- Constraints: `minimum`, `maximum`, `minLength`, `maxLength`, `minItems`,
+  `maxItems`, `pattern`, `format`, `default`
+
+Validation of the output is real: `required` is enforced, `enum`/`const`
+must match, numeric and length bounds are checked, and
+`additionalProperties: false` rejects extra keys. Constraints are therefore a
+*tool* — `maxItems: 4` reliably caps a list, `enum` reliably restricts a
+field — but every constraint is also a way for generation to fail, so apply
+them only where you'd rather have no content than non-conforming content.
+
+Zod schemas (or anything with a `.toJSONSchema()` method) are accepted and
+converted automatically.
+
+### Free-text schema fields are stripped
+
+`description`, `title`, and `example` are removed from the schema before the
+AI sees it (they're a prompt-injection surface, so they're filtered
+server-side). Consequences:
+
+- Schema descriptions **cannot** steer generation. All steering lives in the
+  prompt string.
+- Property *names* are the only in-schema signal of intent — make them
+  self-documenting: `ctaLabel`, `warmthRating`, `priceJustification`.
+
+## Prompting guide
+
+The prompt is the entire instruction channel. A good prompt states, in order:
+
+1. **Context** — what page/situation the shopper is in, naming the entity so
+   research targets the right thing (the AI can't see your DOM, so identify
+   it explicitly):
+   `The shopper is viewing the product "Aurora Down Parka" (SKU AUR-021) on its product page.`
+2. **Task** — what to generate, mapped loosely onto your schema's fields:
+   `Write a heading and 3 reasons to love it; each reason has a short title and one supporting sentence.`
+3. **Grounding expectations** — what store data to draw on:
+   `Base every claim on the product's real materials, features, and price.`
+4. **Voice** — tone and constraints:
+   `Warm and concrete. No exclamation marks, no generic marketing filler.`
+
+Note what's *not* in that prompt: no pasted specs, prices, or descriptions.
+Pointing at the SKU is enough — GreatStore researches the rest itself, from
+data that's live rather than whatever was true when you wrote the prompt.
+
+Anti-patterns:
+
+- **Pasting researched material into the prompt** (specs, prices,
+  descriptions you fetched from your platform's API). GreatStore researches
+  the live catalog itself — point it at the SKU/product/collection and let
+  it look things up. Pasted facts go stale, bloat the cache key, and compete
+  with the fresher data research returns.
+- **Per-visitor or per-moment data in the prompt** (names, cart contents,
+  timestamps, `Math.random()`): destroys caching, so every visitor pays full
+  generation latency and the store pays for every call — and it's redundant,
+  because GreatStore already knows the shopper and personalizes for
+  identified ones server-side. If you need per-shopper *interaction*, that's
+  what `sendMessage` and the chat panel are for.
+- **Asking for data no connector provides** ("convert the price to EUR",
+  "estimate delivery to the shopper's city"): research can't exceed the
+  store's MCP connectors, and the AI may hallucinate plausible-looking
+  values rather than leave the field empty. Validate first — `gs connectors`
+  shows what's wired up ([store-admin.md](store-admin.md)); if there's no
+  connector for it, don't ask for it.
+- **Asking it to read the page** ("summarize the reviews shown below") — it
+  can't. Page-only data (review snippets, UGC, things that exist nowhere but
+  the DOM) is the one kind worth inlining — keep it stable per page so
+  caching still works.
+- **Asking for minute-fresh operational data** (exact live stock counts,
+  delivery countdowns). Even when a connector could answer, responses cache
+  for up to ~24h — display operational data from your own platform APIs and
+  use GreatStore for *editorial intelligence over the catalog*.
+- **Burying instructions in schema descriptions** — stripped, see above.
+
+## Caching: design for it
+
+Responses are cached server-side for up to **24 hours**, keyed by the
+combination of page URL + page title + prompt + schema. Anonymous visitors
+share one entry per key; identified shoppers each get their own (their
+output may be personalized, so it's only ever served back to them).
+(Tracking query params like `utm_*`/`gclid` and the URL fragment are
+ignored, so ad-tagged visits share the campaign-free page's cache entry.
+Meaningful params like `?product=123` are part of the key.)
+
+Practical consequences:
+
+- **The first render pays, repeats fly.** Expect a few seconds on a cache
+  miss and near-instant responses after — shared across all anonymous
+  traffic, per-shopper for identified traffic (the research underneath is
+  cached briefly and shared, so even those misses are cheaper than cold).
+  Design loading states for the miss case.
+- **Same call on different pages = different content**, automatically — the
+  page URL is in the key and in the AI's hints. A single site-wide snippet
+  with a constant prompt yields per-page content for free.
+- **Content refreshes roughly daily.** Don't build experiences that assume
+  minute-level freshness.
+- **To force different content, change the prompt or schema** (e.g. a
+  campaign variant string that changes weekly — deliberate, low-cardinality
+  variation is fine; per-visitor cardinality is not).
+
+The catalog research underneath is also cached briefly, so several distinct
+surfaces on the same page (different prompts/schemas) stay cheap even on
+cold cache.
+
+## Errors and how to handle them
+
+The promise rejects with `new Error(message)`. The message is
+developer-facing — never render it to shoppers. Cases:
+
+| Case | Message you'll see | Retry? |
+|---|---|---|
+| Bad input (empty prompt, non-object schema) | thrown immediately by the SDK | Fix the call |
+| Invalid schema shape | `Invalid schema: …` | Fix the schema |
+| AI declined the request | `The assistant declined to generate content for this request.` | No — permanent for that prompt/schema. Rework the prompt. |
+| Output couldn't satisfy the schema | `Failed to produce valid structured content` | No — usually `required`/constraints demand data the catalog lacks. Loosen the schema. |
+| Rate limit (~20/min per visitor) | rate-limit message | Later — and consolidate calls |
+| Network / server | varies | Next page load |
+
+The uniform shopper-facing strategy: render into a hidden-by-default
+container, reveal on success, leave hidden (or show your static fallback) on
+any rejection. One `try/catch`, no case analysis needed unless you're
+logging.
+
+## Performance pattern
+
+Fire generation as early as possible without blocking render — top of your
+deferred script, before other work:
+
+```js
+const highlightsPromise = window.GreatStore?.generateStructuredContent
+  ? window.GreatStore.generateStructuredContent(schema, prompt).catch(() => null)
+  : Promise.resolve(null);
+
+// …rest of page setup…
+
+const data = await highlightsPromise;
+if (data) renderHighlights(data);
+```
+
+The `.catch(() => null)` attached immediately avoids unhandled-rejection
+noise while keeping a single render path.
+
+For multiple surfaces on one page, prefer **one call with a combined
+schema** over parallel calls — it's one research pass, one cache entry, and
+no rate-limit pressure:
+
+```js
+const schema = {
+  type: "object",
+  properties: {
+    highlights: { /* … */ },
+    faq:        { /* … */ },
+    crossSell:  { /* … */ },
+  },
+  required: ["highlights"],
+};
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@greatstore/cli",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "CLI for administering GreatStore stores and authoring custom components.",
   "license": "UNLICENSED",
   "type": "module",