@weavour/editor 0.0.0-stage → 0.1.0

package/dist/merge-tags.d.ts

@@ -0,0 +1,26 @@
+/** Public configuration, never recipient values or credentials. */
+export type MergeTag = {
+    id: string;
+    label: string;
+    token: string;
+    kind: 'text' | 'url';
+    description?: string;
+    sampleValue?: string;
+};
+export type MergeTagReference = Pick<MergeTag, 'id' | 'token' | 'kind'>;
+export declare const defaultMergeTags: MergeTag[];
+export declare function validMergeToken(value: unknown): value is string;
+/** Also used for persisted references; these intentionally contain no samples. */
+export declare function mergeTagReferences(value: unknown): MergeTagReference[];
+export declare function parseMergeTags(value: unknown): MergeTag[];
+export declare function resolveMergeTags(saved?: unknown, overrides?: unknown): MergeTag[];
+export declare function safeMergeLink(value: string, tags?: readonly MergeTagReference[]): string | undefined;
+export type MergeTagIssue = {
+    code: 'unavailable_tag' | 'changed_tag' | 'invalid_tag_context';
+    id: string;
+    token: string;
+    location: string;
+};
+export type MergeTagUsage = MergeTagReference & {
+    locations: string[];
+};

package/dist/protocol.d.ts

@@ -0,0 +1,9 @@
+export { parseMergeTags, resolveMergeTags, mergeTagReferences, defaultMergeTags, safeMergeLink, validMergeToken } from './merge-tags.js';
+export { emailDocument, canonicalJson } from './email-document.js';
+export { resolveEditorTheme, readableForeground, editorSurfacePalette, colorContrast } from './editor-theme.js';
+export { editorBlockIds } from './editor-blocks.js';
+export type * from './types.js';
+export declare const PROTOCOL_VERSION = 1;
+export declare const MAX_MESSAGE_BYTES = 2097152;
+/** Only JSON-compatible wire values, with bounded size and nesting. */
+export declare function validMessage(value: unknown): value is Record<string, any>;

package/dist/protocol.js

