@fern-api/fern-api-dev 5.94.0 → 5.95.0

package/cli.cjs

@@ -59707,7 +59707,8 @@ var init_HttpReferencedRequestBodySchema2 = __esm({
     init_core();
     init_WithDocsSchema2();
     HttpReferencedRequestBodySchema = schemas_exports.object({
-      type: schemas_exports.string()
+      type: schemas_exports.string(),
+      optional: schemas_exports.boolean().optional()
     }).extend(WithDocsSchema);
   }
 });
@@ -75053,7 +75054,8 @@ var init_BodyRequest2 = __esm({
     init_ReferencedRequestBodyType2();
     BodyRequest = schemas_exports3.objectWithoutOptionalProperties({
       pathParameters: schemas_exports3.list(NamedParameter).optional(),
-      body: ReferencedRequestBodyType2.optional()
+      body: ReferencedRequestBodyType2.optional(),
+      bodyRequired: schemas_exports3.boolean().optional()
     });
   }
 });
@@ -79073,7 +79075,8 @@ var init_HttpRequestBodyReference2 = __esm({
     init_WithDocs3();
     init_WithV2Examples2();
     HttpRequestBodyReference = schemas_exports3.objectWithoutOptionalProperties({
-      requestBodyType: schemas_exports3.lazy(() => TypeReference3)
+      requestBodyType: schemas_exports3.lazy(() => TypeReference3),
+      required: schemas_exports3.boolean().optional()
     }).extend(WithDocs).extend(WithContentType).extend(WithV2Examples);
   }
 });
@@ -147069,9 +147072,10 @@ function buildEndpoint({ endpoint: endpoint3, declarationFile, context: context3
       });
     }
   });
