@drip-apex/sdk 0.1.0 → 0.2.0

package/dist/define.cjs

@@ -0,0 +1,123 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/define.ts
+var define_exports = {};
+__export(define_exports, {
+  ExperimentDefinitionError: () => ExperimentDefinitionError,
+  defineExperiment: () => defineExperiment,
+  defineExperiments: () => defineExperiments
+});
+module.exports = __toCommonJS(define_exports);
+var ExperimentDefinitionError = class extends Error {
+  constructor(slug, issues) {
+    super(`Invalid experiment "${slug}": ${issues.join("; ")}`);
+    this.name = "ExperimentDefinitionError";
+    this.issues = issues;
+  }
+};
+function validate(def) {
+  const issues = [];
+  if (!def.slug || typeof def.slug !== "string") {
+    issues.push("slug is required and must be a non-empty string");
+  } else if (!/^[a-z0-9][a-z0-9-]*[a-z0-9]$/.test(def.slug) && def.slug.length > 1) {
+    issues.push("slug must be lowercase alphanumeric with hyphens (e.g. 'hero-banner-v2')");
+  }
+  if (!def.name || typeof def.name !== "string") {
+    issues.push("name is required");
+  }
+  if (!Array.isArray(def.variations) || def.variations.length < 2) {
+    issues.push("at least 2 variations are required");
+  } else {
+    const controls = def.variations.filter((v) => v.isControl);
+    if (controls.length === 0) {
+      issues.push("exactly one variation must be marked as control (isControl: true)");
+    } else if (controls.length > 1) {
+      issues.push("only one variation can be the control");
+    }
+    const totalWeight = def.variations.reduce((sum, v) => sum + v.weight, 0);
+    if (Math.abs(totalWeight - 1) > 0.01) {
+      issues.push(`variation weights should sum to 1 (got ${totalWeight.toFixed(3)})`);
+    }
+    const ids = /* @__PURE__ */ new Set();
+    for (const v of def.variations) {
+      if (!v.id) issues.push("every variation must have an id");
+      if (ids.has(v.id)) issues.push(`duplicate variation id: "${v.id}"`);
+      ids.add(v.id);
+      if (v.weight < 0 || v.weight > 1) issues.push(`variation "${v.id}" weight must be between 0 and 1`);
+    }
+  }
+  if (def.trafficAllocation !== void 0) {
+    if (def.trafficAllocation < 0 || def.trafficAllocation > 1) {
+      issues.push("trafficAllocation must be between 0 and 1");
+    }
+  }
+  if (def.goals) {
+    const goalIds = /* @__PURE__ */ new Set();
+    for (const g of def.goals) {
+      if (!g.id) issues.push("every goal must have an id");
+      if (goalIds.has(g.id)) issues.push(`duplicate goal id: "${g.id}"`);
+      goalIds.add(g.id);
+      if (g.type === "click" && !g.selector) {
+        issues.push(`click goal "${g.id}" requires a selector`);
+      }
+    }
+  }
+  return issues;
+}
+function defineExperiment(def) {
+  const issues = validate(def);
+  if (issues.length > 0) {
+    throw new ExperimentDefinitionError(def.slug ?? "(unnamed)", issues);
+  }
+  const experiment = {
+    id: def.slug,
+    // slug is used as the id for code-first experiments
+    slug: def.slug,
+    name: def.name,
+    trafficAllocation: def.trafficAllocation ?? 1,
+    targeting: def.targeting,
+    hashAttribute: def.hashAttribute,
+    variations: def.variations.map((v) => ({
+      id: v.id,
+      name: v.name,
+      weight: v.weight,
+      mutations: v.mutations ?? [],
+      value: v.value,
+      css: v.css,
+      js: v.js,
+      resetJs: v.resetJs,
+      externalCssUrl: v.externalCssUrl,
+      externalJsUrl: v.externalJsUrl,
+      isControl: v.isControl ?? false
+    })),
+    goals: def.goals?.map((g) => ({
+      id: g.id,
+      type: g.type,
+      selector: g.selector,
+      urlPattern: g.urlPattern,
+      countOnce: g.countOnce
+    }))
+  };
+  return Object.freeze(experiment);
+}
+function defineExperiments(defs) {
+  return defs.map(defineExperiment);
+}
+//# sourceMappingURL=define.cjs.map

