fix: replace SysLink & MetaLinkProps with Link<T> to improve type safety [CFISO-2344]

[andipaetzold]

SysLink is a frequently used type within CMA.js. Unfortunately, sys.type and sys.linkType are typed as string instead of "Link" and the expected entity name.

In this PR, SysLink is replaced with Link<T>. MetaLinkProps is adjusted accordingly. I also added a generic to MetaSysProps and BasicMetaSysProps to clearly define whether createdBy etc is only a user or could also be an app.

With Link<T> we gain additional type safety as sys.type is typed as "Link" and sys.linkType is typed as T.

SysLink and MetaLinkProps are deprecated and it's recommended to always use Link<T>.

I am not 100% confident on all link types. After an initial reviewed, I'd share this PR internally in case a team spots an inconsistency.

Open questions:

• Should we make all links to a subject (e.g. sys.createdBy) Link<'User'> | Link<'AppDefinition'>? Or check one by one whether that entity can be accessed by an app?
• Should we write Link<'User'> | Link<'AppDefinition'> or Link<'User' | 'AppDefinition'>? The result of the type checking should be identical.

This will be released as a breaking change in CMA.js v12

[marcolink]

@andipaetzold my thoughts to your questions:
In general, I'd prefer to narrow down the possible actor (User, AppDefinition) as it will make it easier to resolve it if required.
Does entities exposed in the App SDK map to entities that can have AppDefinition as a actor?

About how to write the type - I don't have a preference :)

[marcolink]

❤️ for proper deprecation

[andipaetzold]

Does entities exposed in the App SDK map to entities that can have AppDefinition as a actor?

Good idea. I went through the list and updated the PR to match the App SDK capabilities

[jjolton-contentful]

Should we write Link<'User'> | Link<'AppDefinition'> or Link<'User' | 'AppDefinition'>? The result of the type checking should be identical.

I did notice a subtle difference between these two options:

Link<'User'> | Link<'AppDefinition'>: preserves the identity of each linkType

Link<'User' | 'AppDefinition'>: allows linkType to be a union, but we lose the ability to discriminate by type in TypeScript

I prefer Link<'User'> | Link<'AppDefinition'>, because then we can do:

if (link.sys.linkType === 'User') {
  // Now TypeScript knows it's a Link<'User'>
}

[andipaetzold]

As we agreed to release this in a new major version, I made a change to completely remove SysLink and MetaLinkProps.