docusaurus-plugin-generate-schema-docs 1.7.1 → 1.8.1

package/helpers/trackingTargets.js

@@ -0,0 +1,73 @@
+export const DEFAULT_TRACKING_TARGET = 'web-datalayer-js';
+
+export const SUPPORTED_TRACKING_TARGETS = [
+  DEFAULT_TRACKING_TARGET,
+  'android-firebase-kotlin-sdk',
+  'android-firebase-java-sdk',
+  'ios-firebase-swift-sdk',
+  'ios-firebase-objc-sdk',
+];
+
+const TARGET_ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+){2,}$/;
+
+export function resolveTrackingTargets(
+  schema,
+  { schemaFile = 'schema', isQuiet = false } = {},
+) {
+  const configuredTargets = schema?.['x-tracking-targets'];
+
+  if (configuredTargets == null) {
+    const warning = isQuiet
+      ? null
+      : `Schema ${schemaFile} is missing x-tracking-targets. Falling back to "${DEFAULT_TRACKING_TARGET}".`;
+    return {
+      targets: [DEFAULT_TRACKING_TARGET],
+      warning,
+      errors: [],
+    };
+  }
+
+  if (
+    !Array.isArray(configuredTargets) ||
+    configuredTargets.length === 0 ||
+    configuredTargets.some((target) => typeof target !== 'string')
+  ) {
+    return {
+      targets: [],
+      warning: null,
+      errors: [
+        'x-tracking-targets must be a non-empty array of string target IDs.',
+      ],
+    };
+  }
+
+  const errors = [];
+  const unknownTargets = configuredTargets.filter(
+    (target) => !SUPPORTED_TRACKING_TARGETS.includes(target),
+  );
+
+  if (unknownTargets.length > 0) {
+    errors.push(
+      `x-tracking-targets contains unsupported target(s): ${unknownTargets.join(
+        ', ',
+      )}.`,
+    );
+  }
+
+  const badlyFormattedTargets = configuredTargets.filter(
+    (target) => !TARGET_ID_PATTERN.test(target),
+  );
+  if (badlyFormattedTargets.length > 0) {
+    errors.push(
+      `x-tracking-targets must use lowercase kebab-case IDs like "web-datalayer-js". Invalid value(s): ${badlyFormattedTargets.join(
+        ', ',
+      )}.`,
+    );
+  }
+
+  return {
+    targets: errors.length === 0 ? configuredTargets : [],
+    warning: null,
+    errors,
+  };
+}

package/helpers/validator.js

