feat: ✨ added CsvOrder model + endpoints (#7)

* feat: ✨ added CsvOrder model + endpoints * docs: 📝 updated docs about CsvOrder * fix: PR feedback * chore: type error --------- Co-authored-by: Koen van Staveren <[email protected]>
Print-one · Feb 22, 2024 · 9deda48 · 9deda48
1 parent a1d6b6c
commit 9deda48
Show file tree

Hide file tree

Showing 10 changed files with 652 additions and 17 deletions.
diff --git a/docs/CsvOrder.md b/docs/CsvOrder.md
@@ -0,0 +1,98 @@
+Contains all information about a given CsvOrder
+
+# Fields
+
+| Name                  | Type                                 | Description                                                                                                                                                             |
+| --------------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`                  | `string`                             | The ID of the order.                                                                                                                                                    |
+| `templateId`          | `string`                             | The ID of the template the order is based on.                                                                                                                           |
+| `finish`              | `string`                             | The finish of the order. Can be `GLOSSY` or `MATT`.                                                                                                                     |
+| `format`              | `string`                             | The format of the order. Can be `POSTCARD_A5`, `POSTCARD_A6`, `POSTCARD_SQ14` or `GREETINGCARD_SQ15`.                                                                   |
+| `mergeVariableMapping`      | `object`                       | The merge variables of the order. Keys are the merge variable names.                                                                                                    |
+| `sender`              | [`Address`](#Address) \| `undefined` | The sender of the order.                                                                                                                                                |
+| `recipientMapping`    | [`Address`](#Address)                | The mapping of the recipient.                                                                                                                                             |
+| `definitiveCountryId` | `string`                             | The ID of the definitive country of the order.                                                                                                                          |
+| `billingId`           | `string` \| `undefined`              | The ID assigned to the csv order by the customer.                                                                                                                           |
+| `isBillable`          | `boolean`                            | Whether the csv order is billable. True when an live API key is used, false when a test API key is used.                                                                    |
+| `status`              | `string`                             | The status of the csv order. Can be `order_created` or `order_processed` |
+| `friendlyStatus`      | `string`                             | The friendly status of the csv order. Can be `Processing` or `Success`                                                      |
+| `estimatedOrderCount` | `number`                             | The amount of initial orders in the CSV
+| `failedOrderCount`    | `number`                             | The amount of orders which have failed to be processed
+| `processedOrderCount` | `number`                             | The amount of orders which have successfully been processed
+| `totalOrderCount`     | `number`                             | The total amount of orders failed or processed
+| `sendDate`            | `Date`                               | The date the order will be sent on.                                                                                                                                     |
+| `createdAt`           | `Date`                               | The date and time the order was created.                                                                                                                                |
+| `updatedAt`           | `Date`                               | The date and time the order was last updated.                                                                                                                           |
+
+# Methods
+
+## `.getTemplate()`
+
+Get the template the order is based on. Uses [`PrintOne.getTemplate()`](./PrintOne#gettemplateid).
+
+**Returns: [`Promise<Template>`](./Template)**
+
+**Example**
+
+```js
+const order = await client.getOrder("example-order-id");
+const template = await order.getTemplate();
+```
+
+---
+
+## `.refresh()`
+
+Refresh the CsvOrder data to get the latest information
+
+**Returns: `Promise<void>`**
+
+**Example**
+
+```js
+const csvOrder: CsvOrder;
+await csvOrder.refresh();
+```
+
+---
+
+## [`CsvOrder.getOrders([options])`](./PrintOne#getordersoptions)
+
+Get all orders generated by the CSV.
+
+**Parameters**
+
+| Name                            | Type                          | Default          | Description                                                                                                                        |
+| ------------------------------- | ----------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `options.limit`                 | `number`                      | `10`             | The maximum number of orders to return.                                                                                            |
+| `options.page`                  | `number`                      | `1`              | The page of orders to return.                                                                                                      |
+| `options.sortBy`                | [`sort`](./Filtering#Sorting) | `createdAt:DESC` | The field(s) to sort the orders by. Can be `createdAt`, `anonymizedAt`, `updatedAt`, `friendlyStatus` or `sendDate`                |
+| `options.filter.friendlyStatus` | `string` \| `string[]`        | `undefined`      | The friendly status(es) of the order(s) to filter by. Can be `Processing`, `Success`, `Sent`, `Scheduled`, `Cancelled` or `Failed` |
+| `options.filter.billingId`      | `string` \| `string[]`        | `undefined`      | The billing ID(s) of the order(s) to filter by.                                                                                    |
+| `options.filter.format`         | `string` \| `string[]`        | `undefined`      | The format(s) of the order(s) to filter by. Can be `POSTCARD_A5`, `POSTCARD_A6`, `POSTCARD_SQ14` or `GREETINGCARD_SQ15`            |
+| `options.filter.finish`         | `string` \| `string[]`        | `undefined`      | The finish(es) of the order(s) to filter by. Can be `GLOSSY` or `MATTE`                                                            |
+| `options.filter.isBillable`     | `boolean`                     | `undefined`      | Whether the order(s) are live order or test orders.                                                                                |
+| `options.filter.createdAt`      | [`date`](./Filtering#Date)    | `undefined`      | The date(s) the order(s) were created on.                                                                                          |
+
+**Returns: [`Promise<PaginatedResponse<Order>>`](./Order)**
+
+**Example**
+
+```js
+const orders = await csvOrder.getOrders({
+  limit: 20,
+  page: 1,
+  sortBy: "createdAt:ASC",
+  filter: {
+    friendlyStatus: "Success",
+    billingId: "example-billing-id",
+    format: Format.POSTCARD_A5,
+    finish: Finish.GLOSSY,
+    isBillable: true,
+    createdAt: {
+      from: "2020-01-01",
+      to: "2020-01-31",
+    },
+  },
+});
+```
diff --git a/docs/PrintOne.md b/docs/PrintOne.md
@@ -243,3 +243,39 @@ const orders = await client.getOrders({
   },
 });
 ```
+
+---
+
+## `.createCsvOrder(data)`
+
+Create a new csv order.
+
+**Parameters**
+
+| Name   | Type     | Description                                                                              |
+| ------ | -------- | ---------------------------------------------------------------------------------------- |
+| `data` | `object` | The data to create the order with. See [`CsvOrder`](./CsvOrder#createcsvorderdata) for more info. |
+
+**Returns: [`Promise<CsvOrder>`](./CsvOrder)**
+
+**Example**
+
+```js
+const order = await client.createCsvOrder({
+   mapping: {
+      recipient: {
+        city: "{{City}}",
+        name: "{{FirstName}} {{LastName}}",
+        address: "{{Street}} {{HouseNr}}",
+        country: "{{Country}}",
+        postalCode: "{{ZIP}}",
+      },
+      mergeVariables: {
+        name: "{{FirstName}}",
+        coupon: "{{Coupon}}",
+      },
+    },
+    template: template,
+    file: file,
+});
+```
diff --git a/src/PrintOne.ts b/src/PrintOne.ts
@@ -24,13 +24,14 @@ import { IOrder } from "./models/_interfaces/IOrder";
 import { FriendlyStatus } from "./enums/Status";
 import { Format } from "./enums/Format";
 import { AxiosHTTPHandler } from "./AxiosHttpHandler";
+import { CreateCsvOrder, CsvOrder } from "./models/CsvOrder";
+import { ICsvOrder } from "./models/_interfaces/ICsvOrder";
 
 export type RequestHandler = new (
   token: string,
   options: Required<PrintOneOptions>,
   debug: debug.Debugger,
-) => HttpHandler<unknown, unknown>;
-
+) => HttpHandler<{ headers: Record<string, string> }, unknown>;
 export type PrintOneOptions = Partial<{
   url: string;
   version: "v2";
@@ -52,6 +53,21 @@ export type Protected = {
   printOne: PrintOne;
 };
 
+export type OrderPaginatedQuery = PaginationOptions<
+  "createdAt" | "anonymizedAt" | "updatedAt" | "friendlyStatus" | "sendDate"
+> & {
+  filter?: {
+    friendlyStatus?: InFilter<FriendlyStatus>;
+    billingId?: InFilter;
+    format?: InFilter<Format>;
+    // finish?: InFilter<Finish>;
+    isBillable?: boolean;
+    createdAt?: DateFilter;
+    anonymizedAt?: DateFilter | boolean;
+    csvId?: InFilter;
+  };
+};
+
 export class PrintOne {
   private readonly _protected: Partial<Protected> = {
     debug: debug("print-one"),
@@ -249,6 +265,43 @@ export class PrintOne {
     return new Order(this.protected, response);
   }
 
+  public async createCsvOrder(data: CreateCsvOrder): Promise<CsvOrder> {
+    const templateId =
+      typeof data.template === "string" ? data.template : data.template.id;
+
+    const formData = new FormData();
+    formData.append(
+      "file",
+      new Blob([data.file], { type: "text/csv" }),
+      "upload.csv",
+    );
+    formData.append("mapping", JSON.stringify(data.mapping));
+    formData.append(
+      "orderData",
+      JSON.stringify({
+        sender: data.sender,
+        templateId,
+        finish: data.finish,
+        billingId: data.billingId,
+      }),
+    );
+
+    const response = await this.client.POST<{ id: string }>(
+      "orders/csv",
+      formData,
+      {
+        headers: {
+          "Content-Type": "multipart/form-data",
+        },
+      },
+    );
+
+    const id = response.id;
+    const csvInfo = await this.client.GET<ICsvOrder>(`orders/csv/${id}`);
+
+    return new CsvOrder(this.protected, csvInfo);
+  }
+
   /**
    * Get an order by its id.
    * @param { string } id The id of the order.
@@ -270,19 +323,7 @@ export class PrintOne {
    * @throws { PrintOneError } If the order could not be found.
    */
   public async getOrders(
-    options: PaginationOptions<
-      "createdAt" | "anonymizedAt" | "updatedAt" | "friendlyStatus" | "sendDate"
-    > & {
-      filter?: {
-        friendlyStatus?: InFilter<FriendlyStatus>;
-        billingId?: InFilter;
-        format?: InFilter<Format>;
-        // finish?: InFilter<Finish>;
-        isBillable?: boolean;
-        createdAt?: DateFilter;
-        anonymizedAt?: DateFilter | boolean;
-      };
-    } = {},
+    options: OrderPaginatedQuery = {},
   ): Promise<PaginatedResponse<Order>> {
     let params = {
       ...sortToQuery(options),
@@ -291,6 +332,7 @@ export class PrintOne {
       ...inFilterToQuery("format", options.filter?.format),
       // ...inFilterToQuery("finish", options.filter?.finish),
       ...dateFilterToQuery("createdAt", options.filter?.createdAt),
+      ...inFilterToQuery("csvOrderId", options.filter?.csvId),
     };
 
     if (typeof options.filter?.isBillable === "boolean") {

diff --git a/src/enums/CsvStatus.ts b/src/enums/CsvStatus.ts
@@ -0,0 +1,29 @@
+export const CsvStatus: {
+  order_created: "order_created";
+  order_processed: "order_processed";
+} = {
+  order_created: "order_created",
+  order_processed: "order_processed",
+};
+
+export type CsvStatus = (typeof CsvStatus)[keyof typeof CsvStatus];
+
+export const FriendlyCsvStatusText: {
+  Processing: "Processing";
+  Success: "Success";
+} = {
+  Processing: "Processing",
+  Success: "Success",
+};
+
+export type FriendlyCsvStatusText =
+  (typeof FriendlyCsvStatusText)[keyof typeof FriendlyCsvStatusText];
+
+export const FriendlyCsvStatus: {
+  [key in CsvStatus]: FriendlyCsvStatusText;
+} = {
+  order_created: "Processing",
+  order_processed: "Success",
+};
+
+export type FriendlyCsvStatus = typeof FriendlyCsvStatus;
diff --git a/src/index.ts b/src/index.ts
@@ -7,6 +7,7 @@ export * from "./PrintOne";
 // Models
 export * from "./models/Address";
 export * from "./models/Company";
+export * from "./models/CsvOrder";
 export * from "./models/CustomFile";
 export * from "./models/Order";
 export * from "./models/PaginatedResponse";
@@ -15,6 +16,7 @@ export * from "./models/PreviewDetails";
 export * from "./models/Template";
 
 // Enums
+export * from "./enums/CsvStatus";
 export * from "./enums/Finish";
 export * from "./enums/Format";
 export * from "./enums/Status";