Add specific messages for network-specific node error codes

[artifact] replace unzipper with unzip-stream

.github/workflows/artifact-tests.yml

@@ -24,10 +24,10 @@ jobs:
 
     steps:
     - name: Checkout
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
 
     - name: Set Node.js 20.x
-      uses: actions/setup-node@v3
+      uses: actions/setup-node@v4
       with:
         node-version: 20.x
 
@@ -54,39 +54,34 @@ jobs:
         echo '${{ env.file1 }}' > artifact-path/first.txt
         echo '${{ env.file2 }}' > artifact-path/second.txt
 
-    - name: Upload Artifacts using actions/github-script@v6
-      uses: actions/github-script@v6
+    - name: Upload Artifacts using actions/github-script@v7
+      uses: actions/github-script@v7
       with:
         script: |
-          const artifact = require('./packages/artifact/lib/artifact')
+          const {default: artifact} = require('./packages/artifact/lib/artifact')
 
           const artifactName = 'my-artifact-${{ matrix.runs-on }}'
           console.log('artifactName: ' + artifactName)
 
           const fileContents = ['artifact-path/first.txt','artifact-path/second.txt']
 
-          const uploadResult = await artifact.create().uploadArtifact(artifactName, fileContents, './')
+          const uploadResult = await artifact.uploadArtifact(artifactName, fileContents, './')
           console.log(uploadResult)
 
-          const success = uploadResult.success
           const size = uploadResult.size
           const id = uploadResult.id
 
-          if (!success) {
-            throw new Error('Failed to upload artifact')
-          } else {
-            console.log(`Successfully uploaded artifact ${id}`)
-          }
-           
+          console.log(`Successfully uploaded artifact ${id}`)
+
   verify:
     runs-on: ubuntu-latest
     needs: [build]
     steps:
     - name: Checkout
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
 
     - name: Set Node.js 20.x
-      uses: actions/setup-node@v3
+      uses: actions/setup-node@v4
       with:
         node-version: 20.x
 
@@ -101,18 +96,18 @@ jobs:
         npm run tsc
       working-directory: packages/artifact
 
-    - name: List artifacts using actions/github-script@v6
-      uses: actions/github-script@v6
+    - name: List artifacts using actions/github-script@v7
+      uses: actions/github-script@v7
       with:
         script: |
-          const artifact = require('./packages/artifact/lib/artifact')
+          const {default: artifact} = require('./packages/artifact/lib/artifact')
 
           const workflowRunId = process.env.GITHUB_RUN_ID
           const repository = process.env.GITHUB_REPOSITORY
           const repositoryOwner = repository.split('/')[0]
           const repositoryName = repository.split('/')[1]
 
-          const listResult = await artifact.create().listArtifacts(workflowRunId, repositoryOwner, repositoryName, '${{ secrets.GITHUB_TOKEN }}')
+          const listResult = await artifact.listArtifacts(workflowRunId, repositoryOwner, repositoryName, '${{ secrets.GITHUB_TOKEN }}')
           console.log(listResult)
 
           const artifacts = listResult.artifacts

packages/artifact/CONTRIBUTIONS.md

@@ -1,30 +1,43 @@
 # Contributions
 