-  if (endpoint3.examples.length > 0) {
+  const examples = filterExamplesThatOmitTheBody({ endpoint: endpoint3, context: context3 });
+  if (examples.length > 0) {
     convertedEndpoint.examples = convertEndpointExamples({
-      endpointExamples: endpoint3.examples,
+      endpointExamples: examples,
       context: context3,
       pathParameterRenames
     });
@@ -147115,6 +147119,21 @@ function convertEndpointAuth({ endpoint: endpoint3, context: context3 }) {
   }
   return endpoint3.security;
 }
+function filterExamplesThatOmitTheBody({ endpoint: endpoint3, context: context3 }) {
+  if (endpoint3.request == null || !isOptionalJsonBody(endpoint3.request)) {
+    return endpoint3.examples;
+  }
+  return endpoint3.examples.filter((example) => {
+    const rawExample = example.type === "full" ? void 0 : example.value;
+    const name2 = example.type === "full" ? example.name : rawExample?.name;
+    const hasRequest = example.type === "full" ? example.request != null : rawExample?.request != null;
+    if (hasRequest) {
+      return true;
+    }
+    context3.logger.debug(`Skipping the example${name2 != null ? ` "${name2}"` : ""} for ${endpoint3.method} ${endpoint3.path}: it has no request body, and the SDKs describe the body as required.`);
+    return false;
+  });
+}
 function convertEndpointExamples({ endpointExamples, context: context3, pathParameterRenames }) {
   return endpointExamples.map((endpointExample) => {
     try {
@@ -147178,15 +147197,16 @@ function getRequest({ endpoint: endpoint3, declarationFile, context: context3, r
         requestValue.docs = request7.description;
       }
       const canCollapse = typeof requestValue.body === "string" && requestValue["path-parameters"] == null && requestValue["query-parameters"] == null && requestValue.headers == null && requestValue.name == null && requestValue.docs == null && (requestValue["content-type"] == null || requestValue["content-type"] === "application/json");
-      if (context3.options.respectOptionalRequestBody && isOptionalJsonBody(request7)) {
-        requestValue.body = typeof requestTypeReference === "string" ? wrapTypeReferenceInOptional(requestTypeReference) : {
-          ...requestTypeReference,
-          type: wrapTypeReferenceInOptional(requestTypeReference.type)
-        };
+      const mayOmitBody = isOptionalJsonBody(request7);
+      if (mayOmitBody) {
+        if (canCollapse) {
+          delete requestValue["content-type"];
+        }
+        requestValue.body = typeof requestTypeReference === "string" ? { type: requestTypeReference, optional: true } : { ...requestTypeReference, optional: true };
       }
       return {
         schemaIdsToExclude: [],
-        value: canCollapse ? requestValue.body : requestValue
+        value: canCollapse && !mayOmitBody ? requestValue.body : requestValue
       };
     }
     const propertyToDeclarationFile = /* @__PURE__ */ new Map();
@@ -147442,9 +147462,6 @@ function getRequest({ endpoint: endpoint3, declarationFile, context: context3, r
 function isOptionalJsonBody(request7) {
   return request7.type === "json" && request7.required !== true;
 }
-function wrapTypeReferenceInOptional(typeReference2) {
-  return typeReference2.startsWith("optional<") ? typeReference2 : `optional<${typeReference2}>`;
-}
 function endpointRequestSupportsInlinedPathParameters({ context: context3, request: request7 }) {
   if (!context3.options.inlinePathParameters) {
     return false;
@@ -149301,6 +149318,9 @@ var init_OpenApiIrConverterContext = __esm({
 // ../api-importers/openapi/openapi-ir-to-fern/lib/convert.js
 function convert(opts) {
   const context3 = new OpenApiIrConverterContext(opts);
+  if (context3.options.respectOptionalRequestBody) {
+    context3.logger.warn("The `respect-optional-request-body` setting is deprecated and no longer has any effect. A request body that OpenAPI does not mark as required is now always described as omittable in the IR, and each SDK generator opts in to that behaviour through its own configuration.");
+  }
   return buildFernDefinition(context3);
 }
 var init_convert = __esm({
@@ -272644,9 +272664,11 @@ function getMultipartPartEncodingFromContentType2(contentType) {
   return encoding;
 }
 function convertReferenceHttpRequestBody({ requestBody, file: file4, contentType }) {
+  const isOmittable = typeof requestBody !== "string" && requestBody.optional === true;
   return {
     docs: typeof requestBody !== "string" ? requestBody.docs : void 0,
     requestBodyType: file4.parseTypeReference(requestBody),
+    required: isOmittable ? false : void 0,
     contentType,
     v2Examples: void 0
   };
@@ -275488,7 +275510,8 @@ function convertExampleRequestBody({ endpoint: endpoint3, example, typeResolver,
   }
   if (!isInlineRequestBody(requestType)) {
     const rawTypeBeingExemplified = typeof requestType !== "string" ? requestType.type : requestType;
-    if (example.request === void 0 && isOptionalType({ rawType: rawTypeBeingExemplified, typeResolver, file: file4 })) {
+    const isOmittable = typeof requestType !== "string" && requestType.optional === true || isOptionalType({ rawType: rawTypeBeingExemplified, typeResolver, file: file4 });
+    if (example.request === void 0 && isOmittable) {
       return void 0;
     }
     return ExampleRequestBody.reference(convertTypeReferenceExample({
@@ -276777,7 +276800,7 @@ var init_DynamicSnippetsConverter = __esm({
           pathParameters: [...endpoint3.servicePathParameters, ...endpoint3.pathParameters]
         });
         if (endpoint3.sdkRequest == null && endpoint3.requestBody == null) {
-          return dynamic_exports.Request.body({ pathParameters, body: void 0 });
+          return dynamic_exports.Request.body({ pathParameters, body: void 0, bodyRequired: void 0 });
         }
         if (endpoint3.sdkRequest == null) {
           throw new CliError({
@@ -276789,7 +276812,10 @@ var init_DynamicSnippetsConverter = __esm({
           case "justRequestBody":
             return dynamic_exports.Request.body({
               pathParameters,
-              body: this.convertReferencedRequestBodyType({ body: endpoint3.sdkRequest.shape.value })
+              body: this.convertReferencedRequestBodyType({ body: endpoint3.sdkRequest.shape.value }),
+              // carried over from the SDK IR so a snippet generator, which never sees that IR,
+              // can tell an omittable body from a required one. Absent means required.
+              bodyRequired: endpoint3.requestBody?.type === "reference" ? endpoint3.requestBody.required : void 0
             });
           case "wrapper":
             return this.convertInlinedRequest({
@@ -328164,6 +328190,17 @@ var init_fern_schema = __esm({
           },
           type: {
             type: "string"
+          },
+          optional: {
+            oneOf: [
+              {
+                type: "boolean"
+              },
+              {
+                type: "null"
+              }
+            ],
+            description: "Whether the endpoint may be called without a request body. When true, an example may\nomit `request`, and the generated SDK lets the caller omit the body. Populated from\n`requestBody.required` when importing from OpenAPI.\n\nThis is distinct from writing `body: optional<Foo>`, which says the body's *value* may\nbe null. Here the body itself may be absent, so the request carries neither content nor\na `Content-Type` header. It maps to `required: false` on the IR's request body reference."
           }
         },
         required: [
@@ -328364,7 +328401,7 @@ var init_fern_schema = __esm({
                 type: "null"
               }
             ],
-            description: "Whether the endpoint may be called without a request body. When true, an\nexample may omit `request`. Populated from `requestBody.required` when\nimporting from OpenAPI.\n\nThis is read by example validation only: it is not carried into the IR, so it\ndoes not make the request parameter optional in a generated SDK."
+            description: "Whether the endpoint may be called without a request body. When true, an\nexample may omit `request`. Populated from `requestBody.required` when\nimporting from OpenAPI.\n\nThis is read by example validation only: it is not carried into the IR, so it\ndoes not make the request parameter optional in a generated SDK.\n\nNote the asymmetry with the identically named field on\n`HttpReferencedRequestBodySchema`, which does reach the IR as `required: false`. An\ninline body has no single type to mark omittable, so its `optional` stays\nvalidation-only."
           }
         },
         additionalProperties: false
@@ -332621,6 +332658,17 @@ var init_package_yml_schema = __esm({
           },
           type: {
             type: "string"
+          },
+          optional: {
+            oneOf: [
+              {
+                type: "boolean"
+              },
+              {
+                type: "null"
+              }
+            ],
+            description: "Whether the endpoint may be called without a request body. When true, an example may\nomit `request`, and the generated SDK lets the caller omit the body. Populated from\n`requestBody.required` when importing from OpenAPI.\n\nThis is distinct from writing `body: optional<Foo>`, which says the body's *value* may\nbe null. Here the body itself may be absent, so the request carries neither content nor\na `Content-Type` header. It maps to `required: false` on the IR's request body reference."
           }
         },
         required: [
@@ -332821,7 +332869,7 @@ var init_package_yml_schema = __esm({
                 type: "null"
               }
             ],
-            description: "Whether the endpoint may be called without a request body. When true, an\nexample may omit `request`. Populated from `requestBody.required` when\nimporting from OpenAPI.\n\nThis is read by example validation only: it is not carried into the IR, so it\ndoes not make the request parameter optional in a generated SDK."
+            description: "Whether the endpoint may be called without a request body. When true, an\nexample may omit `request`. Populated from `requestBody.required` when\nimporting from OpenAPI.\n\nThis is read by example validation only: it is not carried into the IR, so it\ndoes not make the request parameter optional in a generated SDK.\n\nNote the asymmetry with the identically named field on\n`HttpReferencedRequestBodySchema`, which does reach the IR as `required: false`. An\ninline body has no single type to mark omittable, so its `optional` stays\nvalidation-only."
           }
         },
         additionalProperties: false
@@ -355375,6 +355423,13 @@ var init_RequestBodyConverter = __esm({
         this.streamingExtension = streamingExtension;
         this.queryParameters = queryParameters ?? [];
       }
+      /**
+       * Absent means required, so only an explicit `requestBody.required: false` is carried through.
+       * Generators ignore it unless they opt in, which keeps the field additive for existing users.
+       */
+      get bodyRequired() {
+        return this.required === false ? false : void 0;
+      }
       convert() {
         if (this.streamingExtension?.type == "streamCondition") {
           return this.convertStreamConditionRequestBody();
@@ -355439,6 +355494,7 @@ var init_RequestBodyConverter = __esm({
                 contentType,
                 docs: this.description,
                 requestBodyType: convertedSchema.type,
+                required: this.bodyRequired,
                 v2Examples: this.convertMediaTypeObjectExamples({
                   mediaTypeObject,
                   exampleGenerationStrategy: "request"
@@ -355475,6 +355531,7 @@ var init_RequestBodyConverter = __esm({
               contentType,
               docs: this.description,
               requestBodyType: convertedSchema.type,
+              required: this.bodyRequired,
               v2Examples: this.convertMediaTypeObjectExamples({
                 mediaTypeObject,
                 exampleGenerationStrategy: "request"
@@ -355528,6 +355585,7 @@ var init_RequestBodyConverter = __esm({
             contentType,
             docs: this.description,
             requestBodyType: TypeReference2.unknown(),
+            required: this.bodyRequired,
             v2Examples
           }),
           streamRequestBody: void 0,
@@ -355732,6 +355790,7 @@ var init_RequestBodyConverter = __esm({
             contentType,
             docs: this.description,
             requestBodyType: convertedSchema.type,
+            required: this.bodyRequired,
             v2Examples: this.convertMediaTypeObjectExamples({
               mediaTypeObject: modifiedMediaTypeObject,
               exampleGenerationStrategy: "request"
@@ -690356,6 +690415,9 @@ function validateRequest({ example, endpoint: endpoint3, typeResolver, exampleRe
       return { severity: val.severity ?? "fatal", message: val.message };
     }));
   } else {
+    if (example === void 0 && typeof body !== "string" && body.optional === true) {
+      return violations;
+    }
     const bodyViolations = examples_exports6.validateTypeReferenceExample({
       rawTypeReference: typeof body === "string" ? body : body.type,
       example,
@@ -694260,7 +694322,7 @@ var OpenApiSettingsSchema2 = BaseApiSettingsSchema2.extend({
   useReadVariantForResponses: external_exports.boolean().optional(),
   /** Enables respecting forward compatible enums in OpenAPI specifications. Defaults to false. */
   respectForwardCompatibleEnums: external_exports.boolean().optional(),
-  /** Enables making a JSON request body that OpenAPI does not mark as required optional in the generated SDK, so callers may omit the body. Defaults to false. */
+  /** Deprecated and no longer has any effect. A request body that OpenAPI does not mark as required is always described as omittable in the IR, and each SDK generator opts into that behaviour through its own configuration. */
   respectOptionalRequestBody: external_exports.boolean().optional(),
   /** Enables using the `bytes` type for binary responses in OpenAPI specifications. Defaults to a file stream. */
   useBytesForBinaryResponse: external_exports.boolean().optional(),
@@ -702921,7 +702983,7 @@ var AccessTokenPosthogManager = class {
         properties: {
           ...event,
           ...event.properties,
-          version: "5.94.0",
+          version: "5.95.0",
           usingAccessToken: true,
           ...getRunIdProperties()
         }
@@ -702987,7 +703049,7 @@ var UserPosthogManager = class {
       distinctId: this.userId ?? await this.getPersistedDistinctId(),
       event: "CLI",
       properties: {
-        version: "5.94.0",
+        version: "5.95.0",
         ...event,
         ...event.properties,
         usingAccessToken: false,
@@ -884153,7 +884215,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.94.0";
+  const version7 = "5.95.0";
   return `cli@${version7}`;
 }
 var DebugLogger = class {
@@ -909469,7 +909531,7 @@ var LegacyDocsPublisher = class {
         previewId,
         disableTemplates: void 0,
         skipUpload,
-        cliVersion: "5.94.0",
+        cliVersion: "5.95.0",
         loginCommand: "fern auth login"
       });
       if (taskContext.getResult() === TaskResult.Failure) {
@@ -973883,6 +973945,8 @@ var MethodConverter2 = class extends AbstractConverter {
           contentType: "application/proto",
           docs: void 0,
           requestBodyType: requestBodyType.reference,
+          // a gRPC method always carries a request message, and absent means required
+          required: void 0,
           v2Examples: void 0
         }),
         requestExample: void 0
@@ -976387,7 +976451,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.94.0"
+    cli_version: "5.95.0"
   };
 }
 function isAutomationMode() {
@@ -977219,7 +977283,7 @@ var CliContext = class _CliContext {
     if (false) {
       this.logger.error("CLI_VERSION is not defined");
     }
-    return "5.94.0";
+    return "5.95.0";
   }
   getCliName() {
     if (false) {

package/package.json

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