Skip to content

Commit

Permalink
docs: update sdk and delivery options sections
Browse files Browse the repository at this point in the history
  • Loading branch information
@EdieLemoine
EdieLemoine committed Jun 19, 2023
1 parent c4b3bd4 commit d836a00
Show file tree
Hide file tree
Showing 3 changed files with 107 additions and 216 deletions.
219 changes: 83 additions & 136 deletions src/documentation/51.javascript-sdk.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,31 +12,9 @@ Official JavaScript SDK to connect to the MyParcel API via Node.js or browser.

## Installation

Install [@myparcel/sdk] with your package manager:
Install [@myparcel/sdk](https://www.npmjs.com/package/@myparcel/sdk) with your package manager:

<CodeGroup id="npm">
<CodeGroupItem title="yarn">

```bash
yarn add @myparcel/sdk
```

</CodeGroupItem>
<CodeGroupItem title="pnpm">

```bash
pnpm add @myparcel/sdk
```

</CodeGroupItem>
<CodeGroupItem title="npm">

```bash
npm install @myparcel/sdk
```

</CodeGroupItem>
</CodeGroup>
<InstallNode package="@myparcel/sdk" />

## Usage examples

Expand All @@ -47,23 +25,20 @@ The client is Promise-based, so you can use `async/await`, or `Promise.then`.
First, instantiate an SDK and pass the endpoints you want to use.

```js
import { createPrivateSdk, FetchClient, PostShipments } from '@myparcel/sdk';
import {createPrivateSdk, FetchClient, PostShipments} from '@myparcel/sdk';

const clientConfig = {
headers: {
Authorization: 'bearer ' + MY_BASE_64_ENCODED_API_KEY
}
Authorization: 'bearer ' + MY_BASE_64_ENCODED_API_KEY,
},
};

const sdk = createPrivateSdk(new FetchClient(clientConfig), [
new PostShipments(),
]);

```

Then call the endpoint. There are constants available in our SDK for data like
carriers, package types, delivery types and more.
See [constants](#using-constants)
Then call the endpoint. There are constants available in our SDK for data like carriers, package types, delivery types and more. See [constants](#using-constants).

```js
const result = await sdk.postShipments({
Expand All @@ -80,89 +55,17 @@ const result = await sdk.postShipments({
street: 'Antareslaan 31',
},
},
]
],
});

console.log(result); // [ 123456 ] (The ID of the shipment that was just created)
```

### Using constants

Install [@myparcelnl/constants] to be able to use lots of pre-defined constants needed throughout our entire ecosystem, like carrier and package type IDs, country codes and names of delivery options.

Install [@myparcel/constants] with your package manager:

<CodeGroup id="npm">
<CodeGroupItem title="yarn">

```bash
yarn add @myparcel/constants
```

</CodeGroupItem>
<CodeGroupItem title="pnpm">

```bash
pnpm add @myparcel/constants
```

</CodeGroupItem>
<CodeGroupItem title="npm">

```bash
npm install @myparcel/constants
```

</CodeGroupItem>
</CodeGroup>

- **Carriers**
```js
import { CarrierId, CarrierName } from '@myparcelnl/constants';

CarrierName.PostNL // "postnl"
CarrierId.Dhl // 6
```
- **Package types**
```js
import { PackageTypeId, PackageTypeName } from '@myparcelnl/constants';

PackageTypeName.DigitalStamp // "digital_stamp"
PackageTypeId.Package // 1
// etc
```
- **Delivery types**
```js
import { DeliveryTypeId, DeliveryTypeName } from '@myparcelnl/constants';

DeliveryTypeName.Standard // "standard"
DeliveryTypeId.Pickup // 4
// etc
```
- **Countries** Contains constants for all countries, by name
```js
import { NETHERLANDS, GERMANY, EU_COUNTRIES } from '@myparcelnl/constants/countries';

NETHERLANDS // "NL"
GERMANY // "DE"
EU_COUNTRIES // ["AT", "BE", ...]
```
- **States**
```js
import { GEORGIA, STATES_US, STATES_CANADA } from '@myparcelnl/constants/states';

GEORGIA // "GA"
STATES_US // ["AL", "AK", ...]
STATES_CANADA // ["AB", "BC", ...]
```

### Creating a new endpoint

To create a new endpoint, you can extend either `AbstractPrivateEndpoint`
or `AbstractPublicEndpoint` and fill in the derived class as needed.
To create a new endpoint, you can extend either `AbstractPrivateEndpoint` or `AbstractPublicEndpoint` and fill in the derived class as needed.

Feel free to add open a pull request to add it to our repository!
See [contributing](#contributing).
Feel free to add open a pull request to add it to our repository! See [contributing](#contributing).

### Creating a new client

Expand All @@ -177,8 +80,8 @@ class AxiosClient extends AbstractClient {
url: this.createUrl(endpoint, options),
headers: {
...this.getHeaders(),
...endpoint.getHeaders()
}
...endpoint.getHeaders(),
},
});

return response.data;
Expand All @@ -199,31 +102,89 @@ const carriers = await sdk.getCarriers();
console.log(carriers); // [ { "id": 1, "name": "postnl", (etc...)
```

### Using constants

Install [@myparcel/constants](https://www.npmjs.com/package/@myparcel/constants) to be able to use lots of pre-defined constants needed throughout our entire ecosystem, like carrier and package type IDs, country codes and names of delivery options.

<InstallNode package="@myparcel/constants" />

#### Carriers

```js
import {CarrierId, CarrierName} from '@myparcel/constants';

CarrierName.PostNL; // "postnl"
CarrierId.Dhl; // 6
```

#### Package types

```js
import {PackageTypeId, PackageTypeName} from '@myparcel/constants';

PackageTypeName.DigitalStamp; // "digital_stamp"
PackageTypeId.Package; // 1
// etc
```

#### Delivery types

```js
import {DeliveryTypeId, DeliveryTypeName} from '@myparcel/constants';

DeliveryTypeName.Standard; // "standard"
DeliveryTypeId.Pickup; // 4
// etc
```

#### Countries

Contains constants for all countries, by name

```js
import {
NETHERLANDS,
GERMANY,
EU_COUNTRIES,
} from '@myparcel/constants/countries';

NETHERLANDS; // "NL"
GERMANY; // "DE"
EU_COUNTRIES; // ["AT", "BE", ...]
```

#### States

```js
import {GEORGIA, STATES_US, STATES_CANADA} from '@myparcelnl/constants/states';

GEORGIA; // "GA"
STATES_US; // ["AL", "AK", ...]
STATES_CANADA; // ["AB", "BC", ...]
```

## Endpoints

### Public

Public endpoints do not require authorization and are safe to use in a browser.

- Delivery options
- [GetDeliveryOptions]
- [GetDeliveryOptions]
- Pickup locations
- [GetPickupLocations]
- [GetPickupLocations]
- Carriers
- [GetCarriers]
- [GetCarrier]
- [GetCarriers]
- [GetCarrier]

### Private

Private endpoints require an Authorization header. This should be a base64
encoded MyParcel API key. You can create one in the shop settings in
our [backoffice]. See [Authorization] in the API documentation for more
information.
Private endpoints require an Authorization header. This should be a base64 encoded MyParcel API key. You can create one in the shop settings in our [backoffice]. See [Authorization] in the API documentation for more information.

- Shipments
- [GetShipment]
- [GetShipments]
- [PostShipments]
- [GetShipment]
- [GetShipments]
- [PostShipments]

## Contributing

Expand Down Expand Up @@ -254,41 +215,27 @@ yarn run test:coverage
```

- Coverage % needs to be equal to or greater than that of the previous commit.
- If you added a new file, the corresponding test(s) should go
inside `<filename>.spec.ts` in the same directory.
- If you added a new file, the corresponding test(s) should go inside `<filename>.spec.ts` in the same directory.

### Commit

Make as many commits as you'd like. We use [Conventional Commits]
and [semantic-release] to simplify the process of releasing updates by
automating release notes and changelogs based on the rules
of [@commitlint/config-conventional].
Make as many commits as you'd like. We use [Conventional Commits] and [semantic-release] to simplify the process of releasing updates by automating release notes and changelogs based on the rules of [@commitlint/config-conventional].

Your branch will be squashed into one single valid commit before merging.

### Create a pull request

- Keep your pull requests focused on single subjects
- Please explain what you changed and why
- We will review your code and thoroughly test it before squashing and merging
your pull request
- We will review your code and thoroughly test it before squashing and merging your pull request

[@commitlint/config-conventional]: https://github.com/conventional-changelog/commitlint

[Conventional Commits]: https://www.conventionalcommits.org/en/v1.0.0/#summary

[GetCarrier]: https://github.com/myparcelnl/js-sdk/blob/main/src/endpoints/public/carriers/GetCarrier.ts

[GetCarriers]: https://github.com/myparcelnl/js-sdk/blob/main/src/endpoints/public/carriers/GetCarriers.ts

[GetDeliveryOptions]: https://github.com/myparcelnl/js-sdk/blob/main/src/endpoints/public/delivery-options/GetDeliveryOptions.ts

[GetPickupLocations]: https://github.com/myparcelnl/js-sdk/blob/main/src/endpoints/public/pickup-locations/GetPickupLocations.ts

[GetShipment]: https://github.com/myparcelnl/js-sdk/blob/main/src/endpoints/private/shipments/GetShipment.ts

[GetShipments]: https://github.com/myparcelnl/js-sdk/blob/main/src/endpoints/private/shipments/GetShipments.ts

[PostShipments]: https://github.com/myparcelnl/js-sdk/blob/main/src/endpoints/private/shipments/PostShipments.ts

[semantic-release]: https://github.com/semantic-release/semantic-release
Loading

0 comments on commit d836a00

Please sign in to comment.