feat: readme for v2

BREAKING CHANGE: new api
hongaar · Mar 11, 2023 · 83a6546 · 83a6546
1 parent 5e261bc
commit 83a6546
Show file tree

Hide file tree

Showing 2 changed files with 76 additions and 93 deletions.
diff --git a/README.md b/README.md
@@ -1,124 +1,105 @@
 # motorrijtuigenbelasting [![npm](https://img.shields.io/npm/v/motorrijtuigenbelasting)](https://www.npmjs.com/package/motorrijtuigenbelasting)
 
-**Motorrijtuigenbelasting (MRB) berekenen in JavaScript**
+**Calculate Dutch car tax (motorrijtuigenbelasting) in JavaScript**
 
 ---
 
-> **Warning**: **API has changed**
+> **Warning**: **in development**
 >
-> A new version is being prepared, which changes the API significantly. The
-> README has not been updated yet to reflect these changes.
-
-> **Warning**: **in ontwikkeling**
->
-> Deze module is nog in ontwikkeling en kan momenteel niet worden gebruikt voor
-> het berekenen van de MRB.
+> This module is in development and not ready for use. The implemented rules are
+> tested and verified, but quite some rules are not implemented yet.
 
 ---
 
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 
-- [Installatie](#installatie)
-- [MRB berekenen](#mrb-berekenen)
-- [Betalen naar gebruik](#betalen-naar-gebruik)
-- [Gebruik met RDW data](#gebruik-met-rdw-data)
-- [Onregelmatigheden](#onregelmatigheden)
-- [Roadmap](#roadmap)
+- [CLI](#cli)
+  - [Installation](#installation)
+  - [Usage](#usage)
+- [SDK](#sdk)
+  - [Installation](#installation-1)
+  - [Usage](#usage-1)
 - [Credits](#credits)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
-## Installatie
+## CLI
+
+### Installation
 
 ```bash
-yarn|npm add motorrijtuigenbelasting
+yarn|npm add @motorrijtuigenbelasting/cli
 ```
 
-## MRB berekenen
+### Usage
 
-Standaard wordt het meest recente `Model_2023` gebruikt.
+Show help:
 
-```js
-import {
-  berekenMrb,
-  Brandstof,
-  Provincie,
-  Voertuigtype,
-} from "motorrijtuigenbelasting";
-
-// bedrag is motorrijtuigenbelasting per tijdvak van 3 maanden in euro's
-const bedrag = berekenMrb({
-  voertuigtype: Voertuigtype.Personenauto,
-  brandstof: Brandstof.Benzine,
-  elektrisch_of_waterstof: false,
-  gewicht: 1051,
-  provincie: Provincie.Utrecht,
-});
-```
+```bash
+# yarn
+yarn dlx @motorrijtuigenbelasting/cli --help
 
-## Betalen naar gebruik
+# npm
+npx @motorrijtuigenbelasting/cli --help
+```
 
-Om een voorlopige berekening te maken voor het toekomstige "Betalen naar
-gebruik", kan `model` worden aangepast naar `Model_2030`.
+Example with manual input:
 
-```js
-import {
-  berekenMrb,
-  Brandstof,
-  Models,
-  Provincie,
-  Voertuigtype,
-} from "motorrijtuigenbelasting";
-
-// voorlopige berekening voor betalen naar gebruik
-const bedrag = berekenMrb({
-  model: Models.Model_2030,
-  voertuigtype: Voertuigtype.Personenauto,
-  brandstof: Brandstof.Benzine,
-  elektrisch_of_waterstof: false,
-  gewicht: 1051,
-  provincie: Provincie.Utrecht,
-  km_per_jaar: 10_000,
-});
+```bash
+yarn dlx|npx @motorrijtuigenbelasting/cli \
+  --vehicle-type Personenauto \
+  --weight 1051 \
+  --propulsion-type Benzine \
+  --propulsion-emission 86 \
+  --province Utrecht
 ```
 
-## Gebruik met RDW data
-
-```js
-import { berekenMrb, rdwDataToParams } from "motorrijtuigenbelasting";
+Example with vehicle ID (kenteken) as input:
 
-const kenteken = "1-ABC-123";
+```bash
+export RDW_APP_TOKEN=foo
+yarn dlx|npx @motorrijtuigenbelasting/cli \
+  --vehicle-id S-212-PK
+```
 
-const rdw = (resource) =>
-  fetch(
-    `https://opendata.rdw.nl/resource/${resource}.json?kenteken=${kenteken}`
-  ).then((res: any) => res.json());
+> **Note**: App token can be obtained after registering at the
+> [RDW open data portal](https://opendata.rdw.nl/signup).
 
-const basis = (await rdw("m9d7-ebf2"))[0];
-const brandstof = await rdw("8ys7-d773");
+## SDK
 
-const params = rdwDataToParams({ basis, brandstof });
+### Installation
 
-// bedrag is motorrijtuigenbelasting per tijdvak van 3 maanden in euro's
-const bedrag = berekenMrb({ ...params, provincie: Provincie.Utrecht });
+```bash
+yarn|npm add @motorrijtuigenbelasting/core @motorrijtuigenbelasting/mrb2023
 ```
 
-## Onregelmatigheden
-
-Onregelmatigheden zijn verschillen van dit algoritme met de
-[officiele tool van de Belastingdienst](https://www.belastingdienst.nl/wps/wcm/connect/nl/auto-en-vervoer/content/hulpmiddel-motorrijtuigenbelasting-berekenen)
-(_baseline_). Zie [TODO.md](TODO.md) voor een lijst met onregelmatigheden.
+> **Note**: When you want to use a different revision of the car tax law, use
+> the corresponding package. See elsewhere in this README to see a list of
+> supported revisions.
 
-## Roadmap
+### Usage
 
-- [ ] Personenauto
-  - [x] Benzine
-  - [x] Diesel
-  - [x] Geen uitstoot (elektrisch of waterstof)
-  - [x] Lage uitstoot (halftarief)
-  - [ ] Overige brandstoffen
-- [ ] Overige voertuigtypes
+```js
+import {
+  PropulsionType,
+  Province,
+  run,
+  VehicleType,
+} from "@motorrijtuigenbelasting/core";
+import mrb2023 from "@motorrijtuigenbelasting/mrb2023";
+
+const params = {
+  vehicleType: VehicleType.Personenauto,
+  weight: 1051,
+  propulsions: [{ type: PropulsionType.Benzine, emission: 86 }],
+  province: Province.Utrecht,
+};
+
+const results = run(mrb2023, params, period);
+
+console.log({ results });
+```
 
 ## Credits
 

diff --git a/packages/cli/src/index.ts b/packages/cli/src/index.ts
@@ -15,8 +15,8 @@ import yaml from "js-yaml";
 const cmd = command()
   .default()
   .description("Calculate the tax (motorrijtuigenbelasting) for a car")
-  .option("kenteken", {
-    description: "The license plate number of the car",
+  .option("vehicle-id", {
+    description: "The vehicle id/license plate number (kenteken) of the car",
     type: "string",
   })
   .option("rdw-app-token", {
@@ -65,7 +65,7 @@ const cmd = command()
   })
   .action(
     async ({
-      kenteken,
+      "vehicle-id": vehicleId,
       "rdw-app-token": rdwAppToken,
       "vehicle-type": vehicleType,
       weight,
@@ -78,7 +78,7 @@ const cmd = command()
     }) => {
       let params: Params;
 
-      if (kenteken) {
+      if (vehicleId) {
         if (!rdwAppToken) {
           throw new InvalidArgument("missing rdw-app-token");
         }
@@ -94,7 +94,7 @@ const cmd = command()
           );
         }
 
-        params = await vehicleIdToParams(kenteken, rdwAppToken);
+        params = await vehicleIdToParams(vehicleId, rdwAppToken);
       } else {
         params = {
           vehicleType,
@@ -114,21 +114,23 @@ const cmd = command()
       switch (format) {
         case "js":
           console.dir(
-            { kenteken, params, mrb2023: mrb2023results },
+            { vehicleId, params, mrb2023: mrb2023results },
             { depth: null }
           );
           break;
         case "json":
           console.log(
             JSON.stringify(
-              { kenteken, params, mrb2023: mrb2023results },
+              { vehicleId, params, mrb2023: mrb2023results },
               null,
               2
             )
           );
           break;
         case "yaml":
-          console.log(yaml.dump({ kenteken, params, mrb2023: mrb2023results }));
+          console.log(
+            yaml.dump({ vehicleId, params, mrb2023: mrb2023results })
+          );
           break;
         case "table":
           console.log("Input:");