Rewrite client wrapper in TypeScript

[TheNoim]

Benefits:

• module safety
• better typescript support
• nicer docs
• better support for esmodules

[elias-knodel]

@TheNoim Hey there, is there anything new / any updates to this yet? ^^

[TheNoim]

At some point I began rewriting the client in ts, but I stopped, because I had no time. Maybe I will do it in a few weeks. The only thing is, I am not really sure how I should manage it. An rewrite would be the perfect time to support native ecmascript modules. But, this could break the commonjs support or maybe even some platforms.

[TheNoim]

I mean, meanwhile there are typescript defintions :)

[arnim279]

Hi, I am working on a project that involves the WebUntis API and when I first saw this repo I just skimmed over the source code and everything looked messy and unmaintained to me since was all put into a single file written in JS and so I just started to write my own client for the features I needed. In hindsight, I should've taken a closer look at this repository, because it seems to be relatively active and has support and documentation for all the WebUntis features I failed to find documentation for.

But to get to the point: My client is written in TypeScript, uses ES modules and node-fetch (maybe I'll switch to the internal fetch API at some point but I need node 16 support atm) and I tried to structure the source code properly. If you want, you can take a look at the repo here.

It does however only cover a very small part of the WebUntis API, it uses the jsonrpc.do API (and even there I left some methods out), unlike your library which also supports the internal API, QR Codes and much more. If you want me to, I could rewrite this library in TypeScript and add more structure to the codebase. I also added a schema validator to my client that typechecks responses - but since you have the official documentation, this may not be needed here. Are you still interested in a rewrite? I don't want to force anything on you as a first-time-contributor, this would be a very big change and it's your project after all.

One last thing: When I asked WebUntis which API I should use (internal or "public"), they said that the "JSON-API" will be deprecated by Summer 2023 and told me I could register for a new API here. Do you know anything about this?

[TheNoim]

I am working on a project that involves the WebUntis API and when I first saw this repo I just skimmed over the source code and everything looked messy and unmaintained to me since was all put into a single file written in JS and so I just started to write my own client for the features I needed. In hindsight, I should've taken a closer look at this repository, because it seems to be relatively active and has support and documentation for all the WebUntis features I failed to find documentation for.

This is true. At the beginning this library was only meant for myself. At its core it was a toy library and at some point more people started to use it. This made it more difficult to change the structure of the API without breaking anything. And because I never really had time to invest in a suitable rewrite, it remained the same.

But to get to the point: My client is written in TypeScript, uses ES modules and node-fetch (maybe I'll switch to the internal fetch API at some point but I need node 16 support atm) and I tried to structure the source code properly. If you want, you can take a look at the repo here.

It does however only cover a very small part of the WebUntis API, it uses the jsonrpc.do API (and even there I left some methods out), unlike your library which also supports the internal API, QR Codes and much more. If you want me to, I could rewrite this library in TypeScript and add more structure to the codebase. I also added a schema validator to my client that typechecks responses - but since you have the official documentation, this may not be needed here. Are you still interested in a rewrite? I don't want to force anything on you as a first-time-contributor, this would be a very big change and it's your project after all.

I never did a re-write, because I wanted to keep the compatibility with the current API. But to be fair, it may not be so important after all. I would appreciate help with a rewrite. After all, I am not a student anymore. I always try to look after this library to the best of my ability.

One last thing: When I asked WebUntis which API I should use (internal or "public"), they said that the "JSON-API" will be deprecated by Summer 2023 and told me I could register for a new API here. Do you know anything about this?

This is correct. I know this for a few years now, but nothing happened. The API stayed the same. I think they plan to build a platform API. Do you know MS Teams Apps? The small "extensions" inside of Teams? Something similar like this. The thing with this however is, it is probably more meant for paying partners and not for toy or smaller project. I can be wrong, but I think at some point only the reverse engineered APIs will stay.

I hope I am wrong, because for students starting programming this is awesome. Having an actual use case for coding helps to learn quickly. This was not my only project with Untis. With the knowledge I gained here I build many small utilities and other projects. Obviously, this is all in the past. But sometimes I search on Github for projects using this library and yes, some students use this lib to have their first programming experience and that's awesome.

tl;dr: Yes, I would appreciate a re-write.

[arnim279]

I wont't have time to start this until 2 weeks from now, but I'll open a PR when I have some changes for you to review, unless someone else does so in the meantime. Sorry for the very delayed response btw

[wolflu05]

For the meantime, does anyone have a workaround how to get this to work with typescript currently as I can't import it correctly.

Steps to reproduce

mkdir test-webuntis
cd test-webuntis
npm i webuntis typescript
npx tsc --init
vim index.ts
npx tsc index.ts
cat index.js

index.ts:

import WebUntis from 'webuntis';
const untis = new WebUntis(...);

gets translated via tsc to: index.js:

"use strict";
exports.__esModule = true;
var webuntis_1 = require("webuntis");
new webuntis_1["default"]();

however 'default' doesn't exist on that library.

If I try to import * as WebUntis from 'webuntis' I get the following transpiration error:

index.ts:3:5 - error TS2351: This expression is not constructable.
  Type 'typeof import("webuntis")' has no construct signatures.

3 new WebUntis("...", "...", "...", "...");
      ~~~~~~~~

Found 1 error in index.ts:3

[arnim279]

@wolflu05 I was able to reproduce the error, I fixed it it by setting "type": "module" in your package.json and adding

"target": "ES2022",
"module": "ES2022",
"moduleResolution": "NodeNext"

to your tsconfig compilerOptions. If you do this, your package will use ES Modules which for you means that you'll have to add .js to your file imports, most other things should stay the same. Maybe there are other solutions if you don't want to use ES modules

[wolflu05]

@arnim279 in my real usecase I use nestjs and I don't want to change much in the tsconfig. Isn't there any other way of getting this to work?

[arnim279]

I asked some friends for help since I don't have any experience with CommonJS and the reason seems to be that the type definition is wrong since it's not a default export. If you want to use CommonJS you'll have to wait for it to be updated. I don't have time tomorrow and will be on a school trip starting Sunday so I can't update the definition, sorry cc @TheNoim

[wolflu05]

Any updates on this? My current solution is not optimal. I added the following to my project:

package.json:

  "scripts": {
    "postinstall": "patch-package"
  },
  "devDependencies": {
    "patch-package": "^6.4.7"
  }

patches/webuntis+1.22.1.patch:

diff --git a/node_modules/webuntis/index.d.ts b/node_modules/webuntis/index.d.ts
index 4a8f652..5dcf41d 100644
--- a/node_modules/webuntis/index.d.ts
+++ b/node_modules/webuntis/index.d.ts
@@ -317,7 +317,7 @@ declare module 'webuntis' {
         username: string;
     }

-    export default class WebUntis {
+    export class WebUntis {
         /**
          *
          * @param school Name of the school
diff --git a/node_modules/webuntis/index.js b/node_modules/webuntis/index.js
index ef84e20..5d2d786 100644
--- a/node_modules/webuntis/index.js
+++ b/node_modules/webuntis/index.js
@@ -1067,4 +1072,4 @@ WebUntis.TYPES = {
     STUDENT: 5,
 };

-module.exports = WebUntis;
+module.exports.WebUntis = WebUntis;