diff --git a/plugins/todo/api-report.md b/plugins/todo/api-report.md index 548d55accb..22fca3cb9e 100644 --- a/plugins/todo/api-report.md +++ b/plugins/todo/api-report.md @@ -7,22 +7,84 @@ import { ApiRef } from '@backstage/core-plugin-api'; import { BackstagePlugin } from '@backstage/core-plugin-api'; +import { DiscoveryApi } from '@backstage/core-plugin-api'; import { Entity } from '@backstage/catalog-model'; +import { IdentityApi } from '@backstage/core-plugin-api'; -// Warning: (ae-missing-release-tag) "EntityTodoContent" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export const EntityTodoContent: () => JSX.Element; -// Warning: (ae-forgotten-export) The symbol "TodoApi" needs to be exported by the entry point index.d.ts -// Warning: (ae-missing-release-tag) "todoApiRef" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public +export interface TodoApi { + listTodos(options: TodoListOptions): Promise; +} + +// @public export const todoApiRef: ApiRef; -// Warning: (ae-missing-release-tag) "todoPlugin" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public +export class TodoClient implements TodoApi { + constructor(options: TodoClientOptions); + // (undocumented) + listTodos({ + entity, + offset, + limit, + orderBy, + filters, + }: TodoListOptions): Promise; +} + +// @public +export interface TodoClientOptions { + // (undocumented) + discoveryApi: DiscoveryApi; + // (undocumented) + identityApi: IdentityApi; +} + +// @public +export type TodoItem = { + text: string; + tag: string; + author?: string; + viewUrl?: string; + lineNumber?: number; + repoFilePath?: string; +}; + +// @public +export type TodoListFields = + | 'text' + | 'tag' + | 'author' + | 'viewUrl' + | 'repoFilePath'; + +// @public +export type TodoListOptions = { + entity?: Entity; + offset?: number; + limit?: number; + orderBy?: { + field: TodoListFields; + direction: 'asc' | 'desc'; + }; + filters?: { + field: TodoListFields; + value: string; + }[]; +}; + +// @public +export type TodoListResult = { + items: TodoItem[]; + totalCount: number; + offset: number; + limit: number; +}; + +// @public export const todoPlugin: BackstagePlugin<{}, {}>; // (No @packageDocumentation comment for this package) diff --git a/plugins/todo/src/api/TodoClient.ts b/plugins/todo/src/api/TodoClient.ts index f4fb4071e8..ab2bbea45b 100644 --- a/plugins/todo/src/api/TodoClient.ts +++ b/plugins/todo/src/api/TodoClient.ts @@ -19,16 +19,26 @@ import { ResponseError } from '@backstage/errors'; import { TodoApi, TodoListOptions, TodoListResult } from './types'; import { DiscoveryApi, IdentityApi } from '@backstage/core-plugin-api'; -interface Options { +/** + * Options for creating a todo client. + * + * @public + */ +export interface TodoClientOptions { discoveryApi: DiscoveryApi; identityApi: IdentityApi; } +/** + * An implementation of the TodoApi that talks to the todo plugin backend. + * + * @public + */ export class TodoClient implements TodoApi { private readonly discoveryApi: DiscoveryApi; private readonly identityApi: IdentityApi; - constructor(options: Options) { + constructor(options: TodoClientOptions) { this.discoveryApi = options.discoveryApi; this.identityApi = options.identityApi; } diff --git a/plugins/todo/src/api/index.ts b/plugins/todo/src/api/index.ts index d6771aeaba..b1d9792c95 100644 --- a/plugins/todo/src/api/index.ts +++ b/plugins/todo/src/api/index.ts @@ -15,5 +15,12 @@ */ export { TodoClient } from './TodoClient'; +export type { TodoClientOptions } from './TodoClient'; export { todoApiRef } from './types'; -export type { TodoApi } from './types'; +export type { + TodoApi, + TodoListOptions, + TodoListResult, + TodoItem, + TodoListFields, +} from './types'; diff --git a/plugins/todo/src/api/types.ts b/plugins/todo/src/api/types.ts index 018f1df536..f1f647f6e3 100644 --- a/plugins/todo/src/api/types.ts +++ b/plugins/todo/src/api/types.ts @@ -17,6 +17,11 @@ import { Entity } from '@backstage/catalog-model'; import { createApiRef } from '@backstage/core-plugin-api'; +/** + * TodoItem represents a single TODO comment in source code. + * + * @public + */ export type TodoItem = { /** The contents of the TODO comment */ text: string; @@ -37,23 +42,43 @@ export type TodoItem = { repoFilePath?: string; }; -type Fields = 'text' | 'tag' | 'author' | 'viewUrl' | 'repoFilePath'; +/** + * Fields that can be used to filter or order todo items. + * + * @public + */ +export type TodoListFields = + | 'text' + | 'tag' + | 'author' + | 'viewUrl' + | 'repoFilePath'; +/** + * Options used to list todo items. + * + * @public + */ export type TodoListOptions = { entity?: Entity; offset?: number; limit?: number; orderBy?: { - field: Fields; + field: TodoListFields; direction: 'asc' | 'desc'; }; filters?: { - field: Fields; + field: TodoListFields; /** Value to filter by, with '*' used as wildcard */ value: string; }[]; }; +/** + * The result of listing todos. + * + * @public + */ export type TodoListResult = { items: TodoItem[]; totalCount: number; @@ -61,10 +86,25 @@ export type TodoListResult = { limit: number; }; +/** + * The API used by the todo-plugin to list todos. + * + * @public + */ export interface TodoApi { + /** + * Lists todo items. + * + * @public + */ listTodos(options: TodoListOptions): Promise; } +/** + * ApiRef for the TodoApi. + * + * @public + */ export const todoApiRef = createApiRef({ id: 'plugin.todo.api', description: 'Lists TODOs', diff --git a/plugins/todo/src/index.ts b/plugins/todo/src/index.ts index d04df36f5e..92a85945ac 100644 --- a/plugins/todo/src/index.ts +++ b/plugins/todo/src/index.ts @@ -14,5 +14,13 @@ * limitations under the License. */ -export { todoApiRef } from './api'; +export { todoApiRef, TodoClient } from './api'; +export type { + TodoApi, + TodoListOptions, + TodoListResult, + TodoItem, + TodoListFields, + TodoClientOptions, +} from './api'; export { todoPlugin, EntityTodoContent } from './plugin'; diff --git a/plugins/todo/src/plugin.ts b/plugins/todo/src/plugin.ts index dd24304d0a..5415bbb902 100644 --- a/plugins/todo/src/plugin.ts +++ b/plugins/todo/src/plugin.ts @@ -22,8 +22,11 @@ import { identityApiRef, } from '@backstage/core-plugin-api'; -// import { rootRouteRef } from './routes'; - +/** + * The Todo plugin instance. + * + * @public + */ export const todoPlugin = createPlugin({ id: 'todo', apis: [ @@ -43,6 +46,11 @@ export const todoPlugin = createPlugin({ }, }); +/** + * An extension for displaying the list of todos on an entity page. + * + * @public + */ export const EntityTodoContent = todoPlugin.provide( createComponentExtension({ component: {