package/dist/define.cjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/define.ts"],
+  "sourcesContent": ["/**\n * defineExperiment \u2014 typed experiment definitions with validation.\n *\n * Usage:\n *   const hero = defineExperiment({\n *     slug: \"hero-banner-v2\",\n *     name: \"Hero Banner V2\",\n *     variations: [\n *       { id: \"control\", weight: 0.5, mutations: [], isControl: true },\n *       { id: \"variant-a\", weight: 0.5, mutations: [{ selector: \".hero h1\", action: \"text\", text: \"New headline\" }] },\n *     ],\n *     targeting: { url: [{ type: \"simple\", pattern: \"/\" }] },\n *     goals: [{ id: \"cta-click\", type: \"click\", selector: \".hero-cta\" }],\n *   });\n */\n\nimport type { Experiment, Goal, Mutation, Targeting, Variation } from \"./types\";\n\n// ---------------------------------------------------------------------------\n// Input types \u2014 looser than runtime types for developer ergonomics\n// ---------------------------------------------------------------------------\n\nexport interface ExperimentDefinition {\n  /** Unique slug for GitOps upsert. Required for code-first experiments. */\n  slug: string;\n  /** Human-readable name. */\n  name: string;\n  /** Traffic allocation percentage (0\u20131). Default: 1. */\n  trafficAllocation?: number;\n  /** Targeting rules. */\n  targeting?: Targeting;\n  /** Hash attribute override (default: visitor cookie). */\n  hashAttribute?: string;\n  /** Variation definitions. At least two required. */\n  variations: VariationDefinition[];\n  /** Goal definitions for conversion tracking. */\n  goals?: GoalDefinition[];\n}\n\nexport interface VariationDefinition {\n  /** Variation identifier (used as slug within the experiment). */\n  id: string;\n  /** Display name. Falls back to id if omitted. */\n  name?: string;\n  /** Traffic weight (0\u20131). All weights should sum to 1. */\n  weight: number;\n  /** DOM mutations to apply. Default: []. */\n  mutations?: Mutation[];\n  /** Optional typed value returned by feature-flag helpers. */\n  value?: unknown;\n  /** Custom CSS injected when this variation is active. */\n  css?: string;\n  /** Custom JavaScript executed when this variation is active. */\n  js?: string;\n  /** Reset JavaScript executed on SPA navigation away. */\n  resetJs?: string;\n  /** External CSS artifact URL loaded when this variation is active. */\n  externalCssUrl?: string;\n  /** External JS artifact URL loaded when this variation is active. */\n  externalJsUrl?: string;\n  /** Mark as control variation. Exactly one variation should be control. */\n  isControl?: boolean;\n}\n\nexport interface GoalDefinition {\n  /** Goal identifier (used as slug). */\n  id: string;\n  /** Goal type. */\n  type: \"click\" | \"pageview\" | \"custom\" | \"revenue\";\n  /** CSS selector for click/element goals. */\n  selector?: string;\n  /** URL pattern for pageview goals. */\n  urlPattern?: string;\n  /** Only count once per session. Default: false. */\n  countOnce?: boolean;\n}\n\n// ---------------------------------------------------------------------------\n// Validation errors\n// ---------------------------------------------------------------------------\n\nexport class ExperimentDefinitionError extends Error {\n  public readonly issues: string[];\n\n  constructor(slug: string, issues: string[]) {\n    super(`Invalid experiment \"${slug}\": ${issues.join(\"; \")}`);\n    this.name = \"ExperimentDefinitionError\";\n    this.issues = issues;\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Validation\n// ---------------------------------------------------------------------------\n\nfunction validate(def: ExperimentDefinition): string[] {\n  const issues: string[] = [];\n\n  if (!def.slug || typeof def.slug !== \"string\") {\n    issues.push(\"slug is required and must be a non-empty string\");\n  } else if (!/^[a-z0-9][a-z0-9-]*[a-z0-9]$/.test(def.slug) && def.slug.length > 1) {\n    issues.push(\"slug must be lowercase alphanumeric with hyphens (e.g. 'hero-banner-v2')\");\n  }\n\n  if (!def.name || typeof def.name !== \"string\") {\n    issues.push(\"name is required\");\n  }\n\n  if (!Array.isArray(def.variations) || def.variations.length < 2) {\n    issues.push(\"at least 2 variations are required\");\n  } else {\n    const controls = def.variations.filter((v) => v.isControl);\n    if (controls.length === 0) {\n      issues.push(\"exactly one variation must be marked as control (isControl: true)\");\n    } else if (controls.length > 1) {\n      issues.push(\"only one variation can be the control\");\n    }\n\n    const totalWeight = def.variations.reduce((sum, v) => sum + v.weight, 0);\n    if (Math.abs(totalWeight - 1) > 0.01) {\n      issues.push(`variation weights should sum to 1 (got ${totalWeight.toFixed(3)})`);\n    }\n\n    const ids = new Set<string>();\n    for (const v of def.variations) {\n      if (!v.id) issues.push(\"every variation must have an id\");\n      if (ids.has(v.id)) issues.push(`duplicate variation id: \"${v.id}\"`);\n      ids.add(v.id);\n      if (v.weight < 0 || v.weight > 1) issues.push(`variation \"${v.id}\" weight must be between 0 and 1`);\n    }\n  }\n\n  if (def.trafficAllocation !== undefined) {\n    if (def.trafficAllocation < 0 || def.trafficAllocation > 1) {\n      issues.push(\"trafficAllocation must be between 0 and 1\");\n    }\n  }\n\n  if (def.goals) {\n    const goalIds = new Set<string>();\n    for (const g of def.goals) {\n      if (!g.id) issues.push(\"every goal must have an id\");\n      if (goalIds.has(g.id)) issues.push(`duplicate goal id: \"${g.id}\"`);\n      goalIds.add(g.id);\n\n      if (g.type === \"click\" && !g.selector) {\n        issues.push(`click goal \"${g.id}\" requires a selector`);\n      }\n    }\n  }\n\n  return issues;\n}\n\n// ---------------------------------------------------------------------------\n// defineExperiment\n// ---------------------------------------------------------------------------\n\n/**\n * Define a typed, validated experiment configuration.\n *\n * Returns a frozen Experiment object ready for use with `init({ experiments: [...] })`.\n * Throws `ExperimentDefinitionError` if the definition is invalid.\n */\nexport function defineExperiment(def: ExperimentDefinition): Experiment & { slug: string } {\n  const issues = validate(def);\n  if (issues.length > 0) {\n    throw new ExperimentDefinitionError(def.slug ?? \"(unnamed)\", issues);\n  }\n\n  const experiment: Experiment & { slug: string } = {\n    id: def.slug, // slug is used as the id for code-first experiments\n    slug: def.slug,\n    name: def.name,\n    trafficAllocation: def.trafficAllocation ?? 1,\n    targeting: def.targeting,\n    hashAttribute: def.hashAttribute,\n    variations: def.variations.map((v) => ({\n      id: v.id,\n      name: v.name,\n      weight: v.weight,\n      mutations: v.mutations ?? [],\n      value: v.value,\n      css: v.css,\n      js: v.js,\n      resetJs: v.resetJs,\n      externalCssUrl: v.externalCssUrl,\n      externalJsUrl: v.externalJsUrl,\n      isControl: v.isControl ?? false,\n    })),\n    goals: def.goals?.map((g) => ({\n      id: g.id,\n      type: g.type,\n      selector: g.selector,\n      urlPattern: g.urlPattern,\n      countOnce: g.countOnce,\n    })),\n  };\n\n  return Object.freeze(experiment) as Experiment & { slug: string };\n}\n\n/**\n * Define multiple experiments at once. Validates all, throws on first invalid.\n */\nexport function defineExperiments(defs: ExperimentDefinition[]): Array<Experiment & { slug: string }> {\n  return defs.map(defineExperiment);\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/define.mjs

@@ -0,0 +1,102 @@
+// src/define.ts
+var ExperimentDefinitionError = class extends Error {
+  constructor(slug, issues) {
+    super(`Invalid experiment "${slug}": ${issues.join("; ")}`);
+    this.name = "ExperimentDefinitionError";
+    this.issues = issues;
+  }
+};
+function validate(def) {
+  const issues = [];
+  if (!def.slug || typeof def.slug !== "string") {
+    issues.push("slug is required and must be a non-empty string");
+  } else if (!/^[a-z0-9][a-z0-9-]*[a-z0-9]$/.test(def.slug) && def.slug.length > 1) {
+    issues.push("slug must be lowercase alphanumeric with hyphens (e.g. 'hero-banner-v2')");
+  }
+  if (!def.name || typeof def.name !== "string") {
+    issues.push("name is required");
+  }
+  if (!Array.isArray(def.variations) || def.variations.length < 2) {
+    issues.push("at least 2 variations are required");
+  } else {
+    const controls = def.variations.filter((v) => v.isControl);
+    if (controls.length === 0) {
+      issues.push("exactly one variation must be marked as control (isControl: true)");
+    } else if (controls.length > 1) {
+      issues.push("only one variation can be the control");
+    }
+    const totalWeight = def.variations.reduce((sum, v) => sum + v.weight, 0);
+    if (Math.abs(totalWeight - 1) > 0.01) {
+      issues.push(`variation weights should sum to 1 (got ${totalWeight.toFixed(3)})`);
+    }
+    const ids = /* @__PURE__ */ new Set();
+    for (const v of def.variations) {
+      if (!v.id) issues.push("every variation must have an id");
+      if (ids.has(v.id)) issues.push(`duplicate variation id: "${v.id}"`);
+      ids.add(v.id);
+      if (v.weight < 0 || v.weight > 1) issues.push(`variation "${v.id}" weight must be between 0 and 1`);
+    }
+  }
+  if (def.trafficAllocation !== void 0) {
+    if (def.trafficAllocation < 0 || def.trafficAllocation > 1) {
+      issues.push("trafficAllocation must be between 0 and 1");
+    }
+  }
+  if (def.goals) {
+    const goalIds = /* @__PURE__ */ new Set();
+    for (const g of def.goals) {
+      if (!g.id) issues.push("every goal must have an id");
+      if (goalIds.has(g.id)) issues.push(`duplicate goal id: "${g.id}"`);
+      goalIds.add(g.id);
+      if (g.type === "click" && !g.selector) {
+        issues.push(`click goal "${g.id}" requires a selector`);
+      }
+    }
+  }
+  return issues;
+}
+function defineExperiment(def) {
+  const issues = validate(def);
+  if (issues.length > 0) {
+    throw new ExperimentDefinitionError(def.slug ?? "(unnamed)", issues);
+  }
+  const experiment = {
+    id: def.slug,
+    // slug is used as the id for code-first experiments
+    slug: def.slug,
+    name: def.name,
+    trafficAllocation: def.trafficAllocation ?? 1,
+    targeting: def.targeting,
+    hashAttribute: def.hashAttribute,
+    variations: def.variations.map((v) => ({
+      id: v.id,
+      name: v.name,
+      weight: v.weight,
+      mutations: v.mutations ?? [],
+      value: v.value,
+      css: v.css,
+      js: v.js,
+      resetJs: v.resetJs,
+      externalCssUrl: v.externalCssUrl,
+      externalJsUrl: v.externalJsUrl,
+      isControl: v.isControl ?? false
+    })),
+    goals: def.goals?.map((g) => ({
+      id: g.id,
+      type: g.type,
+      selector: g.selector,
+      urlPattern: g.urlPattern,
+      countOnce: g.countOnce
+    }))
+  };
+  return Object.freeze(experiment);
+}
+function defineExperiments(defs) {
+  return defs.map(defineExperiment);
+}
+export {
+  ExperimentDefinitionError,
+  defineExperiment,
+  defineExperiments
+};
+//# sourceMappingURL=define.mjs.map

package/dist/define.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/define.ts"],
+  "sourcesContent": ["/**\n * defineExperiment \u2014 typed experiment definitions with validation.\n *\n * Usage:\n *   const hero = defineExperiment({\n *     slug: \"hero-banner-v2\",\n *     name: \"Hero Banner V2\",\n *     variations: [\n *       { id: \"control\", weight: 0.5, mutations: [], isControl: true },\n *       { id: \"variant-a\", weight: 0.5, mutations: [{ selector: \".hero h1\", action: \"text\", text: \"New headline\" }] },\n *     ],\n *     targeting: { url: [{ type: \"simple\", pattern: \"/\" }] },\n *     goals: [{ id: \"cta-click\", type: \"click\", selector: \".hero-cta\" }],\n *   });\n */\n\nimport type { Experiment, Goal, Mutation, Targeting, Variation } from \"./types\";\n\n// ---------------------------------------------------------------------------\n// Input types \u2014 looser than runtime types for developer ergonomics\n// ---------------------------------------------------------------------------\n\nexport interface ExperimentDefinition {\n  /** Unique slug for GitOps upsert. Required for code-first experiments. */\n  slug: string;\n  /** Human-readable name. */\n  name: string;\n  /** Traffic allocation percentage (0\u20131). Default: 1. */\n  trafficAllocation?: number;\n  /** Targeting rules. */\n  targeting?: Targeting;\n  /** Hash attribute override (default: visitor cookie). */\n  hashAttribute?: string;\n  /** Variation definitions. At least two required. */\n  variations: VariationDefinition[];\n  /** Goal definitions for conversion tracking. */\n  goals?: GoalDefinition[];\n}\n\nexport interface VariationDefinition {\n  /** Variation identifier (used as slug within the experiment). */\n  id: string;\n  /** Display name. Falls back to id if omitted. */\n  name?: string;\n  /** Traffic weight (0\u20131). All weights should sum to 1. */\n  weight: number;\n  /** DOM mutations to apply. Default: []. */\n  mutations?: Mutation[];\n  /** Optional typed value returned by feature-flag helpers. */\n  value?: unknown;\n  /** Custom CSS injected when this variation is active. */\n  css?: string;\n  /** Custom JavaScript executed when this variation is active. */\n  js?: string;\n  /** Reset JavaScript executed on SPA navigation away. */\n  resetJs?: string;\n  /** External CSS artifact URL loaded when this variation is active. */\n  externalCssUrl?: string;\n  /** External JS artifact URL loaded when this variation is active. */\n  externalJsUrl?: string;\n  /** Mark as control variation. Exactly one variation should be control. */\n  isControl?: boolean;\n}\n\nexport interface GoalDefinition {\n  /** Goal identifier (used as slug). */\n  id: string;\n  /** Goal type. */\n  type: \"click\" | \"pageview\" | \"custom\" | \"revenue\";\n  /** CSS selector for click/element goals. */\n  selector?: string;\n  /** URL pattern for pageview goals. */\n  urlPattern?: string;\n  /** Only count once per session. Default: false. */\n  countOnce?: boolean;\n}\n\n// ---------------------------------------------------------------------------\n// Validation errors\n// ---------------------------------------------------------------------------\n\nexport class ExperimentDefinitionError extends Error {\n  public readonly issues: string[];\n\n  constructor(slug: string, issues: string[]) {\n    super(`Invalid experiment \"${slug}\": ${issues.join(\"; \")}`);\n    this.name = \"ExperimentDefinitionError\";\n    this.issues = issues;\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Validation\n// ---------------------------------------------------------------------------\n\nfunction validate(def: ExperimentDefinition): string[] {\n  const issues: string[] = [];\n\n  if (!def.slug || typeof def.slug !== \"string\") {\n    issues.push(\"slug is required and must be a non-empty string\");\n  } else if (!/^[a-z0-9][a-z0-9-]*[a-z0-9]$/.test(def.slug) && def.slug.length > 1) {\n    issues.push(\"slug must be lowercase alphanumeric with hyphens (e.g. 'hero-banner-v2')\");\n  }\n\n  if (!def.name || typeof def.name !== \"string\") {\n    issues.push(\"name is required\");\n  }\n\n  if (!Array.isArray(def.variations) || def.variations.length < 2) {\n    issues.push(\"at least 2 variations are required\");\n  } else {\n    const controls = def.variations.filter((v) => v.isControl);\n    if (controls.length === 0) {\n      issues.push(\"exactly one variation must be marked as control (isControl: true)\");\n    } else if (controls.length > 1) {\n      issues.push(\"only one variation can be the control\");\n    }\n\n    const totalWeight = def.variations.reduce((sum, v) => sum + v.weight, 0);\n    if (Math.abs(totalWeight - 1) > 0.01) {\n      issues.push(`variation weights should sum to 1 (got ${totalWeight.toFixed(3)})`);\n    }\n\n    const ids = new Set<string>();\n    for (const v of def.variations) {\n      if (!v.id) issues.push(\"every variation must have an id\");\n      if (ids.has(v.id)) issues.push(`duplicate variation id: \"${v.id}\"`);\n      ids.add(v.id);\n      if (v.weight < 0 || v.weight > 1) issues.push(`variation \"${v.id}\" weight must be between 0 and 1`);\n    }\n  }\n\n  if (def.trafficAllocation !== undefined) {\n    if (def.trafficAllocation < 0 || def.trafficAllocation > 1) {\n      issues.push(\"trafficAllocation must be between 0 and 1\");\n    }\n  }\n\n  if (def.goals) {\n    const goalIds = new Set<string>();\n    for (const g of def.goals) {\n      if (!g.id) issues.push(\"every goal must have an id\");\n      if (goalIds.has(g.id)) issues.push(`duplicate goal id: \"${g.id}\"`);\n      goalIds.add(g.id);\n\n      if (g.type === \"click\" && !g.selector) {\n        issues.push(`click goal \"${g.id}\" requires a selector`);\n      }\n    }\n  }\n\n  return issues;\n}\n\n// ---------------------------------------------------------------------------\n// defineExperiment\n// ---------------------------------------------------------------------------\n\n/**\n * Define a typed, validated experiment configuration.\n *\n * Returns a frozen Experiment object ready for use with `init({ experiments: [...] })`.\n * Throws `ExperimentDefinitionError` if the definition is invalid.\n */\nexport function defineExperiment(def: ExperimentDefinition): Experiment & { slug: string } {\n  const issues = validate(def);\n  if (issues.length > 0) {\n    throw new ExperimentDefinitionError(def.slug ?? \"(unnamed)\", issues);\n  }\n\n  const experiment: Experiment & { slug: string } = {\n    id: def.slug, // slug is used as the id for code-first experiments\n    slug: def.slug,\n    name: def.name,\n    trafficAllocation: def.trafficAllocation ?? 1,\n    targeting: def.targeting,\n    hashAttribute: def.hashAttribute,\n    variations: def.variations.map((v) => ({\n      id: v.id,\n      name: v.name,\n      weight: v.weight,\n      mutations: v.mutations ?? [],\n      value: v.value,\n      css: v.css,\n      js: v.js,\n      resetJs: v.resetJs,\n      externalCssUrl: v.externalCssUrl,\n      externalJsUrl: v.externalJsUrl,\n      isControl: v.isControl ?? false,\n    })),\n    goals: def.goals?.map((g) => ({\n      id: g.id,\n      type: g.type,\n      selector: g.selector,\n      urlPattern: g.urlPattern,\n      countOnce: g.countOnce,\n    })),\n  };\n\n  return Object.freeze(experiment) as Experiment & { slug: string };\n}\n\n/**\n * Define multiple experiments at once. Validates all, throws on first invalid.\n */\nexport function defineExperiments(defs: ExperimentDefinition[]): Array<Experiment & { slug: string }> {\n  return defs.map(defineExperiment);\n}\n"],
+  "mappings": "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",
+  "names": []
+}