docs: first version

Print-one · Nov 13, 2023 · 4688682 · 4688682
1 parent 9f29c77
commit 4688682
Show file tree

Hide file tree

Showing 18 changed files with 1,065 additions and 37 deletions.
diff --git a/.github/workflows/docs.yml b/.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
diff --git a/README.md b/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/
diff --git a/docs/Company.md b/docs/Company.md
@@ -0,0 +1,43 @@
+Contains all information about a given Company
+
+# Fields
+
+| Name                    | Type                  | Description                                       |
+|-------------------------|-----------------------|---------------------------------------------------|
+| `id`                    | `string`              | The ID of the company.                            |
+| `firstName`             | `string`              | The first name of the contact person.             |
+| `lastName`              | `string`              | The last name of the contact person.              |
+| `email`                 | `string`              | The email address of the company.                 |
+| `invoiceEmail`          | `string`              | The email address for invoices.                   |
+| `financialContactName`  | `string`              | The name of the financial contact.                |
+| `finacialContactEmail`  | `string`              | The email address for financial contact.          |
+| `technicalContactName`  | `string`              | The name of the technical contact.                |
+| `technicalContactEmail` | `string`              | The email address for technical contact.          |
+| `phoneNumber`           | `string`              | The phone number of the contact person.           |
+| `companyName`           | `string`              | The name of the company.                          |
+| `street`                | `string`              | The street of the company.                        |
+| `houseNumber`           | `string`              | The house number of the company.                  |
+| `country`               | `string`              | The country of the company.                       |
+| `postalCode`            | `string`              | The postal code of the company.                   |
+| `city`                  | `string`              | The city of the company.                          |
+| `cocNumber`             | `string`              | The Chamber of Commerce number.                   |
+| `vatNumber`             | `string`              | The VAT number of the company.                    |
+| `iban`                  | `string`              | The IBAN number of the company.                   |
+| `createdAt`             | `Date`                | The date and time the company was created.        |
+| `updatedAt`             | `Date`                | The date and time the company was last updated.   |
+| `emailVerifiedAt`       | `Date` \| `undefined` | The date and time the email address was verified. |
+
+# Methods
+
+## [`PrintOne.getSelf()`](./PrintOne#getself)
+
+Get the company that the API key belongs to.
+
+**Returns: [`Promise<Company>`](./Company)**
+
+**Example**
+
+```js
+const company = await client.getSelf();
+```
+
diff --git a/docs/CustomFile.md b/docs/CustomFile.md
@@ -0,0 +1,89 @@
+Contains information about CustomFiles and methods to download.
+
+# Fields
+
+| Name            | Type     | Description                                   |
+|-----------------|----------|-----------------------------------------------|
+| `id`            | `string` | The ID of the CustomFile.                     |
+| `fileName`      | `string` | The name of the CustomFile.                   |
+| `fileExtension` | `string` | The extension of the CustomFile.              |
+| `size`          | `number` | The size of the CustomFile in bytes.          |
+| `createdAt`     | `Date`   | The date and time the CustomFile was created. |
+
+# Methods
+
+## `.download()`
+
+Download the CustomFile.
+
+**Returns: `Promise<ArrayBuffer>`**
+
+**Example**
+
+```js
+const file = await customFile.download();
+```
+
+---
+
+## `.delete()`
+
+Delete the CustomFile.
+
+**Returns: `Promise<void>`**
+
+**Example**
+
+```js
+await customFile.delete();
+```
+
+---
+
+## [`PrintOne.getCustomFiles([options])`](./PrintOne#getcustomfilesoptions)
+
+Get all custom files.
+
+**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`](./Filtering#Sorting) | `createdAt:DESC` | The field(s) to sort the custom files by. Can be `createdAt`, `fileName`, `size`, `id` or `fileExtension` |
+
+**Returns: [`Promise<CustomFile[]>`](./CustomFile)**
+
+**Example**
+
+```js
+const customFiles = await client.getCustomFiles({
+  limit: 20,
+  page: 2,
+  sortBy: "fileName:ASC"
+});
+```
+
+---
+
+## [`PrintOne.uploadCustomFile(fileName, file)`](./PrintOne#uploadcustomfilefilename-file)
+
+Upload a custom file. The file must be a image or font.
+
+**Parameters**
+
+| Name       | Type          | Description                                  |
+|------------|---------------|----------------------------------------------|
+| `fileName` | `string`      | The name of the file.                        |
+| `file`     | `ArrayBuffer` | The file to upload. Must be a image or font. |
+
+**Returns: [`Promise<CustomFile>`](./CustomFile)**
+
+**Example**
+
+```js
+import fs from "fs";
+
+const data = fs.readFileSync("example.png").buffer;
+const file = await client.uploadCustomFile("example.png", data);
+```
diff --git a/docs/Examples.md b/docs/Examples.md
diff --git a/docs/Filtering.md b/docs/Filtering.md
@@ -0,0 +1,125 @@
+# 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>"
+  }
+];
+```
+
+# Filtering
+
+## Contains
+
+Filtering a field which is a list of strings can be done using the `contains` filter. It is defined using the following format:
+
+```js
+const contains = "<value>";
+```
+
+Or if all field values must be contained:
+
+```js
+const contains = {
+  all: ["<value1>", "<value2>"]
+};
+```
+
+Or if any field value must be contained:
+
+```js
+const contains = {
+  some: ["<value1>", "<value2>"]
+};
+```
+
+Where `<value>` is the value to filter by.
+
+## Date
+
+Filtering a field which is a date can be done using the `date` filter. It is defined using the following format:
+
+```js
+const date = {
+  from?: "<date>",
+  to?: "<date>"
+};
+```
+
+Where `<date>` is the date to filter by.
+
+## Examples
+
+```js
+// Between two dates
+const filter = {
+  date: {
+    from: "2019-01-01",
+    to: "2019-12-31"
+  }
+};
+```
+
+```js
+// After a date
+const filter = {
+  date: {
+    from: "2019-01-01"
+  }
+};
+```
+
+```js
+// Before a date
+const filter = {
+  date: {
+    to: "2019-12-31"
+  }
+};
+```