\n\n# @useinsider/guido\n\n[](http://coverus.internal.dataforce/app/project/github/useinsider/guido)\n\nGuido is a Vue 2 + TypeScript wrapper for the Stripo Email Editor plugin. Easily embed the professional email editor in your Vue applications with a clean, type-safe configuration.\n\n## Installation\n\n```bash\nnpm install @useinsider/guido\n```\n\n### Prerequisites\n\nYour project needs:\n- Vue 2.7+\n- Pinia (state management)\n\nAdd these to your bundler config to optimize dependencies:\n\n**Webpack** (`webpack.config.js` or `vue.config.js`):\n```js\nshared: {\n vue: { singleton: true },\n pinia: { singleton: true },\n},\n```\n\n**Vite** (`vite.config.js`):\n```js\nresolve: {\n dedupe: ['vue', 'pinia'],\n},\n```\n\n---\n\n## Quick Start\n\n```vue\n\n \n\n\n\n```\n\n---\n\n## Configuration\n\nGuido uses a single, validated `config` prop organized by domain:\n\n```typescript\nimport type { GuidoConfigInput } from '@useinsider/guido';\n\nconst config: GuidoConfigInput = {\n // Required: Identity\n identity: {\n templateId: string, // Required - Template identifier\n userId: string, // Required - User identifier\n variationId?: string, // Optional - A/B test variation\n campaignId?: string, // Optional - Numeric campaign id; absent for templates/modules\n templateLibraryId?: string, // Optional - Numeric template-library id; absent for campaigns/modules\n },\n\n // Required: Partner\n partner: {\n name: string, // Required - Partner name\n productType?: number, // Optional - Default: 60 (Email)\n messageType?: number, // Optional - Default: 1 (Promotional)\n username?: string, // Optional - Default: 'Guido User'\n },\n\n // Optional: Template content\n template?: {\n html?: string,\n css?: string,\n preselectedDynamicContent?: DynamicContent[],\n // Partner-keyed catalog of the account's dynamic-content attributes, e.g.\n // { [partnerName]: [{ text, value, children }] } (architect is multi-partner).\n // Guido flattens the active (first) partner's leaf attributes and uses them to\n // repair label-form tokens (`{{ Phone Number }}` -> `{{phone_number}}`) in\n // dropped saved modules; an unresolvable token raises a single warning toaster\n // (translation key `dynamic-content.unresolved-attributes-on-drop`, registered\n // host-side). Omit it and the repair is a silent no-op. Default: {}.\n dynamicContentList?: DynamicContentList,\n selectedUnsubscribePages?: number[],\n forceRecreate?: boolean, // Default: false - Force recreate template in Stripo storage\n migration?: {\n // Legacy block configs keyed by block ID. Consumed once by the migrator\n // when upgrading templates authored with v1 block formats. See the\n // \"Template Migration\" section below.\n recommendationConfigs?: Record,\n },\n },\n\n // Optional: Editor settings\n editor?: {\n locale?: string, // Default: 'en'\n translationsPath?: string, // Default: first locale registered on window.trans\n migrationDate?: number, // Stripo migration timestamp\n emailHeader?: {\n senderName?: string,\n subject?: string,\n },\n savedModulesFolderName?: string, // Default: 'savedModules' - folder name for user-saved modules\n defaultModulesFolderName?: string, // Default: 'defaultModules' - folder name for default/prebuilt modules\n },\n\n // Optional: UI settings\n ui?: {\n showHeader?: boolean, // Default: true\n backButtonLabel?: string,\n },\n\n // Optional: Feature toggles (defaults apply once initialized — see `ready` prop below)\n features?: {\n dynamicContent?: boolean, // Default: true\n saveAsTemplate?: boolean, // Default: true\n versionHistory?: boolean, // Default: true\n testMessage?: boolean, // Default: true\n displayConditions?: boolean, // Default: true\n unsubscribe?: boolean, // Default: true\n modulesDisabled?: boolean, // Default: false - Disable modules panel\n liquidSyntax?: boolean, // Default: false - Enable Liquid template syntax\n autosave?: boolean, // Default: false - Show the Auto Save toggle in the header. See wiki/AUTOSAVE.md.\n allowlistEnabled?: boolean, // Default: false - Pre-save domain-allowlist check (opt-in). Guido self-serves the block toaster (role lookup, deep-link, copy from window.trans).\n allowSaveWithErrors?: boolean, // Default: true - Allow the validation drawer's \"Save and Continue\" soft-save. Set false to hard-block invalid saves (transactional + unsubscribe pages).\n reusableRecommendationStrategy?: boolean, // Default: false - Assign an RRS strategy to recommendation blocks instead of per-block algorithm/filters/shuffle/product-count settings.\n },\n\n // Optional: Callbacks\n callbacks?: {\n externalValidation?: (data: SavedTemplateDetails) => Promise, // Return false to cancel save\n },\n\n // Optional: Block configuration\n blocks?: {\n excludeDefaults?: DefaultBlockType[],\n includeCustoms?: CustomBlockType[],\n },\n\n // Optional: HTML compiler\n compiler?: {\n customRules?: CompilerRule[],\n ignoreDefaultRules?: boolean, // Default: false\n },\n};\n```\n\n### `identity` ids\n\n`templateId` is the editor's **document** identity (a uuid / Stripo doc id) and never addresses a\nbackend resource. `campaignId` and `templateLibraryId` are the **numeric** ids of the surface the\neditor was opened on, and they are what Guido uses to resolve host-scoped endpoints — most visibly\nwhen converting a legacy recommendation block into a reusable strategy.\n\n| Surface | `campaignId` | `templateLibraryId` |\n|---------|--------------|---------------------|\n| Campaign editor | the campaign id | absent |\n| Saved template editor | absent | the template-library id |\n| Module editor / unsaved template | absent | absent |\n\nPass only the one that applies. A campaign id takes precedence when both are present, and when\nneither is supplied Guido falls back to campaign scope — so a module keeps working unchanged.\n\n### `ready` prop\n\n```vue\n\n```\n\nOptional, defaults to `true` — existing call sites need no change. Pass `false` to mount\nGuido *before* `config` is fetched: it preloads the ~8 MB editor runtime immediately and\ndefers config validation + editor init until `ready` flips to `true`.\n\n`config` must be final at that flip (later mutations don't re-initialize), and the flip is\none-way. While `ready` is `false` every `features` toggle reads as disabled.\n\n---\n\n## Events\n\n| Event | Payload | Description |\n|-------|---------|-------------|\n| `ready` | - | Editor is loaded and ready |\n| `dynamic-content:open` | `DynamicContent \\| null` | User wants to insert dynamic content |\n| `back` | - | Back button clicked |\n| `save:start` | - | Save process started |\n| `save:complete` | `SavedTemplateDetails` | Save completed successfully (includes `metadata`) |\n| `on-change` | - | Template was modified |\n| `test-email:click` | - | Test email button clicked |\n| `onboarding-finished` | - | Onboarding popup dismissed |\n\n### `save:complete` Payload\n\nThe `save:complete` event emits a `SavedTemplateDetails` object containing the compiled template data along with editor `metadata`:\n\n```typescript\ninterface SavedTemplateDetails {\n dynamicContentList: DynamicContent[];\n compiledHtml: string;\n rawHtml: string;\n css: string;\n ampHtml: string;\n ampErrors: string[];\n modules: number[];\n recommendation: {\n campaignUrls: Record;\n configs: Record;\n };\n unsubscribe: {\n status: boolean;\n config: number[];\n };\n metadata: Metadata;\n silent: boolean; // true when triggered by autosave, false when user clicked Save\n}\n\ninterface Metadata {\n emailId: string;\n partnerName?: string;\n productType?: number;\n userId: string;\n username?: string;\n savedModulesFolderName?: string;\n defaultModulesFolderName?: string;\n}\n```\n\n> ⚠️ **Important:** The `metadata` object in the `save:complete` payload must be passed directly into your `templateConfig` / `stripoConfig` object while saving. This ensures the email-service receives the correct version of sync modules features\n\n---\n\n## Exposed Methods\n\n```typescript\nconst guidoRef = ref | null>(null);\n\n// Insert dynamic content\nguidoRef.value?.dynamicContent.insert({\n text: 'Display Name',\n value: 'variable_name',\n fallback: 'Default Value',\n});\n\n// Close dynamic content modal\nguidoRef.value?.dynamicContent.close();\n\n// Silent save (no UI feedback)\nguidoRef.value?.saveSilent();\n\n// Control the editor's full-screen loader for flows Guido can't see.\n// Guido shows the loader automatically for manual saves; use setLoading()\n// when your app keeps the editor mounted after a save and needs to drive it:\n\n// • Release the loader when a save is blocked/rejected and you stay in the\n// editor (e.g. a post-save domain-allowlist error you surface in place),\n// so the editor isn't left stuck on the spinner:\nguidoRef.value?.setLoading(false);\n\n// • Raise the loader to cover a host-initiated navigation (e.g. a\n// save-and-leave flow) so the editor doesn't flash before your route\n// changes — release it again if that save turns out to be blocked:\nguidoRef.value?.setLoading(true);\n```\n\n---\n\n## Block Configuration\n\n### Default Blocks (can be excluded)\n\n```typescript\ntype DefaultBlockType =\n | 'amp-accordion'\n | 'amp-carousel'\n | 'amp-form-controls'\n | 'banner-block'\n | 'button-block'\n | 'html-block'\n | 'image-block'\n | 'menu-block'\n | 'social-block'\n | 'spacer-block'\n | 'text-block'\n | 'timer-block'\n | 'video-block';\n```\n\n### Custom Blocks (opt-in)\n\n```typescript\ntype CustomBlockType =\n | 'dynamic-content'\n | 'checkbox-block'\n | 'radio-button-block'\n | 'recommendation-block'\n | 'unsubscribe-block'\n | 'coupon-block'\n | 'items-block';\n```\n\n### Examples\n\n```typescript\n// Exclude specific default blocks\nconst config: GuidoConfigInput = {\n identity: { templateId: 'tpl-123', userId: 'user-456' },\n partner: { name: 'partner' },\n blocks: {\n excludeDefaults: ['timer-block', 'video-block'],\n },\n};\n\n// Include custom blocks\nconst config: GuidoConfigInput = {\n identity: { templateId: 'tpl-123', userId: 'user-456' },\n partner: { name: 'partner' },\n blocks: {\n includeCustoms: ['recommendation-block', 'coupon-block', 'dynamic-content'],\n },\n};\n```\n\n---\n\n## Module Folder Configuration\n\nCustomize the Stripo module folder names for saved and default modules. These values are passed to Stripo metadata and the dynamic folder paths are constructed in the Stripo plugin panel configuration.\n\n```typescript\nconst config: GuidoConfigInput = {\n identity: { templateId: 'tpl-123', userId: 'user-456' },\n partner: { name: 'acme' },\n editor: {\n // Folder name for user-saved modules\n savedModulesFolderName: 'savedModules',\n\n // Folder name for default/prebuilt modules\n defaultModulesFolderName: 'defaultModules',\n },\n};\n```\n\n### Default Values\n\n| Config Option | Default Value |\n|--------------|---------------|\n| `savedModulesFolderName` | `'savedModules'` |\n| `defaultModulesFolderName` | `'defaultModules'` |\n\n> **Note:** The actual folder paths (e.g., `guido_acme_savedModules`) are configured in the Stripo plugin panel using variable substitution like `${savedModulesFolderName}`.\n\n---\n\n## Autosave\n\nGuido ships an opt-in **autosave** that saves on a 3-minute interval and when the user leaves the tab. Enable it with the `features.autosave` feature flag — this **shows an \"Auto Save\" toggle in the editor header**; the end user switches autosave on per session.\n\n```typescript\nconst config: GuidoConfigInput = {\n identity: { templateId: 'tpl-123', userId: 'user-456' },\n partner: { name: 'partner' },\n features: {\n autosave: true, // Default: false — shows the Auto Save toggle in the header\n },\n};\n```\n\n- Default is `false` — integrations see no change unless they opt in.\n- Autosave reuses the same save pipeline as the Save button, so your existing `@save:complete` handler receives autosave output identically to a manual save. No new events or callbacks.\n- Toggle state is **session-only** (Pinia) — resets to OFF on reload.\n\nFor a deep dive on triggers, guards, and limitations, see **[wiki/AUTOSAVE.md](wiki/AUTOSAVE.md)**.\n\n---\n\n## Template Migration\n\nWhen a template was authored with **v1 block formats** (notably the legacy recommendation block), Guido needs additional context that cannot be recovered from the saved HTML alone — things like filter rules, recommendation strategies, currency settings, locale, and pinned product IDs.\n\nPass that context once via `template.migration` when loading the template. The migrator consumes it during initial render to upgrade legacy blocks to the current format. After migration, the field has no effect on editor behavior — you can keep passing it (it's idempotent on already-migrated templates) or omit it.\n\n> **When to provide this:** Only when loading templates created before the v2 recommendation block was rolled out. New templates do not need it.\n\n### `recommendationConfigs`\n\nA dictionary keyed by the legacy block's element ID. Each entry preserves the v1 block's runtime config so the migrator can hydrate the upgraded block.\n\n```typescript\nconst config: GuidoConfigInput = {\n identity: { templateId: 'tpl-123', userId: 'user-456' },\n partner: { name: 'acme' },\n template: {\n html: legacyHtml,\n css: legacyCss,\n migration: {\n recommendationConfigs: {\n // Key = legacy block element id (also present as `id` in the entry)\n 'recommendation-1700000000000': {\n id: 1700000000000,\n // Filter-driven block — productIds is empty, filters/strategy drive selection\n productIds: [],\n filters: [{ field: 'category', op: 'eq', value: 'shoes' }],\n strategy: 'newArrivals',\n shuffleProducts: false,\n sendProductRequestFlag: true,\n\n // Display & locale\n currency: 'EUR',\n currencySettings: { decimal: ',', thousand: '.', alignment: 'left' },\n language: 'nl_NL',\n decimalCount: 2,\n\n // Layout\n cardsInRow: 2,\n orientation: 'vertical',\n textTrimming: true,\n unresponsive: false,\n mobileLeftPadding: 0,\n mobileRightPadding: 0,\n\n // Snapshot of products as they were rendered in the legacy email\n recommendedProducts: [/* ...legacy product objects... */],\n },\n },\n },\n },\n};\n```\n\nAll fields on a `LegacyRecommendationConfig` entry are optional — pass whatever your storage layer has for that block. Unknown keys are preserved and forwarded to the migrator unchanged, so partner-specific extensions continue to round-trip.\n\n### Field reference\n\n| Field | Type | Purpose |\n|-------|------|---------|\n| `id` | `number` | Block ID (matches the dictionary key and legacy HTML element id) |\n| `productIds` | `unknown[]` | Pinned product IDs — empty when filter-driven |\n| `filters` | `unknown[]` | Filter rules driving product selection |\n| `strategy` | `string` | Recommendation strategy key (e.g. `'newArrivals'`) |\n| `shuffleProducts` | `boolean` | Whether to randomize product order |\n| `sendProductRequestFlag` | `boolean` | Whether the block requested live products at send time |\n| `currency` | `string` | Currency code (e.g. `'EUR'`) |\n| `currencySettings` | `unknown` | Separators, alignment, decimals |\n| `language` | `string` | Locale (e.g. `'nl_NL'`) |\n| `decimalCount` | `string \\| number` | Decimal places for price display |\n| `cardsInRow` | `number` | Product cards per row |\n| `orientation` | `'vertical' \\| 'horizontal'` | Layout orientation |\n| `size` | `string \\| number` | Size variant marker (legacy) |\n| `verticalResponsiveness` | `boolean` | Vertical responsiveness flag (legacy `size=1` variants) |\n| `blockType` | `string` | Block type marker used by some legacy variants |\n| `textTrimming` | `boolean` | Whether long text is trimmed |\n| `unresponsive` | `boolean` | Disable responsive scaling |\n| `mobileLeftPadding` / `mobileRightPadding` | `number` | Mobile-only horizontal padding |\n| `recommendedProducts` | `unknown[]` | Snapshot of products rendered by the legacy block |\n\n> **Note on data shape:** The schema uses `looseObject` because v1 partner data shapes vary across deployments. Some entries carry `verticalResponsiveness`, others carry `blockType` / `orientation` / `size`. Pass whatever you have — the migrator will use what it recognizes and preserve the rest.\n\n---\n\n## HTML Compiler Rules\n\nAdd custom rules to transform HTML during export:\n\n```typescript\nconst config: GuidoConfigInput = {\n identity: { templateId: 'tpl-123', userId: 'user-456' },\n partner: { name: 'partner' },\n compiler: {\n customRules: [\n // Replace rule\n {\n id: 'replace-domain',\n type: 'replace',\n search: 'old-domain.com',\n replacement: 'new-domain.com',\n priority: 10,\n },\n // Regex rule\n {\n id: 'remove-comments',\n type: 'regex',\n pattern: '',\n replacement: '',\n flags: 'g',\n priority: 20,\n },\n // Custom processor\n {\n id: 'add-tracking',\n type: 'custom',\n processor: (html) => html.replace('
![\"Guido](\"https://web-image.useinsider.com/guido/defaultImageLibrary/iUH0liTK0d2YDsVB5LDN1770169173.jpg\")
\n \n