@storyblok/astro 8.1.0 → 9.0.0

package/README.md

@@ -4,7 +4,7 @@
 
 <h1 align="center">@storyblok/astro</h1>
  <p>
-     The Astro SDK to interact with <a href="http://www.storyblok.com?utm_source=github.com&utm_medium=readme&utm_campaign=storyblok-astro" target="_blank">Storyblok API</a> and enable the <a href="https://www.storyblok.com/docs/guide/essentials/visual-editor?utm_source=github.com&utm_medium=readme&utm_campaign=storyblok-astro" target="_blank">Real-time Visual Editing Experience</a>.
+     The Astro SDK to interact with <a href="https://www.storyblok.com/docs/api/content-delivery/v2" target="_blank">Storyblok API</a> and enable the <a href="https://www.storyblok.com/docs/guides/astro/visual-preview#enable-live-preview-in-the-visual-editor" target="_blank">Real-time Visual Editing Experience</a>.
   </p>
   <br />
 </div>

package/dist/components/StoryblokServerData.astro

@@ -0,0 +1,29 @@
+---
+/**
+ * StoryblokServerData Component
+ *
+ * Pass server-side data to the client that persists across live preview updates.
+ * All props passed to this component will be serialized as JSON and available
+ * to the client via the extraData parameter in getLiveStory().
+ *
+ * Data is automatically sanitized to prevent XSS attacks and script injection.
+ *
+ * @example
+ * ```astro
+ * ---
+ * import { StoryblokServerData } from '@storyblok/astro';
+ * const users = await getUsers();
+ * const config = { apiUrl: 'https://api.example.com' };
+ * ---
+ *
+ * <StoryblokServerData users={users} config={config} />
+ * ```
+ */
+
+import { sanitizeJSON } from '@storyblok/astro';
+
+const props = Astro.props;
+const safeJson = sanitizeJSON(props);
+---
+
+<script is:inline id="__STORYBLOK_SERVERDATA__" type="application/json" set:html={safeJson} />

package/dist/index.d.ts

@@ -1,9 +1,11 @@
 /// <reference path="./public.d.ts" />
 import { default as storyblokIntegration } from './lib/storyblok-integration';
-export { getLiveStory, useStoryblokApi } from './lib/helpers';
+export { getLiveStory, getPayload, useStoryblokApi } from './lib/helpers';
+export { sanitizeJSON } from './lib/sanitizeJSON';
 export type { IntegrationOptions } from './lib/storyblok-integration';
 export { handleStoryblokMessage } from './live-preview/handleStoryblokMessage';
 export * from './types';
+export { isEditorRequest } from './utils/isEditorRequest';
 export { toCamelCase } from './utils/toCamelCase';
 export { loadStoryblokBridge, renderRichText, richTextResolver, segmentStoryblokRichText, storyblokEditable, } from '@storyblok/js';
 export { storyblokIntegration as storyblok };

package/dist/lib/helpers.d.ts

@@ -23,6 +23,9 @@ export declare function useStoryblokApi(): StoryblokClient;
  * This function is primarily useful when working with the Storyblok Visual Editor
  * and live preview updates in an Astro project.
  *
+ * @deprecated Use `getPayload()` instead for better type safety and to access both story and serverData.
+ * @see {@link getPayload}
+ *
  * @param {Readonly<AstroGlobal>} Astro - The Astro global object.
  * @returns {Promise<ISbStoryData | null>} The Storyblok story data if available,
  * otherwise `null`.
