[DEV-3319] Add getGuidesQueryString for server-side dirName filtering

.changeset/shiny-clouds-float.md

@@ -0,0 +1,5 @@
+---
+"gitbook-docs": patch
+---
+
+Refactor Strapi guide fetching to use server-side filtering using Strapi 5 capabilities.

packages/gitbook-docs/src/helpers/strapiQuery.ts

@@ -232,7 +232,6 @@ const solutionListPageQueryParams = {
   ...STRAPI_DEFAULT_PAGINATION,
 };
 
-export const guidesQueryString = qs.stringify(guidesQueryParams);
 export const solutionsQueryString = qs.stringify(solutionsQueryParams);
 export const productsQueryString = qs.stringify(productsQueryParams);
 export const apisDataQueryString = qs.stringify(apisDataQueryParams);
@@ -244,6 +243,28 @@ export const solutionListPageQueryString = qs.stringify(
   solutionListPageQueryParams
 );
 
+/**
+ * Generate query string for guides with optional dirName filtering.
+ * Uses deep filtering on the 'versions' component.
+ */
+export function getGuidesQueryString(dirNames?: readonly string[]): string {
+  const params = {
+    ...guidesQueryParams,
+    ...(dirNames && dirNames.length > 0
+      ? {
+        filters: {
+          versions: {
+            dirName: {
+              $in: dirNames,
+            },
+          },
+        },
+      }
+      : {}),
+  };
+  return qs.stringify(params);
+}
+
 /**
  * Generate query strings with optional dirName filtering.
  *
@@ -262,12 +283,12 @@ export function getSolutionsQueryString(dirNames?: readonly string[]): string {
     ...solutionsQueryParams,
     ...(dirNames && dirNames.length > 0
       ? {
-          filters: {
-            dirName: {
-              $in: dirNames,
-            },
+        filters: {
+          dirName: {
+            $in: dirNames,
           },
-        }
+        },
+      }
       : {}),
   };
   return qs.stringify(params);
@@ -280,12 +301,12 @@ export function getReleaseNotesQueryString(
     ...releaseNotesQueryParams,
     ...(dirNames && dirNames.length > 0
       ? {
-          filters: {
-            dirName: {
-              $in: dirNames,
-            },
+        filters: {
+          dirName: {
+            $in: dirNames,
           },
-        }
+        },
+      }
       : {}),
   };
   return qs.stringify(params);

packages/gitbook-docs/src/scripts/deleteUnusedDirectories.ts

@@ -21,7 +21,7 @@ import {
 import { S3Client } from '@aws-sdk/client-s3';
 import path from 'path';
 import {
-  guidesQueryString,
+  getGuidesQueryString,
   releaseNotesQueryString,
   solutionsQueryString,
 } from '../helpers/strapiQuery';
@@ -49,7 +49,7 @@ async function fetchAllDirNamesFromStrapi(): Promise<{ dirNames: string[] }> {
   const [guidesResult, solutionsResult, releaseNotesResult] = await Promise.all(
     [
       // Guides with full populate
-      fetchFromStrapi<StrapiGuide>(`api/guides?${guidesQueryString}`),
+      fetchFromStrapi<StrapiGuide>(`api/guides?${getGuidesQueryString()}`),
       // Solutions with full populate
       fetchFromStrapi<StrapiSolution>(`api/solutions/?${solutionsQueryString}`),
       // Release notes with full populate

packages/gitbook-docs/src/scripts/syncAllMetadata.ts

@@ -41,9 +41,9 @@ import {
 } from '../helpers/strapiTypes';
 import {
   apisDataQueryString,
+  getGuidesQueryString,
   getReleaseNotesQueryString,
   getSolutionsQueryString,
-  guidesQueryString,
   productsQueryString,
 } from '../helpers/strapiQuery';
 import { compact } from 'lodash';
@@ -153,8 +153,7 @@ async function fetchAllStrapiData(): Promise<StrapiData> {
   console.log('Fetching all data from Strapi...');
   if (DIR_NAMES_FILTER) {
     console.log(
-      `Applying dirName filter: ${DIR_NAMES_FILTER.join(', ')} (${
-        DIR_NAMES_FILTER.length
+      `Applying dirName filter: ${DIR_NAMES_FILTER.join(', ')} (${DIR_NAMES_FILTER.length
       } directories)`
     );
   }
@@ -166,10 +165,10 @@ async function fetchAllStrapiData(): Promise<StrapiData> {
     productsResult,
     apisDataResult,
   ] = await Promise.all([
-    // Guides with full populate
-    // NOTE: Cannot filter by versions.dirName server-side due to Strapi v4 component array limitation
-    // Client-side filtering will be applied later in processGuidesMetadata
-    fetchFromStrapi<StrapiGuide>(`api/guides?${guidesQueryString}`),
+    // Guides with full populate and optional dirName filtering
+    fetchFromStrapi<StrapiGuide>(
+      `api/guides?${getGuidesQueryString(DIR_NAMES_FILTER)}`
+    ),
     // Solutions with dirName filter (if provided)
     fetchFromStrapi<StrapiSolution>(
       `api/solutions/?${getSolutionsQueryString(DIR_NAMES_FILTER)}`