diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..83058c6 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,24 @@ +name: Update documentation +on: + push: + branches: + - main + 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/actions-wiki@v0.3.0 + with: + path: docs diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 51894dc..0afae3e 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -2,7 +2,7 @@ name: Release on: push: branches: - - main-wip + - main jobs: release: name: Release @@ -18,8 +18,11 @@ jobs: node-version: "lts/*" - name: Install dependencies run: npm ci - - name: Build - run: npm run build + - name: Test + run: npm run test + env: + API_KEY: ${{ secrets.API_KEY }} + API_URL: ${{ secrets.API_URL }} - name: Release env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml new file mode 100644 index 0000000..53292a3 --- /dev/null +++ b/.github/workflows/test.yml @@ -0,0 +1,35 @@ +name: Test +on: + push: + branches: + - main + paths-ignore: + - "docs/**" + - "**/*.md" + pull_request: + paths-ignore: + - "docs/**" + - "**/*.md" + +jobs: + test: + name: Test + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v3 + with: + fetch-depth: 0 + - name: Setup Node.js + uses: actions/setup-node@v3 + with: + node-version: "lts/*" + - name: Install dependencies + run: npm ci + - name: Test + run: npm run test + env: + API_KEY: ${{ secrets.API_KEY }} + API_URL: ${{ secrets.API_URL }} + - name: Build + run: npm run build diff --git a/README.md b/README.md index 340fd48..43babf9 100644 --- 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(""); -[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 new file mode 100644 index 0000000..026e309 --- /dev/null +++ b/docs/Company.md @@ -0,0 +1,42 @@ +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)** + +**Example** + +```js +const company = await client.getSelf(); +``` diff --git a/docs/CustomFile.md b/docs/CustomFile.md new file mode 100644 index 0000000..b938203 --- /dev/null +++ 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`** + +**Example** + +```js +const file = await customFile.download(); +``` + +--- + +## `.delete()` + +Delete the CustomFile. + +**Returns: `Promise`** + +**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)** + +**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)** + +**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 new file mode 100644 index 0000000..e69de29 diff --git a/docs/Filtering.md b/docs/Filtering.md new file mode 100644 index 0000000..20145dc --- /dev/null +++ b/docs/Filtering.md @@ -0,0 +1,125 @@ +# Sorting + +The sorting options for the API. Are defined using the following format: + +```js +const sortBy = ":"; +``` + +Or: + +```js +const sortBy = { + order: "", + field: "", +}; +``` + +Where `` is the field to sort by and `` is the order to sort in. +It can also be an array of the above formats. + +## Examples + +```js +// Simplest form +const sortBy = ":ASC"; +const sortBy = ":DESC"; +``` + +```js +// Multiple fields +const sortBy = [":ASC", ":DESC"]; +``` + +```js +// Object form +const sortBy = { + order: "ASC", + field: "", +}; +``` + +```js +// Multiple fields in object form +const sortBy = [ + { + order: "ASC", + field: "", + }, + { + order: "DESC", + field: "", + }, +]; +``` + +# 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 = ""; +``` + +Or if all field values must be contained: + +```js +const contains = { + all: ["", ""], +}; +``` + +Or if any field value must be contained: + +```js +const contains = { + some: ["", ""], +}; +``` + +Where `` 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?: "", + to?: "" +}; +``` + +Where `` 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", + }, +}; +``` diff --git a/docs/Home.md b/docs/Home.md new file mode 100644 index 0000000..66a4aae --- /dev/null +++ b/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(""); + ``` + +3. Start using the client + - See examples [here](./Examples) + - See all available methods [here](./PrintOne) + - See all available models [here](./Models) + +## 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). diff --git a/docs/Models.md b/docs/Models.md new file mode 100644 index 0000000..680703a --- /dev/null +++ b/docs/Models.md @@ -0,0 +1,41 @@ +In the Print.One library we have the following models (classes): + +## [PrintOne (client for the Print.one API)](./PrintOne) + +The main class of the library. +It is used to create a client for the Print.one API. +This is the main entry for the library. + +[See the full documentation](./PrintOne) + +## [Company](./Company) + +Is a class that is used for the company that the API key belongs to. + +[See the full documentation](./Company) + +[Portal overview](https://portal.print.one/settings/company) + +## [CustomFile](./CustomFile) + +Is a class that represents a file which can be used in a template. + +[See the full documentation](./CustomFile) + +[Portal overview](https://portal.print.one/customfiles) + +## [Template](./Template) + +Is a class that represents a design template. Consists of multiple pages. + +[See the full documentation](./Template) + +[Portal overview](https://portal.print.one/designs) + +## [Order](./Order) + +Is a class that represents an order. Can be used to get the status of, download or cancel the order. + +[See the full documentation](./Order) + +[Portal overview](https://portal.print.one/orders) diff --git a/docs/Order.md b/docs/Order.md new file mode 100644 index 0000000..e6c2009 --- /dev/null +++ b/docs/Order.md @@ -0,0 +1,192 @@ +Contains all information about a given Order + +# Fields + +| Name | Type | Description | +| --------------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | `string` | The ID of the order. | +| `companyId` | `string` | The ID of the company the order belongs to. | +| `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`. | +| `mergeVariables` | `object` | The merge variables of the order. Keys are the merge variable names. | +| `sender` | [`Address`](#Address) \| `undefined` | The sender of the order. | +| `recipient` | [`Address`](#Address) | The recipient of the order. | +| `definitiveCountryId` | `string` | The ID of the definitive country of the order. | +| `billingId` | `string` \| `undefined` | The ID assigned to the order by the customer. | +| `isBillable` | `boolean` | Whether the 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 order. Can be `order_created`, `order_pdf_created`, `order_pdf_queued`, `order_scheduled`, `order_pdf_delivered`, `order_cancelled` or `order_failed` | +| `friendlyStatus` | `string` | The friendly status of the order. Can be `Processing`, `Success`, `Sent`, `Scheduled`, `Cancelled` or `Failed` | +| `errors` | `string[]` | The errors of the order. | +| `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. | +| `anonymizedAt` | `Date` \| `undefined` | The date and time the order was anonymized. | + +# Methods + +## `.getTemplate()` + +Get the template the order is based on. Uses [`PrintOne.getTemplate()`](./PrintOne#gettemplateid). + +**Returns: [`Promise