@syncbridge/common 2.0.1 → 2.2.0

package/README.md

@@ -117,7 +117,7 @@ property's TypeScript type when not given. Some options:
 
 | Option | Meaning |
 | --- | --- |
-| `label`, `description` | How it is shown |
+| `label`, `description` | How it is shown: text, or text by language - `{ en: 'Port', tr: 'Bağlantı noktası' }` - shown in the reader's language in the server's UI and the Marketplace, else in English |
 | `type` | `VariableType`: `String`, `Secret` (a password or key, kept encrypted in the profile), `Number`, `BigInt`, `Boolean`, `Enum`, `Nested` |
 | `default`, `required` | Its default value, and whether it must be given |
 | `enumValues` | The values of an enum |

package/constants.d.ts

@@ -1,4 +1,4 @@
-export declare const version = "2.0.1";
+export declare const version = "2.2.0";
 export declare const CLASS_METADATA: unique symbol;
 export declare const CLASS_TYPE: unique symbol;
 export declare const VARIABLE_CONTAINER: unique symbol;

package/constants.js

@@ -1,4 +1,4 @@
-export const version = '2.0.1';
+export const version = '2.2.0';
 export const CLASS_METADATA = Symbol.for('CLASS_METADATA');
 export const CLASS_TYPE = Symbol.for('CLASS_TYPE');
 export const VARIABLE_CONTAINER = Symbol.for('VARIABLE_CONTAINER');

package/host-link/host-link.d.ts

@@ -41,3 +41,5 @@ export type HostLinkMessage = HostStatusMessage;
 export declare const CONSOLE_USER_HEADER = "x-sb-console-user";
 export declare const CONSOLE_USER_NAME_HEADER = "x-sb-console-user-name";
 export declare const CONSOLE_ROLE_HEADER = "x-sb-console-role";
+/** What the user may do inside the host: HostPermission values, comma-separated */
+export declare const CONSOLE_PERMISSIONS_HEADER = "x-sb-console-permissions";

package/host-link/host-link.js

