@one-million-lines/email-builder 0.2.2 → 0.3.0

package/README.md

@@ -155,6 +155,49 @@ response is validated with Zod before it is applied. See
 [`src/ai/README.md`](./src/ai/README.md) and
 [`backend/README.md`](./backend/README.md).
 
+### Product search
+
+Connect product cards to your catalog. When a product provider is configured, a
+**Find** button appears on any product grid (and a search icon on each card).
+Searching opens a modal, previews the returned product, and — on **Save** —
+populates the card's fields (which stay fully editable afterwards).
+
+```tsx
+<EmailBuilder productEndpoint="http://localhost:3001/products/search" />
+```
+
+```ts
+import { registerPlugin, productSearchPlugin } from "@one-million-lines/email-builder";
+registerPlugin(productSearchPlugin({ endpoint: "http://localhost:3001/products/search" }));
+```
+
+The demo backend in [`backend/`](./backend) ships a `/products/search` endpoint
+over a small in-memory catalog. Product fields are `title`, `final_price`,
+`old_price` (optional), `description`, `link`, `image` and `stars` (optional).
+See [`src/plugins/productSearch/README.md`](./src/plugins/productSearch/README.md)
+for the wire protocol and response mapping.
+
+### Voucher select
+
+Let users pick a discount code from your backend instead of typing it. When a
+voucher provider is configured, selecting a **voucher block** (the built-in
+**Voucher Code** module, or any module with a `voucherCode` text element) shows a
+**Select voucher** dropdown that fills the code. The list is fetched once and
+cached (lazily, or eagerly with `preload`).
+
+```tsx
+<EmailBuilder voucherEndpoint="http://localhost:3001/vouchers" />
+```
+
+```ts
+import { registerPlugin, voucherPlugin } from "@one-million-lines/email-builder";
+registerPlugin(voucherPlugin({ endpoint: "http://localhost:3001/vouchers", preload: true }));
+```
+
+The demo backend ships a `GET /vouchers` endpoint. See
+[`src/plugins/voucherSelect/README.md`](./src/plugins/voucherSelect/README.md)
+for the wire protocol and response mapping.
+
 ### Styling & isolation
 
 The stylesheet at `@one-million-lines/email-builder/styles.css` is designed to

package/dist/core/plugins.d.ts

@@ -7,13 +7,50 @@ export interface AssetProvider {
         alt?: string;
     }>;
 }
+/**
+ * A single product returned by a {@link ProductProvider} search. Field names
+ * match the builder's `Product` model so results drop straight into a card.
+ */
+export interface ProductSearchResult {
+    name: string;
+    finalPrice: string;
+    oldPrice?: string;
+    description?: string;
+    link?: string;
+    image?: string;
+    imageAlt?: string;
+    stars?: number;
+    /** Optional external identifier echoed back from the backend. */
+    sku?: string;
+}
+export interface ProductProvider {
+    /** Look up a single product for a free-text query. Resolves null if none. */
+    search: (query: string) => Promise<ProductSearchResult | null>;
+}
+/** A discount/voucher entry returned by a {@link VoucherProvider}. */
+export interface Voucher {
+    /** Stable identifier (used to remember the selection). */
+    id: string;
+    /** Human label shown in the select dropdown. */
+    title: string;
+    /** The code (or merge tag) inserted into the voucher block. */
+    code: string;
+    /** Optional longer description. */
+    description?: string;
+}
+export interface VoucherProvider {
+    /** Load the list of vouchers to choose from. */
+    list: () => Promise<Voucher[]>;
+}
 export interface BuilderHandle {
     registerModule: (def: ModuleDefinition) => void;
     registerTheme: (theme: Theme) => void;
     registerAssetProvider: (provider: AssetProvider) => void;
+    registerProductProvider: (provider: ProductProvider) => void;
+    registerVoucherProvider: (provider: VoucherProvider) => void;
     setAIProvider: (provider: AIProvider) => void;
 }
