From 64d1b104d0b1bfe13f590db87226ffd73930e900 Mon Sep 17 00:00:00 2001 From: Rob Herley Date: Thu, 7 Dec 2023 12:57:20 -0500 Subject: [PATCH] Generate Typescript Docs for `@actions/artifact` (#1595) * autogenerate artifact documentation * clean up comments for better autogen docs --- packages/artifact/docs/generated/README.md | 40 ++++ .../classes/ArtifactNotFoundError.md | 169 ++++++++++++++++ .../classes/DefaultArtifactClient.md | 161 ++++++++++++++++ .../generated/classes/FilesNotFoundError.md | 180 ++++++++++++++++++ .../classes/GHESNotSupportedError.md | 169 ++++++++++++++++ .../generated/classes/InvalidResponseError.md | 169 ++++++++++++++++ .../docs/generated/interfaces/Artifact.md | 62 ++++++ .../generated/interfaces/ArtifactClient.md | 131 +++++++++++++ .../interfaces/DownloadArtifactOptions.md | 23 +++ .../interfaces/DownloadArtifactResponse.md | 23 +++ .../docs/generated/interfaces/FindOptions.md | 30 +++ .../interfaces/GetArtifactResponse.md | 23 +++ .../interfaces/ListArtifactsOptions.md | 24 +++ .../interfaces/ListArtifactsResponse.md | 23 +++ .../interfaces/UploadArtifactOptions.md | 55 ++++++ .../interfaces/UploadArtifactResponse.md | 37 ++++ packages/artifact/package-lock.json | 168 ++++++++++++++++ packages/artifact/package.json | 5 +- .../src/internal/shared/interfaces.ts | 71 +++---- 19 files changed, 1530 insertions(+), 33 deletions(-) create mode 100644 packages/artifact/docs/generated/README.md create mode 100644 packages/artifact/docs/generated/classes/ArtifactNotFoundError.md create mode 100644 packages/artifact/docs/generated/classes/DefaultArtifactClient.md create mode 100644 packages/artifact/docs/generated/classes/FilesNotFoundError.md create mode 100644 packages/artifact/docs/generated/classes/GHESNotSupportedError.md create mode 100644 packages/artifact/docs/generated/classes/InvalidResponseError.md create mode 100644 packages/artifact/docs/generated/interfaces/Artifact.md create mode 100644 packages/artifact/docs/generated/interfaces/ArtifactClient.md create mode 100644 packages/artifact/docs/generated/interfaces/DownloadArtifactOptions.md create mode 100644 packages/artifact/docs/generated/interfaces/DownloadArtifactResponse.md create mode 100644 packages/artifact/docs/generated/interfaces/FindOptions.md create mode 100644 packages/artifact/docs/generated/interfaces/GetArtifactResponse.md create mode 100644 packages/artifact/docs/generated/interfaces/ListArtifactsOptions.md create mode 100644 packages/artifact/docs/generated/interfaces/ListArtifactsResponse.md create mode 100644 packages/artifact/docs/generated/interfaces/UploadArtifactOptions.md create mode 100644 packages/artifact/docs/generated/interfaces/UploadArtifactResponse.md diff --git a/packages/artifact/docs/generated/README.md b/packages/artifact/docs/generated/README.md new file mode 100644 index 00000000..a1244395 --- /dev/null +++ b/packages/artifact/docs/generated/README.md @@ -0,0 +1,40 @@ +@actions/artifact + +# @actions/artifact + +## Table of contents + +### Classes + +- [ArtifactNotFoundError](classes/ArtifactNotFoundError.md) +- [DefaultArtifactClient](classes/DefaultArtifactClient.md) +- [FilesNotFoundError](classes/FilesNotFoundError.md) +- [GHESNotSupportedError](classes/GHESNotSupportedError.md) +- [InvalidResponseError](classes/InvalidResponseError.md) + +### Interfaces + +- [Artifact](interfaces/Artifact.md) +- [ArtifactClient](interfaces/ArtifactClient.md) +- [DownloadArtifactOptions](interfaces/DownloadArtifactOptions.md) +- [DownloadArtifactResponse](interfaces/DownloadArtifactResponse.md) +- [FindOptions](interfaces/FindOptions.md) +- [GetArtifactResponse](interfaces/GetArtifactResponse.md) +- [ListArtifactsOptions](interfaces/ListArtifactsOptions.md) +- [ListArtifactsResponse](interfaces/ListArtifactsResponse.md) +- [UploadArtifactOptions](interfaces/UploadArtifactOptions.md) +- [UploadArtifactResponse](interfaces/UploadArtifactResponse.md) + +### Variables + +- [default](README.md#default) + +## Variables + +### default + +• `Const` **default**: [`ArtifactClient`](interfaces/ArtifactClient.md) + +#### Defined in + +[src/artifact.ts:7](https://github.com/actions/toolkit/blob/e3764a5/packages/artifact/src/artifact.ts#L7) diff --git a/packages/artifact/docs/generated/classes/ArtifactNotFoundError.md b/packages/artifact/docs/generated/classes/ArtifactNotFoundError.md new file mode 100644 index 00000000..61700bb3 --- /dev/null +++ b/packages/artifact/docs/generated/classes/ArtifactNotFoundError.md @@ -0,0 +1,169 @@ +[@actions/artifact](../README.md) / ArtifactNotFoundError + +# Class: ArtifactNotFoundError + +## Hierarchy + +- `Error` + + ↳ **`ArtifactNotFoundError`** + +## Table of contents + +### Constructors + +- [constructor](ArtifactNotFoundError.md#constructor) + +### Properties + +- [message](ArtifactNotFoundError.md#message) +- [name](ArtifactNotFoundError.md#name) +- [stack](ArtifactNotFoundError.md#stack) +- [prepareStackTrace](ArtifactNotFoundError.md#preparestacktrace) +- [stackTraceLimit](ArtifactNotFoundError.md#stacktracelimit) + +### Methods + +- [captureStackTrace](ArtifactNotFoundError.md#capturestacktrace) + +## Constructors + +### constructor + +• **new ArtifactNotFoundError**(`message?`): [`ArtifactNotFoundError`](ArtifactNotFoundError.md) + +#### Parameters + +| Name | Type | Default value | +| :------ | :------ | :------ | +| `message` | `string` | `'Artifact not found'` | + +#### Returns + +[`ArtifactNotFoundError`](ArtifactNotFoundError.md) + +#### Overrides + +Error.constructor + +#### Defined in + +[src/internal/shared/errors.ts:24](https://github.com/actions/toolkit/blob/e3764a5/packages/artifact/src/internal/shared/errors.ts#L24) + +## Properties + +### message + +• **message**: `string` + +#### Inherited from + +Error.message + +#### Defined in + +node_modules/typescript/lib/lib.es5.d.ts:1068 + +___ + +### name + +• **name**: `string` + +#### Inherited from + +Error.name + +#### Defined in + +node_modules/typescript/lib/lib.es5.d.ts:1067 + +___ + +### stack + +• `Optional` **stack**: `string` + +#### Inherited from + +Error.stack + +#### Defined in + +node_modules/typescript/lib/lib.es5.d.ts:1069 + +___ + +### prepareStackTrace + +▪ `Static` `Optional` **prepareStackTrace**: (`err`: `Error`, `stackTraces`: `CallSite`[]) => `any` + +#### Type declaration + +▸ (`err`, `stackTraces`): `any` + +Optional override for formatting stack traces + +##### Parameters + +| Name | Type | +| :------ | :------ | +| `err` | `Error` | +| `stackTraces` | `CallSite`[] | + +##### Returns + +`any` + +**`See`** + +https://v8.dev/docs/stack-trace-api#customizing-stack-traces + +#### Inherited from + +Error.prepareStackTrace + +#### Defined in + +node_modules/@types/node/globals.d.ts:11 + +___ + +### stackTraceLimit + +▪ `Static` **stackTraceLimit**: `number` + +#### Inherited from + +Error.stackTraceLimit + +#### Defined in + +node_modules/@types/node/globals.d.ts:13 + +## Methods + +### captureStackTrace + +▸ **captureStackTrace**(`targetObject`, `constructorOpt?`): `void` + +Create .stack property on a target object + +#### Parameters + +| Name | Type | +| :------ | :------ | +| `targetObject` | `object` | +| `constructorOpt?` | `Function` | + +#### Returns + +`void` + +#### Inherited from + +Error.captureStackTrace + +#### Defined in + +node_modules/@types/node/globals.d.ts:4 diff --git a/packages/artifact/docs/generated/classes/DefaultArtifactClient.md b/packages/artifact/docs/generated/classes/DefaultArtifactClient.md new file mode 100644 index 00000000..b93afc3e --- /dev/null +++ b/packages/artifact/docs/generated/classes/DefaultArtifactClient.md @@ -0,0 +1,161 @@ +[@actions/artifact](../README.md) / DefaultArtifactClient + +# Class: DefaultArtifactClient + +The default artifact client that is used by the artifact action(s). + +## Implements + +- [`ArtifactClient`](../interfaces/ArtifactClient.md) + +## Table of contents + +### Constructors + +- [constructor](DefaultArtifactClient.md#constructor) + +### Methods + +- [downloadArtifact](DefaultArtifactClient.md#downloadartifact) +- [getArtifact](DefaultArtifactClient.md#getartifact) +- [listArtifacts](DefaultArtifactClient.md#listartifacts) +- [uploadArtifact](DefaultArtifactClient.md#uploadartifact) + +## Constructors + +### constructor + +• **new DefaultArtifactClient**(): [`DefaultArtifactClient`](DefaultArtifactClient.md) + +#### Returns + +[`DefaultArtifactClient`](DefaultArtifactClient.md) + +## Methods + +### downloadArtifact + +▸ **downloadArtifact**(`artifactId`, `options?`): `Promise`\<[`DownloadArtifactResponse`](../interfaces/DownloadArtifactResponse.md)\> + +Downloads an artifact and unzips the content. + +If `options.findBy` is specified, this will use the public Download Artifact API https://docs.github.com/en/rest/actions/artifacts?apiVersion=2022-11-28#download-an-artifact + +#### Parameters + +| Name | Type | Description | +| :------ | :------ | :------ | +| `artifactId` | `number` | The name of the artifact to download | +| `options?` | [`DownloadArtifactOptions`](../interfaces/DownloadArtifactOptions.md) & [`FindOptions`](../interfaces/FindOptions.md) | Extra options that allow for the customization of the download behavior | + +#### Returns + +`Promise`\<[`DownloadArtifactResponse`](../interfaces/DownloadArtifactResponse.md)\> + +single DownloadArtifactResponse object + +#### Implementation of + +[ArtifactClient](../interfaces/ArtifactClient.md).[downloadArtifact](../interfaces/ArtifactClient.md#downloadartifact) + +#### Defined in + +[src/internal/client.ts:119](https://github.com/actions/toolkit/blob/e3764a5/packages/artifact/src/internal/client.ts#L119) + +___ + +### getArtifact + +▸ **getArtifact**(`artifactName`, `options?`): `Promise`\<[`GetArtifactResponse`](../interfaces/GetArtifactResponse.md)\> + +Finds an artifact by name. +If there are multiple artifacts with the same name in the same workflow run, this will return the latest. +If the artifact is not found, it will throw. + +If `options.findBy` is specified, this will use the public List Artifacts API with a name filter which can get artifacts from other runs. +https://docs.github.com/en/rest/actions/artifacts?apiVersion=2022-11-28#list-workflow-run-artifacts +`@actions/artifact` v2+ does not allow for creating multiple artifacts with the same name in the same workflow run. +It is possible to have multiple artifacts with the same name in the same workflow run by using old versions of upload-artifact (v1,v2 and v3), @actions/artifact < v2 or it is a rerun. +If there are multiple artifacts with the same name in the same workflow run this function will return the first artifact that matches the name. + +#### Parameters + +| Name | Type | Description | +| :------ | :------ | :------ | +| `artifactName` | `string` | The name of the artifact to find | +| `options?` | [`FindOptions`](../interfaces/FindOptions.md) | Extra options that allow for the customization of the get behavior | + +#### Returns + +`Promise`\<[`GetArtifactResponse`](../interfaces/GetArtifactResponse.md)\> + +#### Implementation of + +[ArtifactClient](../interfaces/ArtifactClient.md).[getArtifact](../interfaces/ArtifactClient.md#getartifact) + +#### Defined in + +[src/internal/client.ts:193](https://github.com/actions/toolkit/blob/e3764a5/packages/artifact/src/internal/client.ts#L193) + +___ + +### listArtifacts + +▸ **listArtifacts**(`options?`): `Promise`\<[`ListArtifactsResponse`](../interfaces/ListArtifactsResponse.md)\> + +Lists all artifacts that are part of the current workflow run. +This function will return at most 1000 artifacts per workflow run. + +If `options.findBy` is specified, this will call the public List-Artifacts API which can list from other runs. +https://docs.github.com/en/rest/actions/artifacts?apiVersion=2022-11-28#list-workflow-run-artifacts + +#### Parameters + +| Name | Type | Description | +| :------ | :------ | :------ | +| `options?` | [`ListArtifactsOptions`](../interfaces/ListArtifactsOptions.md) & [`FindOptions`](../interfaces/FindOptions.md) | Extra options that allow for the customization of the list behavior | + +#### Returns + +`Promise`\<[`ListArtifactsResponse`](../interfaces/ListArtifactsResponse.md)\> + +ListArtifactResponse object + +#### Implementation of + +[ArtifactClient](../interfaces/ArtifactClient.md).[listArtifacts](../interfaces/ArtifactClient.md#listartifacts) + +#### Defined in + +[src/internal/client.ts:157](https://github.com/actions/toolkit/blob/e3764a5/packages/artifact/src/internal/client.ts#L157) + +___ + +### uploadArtifact + +▸ **uploadArtifact**(`name`, `files`, `rootDirectory`, `options?`): `Promise`\<[`UploadArtifactResponse`](../interfaces/UploadArtifactResponse.md)\> + +Uploads an artifact. + +#### Parameters + +| Name | Type | Description | +| :------ | :------ | :------ | +| `name` | `string` | The name of the artifact, required | +| `files` | `string`[] | A list of absolute or relative paths that denote what files should be uploaded | +| `rootDirectory` | `string` | An absolute or relative file path that denotes the root parent directory of the files being uploaded | +| `options?` | [`UploadArtifactOptions`](../interfaces/UploadArtifactOptions.md) | Extra options for customizing the upload behavior | + +#### Returns + +`Promise`\<[`UploadArtifactResponse`](../interfaces/UploadArtifactResponse.md)\> + +single UploadArtifactResponse object + +#### Implementation of + +[ArtifactClient](../interfaces/ArtifactClient.md).[uploadArtifact](../interfaces/ArtifactClient.md#uploadartifact) + +#### Defined in + +[src/internal/client.ts:94](https://github.com/actions/toolkit/blob/e3764a5/packages/artifact/src/internal/client.ts#L94) diff --git a/packages/artifact/docs/generated/classes/FilesNotFoundError.md b/packages/artifact/docs/generated/classes/FilesNotFoundError.md new file mode 100644 index 00000000..c7d22014 --- /dev/null +++ b/packages/artifact/docs/generated/classes/FilesNotFoundError.md @@ -0,0 +1,180 @@ +[@actions/artifact](../README.md) / FilesNotFoundError + +# Class: FilesNotFoundError + +## Hierarchy + +- `Error` + + ↳ **`FilesNotFoundError`** + +## Table of contents + +### Constructors + +- [constructor](FilesNotFoundError.md#constructor) + +### Properties + +- [files](FilesNotFoundError.md#files) +- [message](FilesNotFoundError.md#message) +- [name](FilesNotFoundError.md#name) +- [stack](FilesNotFoundError.md#stack) +- [prepareStackTrace](FilesNotFoundError.md#preparestacktrace) +- [stackTraceLimit](FilesNotFoundError.md#stacktracelimit) + +### Methods + +- [captureStackTrace](FilesNotFoundError.md#capturestacktrace) + +## Constructors + +### constructor + +• **new FilesNotFoundError**(`files?`): [`FilesNotFoundError`](FilesNotFoundError.md) + +#### Parameters + +| Name | Type | Default value | +| :------ | :------ | :------ | +| `files` | `string`[] | `[]` | + +#### Returns + +[`FilesNotFoundError`](FilesNotFoundError.md) + +#### Overrides + +Error.constructor + +#### Defined in + +[src/internal/shared/errors.ts:4](https://github.com/actions/toolkit/blob/e3764a5/packages/artifact/src/internal/shared/errors.ts#L4) + +## Properties + +### files + +• **files**: `string`[] + +#### Defined in + +[src/internal/shared/errors.ts:2](https://github.com/actions/toolkit/blob/e3764a5/packages/artifact/src/internal/shared/errors.ts#L2) + +___ + +### message + +• **message**: `string` + +#### Inherited from + +Error.message + +#### Defined in + +node_modules/typescript/lib/lib.es5.d.ts:1068 + +___ + +### name + +• **name**: `string` + +#### Inherited from + +Error.name + +#### Defined in + +node_modules/typescript/lib/lib.es5.d.ts:1067 + +___ + +### stack + +• `Optional` **stack**: `string` + +#### Inherited from + +Error.stack + +#### Defined in + +node_modules/typescript/lib/lib.es5.d.ts:1069 + +___ + +### prepareStackTrace + +▪ `Static` `Optional` **prepareStackTrace**: (`err`: `Error`, `stackTraces`: `CallSite`[]) => `any` + +#### Type declaration + +▸ (`err`, `stackTraces`): `any` + +Optional override for formatting stack traces + +##### Parameters + +| Name | Type | +| :------ | :------ | +| `err` | `Error` | +| `stackTraces` | `CallSite`[] | + +##### Returns + +`any` + +**`See`** + +https://v8.dev/docs/stack-trace-api#customizing-stack-traces + +#### Inherited from + +Error.prepareStackTrace + +#### Defined in + +node_modules/@types/node/globals.d.ts:11 + +___ + +### stackTraceLimit + +▪ `Static` **stackTraceLimit**: `number` + +#### Inherited from + +Error.stackTraceLimit + +#### Defined in + +node_modules/@types/node/globals.d.ts:13 + +## Methods + +### captureStackTrace + +▸ **captureStackTrace**(`targetObject`, `constructorOpt?`): `void` + +Create .stack property on a target object + +#### Parameters + +| Name | Type | +| :------ | :------ | +| `targetObject` | `object` | +| `constructorOpt?` | `Function` | + +#### Returns + +`void` + +#### Inherited from + +Error.captureStackTrace + +#### Defined in + +node_modules/@types/node/globals.d.ts:4 diff --git a/packages/artifact/docs/generated/classes/GHESNotSupportedError.md b/packages/artifact/docs/generated/classes/GHESNotSupportedError.md new file mode 100644 index 00000000..942ae287 --- /dev/null +++ b/packages/artifact/docs/generated/classes/GHESNotSupportedError.md @@ -0,0 +1,169 @@ +[@actions/artifact](../README.md) / GHESNotSupportedError + +# Class: GHESNotSupportedError + +## Hierarchy + +- `Error` + + ↳ **`GHESNotSupportedError`** + +## Table of contents + +### Constructors + +- [constructor](GHESNotSupportedError.md#constructor) + +### Properties + +- [message](GHESNotSupportedError.md#message) +- [name](GHESNotSupportedError.md#name) +- [stack](GHESNotSupportedError.md#stack) +- [prepareStackTrace](GHESNotSupportedError.md#preparestacktrace) +- [stackTraceLimit](GHESNotSupportedError.md#stacktracelimit) + +### Methods + +- [captureStackTrace](GHESNotSupportedError.md#capturestacktrace) + +## Constructors + +### constructor + +• **new GHESNotSupportedError**(`message?`): [`GHESNotSupportedError`](GHESNotSupportedError.md) + +#### Parameters + +| Name | Type | Default value | +| :------ | :------ | :------ | +| `message` | `string` | `'@actions/artifact v2.0.0+, upload-artifact@v4+ and download-artifact@v4+ are not currently supported on GHES.'` | + +#### Returns + +[`GHESNotSupportedError`](GHESNotSupportedError.md) + +#### Overrides + +Error.constructor + +#### Defined in + +[src/internal/shared/errors.ts:31](https://github.com/actions/toolkit/blob/e3764a5/packages/artifact/src/internal/shared/errors.ts#L31) + +## Properties + +### message + +• **message**: `string` + +#### Inherited from + +Error.message + +#### Defined in + +node_modules/typescript/lib/lib.es5.d.ts:1068 + +___ + +### name + +• **name**: `string` + +#### Inherited from + +Error.name + +#### Defined in + +node_modules/typescript/lib/lib.es5.d.ts:1067 + +___ + +### stack + +• `Optional` **stack**: `string` + +#### Inherited from + +Error.stack + +#### Defined in + +node_modules/typescript/lib/lib.es5.d.ts:1069 + +___ + +### prepareStackTrace + +▪ `Static` `Optional` **prepareStackTrace**: (`err`: `Error`, `stackTraces`: `CallSite`[]) => `any` + +#### Type declaration + +▸ (`err`, `stackTraces`): `any` + +Optional override for formatting stack traces + +##### Parameters + +| Name | Type | +| :------ | :------ | +| `err` | `Error` | +| `stackTraces` | `CallSite`[] | + +##### Returns + +`any` + +**`See`** + +https://v8.dev/docs/stack-trace-api#customizing-stack-traces + +#### Inherited from + +Error.prepareStackTrace + +#### Defined in + +node_modules/@types/node/globals.d.ts:11 + +___ + +### stackTraceLimit + +▪ `Static` **stackTraceLimit**: `number` + +#### Inherited from + +Error.stackTraceLimit + +#### Defined in + +node_modules/@types/node/globals.d.ts:13 + +## Methods + +### captureStackTrace + +▸ **captureStackTrace**(`targetObject`, `constructorOpt?`): `void` + +Create .stack property on a target object + +#### Parameters + +| Name | Type | +| :------ | :------ | +| `targetObject` | `object` | +| `constructorOpt?` | `Function` | + +#### Returns + +`void` + +#### Inherited from + +Error.captureStackTrace + +#### Defined in + +node_modules/@types/node/globals.d.ts:4 diff --git a/packages/artifact/docs/generated/classes/InvalidResponseError.md b/packages/artifact/docs/generated/classes/InvalidResponseError.md new file mode 100644 index 00000000..1f6b0b5b --- /dev/null +++ b/packages/artifact/docs/generated/classes/InvalidResponseError.md @@ -0,0 +1,169 @@ +[@actions/artifact](../README.md) / InvalidResponseError + +# Class: InvalidResponseError + +## Hierarchy + +- `Error` + + ↳ **`InvalidResponseError`** + +## Table of contents + +### Constructors + +- [constructor](InvalidResponseError.md#constructor) + +### Properties + +- [message](InvalidResponseError.md#message) +- [name](InvalidResponseError.md#name) +- [stack](InvalidResponseError.md#stack) +- [prepareStackTrace](InvalidResponseError.md#preparestacktrace) +- [stackTraceLimit](InvalidResponseError.md#stacktracelimit) + +### Methods + +- [captureStackTrace](InvalidResponseError.md#capturestacktrace) + +## Constructors + +### constructor + +• **new InvalidResponseError**(`message`): [`InvalidResponseError`](InvalidResponseError.md) + +#### Parameters + +| Name | Type | +| :------ | :------ | +| `message` | `string` | + +#### Returns + +[`InvalidResponseError`](InvalidResponseError.md) + +#### Overrides + +Error.constructor + +#### Defined in + +[src/internal/shared/errors.ts:17](https://github.com/actions/toolkit/blob/e3764a5/packages/artifact/src/internal/shared/errors.ts#L17) + +## Properties + +### message + +• **message**: `string` + +#### Inherited from + +Error.message + +#### Defined in + +node_modules/typescript/lib/lib.es5.d.ts:1068 + +___ + +### name + +• **name**: `string` + +#### Inherited from + +Error.name + +#### Defined in + +node_modules/typescript/lib/lib.es5.d.ts:1067 + +___ + +### stack + +• `Optional` **stack**: `string` + +#### Inherited from + +Error.stack + +#### Defined in + +node_modules/typescript/lib/lib.es5.d.ts:1069 + +___ + +### prepareStackTrace + +▪ `Static` `Optional` **prepareStackTrace**: (`err`: `Error`, `stackTraces`: `CallSite`[]) => `any` + +#### Type declaration + +▸ (`err`, `stackTraces`): `any` + +Optional override for formatting stack traces + +##### Parameters + +| Name | Type | +| :------ | :------ | +| `err` | `Error` | +| `stackTraces` | `CallSite`[] | + +##### Returns + +`any` + +**`See`** + +https://v8.dev/docs/stack-trace-api#customizing-stack-traces + +#### Inherited from + +Error.prepareStackTrace + +#### Defined in + +node_modules/@types/node/globals.d.ts:11 + +___ + +### stackTraceLimit + +▪ `Static` **stackTraceLimit**: `number` + +#### Inherited from + +Error.stackTraceLimit + +#### Defined in + +node_modules/@types/node/globals.d.ts:13 + +## Methods + +### captureStackTrace + +▸ **captureStackTrace**(`targetObject`, `constructorOpt?`): `void` + +Create .stack property on a target object + +#### Parameters + +| Name | Type | +| :------ | :------ | +| `targetObject` | `object` | +| `constructorOpt?` | `Function` | + +#### Returns + +`void` + +#### Inherited from + +Error.captureStackTrace + +#### Defined in + +node_modules/@types/node/globals.d.ts:4 diff --git a/packages/artifact/docs/generated/interfaces/Artifact.md b/packages/artifact/docs/generated/interfaces/Artifact.md new file mode 100644 index 00000000..1597daa5 --- /dev/null +++ b/packages/artifact/docs/generated/interfaces/Artifact.md @@ -0,0 +1,62 @@ +[@actions/artifact](../README.md) / Artifact + +# Interface: Artifact + +An Actions Artifact + +## Table of contents + +### Properties + +- [createdAt](Artifact.md#createdat) +- [id](Artifact.md#id) +- [name](Artifact.md#name) +- [size](Artifact.md#size) + +## Properties + +### createdAt + +• `Optional` **createdAt**: `Date` + +The time when the artifact was created + +#### Defined in + +[src/internal/shared/interfaces.ts:123](https://github.com/actions/toolkit/blob/e3764a5/packages/artifact/src/internal/shared/interfaces.ts#L123) + +___ + +### id + +• **id**: `number` + +The ID of the artifact + +#### Defined in + +[src/internal/shared/interfaces.ts:113](https://github.com/actions/toolkit/blob/e3764a5/packages/artifact/src/internal/shared/interfaces.ts#L113) + +___ + +### name + +• **name**: `string` + +The name of the artifact + +#### Defined in + +[src/internal/shared/interfaces.ts:108](https://github.com/actions/toolkit/blob/e3764a5/packages/artifact/src/internal/shared/interfaces.ts#L108) + +___ + +### size + +• **size**: `number` + +The size of the artifact in bytes + +#### Defined in + +[src/internal/shared/interfaces.ts:118](https://github.com/actions/toolkit/blob/e3764a5/packages/artifact/src/internal/shared/interfaces.ts#L118) diff --git a/packages/artifact/docs/generated/interfaces/ArtifactClient.md b/packages/artifact/docs/generated/interfaces/ArtifactClient.md new file mode 100644 index 00000000..39f7d923 --- /dev/null +++ b/packages/artifact/docs/generated/interfaces/ArtifactClient.md @@ -0,0 +1,131 @@ +[@actions/artifact](../README.md) / ArtifactClient + +# Interface: ArtifactClient + +Generic interface for the artifact client. + +## Implemented by + +- [`DefaultArtifactClient`](../classes/DefaultArtifactClient.md) + +## Table of contents + +### Methods + +- [downloadArtifact](ArtifactClient.md#downloadartifact) +- [getArtifact](ArtifactClient.md#getartifact) +- [listArtifacts](ArtifactClient.md#listartifacts) +- [uploadArtifact](ArtifactClient.md#uploadartifact) + +## Methods + +### downloadArtifact + +▸ **downloadArtifact**(`artifactId`, `options?`): `Promise`\<[`DownloadArtifactResponse`](DownloadArtifactResponse.md)\> + +Downloads an artifact and unzips the content. + +If `options.findBy` is specified, this will use the public Download Artifact API https://docs.github.com/en/rest/actions/artifacts?apiVersion=2022-11-28#download-an-artifact + +#### Parameters + +| Name | Type | Description | +| :------ | :------ | :------ | +| `artifactId` | `number` | The name of the artifact to download | +| `options?` | [`DownloadArtifactOptions`](DownloadArtifactOptions.md) & [`FindOptions`](FindOptions.md) | Extra options that allow for the customization of the download behavior | + +#### Returns + +`Promise`\<[`DownloadArtifactResponse`](DownloadArtifactResponse.md)\> + +single DownloadArtifactResponse object + +#### Defined in + +[src/internal/client.ts:84](https://github.com/actions/toolkit/blob/e3764a5/packages/artifact/src/internal/client.ts#L84) + +___ + +### getArtifact + +▸ **getArtifact**(`artifactName`, `options?`): `Promise`\<[`GetArtifactResponse`](GetArtifactResponse.md)\> + +Finds an artifact by name. +If there are multiple artifacts with the same name in the same workflow run, this will return the latest. +If the artifact is not found, it will throw. + +If `options.findBy` is specified, this will use the public List Artifacts API with a name filter which can get artifacts from other runs. +https://docs.github.com/en/rest/actions/artifacts?apiVersion=2022-11-28#list-workflow-run-artifacts +`@actions/artifact` v2+ does not allow for creating multiple artifacts with the same name in the same workflow run. +It is possible to have multiple artifacts with the same name in the same workflow run by using old versions of upload-artifact (v1,v2 and v3), @actions/artifact < v2 or it is a rerun. +If there are multiple artifacts with the same name in the same workflow run this function will return the first artifact that matches the name. + +#### Parameters + +| Name | Type | Description | +| :------ | :------ | :------ | +| `artifactName` | `string` | The name of the artifact to find | +| `options?` | [`FindOptions`](FindOptions.md) | Extra options that allow for the customization of the get behavior | + +#### Returns + +`Promise`\<[`GetArtifactResponse`](GetArtifactResponse.md)\> + +#### Defined in + +[src/internal/client.ts:70](https://github.com/actions/toolkit/blob/e3764a5/packages/artifact/src/internal/client.ts#L70) + +___ + +### listArtifacts + +▸ **listArtifacts**(`options?`): `Promise`\<[`ListArtifactsResponse`](ListArtifactsResponse.md)\> + +Lists all artifacts that are part of the current workflow run. +This function will return at most 1000 artifacts per workflow run. + +If `options.findBy` is specified, this will call the public List-Artifacts API which can list from other runs. +https://docs.github.com/en/rest/actions/artifacts?apiVersion=2022-11-28#list-workflow-run-artifacts + +#### Parameters + +| Name | Type | Description | +| :------ | :------ | :------ | +| `options?` | [`ListArtifactsOptions`](ListArtifactsOptions.md) & [`FindOptions`](FindOptions.md) | Extra options that allow for the customization of the list behavior | + +#### Returns + +`Promise`\<[`ListArtifactsResponse`](ListArtifactsResponse.md)\> + +ListArtifactResponse object + +#### Defined in + +[src/internal/client.ts:52](https://github.com/actions/toolkit/blob/e3764a5/packages/artifact/src/internal/client.ts#L52) + +___ + +### uploadArtifact + +▸ **uploadArtifact**(`name`, `files`, `rootDirectory`, `options?`): `Promise`\<[`UploadArtifactResponse`](UploadArtifactResponse.md)\> + +Uploads an artifact. + +#### Parameters + +| Name | Type | Description | +| :------ | :------ | :------ | +| `name` | `string` | The name of the artifact, required | +| `files` | `string`[] | A list of absolute or relative paths that denote what files should be uploaded | +| `rootDirectory` | `string` | An absolute or relative file path that denotes the root parent directory of the files being uploaded | +| `options?` | [`UploadArtifactOptions`](UploadArtifactOptions.md) | Extra options for customizing the upload behavior | + +#### Returns + +`Promise`\<[`UploadArtifactResponse`](UploadArtifactResponse.md)\> + +single UploadArtifactResponse object + +#### Defined in + +[src/internal/client.ts:35](https://github.com/actions/toolkit/blob/e3764a5/packages/artifact/src/internal/client.ts#L35) diff --git a/packages/artifact/docs/generated/interfaces/DownloadArtifactOptions.md b/packages/artifact/docs/generated/interfaces/DownloadArtifactOptions.md new file mode 100644 index 00000000..8eff4d8f --- /dev/null +++ b/packages/artifact/docs/generated/interfaces/DownloadArtifactOptions.md @@ -0,0 +1,23 @@ +[@actions/artifact](../README.md) / DownloadArtifactOptions + +# Interface: DownloadArtifactOptions + +Options for downloading an artifact + +## Table of contents + +### Properties + +- [path](DownloadArtifactOptions.md#path) + +## Properties + +### path + +• `Optional` **path**: `string` + +Denotes where the artifact will be downloaded to. If not specified then the artifact is download to GITHUB_WORKSPACE + +#### Defined in + +[src/internal/shared/interfaces.ts:98](https://github.com/actions/toolkit/blob/e3764a5/packages/artifact/src/internal/shared/interfaces.ts#L98) diff --git a/packages/artifact/docs/generated/interfaces/DownloadArtifactResponse.md b/packages/artifact/docs/generated/interfaces/DownloadArtifactResponse.md new file mode 100644 index 00000000..b2220364 --- /dev/null +++ b/packages/artifact/docs/generated/interfaces/DownloadArtifactResponse.md @@ -0,0 +1,23 @@ +[@actions/artifact](../README.md) / DownloadArtifactResponse + +# Interface: DownloadArtifactResponse + +Response from the server when downloading an artifact + +## Table of contents + +### Properties + +- [downloadPath](DownloadArtifactResponse.md#downloadpath) + +## Properties + +### downloadPath + +• `Optional` **downloadPath**: `string` + +The path where the artifact was downloaded to + +#### Defined in + +[src/internal/shared/interfaces.ts:88](https://github.com/actions/toolkit/blob/e3764a5/packages/artifact/src/internal/shared/interfaces.ts#L88) diff --git a/packages/artifact/docs/generated/interfaces/FindOptions.md b/packages/artifact/docs/generated/interfaces/FindOptions.md new file mode 100644 index 00000000..68f56706 --- /dev/null +++ b/packages/artifact/docs/generated/interfaces/FindOptions.md @@ -0,0 +1,30 @@ +[@actions/artifact](../README.md) / FindOptions + +# Interface: FindOptions + +## Table of contents + +### Properties + +- [findBy](FindOptions.md#findby) + +## Properties + +### findBy + +• `Optional` **findBy**: `Object` + +The criteria for finding Artifact(s) out of the scope of the current run. + +#### Type declaration + +| Name | Type | Description | +| :------ | :------ | :------ | +| `repositoryName` | `string` | Repository owner (eg. 'toolkit') | +| `repositoryOwner` | `string` | Repository owner (eg. 'actions') | +| `token` | `string` | Token with actions:read permissions | +| `workflowRunId` | `number` | WorkflowRun of the artifact(s) to lookup | + +#### Defined in + +[src/internal/shared/interfaces.ts:131](https://github.com/actions/toolkit/blob/e3764a5/packages/artifact/src/internal/shared/interfaces.ts#L131) diff --git a/packages/artifact/docs/generated/interfaces/GetArtifactResponse.md b/packages/artifact/docs/generated/interfaces/GetArtifactResponse.md new file mode 100644 index 00000000..f4d56509 --- /dev/null +++ b/packages/artifact/docs/generated/interfaces/GetArtifactResponse.md @@ -0,0 +1,23 @@ +[@actions/artifact](../README.md) / GetArtifactResponse + +# Interface: GetArtifactResponse + +Response from the server when getting an artifact + +## Table of contents + +### Properties + +- [artifact](GetArtifactResponse.md#artifact) + +## Properties + +### artifact + +• **artifact**: [`Artifact`](Artifact.md) + +Metadata about the artifact that was found + +#### Defined in + +[src/internal/shared/interfaces.ts:57](https://github.com/actions/toolkit/blob/e3764a5/packages/artifact/src/internal/shared/interfaces.ts#L57) diff --git a/packages/artifact/docs/generated/interfaces/ListArtifactsOptions.md b/packages/artifact/docs/generated/interfaces/ListArtifactsOptions.md new file mode 100644 index 00000000..27e3d5f7 --- /dev/null +++ b/packages/artifact/docs/generated/interfaces/ListArtifactsOptions.md @@ -0,0 +1,24 @@ +[@actions/artifact](../README.md) / ListArtifactsOptions + +# Interface: ListArtifactsOptions + +Options for listing artifacts + +## Table of contents + +### Properties + +- [latest](ListArtifactsOptions.md#latest) + +## Properties + +### latest + +• `Optional` **latest**: `boolean` + +Filter the workflow run's artifacts to the latest by name +In the case of reruns, this can be useful to avoid duplicates + +#### Defined in + +[src/internal/shared/interfaces.ts:68](https://github.com/actions/toolkit/blob/e3764a5/packages/artifact/src/internal/shared/interfaces.ts#L68) diff --git a/packages/artifact/docs/generated/interfaces/ListArtifactsResponse.md b/packages/artifact/docs/generated/interfaces/ListArtifactsResponse.md new file mode 100644 index 00000000..836cbbd7 --- /dev/null +++ b/packages/artifact/docs/generated/interfaces/ListArtifactsResponse.md @@ -0,0 +1,23 @@ +[@actions/artifact](../README.md) / ListArtifactsResponse + +# Interface: ListArtifactsResponse + +Response from the server when listing artifacts + +## Table of contents + +### Properties + +- [artifacts](ListArtifactsResponse.md#artifacts) + +## Properties + +### artifacts + +• **artifacts**: [`Artifact`](Artifact.md)[] + +A list of artifacts that were found + +#### Defined in + +[src/internal/shared/interfaces.ts:78](https://github.com/actions/toolkit/blob/e3764a5/packages/artifact/src/internal/shared/interfaces.ts#L78) diff --git a/packages/artifact/docs/generated/interfaces/UploadArtifactOptions.md b/packages/artifact/docs/generated/interfaces/UploadArtifactOptions.md new file mode 100644 index 00000000..acff13df --- /dev/null +++ b/packages/artifact/docs/generated/interfaces/UploadArtifactOptions.md @@ -0,0 +1,55 @@ +[@actions/artifact](../README.md) / UploadArtifactOptions + +# Interface: UploadArtifactOptions + +Options for uploading an artifact + +## Table of contents + +### Properties + +- [compressionLevel](UploadArtifactOptions.md#compressionlevel) +- [retentionDays](UploadArtifactOptions.md#retentiondays) + +## Properties + +### compressionLevel + +• `Optional` **compressionLevel**: `number` + +The level of compression for Zlib to be applied to the artifact archive. +The value can range from 0 to 9: +- 0: No compression +- 1: Best speed +- 6: Default compression (same as GNU Gzip) +- 9: Best compression +Higher levels will result in better compression, but will take longer to complete. +For large files that are not easily compressed, a value of 0 is recommended for significantly faster uploads. + +#### Defined in + +[src/internal/shared/interfaces.ts:47](https://github.com/actions/toolkit/blob/e3764a5/packages/artifact/src/internal/shared/interfaces.ts#L47) + +___ + +### retentionDays + +• `Optional` **retentionDays**: `number` + +Duration after which artifact will expire in days. + +By default artifact expires after 90 days: +https://docs.github.com/en/actions/configuring-and-managing-workflows/persisting-workflow-data-using-artifacts#downloading-and-deleting-artifacts-after-a-workflow-run-is-complete + +Use this option to override the default expiry. + +Min value: 1 +Max value: 90 unless changed by repository setting + +If this is set to a greater value than the retention settings allowed, the retention on artifacts +will be reduced to match the max value allowed on server, and the upload process will continue. An +input of 0 assumes default retention setting. + +#### Defined in + +[src/internal/shared/interfaces.ts:36](https://github.com/actions/toolkit/blob/e3764a5/packages/artifact/src/internal/shared/interfaces.ts#L36) diff --git a/packages/artifact/docs/generated/interfaces/UploadArtifactResponse.md b/packages/artifact/docs/generated/interfaces/UploadArtifactResponse.md new file mode 100644 index 00000000..574366fc --- /dev/null +++ b/packages/artifact/docs/generated/interfaces/UploadArtifactResponse.md @@ -0,0 +1,37 @@ +[@actions/artifact](../README.md) / UploadArtifactResponse + +# Interface: UploadArtifactResponse + +Response from the server when an artifact is uploaded + +## Table of contents + +### Properties + +- [id](UploadArtifactResponse.md#id) +- [size](UploadArtifactResponse.md#size) + +## Properties + +### id + +• `Optional` **id**: `number` + +The id of the artifact that was created. Not provided if no artifact was uploaded +This ID can be used as input to other APIs to download, delete or get more information about an artifact: https://docs.github.com/en/rest/actions/artifacts + +#### Defined in + +[src/internal/shared/interfaces.ts:14](https://github.com/actions/toolkit/blob/e3764a5/packages/artifact/src/internal/shared/interfaces.ts#L14) + +___ + +### size + +• `Optional` **size**: `number` + +Total size of the artifact in bytes. Not provided if no artifact was uploaded + +#### Defined in + +[src/internal/shared/interfaces.ts:8](https://github.com/actions/toolkit/blob/e3764a5/packages/artifact/src/internal/shared/interfaces.ts#L8) diff --git a/packages/artifact/package-lock.json b/packages/artifact/package-lock.json index 4706d54a..26967402 100644 --- a/packages/artifact/package-lock.json +++ b/packages/artifact/package-lock.json @@ -27,6 +27,8 @@ }, "devDependencies": { "@types/archiver": "^5.3.2", + "typedoc": "^0.25.4", + "typedoc-plugin-markdown": "^3.17.1", "typescript": "^5.2.2" } }, @@ -477,6 +479,12 @@ "@types/node": "*" } }, + "node_modules/ansi-sequence-parser": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/ansi-sequence-parser/-/ansi-sequence-parser-1.1.1.tgz", + "integrity": "sha512-vJXt3yiaUL4UU546s3rPXlsry/RnM730G1+HkpKE012AN0sx1eOrxSu95oKDIonskeLTijMgqWZ3uDEe3NFvyg==", + "dev": true + }, "node_modules/archiver": { "version": "5.3.1", "resolved": "https://registry.npmjs.org/archiver/-/archiver-5.3.1.tgz", @@ -905,6 +913,27 @@ "resolved": "https://registry.npmjs.org/graceful-fs/-/graceful-fs-4.2.11.tgz", "integrity": "sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ==" }, + "node_modules/handlebars": { + "version": "4.7.8", + "resolved": "https://registry.npmjs.org/handlebars/-/handlebars-4.7.8.tgz", + "integrity": "sha512-vafaFqs8MZkRrSX7sFVUdo3ap/eNiLnb4IakshzvP56X5Nr1iGKAIqdX6tMlm6HcNRIkr6AxO5jFEoJzzpT8aQ==", + "dev": true, + "dependencies": { + "minimist": "^1.2.5", + "neo-async": "^2.6.2", + "source-map": "^0.6.1", + "wordwrap": "^1.0.0" + }, + "bin": { + "handlebars": "bin/handlebars" + }, + "engines": { + "node": ">=0.4.7" + }, + "optionalDependencies": { + "uglify-js": "^3.1.4" + } + }, "node_modules/ieee754": { "version": "1.2.1", "resolved": "https://registry.npmjs.org/ieee754/-/ieee754-1.2.1.tgz", @@ -951,6 +980,12 @@ "resolved": "https://registry.npmjs.org/isarray/-/isarray-1.0.0.tgz", "integrity": "sha512-VLghIWNM6ELQzo7zwmcg0NmTVyWKYjvIeM83yjp0wRDTmUnrM678fQbcKBo6n2CJEF0szoG//ytg+TKla89ALQ==" }, + "node_modules/jsonc-parser": { + "version": "3.2.0", + "resolved": "https://registry.npmjs.org/jsonc-parser/-/jsonc-parser-3.2.0.tgz", + "integrity": "sha512-gfFQZrcTc8CnKXp6Y4/CBT3fTc0OVuDofpre4aEeEpSBPV5X5v4+Vmx+8snU7RLPrNHPKSgLxGo9YuQzz20o+w==", + "dev": true + }, "node_modules/jwt-decode": { "version": "3.1.2", "resolved": "https://registry.npmjs.org/jwt-decode/-/jwt-decode-3.1.2.tgz", @@ -1037,6 +1072,24 @@ "tslib": "^2.0.3" } }, + "node_modules/lunr": { + "version": "2.3.9", + "resolved": "https://registry.npmjs.org/lunr/-/lunr-2.3.9.tgz", + "integrity": "sha512-zTU3DaZaF3Rt9rhN3uBMGQD3dD2/vFQqnvZCDv4dl5iOzq2IZQqTxu90r4E5J+nP70J3ilqVCrbho2eWaeW8Ow==", + "dev": true + }, + "node_modules/marked": { + "version": "4.3.0", + "resolved": "https://registry.npmjs.org/marked/-/marked-4.3.0.tgz", + "integrity": "sha512-PRsaiG84bK+AMvxziE/lCFss8juXjNaWzVbN5tXAm4XjeaS9NAHhop+PjQxz2A9h8Q4M/xGmzP8vqNwy6JeK0A==", + "dev": true, + "bin": { + "marked": "bin/marked.js" + }, + "engines": { + "node": ">= 12" + } + }, "node_modules/mime-db": { "version": "1.52.0", "resolved": "https://registry.npmjs.org/mime-db/-/mime-db-1.52.0.tgz", @@ -1086,6 +1139,12 @@ "mkdirp": "bin/cmd.js" } }, + "node_modules/neo-async": { + "version": "2.6.2", + "resolved": "https://registry.npmjs.org/neo-async/-/neo-async-2.6.2.tgz", + "integrity": "sha512-Yd3UES5mWCSqR+qNT93S3UoYUkqAZ9lLg8a7g9rimsWmYGK8cVToA4/sF3RrshdyV3sAGMXVUmpMYOw+dLpOuw==", + "dev": true + }, "node_modules/no-case": { "version": "3.0.4", "resolved": "https://registry.npmjs.org/no-case/-/no-case-3.0.4.tgz", @@ -1259,6 +1318,27 @@ "resolved": "https://registry.npmjs.org/setimmediate/-/setimmediate-1.0.5.tgz", "integrity": "sha512-MATJdZp8sLqDl/68LfQmbP8zKPLQNV6BIZoIgrscFDQ+RsvK/BxeDQOgyxKKoh0y/8h3BqVFnCqQ/gd+reiIXA==" }, + "node_modules/shiki": { + "version": "0.14.5", + "resolved": "https://registry.npmjs.org/shiki/-/shiki-0.14.5.tgz", + "integrity": "sha512-1gCAYOcmCFONmErGTrS1fjzJLA7MGZmKzrBNX7apqSwhyITJg2O102uFzXUeBxNnEkDA9vHIKLyeKq0V083vIw==", + "dev": true, + "dependencies": { + "ansi-sequence-parser": "^1.1.0", + "jsonc-parser": "^3.2.0", + "vscode-oniguruma": "^1.7.0", + "vscode-textmate": "^8.0.0" + } + }, + "node_modules/source-map": { + "version": "0.6.1", + "resolved": "https://registry.npmjs.org/source-map/-/source-map-0.6.1.tgz", + "integrity": "sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g==", + "dev": true, + "engines": { + "node": ">=0.10.0" + } + }, "node_modules/string_decoder": { "version": "1.3.0", "resolved": "https://registry.npmjs.org/string_decoder/-/string_decoder-1.3.0.tgz", @@ -1345,6 +1425,63 @@ } } }, + "node_modules/typedoc": { + "version": "0.25.4", + "resolved": "https://registry.npmjs.org/typedoc/-/typedoc-0.25.4.tgz", + "integrity": "sha512-Du9ImmpBCw54bX275yJrxPVnjdIyJO/84co0/L9mwe0R3G4FSR6rQ09AlXVRvZEGMUg09+z/usc8mgygQ1aidA==", + "dev": true, + "dependencies": { + "lunr": "^2.3.9", + "marked": "^4.3.0", + "minimatch": "^9.0.3", + "shiki": "^0.14.1" + }, + "bin": { + "typedoc": "bin/typedoc" + }, + "engines": { + "node": ">= 16" + }, + "peerDependencies": { + "typescript": "4.6.x || 4.7.x || 4.8.x || 4.9.x || 5.0.x || 5.1.x || 5.2.x || 5.3.x" + } + }, + "node_modules/typedoc-plugin-markdown": { + "version": "3.17.1", + "resolved": "https://registry.npmjs.org/typedoc-plugin-markdown/-/typedoc-plugin-markdown-3.17.1.tgz", + "integrity": "sha512-QzdU3fj0Kzw2XSdoL15ExLASt2WPqD7FbLeaqwT70+XjKyTshBnUlQA5nNREO1C2P8Uen0CDjsBLMsCQ+zd0lw==", + "dev": true, + "dependencies": { + "handlebars": "^4.7.7" + }, + "peerDependencies": { + "typedoc": ">=0.24.0" + } + }, + "node_modules/typedoc/node_modules/brace-expansion": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.0.1.tgz", + "integrity": "sha512-XnAIvQ8eM+kC6aULx6wuQiwVsnzsi9d3WxzV3FpWTGA19F621kwdbsAcFKXgKUHZWsy+mY6iL1sHTxWEFCytDA==", + "dev": true, + "dependencies": { + "balanced-match": "^1.0.0" + } + }, + "node_modules/typedoc/node_modules/minimatch": { + "version": "9.0.3", + "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-9.0.3.tgz", + "integrity": "sha512-RHiac9mvaRw0x3AYRgDC1CxAP7HTcNrrECeA8YYJeWnpo+2Q5CegtZjaotWTWxDG3UeGA1coE05iH1mPjT/2mg==", + "dev": true, + "dependencies": { + "brace-expansion": "^2.0.1" + }, + "engines": { + "node": ">=16 || 14 >=14.17" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, "node_modules/typescript": { "version": "5.2.2", "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.2.2.tgz", @@ -1358,6 +1495,19 @@ "node": ">=14.17" } }, + "node_modules/uglify-js": { + "version": "3.17.4", + "resolved": "https://registry.npmjs.org/uglify-js/-/uglify-js-3.17.4.tgz", + "integrity": "sha512-T9q82TJI9e/C1TAxYvfb16xO120tMVFZrGA3f9/P4424DNu6ypK103y0GPFVa17yotwSyZW5iYXgjYHkGrJW/g==", + "dev": true, + "optional": true, + "bin": { + "uglifyjs": "bin/uglifyjs" + }, + "engines": { + "node": ">=0.8.0" + } + }, "node_modules/universal-user-agent": { "version": "6.0.0", "resolved": "https://registry.npmjs.org/universal-user-agent/-/universal-user-agent-6.0.0.tgz", @@ -1420,6 +1570,18 @@ "uuid": "dist/bin/uuid" } }, + "node_modules/vscode-oniguruma": { + "version": "1.7.0", + "resolved": "https://registry.npmjs.org/vscode-oniguruma/-/vscode-oniguruma-1.7.0.tgz", + "integrity": "sha512-L9WMGRfrjOhgHSdOYgCt/yRMsXzLDJSL7BPrOZt73gU0iWO4mpqzqQzOz5srxqTvMBaR0XZTSrVWo4j55Rc6cA==", + "dev": true + }, + "node_modules/vscode-textmate": { + "version": "8.0.0", + "resolved": "https://registry.npmjs.org/vscode-textmate/-/vscode-textmate-8.0.0.tgz", + "integrity": "sha512-AFbieoL7a5LMqcnOF04ji+rpXadgOXnZsxQr//r83kLPr7biP7am3g9zbaZIaBGwBRWeSvoMD4mgPdX3e4NWBg==", + "dev": true + }, "node_modules/webidl-conversions": { "version": "3.0.1", "resolved": "https://registry.npmjs.org/webidl-conversions/-/webidl-conversions-3.0.1.tgz", @@ -1434,6 +1596,12 @@ "webidl-conversions": "^3.0.0" } }, + "node_modules/wordwrap": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/wordwrap/-/wordwrap-1.0.0.tgz", + "integrity": "sha512-gvVzJFlPycKc5dZN4yPkP8w7Dc37BtP1yczEneOb4uq34pXZcvrtRTmWV8W+Ume+XCxKgbjM+nevkyFPMybd4Q==", + "dev": true + }, "node_modules/wrappy": { "version": "1.0.2", "resolved": "https://registry.npmjs.org/wrappy/-/wrappy-1.0.2.tgz", diff --git a/packages/artifact/package.json b/packages/artifact/package.json index 7dc7eafc..894e1607 100644 --- a/packages/artifact/package.json +++ b/packages/artifact/package.json @@ -33,7 +33,8 @@ "test": "cd ../../ && npm run test ./packages/artifact", "bootstrap": "cd ../../ && npm run bootstrap", "tsc-run": "tsc", - "tsc": "npm run bootstrap && npm run tsc-run" + "tsc": "npm run bootstrap && npm run tsc-run", + "gen:docs": "typedoc --plugin typedoc-plugin-markdown --out docs/generated src/artifact.ts --githubPages false --readme none" }, "bugs": { "url": "https://github.com/actions/toolkit/issues" @@ -57,6 +58,8 @@ }, "devDependencies": { "@types/archiver": "^5.3.2", + "typedoc": "^0.25.4", + "typedoc-plugin-markdown": "^3.17.1", "typescript": "^5.2.2" } } diff --git a/packages/artifact/src/internal/shared/interfaces.ts b/packages/artifact/src/internal/shared/interfaces.ts index e40fb661..c661721e 100644 --- a/packages/artifact/src/internal/shared/interfaces.ts +++ b/packages/artifact/src/internal/shared/interfaces.ts @@ -1,8 +1,6 @@ -/***************************************************************************** - * * - * UploadArtifact * - * * - *****************************************************************************/ +/** + * Response from the server when an artifact is uploaded + */ export interface UploadArtifactResponse { /** * Total size of the artifact in bytes. Not provided if no artifact was uploaded @@ -16,6 +14,9 @@ export interface UploadArtifactResponse { id?: number } +/** + * Options for uploading an artifact + */ export interface UploadArtifactOptions { /** * Duration after which artifact will expire in days. @@ -46,12 +47,9 @@ export interface UploadArtifactOptions { compressionLevel?: number } -/***************************************************************************** - * * - * GetArtifact * - * * - *****************************************************************************/ - +/** + * Response from the server when getting an artifact + */ export interface GetArtifactResponse { /** * Metadata about the artifact that was found @@ -59,12 +57,9 @@ export interface GetArtifactResponse { artifact: Artifact } -/***************************************************************************** - * * - * ListArtifact * - * * - *****************************************************************************/ - +/** + * Options for listing artifacts + */ export interface ListArtifactsOptions { /** * Filter the workflow run's artifacts to the latest by name @@ -73,6 +68,9 @@ export interface ListArtifactsOptions { latest?: boolean } +/** + * Response from the server when listing artifacts + */ export interface ListArtifactsResponse { /** * A list of artifacts that were found @@ -80,11 +78,9 @@ export interface ListArtifactsResponse { artifacts: Artifact[] } -/***************************************************************************** - * * - * DownloadArtifact * - * * - *****************************************************************************/ +/** + * Response from the server when downloading an artifact + */ export interface DownloadArtifactResponse { /** * The path where the artifact was downloaded to @@ -92,6 +88,9 @@ export interface DownloadArtifactResponse { downloadPath?: string } +/** + * Options for downloading an artifact + */ export interface DownloadArtifactOptions { /** * Denotes where the artifact will be downloaded to. If not specified then the artifact is download to GITHUB_WORKSPACE @@ -99,11 +98,9 @@ export interface DownloadArtifactOptions { path?: string } -/***************************************************************************** - * * - * Shared * - * * - *****************************************************************************/ +/** + * An Actions Artifact + */ export interface Artifact { /** * The name of the artifact @@ -127,16 +124,26 @@ export interface Artifact { } // FindOptions are for fetching Artifact(s) out of the scope of the current run. -// Must specify a token with actions:read scope for cross run/repo lookup otherwise these will be ignored. export interface FindOptions { + /** + * The criteria for finding Artifact(s) out of the scope of the current run. + */ findBy?: { - // Token with actions:read permissions + /** + * Token with actions:read permissions + */ token: string - // WorkflowRun of the artifact(s) to lookup + /** + * WorkflowRun of the artifact(s) to lookup + */ workflowRunId: number - // Repository owner + /** + * Repository owner (eg. 'actions') + */ repositoryOwner: string - // Repository name + /** + * Repository owner (eg. 'toolkit') + */ repositoryName: string } }