fix: add in the IR endpoint identifier (optionally) to have a more un…

…ique id (#881)

fern/apis/fdr/definition/api/v1/db/endpoint.yml

@@ -14,6 +14,7 @@ types:
       environments: optional<list<readEndpoint.Environment>>
       method: readEndpoint.HttpMethod
       id: readEndpoint.EndpointId
+      originalEndpointId: optional<string>
       urlSlug: string
       migratedFromUrlSlugs: optional<list<string>>
       name: optional<string>

fern/apis/fdr/definition/api/v1/read/endpoint.yml

@@ -21,6 +21,7 @@ types:
       environments: list<Environment>
       method: HttpMethod
       id: EndpointId
+      originalEndpointId: optional<string>
       urlSlug: string
       migratedFromUrlSlugs: optional<list<string>>
       name: optional<string>
@@ -112,7 +113,7 @@ types:
     extends: commons.WithDescription
     properties:
       type: HttpResponseBodyShape
-      statusCode: 
+      statusCode:
         type: optional<integer>
         docs: Defaults to 200
 

fern/apis/fdr/definition/api/v1/register/endpoint.yml

@@ -18,7 +18,15 @@ types:
       defaultEnvironment: optional<EnvironmentId>
       environments: optional<list<Environment>>
       method: HttpMethod
-      id: EndpointId
+      id:
+        type: EndpointId
+        docs: This is the name of the endpoint.
+      originalEndpointId:
+        type: optional<string>
+        docs: |
+          The ID for the endpoint as declared within the IR, this is a unique name for the endpoint, whereas
+          path and method are not (specifically for the fern definition, consider chat and chat stream).
+          This is optional to remain backcompat with old definitions of yore.
       name: optional<string>
       path: EndpointPath
       queryParameters: list<QueryParameter>

fern/apis/fdr/definition/commons.yml

@@ -14,11 +14,17 @@ types:
   DocsConfigId:
     type: string
     docs: The ID of a particular docs config.
-  
+
   EndpointIdentifier:
     properties:
       path: EndpointPath
       method: EndpointMethod
+      identifierOverride:
+        type: optional<string>
+        docs: |
+          The ID for the endpoint as declared within the IR, this is a unique name for the endpoint, whereas path and
+          method are not (specifically for the fern definition, consider chat and chat stream). This is optional to 
+          remain backcompat with old snippets of yore.
 
   EndpointPath:
     type: string

fern/fern.config.json

@@ -1,4 +1,4 @@
 {
   "organization": "fern",
-  "version": "0.26.7"
+  "version": "0.26.9"
 }

packages/fdr-sdk/src/client/generated/api/resources/api/resources/v1/resources/db/resources/endpoint/types/DbEndpointDefinition.ts

@@ -11,6 +11,7 @@ export interface DbEndpointDefinition extends FernRegistry.api.v1.read.WithDescr
     environments?: FernRegistry.api.v1.read.Environment[];
     method: FernRegistry.api.v1.read.HttpMethod;
     id: FernRegistry.api.v1.read.EndpointId;
+    originalEndpointId?: string;
     urlSlug: string;
     migratedFromUrlSlugs?: string[];
     name?: string;

packages/fdr-sdk/src/client/generated/api/resources/api/resources/v1/resources/read/resources/endpoint/types/EndpointDefinition.ts

@@ -12,6 +12,7 @@ export interface EndpointDefinition extends FernRegistry.api.v1.read.WithDescrip
     environments: FernRegistry.api.v1.read.Environment[];
     method: FernRegistry.api.v1.read.HttpMethod;
     id: FernRegistry.api.v1.read.EndpointId;
+    originalEndpointId?: string;
     urlSlug: string;
     migratedFromUrlSlugs?: string[];
     name?: string;

packages/fdr-sdk/src/client/generated/api/resources/api/resources/v1/resources/register/resources/endpoint/types/EndpointDefinition.ts

@@ -11,7 +11,14 @@ export interface EndpointDefinition
     defaultEnvironment?: FernRegistry.api.v1.register.EnvironmentId;
     environments?: FernRegistry.api.v1.register.Environment[];
     method: FernRegistry.api.v1.register.HttpMethod;
+    /** This is the name of the endpoint. */
     id: FernRegistry.api.v1.register.EndpointId;
+    /**
+     * The ID for the endpoint as declared within the IR, this is a unique name for the endpoint, whereas
+     * path and method are not (specifically for the fern definition, consider chat and chat stream).
+     * This is optional to remain backcompat with old definitions of yore.
+     */
+    originalEndpointId?: string;
     name?: string;
     path: FernRegistry.api.v1.register.EndpointPath;
     queryParameters: FernRegistry.api.v1.register.QueryParameter[];

packages/fdr-sdk/src/client/generated/api/resources/commons/types/EndpointIdentifier.ts

@@ -7,4 +7,10 @@ import * as FernRegistry from "../../..";
 export interface EndpointIdentifier {
     path: FernRegistry.EndpointPath;
     method: FernRegistry.EndpointMethod;
+    /**
+     * The ID for the endpoint as declared within the IR, this is a unique name for the endpoint, whereas path and
+     * method are not (specifically for the fern definition, consider chat and chat stream). This is optional to
+     * remain backcompat with old snippets of yore.
+     */
+    identifierOverride?: string;
 }

packages/fdr-sdk/src/converters/db/convertAPIDefinitionToDb.ts

@@ -182,6 +182,7 @@ function transformEndpoint({
     // const htmlDescription = getHtmlDescription(writeShape.description);
     const urlSlug = kebabCase(writeShape.id);
     const oldUrlSlug = kebabCase(writeShape.name ?? writeShape.id);
+
     return {
         availability: writeShape.availability,
         environments: writeShape.environments,
@@ -192,6 +193,7 @@ function transformEndpoint({
         migratedFromUrlSlugs: !isEqual(oldUrlSlug, urlSlug) ? [oldUrlSlug] : undefined,
         method: writeShape.method,
         id: writeShape.id,
+        originalEndpointId: writeShape.originalEndpointId,
         name: writeShape.name,
         path: writeShape.path,
         queryParameters: writeShape.queryParameters,
@@ -220,6 +222,7 @@ function transformEndpoint({
         snippetTemplates: snippets.getSnippetTemplateForEndpoint({
             endpointPath: getEndpointPathAsString(writeShape),
             endpointMethod: writeShape.method,
+            identifierOverride: writeShape.originalEndpointId,
         }),
     };
 }
@@ -501,18 +504,22 @@ function transformCodeExamples({
     const maybePythonSnippet = snippets.getPythonCodeSnippetForEndpoint({
         endpointMethod: endpointDefinition.method,
         endpointPath: getEndpointPathAsString(endpointDefinition),
+        identifierOverride: endpointDefinition.originalEndpointId,
     });
     const maybeTypescriptSnippet = snippets.getTypeScriptCodeSnippetForEndpoint({
         endpointMethod: endpointDefinition.method,
         endpointPath: getEndpointPathAsString(endpointDefinition),
+        identifierOverride: endpointDefinition.originalEndpointId,
     });
     const maybeGoSnippet = snippets.getGoCodeSnippetForEndpoint({
         endpointMethod: endpointDefinition.method,
         endpointPath: getEndpointPathAsString(endpointDefinition),
+        identifierOverride: endpointDefinition.originalEndpointId,
     });
     const maybeRubySnippet = snippets.getRubyCodeSnippetForEndpoint({
         endpointMethod: endpointDefinition.method,
         endpointPath: getEndpointPathAsString(endpointDefinition),
+        identifierOverride: endpointDefinition.originalEndpointId,
     });
     return {
         nodeAxios: "",

packages/fdr-sdk/src/converters/db/snippets/SDKSnippetHolder.ts

@@ -9,40 +9,65 @@ export interface SnippetsConfigWithSdkId {
 }
 
 export interface SdkSnippetHolderArgs {
+    // Legacy format for snippets leveraging path and method (which is not unique enough for some cases)
     snippetsBySdkId: Record<string, Record<FdrAPI.EndpointPath, FdrAPI.SnippetsByEndpointMethod>>;
+    // If these are present for the SDK ID, use these, otherwise use snippetsBySdkId
+    snippetsBySdkIdAndEndpointId: Record<string, Record<string, FdrAPI.Snippet[]>>;
     snippetsConfigWithSdkId: SnippetsConfigWithSdkId;
     snippetTemplatesByEndpoint: Record<
         FdrAPI.EndpointPath,
         Record<FdrAPI.EndpointMethod, APIV1Read.EndpointSnippetTemplates>
     >;
+    snippetTemplatesByEndpointId: Record<string, APIV1Read.EndpointSnippetTemplates>;
 }
 
 export class SDKSnippetHolder {
     private snippetsBySdkId: Record<string, Record<FdrAPI.EndpointPath, FdrAPI.SnippetsByEndpointMethod>>;
+    private snippetsBySdkIdAndEndpointId: Record<string, Record<string, FdrAPI.Snippet[]>>;
     private snippetsConfigWithSdkId: SnippetsConfigWithSdkId;
     private snippetTemplatesByEndpoint: Record<
         FdrAPI.EndpointPath,
         Record<FdrAPI.EndpointMethod, APIV1Read.EndpointSnippetTemplates>
     >;
+    private snippetTemplatesByEndpointId: Record<string, APIV1Read.EndpointSnippetTemplates>;
 
-    constructor({ snippetsBySdkId, snippetsConfigWithSdkId, snippetTemplatesByEndpoint }: SdkSnippetHolderArgs) {
+    constructor({
+        snippetsBySdkId,
+        snippetsConfigWithSdkId,
+        snippetTemplatesByEndpoint,
+        snippetsBySdkIdAndEndpointId,
+        snippetTemplatesByEndpointId,
+    }: SdkSnippetHolderArgs) {
         this.snippetsBySdkId = snippetsBySdkId;
         this.snippetsConfigWithSdkId = snippetsConfigWithSdkId;
         this.snippetTemplatesByEndpoint = snippetTemplatesByEndpoint;
+        this.snippetsBySdkIdAndEndpointId = snippetsBySdkIdAndEndpointId;
+        this.snippetTemplatesByEndpointId = snippetTemplatesByEndpointId;
     }
 
     public getPythonCodeSnippetForEndpoint({
         endpointPath,
         endpointMethod,
+        identifierOverride,
     }: {
         endpointPath: string;
         endpointMethod: FdrAPI.EndpointMethod;
+        identifierOverride: string | undefined;
     }): APIV1Read.PythonSnippet | undefined {
         if (this.snippetsConfigWithSdkId.pythonSdk == null) {
             return undefined;
         }
+
         const sdkId = this.snippetsConfigWithSdkId.pythonSdk.sdkId;
-        const snippetsForEndpoint = this.snippetsBySdkId[sdkId]?.[endpointPath]?.[endpointMethod];
+        let snippetsForEndpoint;
+        if (identifierOverride != null) {
+            snippetsForEndpoint = this.snippetsBySdkIdAndEndpointId[sdkId]?.[identifierOverride];
+        }
+
+        if (identifierOverride == null || this.snippetsBySdkIdAndEndpointId[sdkId] == null) {
+            snippetsForEndpoint = this.snippetsBySdkId[sdkId]?.[endpointPath]?.[endpointMethod];
+        }
+
         // if no snippets for this endpoint or multiple snippets just return undefined
         if (snippetsForEndpoint == null || snippetsForEndpoint.length > 1) {
             return undefined;
@@ -60,15 +85,26 @@ export class SDKSnippetHolder {
     public getTypeScriptCodeSnippetForEndpoint({
         endpointPath,
         endpointMethod,
+        identifierOverride,
     }: {
         endpointPath: string;
         endpointMethod: FdrAPI.EndpointMethod;
+        identifierOverride: string | undefined;
     }): APIV1Read.TypescriptSnippet | undefined {
         if (this.snippetsConfigWithSdkId.typescriptSdk == null) {
             return undefined;
         }
+
         const sdkId = this.snippetsConfigWithSdkId.typescriptSdk.sdkId;
-        const snippetsForEndpoint = this.snippetsBySdkId[sdkId]?.[endpointPath]?.[endpointMethod];
+        let snippetsForEndpoint;
+        if (identifierOverride != null) {
+            snippetsForEndpoint = this.snippetsBySdkIdAndEndpointId[sdkId]?.[identifierOverride];
+        }
+
+        if (identifierOverride == null || this.snippetsBySdkIdAndEndpointId[sdkId] == null) {
+            snippetsForEndpoint = this.snippetsBySdkId[sdkId]?.[endpointPath]?.[endpointMethod];
+        }
+
         // if no snippets for this endpoint or multiple snippets just return undefined
         if (snippetsForEndpoint == null || snippetsForEndpoint.length > 1) {
             return undefined;
@@ -85,15 +121,26 @@ export class SDKSnippetHolder {
     public getGoCodeSnippetForEndpoint({
         endpointPath,
         endpointMethod,
+        identifierOverride,
     }: {
         endpointPath: string;
         endpointMethod: FdrAPI.EndpointMethod;
+        identifierOverride: string | undefined;
     }): APIV1Read.GoSnippet | undefined {
         if (this.snippetsConfigWithSdkId.goSdk == null) {
             return undefined;
         }
+
         const sdkId = this.snippetsConfigWithSdkId.goSdk.sdkId;
-        const snippetsForEndpoint = this.snippetsBySdkId[sdkId]?.[endpointPath]?.[endpointMethod];
+        let snippetsForEndpoint;
+        if (identifierOverride != null) {
+            snippetsForEndpoint = this.snippetsBySdkIdAndEndpointId[sdkId]?.[identifierOverride];
+        }
+
+        if (identifierOverride == null || this.snippetsBySdkIdAndEndpointId[sdkId] == null) {
+            snippetsForEndpoint = this.snippetsBySdkId[sdkId]?.[endpointPath]?.[endpointMethod];
+        }
+
         // if no snippets for this endpoint or multiple snippets just return undefined
         if (snippetsForEndpoint == null || snippetsForEndpoint.length > 1) {
             return undefined;
@@ -110,15 +157,26 @@ export class SDKSnippetHolder {
     public getRubyCodeSnippetForEndpoint({
         endpointPath,
         endpointMethod,
+        identifierOverride,
     }: {
         endpointPath: string;
         endpointMethod: FdrAPI.EndpointMethod;
+        identifierOverride: string | undefined;
     }): APIV1Read.RubySnippet | undefined {
         if (this.snippetsConfigWithSdkId.rubySdk == null) {
             return undefined;
         }
+
         const sdkId = this.snippetsConfigWithSdkId.rubySdk.sdkId;
-        const snippetsForEndpoint = this.snippetsBySdkId[sdkId]?.[endpointPath]?.[endpointMethod];
+        let snippetsForEndpoint;
+        if (identifierOverride != null) {
+            snippetsForEndpoint = this.snippetsBySdkIdAndEndpointId[sdkId]?.[identifierOverride];
+        }
+
+        if (identifierOverride == null || this.snippetsBySdkIdAndEndpointId[sdkId] == null) {
+            snippetsForEndpoint = this.snippetsBySdkId[sdkId]?.[endpointPath]?.[endpointMethod];
+        }
+
         // if no snippets for this endpoint or multiple snippets just return undefined
         if (snippetsForEndpoint == null || snippetsForEndpoint.length > 1) {
             return undefined;
@@ -135,10 +193,20 @@ export class SDKSnippetHolder {
     public getSnippetTemplateForEndpoint({
         endpointPath,
         endpointMethod,
+        identifierOverride,
     }: {
         endpointPath: string;
         endpointMethod: FdrAPI.EndpointMethod;
+        identifierOverride: string | undefined;
     }): APIV1Read.EndpointSnippetTemplates | undefined {
-        return this.snippetTemplatesByEndpoint[endpointPath]?.[endpointMethod];
+        let snippetsForEndpoint;
+        if (identifierOverride != null) {
+            snippetsForEndpoint = this.snippetTemplatesByEndpointId[identifierOverride];
+        }
+
+        if (identifierOverride == null || this.snippetTemplatesByEndpointId[identifierOverride] == null) {
+            snippetsForEndpoint = this.snippetTemplatesByEndpoint[endpointPath]?.[endpointMethod];
+        }
+        return snippetsForEndpoint;
     }
 }

packages/fdr-sdk/src/converters/read/convertDbAPIDefinitionToRead.ts

@@ -73,6 +73,7 @@ function transformEndpoint({
         migratedFromUrlSlugs: dbShape.migratedFromUrlSlugs,
         method: dbShape.method,
         id: dbShape.id,
+        originalEndpointId: dbShape.originalEndpointId,
         name: dbShape.name,
         path: dbShape.path,
         queryParameters: dbShape.queryParameters,

servers/fdr/prisma/migrations/20240516210100_add_endpoint_id_override/migration.sql

@@ -0,0 +1,5 @@
+-- AlterTable
+ALTER TABLE "Snippet" ADD COLUMN     "identifierOverride" TEXT;
+
+-- AlterTable
+ALTER TABLE "SnippetTemplate" ADD COLUMN     "identifierOverride" TEXT;

servers/fdr/prisma/schema.prisma

@@ -84,31 +84,33 @@ model OverwrittenAlgoliaIndex {
 }
 
 model SnippetTemplate {
-  id                  String     @id
-  orgId               String
-  apiName             String
-  apiDefinitionId     String
-  endpointPath        String
-  endpointMethod      HttpMethod
-  sdkId               String
+  id                      String     @id
+  orgId                   String
+  apiName                 String
+  apiDefinitionId         String
+  endpointPath            String
+  endpointMethod          HttpMethod
+  identifierOverride      String?
+  sdkId                   String
   // sdk                 Sdk        @relation(fields: [sdkId], references: [id], onDelete: Cascade)
-  version             SnippetTemplateSemanticVersion
+  version                 SnippetTemplateSemanticVersion
   
   // The actual templates themselves held as binary data to save encoding the schema, which may change
-  functionInvocation  Bytes
-  clientInstantiation Bytes
+  functionInvocation      Bytes
+  clientInstantiation     Bytes
 }
 
 model Snippet {
-  id             String     @id
-  orgId          String
-  apiName        String
-  endpointPath   String
-  endpointMethod HttpMethod
-  sdkId          String
-  sdk            Sdk        @relation(fields: [sdkId], references: [id], onDelete: Cascade)
-  snippet        Bytes
-  createdAt      DateTime   @default(now())
+  id                      String     @id
+  orgId                   String
+  apiName                 String
+  endpointPath            String
+  endpointMethod          HttpMethod
+  identifierOverride      String?
+  sdkId                   String
+  sdk                     Sdk        @relation(fields: [sdkId], references: [id], onDelete: Cascade)
+  snippet                 Bytes
+  createdAt               DateTime   @default(now())
 }
 
 model Sdk {