feat: add all required methods to create vouchers

Author: leMaik

src/SevdeskApiClient.ts

@@ -1,3 +1,12 @@
+import {
+  SavedVoucher,
+  CreateVoucherPayload,
+  ExtractedVoucherInformation,
+  TemporaryVoucherFile,
+  VoucherCreditDebit,
+  VoucherTaxRule,
+} from './types/voucher';
+
 /**
  * A client for the sevdesk API.
  * @link https://api.sevdesk.de/
@@ -25,9 +34,77 @@ export default class XentralApiClient {
    * @returns The bookkeeping system version
    */
   getBookkeepingSystemVersion(): Promise<{ version: '1.0' | '2.0' }> {
-    return this.apiRequest('/Tools/bookkeepingSystemVersion')
-      .then((res) => res.json())
-      .then(({ objects }) => objects);
+    return this.apiRequest('/Tools/bookkeepingSystemVersion').then(
+      extractObjectsFromRes,
+    );
+  }
+  //#endregion
+
+  //#region Voucher
+  /**
+   * Upload a PDF file for creating a voucher.
+   * @param file.blob PDF blob
+   * @param file.filename PDF filename
+   * @returns Temporary voucher file to be used with {@link extractVoucherInformationFromPdf} or {@link createVoucher}
+   */
+  uploadTemporaryVoucherFile({
+    blob,
+    filename,
+  }: {
+    blob: Blob;
+    filename: string;
+  }): Promise<TemporaryVoucherFile> {
+    const body = new FormData();
+    body.append('file', blob, filename);
+    return this.apiRequest('/Voucher/Factory/uploadTempFile', {
+      method: 'POST',
+      body,
+    }).then(extractObjectsFromRes);
+  }
+
+  /**
+   * Extract voucher information from a previously uploaded voucher file.
+   * @param temporaryVoucherFile Temporary voucher file previously created using {@link uploadTemporaryVoucherFile}
+   * @returns Extracted voucher information
+   */
+  extractVoucherInformationFromPdf(
+    temporaryVoucherFile: Pick<TemporaryVoucherFile, 'filename' | 'mimeType'>,
+  ): Promise<ExtractedVoucherInformation> {
+    const body = new FormData();
+    body.append('fileName', temporaryVoucherFile.filename);
+    body.append('mimeType', temporaryVoucherFile.mimeType);
+    return this.apiRequest('/Voucher/Factory/createFromPdf', {
+      method: 'POST',
+      body: body,
+    }).then(extractObjectsFromRes);
+  }
+
+  /**
+   * Create a new voucher.
+   * @param voucher Voucher information
+   * @returns The created voucher
+   */
+  createVoucher(voucher: CreateVoucherPayload): Promise<SavedVoucher> {
+    return this.apiRequest('/Voucher/Factory/saveVoucher', {
+      method: 'POST',
+      body: JSON.stringify(voucher),
+      headers: {
+        'Content-Type': 'application/json',
+      },
+    }).then(extractObjectsFromRes);
+  }
+
+  /**
+   * Get the default tax rule for vouchers.
+   * Only applies to Sevdesk 2.0 (check with {@link getBookkeepingSystemVersion}).
+   * @param voucherType Voucher type
+   */
+  getDefaultVoucherTaxRule(
+    voucherType: VoucherCreditDebit,
+  ): Promise<VoucherTaxRule> {
+    return this.apiRequest(
+      `/Voucher/Factory/getDefaultTaxRule?voucherType=${voucherType}`,
+    ).then(extractObjectsFromRes);
   }
   //#endregion
 
@@ -74,3 +151,7 @@ export default class XentralApiClient {
     });
   }
 }
+
+function extractObjectsFromRes(res: Response) {
+  return res.json().then(({ objects }) => objects);
+}

src/helpers.ts

@@ -0,0 +1,24 @@
+import { MixedNumber, NumericBoolean } from './types/common';
+
+export function parseNumber(number: MixedNumber): number {
+  if (typeof number === 'number') {
+    return number;
+  }
+  return parseFloat(number);
+}
+
+export function parseOptionalNumber(
+  number: MixedNumber | null | undefined,
+): number | null {
+  if (number == null) {
+    return null;
+  }
+  if (typeof number === 'number') {
+    return number;
+  }
+  return parseFloat(number);
+}
+
+export function parseBoolean(boolean: NumericBoolean): boolean {
+  return boolean === '1';
+}

src/index.ts

@@ -1 +1,2 @@
 export { default } from './SevdeskApiClient';
+export * from './helpers';

src/types/common.ts

@@ -0,0 +1,8 @@
+export interface ObjectReference<T extends string> {
+  id: string | number;
+  objectName: T;
+}
+
+export type NumericBoolean = '1' | '0';
+
+export type MixedNumber = string | number;