fix(postman): upgrade from ir v23 to ir v53 (#4378)

.github/workflows/lint-pr.yml

@@ -35,6 +35,7 @@ jobs:
             go
             ruby
             seed
+            postman
           requireScope: true
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

generators/postman/CHANGELOG.md

@@ -5,6 +5,10 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0] - 2024-08-21
+
+- Internal: Upgrade the Postman generator to use IR version 53.
+
 ## [0.1.1] - 2024-03-22
 
 - Internal: Shared generator notification and config parsing logic.

generators/postman/VERSION

@@ -1 +1 @@
-0.1.1
+0.2.0

generators/postman/package.json

@@ -36,8 +36,9 @@
     "dockerTagVersion": "pnpm dist:cli && docker build -f ./Dockerfile -t fernapi/fern-postman:${0} ."
   },
   "dependencies": {
+    "@fern-api/core-utils": "workspace:*",
     "@fern-api/generator-commons": "workspace:*",
-    "@fern-fern/ir-sdk": "0.0.2828",
+    "@fern-fern/ir-sdk": "^53.7.0",
     "@fern-fern/postman-sdk": "0.0.46",
     "@types/lodash": "^4.17.4",
     "endent": "^2.1.0",

generators/postman/src/auth.ts

@@ -34,6 +34,16 @@ export function convertAuth(schemes: AuthScheme[]): PostmanRequestAuth | undefin
                     }
                 ]
             }),
