@croct/plug-react 0.4.2 → 0.5.0-next.2

package/README.md

@@ -23,7 +23,8 @@
 
 ## Introduction
 
-The React Plug library provides components and hooks for personalizing applications in real-time that are easy for your marketing team to scale and maintain.
+The React Plug library provides components and hooks for personalizing applications in real-time that are easy for your
+marketing team to scale and maintain.
 
 - **Easy integration**: personalize existing components without touching their code.
 - **Suspense-ready**: take advantage of the latest React features to improve user experience.
@@ -68,32 +69,33 @@ import {render} from 'react-dom';
 import {CroctProvider} from '@croct/plug-react';
 
 function App() {
-  return (
-    <CroctProvider appId="<APP_ID>">
-      <div>
-        <h1>My first personalized app 🚀</h1>
-      </div>
-    </CroctProvider>
-  );
+    return (
+        <CroctProvider appId="<APP_ID>">
+            <div>
+                <h1>My first personalized app 🚀</h1>
+            </div>
+        </CroctProvider>
+    );
 }
 
-render(<App />, document.getElementById('root'));
+render(<App/>, document.getElementById('root'));
 ```
 
 > Replace `<APP_ID>` with your public app ID that you can find at Workspaces > Applications > Setup.
 > In case you don't have an account yet, you can use the sandbox application ID `00000000-0000-0000-0000-000000000000`
 
-### Evaluating expressions
+### Evaluating queries
 
 Once your application is plugged in, you're ready to start personalizing your components using the `<Personalization />`
 component or the `useEvaluation` hook.
 
-We'll go through a simple example that shows how  you can implement feature flags (also known as feature toggles)
+We'll go through a simple example that shows how you can implement feature flags (also known as feature toggles)
 to conditionally renders a different button depending on the user's persona.
 
 ![Evaluation Example](https://user-images.githubusercontent.com/943036/116588852-6a114200-a8f2-11eb-9d88-c346f002e2a1.png)
 
-Let's first implement the use-case using the `<Personalization />` component. It takes an expression (e.g. `user's persona`)
+Let's first implement the use-case using the `<Personalization />` component. It takes an query (
+e.g. `user's persona`)
 and a render function, which tells the component how to render the UI, depending on the evaluation result.
 
 This is what our component would look like:
