= xl-automaten-api

An unofficial TypeScript client library for the https://xl-automaten.de/[XL Automaten] API.

You can use this library to access the API in an easy and type-safe way.

== Install

Just install it with your favorite package manager:

yarn add xl-automaten-api
pnpm add xl-automaten-api
npm install xl-automaten-api

The package should work in the browser and Node.js versions 18 and up.

== Examples

== Obtain an auth token

You need an API token for nearly all operations. You can get one by calling the login function:

const { token } = await login({
  email,
  password,
})
console.log("Your token is", token)

The token is typically valid for 1 hour.

=== Create a pickup

You can create a new pickup code that can be used to pick up an order:

const pickup = await createPickup({
  pickup: {
    code: "code-that-will-be-used-to-pickup-the-order",
    valid_from: new Date(),
    valid_until: new Date(Date.now() + 1000 * 60 * 60 * 24),
    mastermoduleId: 99,
  },
  token: "your-token",
})

console.log(pickup)

=== Get information about an existing pickup

To get information about an existing pickup, use the getPickup function:

const pickup = await getPickup({
  code: "code-of-an-existing-pickup",
  token: "your-token",
})

console.log(pickup)

// With getPickup, you can also get the items included in the pickup:
console.log(pickup.items)

=== Delete an existing pickup

To delete an existing pickup, use the deletePickup function:

const pickup = await createPickup({
  pickup: {
    code: "any-string-you-want",
    valid_from: new Date(),
    valid_until: new Date(Date.now() + 1000 * 60 * 60 * 24),
    mastermoduleId: 99,
  },
  token: "your-token",
})

console.log(pickup)

=== Other operations

You can also create articles (createArticle) and add them to a pickup with createPickupItem. This library also includes functions for accessing machines (e.g., createMachine), mastermodules (getMastermodules), trays, positions, categories, and suppliers. The source code includes comments with examples for these endpoints.

== API Documentation

There is no public API documentation for the XL Automaten API. This package is based on reverse engineering the API and emailing the people from XL Automaten.

I am still figuring out how everything works, so the API is not yet stable. I will update the README once I have enough confidence in the correctness of this package.

Most endpoints are documented in TypeScript in the src/helpers/convert*.ts files.

== Known API endpoints

[cols="1,1"] |=== |endpoint |supported by this package |supported methods

|Cell in column 1, row 2 |Cell in column 2, row 2

|Cell in column 1, row 3 |Cell in column 2, row 3 |===

== Older node versions

This package uses the fetch API, which is only supported in Node.js 18 and up. If you need to use an older version of Node.js, you can use node-fetch. It will be detected and used automatically if your node does not provide a native fetch. The Options object supports passing a custom fetch function. You can also try to pass node-fetch there.

== Building and testing this package

To run the tests for this package, you need to have credentials for XL Automaten. Put these credentials into the src/tests/login.ts file. Now you can run yarn test to run the tests.