+            oauth: () => ({
+                type: "bearer",
+                bearer: [
+                    {
+                        key: "token",
+                        value: getReferenceToVariable(BEARER_AUTH_TOKEN_VARIABLE),
+                        type: "string"
+                    }
+                ]
+            }),
             header: (header) => {
                 return {
                     type: "apikey",
@@ -71,10 +81,11 @@ export function convertAuth(schemes: AuthScheme[]): PostmanRequestAuth | undefin
 
 export function getAuthHeaders(schemes: AuthScheme[]): PostmanHeader[] {
     return schemes.flatMap((scheme) =>
-        AuthScheme._visit(scheme, {
+        AuthScheme._visit<PostmanHeader[]>(scheme, {
             basic: () => [],
             bearer: () => [],
-            header: (header) => [
+            oauth: () => [],
+            header: (header): PostmanHeader[] => [
                 {
                     key: header.name.wireValue,
                     value: getReferenceToVariable(getVariableForAuthHeader(header)),
@@ -110,6 +121,13 @@ export function getVariablesForAuthScheme(scheme: AuthScheme): PostmanVariable[]
                 type: "string"
             }
         ],
+        oauth: () => [
+            {
+                key: BEARER_AUTH_TOKEN_VARIABLE,
+                value: "",
+                type: "string"
+            }
+        ],
         header: (header) => [
             {
                 key: getVariableForAuthHeader(header),

generators/postman/src/convertExampleEndpointCall.ts

@@ -6,7 +6,7 @@ import {
     TypeDeclaration
 } from "@fern-fern/ir-sdk/api";
 import { PostmanExampleResponse, PostmanHeader } from "@fern-fern/postman-sdk/api";
-import { isEqual, startCase } from "lodash";
+import { isEqual, startCase, values } from "lodash";
 import { GeneratedExampleRequest } from "./request/GeneratedExampleRequest";
 
 export function convertExampleEndpointCall({
@@ -35,15 +35,40 @@ export function convertExampleEndpointCall({
     return {
         ...getNameAndStatus({ example, allErrors }),
         originalRequest: generatedRequest,
-        description: httpEndpoint.response?.docs ?? undefined,
-        body:
-            example.response.body?.jsonExample != null
-                ? JSON.stringify(example.response.body.jsonExample, undefined, 4)
-                : "",
+        description:
+            httpEndpoint.response?.body?._visit({
+                fileDownload: (value) => value.docs,
+                json: (value) => value.docs,
+                streamParameter: (value) => value.streamResponse.docs,
+                streaming: (value) => value.docs,
+                text: (value) => value.docs,
+                _other: () => undefined
+            }) ?? undefined,
+        body: example.response._visit({
+            ok: (value) => {
+                return value._visit({
+                    body: (value) => maybeStringify({ jsonExample: value?.jsonExample }),
+                    sse: (value) => maybeStringify({ jsonExample: value.map((event) => event?.data.jsonExample) }),
+                    stream: (value) => maybeStringify({ jsonExample: value.map((event) => event.jsonExample) }),
+                    _other: () => ""
+                });
+            },
+            error: (value) => {
+                return maybeStringify({ jsonExample: value?.body?.jsonExample });
+            },
+            _other: () => ""
+        }),
         postmanPreviewlanguage: "json"
     };
 }
 
+function maybeStringify({ jsonExample }: { jsonExample?: unknown }): string {
+    if (jsonExample == null) {
+        return "";
+    }
+    return JSON.stringify(jsonExample, undefined, 4);
+}
+
 function getNameAndStatus({
     example,
     allErrors

generators/postman/src/convertToPostmanCollection.ts

@@ -15,9 +15,9 @@ import {
     PostmanHeader
 } from "@fern-fern/postman-sdk/api";
 import { startCase } from "lodash";
+import { isNonNullish } from "@fern-api/core-utils";
 import { convertAuth, getAuthHeaders, getVariablesForAuthScheme } from "./auth";
 import { convertExampleEndpointCall } from "./convertExampleEndpointCall";
-import { GeneratedDummyRequest } from "./request/GeneratedDummyRequest";
 import { GeneratedExampleRequest } from "./request/GeneratedExampleRequest";
 import { ORIGIN_VARIABLE_NAME } from "./utils";
 
@@ -82,6 +82,12 @@ function filterAuthSchemes(auth: ApiAuth): AuthScheme[] {
                 }
                 return (hasSeenAuthorizationHeader = true);
             },
+            oauth: () => {
+                if (hasSeenAuthorizationHeader) {
+                    return false;
+                }
+                return (hasSeenAuthorizationHeader = true);
+            },
             header: () => true,
             _other: () => {
                 throw new Error("Unknown auth scheme: " + scheme.type);
@@ -129,18 +135,24 @@ function getCollectionItemsForPackage(
             throw new Error("Service does not exist: " + package_.service);
         }
         items.push(
-            ...service.endpoints.map(
-                (httpEndpoint): PostmanCollectionItem.Endpoint => ({
-                    type: "endpoint",
-                    ...convertEndpoint({
+            ...service.endpoints
+                .map((httpEndpoint): PostmanCollectionItem.Endpoint | undefined => {
+                    const convertedEndpoint = convertEndpoint({
                         authHeaders,
                         httpEndpoint,
                         httpService: service,
                         allTypes: Object.values(ir.types),
                         allErrors: Object.values(ir.errors)
-                    })
+                    });
+                    if (convertedEndpoint != null) {
+                        return {
+                            type: "endpoint",
+                            ...convertedEndpoint
+                        };
+                    }
+                    return undefined;
                 })
-            )
+                .filter(isNonNullish)
         );
     }
 
@@ -159,18 +171,28 @@ function convertEndpoint({
     httpService: HttpService;
     allTypes: TypeDeclaration[];
     allErrors: ErrorDeclaration[];
-}): PostmanCollectionEndpointItem {
-    const example = httpEndpoint.examples[0];
-    const generatedRequest =
-        example != null
-            ? new GeneratedExampleRequest({ authHeaders, httpService, httpEndpoint, allTypes, example })
-            : new GeneratedDummyRequest({ authHeaders, httpService, httpEndpoint, allTypes });
+}): PostmanCollectionEndpointItem | undefined {
+    const example = httpEndpoint.userSpecifiedExamples[0]?.example ?? httpEndpoint.autogeneratedExamples[0]?.example;
+
+    if (example == null) {
+        return undefined;
+    }
 
     return {
         name: httpEndpoint.displayName ?? startCase(httpEndpoint.name.originalName),
-        request: generatedRequest.get(),
-        response: httpEndpoint.examples.map((example) =>
-            convertExampleEndpointCall({ authHeaders, httpService, httpEndpoint, allTypes, allErrors, example })
-        )
+        request: new GeneratedExampleRequest({ authHeaders, httpService, httpEndpoint, allTypes, example }).get(),
+        response: [...httpEndpoint.userSpecifiedExamples, ...httpEndpoint.autogeneratedExamples]
+            .map((example) => example.example)
+            .filter(isNonNullish)
+            .map((example) =>
+                convertExampleEndpointCall({
+                    authHeaders,
+                    httpService,
+                    httpEndpoint,
+                    allTypes,
+                    allErrors,
+                    example
+                })
+            )
     };
 }