feat: add schema definitions for popular analytics providers to the d…

…ocs generator config (#4291)

fern/docs.yml

@@ -322,6 +322,12 @@ navigation:
             path: ./pages/docs/comparison/readme.mdx
       - section: Analytics
         contents:
+          - page: PostHog
+            path: ./pages/docs/analytics/posthog.mdx
+          - page: Intercom
+            path: ./pages/docs/analytics/intercom.mdx
+          - page: Fullstory
+            path: ./pages/docs/analytics/fullstory.mdx
           - page: Segment
             path: ./pages/docs/analytics/segment.mdx
   - tab: cli-api

fern/pages/docs/analytics/fullstory.mdx

@@ -0,0 +1,39 @@
+---
+title: Fullstory
+description: Learn how to integrate Fern Docs with Fullstory to track user behavior and analytics.
+---
+
+## Add Fullstory to your Docs
+
+To add Fullstory to your Docs, you need to add your Fullstory `orgId` to your `docs.yml` file.
+
+### Get your Fullstory Org ID
+
+When you login to your Fullstory account, your Org ID can be found in the URL of your browser.
+
+```
+https://app.fullstory.com/ui/<ORG_ID>/home
+```
+
+Additionally, you can find your Org ID in [Settings > Data Capture and Privacy > Fullstory Setup](https://help.fullstory.com/hc/en-us/articles/360047075853-How-do-I-find-my-Fullstory-Org-Id#:~:text=You%20can%20find%20your%20Org,embedded%20in%20the%20Fullstory%20snippet.&text=More%20information%20about%20installation%20and,the%20URL%20of%20your%20browser.)
+inside the Fullstory snippet:
+
+1. Log in to your Fullstory account.
+2. Find **Settings** in a dropdown by clicking your organization's name or logo in the top left.
+3. Navigate the sidebar to the Data Capture and Privacy section. Click on "Fullstory Setup", located under the heading.
+4. Retrieve the Org Id from the snippet, where it is assigned to `window['_fs_org']`. It will appear as `window['_fs_org'] = '<ORG_ID>'`.
+
+You can find visual instructions in [Fullstory's guide](https://help.fullstory.com/hc/en-us/articles/360047075853-How-do-I-find-my-Fullstory-Org-Id#:~:text=You%20can%20find%20your%20Org,embedded%20in%20the%20Fullstory%20snippet.&text=More%20information%20about%20installation%20and,the%20URL%20of%20your%20browser.)
+about this topic.
+
+### Integrate Fullstory with your Docs
+
+In your `docs.yml` file, add your Fullstory Org ID:
+
+<CodeBlock title="docs.yml">
+```yaml
+analytics:
+  fullstory:
+    org-id: ${FULLSTORY_ORG_ID} # reads your org id from environment variables
+```
+</CodeBlock>

fern/pages/docs/analytics/intercom.mdx

@@ -0,0 +1,32 @@
+---
+title: Intercom
+description: Learn how to integrate Intercom with Fern Docs!
+---
+
+## Add Intercom to your Docs
+
+To add Intercom to your Docs, you need to your Intercom `app_id`, also known as the Intercom workspace ID.
+This is a unique code assigned to your app when you create it in Intercom.
+
+Additionally, you may configure a custom Intercom endpoint.
+
+### Get your Intercom App Id
+
+Your app ID is available under [Settings > Workspace > General](https://app.intercom.com/a/apps/_/settings/workspace/general)
+in the "Workspace name & time zone" tab.
+
+See [Intercom's FAQ](https://www.intercom.com/help/en/articles/8771110-getting-started-faqs#h_c12f89cf9d) for visual instructions.
+
+### Integrate Intercom with your Docs
+
+In your `docs.yml` file, add your Intercom config:
+
+<CodeBlock title="docs.yml">
+```yaml
+analytics:
+  intercom:
+    app-id: ${INTERCOM_APP_ID} # reads your org id from environment variables
+    # Optional
+    endpoint: ${INTERCOM_ENDPOINT} # e.g. https://intercom.custom-instance.com
+```
+</CodeBlock>

fern/pages/docs/analytics/posthog.mdx

@@ -0,0 +1,24 @@
+---
+title: PostHog
+description: Learn how to integrate PostHog with Fern Docs!
+---
+
+## Add Posthog to your Docs
+
+To integrate PostHog, you'll need a Posthog API Key, and optionally, you can configure a custom Posthog host.
+
+### Integrate Posthog
+
+You can find your PostHog API Key under your [project settings.](https://us.posthog.com/settings/project)
+
+Then, in your `docs.yml` file, add your Posthog configuration:
+
+<CodeBlock title="docs.yml">
+```yaml
+analytics:
+  posthog:
+    api-key: ${POSTHOG_API_KEY} # reads your api key from environment variables
+    # Optional
+    endpoint: ${POSTHOG_API_HOST} # e.g. https://analytics.example.com or https://eu.i.posthog.com
+```
+</CodeBlock>

packages/cli/configuration/fern/definition/docs.yml

@@ -24,10 +24,88 @@ types:
   AnalyticsConfig:
     properties:
       segment: optional<SegmentConfig>
+      fullstory: optional<FullStoryAnalyticsConfig>
+      intercom: optional<IntercomConfig>
+      posthog: optional<PostHogConfig>
+      # gtm: optional<GTMConfig>
+      # ga4: optional<GoogleAnalytics4Config>
+      # amplitude: optional<AmplitudeConfig>
+      # mixpanel: optional<MixpanelConfig>
+      # hotjar: optional<HotJarConfig>
+      # koala: optional<KoalaConfig>
+      # logrocket: optional<LogRocketConfig>
+      # pirsch: optional<PirschConfig>
+      # plausible: optional<PlausibleConfig>
+      # fathom: optional<FathomConfig>
+      # clearbit: optional<ClearBitConfig>
+      # heap: optional<HeapConfig>
 
   SegmentConfig:
     properties:
       write-key: string
+
+  FullStoryAnalyticsConfig:
+    properties:
+      org-id: string
+
+  IntercomConfig:
+    properties:
+      app-id: string
+      api-base: optional<string>
+
+  PostHogConfig:
+    properties:
+      api-key: string
+      endpoint: optional<string>
+
+  # GTMConfig:
+  #   properties:
+  #     container-id: string
+
+  # GoogleAnalytics4Config:
+  #   properties:
+  #     measurement-id: string
+
+  # AmplitudeConfig:
+  #   properties:
+  #     api-key: string
+
+  # MixpanelConfig:
+  #   properties:
+  #     api-key: string
+
+  # HotJarConfig:
+  #   properties:
+  #     hjid: string
+  #     hjsv: string
+
+  # KoalaConfig:
+  #   properties:
+  #     api-key: string
+
+  # LogRocketConfig:
+  #   properties:
+  #     api-key: string
+
+  # PirschConfig:
+  #   properties:
+  #     id: string
+
+  # PlausibleConfig:
+  #   properties:
+  #     domain: string
+
+  # FathomConfig:
+  #   properties:
+  #     site-id: string
+
+  # ClearBitConfig:
+  #   properties:
+  #     api-key: string
+
+  # HeapConfig:
+  #   properties:
+  #     app-id: string
 
   DocsConfiguration:
     properties:

packages/cli/configuration/src/docs-yml/schemas/sdk/api/resources/docs/types/AnalyticsConfig.ts

@@ -6,4 +6,7 @@ import * as FernDocsConfig from "../../..";
 
 export interface AnalyticsConfig {
     segment?: FernDocsConfig.SegmentConfig;
+    fullstory?: FernDocsConfig.FullStoryAnalyticsConfig;
+    intercom?: FernDocsConfig.IntercomConfig;
+    posthog?: FernDocsConfig.PostHogConfig;
 }

packages/cli/configuration/src/docs-yml/schemas/sdk/api/resources/docs/types/FullStoryAnalyticsConfig.ts

@@ -0,0 +1,7 @@
+/**
+ * This file was auto-generated by Fern from our API Definition.
+ */
+
+export interface FullStoryAnalyticsConfig {
+    orgId: string;
+}

packages/cli/configuration/src/docs-yml/schemas/sdk/api/resources/docs/types/IntercomConfig.ts

@@ -0,0 +1,8 @@
+/**
+ * This file was auto-generated by Fern from our API Definition.
+ */
+
+export interface IntercomConfig {
+    appId: string;
+    apiBase?: string;
+}

packages/cli/configuration/src/docs-yml/schemas/sdk/api/resources/docs/types/PostHogConfig.ts

@@ -0,0 +1,8 @@
+/**
+ * This file was auto-generated by Fern from our API Definition.
+ */
+
+export interface PostHogConfig {
+    apiKey: string;
+    endpoint?: string;
+}

packages/cli/configuration/src/docs-yml/schemas/sdk/api/resources/docs/types/index.ts

@@ -1,6 +1,9 @@
 export * from "./ProgrammingLanguage";
 export * from "./AnalyticsConfig";
 export * from "./SegmentConfig";
+export * from "./FullStoryAnalyticsConfig";
+export * from "./IntercomConfig";
+export * from "./PostHogConfig";
 export * from "./DocsConfiguration";
 export * from "./TabId";
 export * from "./TabConfig";

packages/cli/configuration/src/docs-yml/schemas/sdk/serialization/resources/docs/types/AnalyticsConfig.ts

@@ -11,10 +11,18 @@ export const AnalyticsConfig: core.serialization.ObjectSchema<
     FernDocsConfig.AnalyticsConfig
 > = core.serialization.object({
     segment: core.serialization.lazyObject(async () => (await import("../../..")).SegmentConfig).optional(),
+    fullstory: core.serialization
+        .lazyObject(async () => (await import("../../..")).FullStoryAnalyticsConfig)
+        .optional(),
+    intercom: core.serialization.lazyObject(async () => (await import("../../..")).IntercomConfig).optional(),
+    posthog: core.serialization.lazyObject(async () => (await import("../../..")).PostHogConfig).optional(),
 });
 
 export declare namespace AnalyticsConfig {
     interface Raw {
         segment?: serializers.SegmentConfig.Raw | null;
+        fullstory?: serializers.FullStoryAnalyticsConfig.Raw | null;
+        intercom?: serializers.IntercomConfig.Raw | null;
+        posthog?: serializers.PostHogConfig.Raw | null;
     }
 }

packages/cli/configuration/src/docs-yml/schemas/sdk/serialization/resources/docs/types/FullStoryAnalyticsConfig.ts

@@ -0,0 +1,20 @@
+/**
+ * This file was auto-generated by Fern from our API Definition.
+ */
+
+import * as serializers from "../../..";
+import * as FernDocsConfig from "../../../../api";
+import * as core from "../../../../core";
+
+export const FullStoryAnalyticsConfig: core.serialization.ObjectSchema<
+    serializers.FullStoryAnalyticsConfig.Raw,
+    FernDocsConfig.FullStoryAnalyticsConfig
+> = core.serialization.object({
+    orgId: core.serialization.property("org-id", core.serialization.string()),
+});
+
+export declare namespace FullStoryAnalyticsConfig {
+    interface Raw {
+        "org-id": string;
+    }
+}

packages/cli/configuration/src/docs-yml/schemas/sdk/serialization/resources/docs/types/IntercomConfig.ts

@@ -0,0 +1,22 @@
+/**
+ * This file was auto-generated by Fern from our API Definition.
+ */
+
+import * as serializers from "../../..";
+import * as FernDocsConfig from "../../../../api";
+import * as core from "../../../../core";
+
+export const IntercomConfig: core.serialization.ObjectSchema<
+    serializers.IntercomConfig.Raw,
+    FernDocsConfig.IntercomConfig
+> = core.serialization.object({
+    appId: core.serialization.property("app-id", core.serialization.string()),
+    apiBase: core.serialization.property("api-base", core.serialization.string().optional()),
+});
+
+export declare namespace IntercomConfig {
+    interface Raw {
+        "app-id": string;
+        "api-base"?: string | null;
+    }
+}

packages/cli/configuration/src/docs-yml/schemas/sdk/serialization/resources/docs/types/PostHogConfig.ts

@@ -0,0 +1,22 @@
+/**
+ * This file was auto-generated by Fern from our API Definition.
+ */
+
+import * as serializers from "../../..";
+import * as FernDocsConfig from "../../../../api";
+import * as core from "../../../../core";
+
+export const PostHogConfig: core.serialization.ObjectSchema<
+    serializers.PostHogConfig.Raw,
+    FernDocsConfig.PostHogConfig
+> = core.serialization.object({
+    apiKey: core.serialization.property("api-key", core.serialization.string()),
+    endpoint: core.serialization.string().optional(),
+});
+
+export declare namespace PostHogConfig {
+    interface Raw {
+        "api-key": string;
+        endpoint?: string | null;
+    }
+}

packages/cli/configuration/src/docs-yml/schemas/sdk/serialization/resources/docs/types/index.ts

@@ -1,6 +1,9 @@
 export * from "./ProgrammingLanguage";
 export * from "./AnalyticsConfig";
 export * from "./SegmentConfig";
+export * from "./FullStoryAnalyticsConfig";
+export * from "./IntercomConfig";
+export * from "./PostHogConfig";
 export * from "./DocsConfiguration";
 export * from "./TabId";
 export * from "./TabConfig";

packages/cli/yaml/docs-validator/src/__test__/valid-docs-endpoints.test.ts

@@ -0,0 +1,19 @@
+import { validEndpoint } from "../rules/valid-docs-endpoints/valid-docs-endpoints";
+
+describe("validEndpoints", () => {
+    it("only origin is invalid", () => {
+        expect(validEndpoint("api.origin.com")).toBeFalsy();
+    });
+
+    it("is valid with protocol", () => {
+        expect(validEndpoint("https://us.i.posthog.com")).toBeTruthy();
+    });
+
+    it("only protocol is invalid", () => {
+        expect(validEndpoint("https://")).toBeFalsy();
+    });
+
+    it("empty string is invalid", () => {
+        expect(validEndpoint("")).toBeFalsy();
+    });
+});

packages/cli/yaml/docs-validator/src/getAllRules.ts

@@ -3,6 +3,7 @@ import { AccentColorContrastRule } from "./rules/accent-color-contrast";
 import { FilepathsExistRule } from "./rules/filepaths-exist";
 import { OnlyVersionedNavigation } from "./rules/only-versioned-navigation";
 import { PlaygroundEnvironmentsExistRule } from "./rules/playground-environments-exist";
+import { ValidDocsEndpoints } from "./rules/valid-docs-endpoints";
 import { ValidFileTypes } from "./rules/valid-file-types";
 import { ValidMarkdownRule } from "./rules/valid-markdown";
 import { ValidMarkdownLinks } from "./rules/valid-markdown-link";
@@ -17,6 +18,7 @@ export function getAllRules(): Rule[] {
         AccentColorContrastRule,
         ValidMarkdownLinks,
         ValidFileTypes,
-        PlaygroundEnvironmentsExistRule
+        PlaygroundEnvironmentsExistRule,
+        ValidDocsEndpoints
     ];
 }

packages/cli/yaml/docs-validator/src/rules/valid-docs-endpoints/index.ts

@@ -0,0 +1 @@
+export { ValidDocsEndpoints } from "./valid-docs-endpoints";