@oneblink/apps-react 9.0.0-beta.2 → 9.0.0-beta.3

package/dist/apps/approvals-service.d.ts

@@ -0,0 +1,390 @@
+import { SubmissionTypes, ApprovalTypes, FormTypes } from '@oneblink/types';
+export type FormSubmissionApprovalsResponse = {
+    approvals: Array<{
+        formSubmissionApproval: ApprovalTypes.FormSubmissionApproval;
+        formApprovalFlowInstance: ApprovalTypes.FormApprovalFlowInstance;
+        formSubmissionMeta: SubmissionTypes.FormSubmissionMeta;
+        latestSuccessfulFormSubmissionPayment: SubmissionTypes.FormSubmissionPayment | undefined;
+    }>;
+};
+export type FormApprovalFlowInstanceHistory = {
+    formApprovalFlowInstance: ApprovalTypes.FormApprovalFlowInstance;
+    formSubmissionMeta: SubmissionTypes.FormSubmissionMeta;
+    formSubmissionApprovals: ApprovalTypes.FormSubmissionApproval[];
+    successfulFormSubmissionPayment?: SubmissionTypes.FormSubmissionPayment;
+};
+export type FormSubmissionApprovalResponse = {
+    formSubmissionMeta: SubmissionTypes.FormSubmissionMeta;
+    formApprovalFlowInstance: ApprovalTypes.FormApprovalFlowInstance;
+    formSubmissionApproval: ApprovalTypes.FormSubmissionApproval;
+    form: FormTypes.Form;
+    successfulFormSubmissionPayment?: SubmissionTypes.FormSubmissionPayment;
+    history: FormApprovalFlowInstanceHistory[];
+};
+export type FormSubmissionsAdministrationApprovalsResponse = {
+    approvals: Array<FormApprovalFlowInstanceHistory & {
+        history: Array<FormApprovalFlowInstanceHistory>;
+    }>;
+    meta: {
+        limit: number;
+        offset: number;
+        nextOffset?: number;
+    };
+};
+/**
+ * Get an Object containing FormSubmissionApprovals assigned to the current user
+ * and the Form definitions in those approvals.
+ *
+ * #### Example
+ *
+ * ```js
+ * const formsAppId = 1
+ * const {
+ *   formSubmissionApprovals,
+ *   formApprovalFlowInstances,
+ *   forms,
+ *   formSubmissionMeta,
+ * } = await approvalsService.getFormSubmissionApprovals(formAppId)
+ * ```
+ *
+ * @param formsAppId
+ * @param abortSignal
+ * @returns
+ */
+export declare function getFormSubmissionApprovals(formsAppId: number, abortSignal?: AbortSignal): Promise<FormSubmissionApprovalsResponse>;
+/**
+ * Get a single FormSubmissionApproval belonging to the given id.
+ *
+ * #### Example
+ *
+ * ```js
+ * const formSubmissionApprovalId = 'd27966cc-128d-48a2-b681-6ad52012e113'
+ * const {
+ *   formSubmissionApproval,
+ *   formApprovalFlowInstance,
+ *   formSubmissionMeta,
+ *   form,
+ *   history,
+ * } = await approvalsService.getFormSubmissionApproval(
+ *   formSubmissionApprovalId,
+ * )
+ * ```
+ *
+ * @param formSubmissionApprovalId
+ * @param abortSignal
+ * @returns
+ */
+export declare function getFormSubmissionApproval(formSubmissionApprovalId: string, abortSignal?: AbortSignal): Promise<FormSubmissionApprovalResponse>;
+/**
+ * Update a single FormSubmissionApproval assigned to the current user.
+ *
+ * #### Example
+ *
+ * ```js
+ * const formSubmissionApproval = {
+ *   id: 'd27966cc-128d-48a2-b681-6ad52012e113',
+ *   status: 'APPROVED',
+ *   username: 'email@example.com',
+ *   formApprovalFlowInstanceId: 1,
+ *   notificationEmailAddress: 'email@example.com',
+ *   notes: 'Great work!!!',
+ *   internalNotes: 'It was not really that great...',
+ *   cannedResponseKey: 'my_canned_response_key',
+ *   createdAt: '2021-02-21T22:57:56.257Z',
+ *   updatedAt: '2021-02-21T22:57:56.257Z',
+ * }
+ * const updatedFormSubmissionApproval =
+ *   await approvalsService.updateFormSubmissionApproval(
+ *     formSubmissionApproval,
+ *   )
+ * ```
+ *
+ * @param formSubmissionApproval
+ * @param abortSignal
+ * @returns
+ */
+export declare function updateFormSubmissionApproval(formSubmissionApproval: ApprovalTypes.FormSubmissionApproval, abortSignal?: AbortSignal): Promise<ApprovalTypes.FormSubmissionApproval>;
+/**
+ * @deprecated Use "reopenFormApprovalFlowInstance()" instead
+ * @internal
+ */
+export declare const reopenFormSubmissionApproval: typeof reopenFormApprovalFlowInstance;
+/**
+ * As an administrator, reopen a submission that has been approved or denied.
+ *
+ * #### Example
+ *
+ * ```js
+ * await approvalsService.reopenFormApprovalFlowInstance({
+ *   formApprovalFlowInstanceId: 1,
+ *   notificationEmailAddress: 'email@example.com',
+ *   notes: 'Great work!!!',
+ *   internalNotes: 'It was not really that great...',
+ *   cannedResponseKey: 'my_canned_response_key',
+ * })
+ * ```
+ *
+ * @param options
+ * @param abortSignal
+ * @returns
+ */
+export declare function reopenFormApprovalFlowInstance({ formApprovalFlowInstanceId, ...payload }: {
+    formApprovalFlowInstanceId: number;
+    notificationEmailAddress: string;
+    notes: string;
+    internalNotes?: string;
+    cannedResponseKey?: string;
+}, abortSignal?: AbortSignal): Promise<ApprovalTypes.FormSubmissionApproval>;
+/**
+ * As an administrator, close a submission that has been approved.
+ *
+ * #### Example
+ *
+ * ```js
+ * await approvalsService.closeFormApprovalFlowInstance({
+ *   formApprovalFlowInstanceId: 1,
+ *   notificationEmailAddress: ['email@example.com'],
+ *   notes: 'Great work!!!',
+ *   internalNotes: 'It was not really that great...',
+ *   cannedResponseKey: 'my_canned_response_key',
+ * })
+ * ```
+ *
+ * @param options
+ * @param abortSignal
+ * @returns
+ */
+export declare function closeFormApprovalFlowInstance({ formApprovalFlowInstanceId, ...payload }: {
+    formApprovalFlowInstanceId: number;
+    notificationEmailAddress?: string[];
+    notes?: string;
+    internalNotes?: string;
+    cannedResponseKey?: string;
+}, abortSignal?: AbortSignal): Promise<ApprovalTypes.FormSubmissionApproval>;
+export type FormApprovalFlowResponse = {
+    forms: FormTypes.Form[];
+};
+export declare function getFormApprovalFlows(formsAppId: number, abortSignal?: AbortSignal): Promise<FormApprovalFlowResponse>;
+/**
+ * Get an Object containing approvals for the app regardless of approval groups
+ * and meta for paging. Must be an Approvals Administrator.
+ *
+ * #### Example
+ *
+ * ```js
+ * const formsAppId = 1
+ * const limit = 50
+ * const offset = 0
+ * const { approvals, meta } =
+ *   await approvalsService.getFormSubmissionAdministrationApprovals({
+ *     formAppId,
+ *     limit,
+ *     offset,
+ *   })
+ * ```
+ *
+ * @param options
+ * @param abortSignal
+ * @returns
+ */
+export declare function getFormSubmissionAdministrationApprovals({ formsAppId, ...rest }: {
+    formsAppId: number;
+    formId?: number;
+    externalId?: string;
+    submissionId?: string;
+    formApprovalFlowInstanceId?: number;
+    submittedAfterDateTime?: string;
+    submittedBeforeDateTime?: string;
+    limit: number;
+    offset: number;
+    statuses?: string[];
+    updatedAfterDateTime?: string;
+    updatedBeforeDateTime?: string;
+    lastUpdatedBy?: string[];
+    submissionTitle?: string;
+}, abortSignal?: AbortSignal): Promise<FormSubmissionsAdministrationApprovalsResponse>;
+export type FormApprovalUsernamesResponse = {
+    usernames: Array<{
+        username: string;
+    }>;
+};
+/**
+ * Get an array containing usernames that have updated approvals in the within
+ * the formsAppId associated with the passed `formsAppId`. Must be an Approvals
+ * Administrator.
+ *
+ * #### Example
+ *
+ * ```js
+ * const formsAppId = 1
+ * const { usernames } =
+ *   await approvalsService.getFormApprovalUsernames(formsAppId)
+ * ```
+ *
+ * @param formsAppId
+ * @param abortSignal
+ * @returns
+ */
+export declare function getFormApprovalUsernames(formsAppId: number, abortSignal?: AbortSignal): Promise<FormApprovalUsernamesResponse>;
+/**
+ * Create an additional note for a form submission approval.
+ *
+ * #### Example
+ *
+ * ```js
+ * const formSubmissionApprovalId = 'd96ff812-f263-4a66-868d-e259a1fe4157'
+ * const newFormSubmissionApprovalNote = {
+ *   note: 'this is my note',
+ * }
+ * const createdFormSubmissionApprovalNote =
+ *   await approvalsService.createApprovalAdditionalNote({
+ *     formSubmissionApprovalId,
+ *     newFormSubmissionApprovalNote,
+ *   })
+ * ```
+ *
+ * @param options
+ * @returns
+ */
+export declare function createApprovalAdditionalNote({ formSubmissionApprovalId, newFormSubmissionApprovalNote, abortSignal, }: {
+    formSubmissionApprovalId: string;
+    newFormSubmissionApprovalNote: ApprovalTypes.NewFormSubmissionApprovalNote;
+    abortSignal?: AbortSignal;
+}): Promise<ApprovalTypes.FormSubmissionApprovalNote>;
+/**
+ * Update an additional note for a form submission approval.
+ *
+ * #### Example
+ *
+ * ```js
+ * const formSubmissionApprovalId = 'd96ff812-f263-4a66-868d-e259a1fe4157'
+ * const formSubmissionApprovalNote = {
+ *   id: '1e84dee3-0dc0-4abe-b2cf-d15d62fd9d0b',
+ *   note: 'this is my note',
+ *   createdAt: '2022-06-24T03:16:34.696Z',
+ *   createdBy: {
+ *     username: 'user@domain.com',
+ *   },
+ *   updatedAt: '2022-06-24T03:16:34.696Z',
+ *   lastUpdatedBy: {
+ *     username: 'user@domain.com',
+ *   },
+ * }
+ * const updatedFormSubmissionApprovalNote =
+ *   await approvalsService.updateApprovalAdditionalNote({
+ *     formSubmissionApprovalId,
+ *     formSubmissionApprovalNote,
+ *   })
+ * ```
+ *
+ * @param options
+ * @returns
+ */
+export declare function updateApprovalAdditionalNote({ formSubmissionApprovalId, formSubmissionApprovalNote, abortSignal, }: {
+    formSubmissionApprovalId: string;
+    formSubmissionApprovalNote: ApprovalTypes.FormSubmissionApprovalNote;
+    abortSignal?: AbortSignal;
+}): Promise<ApprovalTypes.FormSubmissionApprovalNote>;
+/**
+ * Delete an additional note for a form submission approval.
+ *
+ * #### Example
+ *
+ * ```js
+ * const formSubmissionApprovalId = 'd96ff812-f263-4a66-868d-e259a1fe4157'
+ * const formSubmissionApprovalNoteId = '1e84dee3-0dc0-4abe-b2cf-d15d62fd9d0b',
+ * const updatedFormSubmissionApprovalNote =
+ *   await approvalsService.deleteApprovalAdditionalNote({
+ *     formSubmissionApprovalId,
+ *     formSubmissionApprovalNoteId,
+ *   })
+ * ```
+ *
+ * @param options
+ * @returns
+ */
+export declare function deleteApprovalAdditionalNote({ formSubmissionApprovalId, formSubmissionApprovalNoteId, abortSignal, }: {
+    formSubmissionApprovalId: string;
+    formSubmissionApprovalNoteId: string;
+    abortSignal?: AbortSignal;
+}): Promise<void>;
+/**
+ * Get the status of a single FormSubmissionApproval for the given id.
+ *
+ * #### Example
+ *
+ * ```js
+ * const formSubmissionApprovalId = 'd27966cc-128d-48a2-b681-6ad52012e113'
+ * const { status } =
+ *   await approvalsService.getFormSubmissionApprovalStatus(
+ *     formSubmissionApprovalId,
+ *   )
+ * ```
+ *
+ * @param formSubmissionApprovalId
+ * @param abortSignal
+ * @returns
+ */
+export declare function getFormSubmissionApprovalStatus(formSubmissionApprovalId: string, abortSignal?: AbortSignal): Promise<{
+    status: ApprovalTypes.NewFormSubmissionApproval['status'];
+}>;
+/**
+ * Inputs a form approval flow instance and set of form submission approvals and
+ * returns a flattened array of nodes/steps with inlcuded metadata.
+ *
+ * #### Example
+ *
+ * ```js
+ * const formApprovalFlowInstance = {
+ *   steps: [
+ *     {
+ *       type: 'STANDARD',
+ *       group: 'oneblink:administrator',
+ *       isSkipped: false,
+ *       label: 'Manager Approval',
+ *       approvalFormId: '1234',
+ *     },
+ *     {
+ *       type: 'CONCURRENT',
+ *       nodes: [
+ *         {
+ *           label: 'HR Review',
+ *           group: 'oneblink:administrator',
+ *           isSkipped: false,
+ *           approvalFormId: '1234',
+ *         },
+ *         {
+ *           label: 'Finance Review',
+ *           group: 'oneblink:administrator',
+ *           isSkipped: false,
+ *           approvalFormId: '1234',
+ *         },
+ *       ],
+ *     },
+ *   ],
+ * }
+ *
+ * const formSubmissionApprovals = [
+ *   {
+ *     id: 'approval1',
+ *     stepLabel: 'Manager Approval',
+ *     status: 'APPROVED',
+ *     createdAt: '2024-03-20T10:00:00Z',
+ *     updatedAt: '2024-03-20T10:00:00Z',
+ *     updatedBy: 'fake@fake.com',
+ *     group: 'oneblink:administrator',
+ *     approvalFormId: '1234',
+ *   },
+ * ]
+ *
+ * const nodesWithMeta = getFlowInstanceNodesWithMeta(
+ *   formApprovalFlowInstance,
+ *   formSubmissionApprovals,
+ * )
+ * ```
+ *
+ * @param formApprovalFlowInstance
+ * @param formSubmissionApprovals
+ * @returns ApprovalTypes.FlowInstanceNodeWithMeta[]
+ */
+export declare function getFlowInstanceNodesWithMeta(formApprovalFlowInstance: ApprovalTypes.FormApprovalFlowInstance, formSubmissionApprovals: ApprovalTypes.FormSubmissionApproval[]): ApprovalTypes.FlowInstanceNodeWithMeta[];