reorganize function options and document

Signed-off-by: Meredith Lancaster <[email protected]>

packages/attest/README.md

@@ -175,10 +175,71 @@ specification](https://github.com/sigstore/protobuf-specs/blob/main/protos/sigst
 
 ### createStorageRecord
 
-The `createStorageRecord` function accepts parameters defining artifact
+The `createStorageRecord` function creates an
-and package registry details and creates a storage record on behalf of the artifact.
+[artifact metadata storage record](https://docs.github.com/en/rest/orgs/artifact-metadata?apiVersion=2022-11-28#create-artifact-metadata-storage-record)
-The storage record contains metadata about where the artifact is stored on a given
+on behalf of an attested artifact. It accepts parameters defining artifact
-package registry.
+and package registry details. The storage record contains metadata about where the artifact is stored on a given package registry.
+
+```js
+const { createStorageRecord } = require('@actions/attest');
+const core = require('@actions/core');
+
+async function run() {
+    // In order to persist attestations to the repo, this should be a token with
+    // repository write permissions.
+    const ghToken = core.getInput('gh-token');
+
+    const record = await createStorageRecord({
+        name: 'my-artifact-name',
+        digest: { 'sha256': '36ab4667...'},
+        version: "v1.0.0",
+        registry_url: "https://my-fave-pkg-registry.com",
+        token: ghToken
+    });
+
+    console.log(record);
+}
+
+run();
+```
+
+The `createStorageRecord` function supports the following options:
+
+```typescript
+export type StorageRecordOptions = {
+  // Includes details about the attested artifact
+  artifactOptions: {
+    // The name of the artifact
+    name: string
+    // The digest of the artifact
+    digest: string
+    // The version of the artifact
+    version?: string
+    // The status of the artifact
+    status?: string
+  },
+  // Includes details about the package registry the artifact was published to
+  packageRegistryOptions: {
+    // The URL of the package registry
+    registryUrl: string
+    // The URL of the artifact in the package registry
+    artifactUrl?: string
+    // The package registry repository the artifact was published to.
+    repo?: string
+    // The path of the artifact in the package registry repository.
+    path?: string
+  },
+  // GitHub token for writing attestations.
+  token: string
+  // Optional parameters for the write operation.
+  writeOptions: {
+    // The number of times to retry the request.
+    retry?: number
+  // HTTP headers to include in request to Artifact Metadata API.
+    headers?: RequestHeaders
+  }
+}
+```
 
 ## Sigstore Instance
 

packages/attest/__tests__/artifactMetadata.test.ts

@@ -15,7 +15,6 @@ describe('createStorageRecord', () => {
     registryUrl: 'https://my-registry.org',
   }
 
-
   const mockAgent = new MockAgent()
   setGlobalDispatcher(mockAgent)
 
@@ -50,7 +49,12 @@ describe('createStorageRecord', () => {
 
     it('persists the storage record', async () => {
       await expect(
-        createStorageRecord(artifactParams, registryParams, token, {headers})
+        createStorageRecord({
+          artifactOptions: artifactParams,
+          packageRegistryOptions: registryParams,
+          token,
+          writeOptions: {headers},
+        })
       ).resolves.toEqual(['123', '456'])
     })
   })
@@ -75,7 +79,12 @@ describe('createStorageRecord', () => {
 
     it('throws an error', async () => {
       await expect(
-        createStorageRecord(artifactParams, registryParams, token, {retry: 0})
+        createStorageRecord({
+          artifactOptions: artifactParams,
+          packageRegistryOptions: registryParams,
+          token,
+          writeOptions: {retry: 0},
+        })
       ).rejects.toThrow(/oops/)
     })
   })
@@ -106,7 +115,12 @@ describe('createStorageRecord', () => {
     })
 
     it('persists the attestation', async () => {
-      await expect(createStorageRecord(artifactParams, registryParams, token)).resolves.toEqual(['123', '456'])
+      await expect(createStorageRecord({
+        artifactOptions: artifactParams,
+        packageRegistryOptions: registryParams,
+        token,
+        writeOptions: {},
+      })).resolves.toEqual(['123', '456'])
     })
   })
 })

packages/attest/src/artifactMetadata.ts

@@ -5,23 +5,41 @@ import {RequestHeaders} from '@octokit/types'
 const CREATE_STORAGE_RECORD_REQUEST = 'POST /orgs/{owner}/artifacts/metadata/storage-record'
 const DEFAULT_RETRY_COUNT = 5
 
-export type ArtifactParams = {
+/**
-  name: string
+ * Options for creating a storage record for an attested artifact.
-  digest: string
+ */
-  version?: string
+export type StorageRecordOptions = {
-  status?: string
+  // Includes details about the attested artifact
-}
+  artifactOptions: {
-
+    // The name of the artifact
-export type PackageRegistryParams = {
+    name: string
-  registryUrl: string
+    // The digest of the artifact
-  artifactUrl?: string
+    digest: string
-  repo?: string
+    // The version of the artifact
-  path?: string
+    version?: string
-}
+    // The status of the artifact
-
+    status?: string
-export type WriteOptions = {
+  },
-  retry?: number
+  // Includes details about the package registry the artifact was published to
-  headers?: RequestHeaders
+  packageRegistryOptions: {
+    // The URL of the package registry
+    registryUrl: string
+    // The URL of the artifact in the package registry
+    artifactUrl?: string
+    // The package registry repository the artifact was published to.
+    repo?: string
+    // The path of the artifact in the package registry repository.
+    path?: string
+  },
+  // GitHub token for writing attestations.
+  token: string
+  // Optional parameters for the write operation.
+  writeOptions: {
+    // The number of times to retry the request.
+    retry?: number
+  // HTTP headers to include in request to Artifact Metadata API.
+    headers?: RequestHeaders
+  }
 }
 
 /**
@@ -33,20 +51,15 @@ export type WriteOptions = {
  * @returns The ID of the storage record.
  * @throws Error if the storage record fails to persist.
  */
-export async function createStorageRecord(
+export async function createStorageRecord(options: StorageRecordOptions): Promise<Array<string>> {
-  artifactParams: ArtifactParams,
+  const retries = options.writeOptions.retry ?? DEFAULT_RETRY_COUNT
-  packageRegistryParams: PackageRegistryParams,
+  const octokit = github.getOctokit(options.token, {retry: {retries}}, retry)
-  token: string,
-  options: WriteOptions = {}
-): Promise<Array<string>> {
-  const retries = options.retry ?? DEFAULT_RETRY_COUNT
-  const octokit = github.getOctokit(token, {retry: {retries}}, retry)
 
   try {
     const response = await octokit.request(CREATE_STORAGE_RECORD_REQUEST, {
       owner: github.context.repo.owner,
-      headers: options.headers,
+      headers: options.writeOptions.headers,
-      ...buildRequestParams(artifactParams, packageRegistryParams),
+      ...buildRequestParams(options.artifactOptions, options.packageRegistryOptions),
     })
 
     const data =