@silkline/paramify 0.0.2

package/src/internal/utils/values.ts

@@ -0,0 +1,105 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { ParamifyError } from '../../core/error';
+
+// https://url.spec.whatwg.org/#url-scheme-string
+const startsWithSchemeRegexp = /^[a-z][a-z0-9+.-]*:/i;
+
+export const isAbsoluteURL = (url: string): boolean => {
+  return startsWithSchemeRegexp.test(url);
+};
+
+export let isArray = (val: unknown): val is unknown[] => ((isArray = Array.isArray), isArray(val));
+export let isReadonlyArray = isArray as (val: unknown) => val is readonly unknown[];
+
+/** Returns an object if the given value isn't an object, otherwise returns as-is */
+export function maybeObj(x: unknown): object {
+  if (typeof x !== 'object') {
+    return {};
+  }
+
+  return x ?? {};
+}
+
+// https://stackoverflow.com/a/34491287
+export function isEmptyObj(obj: Object | null | undefined): boolean {
+  if (!obj) return true;
+  for (const _k in obj) return false;
+  return true;
+}
+
+// https://eslint.org/docs/latest/rules/no-prototype-builtins
+export function hasOwn<T extends object = object>(obj: T, key: PropertyKey): key is keyof T {
+  return Object.prototype.hasOwnProperty.call(obj, key);
+}
+
+export function isObj(obj: unknown): obj is Record<string, unknown> {
+  return obj != null && typeof obj === 'object' && !Array.isArray(obj);
+}
+
+export const ensurePresent = <T>(value: T | null | undefined): T => {
+  if (value == null) {
+    throw new ParamifyError(`Expected a value to be given but received ${value} instead.`);
+  }
+
+  return value;
+};
+
+export const validatePositiveInteger = (name: string, n: unknown): number => {
+  if (typeof n !== 'number' || !Number.isInteger(n)) {
+    throw new ParamifyError(`${name} must be an integer`);
+  }
+  if (n < 0) {
+    throw new ParamifyError(`${name} must be a positive integer`);
+  }
+  return n;
+};
+
+export const coerceInteger = (value: unknown): number => {
+  if (typeof value === 'number') return Math.round(value);
+  if (typeof value === 'string') return parseInt(value, 10);
+
+  throw new ParamifyError(`Could not coerce ${value} (type: ${typeof value}) into a number`);
+};
+
+export const coerceFloat = (value: unknown): number => {
+  if (typeof value === 'number') return value;
+  if (typeof value === 'string') return parseFloat(value);
+
+  throw new ParamifyError(`Could not coerce ${value} (type: ${typeof value}) into a number`);
+};
+
+export const coerceBoolean = (value: unknown): boolean => {
+  if (typeof value === 'boolean') return value;
+  if (typeof value === 'string') return value === 'true';
+  return Boolean(value);
+};
+
+export const maybeCoerceInteger = (value: unknown): number | undefined => {
+  if (value == null) {
+    return undefined;
+  }
+  return coerceInteger(value);
+};
+
+export const maybeCoerceFloat = (value: unknown): number | undefined => {
+  if (value == null) {
+    return undefined;
+  }
+  return coerceFloat(value);
+};
+
+export const maybeCoerceBoolean = (value: unknown): boolean | undefined => {
+  if (value == null) {
+    return undefined;
+  }
+  return coerceBoolean(value);
+};
+
+export const safeJSON = (text: string) => {
+  try {
+    return JSON.parse(text);
+  } catch (err) {
+    return undefined;
+  }
+};

package/src/internal/utils.ts

@@ -0,0 +1,9 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export * from './utils/values';
+export * from './utils/base64';
+export * from './utils/env';
+export * from './utils/log';
+export * from './utils/uuid';
+export * from './utils/sleep';
+export * from './utils/query';

package/src/lib/.keep

@@ -0,0 +1,4 @@
+File generated from our OpenAPI spec by Stainless.
+
+This directory can be used to store custom files to expand the SDK.
+It is ignored by Stainless code generation and its content (other than this keep file) won't be touched.

package/src/resource.ts

@@ -0,0 +1,2 @@
+/** @deprecated Import from ./core/resource instead */
+export * from './core/resource';

package/src/resources/assessments/assessments.ts

