Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add tutorial #62

Merged
merged 2 commits into from
Sep 6, 2024
Merged

Add tutorial #62

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
74bb68b
Add tutorial
arnoerpenbeck Sep 5, 2024
d6c2551
Add tutorial
arnoerpenbeck Sep 5, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 17 additions & 45 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,23 @@

# 🤖 Introduction

This is a JavaScript/TypeScript SDK for the [fulfillmenttools API](https://docs.fulfillmenttools.com/api-docs/).
This is a JavaScript/TypeScript SDK for the [fulfillmenttools REST API](https://docs.fulfillmenttools.com/api-docs/).

## 👉 Get started

The TypeScript SDK is fully open source and is available on [GitHub](https://github.com/fulfillmenttools/fulfillmenttools-sdk-typescript).
The package is published on [npmjs.com](https://www.npmjs.com/package/@fulfillmenttools/fulfillmenttools-sdk-typescript).
It contains both an ESM and a CommonJS build, so you can use it in the browser and in the backend.

```bash
$ npm install @fulfillmenttools/fulfillmenttools-sdk-typescript
```

Learn how to set up and use the TypeScript SDK with our [tutorial](./TUTORIAL.md).

## 📖 Documentation

The official fulfillmenttools API documentation can be found [here](https://docs.fulfillmenttools.com/api-docs/), and we also publish our [OpenAPI specification](https://fulfillmenttools.github.io/api-reference-ui/).

## 👨‍💻 Development

Expand Down Expand Up @@ -51,50 +67,6 @@ $ npm run test
$ npm run lint
```

## 👉 Usage

This software is published on [npmjs.com](https://www.npmjs.com/package/@fulfillmenttools/fulfillmenttools-sdk-typescript).
The package contains both an ESM and a CommonJS build.

```bash
$ npm install @fulfillmenttools/fulfillmenttools-sdk-typescript`
```

Here's a little example how to create a client instance in TypeScript:

```typescript
import { FftApiClient, FftOrderService, OrderForCreation } from '@fulfillmenttools/fulfillmenttools-sdk-typescript';

const fftApiClient = new FftApiClient(
process.env.FFT_PROJECT_ID || '',
process.env.FFT_API_USER || '',
process.env.FFT_API_PASSWORD || '',
process.env.FFT_API_KEY || ''
);

const fftOrderService = new FftOrderService(fftApiClient);

const fftOrder = {} as OrderForCreation;
await fftOrderService.create(fftOrder);
```

By default, HTTP request logging is disabled. If you wish to have it logging enabled, just add a boolean to your `FftApiClient`:
```typescript
import { FftApiClient, FftOrderService, OrderForCreation } from '@fulfillmenttools/fulfillmenttools-sdk-typescript';

const fftApiClient = new FftApiClient(
process.env.FFT_PROJECT_ID || '',
process.env.FFT_API_USER || '',
process.env.FFT_API_PASSWORD || '',
process.env.FFT_API_KEY || '',
process.env.FFT_LOGGING_ENABLED || true
);
```

## 📖 Documentation

The official fulfillmenttools API documentation can be found [here](https://docs.fulfillmenttools.com/api-docs/), and we also publish our [OpenAPI specification](https://fulfillmenttools.github.io/api-reference-ui/).

## 📜 License

All code in this repository is licensed under the [MIT license](https://github.com/fulfillmenttools/fulfillmenttools-sdk-typescript/blob/master/LICENSE).
Expand Down
207 changes: 207 additions & 0 deletions TUTORIAL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,207 @@
# Get Started

This tutorial will guide you through the first steps to get started with the fulfillmenttools TypeScript SDK.

## Requirements

To follow this tutorial, you will need to:
* have [access](https://docs.fulfillmenttools.com/api-docs/getting-started/setup-your-access-to-fulfillmenttools) to a fulfillmenttools project
* have a basic understanding of [TypeScript](https://www.typescriptlang.org/)
* have [Node.js](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) and npm installed

If you're new to Node.js development, start with one of the many tutorials on the web, e.g. [this one from MDN](https://developer.mozilla.org/en-US/docs/Learn/Server-side/Express_Nodejs/development_environment).

## Objectives

By the end of this guide you will have:
* [Installed the TypeScript SDK](#install-the-typescript-sdk)
* [Created a fulfillmenttools API client](#create-the-client)
* [Learned how to make API calls with the TypeScript SDK](#make-an-api-call)

## Placeholder values

Example code in this guide uses placeholders that should be replaced with the following values.

| Placeholder | Replace with |
| ----------- | ------------ |
| `{projectId}` | your fulfillmenttools project ID, e.g. `ocff-mytenant-prd` |
| `{apiUser}` | your API username |
| `{apiPassword}` | your API password |
| `{apiKey}` | your API key |


## Tutorial

### Set up a Node.js project

First, we need to set up a new Node.js project. Create a new folder `hello-fft` for your project and navigate to it in your terminal:

```bash
mkdir hello-fft
cd hello-fft
```

Next, run the following commands to initialize the project:

```bash
npm init -y
```

Install some development dependencies and initialize TypeScript:

```bash
npm install -D typescript ts-node @types/node
npx tsc --init
```

Finally, open `package.json` and make the following modifications:

```json
{
"name": "hello-fft",
"version": "1.0.0",
"main": "index.js",
"scripts": {
"build": "tsc",
"dev": "node --env-file=.env --watch -r ts-node/register src/index.ts",
"test": "echo \"Error: no test specified\" && exit 1"
},
"keywords": [],
"author": "Fulfillment Expert",
"license": "ISL",
"description": "",
"devDependencies": {
"@types/node": "^22.5.4",
"ts-node": "^10.9.2",
"typescript": "^5.5.4"
},
"engines": {
"node": ">=20.6.0"
}
}
```

### Install the TypeScript SDK

To install the fulfillmenttools TypeScript SDK, run the following command in your terminal:

```bash
npm install @fulfillmenttools/fulfillmenttools-sdk-typescript
```

This command adds the TypeScript SDK to your project and lists it as a necessary package in `package.json`.

### Add environment variables

You can store your credentials in an `.env` file, but make sure not to check it into your code repository:

```INI
FFT_PROJECT_ID={projectId}
FFT_API_USER={apiUser}
FFT_API_PASSWORD={apiPassword}
FFT_API_KEY={apiKey}
```

### Create the main Node app file

Now that we have everything installed, let's create a simple application.
Create a new file `src/index.ts` and add the following code:

```typescript
function test(): void {
console.log(process.env.FFT_PROJECT_ID);
}

test();
```

### Project layout

Your `hello-fft` directory should now look like this:

```
.env
node_modules/
package-lock.json
package.json
src/
index.ts
tsconfig.json
```

### Start the Node server and test live reload

Start the server with `npm run dev` and you’ll see the following output:

```
npm run dev

> [email protected] dev
> node --env-file=.env --watch -r ts-node/register src/index.ts

ocff-mytenant-prd
```

Make a change to `src/index.ts` or `.env` and the server will automatically restart and show your changes in the console.

### Create the client

To create an fulfillmenttools API client, add the following code to the top of the `src/index.ts` file:

```typescript
import { FftApiClient, FftFacilityService } from '@fulfillmenttools/fulfillmenttools-sdk-typescript';

const fftApiClient = new FftApiClient(
process.env.FFT_PROJECT_ID || '',
process.env.FFT_API_USER || '',
process.env.FFT_API_PASSWORD || '',
process.env.FFT_API_KEY || ''
);

const fftFacilityService = new FftFacilityService(fftApiClient);
```

> [!NOTE]
> The `FftApiClient` will handle the autorization process, so you do not have to obtain/renew API tokens explicitly.

### Make an API call

Now you are ready to actually make a call to the fulfillmenttools REST API using your client.
Remove the `test()` function and replace it with the following code:

```typescript
async function getAllFacilities(): Promise<void> {
console.log(`Getting facilities in ${process.env.FFT_PROJECT_ID}...`);
const facilitiesResult = await fftFacilityService.get();
facilitiesResult.facilities?.forEach((facility) => { console.log(facility.name); });
}

void getAllFacilities();
```

The output of the application will now show a list of all facilities in your fulfillmenttools project:

```
Restarting 'src/index.ts'
Getting facilities in ocff-mytenant-prd...
Munich
Hamburg
Cologne
Berlin
```

(_The output will be different depending on your fulfillmenttools project data._)

End the application by pressing Ctrl-C.

## Conclusion

**Congratulations!** You have successfully finished the tutorial.
You are now ready to use the fulfillmenttools TypeScript SDK in your Node.js projects.

You can explore the other functions offered by the SDK, e.g. to create an order using `FftOrderService`, work with pick jobs using `FftPickJobService`, or try out the checkout options using `FftOrderPromisingService`, ...

> [!TIP]
> If you find anything missing or spot anything unusual, please use the [GitHub issues](https://github.com/fulfillmenttools/fulfillmenttools-sdk-typescript/issues) to get in touch. Feel free to reach out to us at [[email protected]](mailto:[email protected]) if you have any questions about the TypeScript SDK or our other open source projects.

Happy coding!