fix, ts: leverage the full package path for reference.md (#3083)

generators/typescript/sdk/CHANGELOG.md

@@ -7,38 +7,48 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [0.12.3-rc1] - 2024-02-27
 
-- Fix: Previously SDK code snippets would not support generation with undiscriminated
-  unions. Now, it does. 
+- Fix: Previously reference.md was just leveraging the function name for the reference, now it leverages the full package-scoped path, mirroring how the function would be used in reality.
 
+```ts
+seedExamples.getException(...)
+
+// is now
+
+seedExamples.file.notification.service.getException(...)
+```
+
+## [0.12.3-rc1] - 2024-02-27
+
+- Fix: Previously SDK code snippets would not support generation with undiscriminated unions. Now, it does.
 
 ## [0.12.2] - 2024-02-27
 
 - Fix: Previously SDK code snippets would not take into account default parameter values
-  and would always include a `{}`. This was odd and didn't represent how a developer 
-  would use the SDK. Now, the snippets check for default parameter values and omit 
-  if there are no fields specified. 
+  and would always include a `{}`. This was odd and didn't represent how a developer
+  would use the SDK. Now, the snippets check for default parameter values and omit
+  if there are no fields specified.
 
   ```ts
   // Before
-  client.users.list({})
+  client.users.list({});
 
   // After
-  client.users.list()
+  client.users.list();
   ```
 
 ## [0.12.1] - 2024-02-27
 
-- Fix: Optional objects in deep query parameters were previously being incorrectly 
+- Fix: Optional objects in deep query parameters were previously being incorrectly
   serialized. Before this change, optional objects were just being JSON.stringified
-  which would send the incorrect contents over the wire. 
+  which would send the incorrect contents over the wire.
 
   ```ts
   // Before
   if (foo != null) {
     _queryParams["foo"] = JSON.stringify(foo);
   }
 
-  // After 
+  // After
   if (foo != null) {
     _queryParams["foo"] = foo;
   }
@@ -48,21 +58,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
     _queryParams["foo"] = serializers.Foo.jsonOrThrow(foo, {
       skipValidation: false,
       breadcrumbs: ["request", "foo"]
-    })
+    });
   }
   ```
 
 ## [0.12.0] - 2024-02-26
 
-- Feature: support deep object query parameter serialization. If, query parameters are 
-  objects then Fern will support serializing them. 
+- Feature: support deep object query parameter serialization. If, query parameters are
+  objects then Fern will support serializing them.
 
   ```yaml
-  MyFoo: 
-    properties: 
-      bar: optional<string> 
+  MyFoo:
+    properties:
+      bar: optional<string>
 
-  query-parameters: 
+  query-parameters:
     foo: MyFoo
   ```
 
@@ -71,22 +81,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   ```ts
   client.doThing({
     foo: {
-      bar: "...",
+      bar: "..."
     }
-  })
+  });
   ```
-  
+
 ## [0.11.5] - 2024-02-15
 
-- Fix: Previously `core.Stream` would not work in the Browser. Now the generated Fern SDK 
-  includes a polyfill for `ReadableStream` and uses `TextDecoder` instead of `Buffer`. 
+- Fix: Previously `core.Stream` would not work in the Browser. Now the generated Fern SDK
+  includes a polyfill for `ReadableStream` and uses `TextDecoder` instead of `Buffer`.
 
-- Feature: add in a reference markdown file, this shows a quick outline of the available endpoints, 
+- Feature: add in a reference markdown file, this shows a quick outline of the available endpoints,
   it's documentation, code snippet, and parameters.
 
-  This feature is currently behind a feature flag called `includeApiReference` and can be used 
+  This feature is currently behind a feature flag called `includeApiReference` and can be used
+
   ```yaml
-  config: 
+  config:
     includeApiReference: true
   ```
 

generators/typescript/sdk/VERSION

@@ -1 +1 @@
-0.12.3-rc1
+0.12.4

generators/typescript/sdk/generator/src/ReferenceGenerator.ts

@@ -1,12 +1,11 @@
 export declare namespace ReferenceGenerator {
     export interface Init {
-        clientName: string;
-        apiName?: string;
+        apiName: string;
     }
 }
 export declare namespace ReferenceGeneratorSection {
     export interface Init {
-        clientName: string;
+        apiName: string;
         // Heading is essentially just the endpoint name in the root package OR
         heading: string;
     }
@@ -21,6 +20,7 @@ export interface ReferenceParameterDeclaration {
 export interface EndpointDeclaration {
     functionPath?: string;
     functionName: string;
+    clientPath?: string;
     returnType: string | undefined;
     returnTypePath?: string;
     codeSnippet: string | undefined;
@@ -44,12 +44,12 @@ function writeSignature(parameters: ReferenceParameterDeclaration[]): string {
 }
 
 class ReferenceGeneratorSection {
-    clientName: string;
+    apiName: string;
     heading: string;
     endpoints: EndpointDeclaration[];
 
     constructor(init: ReferenceGeneratorSection.Init) {
-        this.clientName = init.clientName;
+        this.apiName = init.apiName;
         this.heading = init.heading;
         this.endpoints = [];
     }
@@ -89,9 +89,10 @@ class ReferenceGeneratorSection {
                 : "";
 
         return `
-<details><summary> <code>${this.clientName}.${wrapInLink(endpoint.functionName, endpoint.functionPath)}${writeSignature(
-            endpoint.parameters
-        )} -> ${wrapInLink(
+<details><summary> <code>${endpoint.clientPath ?? this.apiName}.${wrapInLink(
+            endpoint.functionName,
+            endpoint.functionPath
+        )}${writeSignature(endpoint.parameters)} -> ${wrapInLink(
             endpoint.returnType === undefined ? "void" : endpoint.returnType,
             endpoint.returnTypePath
         )}</code> </summary>
@@ -112,18 +113,17 @@ ${this.endpoints.map((endpoint) => this.writeEndpoint(endpoint)).join("\n")}
 }
 
 export class ReferenceGenerator {
-    apiName: string | undefined;
-    clientName: string;
+    apiName: string;
     sections: ReferenceGeneratorSection[];
 
     constructor(init: ReferenceGenerator.Init) {
-        this.clientName = init.clientName;
+        this.apiName = init.apiName;
         this.apiName = init.apiName;
         this.sections = [];
     }
 
     public addSection(heading: string): ReferenceGeneratorSection {
-        const section = new ReferenceGeneratorSection({ clientName: this.clientName, heading });
+        const section = new ReferenceGeneratorSection({ apiName: this.apiName, heading });
         this.sections.push(section);
         return section;
     }

generators/typescript/sdk/generator/src/SdkGenerator.ts

@@ -351,7 +351,6 @@ module.exports = {
             let refGenerator: ReferenceGenerator | undefined;
             if (this.config.includeApiReference) {
                 refGenerator = new ReferenceGenerator({
-                    clientName: this.intermediateRepresentation.apiName.camelCase.safeName,
                     apiName: this.namespaceExport === "api" ? "client" : this.namespaceExport
                 });
             }
@@ -640,6 +639,7 @@ module.exports = {
 
                     if (serviceReference !== undefined) {
                         let returnType = undefined;
+                        let endpointClientAccess: ts.Expression | undefined = undefined;
                         const parameters: ReferenceParameterDeclaration[] = [];
                         const referenceSnippet = this.withSnippet({
                             run: ({ sourceFile, importsManager }): ts.Node[] | undefined => {
@@ -662,6 +662,10 @@ module.exports = {
                                     }) ?? [])
                                 );
 
+                                endpointClientAccess = clientClass.accessFromRootClient({
+                                    referenceToRootClient: context.sdkInstanceReferenceForSnippet
+                                });
+
                                 return this.runWithSnippet({
                                     sourceFile,
                                     importsManager,
@@ -675,7 +679,15 @@ module.exports = {
                             includeImports: false
                         });
 
+                        let statement = undefined;
+                        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+                        if (endpointClientAccess !== undefined) {
+                            statement = getTextOfTsNode(endpointClientAccess);
+                        }
+
                         serviceReference.addEndpoint({
+                            // clientPath: getTextOfTsNode(statement),
+                            clientPath: statement,
                             functionPath: serviceFilepath,
                             functionName: endpoint.name.camelCase.unsafeName,
                             returnType,

packages/seed/fern/definition/features.yml

@@ -82,6 +82,11 @@ types:
         docs: |
           The SDK should provide a way to access additional properties on the response object. 
           This is useful for when the API adds new fields to the response object and the user wants to grab them without upgrading the SDK.
+      apiReferenceGeneration: 
+        type: FeatureImplementation
+        docs: |
+          The SDK should generate an API reference markdown file (refrence.md at the root level) that shows all the endpoints, their documentation,
+           their parameters, and their responses.
       whitelabel: 
         type: FeatureImplementation
         docs: | 

seed/ruby-sdk/seed.yml

@@ -23,3 +23,4 @@ features:
   forwardCompatibleEnums: true
   additionalProperties: true
   whitelabel: false
+  apiReferenceGeneration: false

seed/ts-sdk/seed.yml

@@ -108,4 +108,3 @@ allowedFailures:
   - exhaustive:dev-dependencies
   - audiences
   - enum # throws b/c of undiscriminated union examples
-  - examples:examples-with-api-reference # throws b/c of undiscriminated union examples