@storyblok/astro 7.3.7 → 7.4.0-alpha.0

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, 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`.
@@ -36,4 +39,47 @@ export declare function useStoryblokApi(): StoryblokClient;
  * ```
  */
 export declare function getLiveStory(Astro: Readonly<AstroGlobal>): 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,6 +16,14 @@ 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,