docs: first version

.github/workflows/docs.yml

@@ -0,0 +1,25 @@
+name: Update documentation
+on:
+  push:
+    branches:
+      - main
+      - develop
+    paths:
+      - docs/**
+
+concurrency:
+  group: wiki
+  cancel-in-progress: true
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    name: Update documentation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: spenserblack/[email protected]
+        with:
+          path: docs

README.md

@@ -4,8 +4,18 @@
 [![Build Status][build-img]][build-url]
 [![Issues][issues-img]][issues-url]
 [![Semantic Release][semantic-release-img]][semantic-release-url]
-[![TypeScript][typescript-img]][typescript-url]
 
+[npm-img]:https://img.shields.io/npm/v/@print-one/print-one-js
+[npm-url]:https://www.npmjs.com/package/@print-one/print-one-js
+
+[build-img]:https://github.com/Print-one/print-one-js/actions/workflows/release.yml/badge.svg
+[build-url]:https://github.com/Print-one/print-one-js/actions/workflows/release.yml
+
+[issues-img]:https://img.shields.io/github/issues/Print-one/print-one-js
+[issues-url]:https://github.com/Print-one/print-one-js/issues
+
+[semantic-release-img]:https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg
+[semantic-release-url]:https://github.com/semantic-release/semantic-release
 
 > The official javascript client for [Print.one](https://print.one)
 
@@ -15,22 +25,51 @@
 npm install @print-one/print-one-js
 ```
 
-[npm-img]:https://img.shields.io/npm/v/@print-one/print-one-js
+## Example
 
-[npm-url]:https://www.npmjs.com/package/@print-one/print-one-js
+```js
+import { PrintOne } from '@print-one/print-one-js'
 
-[build-img]:https://github.com/Print-one/print-one-js/actions/workflows/release.yml/badge.svg
+const client = new PrintOne("<YOUR API TOKEN>");
 
-[build-url]:https://github.com/Print-one/print-one-js/actions/workflows/release.yml
+const templates = await client.getTemplates();
+const template = templates[0];
 
-[issues-img]:https://img.shields.io/github/issues/Print-one/print-one-js
+const order = await client.createOrder({
+    recipient: {
+        name: "John Doe",
+        address: "Example Street 2",
+        city: "Anytown",
+        postalCode: "1234AB",
+        country: "NL",
+    },
+    template: template,
+    // All other options are optional
+    sender: {
+        name: "Jane Doe",
+        address: "Example Street 1",
+        addressLine2: "Apt 1",
+        city: "Anytown",
+        postalCode: "1234AB",
+        country: "NL",
+    },
+    finish: Finish.GLOSSY,
+    mergeVariables: {
+        couponCode: "ABC123"
+    },
+    billingId: "8073",
+    sendDate: "2021-01-01",
+});
 
-[issues-url]:https://github.com/ryansonshine/Print-one/print-one-js/issues
+const download = await order.download();
 
-[semantic-release-img]:https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg
+fs.writeFileSync("order.pdf", download);
+```
 
-[semantic-release-url]:https://github.com/semantic-release/semantic-release
+## Help
+
+- For documentation and more examples, see the [documentation](https://github.com/Print-one/print-one-js/wiki).
+- With problems, questions or suggestions, please file an [issue](https://github.com/Print-one/print-one-js/issues).
+- For other questions, feel free to contact us at [our support page](https://printone.atlassian.net/servicedesk/customer/portals).
 
-[typescript-img]:https://img.shields.io/github/languages/top/print-one/print-one-js?logo=typescript&logoColor=white
 
-[typescript-url]:https://www.typescriptlang.org/

docs/Home.md

@@ -0,0 +1,32 @@
+# Print-one-js
+
+> The official javascript client for [Print.one](https://print.one)
+
+## Installation
+
+```bash
+npm install @print-one/print-one-js
+```
+
+## Getting started
+
+1. Get your API token from [Print.one](https://portal.print.one/devs/apikeys)
+2. Create a new client with your API token
+
+    ```js
+    import { PrintOne } from '@print-one/print-one-js'
+
+    const client = new PrintOne('<YOUR API TOKEN>');
+    ```
+3. Start using the client
+    - See examples [here](./Examples.md)
+    - See all available methods [here](./models/PrintOne.md)
+    - See all available models [here](./Models.md)
+
+## Help
+
+- For documentation and more examples, see the [documentation](https://github.com/Print-one/print-one-js/wiki).
+- With problems, questions or suggestions, please file an [issue](https://github.com/Print-one/print-one-js/issues).
+- For other questions, feel free to contact us
+  at [our support page](https://printone.atlassian.net/servicedesk/customer/portals).
+

docs/Sorting.md

@@ -0,0 +1,54 @@
+# Sorting
+
+The sorting options for the API. Are defined using the following format:
+
+```js
+const sortBy = "<field>:<order>";
+```
+
+Or:
+
+```js
+const sortBy = {
+  order: "<order>",
+  field: "<field>"
+};
+```
+
+Where `<field>` is the field to sort by and `<order>` is the order to sort in.
+It can also be an array of the above formats.
+
+## Examples
+
+```js
+// Simplest form
+const sortBy = "<field>:ASC";
+const sortBy = "<field>:DESC";
+```
+
+```js
+// Multiple fields
+const sortBy = ["<field1>:ASC", "<field2>:DESC"];
+```
+
+```js
+// Object form
+const sortBy = {
+  order: "ASC",
+  field: "<field>"
+};
+```
+
+```js
+// Multiple fields in object form
+const sortBy = [
+  {
+    order: "ASC",
+    field: "<field1>"
+  },
+  {
+    order: "DESC",
+    field: "<field2>"
+  }
+];
+```

docs/models/PrintOne.md

@@ -0,0 +1,47 @@
+The main class of the library. It is used to create a client for the Print.one API.
+
+# Constructor
+
+```js
+import { PrintOne } from '@print-one/print-one-js'
+
+const client = new PrintOne(apiKey);
+```
+
+# Methods
+
+## `.getSelf()`
+
+Get the company that the API key belongs to.
+
+#### Returns: [`Promise<Company>`](./Company.md)
+
+#### Example
+
+```js
+const company = await client.getSelf();
+```
+
+## `.getCustomFiles([options])`
+
+Get all custom files of the company.
+
+#### Parameters
+
+| Name             | Type                      | Default          | Description                                                                                               |
+|------------------|---------------------------|------------------|-----------------------------------------------------------------------------------------------------------|
+| `options.limit`  | `number`                  | `10`             | The maximum number of custom files to return.                                                             |
+| `options.page`   | `number`                  | `1`              | The page of custom files to return.                                                                       |
+| `options.sortBy` | [`sort`](./../Sorting.md) | `createdAt:DESC` | The field(s) to sort the custom files by. Can be `createdAt`, `fileName`, `size`, `id` or `fileExtension` |
+
+#### Returns: [`Promise<CustomFile[]>`](./CustomFile.md)
+
+#### Example
+
+```js
+const customFiles = await client.getCustomFiles({
+  limit: 20,
+  page: 2,
+  sortBy: "fileName:ASC"
+});
+```

src/PrintOne.ts

@@ -215,10 +215,14 @@ export class PrintOne {
     finish?: Finish;
     mergeVariables?: Record<string, unknown>;
     billingId?: string;
-    sendDate?: Date;
+    sendDate?: Date | string;
   }): Promise<Order> {
     const templateId =
       typeof data.template === "string" ? data.template : data.template.id;
+    const sendDateStr =
+      data.sendDate instanceof Date
+        ? data.sendDate.toISOString()
+        : data.sendDate;
 
     const response = await this.client.POST<IOrder>("orders", {
       sender: data.sender,
@@ -227,7 +231,7 @@ export class PrintOne {
       finish: data.finish,
       mergeVariables: data.mergeVariables,
       billingId: data.billingId,
-      sendDate: data.sendDate?.toISOString(),
+      sendDate: sendDateStr,
     });
 
     return new Order(this.protected, response);

src/utils.ts

@@ -3,17 +3,19 @@ export async function sleep(ms: number): Promise<void> {
 }
 
 export type SortDirection = "ASC" | "DESC";
-export type SortBy<T> = {
-  order: SortDirection;
-  field: T;
-};
-export type PaginationOptions<T> = {
+export type SortBy<T extends string> =
+  | {
+      order: SortDirection;
+      field: T;
+    }
+  | `${T}:${SortDirection}`;
+export type PaginationOptions<T extends string> = {
   limit?: number;
   page?: number;
   sortBy?: SortBy<T>[] | SortBy<T>;
 };
 
-export function sortToQuery<T>(
+export function sortToQuery<T extends string>(
   options: PaginationOptions<T>,
 ): Record<string, unknown> {
   const query: Record<string, unknown> = {};
@@ -24,7 +26,9 @@ export function sortToQuery<T>(
       : [options.sortBy];
 
     query.sortBy = sortBy
-      .map((sort) => `${sort.field}:${sort.order}`)
+      .map((sort) =>
+        typeof sort === "string" ? sort : `${sort.field}:${sort.order}`,
+      )
       .join(",");
   }
 
@@ -116,8 +120,8 @@ export function invertedFilterToQuery(
 }
 
 export type DateFilter = {
-  from?: Date;
-  to?: Date;
+  from?: string | Date;
+  to?: string | Date;
 };
 
 export function dateFilterToQuery(
@@ -130,14 +134,16 @@ export function dateFilterToQuery(
 
   const query: Record<string, unknown> = {};
 
-  if (values.from && values.to) {
-    query[
-      `filter.${field}`
-    ] = `btw:${values.from.toISOString()},${values.to.toISOString()}`;
+  const from =
+    values.from instanceof Date ? values.from.toISOString() : values.from;
+  const to = values.to instanceof Date ? values.to.toISOString() : values.to;
+
+  if (from && to) {
+    query[`filter.${field}`] = `btw:${from},${to}`;
   } else if (values.from) {
-    query[`filter.${field}`] = `$gte:${values.from.toISOString()}`;
+    query[`filter.${field}`] = `$gte:${from}`;
   } else if (values.to) {
-    query[`filter.${field}`] = `$lte:${values.to.toISOString()}`;
+    query[`filter.${field}`] = `$lte:${to}`;
   }
 
   return query;