@@ -0,0 +1,350 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import * as CyclesAPI from './cycles';
+import {
+  Cycle,
+  CycleIntakeParams,
+  CycleIntakeResponse,
+  CycleListParams,
+  CycleListResponse,
+  CycleRetrieveParams,
+  Cycles,
+} from './cycles';
+import * as ArtifactsAPI from '../evidence/artifacts';
+import { APIPromise } from '../../core/api-promise';
+import { type Uploadable } from '../../core/uploads';
+import { RequestOptions } from '../../internal/request-options';
+import { multipartFormRequestOptions } from '../../internal/uploads';
+import { path } from '../../internal/utils/path';
+
+export class Assessments extends APIResource {
+  cycles: CyclesAPI.Cycles = new CyclesAPI.Cycles(this._client);
+
+  /**
+   * Get a single vulnerability or configuration assessment, including all of its
+   * assessment cycles, by its internal id (UUID).
+   *
+   * @example
+   * ```ts
+   * const assessment = await client.assessments.retrieve(
+   *   '123e4567-e89b-12d3-a456-426614174000',
+   * );
+   * ```
+   */
+  retrieve(assessmentID: string, options?: RequestOptions): APIPromise<AssessmentRetrieveResponse> {
+    return this._client.get(path`/assessment/${assessmentID}`, options);
+  }
+
+  /**
+   * Get all vulnerability and configuration assessments, with all included
+   * assessment cycles, within a workspace. Assessments can be filtered by id,
+   * frequency, and type.
+   *
+   * @example
+   * ```ts
+   * const assessments = await client.assessments.list();
+   * ```
+   */
+  list(
+    query: AssessmentListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<AssessmentListResponse> {
+    return this._client.get('/assessment', { query, ...options });
+  }
+
+  /**
+   * ## Overview
+   *
+   * Uploads a CSV, XML, JSON, or Nessus file as an artifact and attaches it to the
+   * intake on a vulnerability or configuration assessment specified by the
+   * `assessmentId`. Only CSV, XML, JSON, and Nessus files are supported.
+   *
+   * Maximum file size: 10 GB.
+   *
+   * ### Effective Date Handling
+   *
+   * The effective date specified will be used to determine what cycle(s) to upload
+   * the artifact to. If no effective date is specified, the current date will be
+   * used as the effective date.
+   *
+   * ### Cycle Creation and Management
+   *
+   * The artifact will be added to the intake for each cycle on the assessment whose
+   * start and end date overlap the artifact's effective date. If no such cycle can
+   * be found, a new one will be created. The created cycle's start date will be the
+   * beginning of the effective date's month. The cycle's end date will be calculated
+   * based on the assessment's frequency.
+   *
+   * ### Evidence Handling
+   *
+   * If the intake on the cycle does not have an attached evidence, the evidence from
+   * the previous cycle's intake will be used. If there is no previous cycle, a new
+   * evidence will be created.
+   *
+   * ### Multiple Cycle Behavior
+   *
+   * If multiple cycles fall within the range of the artifact's effective date, the
+   * artifact will be attached to each cycle's intake. If the multiple cycle intakes
+   * have different evidences, one artifact will be created for each evidence.
+   *
+   * ### Existing Artifacts
+   *
+   * If any of the cycle intakes already have artifacts attached, the new artifact
+   * will be added without removing existing artifacts.
+   *
+   * @example
+   * ```ts
+   * const response = await client.assessments.intake(
+   *   '123e4567-e89b-12d3-a456-426614174000',
+   *   {
+   *     artifact: {},
+   *     file: fs.createReadStream('path/to/file'),
+   *   },
+   * );
+   * ```
+   */
+  intake(
+    assessmentID: string,
+    body: AssessmentIntakeParams,
+    options?: RequestOptions,
+  ): APIPromise<AssessmentIntakeResponse> {
+    return this._client.post(
+      path`/assessment/${assessmentID}/intake`,
+      multipartFormRequestOptions({ body, ...options }, this._client),
+    );
+  }
+}
+
+/**
+ * The assessment details with mechanism, target components, and cycles.
+ */
+export interface Assessment {
+  /**
+   * The internal UUID of the assessment. This id can be used as an `assessmentId` in
+   * other endpoints.
+   */
+  id: string;
+
+  /**
+   * The cycles associated with the assessment.
+   */
+  cycles: Array<CyclesAPI.Cycle>;
+
+  /**
+   * The frequency of the assessment.
+   */
+  frequency: 'MONTHLY' | 'QUARTERLY' | 'BIANNUALLY' | 'ANNUALLY' | null;
+
+  /**
+   * The component element used as the mechanism of the assessment.
+   */
+  mechanism: Assessment.Mechanism | null;
+
+  /**
+   * The name of the assessment.
+   */
+  name: string;
+
+  /**
+   * The human-readable reference identifier of the assessment.
+   */
+  referenceId: string | null;
+
+  /**
+   * The target component(s) assigned to the assessment.
+   */
+  targetComponents: Array<Assessment.TargetComponent>;
+
+  /**
+   * The type of assessment, either vulnerability or configuration (other assessment
+   * types are not supported).
+   */
+  type: 'VULNERABILITY' | 'CONFIGURATION';
+}
+
+export namespace Assessment {
+  /**
+   * The component element used as the mechanism of the assessment.
+   */
+  export interface Mechanism {
+    /**
+     * The internal UUID of the assessment mechanism.
+     */
+    id: string;
+
+    /**
+     * The name of the assessment mechanism.
+     */
+    name: string;
+  }
+
+  export interface TargetComponent {
+    /**
+     * The internal UUID of the target component.
+     */
+    id: string;
+
+    /**
+     * The name of the target component.
+     */
+    name: string;
+  }
+}
+
+/**
+ * The single assessment object, including all of its assessment cycles.
+ */
+export interface AssessmentRetrieveResponse {
+  /**
+   * The internal UUID of the assessment. This id can be used as an `assessmentId` in
+   * other endpoints.
+   */
+  id: string;
+
+  /**
+   * The cycles associated with the assessment.
+   */
+  cycles: Array<CyclesAPI.Cycle>;
+
+  /**
+   * The frequency of the assessment.
+   */
+  frequency: 'MONTHLY' | 'QUARTERLY' | 'BIANNUALLY' | 'ANNUALLY' | null;
+
+  /**
+   * The component element used as the mechanism of the assessment.
+   */
+  mechanism: AssessmentRetrieveResponse.Mechanism | null;
+
+  /**
+   * The name of the assessment.
+   */
+  name: string;
+
+  /**
+   * The human-readable reference identifier of the assessment.
+   */
+  referenceId: string | null;
+
+  /**
+   * The target component(s) assigned to the assessment.
+   */
+  targetComponents: Array<AssessmentRetrieveResponse.TargetComponent>;
+
+  /**
+   * The type of assessment, either vulnerability or configuration (other assessment
+   * types are not supported).
+   */
+  type: 'VULNERABILITY' | 'CONFIGURATION';
+}
+
+export namespace AssessmentRetrieveResponse {
+  /**
+   * The component element used as the mechanism of the assessment.
+   */
+  export interface Mechanism {
+    /**
+     * The internal UUID of the assessment mechanism.
+     */
+    id: string;
+
+    /**
+     * The name of the assessment mechanism.
+     */
+    name: string;
+  }
+
+  export interface TargetComponent {
+    /**
+     * The internal UUID of the target component.
+     */
+    id: string;
+
+    /**
+     * The name of the target component.
+     */
+    name: string;
+  }
+}
+
+export interface AssessmentListResponse {
+  /**
+   * Array of assessment objects, including all assessment cycles, matching the
+   * filter criteria. The `id` from each assessment can be used as an `assessmentId`
+   * in other endpoints.
+   */
+  assessments: Array<Assessment>;
+}
+
+/**
+ * An array of newly created artifacts. Typically only one artifact will be
+ * created, unless multiple assessment cycles overlap the effective date and have
+ * different evidences attached to their intakes. At least one artifact will always
+ * be created if the request was successful.
+ */
+export interface AssessmentIntakeResponse {
+  artifacts: Array<ArtifactsAPI.Artifact>;
+}
+
+export interface AssessmentListParams {
+  /**
+   * Filter assessments by id. If multiple ids are provided, multiple assessments
+   * will be returned.
+   */
+  id?: Array<string>;
+
+  /**
+   * Filter assessments by frequency. If multiple frequencies are provided,
+   * assessments with either frequency will be returned.
+   */
+  frequency?: Array<'MONTHLY' | 'QUARTERLY' | 'BIANNUALLY' | 'ANNUALLY'>;
+
+  /**
+   * Filter assessments by type, either vulnerability or configuration (other
+   * assessment types are not supported).
+   */
+  type?: Array<'CONFIGURATION' | 'VULNERABILITY'>;
+}
+
+export interface AssessmentIntakeParams {
+  /**
+   * Schema for creating new file artifacts. All fields are optional - you can upload
+   * a file with minimal metadata and enhance it later.
+   */
+  artifact: ArtifactsAPI.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;
+}
+
+Assessments.Cycles = Cycles;
+
+export declare namespace Assessments {
+  export {
+    type Assessment as Assessment,
+    type AssessmentRetrieveResponse as AssessmentRetrieveResponse,
+    type AssessmentListResponse as AssessmentListResponse,
+    type AssessmentIntakeResponse as AssessmentIntakeResponse,
+    type AssessmentListParams as AssessmentListParams,
+    type AssessmentIntakeParams as AssessmentIntakeParams,
+  };
+
+  export {
+    Cycles as Cycles,
+    type Cycle as Cycle,
+    type CycleListResponse as CycleListResponse,
+    type CycleIntakeResponse as CycleIntakeResponse,
+    type CycleRetrieveParams as CycleRetrieveParams,
+    type CycleListParams as CycleListParams,
+    type CycleIntakeParams as CycleIntakeParams,
+  };
+}