add api to retrieve template extensions info from scaffolder-backend

Signed-off-by: Matt Benson <gudnabrsam@gmail.com>

.changeset/strange-planes-kneel.md

@@ -0,0 +1,6 @@
+---
+'@backstage/plugin-scaffolder-react': minor
+'@backstage/plugin-scaffolder': minor
+---
+
+add api to retrieve template extensions info from scaffolder-backend

plugins/scaffolder-react/report.api.md

@@ -55,11 +55,8 @@ export type Action = {
   examples?: ActionExample[];
 };
 
-// @public
-export type ActionExample = {
-  description: string;
-  example: string;
-};
+// @public @deprecated
+export type ActionExample = ScaffolderUsageExample;
 
 // @public
 export function createScaffolderFieldExtension<
@@ -168,6 +165,15 @@ export type LayoutTemplate<T = any> = NonNullable<
 // @public
 export type ListActionsResponse = Array<Action>;
 
+// @public
+export type ListTemplateExtensionsResponse = {
+  filters: Record<string, TemplateFilter>;
+  globals: {
+    functions: Record<string, TemplateGlobalFunction>;
+    values: Record<string, TemplateGlobalValue>;
+  };
+};
+
 // @public
 export type LogEvent = {
   type: 'log' | 'completion' | 'cancelled' | 'recovered';
@@ -241,6 +247,7 @@ export interface ScaffolderApi {
     tasks: ScaffolderTask[];
     totalTasks?: number;
   }>;
+  listTemplateExtensions?(): Promise<ListTemplateExtensionsResponse>;
   retry?(taskId: string): Promise<void>;
   scaffold(
     options: ScaffolderScaffoldOptions,
@@ -492,6 +499,13 @@ export type ScaffolderTaskStatus =
   | 'processing'
   | 'skipped';
 
+// @public
+export type ScaffolderUsageExample = {
+  description?: string;
+  example: string;
+  notes?: string;
+};
+
 // @public
 export interface ScaffolderUseTemplateSecrets {
   // (undocumented)
@@ -523,6 +537,33 @@ export type TaskStream = {
   output?: ScaffolderTaskOutput;
 };
 
+// @public
+export type TemplateFilter = {
+  description?: string;
+  schema?: {
+    input?: JSONSchema7;
+    arguments?: JSONSchema7[];
+    output?: JSONSchema7;
+  };
+  examples?: ScaffolderUsageExample[];
+};
+
+// @public
+export type TemplateGlobalFunction = {
+  description?: string;
+  schema?: {
+    arguments?: JSONSchema7[];
+    output?: JSONSchema7;
+  };
+  examples?: ScaffolderUsageExample[];
+};
+
+// @public
+export type TemplateGlobalValue = {
+  description?: string;
+  value: JsonValue;
+};
+
 // @public (undocumented)
 export type TemplateGroupFilter = {
   title?: React.ReactNode;

plugins/scaffolder-react/src/api/types.ts

@@ -45,15 +45,24 @@ export type ScaffolderTask = {
 };
 
 /**
- * A single action example
+ * A single scaffolder usage example
  *
  * @public
  */
-export type ActionExample = {
-  description: string;
+export type ScaffolderUsageExample = {
+  description?: string;
   example: string;
+  notes?: string;
 };
 
+/**
+ * A single action example
+ *
+ * @public
+ * @deprecated in favor of ScaffolderUsageExample
+ */
+export type ActionExample = ScaffolderUsageExample;
+
 /**
  * The response shape for a single action in the `listActions` call to the `scaffolder-backend`
  *
@@ -76,6 +85,58 @@ export type Action = {
  */
 export type ListActionsResponse = Array<Action>;
 
+/**
+ * The response shape for a single filter in the `listTemplateExtensions` call to the `scaffolder-backend`
+ *
+ * @public
+ */
+export type TemplateFilter = {
+  description?: string;
+  schema?: {
+    input?: JSONSchema7;
+    arguments?: JSONSchema7[];
+    output?: JSONSchema7;
+  };
+  examples?: ScaffolderUsageExample[];
+};
+
+/**
+ * The response shape for a single global function in the `listTemplateExtensions` call to the `scaffolder-backend`
+ *
+ * @public
+ */
+export type TemplateGlobalFunction = {
+  description?: string;
+  schema?: {
+    arguments?: JSONSchema7[];
+    output?: JSONSchema7;
+  };
+  examples?: ScaffolderUsageExample[];
+};
+
+/**
+ * The response shape for a single global value in the `listTemplateExtensions` call to the `scaffolder-backend`
+ *
+ * @public
+ */
+export type TemplateGlobalValue = {
+  description?: string;
+  value: JsonValue;
+};
+
+/**
+ * The response shape for the `listTemplateExtensions` call to the `scaffolder-backend`
+ *
+ * @public
+ */
+export type ListTemplateExtensionsResponse = {
+  filters: Record<string, TemplateFilter>;
+  globals: {
+    functions: Record<string, TemplateGlobalFunction>;
+    values: Record<string, TemplateGlobalValue>;
+  };
+};
+
 /** @public */
 export type ScaffolderOutputLink = {
   title?: string;
@@ -236,6 +297,11 @@ export interface ScaffolderApi {
    */
   listActions(): Promise<ListActionsResponse>;
 
+  /**
+   * Returns a structure describing the available templating extensions.
+   */
+  listTemplateExtensions?(): Promise<ListTemplateExtensionsResponse>;
+
   streamLogs(options: ScaffolderStreamLogsOptions): Observable<LogEvent>;
 
   dryRun?(options: ScaffolderDryRunOptions): Promise<ScaffolderDryRunResponse>;

plugins/scaffolder/report.api.md

@@ -25,6 +25,7 @@ import { JSX as JSX_2 } from 'react';
 import { LayoutOptions as LayoutOptions_2 } from '@backstage/plugin-scaffolder-react';
 import { LayoutTemplate as LayoutTemplate_2 } from '@backstage/plugin-scaffolder-react';
 import { ListActionsResponse as ListActionsResponse_2 } from '@backstage/plugin-scaffolder-react';
+import { ListTemplateExtensionsResponse } from '@backstage/plugin-scaffolder-react';
 import { LogEvent as LogEvent_2 } from '@backstage/plugin-scaffolder-react';
 import { Observable } from '@backstage/types';
 import { PathParams } from '@backstage/core-plugin-api';
@@ -561,6 +562,8 @@ export class ScaffolderClient implements ScaffolderApi_2 {
     totalTasks?: number;
   }>;
   // (undocumented)
+  listTemplateExtensions(): Promise<ListTemplateExtensionsResponse>;
+  // (undocumented)
   retry?(taskId: string): Promise<void>;
   // (undocumented)
   scaffold(

plugins/scaffolder/src/api.ts

@@ -24,6 +24,7 @@ import { ResponseError } from '@backstage/errors';
 import { ScmIntegrationRegistry } from '@backstage/integration';
 import {
   ListActionsResponse,
+  ListTemplateExtensionsResponse,
   LogEvent,
   ScaffolderApi,
   ScaffolderDryRunOptions,
@@ -324,6 +325,17 @@ export class ScaffolderClient implements ScaffolderApi {
     return await response.json();
   }
 
+  async listTemplateExtensions(): Promise<ListTemplateExtensionsResponse> {
+    const baseUrl = await this.discoveryApi.getBaseUrl('scaffolder');
+    const response = await this.fetchApi.fetch(
+      `${baseUrl}/v2/template-extensions`,
+    );
+    if (!response.ok) {
+      throw ResponseError.fromResponse(response);
+    }
+    return response.json();
+  }
+
   async cancelTask(taskId: string): Promise<void> {
     const baseUrl = await this.discoveryApi.getBaseUrl('scaffolder');
     const url = `${baseUrl}/v2/tasks/${encodeURIComponent(taskId)}/cancel`;