@silkline/arena 1.0.0

package/src/resources/files/files.ts

@@ -0,0 +1,950 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import * as FilesAPI from './files';
+import * as ContentAPI from './content';
+import { Content, ContentUploadParams } from './content';
+import * as CorrectionsAPI from './corrections';
+import {
+  CorrectionCreateParams,
+  CorrectionListResponse,
+  CorrectionRetrieveParams,
+  Corrections,
+  FileCorrection,
+} from './corrections';
+import * as EditionsAPI from './editions';
+import { EditionCreateParams, EditionListResponse, Editions } from './editions';
+import * as MarkupsAPI from './markups';
+import {
+  FileAssociationMarkup,
+  FileMarkupCreate,
+  MarkupCreateParams,
+  MarkupDeleteParams,
+  MarkupDeleteResponse,
+  MarkupDownloadContentParams,
+  MarkupListResponse,
+  MarkupRetrieveParams,
+  MarkupUpdateContentParams,
+  MarkupUpdateParams,
+  Markups,
+} from './markups';
+import * as TrainingrecordsAPI from '../items/trainingrecords';
+import * as ItemsAPI from '../requests/items';
+import * as RequestsAPI from '../requests/requests';
+import * as TicketsAPI from '../tickets/tickets_';
+import { APIPromise } from '../../core/api-promise';
+import { Offset, type OffsetParams, PagePromise } from '../../core/pagination';
+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 Files extends APIResource {
+  markups: MarkupsAPI.Markups = new MarkupsAPI.Markups(this._client);
+  editions: EditionsAPI.Editions = new EditionsAPI.Editions(this._client);
+  corrections: CorrectionsAPI.Corrections = new CorrectionsAPI.Corrections(this._client);
+  content: ContentAPI.Content = new ContentAPI.Content(this._client);
+
+  /**
+   * Creates a new File object.
+   *
+   * If you wish to create a File record and upload file content to the Arena
+   * servers, construct a request that is content type
+   * <code>multipart/form-data</code> (specified in the header) and has a
+   * <code>storageMethodName</code> of <code>FILE</code> (stored on Arena servers).
+   *
+   * If you wish to create a File record with no uploaded content, construct a JSON
+   * request with a <code>storageMethodName</code> of <code>FTP</code> (stored on
+   * user FTP server), <code>WEB</code> (web link), or <code>PLACE_HOLDER</code>
+   * (will upload content later).
+   *
+   * When the storageMethod is <code>FTP</code> or <code>WEB</code>, the
+   * <code>location</code> attribute should be the web or ftp address where the file
+   * resides. For Files with <code>storageMethodName</code> <code>FILE</code>, the
+   * <code>location</code> attribute is not used.
+   *
+   * Currently, only Files less than 2GB can be uploaded through this endpoint.
+   */
+  create(body: FileCreateParams, options?: RequestOptions): APIPromise<FileDetail> {
+    return this._client.post('/files', multipartFormRequestOptions({ body, ...options }, this._client));
+  }
+
+  /**
+   * Returns a File object with a given GUID. This is the latest edition of the File.
+   */
+  retrieve(fileGuid: string, options?: RequestOptions): APIPromise<FileDetail> {
+    return this._client.get(path`/files/${fileGuid}`, options);
+  }
+
+  /**
+   * Updates a File object.
+   *
+   * Also supports updating <code>storageMethodName</code> from <code>FILE</code>,
+   * <code>FTP</code>, <code>WEB</code>, or <code>PLACE_HOLDER</code> to
+   * <code>FTP</code>, <code>WEB</code>, or <code>PLACE_HOLDER</code>. This update
+   * can only be performed on unlocked Files.
+   *
+   * Updating <code>storageMethodName</code> to <code>FTP</code>, <code>WEB</code>,
+   * or <code>PLACE_HOLDER</code> also requires including the attribute
+   * <code>location</code>.
+   *
+   * This endpoint does not support updating the <code>storageMethodName</code> from
+   * <code>FTP</code>, <code>WEB</code>, or <code>PLACE_HOLDER</code> to
+   * <code>FILE</code>. This requires a POST call. See POST File Update.
+   */
+  update(fileGuid: string, body: FileUpdateParams, options?: RequestOptions): APIPromise<FileDetail> {
+    return this._client.put(path`/files/${fileGuid}`, { body, ...options });
+  }
+
+  /**
+   * Returns a collection of Compact Files matching the given search criteria. The
+   * editions returned are the latest editions for each matching file.
+   */
+  list(
+    query: FileListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<FileListResponsesOffset, FileListResponse> {
+    return this._client.getAPIList('/files', Offset<FileListResponse>, { query, ...options });
+  }
+
+  /**
+   * Deletes the latest edition of a file with a given GUID. When a File has more
+   * than one edition, only the latest, unlocked edition can be deleted&mdash;to
+   * delete an entire file, repeat the DELETE request for all editions.
+   */
+  delete(fileGuid: string, options?: RequestOptions): APIPromise<string> {
+    return this._client.delete(path`/files/${fileGuid}`, options);
+  }
+
+  /**
+   * Only the user who checked out the File or an Account administrator can cancel
+   * the checkout.
+   *
+   * The existing edition of the File cannot be checked in if the edition is locked
+   * (for example, it is associated with an effective item).
+   *
+   * A new edition of the File can be checked in even if the existing edition is
+   * locked. Only Files of storageMethod <code>FILE</code> can be checked in.
+   *
+   * User must have a Full license to perform the File checkin. User must also have
+   * access to edit the File and full access to the File category.
+   */
+  checkin(body: FileCheckinParams, options?: RequestOptions): APIPromise<void> {
+    return this._client.post(
+      '/files/checkoutstatuschanges',
+      multipartFormRequestOptions(
+        { body, ...options, headers: buildHeaders([{ Accept: '*/*' }, options?.headers]) },
+        this._client,
+      ),
+    );
+  }
+
+  /**
+   * Returns the watermarked file with watermark data associated with the default
+   * item revision (the most recent revision).
+   */
+  downloadWatermarked(fileGuid: string, options?: RequestOptions): APIPromise<Response> {
+    return this._client.get(path`/files/${fileGuid}/watermarkcontent`, {
+      ...options,
+      headers: buildHeaders([{ Accept: 'application/octet-stream' }, options?.headers]),
+      __binaryResponse: true,
+    });
+  }
+
+  /**
+   * Retrieve detailed object information of the specified file association
+   */
+  retrieveAssociation(
+    fileAssociationGuid: string,
+    params: FileRetrieveAssociationParams,
+    options?: RequestOptions,
+  ): APIPromise<FileRetrieveAssociationResponse> {
+    const { fileGuid, objectType } = params;
+    return this._client.get(path`/files/${fileGuid}/${objectType}/${fileAssociationGuid}`, options);
+  }
+
+  /**
+   * Retrieve all file association object information for the specified file.
+   * Supports Item, Supplier Item, Supplier, Request, Quality Process, Change
+   * Reference, Change Implmenetation, Project, Ticket, and Training Plan objects.
+   */
+  retrieveAssociations(
+    objectType:
+      | 'supplieritems'
+      | 'suppliers'
+      | 'requests'
+      | 'qualityprocesses'
+      | 'changereferences'
+      | 'changeimplementations'
+      | 'projects'
+      | 'tickets'
+      | 'trainingplans',
+    params: FileRetrieveAssociationsParams,
+    options?: RequestOptions,
+  ): APIPromise<FileRetrieveAssociationsResponse> {
+    const { fileGuid } = params;
+    return this._client.get(path`/files/${fileGuid}/${objectType}`, options);
+  }
+
+  /**
+   * Retrieve detailed item information of the specified file association
+   */
+  retrieveItemAssociation(
+    fileItemAssociationGuid: string,
+    params: FileRetrieveItemAssociationParams,
+    options?: RequestOptions,
+  ): APIPromise<FileAssociationItem> {
+    const { fileGuid, objectType } = params;
+    return this._client.get(path`/files/${fileGuid}/${objectType}/${fileItemAssociationGuid}`, options);
+  }
+
+  /**
+   * Updates an existing File with <code>storageMethodName</code> <code>FTP</code>,
+   * <code>WEB</code>, or <code>PLACE_HOLDER</code> to <code>FILE</code>.
+   *
+   * To update an existing File with a <code>storageMethodName</code> of
+   * <code>FILE</code> to <code>FTP</code>, <code>WEB</code>, or
+   * <code>PLACE_HOLDER</code> please refer to the PUT File Summary Update endpoint.
+   *
+   * Construct a request with content-type <code>multipart/form-data</code> (in the
+   * header of the request) and file content.
+   *
+   * Currently, only Files less than 2GB can be uploaded through this endpoint.
+   */
+  upload(fileGuid: string, body: FileUploadParams, options?: RequestOptions): APIPromise<FileDetail> {
+    return this._client.post(
+      path`/files/${fileGuid}`,
+      multipartFormRequestOptions({ body, ...options }, this._client),
+    );
+  }
+}
+
+export type FileListResponsesOffset = Offset<FileListResponse>;
+
+export interface ChangeLite {
+  guid?: string;
+
+  number?: string;
+}
+
+export interface FileAssociationItem {
+  guid?: string;
+
+  items?: Array<ItemsAPI.ItemShort>;
+
+  primary?: boolean;
+}
+
+export interface FileAssociationProject {
+  guid?: string;
+
+  project?: FileAssociationProject.Project;
+}
+
+export namespace FileAssociationProject {
+  export interface Project {
+    guid?: string;
+
+    name?: string;
+
+    number?: string;
+
+    phase?: unknown;
+
+    task?: unknown;
+  }
+}
+
+export interface FileAssociationQuality {
+  guid?: string;
+
+  qualityProcess?: FileAssociationQuality.QualityProcess;
+}
+
+export namespace FileAssociationQuality {
+  export interface QualityProcess {
+    guid?: string;
+
+    number?: string;
+
+    step?: QualityProcess.Step;
+  }
+
+  export namespace QualityProcess {
+    export interface Step {
+      guid?: string;
+
+      name?: string;
+    }
+  }
+}
+
+export interface FileAssociationRequest {
+  guid?: string;
+
+  request?: RequestsAPI.RequestMinimal;
+}
+
+export interface FileAssociationSupplier {
+  guid?: string;
+
+  supplier?: SupplierCompact;
+}
+
+export interface FileAssociationTicket {
+  guid?: string;
+
+  ticket?: TicketsAPI.TicketMinimal;
+}
+
+export interface FileAssociationTraining {
+  guid?: string;
+
+  trainingplan?: TrainingrecordsAPI.TrainingMinimal;
+}
+
+export interface FileAuthor {
+  fullName?: string;
+}
+
+export interface FileCategory {
+  guid?: string;
+
+  name?: string;
+}
+
+/**
+ * Metadata and file information for uploading a file
+ */
+export interface FileCreateMetadata {
+  /**
+   * Author full name
+   */
+  'author.fullName'?: string;
+
+  /**
+   * Category GUID
+   */
+  'category.guid'?: string;
+
+  content?: Uploadable;
+
+  /**
+   * Description of the file
+   */
+  description?: string;
+
+  /**
+   * Edition of the file
+   */
+  edition?: string;
+
+  /**
+   * Format of the file
+   */
+  format?: string;
+
+  private?: boolean;
+
+  /**
+   * Storage method
+   */
+  storageMethodName?: string;
+
+  /**
+   * Title of the file
+   */
+  title?: string;
+}
+
+/**
+ * File metadata information
+ */
+export interface FileDetail {
+  author?: FileAuthor;
+
+  category?: FileCategory;
+
+  checkedOut?: boolean;
+
+  checkoutDateTime?: string;
+
+  corrected?: boolean;
+
+  creationDateTime?: string;
+
+  description?: string;
+
+  edition?: string;
+
+  format?: string;
+
+  googleDocs?: FileDetail.GoogleDocs;
+
+  guid?: string;
+
+  hasMarkup?: boolean;
+
+  haveContent?: boolean;
+
+  lastModifiedDateTime?: string;
+
+  latest?: boolean;
+
+  location?: string;
+
+  locked?: boolean;
+
+  microsoft365?: FileDetail.Microsoft365;
+
+  mimeType?: string;
+
+  name?: string;
+
+  number?: string;
+
+  private?: boolean;
+
+  size?: number;
+
+  storageMethodName?: string;
+
+  title?: string;
+}
+
+export namespace FileDetail {
+  export interface GoogleDocs {
+    authorEmail?: string;
+
+    creationDate?: string;
+
+    driveId?: string;
+
+    fileId?: string;
+
+    fileName?: string;
+
+    lastEditors?: Array<string>;
+
+    modifiedDate?: string;
+
+    originalAuthor?: string;
+
+    size?: number;
+
+    version?: string;
+
+    webUrl?: string;
+  }
+
+  export interface Microsoft365 {
+    authorEmail?: string;
+
+    creationDate?: string;
+
+    driveId?: string;
+
+    fileId?: string;
+
+    fileName?: string;
+
+    lastEditors?: Array<string>;
+
+    modifiedDate?: string;
+
+    originalAuthor?: string;
+
+    siteId?: string;
+
+    size?: number;
+
+    version?: string;
+
+    webUrl?: string;
+  }
+}
+
+export interface SupplierCompact {
+  guid?: string;
+
+  name?: string;
+}
+
+export interface FileListResponse {
+  category?: FileCategory;
+
+  checkedOut?: boolean;
+
+  corrected?: boolean;
+
+  creationDateTime?: string;
+
+  edition?: string;
+
+  format?: string;
+
+  guid?: string;
+
+  name?: string;
+
+  number?: string;
+
+  storageMethodName?: string;
+
+  title?: string;
+}
+
+export type FileDeleteResponse = string;
+
+export type FileRetrieveAssociationResponse =
+  | FileAssociationRequest
+  | FileAssociationSupplier
+  | unknown
+  | FileRetrieveAssociationResponse.FileAssociationChangeVo
+  | FileAssociationQuality
+  | FileAssociationProject
+  | FileAssociationTicket
+  | FileAssociationTraining;
+
+export namespace FileRetrieveAssociationResponse {
+  export interface FileAssociationChangeVo {
+    change?: FilesAPI.ChangeLite;
+
+    guid?: string;
+  }
+}
+
+export type FileRetrieveAssociationsResponse =
+  | FileRetrieveAssociationsResponse.FileAssociationItemVoResultRep
+  | FileRetrieveAssociationsResponse.FileAssociationRequestVoResultRep
+  | FileRetrieveAssociationsResponse.FileAssociationSupplierVoResultRep
+  | FileRetrieveAssociationsResponse.FileAssociationSupplierItemVoResultRep
+  | FileRetrieveAssociationsResponse.FileAssociationChangeVoResultRep
+  | FileRetrieveAssociationsResponse.FileAssociationQualityVoResultRep
+  | FileRetrieveAssociationsResponse.FileAssociationProjectVoResultRep
+  | FileRetrieveAssociationsResponse.FileAssociationTicketVoResultRep
+  | FileRetrieveAssociationsResponse.FileAssociationTrainingVoResultRep;
+
+export namespace FileRetrieveAssociationsResponse {
+  export interface FileAssociationItemVoResultRep {
+    count?: number;
+
+    results?: Array<FilesAPI.FileAssociationItem>;
+  }
+
+  export interface FileAssociationRequestVoResultRep {
+    count?: number;
+
+    results?: Array<FilesAPI.FileAssociationRequest>;
+  }
+
+  export interface FileAssociationSupplierVoResultRep {
+    count?: number;
+
+    results?: Array<FilesAPI.FileAssociationSupplier>;
+  }
+
+  export interface FileAssociationSupplierItemVoResultRep {
+    count?: number;
+
+    results?: Array<unknown>;
+  }
+
+  export interface FileAssociationChangeVoResultRep {
+    count?: number;
+
+    results?: Array<FilesAPI.ChangeLite>;
+  }
+
+  export interface FileAssociationQualityVoResultRep {
+    count?: number;
+
+    results?: Array<FilesAPI.FileAssociationQuality>;
+  }
+
+  export interface FileAssociationProjectVoResultRep {
+    count?: number;
+
+    results?: Array<FilesAPI.FileAssociationProject>;
+  }
+
+  export interface FileAssociationTicketVoResultRep {
+    count?: number;
+
+    results?: Array<FilesAPI.FileAssociationTicket>;
+  }
+
+  export interface FileAssociationTrainingVoResultRep {
+    count?: number;
+
+    results?: Array<FilesAPI.FileAssociationTraining>;
+  }
+}
+
+export interface FileCreateParams {
+  /**
+   * Author full name
+   */
+  'author.fullName'?: string;
+
+  /**
+   * Category GUID
+   */
+  'category.guid'?: string;
+
+  content?: Uploadable;
+
+  /**
+   * Description of the file
+   */
+  description?: string;
+
+  /**
+   * Edition of the file
+   */
+  edition?: string;
+
+  /**
+   * Format of the file
+   */
+  format?: string;
+
+  private?: boolean;
+
+  /**
+   * Storage method
+   */
+  storageMethodName?: string;
+
+  /**
+   * Title of the file
+   */
+  title?: string;
+}
+
+export interface FileUpdateParams {
+  author?: FileAuthor;
+
+  category?: FileCategory;
+
+  checkedOut?: boolean;
+
+  checkoutDateTime?: string;
+
+  corrected?: boolean;
+
+  creationDateTime?: string;
+
+  description?: string;
+
+  edition?: string;
+
+  format?: string;
+
+  googleDocs?: FileUpdateParams.GoogleDocs;
+
+  guid?: string;
+
+  hasMarkup?: boolean;
+
+  haveContent?: boolean;
+
+  lastModifiedDateTime?: string;
+
+  latest?: boolean;
+
+  location?: string;
+
+  locked?: boolean;
+
+  microsoft365?: FileUpdateParams.Microsoft365;
+
+  mimeType?: string;
+
+  name?: string;
+
+  number?: string;
+
+  private?: boolean;
+
+  size?: number;
+
+  storageMethodName?: string;
+
+  title?: string;
+}
+
+export namespace FileUpdateParams {
+  export interface GoogleDocs {
+    authorEmail?: string;
+
+    creationDate?: string;
+
+    driveId?: string;
+
+    fileId?: string;
+
+    fileName?: string;
+
+    lastEditors?: Array<string>;
+
+    modifiedDate?: string;
+
+    originalAuthor?: string;
+
+    size?: number;
+
+    version?: string;
+
+    webUrl?: string;
+  }
+
+  export interface Microsoft365 {
+    authorEmail?: string;
+
+    creationDate?: string;
+
+    driveId?: string;
+
+    fileId?: string;
+
+    fileName?: string;
+
+    lastEditors?: Array<string>;
+
+    modifiedDate?: string;
+
+    originalAuthor?: string;
+
+    siteId?: string;
+
+    size?: number;
+
+    version?: string;
+
+    webUrl?: string;
+  }
+}
+
+export interface FileListParams extends OffsetParams {
+  category?: FileListParams.Category;
+
+  /**
+   * file format
+   */
+  format?: string;
+
+  includeChildCategories?: boolean;
+
+  /**
+   * file name
+   */
+  name?: string;
+
+  /**
+   * file number
+   */
+  number?: string;
+
+  /**
+   * file title
+   */
+  title?: string;
+}
+
+export namespace FileListParams {
+  export interface Category {
+    /**
+     * category guid
+     */
+    guid?: string;
+  }
+}
+
+export interface FileCheckinParams {
+  checkedOut?: boolean;
+
+  comment?: string;
+
+  /**
+   * Author full name
+   */
+  'file.author.fullName'?: string;
+
+  /**
+   * Category GUID
+   */
+  'file.category.guid'?: string;
+
+  'file.content'?: Uploadable;
+
+  /**
+   * Description of the file
+   */
+  'file.description'?: string;
+
+  /**
+   * Edition of the file
+   */
+  'file.edition'?: string;
+
+  /**
+   * Format of the file
+   */
+  'file.format'?: string;
+
+  /**
+   * File GUID
+   */
+  'file.guid'?: string;
+
+  /**
+   * Storage method
+   */
+  'file.storageMethodName'?: string;
+
+  /**
+   * Title of the file
+   */
+  'file.title'?: string;
+
+  newEdition?: boolean;
+
+  private?: boolean;
+}
+
+export interface FileRetrieveAssociationParams {
+  fileGuid: string;
+
+  /**
+   * Type of the file association object
+   */
+  objectType:
+    | 'supplieritems'
+    | 'suppliers'
+    | 'requests'
+    | 'qualityprocesses'
+    | 'changereferences'
+    | 'changeimplementations'
+    | 'projects'
+    | 'tickets'
+    | 'trainingplans';
+}
+
+export interface FileRetrieveAssociationsParams {
+  fileGuid: string;
+}
+
+export interface FileRetrieveItemAssociationParams {
+  fileGuid: string;
+
+  objectType: string;
+}
+
+export interface FileUploadParams {
+  /**
+   * Author full name
+   */
+  'author.fullName'?: string;
+
+  /**
+   * Category GUID
+   */
+  'category.guid'?: string;
+
+  content?: Uploadable;
+
+  /**
+   * Description of the file
+   */
+  description?: string;
+
+  /**
+   * Edition of the file
+   */
+  edition?: string;
+
+  /**
+   * Format of the file
+   */
+  format?: string;
+
+  private?: boolean;
+
+  /**
+   * Storage method
+   */
+  storageMethodName?: string;
+
+  /**
+   * Title of the file
+   */
+  title?: string;
+}
+
+Files.Markups = Markups;
+Files.Editions = Editions;
+Files.Corrections = Corrections;
+Files.Content = Content;
+
+export declare namespace Files {
+  export {
+    type ChangeLite as ChangeLite,
+    type FileAssociationItem as FileAssociationItem,
+    type FileAssociationProject as FileAssociationProject,
+    type FileAssociationQuality as FileAssociationQuality,
+    type FileAssociationRequest as FileAssociationRequest,
+    type FileAssociationSupplier as FileAssociationSupplier,
+    type FileAssociationTicket as FileAssociationTicket,
+    type FileAssociationTraining as FileAssociationTraining,
+    type FileAuthor as FileAuthor,
+    type FileCategory as FileCategory,
+    type FileCreateMetadata as FileCreateMetadata,
+    type FileDetail as FileDetail,
+    type SupplierCompact as SupplierCompact,
+    type FileListResponse as FileListResponse,
+    type FileDeleteResponse as FileDeleteResponse,
+    type FileRetrieveAssociationResponse as FileRetrieveAssociationResponse,
+    type FileRetrieveAssociationsResponse as FileRetrieveAssociationsResponse,
+    type FileListResponsesOffset as FileListResponsesOffset,
+    type FileCreateParams as FileCreateParams,
+    type FileUpdateParams as FileUpdateParams,
+    type FileListParams as FileListParams,
+    type FileCheckinParams as FileCheckinParams,
+    type FileRetrieveAssociationParams as FileRetrieveAssociationParams,
+    type FileRetrieveAssociationsParams as FileRetrieveAssociationsParams,
+    type FileRetrieveItemAssociationParams as FileRetrieveItemAssociationParams,
+    type FileUploadParams as FileUploadParams,
+  };
+
+  export {
+    Markups as Markups,
+    type FileAssociationMarkup as FileAssociationMarkup,
+    type FileMarkupCreate as FileMarkupCreate,
+    type MarkupListResponse as MarkupListResponse,
+    type MarkupDeleteResponse as MarkupDeleteResponse,
+    type MarkupCreateParams as MarkupCreateParams,
+    type MarkupRetrieveParams as MarkupRetrieveParams,
+    type MarkupUpdateParams as MarkupUpdateParams,
+    type MarkupDeleteParams as MarkupDeleteParams,
+    type MarkupDownloadContentParams as MarkupDownloadContentParams,
+    type MarkupUpdateContentParams as MarkupUpdateContentParams,
+  };
+
+  export {
+    Editions as Editions,
+    type EditionListResponse as EditionListResponse,
+    type EditionCreateParams as EditionCreateParams,
+  };
+
+  export {
+    Corrections as Corrections,
+    type FileCorrection as FileCorrection,
+    type CorrectionListResponse as CorrectionListResponse,
+    type CorrectionCreateParams as CorrectionCreateParams,
+    type CorrectionRetrieveParams as CorrectionRetrieveParams,
+  };
+
+  export { Content as Content, type ContentUploadParams as ContentUploadParams };
+}