@@ -49,6 +49,7 @@ function createAjvInstance(schemas, mainSchema, schemaPath) {
   addFormats(ajv);
   if (ajv.addKeyword) {
     ajv.addKeyword('x-gtm-clear');
+    ajv.addKeyword('x-tracking-targets');
   }
   ajvKeywords(ajv);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docusaurus-plugin-generate-schema-docs",
-  "version": "1.7.1",
+  "version": "1.8.1",
   "description": "Docusaurus plugin to generate documentation from JSON schemas.",
   "main": "index.js",
   "license": "MIT",

package/test-data/payloadContracts.js

@@ -0,0 +1,155 @@
+const PAYLOAD_CONTRACTS = [
+  {
+    id: 'screen-view-predefined',
+    class: 'predefined',
+    example: {
+      event: 'screen_view',
+      firebase_screen: 'Checkout',
+      firebase_screen_class: 'CheckoutViewController',
+    },
+    expected: {
+      web: {
+        eventName: 'screen_view',
+        payload: {
+          event: 'screen_view',
+          firebase_screen: 'Checkout',
+          firebase_screen_class: 'CheckoutViewController',
+        },
+      },
+      firebase: {
+        eventName: 'screen_view',
+        parameters: {
+          screen_name: 'Checkout',
+          screen_class: 'CheckoutViewController',
+        },
+        userProperties: {},
+      },
+    },
+  },
+  {
+    id: 'add-to-cart-with-items',
+    class: 'ecommerce_items',
+    example: {
+      event: 'add_to_cart',
+      currency: 'EUR',
+      value: 42.5,
+      items: [
+        {
+          item_id: 'sku-1',
+          item_name: 'Socks',
+          price: 21.25,
+          quantity: 2,
+        },
+      ],
+    },
+    expected: {
+      web: {
+        eventName: 'add_to_cart',
+        payload: {
+          event: 'add_to_cart',
+          currency: 'EUR',
+          value: 42.5,
+          items: [
+            {
+              item_id: 'sku-1',
+              item_name: 'Socks',
+              price: 21.25,
+              quantity: 2,
+            },
+          ],
+        },
+      },
+      firebase: {
+        eventName: 'add_to_cart',
+        parameters: {
+          currency: 'EUR',
+          value: 42.5,
+          items: [
+            {
+              item_id: 'sku-1',
+              item_name: 'Socks',
+              price: 21.25,
+              quantity: 2,
+            },
+          ],
+        },
+        userProperties: {},
+      },
+    },
+  },
+  {
+    id: 'custom-event-with-user-properties',
+    class: 'custom',
+    example: {
+      event: 'my_custom_event',
+      plan: 'pro',
+      count: 2,
+      premium: true,
+      user_properties: {
+        sign_up_method: 'email',
+        allow_ad_personalization_signals: false,
+      },
+    },
+    expected: {
+      web: {
+        eventName: 'my_custom_event',
+        payload: {
+          event: 'my_custom_event',
+          plan: 'pro',
+          count: 2,
+          premium: true,
+          user_properties: {
+            sign_up_method: 'email',
+            allow_ad_personalization_signals: false,
+          },
+        },
+      },
+      firebase: {
+        eventName: 'my_custom_event',
+        parameters: {
+          plan: 'pro',
+          count: 2,
+          premium: 1,
+        },
+        userProperties: {
+          sign_up_method: 'email',
+          allow_personalized_ads: 'false',
+        },
+      },
+    },
+  },
+  {
+    id: 'web-fallback-json-serialization',
+    class: 'fallback_json_serialization',
+    targets: ['web-datalayer-js'],
+    example: {
+      event: 'metadata_capture',
+      metadata: {
+        checkout_step: 2,
+        flags: ['beta', 'ios'],
+      },
+      user: {
+        id: 'U-123',
+      },
+    },
+    expected: {
+      web: {
+        eventName: 'metadata_capture',
+        payload: {
+          event: 'metadata_capture',
+          metadata: {
+            checkout_step: 2,
+            flags: ['beta', 'ios'],
+          },
+          user: {
+            id: 'U-123',
+          },
+        },
+      },
+    },
+  },
+];
+
+module.exports = {
+  PAYLOAD_CONTRACTS,
+};

package/validateSchemas.js

@@ -3,6 +3,7 @@ import fs from 'fs';
 import path from 'path';
 import processSchema from './helpers/processSchema.js';
 import { schemaToExamples } from './helpers/schemaToExamples.js';
+import { resolveTrackingTargets } from './helpers/trackingTargets.js';
 
 const validateSingleSchema = async (filePath, schemaPath) => {
   const file = path.basename(filePath);
@@ -13,6 +14,20 @@ const validateSingleSchema = async (filePath, schemaPath) => {
     const mergedSchema = await processSchema(filePath);
     const exampleGroups = schemaToExamples(mergedSchema);
     const originalSchema = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+    const trackingTargets = resolveTrackingTargets(originalSchema, {
+      schemaFile: file,
+    });
+
+    if (trackingTargets.warning) {
+      console.warn(trackingTargets.warning);
+    }
+    if (trackingTargets.errors.length > 0) {
+      trackingTargets.errors.forEach((error) =>
+        errors.push(`x Schema ${file} ${error}`),
+      );
+      return { allValid: false, errors };
+    }
+
     const validate = await createValidator([], originalSchema, schemaPath);
 
     if (exampleGroups.length === 0) {