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
-and package registry details and creates a storage record on behalf of the artifact.
-The storage record contains metadata about where the artifact is stored on a given
-package registry.
+The `createStorageRecord` function creates an
+[artifact metadata storage record](https://docs.github.com/en/rest/orgs/artifact-metadata?apiVersion=2022-11-28#create-artifact-metadata-storage-record)
+on behalf of an attested artifact. It accepts parameters defining artifact
+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