@@ -51,3 +51,5 @@ export function summarizeWorkers(workers) {
 export const CONSOLE_USER_HEADER = 'x-sb-console-user';
 export const CONSOLE_USER_NAME_HEADER = 'x-sb-console-user-name';
 export const CONSOLE_ROLE_HEADER = 'x-sb-console-role';
+/** What the user may do inside the host: HostPermission values, comma-separated */
+export const CONSOLE_PERMISSIONS_HEADER = 'x-sb-console-permissions';

package/host-link/host-permissions.d.ts

@@ -0,0 +1,44 @@
+/**
+ * What a user may do inside a host. Console grants them to an
+ * organization's members and passes them on with each request
+ * (CONSOLE_PERMISSIONS_HEADER); the host's own users have their role's.
+ */
+export declare enum HostPermission {
+    /** Seeing the workers, their logs and configuration, and the settings */
+    WorkersView = "host.workers.view",
+    /** Starting, stopping and initializing workers */
+    WorkersControl = "host.workers.control",
+    /** Changing a worker's configuration and its log channels */
+    WorkersConfigure = "host.workers.configure",
+    /** Adding workers */
+    WorkersCreate = "host.workers.create",
+    /** Removing workers */
+    WorkersDelete = "host.workers.delete",
+    /** Changing the host's settings, uploading packages */
+    Settings = "host.settings",
+    /** Updating SyncBridge */
+    Updates = "host.updates",
+    /** The host's own users */
+    Users = "host.users",
+    /** Pairing with Console, restoring, restarting SyncBridge */
+    System = "host.system",
+    /**
+     * Installing packages from the registry: Console's own permission, sent
+     * with its installs
+     */
+    Install = "hosts.install"
+}
+/** The roles inside a host, each a set of permissions */
+export type HostRole = 'viewer' | 'operator' | 'admin';
+/**
+ * The permissions of each role: a host's own users', and a user's whose
+ * Console sends a role alone (one older than the permissions)
+ */
+export declare const HOST_ROLE_PERMISSIONS: Readonly<Record<HostRole, readonly HostPermission[]>>;
+/** The permissions of a role; none for a role not known */
+export declare function hostRolePermissions(role: string | undefined | null): HostPermission[];
+/**
+ * The permissions a CONSOLE_PERMISSIONS_HEADER value gives: comma-separated,
+ * those not known dropped. No header, undefined: the role's to be taken.
+ */
+export declare function parseHostPermissions(value: string | undefined | null): HostPermission[] | undefined;

package/host-link/host-permissions.js

@@ -0,0 +1,66 @@
+/**
+ * What a user may do inside a host. Console grants them to an
+ * organization's members and passes them on with each request
+ * (CONSOLE_PERMISSIONS_HEADER); the host's own users have their role's.
+ */
+export var HostPermission;
+(function (HostPermission) {
+    /** Seeing the workers, their logs and configuration, and the settings */
+    HostPermission["WorkersView"] = "host.workers.view";
+    /** Starting, stopping and initializing workers */
+    HostPermission["WorkersControl"] = "host.workers.control";
+    /** Changing a worker's configuration and its log channels */
+    HostPermission["WorkersConfigure"] = "host.workers.configure";
+    /** Adding workers */
+    HostPermission["WorkersCreate"] = "host.workers.create";
+    /** Removing workers */
+    HostPermission["WorkersDelete"] = "host.workers.delete";
+    /** Changing the host's settings, uploading packages */
+    HostPermission["Settings"] = "host.settings";
+    /** Updating SyncBridge */
+    HostPermission["Updates"] = "host.updates";
+    /** The host's own users */
+    HostPermission["Users"] = "host.users";
+    /** Pairing with Console, restoring, restarting SyncBridge */
+    HostPermission["System"] = "host.system";
+    /**
+     * Installing packages from the registry: Console's own permission, sent
+     * with its installs
+     */
+    HostPermission["Install"] = "hosts.install";
+})(HostPermission || (HostPermission = {}));
+const VIEWER = [HostPermission.WorkersView];
+const OPERATOR = [
+    ...VIEWER,
+    HostPermission.WorkersControl,
+    HostPermission.WorkersConfigure,
+    HostPermission.WorkersCreate,
+    HostPermission.Install,
+];
+/**
+ * The permissions of each role: a host's own users', and a user's whose
+ * Console sends a role alone (one older than the permissions)
+ */
+export const HOST_ROLE_PERMISSIONS = {
+    viewer: VIEWER,
+    operator: OPERATOR,
+    admin: Object.values(HostPermission),
+};
+const KNOWN = new Set(Object.values(HostPermission));
+/** The permissions of a role; none for a role not known */
+export function hostRolePermissions(role) {
+    return [...(HOST_ROLE_PERMISSIONS[role] || [])];
+}
+/**
+ * The permissions a CONSOLE_PERMISSIONS_HEADER value gives: comma-separated,
+ * those not known dropped. No header, undefined: the role's to be taken.
+ */
+export function parseHostPermissions(value) {
+    if (value == null)
+        return;
+    const given = value
+        .split(',')
+        .map(s => s.trim())
+        .filter(s => KNOWN.has(s));
+    return [...new Set(given)];
+}

package/index.d.ts

@@ -16,6 +16,7 @@ export * from './decorators/log-channel.decorator.js';
 export * from './host-link/host-identity.js';
 export * from './host-link/host-link.js';
 export * from './host-link/host-packages.js';
+export * from './host-link/host-permissions.js';
 export * from './host-link/host-workers.js';
 export * from './host-link/multiplexer.js';
 export * from './host-link/sealed-box.js';
@@ -26,6 +27,7 @@ export * from './models-document.js';
 export * from './registry/docs-sidebar.js';
 export * from './registry/extension-package.js';
 export * from './registry/extension-registry.js';
+export * from './registry/localized-text.js';
 export * from './registry/module-catalog.js';
 export * from './registry/package-docs.js';
 export * from './registry/package-manifest.js';

package/index.js

@@ -16,6 +16,7 @@ export * from './decorators/log-channel.decorator.js';
 export * from './host-link/host-identity.js';
 export * from './host-link/host-link.js';
 export * from './host-link/host-packages.js';
+export * from './host-link/host-permissions.js';
 export * from './host-link/host-workers.js';
 export * from './host-link/multiplexer.js';
 export * from './host-link/sealed-box.js';
@@ -26,6 +27,7 @@ export * from './models-document.js';
 export * from './registry/docs-sidebar.js';
 export * from './registry/extension-package.js';
 export * from './registry/extension-registry.js';
+export * from './registry/localized-text.js';
 export * from './registry/module-catalog.js';
 export * from './registry/package-docs.js';
 export * from './registry/package-manifest.js';

package/models/metadata/variable-metadata.d.ts

@@ -1,3 +1,4 @@
+import type { LocalizedText } from '../../registry/localized-text.js';
 import { EnumSource } from '../enums/enum-source.enum.js';
 import { VariableFormat } from '../enums/variable-format.enum.js';
 import { VariableType } from '../enums/variable-type.enum.js';
@@ -14,8 +15,8 @@ export declare class VariableMetadata {
     ignored?: boolean;
     index?: number;
     hotPlug?: boolean;
-    label?: string;
-    description?: string;
+    label?: LocalizedText;
+    description?: LocalizedText;
     examples?: string[];
     choice?: string[];
     type?: VariableType;

package/models/metadata/variable-metadata.js

@@ -36,15 +36,17 @@ __decorate([
 ], VariableMetadata.prototype, "hotPlug", void 0);
 __decorate([
     ApiField({
-        description: 'Label of the variable',
+        description: "Its label: text, or text by language ({ en: '...', tr: '...' }) - shown in the server's UI and the Marketplace in the reader's language",
+        type: 'any',
     }),
-    __metadata("design:type", String)
+    __metadata("design:type", Object)
 ], VariableMetadata.prototype, "label", void 0);
 __decorate([
     ApiField({
-        description: 'App description',
+        description: "What it is for: text, or text by language ({ en: '...', tr: '...' })",
+        type: 'any',
     }),
-    __metadata("design:type", String)
+    __metadata("design:type", Object)
 ], VariableMetadata.prototype, "description", void 0);
 __decorate([
     ApiField({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncbridge/common",
-  "version": "2.0.1",
+  "version": "2.2.0",
   "description": "SyncBridge Common utilities",
   "author": "Panates Inc",
   "license": "MIT",

package/registry/docs-sidebar.d.ts

@@ -1,3 +1,4 @@
+import type { LocalizedText } from './localized-text.js';
 /**
  * How a package's documents are listed, where its author tells it: a
  * sidebar.json in docs/ (the package's own) or in docs/<ClassName>/ (an
@@ -21,7 +22,7 @@
  */
 export declare const SIDEBAR_FILE = "sidebar.json";
 /** Text, or text by language: { "tr": "Ağ", "en": "Network" } */
-export type SidebarText = string | Record<string, string>;
+export type SidebarText = LocalizedText;
 /** An item of a sidebar, as its author writes it */
 export type SidebarItemSource = string | {
     doc: string;

package/registry/localized-text.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Text, or text by language: { en: 'Port number', tr: 'Port numarası' }.
+ * A text alone is in the package's docs language.
+ */
+export type LocalizedText = string | Record<string, string>;
+/**
+ * A text in the language asked for: else in its base language ("pt" for
+ * "pt-BR"), else in English, else the first told; a text alone as it is
+ */
+export declare function textIn(text: LocalizedText | undefined, language: string): string | undefined;
+/**
+ * What is wrong with a text told by language: a key not a language, a
+ * text empty; a text alone, or none, is right
+ */
+export declare function localizedTextProblems(text: unknown, what: string): string[];
+/** The settings of a definition: those of a group under it too */
+interface VariableTexts {
+    label?: unknown;
+    description?: unknown;
+    variables?: Record<string, VariableTexts>;
+}
+/**
+ * What is wrong with the labels and descriptions of an app's, a
+ * component's or a plugin's settings, those in groups too: each by its
+ * path ("ClassName's tls.cert label")
+ */
+export declare function variableTextProblems(variables: Record<string, VariableTexts> | undefined, owner: string, at?: string): string[];
+export {};

package/registry/localized-text.js

@@ -0,0 +1,49 @@
+import { isDocsLanguage } from './package-docs.js';
+/**
+ * A text in the language asked for: else in its base language ("pt" for
+ * "pt-BR"), else in English, else the first told; a text alone as it is
+ */
+export function textIn(text, language) {
+    if (text === undefined || typeof text === 'string')
+        return text;
+    return (text[language] ??
+        text[language.split('-')[0]] ??
+        text.en ??
+        Object.values(text)[0]);
+}
+/**
+ * What is wrong with a text told by language: a key not a language, a
+ * text empty; a text alone, or none, is right
+ */
+export function localizedTextProblems(text, what) {
+    if (text === undefined || (typeof text === 'string' && text.trim()))
+        return [];
+    if (!text || typeof text !== 'object' || Array.isArray(text))
+        return [`${what} is text, or text by language: { en: '...', tr: '...' }`];
+    const entries = Object.entries(text);
+    if (!entries.length)
+        return [`${what} is text, or text by language: { en: '...', tr: '...' }`];
+    const problems = [];
+    for (const [language, value] of entries) {
+        if (!isDocsLanguage(language))
+            problems.push(`${what} is told in "${language}", not a language: en, tr, pt-BR...`);
+        else if (typeof value !== 'string' || !value.trim())
+            problems.push(`${what} in ${language} is empty`);
+    }
+    return problems;
+}
+/**
+ * What is wrong with the labels and descriptions of an app's, a
+ * component's or a plugin's settings, those in groups too: each by its
+ * path ("ClassName's tls.cert label")
+ */
+export function variableTextProblems(variables, owner, at = '') {
+    const problems = [];
+    for (const [key, v] of Object.entries(variables ?? {})) {
+        if (!v || typeof v !== 'object')
+            continue;
+        const path = at + key;
+        problems.push(...localizedTextProblems(v.label, `${owner}'s ${path} label`), ...localizedTextProblems(v.description, `${owner}'s ${path} description`), ...variableTextProblems(v.variables, owner, `${path}.`));
+    }
+    return problems;
+}

package/registry/module-catalog.d.ts

@@ -1,7 +1,8 @@
+import type { LocalizedText } from './localized-text.js';
 export declare const SUMMARY_MAX_LENGTH = 160;
 export declare const SCREENSHOTS_MAX = 8;
 /** A summary as told: one in the package's docs language, or one per language */
-export type ModuleSummary = string | Record<string, string>;
+export type ModuleSummary = LocalizedText;
 /** What the Marketplace is told of a module, as its makers wrote it */
 export interface ModuleCatalogInput {
     className: string;