@silkline/paramify 0.0.2

package/src/resources/evidence/artifacts.ts

@@ -0,0 +1,682 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import { APIPromise } from '../../core/api-promise';
+import { type Uploadable } from '../../core/uploads';
+import { buildHeaders } from '../../internal/headers';
+import { RequestOptions } from '../../internal/request-options';
+import { multipartFormRequestOptions } from '../../internal/uploads';
+import { path } from '../../internal/utils/path';
+
+export class Artifacts extends APIResource {
+  /**
+   * Retrieves a specific artifact by ID.
+   *
+   * @example
+   * ```ts
+   * const artifact = await client.evidence.artifacts.retrieve(
+   *   '123e4567-e89b-12d3-a456-426614174000',
+   *   { evidenceId: '123e4567-e89b-12d3-a456-426614174000' },
+   * );
+   * ```
+   */
+  retrieve(
+    artifactID: string,
+    params: ArtifactRetrieveParams,
+    options?: RequestOptions,
+  ): APIPromise<ArtifactRetrieveResponse> {
+    const { evidenceId } = params;
+    return this._client.get(path`/evidence/${evidenceId}/artifacts/${artifactID}`, options);
+  }
+
+  /**
+   * Update a specific artifact by ID. You can modify the title, note, and effective
+   * date of an artifact without changing the underlying file or URL. Only the fields
+   * provided in the request body will be updated.
+   *
+   * @example
+   * ```ts
+   * const artifact = await client.evidence.artifacts.update(
+   *   '123e4567-e89b-12d3-a456-426614174000',
+   *   { evidenceId: '123e4567-e89b-12d3-a456-426614174000' },
+   * );
+   * ```
+   */
+  update(
+    artifactID: string,
+    params: ArtifactUpdateParams,
+    options?: RequestOptions,
+  ): APIPromise<ArtifactUpdateResponse> {
+    const { evidenceId, ...body } = params;
+    return this._client.patch(path`/evidence/${evidenceId}/artifacts/${artifactID}`, { body, ...options });
+  }
+
+  /**
+   * Retrieves all artifacts associated with a specific evidence record. Artifacts
+   * are digital files, documents, or URL references that support and validate
+   * evidence.
+   *
+   * @example
+   * ```ts
+   * const artifacts = await client.evidence.artifacts.list(
+   *   '123e4567-e89b-12d3-a456-426614174000',
+   * );
+   * ```
+   */
+  list(
+    evidenceID: string,
+    query: ArtifactListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<ArtifactListResponse> {
+    return this._client.get(path`/evidence/${evidenceID}/artifacts`, { query, ...options });
+  }
+
+  /**
+   * Delete a specific artifact by ID. This operation cannot be undone. If the
+   * artifact is a file upload, the file will be removed from storage. If it is a URL
+   * artifact, the reference will be deleted. Use this endpoint carefully as it is
+   * irreversible.
+   *
+   * @example
+   * ```ts
+   * await client.evidence.artifacts.delete(
+   *   '123e4567-e89b-12d3-a456-426614174000',
+   *   { evidenceId: '123e4567-e89b-12d3-a456-426614174000' },
+   * );
+   * ```
+   */
+  delete(artifactID: string, params: ArtifactDeleteParams, options?: RequestOptions): APIPromise<void> {
+    const { evidenceId } = params;
+    return this._client.delete(path`/evidence/${evidenceId}/artifacts/${artifactID}`, {
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+
+  /**
+   * Creates an artifact from a URL reference and associates it with the specified
+   * evidence record. The URL artifact will maintain the link to the external
+   * resource while storing relevant metadata such as title, notes, and effective
+   * date.
+   *
+   * @example
+   * ```ts
+   * const artifact = await client.evidence.artifacts.addURL(
+   *   '123e4567-e89b-12d3-a456-426614174000',
+   *   {
+   *     pathName:
+   *       'https://docs.company.com/security/policies/access-control',
+   *   },
+   * );
+   * ```
+   */
+  addURL(evidenceID: string, body: ArtifactAddURLParams, options?: RequestOptions): APIPromise<Artifact> {
+    return this._client.post(path`/evidence/${evidenceID}/artifacts/url`, { body, ...options });
+  }
+
+  /**
+   * Associates an artifact with a subject. The subject can be a control
+   * implementation. Artifacts can only be associated with control implementations on
+   * audit assessments, not with program control implementations.
+   *
+   * @example
+   * ```ts
+   * await client.evidence.artifacts.artifactAssociate(
+   *   '123e4567-e89b-12d3-a456-426614174000',
+   *   {
+   *     evidenceId: '123e4567-e89b-12d3-a456-426614174000',
+   *     associationType: 'CONNECT',
+   *     subjectId: '123e4567-e89b-12d3-a456-426614174000',
+   *     subjectType: 'CONTROL_IMPLEMENTATION',
+   *   },
+   * );
+   * ```
+   */
+  artifactAssociate(
+    artifactID: string,
+    params: ArtifactArtifactAssociateParams,
+    options?: RequestOptions,
+  ): APIPromise<void> {
+    const { evidenceId, ...body } = params;
+    return this._client.post(path`/evidence/${evidenceId}/artifacts/${artifactID}/associate`, {
+      body,
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+
+  /**
+   * Uploads a file as an artifact and associates it with the specified evidence
+   * record. The uploaded file will be securely stored and made available for future
+   * reference. Maximum file size: 10 GB.
+   *
+   * @example
+   * ```ts
+   * const artifact = await client.evidence.artifacts.upload(
+   *   '123e4567-e89b-12d3-a456-426614174000',
+   *   {
+   *     artifact: {},
+   *     file: fs.createReadStream('path/to/file'),
+   *   },
+   * );
+   * ```
+   */
+  upload(evidenceID: string, body: ArtifactUploadParams, options?: RequestOptions): APIPromise<Artifact> {
+    return this._client.post(
+      path`/evidence/${evidenceID}/artifacts/upload`,
+      multipartFormRequestOptions({ body, ...options }, this._client),
+    );
+  }
+}
+
+/**
+ * Complete artifact object containing all metadata, file information, and creation
+ * details. Artifacts can be either uploaded files or URL references.
+ */
+export interface Artifact {
+  /**
+   * Unique identifier for the artifact
+   */
+  id: string;
+
+  /**
+   * ISO 8601 timestamp when the artifact was created in the system
+   */
+  createdAt: string;
+
+  /**
+   * Information about the user who created the artifact
+   */
+  createdBy: Artifact.CreatedBy;
+
+  /**
+   * Indicates the artifact type: true for URL artifacts, false for uploaded file
+   * artifacts
+   */
+  isUrl: boolean;
+
+  /**
+   * For file artifacts: the direct URL to retrieve the stored file. This link may
+   * expire after about 60 minutes; request the artifact again to get a new link. For
+   * URL artifacts: this is the full external URL to the resource.
+   */
+  pathname: string;
+
+  /**
+   * Display title of the artifact. For file uploads, this defaults to the original
+   * filename if not provided during creation.
+   */
+  title: string;
+
+  /**
+   * Information about the validators that have run or are running on the artifact
+   */
+  validators: Array<Artifact.Validator>;
+
+  /**
+   * The date when this artifact was effective or relevant. This may differ from
+   * createdAt and represents when the data was actually valid.
+   */
+  effectiveDate?: string;
+
+  /**
+   * MIME type of the file (e.g., application/pdf, image/png). This field is null for
+   * URL artifacts.
+   */
+  fileType?: string | null;
+
+  /**
+   * Additional notes or comments about the artifact. Can be null if no note was
+   * provided.
+   */
+  note?: string | null;
+
+  /**
+   * The original filename when the artifact was uploaded. This field is null for URL
+   * artifacts.
+   */
+  originalFileName?: string | null;
+}
+
+export namespace Artifact {
+  /**
+   * Information about the user who created the artifact
+   */
+  export interface CreatedBy {
+    email: string | null;
+
+    username: string | null;
+  }
+
+  export interface Validator {
+    id: string | null;
+
+    name: string;
+
+    result: 'PASS' | 'FAIL' | 'NOT_SET' | 'ERROR' | null;
+  }
+}
+
+/**
+ * Schema for updating artifact metadata. All fields are optional - only include
+ * the fields you want to update. The underlying file or URL cannot be changed
+ * through this endpoint.
+ */
+export interface PatchArtifact {
+  /**
+   * Update the effective date of the artifact. Set to null to remove the effective
+   * date, or provide a new date to update it.
+   */
+  effectiveDate?: string | null;
+
+  /**
+   * Update the note or comments for the artifact. This will replace the existing
+   * note with the new value.
+   */
+  note?: string;
+
+  /**
+   * Update the title of the artifact. This will replace the existing title with the
+   * new value.
+   */
+  title?: string;
+}
+
+/**
+ * Schema for creating new URL artifacts. The pathName field is required and must
+ * be a valid URL. All other fields are optional.
+ */
+export interface PostURLArtifact {
+  /**
+   * The complete URL to the external resource. Must be a valid URL starting with
+   * http:// or https://
+   */
+  pathName: string;
+
+  /**
+   * The date when this URL artifact was effective or relevant. This represents when
+   * the content at the URL was valid or applicable. If not provided, defaults to the
+   * current date.
+   */
+  effectiveDate?: string | null;
+
+  /**
+   * Additional notes or comments about the URL artifact. Use this to explain what
+   * the URL contains or why it is relevant to the evidence.
+   */
+  note?: string | null;
+
+  /**
+   * A descriptive title for the URL artifact. If not provided, the URL domain will
+   * be used as the title.
+   */
+  title?: string | null;
+}
+
+/**
+ * Schema for creating new file artifacts. All fields are optional - you can upload
+ * a file with minimal metadata and enhance it later.
+ */
+export interface UploadArtifact {
+  /**
+   * The date when this artifact was effective or relevant. This may differ from the
+   * upload date and represents when the data or document was actually valid. If not
+   * provided, defaults to the current date.
+   */
+  effectiveDate?: string;
+
+  /**
+   * Additional notes or comments about the artifact. Use this field to provide
+   * context, explanations, or any relevant information about the artifact.
+   */
+  note?: string;
+
+  /**
+   * A descriptive title for the artifact. If not provided, the original filename
+   * will be used as the title.
+   */
+  title?: string;
+}
+
+/**
+ * The single artifact object with detailed metadata and file information
+ */
+export interface ArtifactRetrieveResponse {
+  /**
+   * Unique identifier for the artifact
+   */
+  id: string;
+
+  /**
+   * ISO 8601 timestamp when the artifact was created in the system
+   */
+  createdAt: string;
+
+  /**
+   * Information about the user who created the artifact
+   */
+  createdBy: ArtifactRetrieveResponse.CreatedBy;
+
+  /**
+   * Indicates the artifact type: true for URL artifacts, false for uploaded file
+   * artifacts
+   */
+  isUrl: boolean;
+
+  /**
+   * For file artifacts: the direct URL to retrieve the stored file. This link may
+   * expire after about 60 minutes; request the artifact again to get a new link. For
+   * URL artifacts: this is the full external URL to the resource.
+   */
+  pathname: string;
+
+  /**
+   * Display title of the artifact. For file uploads, this defaults to the original
+   * filename if not provided during creation.
+   */
+  title: string;
+
+  /**
+   * Information about the validators that have run or are running on the artifact
+   */
+  validators: Array<ArtifactRetrieveResponse.Validator>;
+
+  /**
+   * The date when this artifact was effective or relevant. This may differ from
+   * createdAt and represents when the data was actually valid.
+   */
+  effectiveDate?: string;
+
+  /**
+   * MIME type of the file (e.g., application/pdf, image/png). This field is null for
+   * URL artifacts.
+   */
+  fileType?: string | null;
+
+  /**
+   * Additional notes or comments about the artifact. Can be null if no note was
+   * provided.
+   */
+  note?: string | null;
+
+  /**
+   * The original filename when the artifact was uploaded. This field is null for URL
+   * artifacts.
+   */
+  originalFileName?: string | null;
+}
+
+export namespace ArtifactRetrieveResponse {
+  /**
+   * Information about the user who created the artifact
+   */
+  export interface CreatedBy {
+    email: string | null;
+
+    username: string | null;
+  }
+
+  export interface Validator {
+    id: string | null;
+
+    name: string;
+
+    result: 'PASS' | 'FAIL' | 'NOT_SET' | 'ERROR' | null;
+  }
+}
+
+/**
+ * The artifact as it exists after the update operation, including all current
+ * metadata
+ */
+export interface ArtifactUpdateResponse {
+  /**
+   * Unique identifier for the artifact
+   */
+  id: string;
+
+  /**
+   * ISO 8601 timestamp when the artifact was created in the system
+   */
+  createdAt: string;
+
+  /**
+   * Information about the user who created the artifact
+   */
+  createdBy: ArtifactUpdateResponse.CreatedBy;
+
+  /**
+   * Indicates the artifact type: true for URL artifacts, false for uploaded file
+   * artifacts
+   */
+  isUrl: boolean;
+
+  /**
+   * For file artifacts: the direct URL to retrieve the stored file. This link may
+   * expire after about 60 minutes; request the artifact again to get a new link. For
+   * URL artifacts: this is the full external URL to the resource.
+   */
+  pathname: string;
+
+  /**
+   * Display title of the artifact. For file uploads, this defaults to the original
+   * filename if not provided during creation.
+   */
+  title: string;
+
+  /**
+   * Information about the validators that have run or are running on the artifact
+   */
+  validators: Array<ArtifactUpdateResponse.Validator>;
+
+  /**
+   * The date when this artifact was effective or relevant. This may differ from
+   * createdAt and represents when the data was actually valid.
+   */
+  effectiveDate?: string;
+
+  /**
+   * MIME type of the file (e.g., application/pdf, image/png). This field is null for
+   * URL artifacts.
+   */
+  fileType?: string | null;
+
+  /**
+   * Additional notes or comments about the artifact. Can be null if no note was
+   * provided.
+   */
+  note?: string | null;
+
+  /**
+   * The original filename when the artifact was uploaded. This field is null for URL
+   * artifacts.
+   */
+  originalFileName?: string | null;
+}
+
+export namespace ArtifactUpdateResponse {
+  /**
+   * Information about the user who created the artifact
+   */
+  export interface CreatedBy {
+    email: string | null;
+
+    username: string | null;
+  }
+
+  export interface Validator {
+    id: string | null;
+
+    name: string;
+
+    result: 'PASS' | 'FAIL' | 'NOT_SET' | 'ERROR' | null;
+  }
+}
+
+export interface ArtifactListResponse {
+  /**
+   * Array of artifact objects matching the filter criteria
+   */
+  artifacts: Array<Artifact>;
+}
+
+export interface ArtifactRetrieveParams {
+  /**
+   * An id that represents an evidence within the Paramify application.
+   */
+  evidenceId: string;
+}
+
+export interface ArtifactUpdateParams {
+  /**
+   * Path param: An id that represents an evidence within the Paramify application.
+   */
+  evidenceId: string;
+
+  /**
+   * Body param: Update the effective date of the artifact. Set to null to remove the
+   * effective date, or provide a new date to update it.
+   */
+  effectiveDate?: string | null;
+
+  /**
+   * Body param: Update the note or comments for the artifact. This will replace the
+   * existing note with the new value.
+   */
+  note?: string;
+
+  /**
+   * Body param: Update the title of the artifact. This will replace the existing
+   * title with the new value.
+   */
+  title?: string;
+}
+
+export interface ArtifactListParams {
+  /**
+   * Filter artifacts by specific artifact IDs. Multiple IDs can be provided to fetch
+   * several artifacts in a single request.
+   */
+  id?: Array<string>;
+
+  /**
+   * Filter artifacts created on specific dates. Use this to find artifacts that were
+   * uploaded or created on particular dates. Date format should be YYYY-MM-DD.
+   * Multiple dates can be provided.
+   */
+  createdAt?: Array<string>;
+
+  /**
+   * Filter artifacts by their effective dates. The effective date represents when
+   * the artifact data was actually valid or captured, which may differ from the
+   * upload date. Multiple dates can be provided.
+   */
+  effectiveDate?: Array<string>;
+
+  /**
+   * Filter artifacts by type - whether they are URL references (true) or uploaded
+   * files (false). Use true to get only URL artifacts, false to get only file
+   * uploads.
+   */
+  isUrl?: boolean;
+
+  /**
+   * Filter artifacts by their original file names. Multiple file names can be
+   * provided to fetch several artifacts in a single request.
+   */
+  originalFileName?: Array<string>;
+}
+
+export interface ArtifactDeleteParams {
+  /**
+   * An id that represents an evidence within the Paramify application.
+   */
+  evidenceId: string;
+}
+
+export interface ArtifactAddURLParams {
+  /**
+   * The complete URL to the external resource. Must be a valid URL starting with
+   * http:// or https://
+   */
+  pathName: string;
+
+  /**
+   * The date when this URL artifact was effective or relevant. This represents when
+   * the content at the URL was valid or applicable. If not provided, defaults to the
+   * current date.
+   */
+  effectiveDate?: string | null;
+
+  /**
+   * Additional notes or comments about the URL artifact. Use this to explain what
+   * the URL contains or why it is relevant to the evidence.
+   */
+  note?: string | null;
+
+  /**
+   * A descriptive title for the URL artifact. If not provided, the URL domain will
+   * be used as the title.
+   */
+  title?: string | null;
+}
+
+export interface ArtifactArtifactAssociateParams {
+  /**
+   * Path param: An id that represents an evidence within the Paramify application.
+   */
+  evidenceId: string;
+
+  /**
+   * Body param: The type of association to make.
+   */
+  associationType: 'CONNECT' | 'DISCONNECT';
+
+  /**
+   * Body param: The ID of the subject to associate the artifact with.
+   */
+  subjectId: string;
+
+  /**
+   * Body param: The type of subject to associate the artifact with.
+   */
+  subjectType: 'CONTROL_IMPLEMENTATION';
+}
+
+export interface ArtifactUploadParams {
+  /**
+   * Schema for creating new file artifacts. All fields are optional - you can upload
+   * a file with minimal metadata and enhance it later.
+   */
+  artifact: UploadArtifact;
+
+  /**
+   * The file to be uploaded as an artifact. Any file type is supported. The original
+   * filename will be preserved and used as the default title if no title is
+   * specified in the metadata.
+   *
+   * **IMPORTANT**: Filenames containing certain special characters may cause upload
+   * errors. URL-encode your filename to avoid issues -- it will be decoded
+   * automatically.
+   */
+  file: Uploadable;
+}
+
+export declare namespace Artifacts {
+  export {
+    type Artifact as Artifact,
+    type PatchArtifact as PatchArtifact,
+    type PostURLArtifact as PostURLArtifact,
+    type UploadArtifact as UploadArtifact,
+    type ArtifactRetrieveResponse as ArtifactRetrieveResponse,
+    type ArtifactUpdateResponse as ArtifactUpdateResponse,
+    type ArtifactListResponse as ArtifactListResponse,
+    type ArtifactRetrieveParams as ArtifactRetrieveParams,
+    type ArtifactUpdateParams as ArtifactUpdateParams,
+    type ArtifactListParams as ArtifactListParams,
+    type ArtifactDeleteParams as ArtifactDeleteParams,
+    type ArtifactAddURLParams as ArtifactAddURLParams,
+    type ArtifactArtifactAssociateParams as ArtifactArtifactAssociateParams,
+    type ArtifactUploadParams as ArtifactUploadParams,
+  };
+}