@@ -105,7 +107,7 @@ import {Personalization} from '@croct/plug-react';
 function OnboardingPage(): ReactElement {
     return (
         <Suspense fallback="✨ Personalizing...">
-            <Personalization expression="user's persona is not 'developer'">
+            <Personalization query="user's persona is not 'developer'">
                 {(isDeveloper: boolean) => isDeveloper
                     ? <a href="/docs">View docs</a>
                     : <a href="/share">Share with your developer</a>
@@ -124,7 +126,7 @@ import {Personalization} from '@croct/plug-react';
 
 function OnboardingPage(): ReactElement {
     return (
-        <Personalization expression="user's persona is not 'developer'" initial={false}>
+        <Personalization query="user's persona is not 'developer'" initial={false}>
             {(isDeveloper: boolean) => isDeveloper
                 ? <a href="/docs">View docs</a>
                 : <a href="/share">Share with your developer</a>
@@ -153,7 +155,7 @@ function ViewDocsLink(): ReactElement {
 export default function OnboardingPage(): ReactElement {
     return (
         <Suspense fallback="✨ Personalizing...">
-            <ViewDocsLink />
+            <ViewDocsLink/>
         </Suspense>
     )
 }
@@ -166,8 +168,8 @@ user's profile.
 
 #### Fault tolerance
 
-We strongly recommend specifying the `fallback` property in client-side rendered applications to ensure your app behaves 
-the same way regardless of the personalization. In this way, the UI will still be fully functional even in maintenance 
+We strongly recommend specifying the `fallback` property in client-side rendered applications to ensure your app behaves
+the same way regardless of the personalization. In this way, the UI will still be fully functional even in maintenance
 windows. **Specifying a `fallback` is required for server-side rendering (SSR).**
 
 The following example shows how you can specify a fallback behaviour for the docs link:
@@ -186,7 +188,7 @@ export default function OnboardingPage(): ReactElement {
     return (
         <Suspense fallback="✨ Personalizing...">
             {/* Using the <Personalization /> component */}
-            <Personalization expression="user's persona is 'developer'" fallback={false}>
+            <Personalization query="user's persona is 'developer'" fallback={false}>
                 {(isDeveloper: boolean) => (
                     <Fragment>
                         {isDeveloper && <a href="/docs">View docs</a>}
@@ -195,7 +197,7 @@ export default function OnboardingPage(): ReactElement {
             </Personalization>
 
             {/* Using useEvaluation hook */}
-            <ViewDocsLink />
+            <ViewDocsLink/>
         </Suspense>
     )
 }
@@ -205,7 +207,7 @@ For a full list of the available options, please refer to the [API documentation
 
 ### Using slots
 
-Evaluating expression is a flexible and powerful way to customize your UI. However, for components whose content
+Evaluating query is a flexible and powerful way to customize your UI. However, for components whose content
 changes too often, this approach can be overkill. For those cases, we encourage you to use the Slots feature instead.
 Using slots gives your team the flexibility to change the content or personalization rules whenever needed without
 touching the component code.
@@ -240,19 +242,23 @@ import {ReactElement, Suspense} from 'react';
 import {Slot} from '@croct/plug-react';
 
 type HomeBannerContent = {
-  title: string,
-  subtitle: string,
-  cta: {
-      label: string,
-      link: string,
-  },
+    title: string,
+    subtitle: string,
+    cta: {
+        label: string,
+        link: string,
+    },
 };
 
 export default function OnboardingPage(): ReactElement {
     return (
         <Suspense fallback="✨ Personalizing content...">
             <Slot id="home-banner">
-                {({title, subtitle, cta}: HomeBannerContent) => (
+                {({
+                    title,
+                    subtitle,
+                    cta
+                }: HomeBannerContent) => (
                     <div>
                         <strong>{title}</strong>
                         <p>{subtitle}</p>
@@ -272,26 +278,26 @@ import {ReactElement} from 'react';
 import {Slot} from '@croct/plug-react';
 
 type HomeBannerContent = {
-  title: string,
-  subtitle: string,
-  cta: {
-      label: string,
-      link: string,
-  },
+    title: string,
+    subtitle: string,
+    cta: {
+        label: string,
+        link: string,
+    },
 };
 
 export default function OnboardingPage(): ReactElement {
     return (
         <Slot id="home-banner" initial={null}>
-            {(props: HomeBannerContent|null) => (
-                props === null 
+            {(props: HomeBannerContent | null) => (
+                props === null
                     ? '✨ Personalizing...'
                     : (
                         <div>
                             <strong>{props.title}</strong>
                             <p>{props.subtitle}</p>
                             <a href={props.cta.link}>{props.cta.label}</a>
-                        </div>    
+                        </div>
                     )
             )}
         </Slot>
@@ -306,16 +312,20 @@ import {ReactElement, Suspense} from 'react';
 import {useContent} from '@croct/plug-react';
 
 type HomeBannerContent = {
-  title: string,
-  subtitle: string,
-  cta: {
-      label: string,
-      link: string,
-  },
+    title: string,
+    subtitle: string,
+    cta: {
+        label: string,
+        link: string,
+    },
 };
 
 function HomeBanner(): ReactElement {
-    const {title, subtitle, cta} = useContent<HomeBannerContent>('home-banner');
+    const {
+        title,
+        subtitle,
+        cta
+    } = useContent<HomeBannerContent>('home-banner');
 
     return (
         <div>
@@ -335,6 +345,15 @@ export default function HomePage(): ReactElement {
 }
 ```
 
+You can specify the version of the slot by passing a versioned ID in the form `id@version`. For example,
+passing `home-banner@1` will fetch the content for the `home-banner` slot in version 1. Not specifying a
+version number is the same as passing `home-banner@latest`, which will load the latest version of the slot.
+
+> ✅ Best practice  
+> It's strongly recommended to specify a slot version for production deployments.
+> That way, you ensure the front end will always receive content with the expected
+> schema while your team can freely evolve the content's schema in parallel.
+
 #### Fault tolerance
 
 The following example shows how you can specify a fallback state for the `home-banner` slot:
@@ -344,12 +363,12 @@ import {ReactElement, Suspense} from 'react';
 import {Slot, useContent} from '@croct/plug-react';
 
 type HomeBannerContent = {
-  title: string,
-  subtitle: string,
-  cta: {
-      label: string,
-      link: string,
-  },
+    title: string,
+    subtitle: string,
+    cta: {
+        label: string,
+        link: string,
+    },
 };
 
 const fallbackBanner: HomeBannerContent = {
@@ -362,7 +381,11 @@ const fallbackBanner: HomeBannerContent = {
 };
 
 function HomeBanner(): ReactElement {
-    const {title, subtitle, cta} = useContent<HomeBannerContent>('home-banner', {fallback: fallbackBanner});
+    const {
+        title,
+        subtitle,
+        cta
+    } = useContent<HomeBannerContent>('home-banner', {fallback: fallbackBanner});
 
     return (
         <div>
@@ -378,7 +401,11 @@ export default function HomePage(): ReactElement {
         <Suspense fallback="Personalizing content...">
             {/* Using the <Slot /> component */}
             <Slot id="home-banner" fallback={fallbackBanner}>
-                {({title, subtitle, cta}: HomeBannerContent) => (
+                {({
+                    title,
+                    subtitle,
+                    cta
+                }: HomeBannerContent) => (
                     <div>
                         <strong>{title}</strong>
                         <p>{subtitle}</p>
@@ -388,13 +415,14 @@ export default function HomePage(): ReactElement {
             </Slot>
 
             {/* Using the useContent hook */}
-            <HomeBanner />
+            <HomeBanner/>
         </Suspense>
     )
 }
 ```
 
-Again, we strongly recommend always providing a value for the `fallback` property. For a full list of the available options,
+Again, we strongly recommend always providing a value for the `fallback` property. For a full list of the available
+options,
 please refer to the [API documentation](#component-api-reference).
 
 #### 💡 ProTip
@@ -407,11 +435,10 @@ using module augmentation as follows:
 
 ```ts
 // slots.d.ts
-import {NullableJsonObject} from '@croct/plug/sdk/json';
 import {HomeBanner} from './HomePage';
 
-declare module '@croct/plug/fetch' {
-    interface SlotMap extends Record<string, NullableJsonObject> {
+declare module '@croct/plug/slot' {
+    interface SlotMap {
         'home-banner': HomeBanner;
     }
 }
@@ -428,12 +455,15 @@ You can use the same components and hooks on the server-side by simply providing
 pre-render on the server - the personalization happens transparently on the client during the initial render.
 That means it's SEO friendly and can be cached with no performance overhead.
 
-Notice that the methods exposed by the Plug work only on the client-side. Therefore, if you are using [`useCroct`](#usecroct),
-the operations have to be executed inside the `useEffect` hook or client-side callbacks, such as `onClick` or `onChange`, for example.
+Notice that the methods exposed by the Plug work only on the client-side. Therefore, if you are
+using [`useCroct`](#usecroct),
+the operations have to be executed inside the `useEffect` hook or client-side callbacks, such as `onClick` or `onChange`
+, for example.
 
 ### Accessing the Plug instance
 
-This library is built on top of the PlugJS. You can access the Plug instance through the `useCroct` hook to track events,
+This library is built on top of the PlugJS. You can access the Plug instance through the `useCroct` hook to track
+events,
 login and logout users, and more.
 
 In the following example we use the `useCroct` to get the Plug instance and set an attribute to the user profile:
@@ -461,7 +491,7 @@ This reference documents all components available in the library.
 
 ### &lt;CroctProvider /&gt;
 
-The `<CroctProvider />` component  leverages [React's Context API](https://reactjs.org/docs/context.html) to 
+The `<CroctProvider />` component leverages [React's Context API](https://reactjs.org/docs/context.html) to
 make a configured [Plug instance](https://github.com/croct-tech/plug-js/blob/master/docs/plug.md) available throughout
 a React component tree.
 
@@ -471,18 +501,19 @@ The component takes the followings properties:
 
 | Option                  | Type         | Required | Default Value | Description                                                                                                                                                                                               |
 |-------------------------|--------------|----------|---------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `appId`                 | string       | Yes      | None          | The ID of the application you set up on Croct.
+| `appId`                 | string       | Yes      | None          | The ID of the application you set up on Croct.                                                                                                                                                            |
 | `debug`                 | boolean      | No       | `false`       | If `true`, turns on debug mode, which logs helpful messages to the console.                                                                                                                               |
-| `track`                 | boolean      | No       | `true`        | If `true`, enables the automatic event tracking on initialization.
-| `token`                 | string\|null | No       | None          | The JWT token issued by Croct. If `null`, clears any token specified on previous calls.
-| `userId`                | string       | No       | None          | The ID of the user logged into the application. Internally, the SDK will issue a token using the specified ID as the subject claim of the token. The `token` and `userId` options are mutually exclusive.
-| `tokenScope`            | string       | No       | `global`      | Defines how the SDK should synchronize the token across multiple tabs, see [token scopes](#token-scopes) for more details.
-| `eventMetadata`         | JSON         | No       | None          | Any additional information that may be useful to include as part of the event metadata. A common use case is to record the version of the application for future reference.
-| `logger`                | object       | No       | None          | A custom logger to handle log messages. By default, all logs are suppressed.
-| `urlSanitizer`          | function     | No       | None          | A function to sanitize URLs that allows removing sensitive information from URLs, such as tokens, that should not be sent to the platform.
-| `trackerEndpointUrl`    | string       | No       | None          | The URL of the tracker service, used by Croct's development team for testing purposes.
-| `evaluationEndpointUrl` | string       | No       | None          | The URL of the evaluation service, used by Croct's development team for testing purposes.
-| `bootstrapEndpointUrl`  | string       | No       | None          | The URL of the bootstrap service, used by Croct's development team for testing purposes.
+| `track`                 | boolean      | No       | `true`        | If `true`, enables the automatic event tracking on initialization.                                                                                                                                        |
+| `clientId`              | string       | No       | None          | The ID of the client using the application.                                                                                                                                                               |
+| `token`                 | string\|null | No       | None          | The JWT token issued by Croct. If `null`, clears any token specified on previous calls.                                                                                                                   |
+| `userId`                | string       | No       | None          | The ID of the user logged into the application. Internally, the SDK will issue a token using the specified ID as the subject claim of the token. The `token` and `userId` options are mutually exclusive. |
+| `tokenScope`            | string       | No       | `global`      | Defines how the SDK should synchronize the token across multiple tabs, see [token scopes](#token-scopes) for more details.                                                                                |
+| `eventMetadata`         | JSON         | No       | None          | Any additional information that may be useful to include as part of the event metadata. A common use case is to record the version of the application for future reference.                               |
+| `logger`                | object       | No       | None          | A custom logger to handle log messages. By default, all logs are suppressed.                                                                                                                              |
+| `urlSanitizer`          | function     | No       | None          | A function to sanitize URLs that allows removing sensitive information from URLs, such as tokens, that should not be sent to the platform.                                                                |
+| `trackerEndpointUrl`    | string       | No       | None          | The URL of the tracker service, used by Croct's development team for testing purposes.                                                                                                                    |
+| `evaluationEndpointUrl` | string       | No       | None          | The URL of the evaluation service, used by Croct's development team for testing purposes.                                                                                                                 |
+| `bootstrapEndpointUrl`  | string       | No       | None          | The URL of the bootstrap service, used by Croct's development team for testing purposes.                                                                                                                  |
 
 #### Code Sample
 
@@ -512,16 +543,16 @@ The `<Personalization />` component evaluates and renders a CQL query.
 
 The component takes the followings properties:
 
-| Option       | Type     | Required | Description
-|--------------|----------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
-| `expression` | string   | Yes      | The CQL query to evaluate.
-| `children`   | Function | Yes      | A callback to render the result.
-| `fallback`   | Result   | No       | A value to render when the evaluation fails. If not specified, the hook will throw an exception in case of failures.
-| `initial`    | Result   | SSR only | A value to render while loading, required for server-side rendering. If not specified, the rendering will suspend.
-| `timeout`    | number   | No       | The maximum evaluation time in milliseconds. Once reached, the evaluation will fail.
-| `attributes` | JSON     | No       | A map of attributes to inject in the evaluation context. For example, passing the attributes `{cities: ['New York', 'San Francisco']}` you can reference them in expressions like `context's cities include location's city`.
-| `cacheKey`   | string   | No       | An identifier that allows keeping the cached result separate from other cached items. By default, the cache key is formed from the expression and attributes.
-| `expiration` | number   | No       | The cache expiration time in milliseconds, extended on every render. If negative, the cache never expires. By default, the cache lifespan is set to 60000 (1 minute).
+| Option       | Type     | Required | Description                                                                                                                                                                                                               |
+|--------------|----------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `query`      | string   | Yes      | The CQL query to evaluate.                                                                                                                                                                                                |
+| `children`   | Function | Yes      | A callback to render the result.                                                                                                                                                                                          |
+| `fallback`   | Result   | No       | A value to render when the evaluation fails. If not specified, the hook will throw an exception in case of failures.                                                                                                      |
+| `initial`    | Result   | SSR only | A value to render while loading, required for server-side rendering. If not specified, the rendering will suspend.                                                                                                        |
+| `timeout`    | number   | No       | The maximum evaluation time in milliseconds. Once reached, the evaluation will fail.                                                                                                                                      |
+| `attributes` | JSON     | No       | A map of attributes to inject in the evaluation context. For example, passing the attributes `{cities: ['New York', 'San Francisco']}` you can reference them in queries like `context's cities include location's city`. |
+| `cacheKey`   | string   | No       | An identifier that allows keeping the cached result separate from other cached items. By default, the cache key is formed from the query and attributes.                                                                  |
+| `expiration` | number   | No       | The cache expiration time in milliseconds, extended on every render. If negative, the cache never expires. By default, the cache lifespan is set to 60000 (1 minute).                                                     |
 
 #### Code Sample
 
@@ -533,7 +564,7 @@ import {Personalization} from '@croct/plug-react';
 
 function PersonaBadge(): ReactElement {
     return (
-        <Personalization expression="user's persona or else 'unknown'">
+        <Personalization query="user's persona or else 'unknown'">
             {persona => (<span>{persona}</span>)}
         </Personalization>
     );
@@ -548,14 +579,15 @@ The `<Slot />` component fetches and renders a slot.
 
 The component takes the followings properties:
 
-| Option       | Type     | Required | Description
-|--------------|----------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
-| `id`         | string   | Yes      | The ID of the slot to fetch.
-| `children`   | Function | Yes      | A callback to render the result.
-| `fallback`   | Result   | No       | A value to render when the fetch fails. If not specified, the hook will throw an exception in case of failures.
-| `initial`    | Result   | SSR only | A value to render while loading, required for server-side rendering. If not specified, the rendering will suspend.
-| `cacheKey`   | string   | No       | An identifier that allows keeping the cached result separate from other cached items. By default, the cache key is formed from the expression and attributes.
-| `expiration` | number   | No       | The cache expiration time in milliseconds, extended on every render. If negative, the cache never expires. By default, the cache lifespan is set to 60000 (1 minute).
+| Option            | Type     | Required | Description                                                                                                                                                           |
+|-------------------|----------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `id`              | string   | Yes      | The ID of the slot to fetch.                                                                                                                                          |
+| `children`        | Function | Yes      | A callback to render the result.                                                                                                                                      |
+| `fallback`        | Result   | No       | A value to render when the fetch fails. If not specified, the hook will throw an exception in case of failures.                                                       |
+| `preferredLocale` | string   | No       | The preferred locale to fetch. If not specified or not available, the hook will fetch the default locale.                                                             |
+| `initial`         | Result   | SSR only | A value to render while loading, required for server-side rendering. If not specified, the rendering will suspend.                                                    |
+| `cacheKey`        | string   | No       | An identifier that allows keeping the cached result separate from other cached items. By default, the cache key is formed from the query and attributes.              |
+| `expiration`      | number   | No       | The cache expiration time in milliseconds, extended on every render. If negative, the cache never expires. By default, the cache lifespan is set to 60000 (1 minute). |
 
 #### Code Sample
 
@@ -568,7 +600,10 @@ import {Slot} from '@croct/plug-react';
 function HeroBanner(): ReactElement {
     return (
         <Slot id="hero">
-            {({title, subtitle}) => (
+            {({
+                title,
+                subtitle
+            }) => (
                 <div>
                     <h1>{title}</h1>
                     <p>{subtitle}</p>
@@ -620,18 +655,18 @@ The `useEvaluation` hook evaluates a CQL query.
 The hook has the following signature:
 
 ```ts
- function useEvaluation<Result extends JsonValue>(expression: string, options: Options = {}): Result
+ function useEvaluation<Result extends JsonValue>(query: string, options: Options = {}): Result
 ```
 
 These are the currently supported options:
 
-| Option       | Type    | Description
-|--------------|---------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
-| `fallback`   | Result  | The value returned when the evaluation fails. If not specified, the hook will throw an exception in case of failures.
-| `timeout`    | number  | The maximum evaluation time in milliseconds. Once reached, the evaluation will fail.
-| `attributes` | JSON    | The map of attributes to inject in the evaluation context. For example, passing the attributes `{cities: ['New York', 'San Francisco']}` you can reference them in expressions like `context's cities include location's city`.
-| `cacheKey`   | string  | An identifier that allows keeping the cached result separate from other cached items. By default, the cache key is formed from the expression and attributes.
-| `expiration` | number  | The cache expiration time in milliseconds, extended on every render. If negative, the cache never expires. By default, the cache lifespan is set to 60000 (1 minute).
+| Option       | Type   | Description                                                                                                                                                                                                                |
+|--------------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `fallback`   | Result | The value returned when the evaluation fails. If not specified, the hook will throw an exception in case of failures.                                                                                                      |
+| `timeout`    | number | The maximum evaluation time in milliseconds. Once reached, the evaluation will fail.                                                                                                                                       |
+| `attributes` | JSON   | The map of attributes to inject in the evaluation context. For example, passing the attributes `{cities: ['New York', 'San Francisco']}` you can reference them in querys like `context's cities include location's city`. |
+| `cacheKey`   | string | An identifier that allows keeping the cached result separate from other cached items. By default, the cache key is formed from the query and attributes.                                                                   |
+| `expiration` | number | The cache expiration time in milliseconds, extended on every render. If negative, the cache never expires. By default, the cache lifespan is set to 60000 (1 minute).                                                      |
 
 #### Code Sample
 
@@ -657,16 +692,18 @@ The `useContent` hook fetches the content of a slot.
 The hook has the following signature:
 
 ```ts
-function useContent<Content extends NullableJsonObject>(slotId: string, options: Options = {}): Content
+function useContent(slotId: string, options: Options = {}): JsonObject
 ```
 
 These are the currently supported options:
 
-| Option       | Type    | Description
-|--------------|---------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
-| `fallback`   | Content | The content returned when the fetch fails. If not specified, the hook will throw an exception in case of failures.
-| `cacheKey`   | string  | An identifier that allows keeping the cached content separate from other cached items. By default, the cache key is formed from the slot ID.
-| `expiration` | number  | The cache expiration time in milliseconds, extended on every render. If negative, the cache never expires. By default, the cache lifespan is set to 60000 (1 minute).
+| Option            | Type    | Description                                                                                                                                                           |
+|-------------------|---------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `fallback`        | Content | The content returned when the fetch fails. If not specified, the hook will throw an exception in case of failures.                                                    |
+| `preferredLocale` | string  | The preferred locale to fetch. If not specified or not available, the hook will fetch the default locale.                                                             |
+| `cacheKey`        | string  | An identifier that allows keeping the cached content separate from other cached items. By default, the cache key is formed from the slot ID.                          |
+| `expiration`      | number  | The cache expiration time in milliseconds, extended on every render. If negative, the cache never expires. By default, the cache lifespan is set to 60000 (1 minute). |
+
 
 #### Code Sample
 
@@ -686,7 +723,10 @@ type HomeBannerContent = {
 };
 
 export default function HeroBanner(): ReactElement {
-    const {title, subtitle} = useContent<HomeBannerContent>('hero');
+    const {
+        title,
+        subtitle
+    } = useContent<HomeBannerContent>('hero');
 
     return (
         <div>
@@ -697,6 +737,103 @@ export default function HeroBanner(): ReactElement {
 }
 ```
 
+## Standalone function reference
+
+This reference documents all standalone functions available in the library.
+
+### evaluate
+
+The `evaluate` function evaluates a CQL query on the server-side and returns the result.
+
+#### Signature
+
+The function has the following signature:
+
+```ts
+function evaluate(query: string, options: EvaluationOptions): Promise<JsonValue>
+```
+
+These are the currently supported options:
+
+| Option                     | Type   | Required | Description                                                                                                                                                                                                                                                                                                                                |
+|----------------------------|--------|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `apiKey`                   | string | Yes      | The private API key of the application. This is a private key that should never be exposed to the client-side.                                                                                                                                                                                                                             |
+| `fallback`                 | JSON   | No       | The value returned when the evaluation fails. If not specified, the function will throw an exception in case of failures.                                                                                                                                                                                                                  |
+| `timeout`                  | number | No       | The maximum evaluation time in milliseconds. Once reached, the evaluation will fail.                                                                                                                                                                                                                                                       | 
+| `clientId`                 | string | No       | A UUID v4 that uniquely identifies the client across multiple evaluations. You should generate this identifier on your server-side using a random, cryptographically secure generator and ensure it doesn't change throughout the user journey (e.g. store in cookies). If not specified, the evaluation will run in an anonymous context. |
+ | `clientIp`                 | string | No       | The IP address of the client to determine the location. The IP is only used to determine the location and then discarded.                                                                                                                                                                                                                  |
+ | `userAgent`                | string | No       | The user agent of the client to determine the device.                                                                                                                                                                                                                                                                                      |
+ | `userToken`                | string | No       | The token that uniquely identifies the user. You can use this to provide consistent experiences across multiple channels.                                                                                                                                                                                                                  |
+| `context`                  | JSON   | No       | The evaluation context.                                                                                                                                                                                                                                                                                                                    |
+ | `context.timeZone`         | string | No       | The time zone of the client.                                                                                                                                                                                                                                                                                                               |
+ | `context.campaign`         | JSON   | No       | The marketing campaign that brought the user to the application.                                                                                                                                                                                                                                                                           |
+ | `context.campaign.name`    | string | No       | The name of the campaign.                                                                                                                                                                                                                                                                                                                  |
+ | `context.campaign.source`  | string | No       | The source of the campaign. For example, "google", "newsletter", "facebook".                                                                                                                                                                                                                                                               |
+ | `context.campaign.medium`  | string | No       | The marketing medium. For example, "cpc", "banner", "ads".                                                                                                                                                                                                                                                                                 |
+ | `context.campaign.term`    | string | No       | The campaign keywords. For example, "smartphone online sale".                                                                                                                                                                                                                                                                              |
+ | `context.campaign.content` | string | No       | The campaign content. For example, "top-banner", "cta", "sidebar".                                                                                                                                                                                                                                                                         |
+ | `context.page`             | JSON   | No       | The page the user is currently viewing.                                                                                                                                                                                                                                                                                                    |
+ | `context.page.url`         | string | Yes      | The URL of the page.                                                                                                                                                                                                                                                                                                                       |
+ | `context.page.title`       | string | No       | The title of the page.                                                                                                                                                                                                                                                                                                                     |
+ | `context.page.referrer`    | string | No       | The URL of the page that referred the user to the current page.                                                                                                                                                                                                                                                                            |
+ | `context.attributes`       | JSON   | No       | The map of attributes to inject in the evaluation context. For example, passing the attributes `{cities: ['New York', 'San Francisco']}` you can reference them in querys like `context's cities include location's city`.                                                                                                                 |
+ | `extra`                    | JSON   | No       | Additional [options](https://developer.mozilla.org/en-US/docs/Web/API/fetch#parameters) to pass to the fetch function.                                                                                                                                                                                                               |
+
+#### Code Sample
+
+Here's a simple example showing how to evaluate a CQL query:
+
+```ts
+import {evaluate} from '@croct/plug/api';
+
+const result = await evaluate("user's persona", {
+    apiKey: process.env.CROCT_API_KEY,
+});
+```
+
+### fetchContent
+
+The `fetchContent` function fetches the content for a slot on the server-side and returns the result.
+
+#### Signature
+
+The function has the following signature:
+
+```ts
+function fetchContent(slotId: string, options: FetchOptions): Promise<{content: JsonValue}>
+```
+
+These are the currently supported options:
+
+
+| Option                     | Type    | Required | Description                                                                                                                                                                                                                                                                                                                                |
+|----------------------------|---------|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `apiKey`                   | string  | Yes      | The private API key of the application. This is a private key that should never be exposed to the client-side.                                                                                                                                                                                                                             |
+| `fallback`                 | JSON    | No       | The value returned when the fetch fails. If not specified, the function will throw an exception in case of failures.                                                                                                                                                                                                                       |
+| `static`                   | boolean | No       | Whether to fetch the static content. If not specified, the function will fetch the dynamic content.                                                                                                                                                                                                                                        |
+| `timeout`                  | number  | No       | The maximum fetch time in milliseconds. Once reached, the fetch will fail.                                                                                                                                                                                                                                                                 |
+ | `previewToken`             | string  | No       | The token that enables preview mode.                                                                                                                                                                                                                                                                                                       |
+| `preferredLocale`          | string  | No       | The preferred locale to fetch. If not specified or not available, the hook will fetch the default locale.                                                                                                                                                                                                                                  |
+| `clientId`                 | string  | No       | A UUID v4 that uniquely identifies the client across multiple evaluations. You should generate this identifier on your server-side using a random, cryptographically secure generator and ensure it doesn't change throughout the user journey (e.g. store in cookies). If not specified, the evaluation will run in an anonymous context. |
+| `clientIp`                 | string  | No       | The IP address of the client to determine the location. The IP is only used to determine the location and then discarded.                                                                                                                                                                                                                  |
+| `userAgent`                | string  | No       | The user agent of the client to determine the device.                                                                                                                                                                                                                                                                                      |
+| `userToken`                | string  | No       | The token that uniquely identifies the user. You can use this to provide consistent experiences across multiple channels.                                                                                                                                                                                                                  |
+| `context`                  | JSON    | No       | The evaluation context.                                                                                                                                                                                                                                                                                                                    |
+| `context.timeZone`         | string  | No       | The time zone of the client.                                                                                                                                                                                                                                                                                                               |
+| `context.campaign`         | JSON    | No       | The marketing campaign that brought the user to the application.                                                                                                                                                                                                                                                                           |
+| `context.campaign.name`    | string  | No       | The name of the campaign.                                                                                                                                                                                                                                                                                                                  |
+| `context.campaign.source`  | string  | No       | The source of the campaign. For example, "google", "newsletter", "facebook".                                                                                                                                                                                                                                                               |
+| `context.campaign.medium`  | string  | No       | The marketing medium. For example, "cpc", "banner", "ads".                                                                                                                                                                                                                                                                                 |
+| `context.campaign.term`    | string  | No       | The campaign keywords. For example, "smartphone online sale".                                                                                                                                                                                                                                                                              |
+| `context.campaign.content` | string  | No       | The campaign content. For example, "top-banner", "cta", "sidebar".                                                                                                                                                                                                                                                                         |
+| `context.page`             | JSON    | No       | The page the user is currently viewing.                                                                                                                                                                                                                                                                                                    |
+| `context.page.url`         | string  | Yes      | The URL of the page.                                                                                                                                                                                                                                                                                                                       |
+| `context.page.title`       | string  | No       | The title of the page.                                                                                                                                                                                                                                                                                                                     |
+| `context.page.referrer`    | string  | No       | The URL of the page that referred the user to the current page.                                                                                                                                                                                                                                                                            |
+| `context.attributes`       | JSON    | No       | The map of attributes to inject in the evaluation context. For example, passing the attributes `{cities: ['New York', 'San Francisco']}` you can reference them in querys like `context's cities include location's city`.                                                                                                                 |
+| `extra`                    | JSON    | No       | Additional [options](https://developer.mozilla.org/en-US/docs/Web/API/fetch#parameters) to pass to the fetch function.                                                                                                                                                                                                                     |
+
+
 ## Support
 
 If this documentation has not answered all your questions, don't worry.
@@ -714,7 +851,8 @@ please [ask a new one](https://stackoverflow.com/questions/ask?tags=croct%20plug
 If you have what looks like a bug, or you would like to make a feature request, please
 [open a new issue on GitHub](https://github.com/croct-tech/plug-react/issues/new/choose).
 
-Before you file an issue, a good practice is to search for issues to see whether others have the same or similar problems.
+Before you file an issue, a good practice is to search for issues to see whether others have the same or similar
+problems.
 If you are unable to find an open issue addressing the problem, then feel free to open a new one.
 
 ### Slack Channel