(improvement, yaml): Update default OAuth configuration

packages/cli/configuration/src/DocsLinks.ts

@@ -0,0 +1,7 @@
+export interface DocsLinks {
+    oauth: string;
+}
+
+export const DocsLinks: DocsLinks = {
+    oauth: "https://buildwithfern.com/learn/api-definition/fern/api-yml-reference#authentication"
+};

packages/cli/configuration/src/index.ts

@@ -4,6 +4,7 @@ export * from "./commons/WithoutQuestionMarks";
 export * from "./constants";
 export * as dependenciesYml from "./dependencies-yml";
 export * as docsYml from "./docs-yml";
+export { DocsLinks } from "./DocsLinks";
 export * as fernConfigJson from "./fern-config-json";
 export * as generatorsYml from "./generators-yml";
 export { GeneratorName } from "./generators-yml/GeneratorName";

packages/cli/generation/ir-generator/src/converters/convertOAuthUtils.ts

@@ -1,6 +1,34 @@
 import { RawSchemas } from "@fern-api/yaml-schema";
 import { getRequestPropertyComponents, getResponsePropertyComponents } from "./services/convertProperty";
 
+const DEFAULT_TOKEN_ENDPOINT: Omit<TokenEndpoint, "endpoint"> = {
+    requestProperties: {
+        type: "access_token",
+        client_id: ["client_id"],
+        client_secret: ["client_secret"],
+        scopes: undefined
+    },
+    responseProperties: {
+        type: "access_token",
+        access_token: ["access_token"],
+        expires_in: undefined,
+        refresh_token: undefined
+    }
+};
+
+const DEFAULT_REFRESH_TOKEN_ENDPOINT: Omit<RefreshTokenEndpoint, "endpoint"> = {
+    requestProperties: {
+        type: "refresh_token",
+        refresh_token: ["refresh_token"]
+    },
+    responseProperties: {
+        type: "access_token",
+        access_token: ["access_token"],
+        refresh_token: undefined,
+        expires_in: undefined
+    }
+};
+
 export interface TokenEndpoint {
     endpoint: string;
     requestProperties: OAuthAccessTokenRequestPropertyComponents;
@@ -33,58 +61,119 @@ interface OAuthRefreshTokenRequestPropertyComponents {
 }
 
 export function getTokenEndpoint(oauthSchema: RawSchemas.OAuthSchemeSchema): TokenEndpoint {
-    // const maybeScopes = oauthSchema["get-token"]["request-properties"].scopes;
-    const maybeExpiresIn = oauthSchema["get-token"]["response-properties"]["expires-in"];
-    const maybeRefreshToken = oauthSchema["get-token"]["response-properties"]["refresh-token"];
     return {
         endpoint: oauthSchema["get-token"].endpoint,
-        // TODO: Update the YAML schema and make this configurable with the following:
-        // requestProperties: {
-        //     type: "access_token",
-        //     client_id: getRequestPropertyComponents(oauthSchema["get-token"]["request-properties"]["client-id"]),
-        //     client_secret: getRequestPropertyComponents(
-        //         oauthSchema["get-token"]["request-properties"]["client-secret"]
-        //     ),
-        //     scopes: maybeScopes != null ? getRequestPropertyComponents(maybeScopes) : undefined
-        // },
-        requestProperties: {
-            type: "access_token",
-            client_id: ["client_id"],
-            client_secret: ["client_secret"],
-            scopes: undefined
-        },
-        responseProperties: {
-            type: "access_token",
-            access_token: getResponsePropertyComponents(
-                oauthSchema["get-token"]["response-properties"]["access-token"]
-            ),
-            expires_in: maybeExpiresIn != null ? getResponsePropertyComponents(maybeExpiresIn) : undefined,
-            refresh_token: maybeRefreshToken != null ? getResponsePropertyComponents(maybeRefreshToken) : undefined
-        }
+        requestProperties: getTokenEndpointRequestProperties({
+            requestProperties: oauthSchema["get-token"]?.["request-properties"]
+        }),
+        responseProperties: getTokenEndpointResponseProperties({
+            responseProperties: oauthSchema["get-token"]?.["response-properties"]
+        })
     };
 }
 
 export function getRefreshTokenEndpoint(oauthSchema: RawSchemas.OAuthSchemeSchema): RefreshTokenEndpoint | undefined {
     if (oauthSchema["refresh-token"] == null) {
         return undefined;
     }
-    const maybeExpiresIn = oauthSchema["get-token"]["response-properties"]["expires-in"];
-    const maybeRefreshToken = oauthSchema["get-token"]["response-properties"]["refresh-token"];
     return {
         endpoint: oauthSchema["refresh-token"].endpoint,
-        requestProperties: {
-            type: "refresh_token",
-            refresh_token: getRequestPropertyComponents(
-                oauthSchema["refresh-token"]["request-properties"]["refresh-token"]
-            )
-        },
-        responseProperties: {
-            type: "access_token",
-            access_token: getResponsePropertyComponents(
-                oauthSchema["get-token"]["response-properties"]["access-token"]
-            ),
-            expires_in: maybeExpiresIn != null ? getResponsePropertyComponents(maybeExpiresIn) : undefined,
-            refresh_token: maybeRefreshToken != null ? getResponsePropertyComponents(maybeRefreshToken) : undefined
-        }
+        requestProperties: getRefreshTokenEndpointRequestProperties({
+            requestProperties: oauthSchema["refresh-token"]?.["request-properties"]
+        }),
+        responseProperties: getRefreshTokenEndpointResponseProperties({
+            responseProperties: oauthSchema["refresh-token"]?.["response-properties"]
+        })
+    };
+}
+
+function getTokenEndpointRequestProperties({
+    requestProperties
+}: {
+    requestProperties: RawSchemas.OAuthAccessTokenRequestPropertiesSchema | undefined;
+}): OAuthAccessTokenRequestPropertyComponents {
+    if (requestProperties == null) {
+        return DEFAULT_TOKEN_ENDPOINT.requestProperties;
+    }
+    const maybeClientId = requestProperties["client-id"];
+    const maybeClientSecret = requestProperties["client-secret"];
+    const maybeScopes = requestProperties.scopes;
+    return {
+        type: "access_token",
+        client_id:
+            maybeClientId != null
+                ? getRequestPropertyComponents(maybeClientId)
+                : DEFAULT_TOKEN_ENDPOINT.requestProperties.client_id,
+        client_secret:
+            maybeClientSecret != null
+                ? getRequestPropertyComponents(maybeClientSecret)
+                : DEFAULT_TOKEN_ENDPOINT.requestProperties.client_secret,
+        scopes:
+            maybeScopes != null
+                ? getRequestPropertyComponents(maybeScopes)
+                : DEFAULT_TOKEN_ENDPOINT.requestProperties.scopes
+    };
+}
+
+function getTokenEndpointResponseProperties({
+    responseProperties
+}: {
+    responseProperties: RawSchemas.OAuthAccessTokenResponsePropertiesSchema | undefined;
+}): OAuthAccessTokenResponsePropertyComponents {
+    return getTokenEndpointResponsePropertiesWithDefault({
+        responseProperties,
+        defaultValue: DEFAULT_TOKEN_ENDPOINT.responseProperties
+    });
+}
+
+function getRefreshTokenEndpointRequestProperties({
+    requestProperties
+}: {
+    requestProperties: RawSchemas.OAuthRefreshTokenRequestPropertiesSchema | undefined;
+}): OAuthRefreshTokenRequestPropertyComponents {
+    if (requestProperties == null) {
+        return DEFAULT_REFRESH_TOKEN_ENDPOINT.requestProperties;
+    }
+    const maybeRefreshToken = requestProperties["refresh-token"];
+    return {
+        type: "refresh_token",
+        refresh_token:
+            maybeRefreshToken != null
+                ? getRequestPropertyComponents(maybeRefreshToken)
+                : DEFAULT_REFRESH_TOKEN_ENDPOINT.requestProperties.refresh_token
+    };
+}
+
+function getRefreshTokenEndpointResponseProperties({
+    responseProperties
+}: {
+    responseProperties: RawSchemas.OAuthAccessTokenResponsePropertiesSchema | undefined;
+}): OAuthAccessTokenResponsePropertyComponents {
+    return getTokenEndpointResponsePropertiesWithDefault({
+        responseProperties,
+        defaultValue: DEFAULT_REFRESH_TOKEN_ENDPOINT.responseProperties
+    });
+}
+
+function getTokenEndpointResponsePropertiesWithDefault({
+    responseProperties,
+    defaultValue
+}: {
+    responseProperties: RawSchemas.OAuthAccessTokenResponsePropertiesSchema | undefined;
+    defaultValue: OAuthAccessTokenResponsePropertyComponents;
+}): OAuthAccessTokenResponsePropertyComponents {
+    if (responseProperties == null) {
+        return defaultValue;
+    }
+    const maybeAccessToken = responseProperties["access-token"];
+    const maybeExpiresIn = responseProperties["expires-in"];
+    const maybeRefreshToken = responseProperties["refresh-token"];
+    return {
+        type: "access_token",
+        access_token:
+            maybeAccessToken != null ? getResponsePropertyComponents(maybeAccessToken) : defaultValue.access_token,
+        expires_in: maybeExpiresIn != null ? getResponsePropertyComponents(maybeExpiresIn) : defaultValue.expires_in,
+        refresh_token:
+            maybeRefreshToken != null ? getResponsePropertyComponents(maybeRefreshToken) : defaultValue.refresh_token
     };
 }

packages/cli/yaml/validator/package.json

@@ -37,7 +37,8 @@
     "@fern-api/yaml-schema": "workspace:*",
     "chalk": "^5.0.1",
     "lodash-es": "^4.17.21",
-    "strip-ansi": "^7.1.0"
+    "strip-ansi": "^7.1.0",
+    "terminal-link": "^3.0.0"
   },
   "devDependencies": {
     "@types/jest": "^29.0.3",

packages/cli/yaml/validator/src/rules/valid-oauth/__test__/fixtures/invalid/definition/api.yml → packages/cli/yaml/validator/src/rules/valid-oauth/__test__/fixtures/invalid/missing/definition/api.yml

@@ -1,18 +1,18 @@
-name: invalid
-imports: 
+name: missing
+imports:
   auth: auth.yml
 
 auth: OAuthScheme
 auth-schemes:
   OAuthScheme: 
     scheme: oauth
     type: client-credentials
-    get-token: 
+    get-token:
       endpoint: auth.getTokenWithClientCredentials
-      response-properties: 
-        access-token: $response.missing.access_token
-        expires-in: $response.missing.expires_in
-    refresh-token: 
+      response-properties:
+        access-token: $response.accessToken
+        expires-in: $response.expiresIn
+    refresh-token:
       endpoint: auth.refreshToken
       request-properties:
         refresh-token: $request.refreshTokenDoesNotExist

packages/cli/yaml/validator/src/rules/valid-oauth/__test__/fixtures/invalid/definition/auth.yml → packages/cli/yaml/validator/src/rules/valid-oauth/__test__/fixtures/invalid/missing/definition/auth.yml

@@ -14,7 +14,7 @@ service:
     getTokenWithClientCredentials:
       path: /token
       method: POST
-      request: 
+      request:
         name: GetTokenRequest
         body:
           properties:

packages/cli/yaml/validator/src/rules/valid-oauth/__test__/fixtures/invalid/property-path/definition/api.yml

@@ -0,0 +1,14 @@
+name: invalid
+imports:
+  auth: auth.yml
+
+auth: OAuthScheme
+auth-schemes:
+  OAuthScheme:
+    scheme: oauth
+    type: client-credentials
+    get-token:
+      endpoint: auth.getToken
+      request-properties:
+        client-id: $request.credentials.client_id
+        client-secret: $request.credentials.client_secret

packages/cli/yaml/validator/src/rules/valid-oauth/__test__/fixtures/invalid/property-path/definition/auth.yml

@@ -0,0 +1,29 @@
+types:
+  TokenCredentials:
+    docs: |
+      The credentials required to retrieve an access token.
+    properties:
+      client_id: string
+      client_secret: string
+
+  TokenResponse:
+    docs: |
+      An OAuth token response.
+    properties:
+      access_token: string
+      expires_in: integer
+      refresh_token: optional<string>
+
+service:
+  auth: false
+  base-path: /
+  endpoints:
+    getToken:
+      path: /token
+      method: POST
+      request:
+        name: GetTokenRequest
+        body:
+          properties:
+            credentials: TokenCredentials
+      response: TokenResponse

packages/cli/yaml/validator/src/rules/valid-oauth/__test__/fixtures/invalid/types/definition/api.yml

@@ -0,0 +1,13 @@
+name: invalid
+imports:
+  auth: auth.yml
+
+auth: OAuthScheme
+auth-schemes:
+  OAuthScheme:
+    scheme: oauth
+    type: client-credentials
+    get-token:
+      endpoint: auth.getToken
+      request-properties:
+        scopes: $request.scopes

packages/cli/yaml/validator/src/rules/valid-oauth/__test__/fixtures/invalid/types/definition/auth.yml

@@ -0,0 +1,24 @@
+types:
+  TokenResponse:
+    docs: |
+      An OAuth token response.
+    properties:
+      access_token: string
+      expires_in: integer
+      refresh_token: optional<string>
+
+service:
+  auth: false
+  base-path: /
+  endpoints:
+    getToken:
+      path: /token
+      method: POST
+      request:
+        name: GetTokenRequest
+        body:
+          properties:
+            client_id: uuid
+            client_secret: uuid
+            scopes: integer
+      response: TokenResponse

packages/cli/yaml/validator/src/rules/valid-oauth/__test__/fixtures/valid/alias/definition/api.yml

@@ -0,0 +1,11 @@
+name: alias
+imports:
+  auth: auth.yml
+
+auth: OAuthScheme
+auth-schemes:
+  OAuthScheme:
+    scheme: oauth
+    type: client-credentials
+    get-token:
+      endpoint: auth.getToken

packages/cli/yaml/validator/src/rules/valid-oauth/__test__/fixtures/valid/alias/definition/auth.yml

@@ -0,0 +1,26 @@
+types:
+  ClientID: string
+  ClientSecret: string
+  AccessToken: string
+
+  TokenResponse:
+    docs: |
+      An OAuth token response.
+    properties:
+      access_token: AccessToken
+
+service:
+  auth: false
+  base-path: /
+  endpoints:
+    getToken:
+      path: /token
+      method: POST
+      request:
+        name: GetTokenRequest
+        body:
+          properties:
+            client_id: ClientID
+            client_secret: ClientSecret
+            grant_type: literal<"client_credentials">
+      response: TokenResponse