@@ -35,5 +38,50 @@ export declare function useStoryblokApi(): StoryblokClient;
  * }
  * ```
  */
-export declare function getLiveStory(Astro: Readonly<AstroGlobal>): Promise<ISbStoryData | null>;
+export declare function getLiveStory(Astro: {
+    locals: AstroGlobal['locals'];
+}): Promise<ISbStoryData | null>;
+/**
+ * Retrieves the live Storyblok story and server data from Astro's `locals` during preview mode.
+ *
+ * This function is primarily useful when working with the Storyblok Visual Editor
+ * and live preview updates in an Astro project.
+ *
+ * @template ServerData - The type of server data, constrained to StoryblokServerData
+ * @template Story - The type of story data, constrained to ISbStoryData
+ * @param {object} params - The function parameters
+ * @param {object} params.locals - The Astro locals object
+ * @returns {Promise<{ story?: Story; serverData?: ServerData }>} An object containing the story and serverData if available
+ *
+ * @example
+ * ```ts
+ * // Basic usage:
+ * const payload = await getPayload({ locals: Astro.locals });
+ * const story = payload.story ?? null;
+ *
+ * // With typed server data:
+ * interface ServerData {
+ *   users?: User[];
+ * }
+ *
+ * interface MyStory extends ISbStoryData {
+ *   content: { myField: string };
+ * }
+ *
+ * const payload = await getPayload<ServerData, MyStory>({ locals: Astro.locals });
+ * const story = payload.story ?? null;
+ * const users = payload.serverData?.users ?? [];
+ * ```
+ */
+export declare function getPayload<ServerData extends object = object, Story extends ISbStoryData = ISbStoryData>({ locals, }: {
+    locals: {
+        _storyblok_preview_data?: {
+            serverData?: ServerData;
+            story?: Story;
+        };
+    };
+}): Promise<{
+    story?: Story;
+    serverData?: ServerData;
+}>;
 export declare function initStoryblokBridge(config: boolean | StoryblokBridgeConfigV2): string;

package/dist/lib/sanitizeJSON.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Safely serializes data to JSON and escapes characters that could break out of a script tag
+ * or execute malicious code when embedded in HTML.
+ *
+ * This prevents XSS attacks by escaping:
+ * - `</script>` tags that could close the script tag early
+ * - `<!--` and `-->` HTML comment sequences
+ * - Line separator (U+2028) and paragraph separator (U+2029) which are valid JSON but can break JS
+ * - Other potentially dangerous Unicode characters
+ *
+ * @param data - The data to serialize
+ * @returns A safe JSON string that can be embedded in HTML
+ *
+ * @example
+ * ```ts
+ * const safeJSON = sanitizeJSON({
+ *   message: '</script><script>alert("XSS")</script>'
+ * });
+ * // Returns escaped version that won't execute
+ * ```
+ */
+export declare function sanitizeJSON(data: unknown): string;
+/**
+ * Parses JSON that was sanitized with sanitizeJSON()
+ * This is just JSON.parse but provided for symmetry and clarity
+ *
+ * @param json - The sanitized JSON string
+ * @returns The parsed data
+ */
+export declare function parseSanitizedJSON<T = unknown>(json: string): T;

package/dist/live-preview/middleware.ts

@@ -1,18 +1,17 @@
 import { defineMiddleware } from 'astro/middleware';
+import { isEditorRequest } from '@storyblok/astro';
 
 export const onRequest = defineMiddleware(async ({ locals, request }, next) => {
   if (request.method === 'POST') {
-    const url = new URL(request.url);
-    // First do a basic check if its coming from within storyblok
-    const isStoryblokRequest
-      = url.searchParams.has('_storyblok')
-        && url.searchParams.has('_storyblok_c');
+    // First do a check if its coming from within storyblok
+    const editorRequest
+      = isEditorRequest(new URL(request.url));
 
-    if (isStoryblokRequest) {
+    if (editorRequest) {
       try {
         // Create a copy of the request
         const requestBody = await request.clone().json();
-        if (requestBody && requestBody.is_storyblok_preview) {
+        if (requestBody?.story?.is_storyblok_preview) {
           locals._storyblok_preview_data = requestBody;
         }
       }

package/dist/public.d.ts

@@ -16,8 +16,49 @@ declare module '@storyblok/astro/StoryblokComponent.astro' {
   /** Renders a dynamic Storyblok component */
   export default StoryblokComponent;
 }
+declare module '@storyblok/astro/StoryblokServerData.astro' {
+  function StoryblokServerData(
+    _props: Record<string, unknown>
+  ): any;
+
+  /** Renders a dynamic Storyblok component */
+  export default StoryblokServerData;
+}
 declare module '@storyblok/astro/client' {
-  import type { StoryblokClient } from '@storyblok/astro';
+  import type {
+    StoryblokClient,
+    StoryblokRichTextNode,
+    StoryblokRichTextResolvers,
+  } from '@storyblok/astro';
+  /**
+   * @experimental Converts a Storyblok RichText field into an HTML string.
+   *
+   * This API is still under development and may change in future releases.
+   * It also relies on Astro’s experimental
+   * [experimental_AstroContainer](https://docs.astro.build/en/reference/container-reference/) feature.
+   *
+   * @async
+   * @param {StoryblokRichTextNode} richTextField - The root RichText node to convert.
+   * @param {StoryblokRichTextResolvers} [customResolvers] - Optional custom resolvers
+   *   for customizing how specific nodes or marks are transformed into HTML.
+   * @returns {Promise<string>} A promise that resolves to the HTML string representation
+   *   of the provided RichText content.
+   *
+   * @example
+   * ```astro
+   * ---
+   * import { richTextToHTML } from '@storyblok/astro/client';
+   * const { blok } = Astro.props;
+   * const renderedRichText = await richTextToHTML(blok.text);
+   * ---
+   *
+   * <div set:html={renderedRichText} />
+   * ```
+   */
+  export function richTextToHTML(
+    richTextField: StoryblokRichTextNode,
+    customResolvers?: StoryblokRichTextResolvers
+  ): Promise<string>;
 
   /**
    * Provides direct access to the initialized Storyblok API client instance.