@builder.io/sdk-svelte 0.2.3 → 0.4.0

package/src/functions/evaluate.ts

@@ -1,18 +1,26 @@
-import type { BuilderContextInterface } from '../context/types.js';
+import type {
+  BuilderContextInterface,
+  BuilderRenderState,
+} from '../context/types.js';
 import { isBrowser } from './is-browser.js';
 import { isEditing } from './is-editing.js';
 
 export function evaluate({
   code,
   context,
-  state,
+  localState,
+  rootState,
+  rootSetState,
   event,
   isExpression = true,
 }: {
   code: string;
   event?: Event;
   isExpression?: boolean;
-} & Pick<BuilderContextInterface, 'state' | 'context'>): any {
+} & Pick<
+  BuilderContextInterface,
+  'localState' | 'context' | 'rootState' | 'rootSetState'
+>): any {
   if (code === '') {
     console.warn('Skipping evaluation of empty code block.');
     return;
@@ -45,7 +53,13 @@ export function evaluate({
       'context',
       'event',
       useCode
-    )(builder, builder, state, context, event);
+    )(
+      builder,
+      builder,
+      flattenState(rootState, localState, rootSetState),
+      context,
+      event
+    );
   } catch (e) {
     console.warn(
       'Builder custom code error: \n While Evaluating: \n ',
@@ -55,3 +69,31 @@ export function evaluate({
     );
   }
 }
+
+export function flattenState(
+  rootState: Record<string | symbol, any>,
+  localState: Record<string | symbol, any> | undefined,
+  rootSetState: ((rootState: BuilderRenderState) => void) | undefined
+): BuilderRenderState {
+  if (rootState === localState) {
+    throw new Error('rootState === localState');
+  }
+  return new Proxy(rootState, {
+    get: (_, prop) => {
+      if (localState && prop in localState) {
+        return localState[prop];
+      }
+      return rootState[prop as string];
+    },
+    set: (_, prop, value) => {
+      if (localState && prop in localState) {
+        throw new Error(
+          'Writing to local state is not allowed as it is read-only.'
+        );
+      }
+      rootState[prop as string] = value;
+      rootSetState?.(rootState);
+      return true;
+    },
+  });
+}

package/src/functions/get-block-actions-handler.ts

@@ -4,7 +4,10 @@ import { evaluate } from './evaluate.js';
 
 type Options = {
   block: BuilderBlock;
-} & Pick<BuilderContextInterface, 'state' | 'context'>;
+} & Pick<
+  BuilderContextInterface,
+  'localState' | 'context' | 'rootState' | 'rootSetState'
+>;
 
 type EventHandler = (event: Event) => any;
 
@@ -14,7 +17,9 @@ export const createEventHandler =
     evaluate({
       code: value,
       context: options.context,
-      state: options.state,
+      localState: options.localState,
+      rootState: options.rootState,
+      rootSetState: options.rootSetState,
       event,
       isExpression: false,
     });

package/src/functions/get-block-actions.ts

@@ -8,7 +8,10 @@ type Actions = { [index: string]: (event: Event) => any };
 export function getBlockActions(
   options: {
     block: BuilderBlock;
-  } & Pick<BuilderContextInterface, 'state' | 'context'>
+  } & Pick<
+    BuilderContextInterface,
+    'localState' | 'context' | 'rootState' | 'rootSetState'
+  >
 ): Actions {
   const obj: Actions = {};
   const optionActions = options.block.actions ?? {};

package/src/functions/get-content/generate-content-url.test.ts

@@ -92,4 +92,21 @@ describe('Generate Content URL', () => {
       `Invalid apiVersion: expected 'v2' or 'v3', received 'INVALID_API_VERSION'`
     );
   });
+
+  test('generate content url with enrich option true', () => {
+    const output = generateContentUrl({
+      apiKey: testKey,
+      model: testModel,
+      enrich: true,
+    });
+    expect(output).toMatchSnapshot();
+  });
+
+  test('generate content url with enrich option not present', () => {
+    const output = generateContentUrl({
+      apiKey: testKey,
+      model: testModel,
+    });
+    expect(output).toMatchSnapshot();
+  });
 });

package/src/functions/get-content/generate-content-url.ts

@@ -15,6 +15,7 @@ export const generateContentUrl = (options: GetContentOptions): URL => {
     model,
     apiKey,
     includeRefs = true,
+    enrich,
     locale,
     apiVersion = DEFAULT_API_VERSION,
   } = options;