-This package is used internally by the v2+ versions of [upload-artifact](https://github.com/actions/upload-artifact) and [download-artifact](https://github.com/actions/download-artifact). This package can also be used by other actions to interact with artifacts. Any changes or updates to this package will propagate updates to these actions so it is important that major changes or updates get properly tested. 
+This package is used internally by the v4 versions of [upload-artifact](https://github.com/actions/upload-artifact) and [download-artifact](https://github.com/actions/download-artifact). This package can also be used by other actions to interact with artifacts. Any changes or updates to this package will propagate updates to these actions so it is important that major changes or updates get properly tested.
 
 Any issues or feature requests that are related to the artifact actions should be filled in the appropriate repo.
 
 A limited range of unit tests run as part of each PR when making changes to the artifact packages. For small contributions and fixes, they should be sufficient.
 
-If making large changes, there are a few scenarios that should be tested.
+If making large changes, there are a few scenarios that should be tested:
 
-- Uploading very large artifacts (large artifacts get compressed using gzip so compression/decompression must be tested)
-- Uploading artifacts with lots of small files (each file is uploaded with its own HTTP call, timeouts and non-success HTTP responses can be expected so they must be properly handled)
+- Uploading very large artifacts
+- Uploading artifacts with lots of small files
 - Uploading artifacts using a self-hosted runner (uploads and downloads behave differently due to extra latency)
 - Downloading a single artifact (large and small, if lots of small files are part of an artifact, timeouts and non-success HTTP responses can be expected)
 - Downloading all artifacts at once
 
 Large architectural changes can impact upload/download performance so it is important to separately run extra tests. We request that any large contributions/changes have extra detailed testing so we can verify performance and possible regressions.
 
-It is not possible to run end-to-end tests for artifacts as part of a PR in this repo because certain env variables such as `ACTIONS_RUNTIME_URL` are only available from the context of an action as opposed to a shell script. These env variables are needed in order to make the necessary API calls.
+Tests will run for every push/pull_request [via Actions](https://github.com/actions/toolkit/blob/main/.github/workflows/artifact-tests.yml).
 
 # Testing
 
-Any easy way to test changes is to fork the artifact actions and to use `npm link` to test your changes.
+## Package tests
 
-1. Fork the [upload-artifact](https://github.com/actions/upload-artifact) and [download-artifact](https://github.com/actions/download-artifact) repos
-2. Clone the forks locally
-3. With your local changes to the toolkit repo, type `npm link` after ensuring there are no errors when running `tsc`
-4. In the locally cloned fork, type `npm link @actions/artifact`
-4. Create a new release for your local fork using `tsc` and `npm run release` (this will create a new `dist/index.js` file using `@vercel/ncc`)
-5. Commit and push your local changes, you will then be able to test your changes with your forked action
+To run unit tests for the `@actions/artifact` package:
+
+1. Clone `actions/toolkit` locally
+2. Install dependencies: `npm bootstrap`
+3. Change working directory to `packages/artifact`
+4. Run jest tests: `npm run test`
+
+## Within upload-artifact or download-artifact actions
+
+Any easy way to test changes for the official upload/download actions is to fork them, compile changes and run them.
+
+1. For your local `actions/toolkit` changes:
+   1. Change directory to `packages/artifact`
+   2. Compile the changes: `npm run tsc`
+   3. Symlink your package change: `npm link`
+2. Fork and clone either [upload-artifact](https://github.com/actions/upload-artifact) and [download-artifact](https://github.com/actions/download-artifact)
+   1. In the locally cloned fork, link to your local toolkit changes: `npm link @actions/artifact`
+   2. Then, compile your changes with: `npm run release`. The local `dist/index.js` should be updated with your changes.
+   3. Commit and push to your fork, you can then test with a `uses:` in your workflow pointed at your fork.

packages/artifact/README.md

@@ -1,13 +1,150 @@
 # `@actions/artifact`
 
-## Usage
+Interact programmatically with [Actions Artifacts](https://docs.github.com/en/actions/using-workflows/storing-workflow-data-as-artifacts).
 
-You can use this package to interact with the Actions artifacts.
+This is the core library that powers the [`@actions/upload-artifact`](https://github.com/actions/upload-artifact) and [`@actions/download-artifact`](https://github.com/actions/download-artifact) actions.
 
-This most recently published version of this package (`1.1.1`) can be found [here](https://github.com/actions/toolkit/tree/@actions/artifact@1.1.1/packages/artifact)
 
-## 🚧 Under construction 🚧
+- [`@actions/artifact`](#actionsartifact)
+  - [v2 - What's New](#v2---whats-new)
+    - [Improvements](#improvements)
+    - [Breaking changes](#breaking-changes)
+  - [Quick Start](#quick-start)
+  - [Examples](#examples)
+    - [Upload and Download](#upload-and-download)
+    - [Downloading from other workflow runs or repos](#downloading-from-other-workflow-runs-or-repos)
+    - [Speeding up large uploads](#speeding-up-large-uploads)
+  - [Additional Resources](#additional-resources)
 
-This package is currently undergoing a major overhaul in preparation for `v4` versions of `upload-artifact` and `download-artifact` (these Actions will use a new `2.0.0` version of `@actions/artifact` that will soon be released). The upcoming version of `@actions/artifact` will take advantage of a major re-architecture with entirely new APIs.
+## v2 - What's New
 
-The upcoming `2.0.0` package and `v4` artifact Actions aim to solve some of the major pain-points that have made artifact usage difficult up until now.
+> [!IMPORTANT]
+> @actions/artifact v2+, upload-artifact@v4+ download-artifact@v4+ are not currently supported on GHES yet. The previous version of this package can be found at [this tag](https://github.com/actions/toolkit/tree/@actions/artifact@1.1.2/packages/artifact) and [on npm](https://www.npmjs.com/package/@actions/artifact/v/1.1.2).
+
+The release of `@actions/artifact@v2` (including `upload-artifact@v4` and `download-artifact@v4`) are major changes to the backend architecture of Artifacts. They have numerous performance and behavioral improvements.
+
+### Improvements
+
+1. All upload and download operations are much quicker, up to 80% faster download times and 96% faster upload times in worst case scenarios.
+2. Once uploaded, an Artifact ID is returned and Artifacts are immediately available in the UI and [REST API](https://docs.github.com/en/rest/actions/artifacts). Previously, you would have to wait for the run to be completed before an ID was available or any APIs could be utilized.
+3. Artifacts can now be downloaded and deleted from the UI _before_ the entire workflow run finishes.
+4. The contents of an Artifact are uploaded together into an _immutable_ archive. They cannot be altered by subsequent jobs. Both of these factors help reduce the possibility of accidentally corrupting Artifact files. (Digest/integrity hash coming soon in the API!)
+5. This library (and `actions/download-artifact`) now support downloading Artifacts from _other_ repositories and runs if a `GITHUB_TOKEN` with sufficient `actions:read` permissions are provided.
+
+### Breaking changes
+
+1. Firewall rules required for self-hosted runners.
+
+    If you are using self-hosted runners behind a firewall, you must have flows open to [Actions endpoints](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners#communication-between-self-hosted-runners-and-github). If you cannot use wildcard rules for your firewall, see the GitHub [meta endpoint](https://api.github.com/meta) for specific endpoints.
+
+    e.g.
+
+    ```bash
+    curl https://api.github.com/meta | jq .domains.actions
+    ```
+
+2. Uploading to the same named Artifact multiple times.
+
+    Due to how Artifacts are created in this new version, it is no longer possible to upload to the same named Artifact multiple times. You must either split the uploads into multiple Artifacts with different names, or only upload once.
+
+3. Limit of Artifacts for an individual job.
+
+    Each job in a workflow run now has a limit of 10 artifacts.
+
+## Quick Start
+
+Install the package:
+
+```bash
+npm i @actions/artifact
+```
+
+Import the module:
+
+```js
+// ES6 module
+import artifact from '@actions/artifact'
+
+// CommonJS
+const {default: artifact} = require('@actions/artifact')
+```
+
+ℹ️ For a comprehensive list of classes, interfaces, functions and more, see the [generated documentation](./docs/generated/README.md).
+
+## Examples
+
+### Upload and Download
+
+The most basic scenario is uploading one or more files to an Artifact, then downloading that Artifact. Downloads are based on the Artifact ID, which can be obtained in the response of `uploadArtifact`, `getArtifact`, `listArtifacts` or via the [REST API](https://docs.github.com/en/rest/actions/artifacts).
+
+```js
+const {id, size} = await artifact.uploadArtifact(
+  // name of the artifact
+  'my-artifact',
+  // files to include (supports absolute and relative paths)
+  ['/absolute/path/file1.txt', './relative/file2.txt'],
+  {
+    // optional: how long to retain the artifact
+    // if unspecified, defaults to repository/org retention settings (the limit of this value)
+    retentionDays: 10
+  }
+)
+
+console.log(`Created artifact with id: ${id} (bytes: ${size}`)
+
+const {downloadPath} = await artifact.downloadArtifact(id, {
+  // optional: download destination path. otherwise defaults to $GITHUB_WORKSPACE
+  path: '/tmp/dst/path',
+})
+
+console.log(`Downloaded artifact ${id} to: ${downloadPath}`)
+```
+
+### Downloading from other workflow runs or repos
+
+It may be useful to download Artifacts from other workflow runs, or even other repositories. By default, the permissions are scoped so they can only download Artifacts within the current workflow run. To elevate permissions for this scenario, you must specify `options.findBy` to `downloadArtifact`.
+
+```ts
+const findBy = {
+  // must have actions:read permission on target repository
+  token: process.env['GITHUB_TOKEN'],
+  workflowRunId: 123,
+  repositoryOwner: 'actions',
+  repositoryName: 'toolkit'
+}
+
+await artifact.downloadArtifact(1337, {
+  findBy
+})
+
+// can also be used in other methods
+
+await artifact.getArtifact('my-artifact', {
+  findBy
+})
+
+await artifact.listArtifacts({
+  findBy
+})
+```
+
+### Speeding up large uploads
+
+If you have large files that need to be uploaded (or file types that don't compress well), you may benefit from changing the compression level of the Artifact archive. NOTE: This is a tradeoff between artifact upload time and stored data size.
+
+```ts
+await artifact.uploadArtifact('my-massive-artifact', ['big_file.bin'], {
+  // The level of compression for Zlib to be applied to the artifact archive.
+  // - 0: No compression
+  // - 1: Best speed
+  // - 6: Default compression (same as GNU Gzip)
+  // - 9: Best compression
+  compressionLevel: 0
+})
+```
+
+## Additional Resources
+
+- [Releases](./RELEASES.md)
+- [Contribution Guide](./CONTRIBUTIONS.md)
+- [Frequently Asked Questions](./docs/faq.md)

packages/artifact/RELEASES.md

@@ -94,3 +94,10 @@
 ### 1.1.1
 
 - Fixed a bug in Node16 where if an HTTP download finished too quickly (<1ms, e.g. when it's mocked) we attempt to delete a temp file that has not been created yet [#1278](https://github.com/actions/toolkit/pull/1278/commits/b9de68a590daf37c6747e38d3cb4f1dd2cfb791c)
+
+### 2.0.0
+
+Major release. Supports new Artifact backend for improved speed, reliability and behavior.
+Numerous API changes, [some breaking](./README.md#breaking-changes).
+
+Blog post with more info: TBD

packages/artifact/__tests__/artifact-http-client.test.ts

@@ -7,6 +7,12 @@ import {noopLogs} from './common'
 
 jest.mock('@actions/http-client')
 
+const clientOptions = {
+  maxAttempts: 5,
+  retryIntervalMs: 1,
+  retryMultiplier: 1.5
+}
+
 describe('artifact-http-client', () => {
   beforeAll(() => {
     noopLogs()
@@ -94,11 +100,7 @@ describe('artifact-http-client', () => {
       }
     })
 
-    const client = internalArtifactTwirpClient({
-      maxAttempts: 5,
-      retryIntervalMs: 1,
-      retryMultiplier: 1.5
-    })
+    const client = internalArtifactTwirpClient(clientOptions)
     const artifact = await client.CreateArtifact({
       workflowRunBackendId: '1234',
       workflowJobRunBackendId: '5678',
@@ -133,11 +135,7 @@ describe('artifact-http-client', () => {
         post: mockPost
       }
     })
-    const client = internalArtifactTwirpClient({
-      maxAttempts: 5,
-      retryIntervalMs: 1,
-      retryMultiplier: 1.5
-    })
+    const client = internalArtifactTwirpClient(clientOptions)
     await expect(async () => {
       await client.CreateArtifact({
         workflowRunBackendId: '1234',
@@ -172,11 +170,7 @@ describe('artifact-http-client', () => {
         post: mockPost
       }
     })
-    const client = internalArtifactTwirpClient({
-      maxAttempts: 5,
-      retryIntervalMs: 1,
-      retryMultiplier: 1.5
-    })
+    const client = internalArtifactTwirpClient(clientOptions)
     await expect(async () => {
       await client.CreateArtifact({
         workflowRunBackendId: '1234',
@@ -190,4 +184,83 @@ describe('artifact-http-client', () => {
     expect(mockHttpClient).toHaveBeenCalledTimes(1)
     expect(mockPost).toHaveBeenCalledTimes(1)
   })
+
+  it('should fail with a descriptive error', async () => {
+    // 409 duplicate error
+    const mockPost = jest.fn(() => {
+      const msgFailed = new http.IncomingMessage(new net.Socket())
+      msgFailed.statusCode = 409
+      msgFailed.statusMessage = 'Conflict'
+      return {
+        message: msgFailed,
+        readBody: async () => {
+          return Promise.resolve(
+            `{"msg": "an artifact with this name already exists on the workflow run"}`
+          )
+        }
+      }
+    })
+
+    const mockHttpClient = (
+      HttpClient as unknown as jest.Mock
+    ).mockImplementation(() => {
+      return {
+        post: mockPost
+      }
+    })
+    const client = internalArtifactTwirpClient(clientOptions)
+    await expect(async () => {
+      await client.CreateArtifact({
+        workflowRunBackendId: '1234',
+        workflowJobRunBackendId: '5678',
+        name: 'artifact',
+        version: 4
+      })
+      await client.CreateArtifact({
+        workflowRunBackendId: '1234',
+        workflowJobRunBackendId: '5678',
+        name: 'artifact',
+        version: 4
+      })
+    }).rejects.toThrowError(
+      'Failed to CreateArtifact: Received non-retryable error: Failed request: (409) Conflict: an artifact with this name already exists on the workflow run'
+    )
+    expect(mockHttpClient).toHaveBeenCalledTimes(1)
+    expect(mockPost).toHaveBeenCalledTimes(1)
+  })
+
+  it('should properly describe a network failure', async () => {
+    class FakeNodeError extends Error {
+      code: string
+      constructor(code: string) {
+        super()
+        this.code = code
+      }
+    }
+
+    const mockPost = jest.fn(() => {
+      throw new FakeNodeError('ENOTFOUND')
+    })
+
+    const mockHttpClient = (
+      HttpClient as unknown as jest.Mock
+    ).mockImplementation(() => {
+      return {
+        post: mockPost
+      }
+    })
+    const client = internalArtifactTwirpClient()
+    await expect(async () => {
+      await client.CreateArtifact({
+        workflowRunBackendId: '1234',
+        workflowJobRunBackendId: '5678',
+        name: 'artifact',
+        version: 4
+      })
+    }).rejects.toThrowError(
+      'Failed to CreateArtifact: Unable to make request: ENOTFOUND\nIf you are using self-hosted runners, please make sure your runner has access to all GitHub endpoints: https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners#communication-between-self-hosted-runners-and-github'
+    )
+    expect(mockHttpClient).toHaveBeenCalledTimes(1)
+    expect(mockPost).toHaveBeenCalledTimes(1)
+  })
 })

packages/artifact/__tests__/download-artifact.test.ts

@@ -104,6 +104,7 @@ const mockGetArtifactSuccess = jest.fn(() => {
   const message = new http.IncomingMessage(new net.Socket())
   message.statusCode = 200
   message.push(fs.readFileSync(fixtures.exampleArtifact.path))
+  message.push(null)
   return {
     message
   }
@@ -113,6 +114,7 @@ const mockGetArtifactFailure = jest.fn(() => {
   const message = new http.IncomingMessage(new net.Socket())
   message.statusCode = 500
   message.push('Internal Server Error')
+  message.push(null)
   return {
     message
   }
@@ -164,7 +166,6 @@ describe('download-artifact', () => {
         fixtures.blobStorageUrl
       )
       expectExtractedArchive(fixtures.workspaceDir)
-      expect(response.success).toBe(true)
       expect(response.downloadPath).toBe(fixtures.workspaceDir)
     })
 
@@ -214,7 +215,6 @@ describe('download-artifact', () => {
         fixtures.blobStorageUrl
       )
       expectExtractedArchive(customPath)
-      expect(response.success).toBe(true)
       expect(response.downloadPath).toBe(customPath)
     })
 
@@ -344,7 +344,6 @@ describe('download-artifact', () => {
       const response = await downloadArtifactInternal(fixtures.artifactID)
 
       expectExtractedArchive(fixtures.workspaceDir)
-      expect(response.success).toBe(true)
       expect(response.downloadPath).toBe(fixtures.workspaceDir)
       expect(mockHttpClient).toHaveBeenCalledWith(getUserAgentString())
       expect(mockListArtifacts).toHaveBeenCalledWith({
@@ -396,7 +395,6 @@ describe('download-artifact', () => {
       })
 
       expectExtractedArchive(customPath)
-      expect(response.success).toBe(true)
       expect(response.downloadPath).toBe(customPath)
       expect(mockHttpClient).toHaveBeenCalledWith(getUserAgentString())
       expect(mockListArtifacts).toHaveBeenCalledWith({

packages/artifact/__tests__/get-artifact.test.ts

@@ -0,0 +1,239 @@
+import * as github from '@actions/github'
+import type {RequestInterface} from '@octokit/types'
+import {
+  getArtifactInternal,
+  getArtifactPublic
+} from '../src/internal/find/get-artifact'
+import * as config from '../src/internal/shared/config'
+import {ArtifactServiceClientJSON, Timestamp} from '../src/generated'
+import * as util from '../src/internal/shared/util'
+import {noopLogs} from './common'
+import {
+  ArtifactNotFoundError,
+  InvalidResponseError
+} from '../src/internal/shared/errors'
+
+type MockedRequest = jest.MockedFunction<RequestInterface<object>>
+
+jest.mock('@actions/github', () => ({
+  getOctokit: jest.fn().mockReturnValue({
+    request: jest.fn()
+  })
+}))
+
+const fixtures = {
+  repo: 'toolkit',
+  owner: 'actions',
+  token: 'ghp_1234567890',
+  runId: 123,
+  backendIds: {
+    workflowRunBackendId: 'c4d7c21f-ba3f-4ddc-a8c8-6f2f626f8422',
+    workflowJobRunBackendId: '760803a1-f890-4d25-9a6e-a3fc01a0c7cf'
+  },
+  artifacts: [
+    {
+      id: 1,
+      name: 'my-artifact',
+      size: 456,
+      createdAt: new Date('2023-12-01')
+    },
+    {
+      id: 2,
+      name: 'my-artifact',
+      size: 456,
+      createdAt: new Date('2023-12-02')
+    }
+  ]
+}
+
+describe('get-artifact', () => {
+  beforeAll(() => {
+    noopLogs()
+  })
+
+  describe('public', () => {
+    it('should return the artifact if it is found', async () => {
+      const mockRequest = github.getOctokit(fixtures.token)
+        .request as MockedRequest
+      mockRequest.mockResolvedValueOnce({
+        status: 200,
+        headers: {},
+        url: '',
+        data: {
+          artifacts: [
+            {
+              name: fixtures.artifacts[0].name,
+              id: fixtures.artifacts[0].id,
+              size_in_bytes: fixtures.artifacts[0].size,
+              created_at: fixtures.artifacts[0].createdAt.toISOString()
+            }
+          ]
+        }
+      })
+
+      const response = await getArtifactPublic(
+        fixtures.artifacts[0].name,
+        fixtures.runId,
+        fixtures.owner,
+        fixtures.repo,
+        fixtures.token
+      )
+
+      expect(response).toEqual({
+        artifact: fixtures.artifacts[0]
+      })
+    })
+
+    it('should return the latest artifact if multiple are found', async () => {
+      const mockRequest = github.getOctokit(fixtures.token)
+        .request as MockedRequest
+      mockRequest.mockResolvedValueOnce({
+        status: 200,
+        headers: {},
+        url: '',
+        data: {
+          artifacts: fixtures.artifacts.map(artifact => ({
+            name: artifact.name,
+            id: artifact.id,
+            size_in_bytes: artifact.size,
+            created_at: artifact.createdAt.toISOString()
+          }))
+        }
+      })
+
+      const response = await getArtifactPublic(
+        fixtures.artifacts[0].name,
+        fixtures.runId,
+        fixtures.owner,
+        fixtures.repo,
+        fixtures.token
+      )
+
+      expect(response).toEqual({
+        artifact: fixtures.artifacts[1]
+      })
+    })
+
+    it('should fail if no artifacts are found', async () => {
+      const mockRequest = github.getOctokit(fixtures.token)
+        .request as MockedRequest
+      mockRequest.mockResolvedValueOnce({
+        status: 200,
+        headers: {},
+        url: '',
+        data: {
+          artifacts: []
+        }
+      })
+
+      const response = getArtifactPublic(
+        fixtures.artifacts[0].name,
+        fixtures.runId,
+        fixtures.owner,
+        fixtures.repo,
+        fixtures.token
+      )
+
+      expect(response).rejects.toThrowError(ArtifactNotFoundError)
+    })
+
+    it('should fail if non-200 response', async () => {
+      const mockRequest = github.getOctokit(fixtures.token)
+        .request as MockedRequest
+      mockRequest.mockResolvedValueOnce({
+        status: 404,
+        headers: {},
+        url: '',
+        data: {}
+      })
+
+      const response = getArtifactPublic(
+        fixtures.artifacts[0].name,
+        fixtures.runId,
+        fixtures.owner,
+        fixtures.repo,
+        fixtures.token
+      )
+
+      expect(response).rejects.toThrowError(InvalidResponseError)
+    })
+  })
+
+  describe('internal', () => {
+    beforeEach(() => {
+      jest.spyOn(config, 'getRuntimeToken').mockReturnValue('test-token')
+
+      jest
+        .spyOn(util, 'getBackendIdsFromToken')
+        .mockReturnValue(fixtures.backendIds)
+
+      jest
+        .spyOn(config, 'getResultsServiceUrl')
+        .mockReturnValue('https://results.local')
+    })
+
+    it('should return the artifact if it is found', async () => {
+      jest
+        .spyOn(ArtifactServiceClientJSON.prototype, 'ListArtifacts')
+        .mockResolvedValue({
+          artifacts: [
+            {
+              ...fixtures.backendIds,
+              databaseId: fixtures.artifacts[0].id.toString(),
+              name: fixtures.artifacts[0].name,
+              size: fixtures.artifacts[0].size.toString(),
+              createdAt: Timestamp.fromDate(fixtures.artifacts[0].createdAt)
+            }
+          ]
+        })
+
+      const response = await getArtifactInternal(fixtures.artifacts[0].name)
+
+      expect(response).toEqual({
+        artifact: fixtures.artifacts[0]
+      })
+    })
+
+    it('should return the latest artifact if multiple are found', async () => {
+      jest
+        .spyOn(ArtifactServiceClientJSON.prototype, 'ListArtifacts')
+        .mockResolvedValue({
+          artifacts: fixtures.artifacts.map(artifact => ({
+            ...fixtures.backendIds,
+            databaseId: artifact.id.toString(),
+            name: artifact.name,
+            size: artifact.size.toString(),
+            createdAt: Timestamp.fromDate(artifact.createdAt)
+          }))
+        })
+
+      const response = await getArtifactInternal(fixtures.artifacts[0].name)
+
+      expect(response).toEqual({
+        artifact: fixtures.artifacts[1]
+      })
+    })
+
+    it('should fail if no artifacts are found', async () => {
+      jest
+        .spyOn(ArtifactServiceClientJSON.prototype, 'ListArtifacts')
+        .mockResolvedValue({
+          artifacts: []
+        })
+
+      const response = getArtifactInternal(fixtures.artifacts[0].name)
+
+      expect(response).rejects.toThrowError(ArtifactNotFoundError)
+    })
+
+    it('should fail if non-200 response', async () => {
+      jest
+        .spyOn(ArtifactServiceClientJSON.prototype, 'ListArtifacts')
+        .mockRejectedValue(new Error('boom'))
+
+      const response = getArtifactInternal(fixtures.artifacts[0].name)
+
+      expect(response).rejects.toThrow()
+    })
+  })
+})

packages/artifact/__tests__/list-artifacts.test.ts

@@ -0,0 +1,242 @@
+import * as github from '@actions/github'
+import type {RestEndpointMethods} from '@octokit/plugin-rest-endpoint-methods/dist-types/generated/method-types'
+import type {RestEndpointMethodTypes} from '@octokit/plugin-rest-endpoint-methods/dist-types/generated/parameters-and-response-types'
+import {
+  listArtifactsInternal,
+  listArtifactsPublic
+} from '../src/internal/find/list-artifacts'
+import * as config from '../src/internal/shared/config'
+import {ArtifactServiceClientJSON, Timestamp} from '../src/generated'
+import * as util from '../src/internal/shared/util'
+import {noopLogs} from './common'
+import {Artifact} from '../src/internal/shared/interfaces'
+
+type MockedListWorkflowRunArtifacts = jest.MockedFunction<
+  RestEndpointMethods['actions']['listWorkflowRunArtifacts']
+>
+
+jest.mock('@actions/github', () => ({
+  getOctokit: jest.fn().mockReturnValue({
+    rest: {
+      actions: {
+        listWorkflowRunArtifacts: jest.fn()
+      }
+    }
+  })
+}))
+
+const artifactsToListResponse = (
+  artifacts: Artifact[]
+): RestEndpointMethodTypes['actions']['listWorkflowRunArtifacts']['response']['data'] => {
+  return {
+    total_count: artifacts.length,
+    artifacts: artifacts.map(artifact => ({
+      name: artifact.name,
+      id: artifact.id,
+      size_in_bytes: artifact.size,
+      created_at: artifact.createdAt?.toISOString() || '',
+      run_id: fixtures.runId,
+      // unused fields for tests
+      url: '',
+      archive_download_url: '',
+      expired: false,
+      expires_at: '',
+      node_id: '',
+      run_url: '',
+      type: '',
+      updated_at: ''
+    }))
+  }
+}
+
+const fixtures = {
+  repo: 'toolkit',
+  owner: 'actions',
+  token: 'ghp_1234567890',
+  runId: 123,
+  backendIds: {
+    workflowRunBackendId: 'c4d7c21f-ba3f-4ddc-a8c8-6f2f626f8422',
+    workflowJobRunBackendId: '760803a1-f890-4d25-9a6e-a3fc01a0c7cf'
+  },
+  artifacts: [
+    {
+      id: 1,
+      name: 'my-artifact',
+      size: 456,
+      createdAt: new Date('2023-12-01')
+    },
+    {
+      id: 2,
+      name: 'my-artifact',
+      size: 456,
+      createdAt: new Date('2023-12-02')
+    }
+  ]
+}
+
+describe('list-artifact', () => {
+  beforeAll(() => {
+    noopLogs()
+  })
+
+  describe('public', () => {
+    it('should return a list of artifacts', async () => {
+      const mockListArtifacts = github.getOctokit(fixtures.token).rest.actions
+        .listWorkflowRunArtifacts as MockedListWorkflowRunArtifacts
+
+      mockListArtifacts.mockResolvedValueOnce({
+        status: 200,
+        headers: {},
+        url: '',
+        data: artifactsToListResponse(fixtures.artifacts)
+      })
+
+      const response = await listArtifactsPublic(
+        fixtures.runId,
+        fixtures.owner,
+        fixtures.repo,
+        fixtures.token,
+        false
+      )
+
+      expect(response).toEqual({
+        artifacts: fixtures.artifacts
+      })
+    })
+
+    it('should return the latest artifact when latest is specified', async () => {
+      const mockListArtifacts = github.getOctokit(fixtures.token).rest.actions
+        .listWorkflowRunArtifacts as MockedListWorkflowRunArtifacts
+
+      mockListArtifacts.mockResolvedValueOnce({
+        status: 200,
+        headers: {},
+        url: '',
+        data: artifactsToListResponse(fixtures.artifacts)
+      })
+
+      const response = await listArtifactsPublic(
+        fixtures.runId,
+        fixtures.owner,
+        fixtures.repo,
+        fixtures.token,
+        true
+      )
+
+      expect(response).toEqual({
+        artifacts: [fixtures.artifacts[1]]
+      })
+    })
+
+    it('can return empty artifacts', async () => {
+      const mockListArtifacts = github.getOctokit(fixtures.token).rest.actions
+        .listWorkflowRunArtifacts as MockedListWorkflowRunArtifacts
+
+      mockListArtifacts.mockResolvedValueOnce({
+        status: 200,
+        headers: {},
+        url: '',
+        data: {
+          total_count: 0,
+          artifacts: []
+        }
+      })
+
+      const response = await listArtifactsPublic(
+        fixtures.runId,
+        fixtures.owner,
+        fixtures.repo,
+        fixtures.token,
+        true
+      )
+
+      expect(response).toEqual({
+        artifacts: []
+      })
+    })
+
+    it('should fail if non-200 response', async () => {
+      const mockListArtifacts = github.getOctokit(fixtures.token).rest.actions
+        .listWorkflowRunArtifacts as MockedListWorkflowRunArtifacts
+
+      mockListArtifacts.mockRejectedValue(new Error('boom'))
+
+      await expect(
+        listArtifactsPublic(
+          fixtures.runId,
+          fixtures.owner,
+          fixtures.repo,
+          fixtures.token,
+          false
+        )
+      ).rejects.toThrow('boom')
+    })
+  })
+
+  describe('internal', () => {
+    beforeEach(() => {
+      jest.spyOn(config, 'getRuntimeToken').mockReturnValue('test-token')
+      jest
+        .spyOn(util, 'getBackendIdsFromToken')
+        .mockReturnValue(fixtures.backendIds)
+      jest
+        .spyOn(config, 'getResultsServiceUrl')
+        .mockReturnValue('https://results.local')
+    })
+
+    it('should return a list of artifacts', async () => {
+      jest
+        .spyOn(ArtifactServiceClientJSON.prototype, 'ListArtifacts')
+        .mockResolvedValue({
+          artifacts: fixtures.artifacts.map(artifact => ({
+            ...fixtures.backendIds,
+            databaseId: artifact.id.toString(),
+            name: artifact.name,
+            size: artifact.size.toString(),
+            createdAt: Timestamp.fromDate(artifact.createdAt)
+          }))
+        })
+      const response = await listArtifactsInternal(false)
+      expect(response).toEqual({
+        artifacts: fixtures.artifacts
+      })
+    })
+
+    it('should return the latest artifact when latest is specified', async () => {
+      jest
+        .spyOn(ArtifactServiceClientJSON.prototype, 'ListArtifacts')
+        .mockResolvedValue({
+          artifacts: fixtures.artifacts.map(artifact => ({
+            ...fixtures.backendIds,
+            databaseId: artifact.id.toString(),
+            name: artifact.name,
+            size: artifact.size.toString(),
+            createdAt: Timestamp.fromDate(artifact.createdAt)
+          }))
+        })
+      const response = await listArtifactsInternal(true)
+      expect(response).toEqual({
+        artifacts: [fixtures.artifacts[1]]
+      })
+    })
+
+    it('can return empty artifacts', async () => {
+      jest
+        .spyOn(ArtifactServiceClientJSON.prototype, 'ListArtifacts')
+        .mockResolvedValue({
+          artifacts: []
+        })
+      const response = await listArtifactsInternal(false)
+      expect(response).toEqual({
+        artifacts: []
+      })
+    })
+
+    it('should fail if non-200 response', async () => {
+      jest
+        .spyOn(ArtifactServiceClientJSON.prototype, 'ListArtifacts')
+        .mockRejectedValue(new Error('boom'))
+      await expect(listArtifactsInternal(false)).rejects.toThrow('boom')
+    })
+  })
+})

packages/artifact/__tests__/upload-artifact.test.ts

@@ -7,6 +7,7 @@ import {Timestamp, ArtifactServiceClientJSON} from '../src/generated'
 import * as blobUpload from '../src/internal/upload/blob-upload'
 import {uploadArtifact} from '../src/internal/upload/upload-artifact'
 import {noopLogs} from './common'
+import {FilesNotFoundError} from '../src/internal/shared/errors'
 
 describe('upload-artifact', () => {
   beforeEach(() => {
@@ -59,7 +60,6 @@ describe('upload-artifact', () => {
       )
     jest.spyOn(blobUpload, 'uploadZipToBlobStorage').mockReturnValue(
       Promise.resolve({
-        isSuccess: true,
         uploadSize: 1234,
         sha256Hash: 'test-sha256-hash'
       })
@@ -84,7 +84,7 @@ describe('upload-artifact', () => {
       '/home/user/files/plz-upload'
     )
 
-    expect(uploadResp).resolves.toEqual({success: true, size: 1234, id: 1})
+    expect(uploadResp).resolves.toEqual({size: 1234, id: 1})
   })
 
   it('should throw an error if the root directory is invalid', () => {
@@ -107,7 +107,7 @@ describe('upload-artifact', () => {
     expect(uploadResp).rejects.toThrow('Invalid root directory')
   })
 
-  it('should return false if there are no files to upload', () => {
+  it('should reject if there are no files to upload', () => {
     jest
       .spyOn(uploadZipSpecification, 'validateRootDirectory')
       .mockReturnValue()
@@ -124,7 +124,7 @@ describe('upload-artifact', () => {
       ],
       '/home/user/files/plz-upload'
     )
-    expect(uploadResp).resolves.toEqual({success: false})
+    expect(uploadResp).rejects.toThrowError(FilesNotFoundError)
   })
 
   it('should reject if no backend IDs are found', () => {
@@ -217,7 +217,7 @@ describe('upload-artifact', () => {
       '/home/user/files/plz-upload'
     )
 
-    expect(uploadResp).resolves.toEqual({success: false})
+    expect(uploadResp).rejects.toThrow()
   })
 
   it('should return false if blob storage upload is unsuccessful', () => {
@@ -262,7 +262,7 @@ describe('upload-artifact', () => {
       )
     jest
       .spyOn(blobUpload, 'uploadZipToBlobStorage')
-      .mockReturnValue(Promise.resolve({isSuccess: false}))
+      .mockReturnValue(Promise.reject(new Error('boom')))
 
     // ArtifactHttpClient mocks
     jest.spyOn(config, 'getRuntimeToken').mockReturnValue('test-token')
@@ -280,10 +280,10 @@ describe('upload-artifact', () => {
       '/home/user/files/plz-upload'
     )
 
-    expect(uploadResp).resolves.toEqual({success: false})
+    expect(uploadResp).rejects.toThrow()
   })
 
-  it('should return false if finalize artifact fails', () => {
+  it('should reject if finalize artifact fails', () => {
     const mockDate = new Date('2020-01-01')
     jest
       .spyOn(uploadZipSpecification, 'validateRootDirectory')
@@ -325,7 +325,6 @@ describe('upload-artifact', () => {
       )
     jest.spyOn(blobUpload, 'uploadZipToBlobStorage').mockReturnValue(
       Promise.resolve({
-        isSuccess: true,
         uploadSize: 1234,
         sha256Hash: 'test-sha256-hash'
       })
@@ -350,6 +349,6 @@ describe('upload-artifact', () => {
       '/home/user/files/plz-upload'
     )
 
-    expect(uploadResp).resolves.toEqual({success: false})
+    expect(uploadResp).rejects.toThrow()
   })
 })

packages/artifact/docs/docs.md

@@ -1 +0,0 @@
-Docs will be added here once development of version `2.0.0` has finished

packages/artifact/docs/faq.md

@@ -0,0 +1,35 @@
+# Frequently Asked Questions
+
+- [Frequently Asked Questions](#frequently-asked-questions)
+  - [Supported Characters](#supported-characters)
+  - [Compression? ZIP? How is my artifact stored?](#compression-zip-how-is-my-artifact-stored)
+
+## Supported Characters
+
+When uploading an artifact, the inputted `name` parameter along with the files specified in `files` cannot contain any of the following characters. If they are present in `name` or `files`,  the Artifact will be rejected by the server and the upload will fail. These characters are not allowed due to limitations and restrictions with certain file systems such as NTFS. To maintain platform-agnostic behavior, characters that are not supported by an individual filesystem/platform will not be supported on all filesystems/platforms.
+
+- "
+- :
+- <
+- \>
+- |
+- \*
+- ?
+
+In addition to the aforementioned characters, the inputted `name` also cannot include the following
+- \
+- /
+
+## Compression? ZIP? How is my artifact stored?
+
+When creating an Artifact, the files are dynamically compressed and streamed into a ZIP archive. Since they are stored in a ZIP, they can be compressed by Zlib in varying levels.
+
+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.

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)

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

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)

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

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

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

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

packages/artifact/package-lock.json

@@ -18,15 +18,17 @@
         "@octokit/plugin-retry": "^3.0.9",
         "@octokit/request-error": "^5.0.0",
         "@protobuf-ts/plugin": "^2.2.3-alpha.1",
-        "@types/unzipper": "^0.10.6",
         "archiver": "^5.3.1",
         "crypto": "^1.0.1",
         "jwt-decode": "^3.1.2",
         "twirp-ts": "^2.5.0",
-        "unzipper": "^0.10.14"
+        "unzip-stream": "^0.3.1"
       },
       "devDependencies": {
         "@types/archiver": "^5.3.2",
+        "@types/unzip-stream": "^0.3.4",
+        "typedoc": "^0.25.4",
+        "typedoc-plugin-markdown": "^3.17.1",
         "typescript": "^5.2.2"
       }
     },
@@ -469,14 +471,21 @@
         "@types/node": "*"
       }
     },
-    "node_modules/@types/unzipper": {
-      "version": "0.10.6",
-      "resolved": "https://registry.npmjs.org/@types/unzipper/-/unzipper-0.10.6.tgz",
-      "integrity": "sha512-zcBj329AHgKLQyz209N/S9R0GZqXSkUQO4tJSYE3x02qg4JuDFpgKMj50r82Erk1natCWQDIvSccDddt7jPzjA==",
+    "node_modules/@types/unzip-stream": {
+      "version": "0.3.4",
+      "resolved": "https://registry.npmjs.org/@types/unzip-stream/-/unzip-stream-0.3.4.tgz",
+      "integrity": "sha512-ud0vtsNRF+joUCyvNMyo0j5DKX2Lh/im+xVgRzBEsfHhQYZ+i4fKTveova9XxLzt6Jl6G0e/0mM4aC0gqZYSnA==",
+      "dev": true,
       "dependencies": {
         "@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",
@@ -580,14 +589,6 @@
       "resolved": "https://registry.npmjs.org/before-after-hook/-/before-after-hook-2.2.3.tgz",
       "integrity": "sha512-NzUnlZexiaH/46WDhANlyR2bXRopNg4F/zuSA3OpZnllCUgRaOF2znDioDWrmbNVsuZk6l9pMquQB38cfBZwkQ=="
     },
-    "node_modules/big-integer": {
-      "version": "1.6.51",
-      "resolved": "https://registry.npmjs.org/big-integer/-/big-integer-1.6.51.tgz",
-      "integrity": "sha512-GPEid2Y9QU1Exl1rpO9B2IPJGHPSupF5GnVIP0blYvNOMer2bTvSWs1jGOUg04hTmu67nmLsQ9TBo1puaotBHg==",
-      "engines": {
-        "node": ">=0.6"
-      }
-    },
     "node_modules/binary": {
       "version": "0.3.0",
       "resolved": "https://registry.npmjs.org/binary/-/binary-0.3.0.tgz",
@@ -610,11 +611,6 @@
         "readable-stream": "^3.4.0"
       }
     },
-    "node_modules/bluebird": {
-      "version": "3.4.7",
-      "resolved": "https://registry.npmjs.org/bluebird/-/bluebird-3.4.7.tgz",
-      "integrity": "sha512-iD3898SR7sWVRHbiQv+sHUtHnMvC1o3nW5rAcqnq3uOn07DSAppZYUkIGslDz6gXC7HfunPe7YVBgoEJASPcHA=="
-    },
     "node_modules/bottleneck": {
       "version": "2.19.5",
       "resolved": "https://registry.npmjs.org/bottleneck/-/bottleneck-2.19.5.tgz",
@@ -660,14 +656,6 @@
         "node": "*"
       }
     },
-    "node_modules/buffer-indexof-polyfill": {
-      "version": "1.0.2",
-      "resolved": "https://registry.npmjs.org/buffer-indexof-polyfill/-/buffer-indexof-polyfill-1.0.2.tgz",
-      "integrity": "sha512-I7wzHwA3t1/lwXQh+A5PbNvJxgfo5r3xulgpYDB5zckTu/Z9oUK9biouBKQUjEqzaz3HnAT6TYoovmE+GqSf7A==",
-      "engines": {
-        "node": ">=0.10"
-      }
-    },
     "node_modules/buffers": {
       "version": "0.1.1",
       "resolved": "https://registry.npmjs.org/buffers/-/buffers-0.1.1.tgz",
@@ -793,41 +781,6 @@
         "dot-object": "bin/dot-object"
       }
     },
-    "node_modules/duplexer2": {
-      "version": "0.1.4",
-      "resolved": "https://registry.npmjs.org/duplexer2/-/duplexer2-0.1.4.tgz",
-      "integrity": "sha512-asLFVfWWtJ90ZyOUHMqk7/S2w2guQKxUI2itj3d92ADHhxUSbCMGi1f1cBcJ7xM1To+pE/Khbwo1yuNbMEPKeA==",
-      "dependencies": {
-        "readable-stream": "^2.0.2"
-      }
-    },
-    "node_modules/duplexer2/node_modules/readable-stream": {
-      "version": "2.3.8",
-      "resolved": "https://registry.npmjs.org/readable-stream/-/readable-stream-2.3.8.tgz",
-      "integrity": "sha512-8p0AUk4XODgIewSi0l8Epjs+EVnWiK7NoDIEGU0HhE7+ZyY8D1IMY7odu5lRrFXGg71L15KG8QrPmum45RTtdA==",
-      "dependencies": {
-        "core-util-is": "~1.0.0",
-        "inherits": "~2.0.3",
-        "isarray": "~1.0.0",
-        "process-nextick-args": "~2.0.0",
-        "safe-buffer": "~5.1.1",
-        "string_decoder": "~1.1.1",
-        "util-deprecate": "~1.0.1"
-      }
-    },
-    "node_modules/duplexer2/node_modules/safe-buffer": {
-      "version": "5.1.2",
-      "resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.1.2.tgz",
-      "integrity": "sha512-Gd2UZBJDkXlY7GbJxfsE8/nvKkUEU1G38c1siN6QP6a9PT9MmHB8GnpscSmMJSoF8LOIrt8ud/wPtojys4G6+g=="
-    },
-    "node_modules/duplexer2/node_modules/string_decoder": {
-      "version": "1.1.1",
-      "resolved": "https://registry.npmjs.org/string_decoder/-/string_decoder-1.1.1.tgz",
-      "integrity": "sha512-n/ShnvDi6FHbbVfviro+WojiFzv+s8MPMHBczVePfUpDJLwoLT0ht1l4YwBCbi8pJAveEEdnkHyPyTP/mzRfwg==",
-      "dependencies": {
-        "safe-buffer": "~5.1.0"
-      }
-    },
     "node_modules/end-of-stream": {
       "version": "1.4.4",
       "resolved": "https://registry.npmjs.org/end-of-stream/-/end-of-stream-1.4.4.tgz",
@@ -867,20 +820,6 @@
       "resolved": "https://registry.npmjs.org/fs.realpath/-/fs.realpath-1.0.0.tgz",
       "integrity": "sha512-OO0pH2lK6a0hZnAdau5ItzHPI6pUlvI7jMVnxUQRtw4owF2wk8lOSabtGDCTP4Ggrg2MbGnWO9X8K1t4+fGMDw=="
     },
-    "node_modules/fstream": {
-      "version": "1.0.12",
-      "resolved": "https://registry.npmjs.org/fstream/-/fstream-1.0.12.tgz",
-      "integrity": "sha512-WvJ193OHa0GHPEL+AycEJgxvBEwyfRkN1vhjca23OaPVMCaLCXTd5qAu82AjTcgP1UJmytkOKb63Ypde7raDIg==",
-      "dependencies": {
-        "graceful-fs": "^4.1.2",
-        "inherits": "~2.0.0",
-        "mkdirp": ">=0.5 0",
-        "rimraf": "2"
-      },
-      "engines": {
-        "node": ">=0.6"
-      }
-    },
     "node_modules/glob": {
       "version": "7.2.3",
       "resolved": "https://registry.npmjs.org/glob/-/glob-7.2.3.tgz",
@@ -905,6 +844,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 +911,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",
@@ -994,11 +960,6 @@
         "safe-buffer": "~5.1.0"
       }
     },
-    "node_modules/listenercount": {
-      "version": "1.0.1",
-      "resolved": "https://registry.npmjs.org/listenercount/-/listenercount-1.0.1.tgz",
-      "integrity": "sha512-3mk/Zag0+IJxeDrxSgaDPy4zZ3w05PRZeJNnlWhzFz5OkX49J4krc+A8X2d2M69vGMBEX0uyl8M+W+8gH+kBqQ=="
-    },
     "node_modules/lodash": {
       "version": "4.17.21",
       "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz",
@@ -1037,6 +998,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 +1065,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",
@@ -1219,17 +1204,6 @@
         "node": ">=10"
       }
     },
-    "node_modules/rimraf": {
-      "version": "2.7.1",
-      "resolved": "https://registry.npmjs.org/rimraf/-/rimraf-2.7.1.tgz",
-      "integrity": "sha512-uWjbaKIK3T1OSVptzX7Nl6PvQ3qAGtKEtVRjRuazjfL3Bx5eI409VZSqgND+4UNnmzLVdPj9FqFJNPqBZFve4w==",
-      "dependencies": {
-        "glob": "^7.1.3"
-      },
-      "bin": {
-        "rimraf": "bin.js"
-      }
-    },
     "node_modules/safe-buffer": {
       "version": "5.2.1",
       "resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.2.1.tgz",
@@ -1254,10 +1228,26 @@
       "resolved": "https://registry.npmjs.org/sax/-/sax-1.2.4.tgz",
       "integrity": "sha512-NqVDv9TpANUjFm0N8uM5GxL36UgKi9/atZw+x7YFnQ8ckwFGKrl4xX4yWtrey3UJm5nP1kUbnYgLopqWNSRhWw=="
     },
-    "node_modules/setimmediate": {
-      "version": "1.0.5",
-      "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",
@@ -1345,6 +1335,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,53 +1405,31 @@
         "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",
       "integrity": "sha512-isyNax3wXoKaulPDZWHQqbmIx1k2tb9fb3GGDBRxCscfYV2Ch7WxPArBsFEG8s/safwXTT7H4QGhaIkTp9447w=="
     },
-    "node_modules/unzipper": {
-      "version": "0.10.14",
-      "resolved": "https://registry.npmjs.org/unzipper/-/unzipper-0.10.14.tgz",
-      "integrity": "sha512-ti4wZj+0bQTiX2KmKWuwj7lhV+2n//uXEotUmGuQqrbVZSEGFMbI68+c6JCQ8aAmUWYvtHEz2A8K6wXvueR/6g==",
+    "node_modules/unzip-stream": {
+      "version": "0.3.1",
+      "resolved": "https://registry.npmjs.org/unzip-stream/-/unzip-stream-0.3.1.tgz",
+      "integrity": "sha512-RzaGXLNt+CW+T41h1zl6pGz3EaeVhYlK+rdAap+7DxW5kqsqePO8kRtWPaCiVqdhZc86EctSPVYNix30YOMzmw==",
       "dependencies": {
-        "big-integer": "^1.6.17",
-        "binary": "~0.3.0",
-        "bluebird": "~3.4.1",
-        "buffer-indexof-polyfill": "~1.0.0",
-        "duplexer2": "~0.1.4",
-        "fstream": "^1.0.12",
-        "graceful-fs": "^4.2.2",
-        "listenercount": "~1.0.1",
-        "readable-stream": "~2.3.6",
-        "setimmediate": "~1.0.4"
-      }
-    },
-    "node_modules/unzipper/node_modules/readable-stream": {
-      "version": "2.3.8",
-      "resolved": "https://registry.npmjs.org/readable-stream/-/readable-stream-2.3.8.tgz",
-      "integrity": "sha512-8p0AUk4XODgIewSi0l8Epjs+EVnWiK7NoDIEGU0HhE7+ZyY8D1IMY7odu5lRrFXGg71L15KG8QrPmum45RTtdA==",
-      "dependencies": {
-        "core-util-is": "~1.0.0",
-        "inherits": "~2.0.3",
-        "isarray": "~1.0.0",
-        "process-nextick-args": "~2.0.0",
-        "safe-buffer": "~5.1.1",
-        "string_decoder": "~1.1.1",
-        "util-deprecate": "~1.0.1"
-      }
-    },
-    "node_modules/unzipper/node_modules/safe-buffer": {
-      "version": "5.1.2",
-      "resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.1.2.tgz",
-      "integrity": "sha512-Gd2UZBJDkXlY7GbJxfsE8/nvKkUEU1G38c1siN6QP6a9PT9MmHB8GnpscSmMJSoF8LOIrt8ud/wPtojys4G6+g=="
-    },
-    "node_modules/unzipper/node_modules/string_decoder": {
-      "version": "1.1.1",
-      "resolved": "https://registry.npmjs.org/string_decoder/-/string_decoder-1.1.1.tgz",
-      "integrity": "sha512-n/ShnvDi6FHbbVfviro+WojiFzv+s8MPMHBczVePfUpDJLwoLT0ht1l4YwBCbi8pJAveEEdnkHyPyTP/mzRfwg==",
-      "dependencies": {
-        "safe-buffer": "~5.1.0"
+        "binary": "^0.3.0",
+        "mkdirp": "^0.5.1"
       }
     },
     "node_modules/util-deprecate": {
@@ -1420,6 +1445,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 +1471,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",

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"
@@ -48,15 +49,17 @@
     "@octokit/plugin-retry": "^3.0.9",
     "@octokit/request-error": "^5.0.0",
     "@protobuf-ts/plugin": "^2.2.3-alpha.1",
-    "@types/unzipper": "^0.10.6",
     "archiver": "^5.3.1",
     "crypto": "^1.0.1",
     "jwt-decode": "^3.1.2",
     "twirp-ts": "^2.5.0",
-    "unzipper": "^0.10.14"
+    "unzip-stream": "^0.3.1"
   },
   "devDependencies": {
     "@types/archiver": "^5.3.2",
+    "@types/unzip-stream": "^0.3.4",
+    "typedoc": "^0.25.4",
+    "typedoc-plugin-markdown": "^3.17.1",
     "typescript": "^5.2.2"
   }
 }

packages/artifact/src/artifact.ts

@@ -1,11 +1,8 @@
-import {ArtifactClient, Client} from './internal/client'
+import {ArtifactClient, DefaultArtifactClient} from './internal/client'
 
-/**
- * Exported functionality that we want to expose for any users of @actions/artifact
- */
 export * from './internal/shared/interfaces'
-export {ArtifactClient}
+export * from './internal/shared/errors'
+export * from './internal/client'
 
-export function create(): ArtifactClient {
-  return Client.create()
-}
+const client: ArtifactClient = new DefaultArtifactClient()
+export default client

packages/artifact/src/generated/results/api/v1/artifact.ts

@@ -163,6 +163,12 @@ export interface ListArtifactsResponse_MonolithArtifact {
      * @generated from protobuf field: int64 size = 5;
      */
     size: string;
+    /**
+     * When the artifact was created in the monolith
+     *
+     * @generated from protobuf field: google.protobuf.Timestamp created_at = 6;
+     */
+    createdAt?: Timestamp;
 }
 /**
  * @generated from protobuf message github.actions.results.api.v1.GetSignedArtifactURLRequest
@@ -571,7 +577,8 @@ class ListArtifactsResponse_MonolithArtifact$Type extends MessageType<ListArtifa
             { no: 2, name: "workflow_job_run_backend_id", kind: "scalar", T: 9 /*ScalarType.STRING*/ },
             { no: 3, name: "database_id", kind: "scalar", T: 3 /*ScalarType.INT64*/ },
             { no: 4, name: "name", kind: "scalar", T: 9 /*ScalarType.STRING*/ },
-            { no: 5, name: "size", kind: "scalar", T: 3 /*ScalarType.INT64*/ }
+            { no: 5, name: "size", kind: "scalar", T: 3 /*ScalarType.INT64*/ },
+            { no: 6, name: "created_at", kind: "message", T: () => Timestamp }
         ]);
     }
     create(value?: PartialMessage<ListArtifactsResponse_MonolithArtifact>): ListArtifactsResponse_MonolithArtifact {
@@ -601,6 +608,9 @@ class ListArtifactsResponse_MonolithArtifact$Type extends MessageType<ListArtifa
                 case /* int64 size */ 5:
                     message.size = reader.int64().toString();
                     break;
+                case /* google.protobuf.Timestamp created_at */ 6:
+                    message.createdAt = Timestamp.internalBinaryRead(reader, reader.uint32(), options, message.createdAt);
+                    break;
                 default:
                     let u = options.readUnknownField;
                     if (u === "throw")
@@ -628,6 +638,9 @@ class ListArtifactsResponse_MonolithArtifact$Type extends MessageType<ListArtifa
         /* int64 size = 5; */
         if (message.size !== "0")
             writer.tag(5, WireType.Varint).int64(message.size);
+        /* google.protobuf.Timestamp created_at = 6; */
+        if (message.createdAt)
+            Timestamp.internalBinaryWrite(message.createdAt, writer.tag(6, WireType.LengthDelimited).fork(), options).join();
         let u = options.writeUnknownFields;
         if (u !== false)
             (u == true ? UnknownFieldHandler.onWrite : u)(this.typeName, message, writer);

packages/artifact/src/internal/client.ts

@@ -1,10 +1,11 @@
 import {warning} from '@actions/core'
 import {isGhes} from './shared/config'
 import {
-  UploadOptions,
-  UploadResponse,
+  UploadArtifactOptions,
+  UploadArtifactResponse,
   DownloadArtifactOptions,
   GetArtifactResponse,
+  ListArtifactsOptions,
   ListArtifactsResponse,
   DownloadArtifactResponse,
   FindOptions
@@ -16,43 +17,51 @@ import {
 } from './download/download-artifact'
 import {getArtifactPublic, getArtifactInternal} from './find/get-artifact'
 import {listArtifactsPublic, listArtifactsInternal} from './find/list-artifacts'
+import {GHESNotSupportedError} from './shared/errors'
 
+/**
+ * Generic interface for the artifact client.
+ */
 export interface ArtifactClient {
   /**
-   * Uploads an artifact
+   * Uploads an artifact.
    *
    * @param name The name of the artifact, required
    * @param files A list of absolute or relative paths that denote what files should be uploaded
    * @param rootDirectory An absolute or relative file path that denotes the root parent directory of the files being uploaded
    * @param options Extra options for customizing the upload behavior
-   * @returns single UploadResponse object
+   * @returns single UploadArtifactResponse object
    */
   uploadArtifact(
     name: string,
     files: string[],
     rootDirectory: string,
-    options?: UploadOptions
-  ): Promise<UploadResponse>
+    options?: UploadArtifactOptions
+  ): Promise<UploadArtifactResponse>
 
   /**
    * 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.
+   * 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
    *
    * @param options Extra options that allow for the customization of the list behavior
    * @returns ListArtifactResponse object
    */
-  listArtifacts(options?: FindOptions): Promise<ListArtifactsResponse>
+  listArtifacts(
+    options?: ListArtifactsOptions & FindOptions
+  ): Promise<ListArtifactsResponse>
 
   /**
    * 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.
+   * 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 > 2.0.0 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.0.0 or it is a rerun.
+   * `@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.
    *
    * @param artifactName The name of the artifact to find
@@ -66,7 +75,7 @@ export interface ArtifactClient {
   /**
    * 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
+   * 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
    *
    * @param artifactId The name of the artifact to download
    * @param options Extra options that allow for the customization of the download behavior
@@ -78,33 +87,21 @@ export interface ArtifactClient {
   ): Promise<DownloadArtifactResponse>
 }
 
-export class Client implements ArtifactClient {
-  /**
-   * Constructs a Client
-   */
-  static create(): Client {
-    return new Client()
-  }
-
-  /**
-   * Upload Artifact
-   */
+/**
+ * The default artifact client that is used by the artifact action(s).
+ */
+export class DefaultArtifactClient implements ArtifactClient {
   async uploadArtifact(
     name: string,
     files: string[],
     rootDirectory: string,
-    options?: UploadOptions
-  ): Promise<UploadResponse> {
-    if (isGhes()) {
-      warning(
-        `@actions/artifact v2.0.0+ and upload-artifact@v4+ are not currently supported on GHES.`
-      )
-      return {
-        success: false
-      }
-    }
-
+    options?: UploadArtifactOptions
+  ): Promise<UploadArtifactResponse> {
     try {
+      if (isGhes()) {
+        throw new GHESNotSupportedError()
+      }
+
       return uploadArtifact(name, files, rootDirectory, options)
     } catch (error) {
       warning(
@@ -114,29 +111,20 @@ Errors can be temporary, so please try again and optionally run the action with
 
 If the error persists, please check whether Actions is operating normally at [https://githubstatus.com](https://www.githubstatus.com).`
       )
-      return {
-        success: false
-      }
+
+      throw error
     }
   }
 
-  /**
-   * Download Artifact
-   */
   async downloadArtifact(
     artifactId: number,
     options?: DownloadArtifactOptions & FindOptions
   ): Promise<DownloadArtifactResponse> {
-    if (isGhes()) {
-      warning(
-        `@actions/artifact v2.0.0+ and download-artifact@v4+ are not currently supported on GHES.`
-      )
-      return {
-        success: false
-      }
-    }
-
     try {
+      if (isGhes()) {
+        throw new GHESNotSupportedError()
+      }
+
       if (options?.findBy) {
         const {
           findBy: {repositoryOwner, repositoryName, token},
@@ -155,33 +143,25 @@ If the error persists, please check whether Actions is operating normally at [ht
       return downloadArtifactInternal(artifactId, options)
     } catch (error) {
       warning(
-        `Artifact download failed with error: ${error}.
+        `Download Artifact failed with error: ${error}.
 
 Errors can be temporary, so please try again and optionally run the action with debug mode enabled for more information.
 
 If the error persists, please check whether Actions and API requests are operating normally at [https://githubstatus.com](https://www.githubstatus.com).`
       )
 
-      return {
-        success: false
-      }
+      throw error
     }
   }
 
-  /**
-   * List Artifacts
-   */
-  async listArtifacts(options?: FindOptions): Promise<ListArtifactsResponse> {
-    if (isGhes()) {
-      warning(
-        `@actions/artifact v2.0.0+ and download-artifact@v4+ are not currently supported on GHES.`
-      )
-      return {
-        artifacts: []
-      }
-    }
-
+  async listArtifacts(
+    options?: ListArtifactsOptions & FindOptions
+  ): Promise<ListArtifactsResponse> {
     try {
+      if (isGhes()) {
+        throw new GHESNotSupportedError()
+      }
+
       if (options?.findBy) {
         const {
           findBy: {workflowRunId, repositoryOwner, repositoryName, token}
@@ -191,11 +171,12 @@ If the error persists, please check whether Actions and API requests are operati
           workflowRunId,
           repositoryOwner,
           repositoryName,
-          token
+          token,
+          options?.latest
         )
       }
 
-      return listArtifactsInternal()
+      return listArtifactsInternal(options?.latest)
     } catch (error: unknown) {
       warning(
         `Listing Artifacts failed with error: ${error}.
@@ -205,29 +186,19 @@ Errors can be temporary, so please try again and optionally run the action with
 If the error persists, please check whether Actions and API requests are operating normally at [https://githubstatus.com](https://www.githubstatus.com).`
       )
 
-      return {
-        artifacts: []
-      }
+      throw error
     }
   }
 
-  /**
-   * Get Artifact
-   */
   async getArtifact(
     artifactName: string,
     options?: FindOptions
   ): Promise<GetArtifactResponse> {
-    if (isGhes()) {
-      warning(
-        `@actions/artifact v2.0.0+ and download-artifact@v4+ are not currently supported on GHES.`
-      )
-      return {
-        success: false
-      }
-    }
-
     try {
+      if (isGhes()) {
+        throw new GHESNotSupportedError()
+      }
+
       if (options?.findBy) {
         const {
           findBy: {workflowRunId, repositoryOwner, repositoryName, token}
@@ -245,15 +216,13 @@ If the error persists, please check whether Actions and API requests are operati
       return getArtifactInternal(artifactName)
     } catch (error: unknown) {
       warning(
-        `Fetching Artifact failed with error: ${error}.
+        `Get Artifact failed with error: ${error}.
 
 Errors can be temporary, so please try again and optionally run the action with debug mode enabled for more information.
 
 If the error persists, please check whether Actions and API requests are operating normally at [https://githubstatus.com](https://www.githubstatus.com).`
       )
-      return {
-        success: false
-      }
+      throw error
     }
   }
 }

packages/artifact/src/internal/download/download-artifact.ts

@@ -2,7 +2,7 @@ import fs from 'fs/promises'
 import * as github from '@actions/github'
 import * as core from '@actions/core'
 import * as httpClient from '@actions/http-client'
-import unzipper from 'unzipper'
+import unzip from 'unzip-stream'
 import {
   DownloadArtifactOptions,
   DownloadArtifactResponse
@@ -16,6 +16,7 @@ import {
   ListArtifactsRequest
 } from '../../generated'
 import {getBackendIdsFromToken} from '../shared/util'
+import {ArtifactNotFoundError} from '../shared/errors'
 
 const scrubQueryParameters = (url: string): string => {
   const parsed = new URL(url)
@@ -46,7 +47,12 @@ async function streamExtract(url: string, directory: string): Promise<void> {
     )
   }
 
-  return response.message.pipe(unzipper.Extract({path: directory})).promise()
+  return new Promise((resolve, reject) => {
+    response.message
+      .pipe(unzip.Extract({path: directory}))
+      .on('close', resolve)
+      .on('error', reject)
+  })
 }
 
 export async function downloadArtifactPublic(
@@ -95,7 +101,7 @@ export async function downloadArtifactPublic(
     throw new Error(`Unable to download and extract artifact: ${error.message}`)
   }
 
-  return {success: true, downloadPath}
+  return {downloadPath}
 }
 
 export async function downloadArtifactInternal(
@@ -118,10 +124,9 @@ export async function downloadArtifactInternal(
   const {artifacts} = await artifactClient.ListArtifacts(listReq)
 
   if (artifacts.length === 0) {
-    core.warning(
+    throw new ArtifactNotFoundError(
       `No artifacts found for ID: ${artifactId}\nAre you trying to download from a different run? Try specifying a github-token with \`actions:read\` scope.`
     )
-    return {success: false}
   }
 
   if (artifacts.length > 1) {
@@ -148,7 +153,7 @@ export async function downloadArtifactInternal(
     throw new Error(`Unable to download and extract artifact: ${error.message}`)
   }
 
-  return {success: true, downloadPath}
+  return {downloadPath}
 }
 
 async function resolveOrCreateDirectory(

packages/artifact/src/internal/find/get-artifact.ts

@@ -9,7 +9,8 @@ import {GetArtifactResponse} from '../shared/interfaces'
 import {getBackendIdsFromToken} from '../shared/util'
 import {getUserAgentString} from '../shared/user-agent'
 import {internalArtifactTwirpClient} from '../shared/artifact-twirp-client'
-import {ListArtifactsRequest, StringValue} from '../../generated'
+import {ListArtifactsRequest, StringValue, Timestamp} from '../../generated'
+import {ArtifactNotFoundError, InvalidResponseError} from '../shared/errors'
 
 export async function getArtifactPublic(
   artifactName: string,
@@ -41,31 +42,31 @@ export async function getArtifactPublic(
   )
 
   if (getArtifactResp.status !== 200) {
-    core.warning(`non-200 response from GitHub API: ${getArtifactResp.status}`)
-    return {
-      success: false
-    }
+    throw new InvalidResponseError(
+      `Invalid response from GitHub API: ${getArtifactResp.status} (${getArtifactResp?.headers?.['x-github-request-id']})`
+    )
   }
 
   if (getArtifactResp.data.artifacts.length === 0) {
-    core.warning('no artifacts found')
-    return {
-      success: false
-    }
+    throw new ArtifactNotFoundError(
+      `Artifact not found for name: ${artifactName}`
+    )
   }
 
+  let artifact = getArtifactResp.data.artifacts[0]
   if (getArtifactResp.data.artifacts.length > 1) {
-    core.warning(
-      'more than one artifact found for a single name, returning first'
+    artifact = getArtifactResp.data.artifacts.sort((a, b) => b.id - a.id)[0]
+    core.debug(
+      `More than one artifact found for a single name, returning newest (id: ${artifact.id})`
     )
   }
 
   return {
-    success: true,
     artifact: {
-      name: getArtifactResp.data.artifacts[0].name,
-      id: getArtifactResp.data.artifacts[0].id,
-      size: getArtifactResp.data.artifacts[0].size_in_bytes
+      name: artifact.name,
+      id: artifact.id,
+      size: artifact.size_in_bytes,
+      createdAt: artifact.created_at ? new Date(artifact.created_at) : undefined
     }
   }
 }
@@ -87,32 +88,30 @@ export async function getArtifactInternal(
   const res = await artifactClient.ListArtifacts(req)
 
   if (res.artifacts.length === 0) {
-    core.warning('no artifacts found')
-    return {
-      success: false
-    }
-  }
-
-  if (res.artifacts.length > 1) {
-    core.warning(
-      'more than one artifact found for a single name, returning first'
+    throw new ArtifactNotFoundError(
+      `Artifact not found for name: ${artifactName}`
     )
   }
 
-  // In the case of reruns, we may have artifacts with the same name scoped under the same workflow run.
-  // Let's prefer the artifact closest scoped to this run.
-  // If it doesn't exist (e.g. partial rerun) we'll use the first match.
-  const artifact =
-    res.artifacts.find(
-      artifact => artifact.workflowRunBackendId === workflowRunBackendId
-    ) || res.artifacts[0]
+  let artifact = res.artifacts[0]
+  if (res.artifacts.length > 1) {
+    artifact = res.artifacts.sort(
+      (a, b) => Number(b.databaseId) - Number(a.databaseId)
+    )[0]
+
+    core.debug(
+      `More than one artifact found for a single name, returning newest (id: ${artifact.databaseId})`
+    )
+  }
 
   return {
-    success: true,
     artifact: {
       name: artifact.name,
       id: Number(artifact.databaseId),
-      size: Number(artifact.size)
+      size: Number(artifact.size),
+      createdAt: artifact.createdAt
+        ? Timestamp.toDate(artifact.createdAt)
+        : undefined
     }
   }
 }

packages/artifact/src/internal/find/list-artifacts.ts

@@ -9,7 +9,7 @@ import {retry} from '@octokit/plugin-retry'
 import {OctokitOptions} from '@octokit/core/dist-types/types'
 import {internalArtifactTwirpClient} from '../shared/artifact-twirp-client'
 import {getBackendIdsFromToken} from '../shared/util'
-import {ListArtifactsRequest} from 'src/generated'
+import {ListArtifactsRequest, Timestamp} from '../../generated'
 
 // Limiting to 1000 for perf reasons
 const maximumArtifactCount = 1000
@@ -20,13 +20,14 @@ export async function listArtifactsPublic(
   workflowRunId: number,
   repositoryOwner: string,
   repositoryName: string,
-  token: string
+  token: string,
+  latest = false
 ): Promise<ListArtifactsResponse> {
   info(
     `Fetching artifact list for workflow run ${workflowRunId} in repository ${repositoryOwner}/${repositoryName}`
   )
 
-  const artifacts: Artifact[] = []
+  let artifacts: Artifact[] = []
   const [retryOpts, requestOpts] = getRetryOptions(defaultGitHubOptions)
 
   const opts: OctokitOptions = {
@@ -65,7 +66,8 @@ export async function listArtifactsPublic(
     artifacts.push({
       name: artifact.name,
       id: artifact.id,
-      size: artifact.size_in_bytes
+      size: artifact.size_in_bytes,
+      createdAt: artifact.created_at ? new Date(artifact.created_at) : undefined
     })
   }
 
@@ -91,11 +93,18 @@ export async function listArtifactsPublic(
       artifacts.push({
         name: artifact.name,
         id: artifact.id,
-        size: artifact.size_in_bytes
+        size: artifact.size_in_bytes,
+        createdAt: artifact.created_at
+          ? new Date(artifact.created_at)
+          : undefined
       })
     }
   }
 
+  if (latest) {
+    artifacts = filterLatest(artifacts)
+  }
+
   info(`Found ${artifacts.length} artifact(s)`)
 
   return {
@@ -103,7 +112,9 @@ export async function listArtifactsPublic(
   }
 }
 
-export async function listArtifactsInternal(): Promise<ListArtifactsResponse> {
+export async function listArtifactsInternal(
+  latest = false
+): Promise<ListArtifactsResponse> {
   const artifactClient = internalArtifactTwirpClient()
 
   const {workflowRunBackendId, workflowJobRunBackendId} =
@@ -115,15 +126,40 @@ export async function listArtifactsInternal(): Promise<ListArtifactsResponse> {
   }
 
   const res = await artifactClient.ListArtifacts(req)
-  const artifacts = res.artifacts.map(artifact => ({
+  let artifacts: Artifact[] = res.artifacts.map(artifact => ({
     name: artifact.name,
     id: Number(artifact.databaseId),
-    size: Number(artifact.size)
+    size: Number(artifact.size),
+    createdAt: artifact.createdAt
+      ? Timestamp.toDate(artifact.createdAt)
+      : undefined
   }))
 
+  if (latest) {
+    artifacts = filterLatest(artifacts)
+  }
+
   info(`Found ${artifacts.length} artifact(s)`)
 
   return {
     artifacts
   }
 }
+
+/**
+ * Filters a list of artifacts to only include the latest artifact for each name
+ * @param artifacts The artifacts to filter
+ * @returns The filtered list of artifacts
+ */
+function filterLatest(artifacts: Artifact[]): Artifact[] {
+  artifacts.sort((a, b) => b.id - a.id)
+  const latestArtifacts: Artifact[] = []
+  const seenArtifactNames = new Set<string>()
+  for (const artifact of artifacts) {
+    if (!seenArtifactNames.has(artifact.name)) {
+      latestArtifacts.push(artifact)
+      seenArtifactNames.add(artifact.name)
+    }
+  }
+  return latestArtifacts
+}

packages/artifact/src/internal/shared/artifact-twirp-client.ts

@@ -4,6 +4,7 @@ import {info, debug} from '@actions/core'
 import {ArtifactServiceClientJSON} from '../../generated'
 import {getResultsServiceUrl, getRuntimeToken} from './config'
 import {getUserAgentString} from './user-agent'
+import {NetworkError} from './errors'
 
 // The twirp http client must implement this interface
 interface Rpc {
@@ -59,10 +60,10 @@ class ArtifactHttpClient implements Rpc {
       'Content-Type': contentType
     }
     try {
-      const response = await this.retryableRequest(async () =>
+      const {body} = await this.retryableRequest(async () =>
         this.httpClient.post(url, JSON.stringify(data), headers)
       )
-      const body = await response.readBody()
+
       return JSON.parse(body)
     } catch (error) {
       throw new Error(`Failed to ${method}: ${error.message}`)
@@ -71,7 +72,7 @@ class ArtifactHttpClient implements Rpc {
 
   async retryableRequest(
     operation: () => Promise<HttpClientResponse>
-  ): Promise<HttpClientResponse> {
+  ): Promise<{response: HttpClientResponse; body: string}> {
     let attempt = 0
     let errorMessage = ''
     while (attempt < this.maxAttempts) {
@@ -80,18 +81,25 @@ class ArtifactHttpClient implements Rpc {
       try {
         const response = await operation()
         const statusCode = response.message.statusCode
-        debug(`[Response] ${response.message.statusCode}`)
-        debug(JSON.stringify(response.message.headers, null, 2))
-
+        const body = await response.readBody()
+        debug(`[Response] - ${response.message.statusCode}`)
+        debug(`Headers: ${JSON.stringify(response.message.headers, null, 2)}`)
+        debug(`Body: ${body}`)
         if (this.isSuccessStatusCode(statusCode)) {
-          return response
+          return {response, body}
         }
-
         isRetryable = this.isRetryableHttpStatusCode(statusCode)
         errorMessage = `Failed request: (${statusCode}) ${response.message.statusMessage}`
+        const responseMessage = JSON.parse(body).msg
+        if (responseMessage) {
+          errorMessage = `${errorMessage}: ${responseMessage}`
+        }
       } catch (error) {
         isRetryable = true
         errorMessage = error.message
+        if (NetworkError.isNetworkErrorCode(error?.code)) {
+          throw new NetworkError(error?.code)
+        }
       }
 
       if (!isRetryable) {
@@ -131,8 +139,7 @@ class ArtifactHttpClient implements Rpc {
       HttpCodes.GatewayTimeout,
       HttpCodes.InternalServerError,
       HttpCodes.ServiceUnavailable,
-      HttpCodes.TooManyRequests,
-      413 // Payload Too Large
+      HttpCodes.TooManyRequests
     ]
 
     return retryableStatusCodes.includes(statusCode)

packages/artifact/src/internal/shared/errors.ts

@@ -0,0 +1,59 @@
+export class FilesNotFoundError extends Error {
+  files: string[]
+
+  constructor(files: string[] = []) {
+    let message = 'No files were found to upload'
+    if (files.length > 0) {
+      message += `: ${files.join(', ')}`
+    }
+
+    super(message)
+    this.files = files
+    this.name = 'FilesNotFoundError'
+  }
+}
+
+export class InvalidResponseError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'InvalidResponseError'
+  }
+}
+
+export class ArtifactNotFoundError extends Error {
+  constructor(message = 'Artifact not found') {
+    super(message)
+    this.name = 'ArtifactNotFoundError'
+  }
+}
+
+export class GHESNotSupportedError extends Error {
+  constructor(
+    message = '@actions/artifact v2.0.0+, upload-artifact@v4+ and download-artifact@v4+ are not currently supported on GHES.'
+  ) {
+    super(message)
+    this.name = 'GHESNotSupportedError'
+  }
+}
+
+export class NetworkError extends Error {
+  code: string
+
+  constructor(code: string) {
+    const message = `Unable to make request: ${code}\nIf you are using self-hosted runners, please make sure your runner has access to all GitHub endpoints: https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners#communication-between-self-hosted-runners-and-github`
+    super(message)
+    this.code = code
+    this.name = 'NetworkError'
+  }
+
+  static isNetworkErrorCode = (code?: string): boolean => {
+    if (!code) return false
+    return [
+      'ECONNRESET',
+      'ENOTFOUND',
+      'ETIMEDOUT',
+      'ECONNREFUSED',
+      'EHOSTUNREACH'
+    ].includes(code)
+  }
+}

packages/artifact/src/internal/shared/interfaces.ts

@@ -1,14 +1,7 @@
-/*****************************************************************************
- *                                                                           *
- *                            UploadArtifact                                 *
- *                                                                           *
- *****************************************************************************/
-export interface UploadResponse {
-  /**
-   * Denotes if an artifact was successfully uploaded
-   */
-  success: boolean
-
+/**
+ * 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
    */
@@ -21,7 +14,10 @@ export interface UploadResponse {
   id?: number
 }
 
-export interface UploadOptions {
+/**
+ * Options for uploading an artifact
+ */
+export interface UploadArtifactOptions {
   /**
    * Duration after which artifact will expire in days.
    *
@@ -51,29 +47,30 @@ export interface UploadOptions {
   compressionLevel?: number
 }
 
-/*****************************************************************************
- *                                                                           *
- *                              GetArtifact                                  *
- *                                                                           *
- *****************************************************************************/
-
+/**
+ * Response from the server when getting an artifact
+ */
 export interface GetArtifactResponse {
-  /**
-   * If an artifact was found
-   */
-  success: boolean
-
   /**
    * Metadata about the artifact that was found
    */
-  artifact?: Artifact
+  artifact: Artifact
 }
 
-/*****************************************************************************
- *                                                                           *
- *                             ListArtifact                                  *
- *                                                                           *
- *****************************************************************************/
+/**
+ * Options for listing artifacts
+ */
+export interface ListArtifactsOptions {
+  /**
+   * Filter the workflow run's artifacts to the latest by name
+   * In the case of reruns, this can be useful to avoid duplicates
+   */
+  latest?: boolean
+}
+
+/**
+ * Response from the server when listing artifacts
+ */
 export interface ListArtifactsResponse {
   /**
    * A list of artifacts that were found
@@ -81,22 +78,19 @@ export interface ListArtifactsResponse {
   artifacts: Artifact[]
 }
 
-/*****************************************************************************
- *                                                                           *
- *                           DownloadArtifact                                *
- *                                                                           *
- *****************************************************************************/
+/**
+ * Response from the server when downloading an artifact
+ */
 export interface DownloadArtifactResponse {
-  /**
-   * If the artifact download was successful
-   */
-  success: boolean
   /**
    * The path where the artifact was downloaded to
    */
   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
@@ -104,11 +98,9 @@ export interface DownloadArtifactOptions {
   path?: string
 }
 
-/*****************************************************************************
- *                                                                           *
- *                                 Shared                                    *
- *                                                                           *
- *****************************************************************************/
+/**
+ * An Actions Artifact
+ */
 export interface Artifact {
   /**
    * The name of the artifact
@@ -124,19 +116,34 @@ export interface Artifact {
    * The size of the artifact in bytes
    */
   size: number
+
+  /**
+   * The time when the artifact was created
+   */
+  createdAt?: Date
 }
 
 // FindOptions are for fetching Artifact(s) out of the scope of the current run.
-// Must specify a PAT 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
   }
 }

packages/artifact/src/internal/upload/blob-upload.ts

@@ -5,13 +5,9 @@ import {getUploadChunkSize, getConcurrency} from '../shared/config'
 import * as core from '@actions/core'
 import * as crypto from 'crypto'
 import * as stream from 'stream'
+import {NetworkError} from '../shared/errors'
 
 export interface BlobUploadResponse {
-  /**
-   * If the upload was successful or not
-   */
-  isSuccess: boolean
-
   /**
    * The total reported upload size in bytes. Empty if the upload failed
    */
@@ -55,41 +51,36 @@ export async function uploadZipToBlobStorage(
   zipUploadStream.pipe(uploadStream) // This stream is used for the upload
   zipUploadStream.pipe(hashStream).setEncoding('hex') // This stream is used to compute a hash of the zip content that gets used. Integrity check
 
-  try {
-    core.info('Beginning upload of artifact content to blob storage')
+  core.info('Beginning upload of artifact content to blob storage')
 
+  try {
     await blockBlobClient.uploadStream(
       uploadStream,
       bufferSize,
       maxConcurrency,
       options
     )
-
-    core.info('Finished uploading artifact content to blob storage!')
-
-    hashStream.end()
-    sha256Hash = hashStream.read() as string
-    core.info(`SHA256 hash of uploaded artifact zip is ${sha256Hash}`)
   } catch (error) {
-    core.warning(
-      `Failed to upload artifact zip to blob storage, error: ${error}`
-    )
-    return {
-      isSuccess: false
+    if (NetworkError.isNetworkErrorCode(error?.code)) {
+      throw new NetworkError(error?.code)
     }
+
+    throw error
   }
 
+  core.info('Finished uploading artifact content to blob storage!')
+
+  hashStream.end()
+  sha256Hash = hashStream.read() as string
+  core.info(`SHA256 hash of uploaded artifact zip is ${sha256Hash}`)
+
   if (uploadByteCount === 0) {
     core.warning(
-      `No data was uploaded to blob storage. Reported upload byte count is 0`
+      `No data was uploaded to blob storage. Reported upload byte count is 0.`
     )
-    return {
-      isSuccess: false
-    }
   }
 
   return {
-    isSuccess: true,
     uploadSize: uploadByteCount,
     sha256Hash
   }

packages/artifact/src/internal/upload/upload-artifact.ts

@@ -1,5 +1,8 @@
 import * as core from '@actions/core'
-import {UploadOptions, UploadResponse} from '../shared/interfaces'
+import {
+  UploadArtifactOptions,
+  UploadArtifactResponse
+} from '../shared/interfaces'
 import {getExpiration} from './retention'
 import {validateArtifactName} from './path-and-artifact-name-validation'
 import {internalArtifactTwirpClient} from '../shared/artifact-twirp-client'
@@ -16,13 +19,14 @@ import {
   FinalizeArtifactRequest,
   StringValue
 } from '../../generated'
+import {FilesNotFoundError, InvalidResponseError} from '../shared/errors'
 
 export async function uploadArtifact(
   name: string,
   files: string[],
   rootDirectory: string,
-  options?: UploadOptions | undefined
-): Promise<UploadResponse> {
+  options?: UploadArtifactOptions | undefined
+): Promise<UploadArtifactResponse> {
   validateArtifactName(name)
   validateRootDirectory(rootDirectory)
 
@@ -31,17 +35,11 @@ export async function uploadArtifact(
     rootDirectory
   )
   if (zipSpecification.length === 0) {
-    core.warning(`No files were found to upload`)
-    return {
-      success: false
-    }
+    throw new FilesNotFoundError(
+      zipSpecification.flatMap(s => (s.sourcePath ? [s.sourcePath] : []))
+    )
   }
 
-  const zipUploadStream = await createZipUploadStream(
-    zipSpecification,
-    options?.compressionLevel
-  )
-
   // get the IDs needed for the artifact creation
   const backendIds = getBackendIdsFromToken()
 
@@ -65,22 +63,21 @@ export async function uploadArtifact(
   const createArtifactResp =
     await artifactClient.CreateArtifact(createArtifactReq)
   if (!createArtifactResp.ok) {
-    core.warning(`Failed to create artifact`)
-    return {
-      success: false
-    }
+    throw new InvalidResponseError(
+      'CreateArtifact: response from backend was not ok'
+    )
   }
 
+  const zipUploadStream = await createZipUploadStream(
+    zipSpecification,
+    options?.compressionLevel
+  )
+
   // Upload zip to blob storage
   const uploadResult = await uploadZipToBlobStorage(
     createArtifactResp.signedUploadUrl,
     zipUploadStream
   )
-  if (uploadResult.isSuccess === false) {
-    return {
-      success: false
-    }
-  }
 
   // finalize the artifact
   const finalizeArtifactReq: FinalizeArtifactRequest = {
@@ -101,10 +98,9 @@ export async function uploadArtifact(
   const finalizeArtifactResp =
     await artifactClient.FinalizeArtifact(finalizeArtifactReq)
   if (!finalizeArtifactResp.ok) {
-    core.warning(`Failed to finalize artifact`)
-    return {
-      success: false
-    }
+    throw new InvalidResponseError(
+      'FinalizeArtifact: response from backend was not ok'
+    )
   }
 
   const artifactId = BigInt(finalizeArtifactResp.artifactId)
@@ -113,7 +109,6 @@ export async function uploadArtifact(
   )
 
   return {
-    success: true,
     size: uploadResult.uploadSize,
     id: Number(artifactId)
   }