@@ -0,0 +1,234 @@
+// packages/editor/src/merge-tags.ts
+var defaultMergeTags = [
+  { id: "unsubscribe_url", label: "Unsubscribe link", token: "{{unsubscribe_url}}", kind: "url" },
+  { id: "online_version_url", label: "Online version link", token: "{{online_version_url}}", kind: "url" }
+];
+var control = /[\u0000-\u001f\u007f]/;
+function validMergeToken(value) {
+  return typeof value === "string" && !!value.trim() && value.length <= 200 && !control.test(value) && !/[<>"'`&]/.test(value) && !/^[a-z][a-z\d+.-]*:/i.test(value.trimStart());
+}
+function mergeTagReferences(value) {
+  if (!Array.isArray(value) || value.length > 1e3) throw new Error("invalid_merge_tags");
+  return value.map((tag) => {
+    if (!tag || typeof tag !== "object" || typeof tag.id !== "string" || !/^[a-zA-Z][a-zA-Z0-9_]{0,63}$/.test(tag.id) || !validMergeToken(tag.token) || !["text", "url"].includes(tag.kind) || defaultMergeTags.some((builtin) => builtin.id === tag.id && tag.kind !== "url")) throw new Error("invalid_merge_tags");
+    return { id: tag.id, token: tag.token, kind: tag.kind };
+  });
+}
+function parseMergeTags(value) {
+  if (!Array.isArray(value) || value.length > 100) throw new Error("invalid_merge_tags");
+  const refs = mergeTagReferences(value);
+  const tags = value.map((tag, index) => {
+    if (Object.keys(tag).some((key) => !["id", "label", "token", "kind", "description", "sampleValue"].includes(key)) || typeof tag.label !== "string" || !tag.label.trim() || tag.label.length > 100 || control.test(tag.label) || tag.description !== void 0 && (typeof tag.description !== "string" || tag.description.length > 500 || control.test(tag.description)) || tag.sampleValue !== void 0 && (typeof tag.sampleValue !== "string" || tag.sampleValue.length > 2048 || control.test(tag.sampleValue)) || tag.kind === "url" && tag.sampleValue && !safeMergeLink(tag.sampleValue)) throw new Error("invalid_merge_tags");
+    return { ...refs[index], label: tag.label, ...tag.description === void 0 ? {} : { description: tag.description }, ...tag.sampleValue === void 0 ? {} : { sampleValue: tag.sampleValue } };
+  });
+  const ids = /* @__PURE__ */ new Set();
+  for (const [index, tag] of tags.entries()) {
+    if (ids.has(tag.id) || tags.some((other, at) => at !== index && (other.token.includes(tag.token) || tag.token.includes(other.token)))) throw new Error("invalid_merge_tags");
+    ids.add(tag.id);
+  }
+  return tags;
+}
+function resolveMergeTags(saved = [], overrides = []) {
+  const resolved = new Map(defaultMergeTags.map((tag) => [tag.id, tag]));
+  for (const layer of [saved, overrides]) for (const tag of parseMergeTags(layer)) resolved.set(tag.id, tag);
+  return parseMergeTags([...resolved.values()]);
+}
+function safeMergeLink(value, tags = []) {
+  if (!value || value.length > 2048 || control.test(value)) return void 0;
+  if (tags.some((tag) => tag.kind === "url" && tag.token === value)) return value;
+  if (/\s|[{}<>"`]/.test(value)) return void 0;
+  try {
+    const url = new URL(value);
+    return ["https:", "http:", "mailto:", "tel:"].includes(url.protocol) && !url.username && !url.password && (["https:", "http:"].includes(url.protocol) || url.pathname) ? value : void 0;
+  } catch {
+    return void 0;
+  }
+}
+
+// packages/editor/src/template-preview-limits.ts
+var TEMPLATE_PREVIEW_LIMIT = 131072;
+
+// packages/editor/src/email-document.ts
+function emailDocument(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("invalid_document");
+  const doc = value;
+  if (doc.schemaVersion !== 1 || typeof doc.subject !== "string" || doc.subject.length > 200 || typeof doc.preheader !== "string" || doc.preheader.length > 500 || !doc.content || typeof doc.content !== "object" || Array.isArray(doc.content)) throw new Error("invalid_document");
+  let nodes = 0;
+  const visit = (value2, depth) => {
+    if (!value2 || typeof value2 !== "object" || Array.isArray(value2) || depth > 50 || ++nodes > 1e4) throw new Error("invalid_document");
+    const node = value2;
+    if (typeof node.type !== "string" || !node.type || node.type.length > 100 || node.text !== void 0 && typeof node.text !== "string") throw new Error("invalid_document");
+    if (node.type === "doc") {
+      const attrs = node.attrs;
+      if (attrs?.mergeTagReferences !== void 0) mergeTagReferences(attrs.mergeTagReferences);
+    }
+    if (node.type === "mergeTag" || node.type === "unsubscribe") {
+      const attrs = node.attrs;
+      if (!attrs) throw new Error("invalid_document");
+      mergeTagReferences([{ id: attrs.id, token: attrs.token, kind: node.type === "unsubscribe" ? "url" : attrs.kind }]);
+      if (node.type === "unsubscribe" && (attrs.id !== "unsubscribe_url" || typeof attrs.label !== "string" || !attrs.label.trim() || attrs.label.length > 500)) throw new Error("invalid_document");
+    }
+    if (node.content !== void 0) {
+      if (!Array.isArray(node.content)) throw new Error("invalid_document");
+      node.content.forEach((child) => visit(child, depth + 1));
+    }
+  };
+  if (doc.content.type !== "doc") throw new Error("invalid_document");
+  visit(doc.content, 0);
+  if (doc.previewHtml !== void 0 && (typeof doc.previewHtml !== "string" || doc.previewHtml.length > TEMPLATE_PREVIEW_LIMIT)) throw new Error("invalid_document");
+  return { ...doc.previewHtml === void 0 ? {} : { previewHtml: doc.previewHtml }, schemaVersion: 1, content: doc.content, subject: doc.subject, preheader: doc.preheader };
+}
+function canonicalJson(value) {
+  if (Array.isArray(value)) return "[" + value.map(canonicalJson).join(",") + "]";
+  if (value && typeof value === "object") return "{" + Object.keys(value).sort().filter((key) => value[key] !== void 0).map((key) => JSON.stringify(key) + ":" + canonicalJson(value[key])).join(",") + "}";
+  return JSON.stringify(value);
+}
+
+// packages/editor/src/editor-theme.ts
+function resolveEditorTheme(input = {}) {
+  const dark = input.mode === "dark";
+  const theme = {
+    mode: dark ? "dark" : "light",
+    primaryColor: dark ? "#9c90ff" : "#6351ce",
+    backgroundColor: dark ? "#111827" : "#f7f8fc",
+    surfaceColor: dark ? "#1b2232" : "#ffffff",
+    shellColor: dark ? "#1b2232" : "#ffffff",
+    inputColor: dark ? "#1b2232" : "#ffffff",
+    textColor: dark ? "#e9edf5" : "#111827",
+    mutedColor: dark ? "#a6b1c6" : "#56657b",
+    borderColor: dark ? "#2c3750" : "#dce1eb",
+    cornerRadius: 8,
+    density: "comfortable",
+    fontFamily: "Inter"
+  };
+  for (const key of ["primaryColor", "backgroundColor", "surfaceColor", "shellColor", "inputColor", "textColor", "mutedColor", "borderColor"]) {
+    const value = input[key];
+    if (typeof value === "string" && /^#[0-9a-f]{6}$/i.test(value)) theme[key] = value;
+  }
+  if (!/^#[0-9a-f]{6}$/i.test(input.shellColor ?? "")) theme.shellColor = theme.surfaceColor;
+  if (!/^#[0-9a-f]{6}$/i.test(input.inputColor ?? "")) theme.inputColor = theme.surfaceColor;
+  if (typeof input.cornerRadius === "number" && Number.isFinite(input.cornerRadius)) {
+    theme.cornerRadius = Math.max(0, Math.min(24, input.cornerRadius));
+  }
+  if (input.density === "compact") theme.density = "compact";
+  if (typeof input.fontFamily === "string" && /^[\p{L}\p{N}][\p{L}\p{N} ._-]{0,99}$/u.test(input.fontFamily)) theme.fontFamily = input.fontFamily;
+  return theme;
+}
+function luminance(color) {
+  const channels = [1, 3, 5].map((start) => parseInt(color.slice(start, start + 2), 16) / 255).map((value) => value <= 0.04045 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4);
+  return channels[0] * 0.2126 + channels[1] * 0.7152 + channels[2] * 0.0722;
+}
+function colorContrast(first, second) {
+  const a = luminance(first), b = luminance(second);
+  return (Math.max(a, b) + 0.05) / (Math.min(a, b) + 0.05);
+}
+function readableForeground(background) {
+  if (colorContrast(background, "#111111") >= 4.5 && colorContrast(background, "#111111") >= colorContrast(background, "#ffffff")) return "#111111";
+  return colorContrast(background, "#000000") > colorContrast(background, "#ffffff") ? "#000000" : "#ffffff";
+}
+function mixColor(background, foreground, amount) {
+  return "#" + [1, 3, 5].map((start) => Math.round(
+    parseInt(background.slice(start, start + 2), 16) * (1 - amount) + parseInt(foreground.slice(start, start + 2), 16) * amount
+  ).toString(16).padStart(2, "0")).join("");
+}
+function readableColor(backgrounds, candidate, fallback, minimum = 4.5) {
+  const passes = (color) => backgrounds.every((background) => colorContrast(background, color) >= minimum);
+  const seed = candidate && /^#[0-9a-f]{6}$/i.test(candidate) ? candidate : fallback;
+  if (passes(seed)) return seed;
+  for (let step = 1; step <= 100; step++) {
+    const color = mixColor(seed, fallback, step / 100);
+    if (passes(color)) return color;
+  }
+  return fallback;
+}
+function stateBackground(background, target, text) {
+  for (let step = 100; step >= 0; step--) {
+    const color = mixColor(background, target, step / 100);
+    if (colorContrast(color, text) >= 4.5) return color;
+  }
+  return background;
+}
+function editorSurfacePalette(background, theme) {
+  const foreground = readableForeground(background);
+  const text = theme.textColor && /^#[0-9a-f]{6}$/i.test(theme.textColor) && colorContrast(background, theme.textColor) >= 4.5 ? theme.textColor : foreground;
+  const hover = stateBackground(background, luminance(background) > 0.7 ? mixColor(background, "#000000", 0.04) : mixColor(background, "#ffffff", 0.08), text);
+  const selected = stateBackground(background, mixColor(background, foreground, 0.04), text);
+  const states = [background, hover, selected];
+  const muted = readableColor(states, theme.mutedColor ?? mixColor(background, text, 0.65), text);
+  const danger = readableColor(states, "#b93845", states.every((color) => colorContrast(color, "#ffffff") >= 4.5) ? "#ffffff" : "#000000");
+  const focus = readableColor(states, theme.primaryColor, text, 3);
+  const border = readableColor([background], mixColor(background, foreground, 0.3), foreground, 3);
+  const accessory = mixColor(background, "#000000", 0.08);
+  const accessoryText = readableColor([accessory], text, readableForeground(accessory));
+  return {
+    text,
+    muted,
+    danger,
+    focus,
+    hover,
+    selected,
+    accessory,
+    accessoryText,
+    accessoryFocus: readableColor([accessory], theme.primaryColor, accessoryText, 3),
+    border: theme.borderColor && /^#[0-9a-f]{6}$/i.test(theme.borderColor) ? theme.borderColor : border,
+    colorScheme: luminance(background) < 0.179 ? "dark" : "light"
+  };
+}
+
+// packages/editor/src/editor-blocks.ts
+var editorBlockIds = [
+  "text",
+  "heading",
+  "button",
+  "image",
+  "video",
+  "gif",
+  "timer",
+  "menu",
+  "social",
+  "unsubscribe",
+  "list",
+  "html",
+  "space",
+  "divider",
+  "section",
+  "columns"
+];
+
+// packages/editor/src/protocol.ts
+var PROTOCOL_VERSION = 1;
+var MAX_MESSAGE_BYTES = 2097152;
+function validMessage(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  let count = 0;
+  const visit = (item, depth) => {
+    if (++count > 5e4 || depth > 60) return false;
+    if (item === null || item === void 0 || typeof item === "string" || typeof item === "boolean") return true;
+    if (typeof item === "number") return Number.isFinite(item);
+    if (typeof item !== "object") return false;
+    return Object.values(item).every((child) => visit(child, depth + 1));
+  };
+  try {
+    return visit(value, 0) && JSON.stringify(value).length <= MAX_MESSAGE_BYTES;
+  } catch {
+    return false;
+  }
+}
+export {
+  MAX_MESSAGE_BYTES,
+  PROTOCOL_VERSION,
+  canonicalJson,
+  colorContrast,
+  defaultMergeTags,
+  editorBlockIds,
+  editorSurfacePalette,
+  emailDocument,
+  mergeTagReferences,
+  parseMergeTags,
+  readableForeground,
+  resolveEditorTheme,
+  resolveMergeTags,
+  safeMergeLink,
+  validMergeToken,
+  validMessage
+};

package/dist/template-preview-limits.d.ts

@@ -0,0 +1,2 @@
+/** Keep list payloads bounded independently of the source document. */
+export declare const TEMPLATE_PREVIEW_LIMIT = 131072;

package/dist/types.d.ts

@@ -0,0 +1,94 @@
+import type { EditorTheme } from './editor-theme.js';
+import type { MergeTag, MergeTagReference, MergeTagUsage, MergeTagIssue } from './merge-tags.js';
+import type { EmailDocument } from './email-document.js';
+import type { EditorBlockId } from './editor-blocks.js';
+export type { EditorTheme, MergeTag, MergeTagReference, MergeTagUsage, MergeTagIssue, EmailDocument, EditorBlockId };
+export type EditorExport = {
+    html: string;
+    text: string;
+    document: Record<string, unknown>;
+    subject: string;
+    preheader: string;
+    mergeTags: MergeTagUsage[];
+    mergeTagIssues: MergeTagIssue[];
+};
+export type SaveStatus = 'idle' | 'unsaved' | 'saving' | 'saved' | 'failed' | 'conflict' | 'read-only';
+export type DraftChange = {
+    draftId: string | null;
+    revision: number | null;
+};
+export type SaveStatusChange = DraftChange & {
+    status: SaveStatus;
+};
+export type DraftSummary = {
+    id: string;
+    subject: string;
+    revision: number;
+    metadataRevision: number;
+    hash: string;
+    createdAt: number;
+    updatedAt: number;
+    archivedAt: number | null;
+    sourceTemplateId: string | null;
+    baseTemplateRevision: number | null;
+};
+export type DraftFlushResult = {
+    draft: DraftSummary | null;
+};
+export type TestEmailRequest = {
+    to: string;
+    subject: string;
+    html: string;
+    text: string;
+    document: Record<string, unknown>;
+};
+export type EditorConfig = {
+    theme?: EditorTheme;
+    mergeTags?: MergeTag[];
+    locale?: string;
+    allowedBlocks?: EditorBlockId[];
+    enableAi?: boolean;
+    aiPaidOrigin?: string;
+    enableTemplates?: boolean;
+    enableAutosave?: boolean;
+};
+export type EditorCallbacks = {
+    onReady?(): void;
+    onError?(error: Error): void;
+    onChange?(document: Record<string, unknown>): void;
+    onDocumentChange?(document: EmailDocument): void;
+    onTestEmail?(request: TestEmailRequest): void | Promise<void>;
+    onDraftChange?(value: DraftChange): void;
+    onSaveStatusChange?(value: SaveStatusChange): void;
+};
+export type MountOptions = EditorConfig & EditorCallbacks & {
+    editorKey: string;
+    userId?: string;
+    organizationId?: string;
+    document?: Record<string, unknown>;
+    emailDocument?: EmailDocument;
+    subject?: string;
+    preheader?: string;
+    draftId?: string;
+    editorConfig?: EditorConfig;
+    editorUrl?: string;
+    apiUrl?: string;
+    demo?: boolean;
+};
+export type EditorInstance = {
+    readonly ready: Promise<void>;
+    exportHTML(): Promise<EditorExport>;
+    previewTemplate(): Promise<EmailDocument>;
+    flushAutosave(): Promise<DraftFlushResult>;
+    updateConfig(config: EditorConfig): void;
+    destroy(): void;
+};
+export type EditorSDK = {
+    mount(target: HTMLElement | string, options: MountOptions): EditorInstance;
+};
+/** Dependency injection for local hosts and private dashboard adapters. Never serialized to the iframe. */
+export type SDKOptions = {
+    fetch?: typeof globalThis.fetch;
+    scriptUrl?: string;
+    readiness?: 'application' | 'configured';
+};

package/package.json

@@ -1,6 +1,37 @@
 {
+  "version": "0.1.0",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/weavour/editor-sdk.git"
+  },
+  "homepage": "https://github.com/weavour/editor-sdk#readme",
+  "bugs": "https://github.com/weavour/editor-sdk/issues",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22.12"
+  },
   "name": "@weavour/editor",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "description": "Framework-neutral SDK for embedding the hosted Weavour email editor.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./protocol": {
+      "types": "./dist/protocol.d.ts",
+      "import": "./dist/protocol.js"
+    },
+    "./editor.js": "./dist/editor.js"
+  }
+}