@@ -32,7 +33,7 @@ export const generateContentUrl = (options: GetContentOptions): URL => {
   const url = new URL(
     `https://cdn.builder.io/api/${apiVersion}/content/${model}?apiKey=${apiKey}&limit=${limit}&noTraverse=${noTraverse}&includeRefs=${includeRefs}${
       locale ? `&locale=${locale}` : ''
-    }`
+    }${enrich ? `&enrich=${enrich}` : ''}`
   );
 
   const queryOptions = {

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

@@ -1,60 +1,91 @@
+import { TARGET } from '../../constants/target.js';
+import { handleABTesting } from '../../helpers/ab-tests.js';
+import { getDefaultCanTrack } from '../../helpers/canTrack.js';
 import { logger } from '../../helpers/logger.js';
 import type { BuilderContent } from '../../types/builder-content.js';
 import { fetch } from '../get-fetch.js';
-import { handleABTesting } from './ab-testing.js';
+import { isBrowser } from '../is-browser.js';
 import { generateContentUrl } from './generate-content-url.js';
 import type { GetContentOptions } from './types.js';
 
+const checkContentHasResults = (
+  content: ContentResponse
+): content is ContentResults => 'results' in content;
+
 export async function getContent(
   options: GetContentOptions
 ): Promise<BuilderContent | null> {
   const allContent = await getAllContent({ ...options, limit: 1 });
-  if (allContent && 'results' in allContent) {
-    return allContent?.results[0] || null;
+  if (allContent && checkContentHasResults(allContent)) {
+    return allContent.results[0] || null;
   }
 
   return null;
 }
 
+type ContentResults = {
+  results: BuilderContent[];
+};
+
 type ContentResponse =
-  | {
-      results: BuilderContent[];
-    }
+  | ContentResults
   | {
       status: number;
       message: string;
     };
 
+const fetchContent = async (options: GetContentOptions) => {
+  const url = generateContentUrl(options);
+
+  const res = await fetch(url.href);
+  const content = await (res.json() as Promise<ContentResponse>);
+  return content;
+};
+
+/**
+ * Exported only for testing purposes. Should not be used directly.
+ */
+export const processContentResult = async (
+  options: GetContentOptions,
+  content: ContentResults
+) => {
+  const canTrack = getDefaultCanTrack(options.canTrack);
+
+  if (!canTrack) return content;
+  if (!(isBrowser() || TARGET === 'reactNative')) return content;
+
+  /**
+   * For client-side navigations, it is ideal to handle AB testing at this point instead of using our
+   * complex multi-rendering variants approach, which is only needed for SSR'd content.
+   *
+   * This is also where react-native would handle AB testing.
+   */
+  try {
+    const newResults: BuilderContent[] = [];
+    for (const item of content.results) {
+      newResults.push(await handleABTesting({ item, canTrack }));
+    }
+    content.results = newResults;
+  } catch (e) {
+    logger.error('Could not process A/B tests. ', e);
+  }
+
+  return content;
+};
+
 export async function getAllContent(
   options: GetContentOptions
 ): Promise<ContentResponse | null> {
   try {
     const url = generateContentUrl(options);
+    const content = await fetchContent(options);
 
-    const res = await fetch(url.href);
-    const content = await (res.json() as Promise<ContentResponse>);
-
-    if ('status' in content && !('results' in content)) {
+    if (!checkContentHasResults(content)) {
       logger.error('Error fetching data. ', { url, content, options });
       return content;
     }
 
-    const canTrack = options.canTrack !== false;
-    try {
-      if (
-        canTrack &&
-        // This makes sure we have a non-error response with the results array.
-        Array.isArray(content.results)
-      ) {
-        for (const item of content.results) {
-          await handleABTesting({ item, canTrack });
-        }
-      }
-    } catch (e) {
-      logger.error('Could not setup A/B testing. ', e);
-    }
-
-    return content;
+    return processContentResult(options, content);
   } catch (error) {
     logger.error('Error fetching data. ', error);
     return null;

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/functions/get-processed-block.test.ts

@@ -21,7 +21,9 @@ test('Can process bindings', () => {
   const processed = getProcessedBlock({
     block,
     context: {},
-    state: { test: 'hello' },
+    rootState: { test: 'hello' },
+    rootSetState: undefined,
+    localState: undefined,
     shouldEvaluateBindings: true,
   });
   expect(processed).not.toEqual(block);

package/src/functions/get-processed-block.ts

@@ -8,10 +8,15 @@ import { transformBlock } from './transform-block.js';
 const evaluateBindings = ({
   block,
   context,
-  state,
+  localState,
+  rootState,
+  rootSetState,
 }: {
   block: BuilderBlock;
-} & Pick<BuilderContextInterface, 'state' | 'context'>): BuilderBlock => {
+} & Pick<
+  BuilderContextInterface,
+  'localState' | 'context' | 'rootState' | 'rootSetState'
+>): BuilderBlock => {
   if (!block.bindings) {
     return block;
   }
@@ -24,7 +29,13 @@ const evaluateBindings = ({
 
   for (const binding in block.bindings) {
     const expression = block.bindings[binding];
-    const value = evaluate({ code: expression, state, context });
+    const value = evaluate({
+      code: expression,
+      localState,
+      rootState,
+      rootSetState,
+      context,
+    });
     set(copied, binding, value);
   }
 
@@ -35,7 +46,9 @@ export function getProcessedBlock({
   block,
   context,
   shouldEvaluateBindings,
-  state,
+  localState,
+  rootState,
+  rootSetState,
 }: {
   block: BuilderBlock;
   /**
@@ -43,11 +56,20 @@ export function getProcessedBlock({
    * also sometimes too early to consider bindings, e.g. when we might be looking at a repeated block.
    */
   shouldEvaluateBindings: boolean;
-} & Pick<BuilderContextInterface, 'state' | 'context'>): BuilderBlock {
+} & Pick<
+  BuilderContextInterface,
+  'localState' | 'context' | 'rootState' | 'rootSetState'
+>): BuilderBlock {
   const transformedBlock = transformBlock(block);
 
   if (shouldEvaluateBindings) {
-    return evaluateBindings({ block: transformedBlock, state, context });
+    return evaluateBindings({
+      block: transformedBlock,
+      localState,
+      rootState,
+      rootSetState,
+      context,
+    });
   } else {
     return transformedBlock;
   }

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,24 @@
 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 { 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';