vertinho/README.md

Library to make conference apps and softphones through WebSockets with FreeSWITCH mod_verto.

# Vertinho
Library to make conference apps and softphones through WebSockets with FreeSWITCH mod_verto.

> Available on NPM: https://www.npmjs.com/package/vertinho

## Tutorial

Soon. when it becomes stable and testable enough.

## Licensing

The [original Verto JS](https://freeswitch.org/stash/projects/FS/repos/freeswitch/browse/html5/verto/js)
was written first depending of [JQuery](https://jquery.com/)
(and that's still the official version supported by
[FreeSWITCH](http://freeswitch.org/) team). It was made by
[Anthony Minessale II](https://github.com/anthmFS) who **copyrights it as Verto initial developer**
and created its backend code.
Later, my friend [Stefan Yohansson](https://github.com/StefanYohansson) remade it
[without JQuery](https://freeswitch.org/stash/projects/FS/repos/freeswitch/browse/html5/verto/js?at=refs%2Fheads%2Fbugfix%2FFS-10028-refactor-verto-lib-to-remove-jquery).
Also were part of it [Seven Du](mail-to:jiangxueyun@x-y-t.cn) and
[Xueyun Jiang](mail-to:jiangxueyun@x-y-t.cn) as contributors too and by extension the whole community.
Until then, the code was under
[MPL 1.1](https://tldrlegal.com/license/mozilla-public-license-1.1-(mpl-1.1)).

However, **I'm releasing Vertinho under
[MPL 2.0](https://tldrlegal.com/license/mozilla-public-license-2.0-(mpl-2))**
(an upgrade explicitly allowed by the first license), a strong copyleft license
compatible with GNU ones.

## Asking why rewrite what was already "good and running"?

This is an indie fork of the original Verto JQuery, but it's not a pointless refactoring.
Here are dozens of reasons if you're interested to know.

It's almost five years, frontend world had changed a lot, JS tools like JQuery
are currently ephemeral. And one of my goals here is to help the FreeSWITCH community
to follow the current JavaScript's state of the art.

So I'm specifically working on top of some problems that I encountered while
coding with old Verto in the past months contributing for its core and fixing bugs
of private forks. Disclaimer: I don't need to reveal closed source customizations or ideas here.
People only break Verto because it's hard to understand how it works and how it's architetured. It's
easier to make workarounds, patchs, adapters, shim layers... anything.

Here is what I intent to fix with Vertinho:
- It has static and outdated dependencies managed by manual "copy and paste":
  - like the JQuery itself or the WebRTC Adapter;
  - deprecated WebRTC API functions (like `RTCPeerConnection.addStream` which is now totally deprecated);
  - outdated WebRTC API usage (like `MediaDevices.getUserMedia` and `RTCPeerConnection.createOffer` that should be consumed using their `Promise`-based forms instead of passing callbacks as arguments).
- The library itself is not that good to be used as a dependency for others:
  - versioning is inexistent, depending entirely of FreeSWITCH releases;
  - no easily accessible changelogs;
  - almost an abandoned support of it on NPM package manager;
  - documentation consists only of a few examples that doesn't cover the entire API, since the people who wrote it aren't the same that developed it;
  - very redundant API (having more than one or two ways to change instance properties is confusing, specially when there are divergencies between them);
  - poorly parsed objects exposed (if you consume some of `LiveArray` messages, for example, you need to handle serialised JSON strings inside JS objects in arrays of unnamed data, which is more confusing than read this description);
  - bad error handling and messaging (for example, exceptions occured on a `getUserMedia` are always considered permission errors, which is not always true),
  - some ambiguous and implicit variable naming on exposed API (like `res`, `e` and `pvt` variables).
- Has too much responsibilities like manipulating the DOM:
  - most of JS UI libraries currently use Virtual DOM, then having Verto changing the DOM directly (like putting `MediaStream` into nodes from `getElementById`) could have been convenient in older days but today is just anti-pattern, causing conflicts and not helping that much;
  - having the library implicitly changing the UI style properties (like `display` to `block` or `none`) reduces the client developers control over their own applications.
- Lack of automated tests, making people afraid of changing code for paying technical debt or developing cutting edge features.
- Repository not in the same place as the majority of other JS libraries (i.e., GitHub), so is a less accessible for real frontend developers.
- License toxic for free source projects (old MPL is not GNU compatible).
- Difficult to debug issues on its core development:
  - great amount of side effects on the provided arguments (like the option `useCamera` being mutated from a string type into a document element);
  - a few side effects on internal methods (e.g., an inner `getUserMedia` that, despite being a getter, also acts as a setter and manipulates DOM);
  - weak transparency usage for parameters provided (e.g., `useCamera` is an unnecessary abstraction to browsers `deviceId` constraint);
  - a lot of unused variables and parameters;
  - greatly messed up indentation.

**Seriously, why?**
Rewriting Verto JS helps me to study deeper how all of it works. I couldn't learn nor work with it properly
if it's just black magic, accordingly with [Clark's third law](https://en.wikipedia.org/wiki/Clarke%27s_three_laws).

Also, I came from [a land where simple is better than complex](https://www.python.org/dev/peps/pep-0020/):