-export type PluginType = "modules" | "themes" | "asset-provider" | "ai-provider";
+export type PluginType = "modules" | "themes" | "asset-provider" | "product-provider" | "voucher-provider" | "ai-provider";
 export interface Plugin {
     name: string;
     type: PluginType;
@@ -23,4 +60,6 @@ export declare const builder: BuilderHandle;
 export declare function registerPlugin(plugin: Plugin): void;
 export declare function getRegisteredThemes(): Theme[];
 export declare function getAssetProvider(): AssetProvider | null;
+export declare function getProductProvider(): ProductProvider | null;
+export declare function getVoucherProvider(): VoucherProvider | null;
 export declare function getAIProvider(): AIProvider | null;

package/dist/core/types.d.ts

@@ -18,7 +18,7 @@ export interface BaseStyle {
 export interface TextElement {
     id: string;
     type: "text";
-    role?: "headline" | "subheadline" | "body" | "caption";
+    role?: "headline" | "subheadline" | "body" | "caption" | "voucherCode";
     content: string;
     style?: BaseStyle & {
         fontFamily?: string;
@@ -79,6 +79,8 @@ export interface Product {
     description?: string;
     link?: string;
     buttonLabel?: string;
+    /** Optional 0–5 rating. Rendered as star glyphs when the grid shows stars. */
+    stars?: number;
 }
 export interface ProductGridElement {
     id: string;
@@ -88,6 +90,8 @@ export interface ProductGridElement {
     showOldPrice: boolean;
     showButton: boolean;
     showDescription: boolean;
+    /** Show the star rating on each product card. Optional for back-compat. */
+    showStars?: boolean;
     buttonLabel?: string;
     style?: BaseStyle & {
         nameColor?: string;

package/dist/core/utils.d.ts

@@ -1,3 +1,10 @@
 export declare function uid(prefix?: string): string;
 export declare function escapeHtml(s: string): string;
 export declare function safeUrl(url: string | undefined): string;
+/** Default gold used for product star ratings. */
+export declare const STAR_COLOR = "#F5A623";
+/**
+ * Build a 5-glyph star string for a 0–5 rating (rounded to the nearest whole
+ * star). Uses ★ (full) and ☆ (empty) so it renders in any email client.
+ */
+export declare function starGlyphs(rating: number): string;

package/dist/core/validation.d.ts

@@ -44,11 +44,13 @@ export declare const moduleSchema: z.ZodObject<{
             description: z.ZodOptional<z.ZodString>;
             link: z.ZodOptional<z.ZodString>;
             buttonLabel: z.ZodOptional<z.ZodString>;
+            stars: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strip>>;
         columns: z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<3>]>;
         showOldPrice: z.ZodBoolean;
         showButton: z.ZodBoolean;
         showDescription: z.ZodBoolean;
+        showStars: z.ZodOptional<z.ZodBoolean>;
         buttonLabel: z.ZodOptional<z.ZodString>;
         style: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodRecord<z.ZodString, z.ZodAny>]>>>;
     }, z.core.$strip>], "type">>;
@@ -130,11 +132,13 @@ export declare const documentSchema: z.ZodObject<{
                 description: z.ZodOptional<z.ZodString>;
                 link: z.ZodOptional<z.ZodString>;
                 buttonLabel: z.ZodOptional<z.ZodString>;
+                stars: z.ZodOptional<z.ZodNumber>;
             }, z.core.$strip>>;
             columns: z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<3>]>;
             showOldPrice: z.ZodBoolean;
             showButton: z.ZodBoolean;
             showDescription: z.ZodBoolean;
+            showStars: z.ZodOptional<z.ZodBoolean>;
             buttonLabel: z.ZodOptional<z.ZodString>;
             style: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodRecord<z.ZodString, z.ZodAny>]>>>;
         }, z.core.$strip>], "type">>;