@fern-api/fern-api-dev 5.34.0 → 5.35.0

package/cli.cjs

@@ -236720,10 +236720,28 @@ var init_GraphQLConverter = __esm({
       namespace;
       processingTypes = /* @__PURE__ */ new Set();
       types = {};
-      constructor({ context: context3, filePath, namespace }) {
+      examplesByOperation = /* @__PURE__ */ new Map();
+      constructor({ context: context3, filePath, namespace, examples }) {
         this.context = context3;
         this.filePath = filePath;
         this.namespace = namespace;
+        if (examples != null) {
+          for (const entry of examples) {
+            const mapped = entry.examples.map((ex) => ({
+              name: ex.name ?? void 0,
+              description: ex.description ?? void 0,
+              query: ex.query,
+              variables: ex.variables ?? void 0,
+              response: ex.response ?? void 0
+            }));
+            if (entry.operationType != null) {
+              const key2 = `${entry.operationType.toLowerCase()}:${entry.operation}`;
+              this.examplesByOperation.set(key2, mapped);
+            } else {
+              this.examplesByOperation.set(entry.operation, mapped);
+            }
+          }
+        }
       }
       isBuiltInScalar(typeName) {
         return ["String", "Int", "Float", "Boolean", "ID"].includes(typeName);
@@ -236887,6 +236905,7 @@ var init_GraphQLConverter = __esm({
       }
       convertField(field5, name2, operationType) {
         const args = field5.args.map((arg) => this.convertArgument(arg));
+        const examples = this.examplesByOperation.get(`${operationType.toLowerCase()}:${name2}`) ?? this.examplesByOperation.get(name2);
         return {
           id: this.getNamespacedOperationId(`${operationType.toLowerCase()}_${name2}`),
           operationType,
@@ -236896,7 +236915,7 @@ var init_GraphQLConverter = __esm({
           availability: void 0,
           arguments: args.length > 0 ? args : void 0,
           returnType: this.convertOutputType(field5.type),
-          examples: void 0,
+          examples: examples != null && examples.length > 0 ? examples : void 0,
           snippets: void 0
         };
       }
@@ -561844,6 +561863,7 @@ var GraphQlSpecSchema = schemas_exports8.object({
   graphql: schemas_exports8.string(),
   origin: schemas_exports8.string().optional(),
   overrides: schemas_exports8.string().optional(),
+  examples: schemas_exports8.string().optional(),
   name: schemas_exports8.string().optional()
 });
 
@@ -596233,7 +596253,8 @@ async function parseApiConfigurationV2Schema({ apiConfiguration, rawConfiguratio
       definitionLocation = {
         schema: {
           type: "graphql",
-          path: spec.graphql
+          path: spec.graphql,
+          examples: spec.examples
         },
         origin: spec.origin,
         overrides: spec.overrides,
@@ -659909,9 +659930,12 @@ var OSSWorkspace = class _OSSWorkspace extends BaseOpenAPIWorkspace {
     const graphqlSpecs = this.allSpecs.filter((spec) => spec.type === "graphql");
     for (const spec of graphqlSpecs) {
       try {
+        const examples = await loadGraphQlExamples(spec.absoluteFilepathToExamples, context3);
         const converter = new GraphQLConverter2({
           context: context3,
-          filePath: spec.absoluteFilepath
+          filePath: spec.absoluteFilepath,
+          namespace: spec.namespace,
+          examples
         });
         const result = await converter.convert();
         Object.assign(this.graphqlOperations, result.graphqlOperations);
@@ -660245,7 +660269,8 @@ var OSSWorkspace = class _OSSWorkspace extends BaseOpenAPIWorkspace {
       ...this.allSpecs.flatMap((spec) => {
         const mainPath = spec.type === "protobuf" ? spec.absoluteFilepathToProtobufTarget : spec.absoluteFilepath;
         const overridePaths = Array.isArray(spec.absoluteFilepathToOverrides) ? spec.absoluteFilepathToOverrides : spec.absoluteFilepathToOverrides != null ? [spec.absoluteFilepathToOverrides] : [];
-        return [mainPath, ...overridePaths];
+        const examplesPath = spec.type === "graphql" ? spec.absoluteFilepathToExamples : void 0;
+        return [mainPath, ...overridePaths, ...examplesPath != null ? [examplesPath] : []];
       }).filter(isNonNullish)
     ];
   }
@@ -660270,6 +660295,52 @@ var OSSWorkspace = class _OSSWorkspace extends BaseOpenAPIWorkspace {
     }, result);
   }
 };
+async function loadGraphQlExamples(absoluteFilepathToExamples, context3) {
+  if (absoluteFilepathToExamples == null) {
+    return void 0;
+  }
+  try {
+    const contents = (await (0, import_promises39.readFile)(absoluteFilepathToExamples)).toString();
+    const parsed = jsYaml.load(contents);
+    if (!Array.isArray(parsed)) {
+      return void 0;
+    }
+    for (const entry of parsed) {
+      if (typeof entry !== "object" || entry == null) {
+        context3.logger.warn(`Skipping invalid entry in GraphQL examples file ${absoluteFilepathToExamples}: expected object`);
+        continue;
+      }
+      if (typeof entry.operation !== "string") {
+        context3.logger.warn(`Skipping entry in GraphQL examples file ${absoluteFilepathToExamples}: missing or invalid 'operation' field`);
+        continue;
+      }
+      if (!Array.isArray(entry.examples)) {
+        context3.logger.warn(`Skipping entry for operation '${entry.operation}' in ${absoluteFilepathToExamples}: 'examples' must be an array`);
+        continue;
+      }
+    }
+    const validEntries = parsed.filter((entry) => typeof entry === "object" && entry != null && typeof entry.operation === "string" && Array.isArray(entry.examples)).map((entry) => {
+      const validExamples = entry.examples.filter((ex) => {
+        if (typeof ex !== "object" || ex == null || typeof ex.query !== "string") {
+          context3.logger.warn(`Skipping malformed example for operation '${entry.operation}' in ${absoluteFilepathToExamples}: missing or invalid 'query' field`);
+          return false;
+        }
+        return true;
+      });
+      if (entry.operationType != null) {
+        const lower = entry.operationType.toLowerCase();
+        if (lower !== "query" && lower !== "mutation" && lower !== "subscription") {
+          context3.logger.warn(`Invalid operationType '${entry.operationType}' for operation '${entry.operation}' in ${absoluteFilepathToExamples}: must be 'query', 'mutation', or 'subscription'`);
+        }
+      }
+      return { ...entry, examples: validExamples };
+    }).filter((entry) => entry.examples.length > 0);
+    return validEntries.length > 0 ? validEntries : void 0;
+  } catch (error50) {
+    context3.logger.error(`Failed to load GraphQL examples from ${absoluteFilepathToExamples}:`, extractErrorMessage(error50));
+    return void 0;
+  }
+}
 async function getAuthFromOverrideFiles(specs) {
   for (const spec of specs) {
     if (spec.type !== "openapi") {
@@ -661303,6 +661374,8 @@ var GraphQlSpecSchema2 = external_exports.object({
   origin: external_exports.string().optional(),
   /** Path to overrides file for the GraphQL spec. */
   overrides: external_exports.union([external_exports.string(), external_exports.array(external_exports.string()).nonempty()]).optional(),
+  /** Path to a YAML/JSON file containing named examples for GraphQL operations. */
+  examples: external_exports.string().optional(),
   /** Name used to group this GraphQL spec in the docs (rendered as a top-level section). */
   name: external_exports.string().optional()
 });
@@ -668495,7 +668568,7 @@ var AccessTokenPosthogManager = class {
         properties: {
           ...event,
           ...event.properties,
-          version: "5.34.0",
+          version: "5.35.0",
           usingAccessToken: true,
           ...getRunIdProperties()
         }
@@ -668559,7 +668632,7 @@ var UserPosthogManager = class {
       distinctId: this.userId ?? await this.getPersistedDistinctId(),
       event: "CLI",
       properties: {
-        version: "5.34.0",
+        version: "5.35.0",
         ...event,
         ...event.properties,
         usingAccessToken: false,
@@ -673153,6 +673226,13 @@ var ApiDefinitionConverter = class {
         sourced: sourced.overrides
       });
     }
+    if (spec.examples != null && !isNullish2(sourced.examples)) {
+      result.examples = await this.resolvePath({
+        absoluteFernYmlPath,
+        path: spec.examples,
+        sourced: sourced.examples
+      });
+    }
     if (spec.name != null) {
       result.name = spec.name;
     }
@@ -674588,6 +674668,7 @@ var LegacyApiSpecAdapter = class {
       type: "graphql",
       absoluteFilepath: spec.graphql,
       absoluteFilepathToOverrides: spec.overrides,
+      absoluteFilepathToExamples: spec.examples,
       namespace: spec.name
     };
   }
@@ -825187,10 +825268,12 @@ https://buildwithfern.com/learn/docs/getting-started/project-structure#api-defin
     const graphqlSpecs = workspace.allSpecs.filter((spec) => spec.type === "graphql");
     for (const spec of graphqlSpecs) {
       try {
+        const examples = await this.loadGraphQlExamples(spec.absoluteFilepathToExamples);
         const converter = new GraphQLConverter({
           context: this.taskContext,
           filePath: spec.absoluteFilepath,
-          namespace: spec.namespace
+          namespace: spec.namespace,
+          examples
         });
         const graphqlResult = await converter.convert();
         Object.assign(graphqlOperations, graphqlResult.graphqlOperations);
@@ -825206,6 +825289,52 @@ https://buildwithfern.com/learn/docs/getting-started/project-structure#api-defin
     }
     return { operations: graphqlOperations, types: graphqlTypes, namespacesByOperationId };
   }
+  async loadGraphQlExamples(absoluteFilepathToExamples) {
+    if (absoluteFilepathToExamples == null) {
+      return void 0;
+    }
+    try {
+      const contents = (await (0, import_promises65.readFile)(absoluteFilepathToExamples)).toString();
+      const parsed = jsYaml.load(contents);
+      if (!Array.isArray(parsed)) {
+        return void 0;
+      }
+      for (const entry of parsed) {
+        if (typeof entry !== "object" || entry == null) {
+          this.taskContext.logger.warn(`Skipping invalid entry in GraphQL examples file ${absoluteFilepathToExamples}: expected object`);
+          continue;
+        }
+        if (typeof entry.operation !== "string") {
+          this.taskContext.logger.warn(`Skipping entry in GraphQL examples file ${absoluteFilepathToExamples}: missing or invalid 'operation' field`);
+          continue;
+        }
+        if (!Array.isArray(entry.examples)) {
+          this.taskContext.logger.warn(`Skipping entry for operation '${entry.operation}' in ${absoluteFilepathToExamples}: 'examples' must be an array`);
+          continue;
+        }
+      }
+      const validEntries = parsed.filter((entry) => typeof entry === "object" && entry != null && typeof entry.operation === "string" && Array.isArray(entry.examples)).map((entry) => {
+        const validExamples = entry.examples.filter((ex) => {
+          if (typeof ex !== "object" || ex == null || typeof ex.query !== "string") {
+            this.taskContext.logger.warn(`Skipping malformed example for operation '${entry.operation}' in ${absoluteFilepathToExamples}: missing or invalid 'query' field`);
+            return false;
+          }
+          return true;
+        });
+        if (entry.operationType != null) {
+          const lower = entry.operationType.toLowerCase();
+          if (lower !== "query" && lower !== "mutation" && lower !== "subscription") {
+            this.taskContext.logger.warn(`Invalid operationType '${entry.operationType}' for operation '${entry.operation}' in ${absoluteFilepathToExamples}: must be 'query', 'mutation', or 'subscription'`);
+          }
+        }
+        return { ...entry, examples: validExamples };
+      }).filter((entry) => entry.examples.length > 0);
+      return validEntries.length > 0 ? validEntries : void 0;
+    } catch (error50) {
+      this.taskContext.logger.error(`Failed to load GraphQL examples from ${absoluteFilepathToExamples}:`, String(error50));
+      return void 0;
+    }
+  }
   /**
    * Handles librarySection navigation items by reading pre-generated MDX files
    * and _navigation.yml from the library's output directory.
@@ -860356,7 +860485,7 @@ var LOCAL_STORAGE_FOLDER4 = ".fern-dev";
 var LOGS_FOLDER_NAME = "logs";
 var MAX_LOGS_DIR_SIZE_BYTES = 100 * 1024 * 1024;
 function getCliSource() {
-  const version7 = "5.34.0";
+  const version7 = "5.35.0";
   return `cli@${version7}`;
 }
 var DebugLogger = class {
@@ -869684,10 +869813,22 @@ async function loadSingleNamespaceAPIWorkspace({ absolutePathToWorkspace, namesp
           }
         };
       }
+      const absoluteFilepathToExamples = definition3.schema.examples != null ? join8(absolutePathToWorkspace, RelativeFilePath2.of(definition3.schema.examples)) : void 0;
+      if (definition3.schema.examples != null && absoluteFilepathToExamples != null && !await doesPathExist(absoluteFilepathToExamples)) {
+        return {
+          didSucceed: false,
+          failures: {
+            [RelativeFilePath2.of(definition3.schema.examples)]: {
+              type: WorkspaceLoaderFailureType.FILE_MISSING
+            }
+          }
+        };
+      }
       specs.push({
         type: "graphql",
         absoluteFilepath: absoluteFilepathToGraphQL,
         absoluteFilepathToOverrides,
+        absoluteFilepathToExamples,
         namespace
       });
       continue;
@@ -879216,7 +879357,7 @@ var LegacyDocsPublisher = class {
         previewId,
         disableTemplates: void 0,
         skipUpload,
-        cliVersion: "5.34.0",
+        cliVersion: "5.35.0",
         loginCommand: "fern auth login"
       });
       if (taskContext.getResult() === TaskResult.Failure) {
@@ -904633,7 +904774,7 @@ var EndpointSnippetGenerator3 = class {
     this.context.errors.scope(Scope4.PathParameters);
     const pathParameters = [...this.context.ir.pathParameters ?? [], ...request7.pathParameters ?? []];
     if (pathParameters.length > 0) {
-      otherArgs.push(...this.getPathParameters({ namedParameters: pathParameters, snippet: snippet2 }).map((field5) => field5.value));
+      otherArgs.push(...this.getPathParameters({ namedParameters: pathParameters, snippet: snippet2, asPointer: true }).map((field5) => field5.value));
     }
     this.context.errors.unscope();
     this.context.errors.scope(Scope4.RequestBody);
@@ -904671,20 +904812,25 @@ var EndpointSnippetGenerator3 = class {
       inlinePathParameters: this.context.customConfig?.inlinePathParameters ?? true,
       inlineFileProperties: this.context.customConfig?.inlineFileProperties ?? true
     };
+    const includePathParamsInRequest = this.context.includePathParametersInWrappedRequest({
+      request: request7,
+      inlinePathParameters
+    });
     this.context.errors.scope(Scope4.PathParameters);
     const pathParameterFields = [];
     const pathParameters = [...this.context.ir.pathParameters ?? [], ...request7.pathParameters ?? []];
     if (pathParameters.length > 0) {
       pathParameterFields.push(...this.getPathParameters({
         namedParameters: pathParameters,
-        snippet: snippet2
+        snippet: snippet2,
+        asPointer: !includePathParamsInRequest
       }));
     }
     this.context.errors.unscope();
     this.context.errors.scope(Scope4.RequestBody);
     const filePropertyInfo = this.getFilePropertyInfo({ request: request7, snippet: snippet2 });
     this.context.errors.unscope();
-    if (!this.context.includePathParametersInWrappedRequest({ request: request7, inlinePathParameters })) {
+    if (!includePathParamsInRequest) {
       otherArgs.push(...pathParameterFields.map((field5) => field5.value));
     }
     if (!inlineFileProperties) {
@@ -904697,10 +904843,7 @@ var EndpointSnippetGenerator3 = class {
     }) ? this.getInlinedRequestArg({
       request: request7,
       snippet: snippet2,
-      pathParameterFields: this.context.includePathParametersInWrappedRequest({
-        request: request7,
-        inlinePathParameters
-      }) ? pathParameterFields : [],
+      pathParameterFields: includePathParamsInRequest ? pathParameterFields : [],
       filePropertyInfo
     }) : void 0;
     return { otherArgs, requestArg };
@@ -904802,7 +904945,7 @@ var EndpointSnippetGenerator3 = class {
     }
     return fields;
   }
-  getPathParameters({ namedParameters, snippet: snippet2 }) {
+  getPathParameters({ namedParameters, snippet: snippet2, asPointer }) {
     const args = [];
     const pathParameters = this.context.associateByWireValueOrDefault({
       parameters: namedParameters,
@@ -904811,7 +904954,7 @@ var EndpointSnippetGenerator3 = class {
     for (const parameter6 of pathParameters) {
       args.push({
         name: this.context.getTypeName(parameter6.name.name),
-        value: this.context.dynamicTypeInstantiationMapper.convertToPointerIfPossible(parameter6)
+        value: asPointer ? this.context.dynamicTypeInstantiationMapper.convertToPointerIfPossible(parameter6) : this.context.dynamicTypeInstantiationMapper.convert(parameter6)
       });
     }
     return args;
@@ -953954,7 +954097,7 @@ function getAutomationContextFromEnv() {
     config_branch: process.env.FERN_CONFIG_BRANCH,
     config_pr_number: process.env.FERN_CONFIG_PR_NUMBER,
     trigger: process.env.GITHUB_EVENT_NAME,
-    cli_version: "5.34.0"
+    cli_version: "5.35.0"
   };
 }
 function isAutomationMode() {
@@ -954780,7 +954923,7 @@ var CliContext = class _CliContext {
     if (false) {
       this.logger.error("CLI_VERSION is not defined");
     }
-    return "5.34.0";
+    return "5.35.0";
   }
   getCliName() {
     if (false) {

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "5.34.0",
+  "version": "5.35.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/fern-api/fern.git",