@builder.io/sdk-svelte 0.3.1 → 0.4.1

package/src/functions/get-content/types.ts

@@ -23,6 +23,7 @@ export interface GetContentOptions {
   /**
    * If set to `true`, it will lazy load symbols/references.
    * If set to `false`, it will render the entire content tree eagerly.
+   * @deprecated use `enrich` instead
    */
   noTraverse?: boolean;
 
@@ -36,9 +37,15 @@ export interface GetContentOptions {
 
   /**
    * Include references in the response. Defaults to `true`.
+   * @deprecated use `enrich` instead
    */
   includeRefs?: boolean;
 
+  /**
+   * Include multilevel references in the response.
+   */
+  enrich?: boolean;
+
   /**
    * If provided, the API will auto-resolve localized objects to the value of this `locale` key.
    */

package/src/helpers/ab-tests.ts

@@ -1,22 +1,175 @@
 import type { CanTrack } from '../types/can-track.js';
-import { getCookie, setCookie } from './cookie.js';
+import { getCookie, getCookieSync, setCookie } from './cookie.js';
+import type {
+  BuilderContent,
+  BuilderContentVariation,
+} from '../types/builder-content.js';
+import type { Nullable, Overwrite } from '../types/typescript.js';
+import { checkIsDefined } from '../helpers/nullable.js';
+import { logger } from './logger.js';
 
-const BUILDER_STORE_PREFIX = 'builderio.variations';
+const BUILDER_STORE_PREFIX = 'builder.tests';
 
 const getContentTestKey = (id: string) => `${BUILDER_STORE_PREFIX}.${id}`;
 
-export const getContentVariationCookie = ({
-  contentId,
-  canTrack,
-}: { contentId: string } & CanTrack) =>
-  getCookie({ name: getContentTestKey(contentId), canTrack });
+const getContentVariationCookie = ({ contentId }: { contentId: string }) =>
+  getCookie({ name: getContentTestKey(contentId), canTrack: true });
 
-export const setContentVariationCookie = ({
+const getContentVariationCookieSync = ({ contentId }: { contentId: string }) =>
+  getCookieSync({ name: getContentTestKey(contentId), canTrack: true });
+
+const setContentVariationCookie = ({
   contentId,
-  canTrack,
   value,
 }: {
   contentId: string;
   value: string;
-} & CanTrack) =>
-  setCookie({ name: getContentTestKey(contentId), value, canTrack });
+}) => setCookie({ name: getContentTestKey(contentId), value, canTrack: true });
+
+type BuilderContentWithVariations = Overwrite<
+  BuilderContent,
+  Required<Pick<BuilderContent, 'variations' | 'id'>>
+>;
+
+const checkIsBuilderContentWithVariations = (
+  item: BuilderContent
+): item is BuilderContentWithVariations =>
+  checkIsDefined(item.id) &&
+  checkIsDefined(item.variations) &&
+  Object.keys(item.variations).length > 0;
+
+/**
+ * Randomly assign a variation to a user
+ */
+const getRandomVariationId = ({
+  id,
+  variations,
+}: BuilderContentWithVariations) => {
+  let n = 0;
+  const random = Math.random();
+
+  // loop over variations test ratios, incrementing a counter,
+  // until we find the variation that this user should be assigned to
+  for (const id in variations) {
+    const testRatio = variations[id]?.testRatio;
+    n += testRatio!;
+
+    if (random < n) {
+      return id;
+    }
+  }
+
+  // the variations array does not include the default variation.
+  // if we arrive here, then it means that the random number fits in the default variation bucket.
+  return id;
+};
+
+const getAndSetVariantId = (args: BuilderContentWithVariations) => {
+  // if variation not found in storage, assign a random variation to this user
+  const randomVariationId = getRandomVariationId(args);
+
+  // store variation in cookies/storage
+  setContentVariationCookie({
+    contentId: args.id,
+    value: randomVariationId,
+  }).catch((err) => {
+    logger.error('could not store A/B test variation: ', err);
+  });
+
+  return randomVariationId;
+};
+
+type TestFields = {
+  data?: BuilderContentVariation['data'];
+  testVariationId?: string;
+  testVariationName: string;
+};
+
+const getTestFields = ({
+  item,
+  testGroupId,
+}: {
+  item: BuilderContentWithVariations;
+  testGroupId: string;
+}): TestFields => {
+  const variationValue = item.variations[testGroupId];
+  if (
+    testGroupId === item.id ||
+    // handle edge-case where `testGroupId` points to non-existing variation
+    !variationValue
+  ) {
+    return {
+      testVariationId: item.id,
+      testVariationName: 'Default',
+    };
+  } else {
+    return {
+      data: variationValue.data,
+      testVariationId: variationValue.id,
+      testVariationName:
+        variationValue.name || (variationValue.id === item.id ? 'Default' : ''),
+    };
+  }
+};
+
+export const handleABTestingSync = ({
+  item,
+  canTrack,
+}: { item: Nullable<BuilderContent> } & CanTrack): Nullable<BuilderContent> => {
+  if (!canTrack) {
+    return item;
+  }
+
+  if (!item) {
+    return undefined;
+  }
+
+  if (!checkIsBuilderContentWithVariations(item)) {
+    return item;
+  }
+
+  const testGroupId =
+    getContentVariationCookieSync({
+      contentId: item.id,
+    }) ||
+    getAndSetVariantId({
+      variations: item.variations,
+      id: item.id,
+    });
+
+  const variationValue = getTestFields({ item, testGroupId });
+  return {
+    ...item,
+    ...variationValue,
+  };
+};
+
+export const handleABTesting = async ({
+  item,
+  canTrack,
+}: { item: BuilderContent } & CanTrack): Promise<BuilderContent> => {
+  if (!canTrack) {
+    return item;
+  }
+
+  if (!checkIsBuilderContentWithVariations(item)) {
+    return item;
+  }
+
+  const cookieValue = await getContentVariationCookie({
+    contentId: item.id,
+  });
+
+  const testGroupId =
+    cookieValue ||
+    getAndSetVariantId({
+      variations: item.variations,
+      id: item.id,
+    });
+
+  const variationValue = getTestFields({ item, testGroupId });
+  return {
+    ...item,
+    ...variationValue,
+  };
+};

package/src/helpers/canTrack.ts

@@ -0,0 +1,4 @@
+import { checkIsDefined } from './nullable';
+
+export const getDefaultCanTrack = (canTrack?: boolean) =>
+  checkIsDefined(canTrack) ? canTrack : true;

package/src/helpers/cookie.ts

@@ -1,17 +1,17 @@
 import { isBrowser } from '../functions/is-browser.js';
 import type { CanTrack } from '../types/can-track.js';
+import { logger } from './logger.js';
 import { checkIsDefined } from './nullable.js';
 import { getTopLevelDomain } from './url.js';
 
-/**
- * NOTE: This function is `async` because its react-native override is async. Do not remove the `async` keyword!
- */
-export const getCookie = async ({
+type GetCookieArgs = {
+  name: string;
+} & CanTrack;
+
+export const getCookieSync = ({
   name,
   canTrack,
-}: {
-  name: string;
-} & CanTrack): Promise<string | undefined> => {
+}: GetCookieArgs): string | undefined => {
   try {
     if (!canTrack) {
       return undefined;
@@ -25,11 +25,16 @@ export const getCookie = async ({
       .split('; ')
       .find((row) => row.startsWith(`${name}=`))
       ?.split('=')[1];
-  } catch (err) {
-    console.debug('[COOKIE] GET error: ', err);
+  } catch (err: any) {
+    logger.warn('[COOKIE] GET error: ', err?.message || err);
     return undefined;
   }
 };
+/**
+ * NOTE: This function is `async` because its react-native override is async. Do not remove the `async` keyword!
+ * The sync version is only safe to use in code blocks that `react-native` is guaranteed not to not run.
+ */
+export const getCookie = async (args: GetCookieArgs) => getCookieSync(args);
 
 type CookieConfiguration = Array<
   | ['expires', string]
@@ -101,7 +106,7 @@ export const setCookie = async ({
     }
     const cookie = createCookieString({ name, value, expires });
     document.cookie = cookie;
-  } catch (err) {
-    console.warn('[COOKIE] SET error: ', err);
+  } catch (err: any) {
+    logger.warn('[COOKIE] SET error: ', err?.message || err);
   }
 };

package/src/helpers/logger.ts

@@ -3,4 +3,5 @@ export const logger = {
   log: (...message: any[]) => console.log(MSG_PREFIX, ...message),
   error: (...message: any[]) => console.error(MSG_PREFIX, ...message),
   warn: (...message: any[]) => console.warn(MSG_PREFIX, ...message),
+  debug: (...message: any[]) => console.debug(MSG_PREFIX, ...message),
 };

package/src/index-helpers/blocks-exports.ts

@@ -3,8 +3,8 @@ export { default as Columns } from '../blocks/columns/columns.svelte';
 export { default as Fragment } from '../blocks/fragment/fragment.svelte';
 export { default as Image } from '../blocks/image/image.svelte';
 export { default as RenderBlocks } from '../components/render-blocks.svelte';
-export { default as RenderContent } from '../components/render-content/render-content.svelte';
 export { default as Section } from '../blocks/section/section.svelte';
 export { default as Symbol } from '../blocks/symbol/symbol.svelte';
 export { default as Text } from '../blocks/text/text.svelte';
 export { default as Video } from '../blocks/video/video.svelte';
+export { default as RenderContent } from '../components/render-content-variants/render-content-variants.svelte';

package/src/index.ts

@@ -1,15 +1,26 @@
 export * from './index-helpers/top-of-file.js';
-
 export * from './index-helpers/blocks-exports.js';
 
-export * from './functions/is-editing.js';
-export * from './functions/is-previewing.js';
-export * from './functions/register-component.js';
-export * from './functions/register.js';
-export * from './functions/set-editor-settings.js';
-export * from './functions/get-content/index.js';
-export * from './functions/get-builder-search-params/index.js';
+export { isEditing } from './functions/is-editing.js';
+export { isPreviewing } from './functions/is-previewing.js';
+export { createRegisterComponentMessage } from './functions/register-component.js';
+
+export { register } from './functions/register.js';
+export type { InsertMenuConfig, InsertMenuItem } from './functions/register.js';
+
+export { setEditorSettings } from './functions/set-editor-settings.js';
+export type { Settings } from './functions/set-editor-settings.js';
+
+export {
+  getAllContent,
+  getContent,
+  processContentResult,
+} from './functions/get-content/index.js';
+
+export { getBuilderSearchParams } from './functions/get-builder-search-params/index.js';
+
 export { track } from './functions/track/index.js';
+
 export type { RegisteredComponent } from './context/types';
 export type { ComponentInfo } from './types/components';
 export type { RenderContentProps } from './components/render-content/render-content.types.js';

package/src/scripts/init-editing.ts

@@ -27,6 +27,7 @@ export const registerInsertMenu = () => {
 let isSetupForEditing = false;
 export const setupBrowserForEditing = (
   options: {
+    enrich?: boolean;
     includeRefs?: boolean;
     locale?: string;
   } = {}

package/src/types/builder-content.ts

@@ -30,8 +30,6 @@ export interface BuilderContentVariation {
 export interface BuilderContent extends BuilderContentVariation {
   // TODO: query
   '@version'?: number;
-  id?: string;
-  name?: string;
   published?: 'published' | 'draft' | 'archived';
   modelId?: string;
   priority?: number;
@@ -39,7 +37,7 @@ export interface BuilderContent extends BuilderContentVariation {
   startDate?: number;
   endDate?: number;
   variations?: {
-    [id: string]: BuilderContentVariation | undefined;
+    [id: string]: BuilderContentVariation;
   };
   testVariationId?: string;
   testVariationName?: string;

package/package/functions/get-content/ab-testing.d.ts

@@ -1,5 +0,0 @@
-import type { BuilderContent } from '../../types/builder-content.js';
-import type { CanTrack } from '../../types/can-track.js';
-export declare const handleABTesting: ({ item, canTrack, }: {
-    item: BuilderContent;
-} & CanTrack) => Promise<void>;

package/package/functions/get-content/ab-testing.js

@@ -1,78 +0,0 @@
-import { getContentVariationCookie, setContentVariationCookie, } from '../../helpers/ab-tests.js';
-import { checkIsDefined } from '../../helpers/nullable.js';
-const checkIsBuilderContentWithVariations = (item) => checkIsDefined(item.id) &&
-    checkIsDefined(item.variations) &&
-    Object.keys(item.variations).length > 0;
-/**
- * Randomly assign a variation to this user and store it in cookies/storage
- */
-const getRandomVariationId = ({ id, variations, }) => {
-    let n = 0;
-    const random = Math.random();
-    // loop over variations test ratios, incrementing a counter,
-    // until we find the variation that this user should be assigned to
-    for (const id in variations) {
-        const testRatio = variations[id]?.testRatio;
-        n += testRatio;
-        if (random < n) {
-            return id;
-        }
-    }
-    // `item.variations` does not include the default variation
-    // if we arrive here, then it means that the random number fits in the default variation bucket
-    return id;
-};
-const getTestFields = ({ item, testGroupId, }) => {
-    const variationValue = item.variations[testGroupId];
-    if (testGroupId === item.id ||
-        // handle edge-case where `testGroupId` points to non-existing variation
-        !variationValue) {
-        return {
-            testVariationId: item.id,
-            testVariationName: 'Default',
-        };
-    }
-    else {
-        return {
-            data: variationValue.data,
-            testVariationId: variationValue.id,
-            testVariationName: variationValue.name || (variationValue.id === item.id ? 'Default' : ''),
-        };
-    }
-};
-const getContentVariation = async ({ item, canTrack, }) => {
-    // try to find test variation in cookies/storage
-    const testGroupId = await getContentVariationCookie({
-        canTrack,
-        contentId: item.id,
-    });
-    const testFields = testGroupId
-        ? getTestFields({ item, testGroupId })
-        : undefined;
-    if (testFields) {
-        return testFields;
-    }
-    else {
-        // if variation not found in storage, assign a random variation to this user
-        const randomVariationId = getRandomVariationId({
-            variations: item.variations,
-            id: item.id,
-        });
-        // store variation in cookies/storage
-        setContentVariationCookie({
-            contentId: item.id,
-            value: randomVariationId,
-            canTrack,
-        }).catch((err) => {
-            console.error('could not store A/B test variation: ', err);
-        });
-        return getTestFields({ item, testGroupId: randomVariationId });
-    }
-};
-export const handleABTesting = async ({ item, canTrack, }) => {
-    if (!checkIsBuilderContentWithVariations(item)) {
-        return;
-    }
-    const variationValue = await getContentVariation({ item, canTrack });
-    Object.assign(item, variationValue);
-};

package/src/functions/get-content/ab-testing.ts

@@ -1,132 +0,0 @@
-import type {
-  BuilderContent,
-  BuilderContentVariation,
-} from '../../types/builder-content.js';
-import {
-  getContentVariationCookie,
-  setContentVariationCookie,
-} from '../../helpers/ab-tests.js';
-import type { Overwrite } from '../../types/typescript.js';
-import type { CanTrack } from '../../types/can-track.js';
-import { checkIsDefined } from '../../helpers/nullable.js';
-
-type BuilderContentWithVariations = Overwrite<
-  BuilderContent,
-  Required<Pick<BuilderContent, 'variations' | 'id'>>
->;
-
-const checkIsBuilderContentWithVariations = (
-  item: BuilderContent
-): item is BuilderContentWithVariations =>
-  checkIsDefined(item.id) &&
-  checkIsDefined(item.variations) &&
-  Object.keys(item.variations).length > 0;
-
-/**
- * Randomly assign a variation to this user and store it in cookies/storage
- */
-const getRandomVariationId = ({
-  id,
-  variations,
-}: BuilderContentWithVariations) => {
-  let n = 0;
-  const random = Math.random();
-
-  // loop over variations test ratios, incrementing a counter,
-  // until we find the variation that this user should be assigned to
-  for (const id in variations) {
-    const testRatio = variations[id]?.testRatio;
-    n += testRatio!;
-
-    if (random < n) {
-      return id;
-    }
-  }
-
-  // `item.variations` does not include the default variation
-  // if we arrive here, then it means that the random number fits in the default variation bucket
-  return id;
-};
-
-const getTestFields = ({
-  item,
-  testGroupId,
-}: {
-  item: BuilderContentWithVariations;
-  testGroupId: string;
-}): TestFields => {
-  const variationValue = item.variations[testGroupId];
-  if (
-    testGroupId === item.id ||
-    // handle edge-case where `testGroupId` points to non-existing variation
-    !variationValue
-  ) {
-    return {
-      testVariationId: item.id,
-      testVariationName: 'Default',
-    };
-  } else {
-    return {
-      data: variationValue.data,
-      testVariationId: variationValue.id,
-      testVariationName:
-        variationValue.name || (variationValue.id === item.id ? 'Default' : ''),
-    };
-  }
-};
-
-type TestFields = {
-  data?: BuilderContentVariation['data'];
-  testVariationId?: string;
-  testVariationName: string;
-};
-
-const getContentVariation = async ({
-  item,
-  canTrack,
-}: {
-  item: BuilderContentWithVariations;
-} & CanTrack): Promise<TestFields> => {
-  // try to find test variation in cookies/storage
-  const testGroupId = await getContentVariationCookie({
-    canTrack,
-    contentId: item.id,
-  });
-
-  const testFields = testGroupId
-    ? getTestFields({ item, testGroupId })
-    : undefined;
-
-  if (testFields) {
-    return testFields;
-  } else {
-    // if variation not found in storage, assign a random variation to this user
-    const randomVariationId = getRandomVariationId({
-      variations: item.variations,
-      id: item.id,
-    });
-
-    // store variation in cookies/storage
-    setContentVariationCookie({
-      contentId: item.id,
-      value: randomVariationId,
-      canTrack,
-    }).catch((err) => {
-      console.error('could not store A/B test variation: ', err);
-    });
-
-    return getTestFields({ item, testGroupId: randomVariationId });
-  }
-};
-
-export const handleABTesting = async ({
-  item,
-  canTrack,
-}: { item: BuilderContent } & CanTrack) => {
-  if (!checkIsBuilderContentWithVariations(item)) {
-    return;
-  }
-
-  const variationValue = await getContentVariation({ item, canTrack });
-  Object.assign(item, variationValue);
-};