@peter.prib/renderengine 0.4.0 → 0.5.0

package/REFERENCE.md

@@ -2614,6 +2614,16 @@ open model:
   or title. Ids are the tracker's keys, so a newer export brought in replaces what it had. Where each tracker keeps
   each field is data (`TRACKERS`); a team's own column is given with `new TrackerExport({ columns: { criteria:
   ['Done when'] } })` (in Jira's JSON, a custom field's key).
+- **A tracker, live** (`TrackerApi`; `JiraApi`, `AzureDevOpsApi`, `GitLabApi`): the issues a connection names, read
+  through the tracker's API page by page — Jira by JQL (a project's by default; Cloud with an email and API token,
+  Server / Data Center with a personal access token), Azure DevOps by WIQL (a project's work items but its tasks,
+  200 at a time, each linked to its page in Boards), GitLab a project's issues (open and closed, filtered as its
+  issues API filters). `read()` is the JSON `TrackerExport` reads, `model()` the model's spec, named as the
+  connection is; at most `maxIssues` (5000) are read, `truncated` saying when there were more. `fetch` is given,
+  since a tracker's token belongs where the request is made (a server); an error says what the tracker answered,
+  never the token. What a connection asks for is each class's `fields` (`trackerConnectionFields()`: per tracker,
+  `{key, label, type?, choices?, required?, secret?, placeholder?, hint?}`), for a host to build its form from;
+  `problems()` what is missing before the tracker is asked.
 - **A storyboard** (`StoryboardFileFormat`, `Storyboard`): Markdown — a `#` title names it, `##` are epics (or any
   heading saying *Epic*), `###` stories (or *Story*); "As a … I want …" list items under an epic are stories; a
   picture is kept by its caption.
@@ -2623,6 +2633,11 @@ const { RequirementsModel, TrackerExport } = window.RenderEngine;
 const model = new RequirementsModel(new TrackerExport().read(jiraCsvText));
 model.storyMap().columns.map(c => c.name);   // the epics, across
 model.coverage().criteriaShare;              // how many stories say when they are done
+
+// The same, live — on a server, where the token is kept:
+const api = trackerApi({ tracker: 'jira', name: 'Shop backlog', baseUrl: 'https://shop.atlassian.net',
+    user: 'me@example.com', token: process.env.JIRA_TOKEN, project: 'SHOP' }, { fetch });
+const live = new RequirementsModel(await api.model());
 ```
 
 `RequirementsPart` (type `requirements`, in a `ModelsPart` with `editorType: 'requirements'`) shows the model as

package/dist/renderengine-workspace.umd.js

@@ -49300,15 +49300,16 @@
             return found?.[0] ?? null;
         }
 
-        /** @private */
+        /** @private — an API's JSON, given as text or already parsed. */
         static _json(text) {
+            if (text && typeof text === 'object') return text;
             const s = String(text ?? '').trim();
             if (!s.startsWith('{') && !s.startsWith('[')) return null;
             try { return JSON.parse(s); } catch { return null; }
         }
 
         /**
-         * The export as a requirements model's spec.
+         * The export (its text; an API's JSON as text or parsed — TrackerApi) as a requirements model's spec.
          * @returns {{epics: Array, releases: Array, stories: Array, tracker: string|null}}
          */
         read(text) {
@@ -49542,6 +49543,329 @@
         }
     }
 
+    /** Text as base64, whatever its characters (btoa takes only Latin-1). */
+    function base64(text) {
+        const bytes = new TextEncoder().encode(String(text));
+        let binary = '';
+        for (const b of bytes) binary += String.fromCharCode(b);
+        return btoa(binary);
+    }
+
+    /**
+     * TrackerApi — a tracker read through its API rather than from an export: the
+     * issues a connection names, page by page, as the JSON `TrackerExport` reads
+     * (so an API's answer and a file saved from it make the same model). A
+     * subclass per tracker (`JiraApi`, `AzureDevOpsApi`, `GitLabApi`) says where
+     * its issues are, how it pages and how it is signed in to; what a connection
+     * asks for is `fields`, which a host builds its form from.
+     *
+     * `fetch` is given (a server's, or a test's): a tracker's token belongs where
+     * the request is made, which is seldom a browser. Nothing here keeps or logs
+     * the token; an error says what the tracker answered, not what was sent.
+     */
+    class TrackerApi {
+        /** The tracker's key in TRACKERS ('jira'). */
+        static tracker = null;
+
+        /** Most issues read from one connection: a connection naming a whole site is stopped there (`truncated`). */
+        static MAX_ISSUES = 5000;
+
+        /**
+         * What a connection asks for, in order: `{key, label, type?, choices?,
+         * required?, secret?, placeholder?, hint?}` — `secret` written, never
+         * shown back. The tracker's own between its address and its token.
+         */
+        static get fields() {
+            return [
+                { key: 'name', label: 'Name', required: true, placeholder: 'What people pick it by, e.g. "Shop backlog"' },
+                { key: 'baseUrl', label: 'Address', required: true, placeholder: this.baseUrlPlaceholder },
+                ...this.ownFields,
+                { key: 'token', label: 'Token', type: 'password', required: true, secret: true, hint: this.tokenHint },
+            ];
+        }
+
+        /** @protected */
+        static get ownFields() { return []; }
+
+        /** @protected */
+        static baseUrlPlaceholder = 'https://…';
+
+        /** @protected */
+        static tokenHint = 'An access token that may read the issues';
+
+        /**
+         * @param {Object} connection - Its `fields`' values (and `columns`, a TrackerExport's own columns)
+         * @param {Object} [options]
+         * @param {Function} [options.fetch] - The fetch to read with (default: the global one)
+         * @param {number} [options.maxIssues] - Most issues read (default MAX_ISSUES)
+         */
+        constructor(connection, { fetch = globalThis.fetch, maxIssues = new.target.MAX_ISSUES } = {}) {
+            this.connection = connection ?? {};
+            this.fetch = fetch;
+            this.maxIssues = maxIssues;
+            /** Whether the last read stopped at maxIssues. */
+            this.truncated = false;
+        }
+
+        get tracker() { return this.constructor.tracker; }
+
+        /** What the tracker is called ('Jira'). */
+        get label() { return TrackerExport.label(this.tracker); }
+
+        /** What is wrong with the connection, before anything is asked of the tracker: messages, none when it will do. */
+        problems() {
+            const c = this.connection;
+            const out = this.constructor.fields.filter(f => f.required && !String(c[f.key] ?? '').trim()).map(f => `${f.label} is needed.`);
+            if (c.baseUrl && !/^https?:\/\/[^\s/]+/i.test(String(c.baseUrl).trim())) out.push(`Address must start http:// or https:// ("${c.baseUrl}").`);
+            return out;
+        }
+
+        /** The issues, as the tracker's API gives them (the JSON TrackerExport reads). */
+        async read() {
+            const problems = this.problems();
+            if (problems.length) throw new Error(`${this.label} connection "${this.connection.name ?? ''}": ${problems.join(' ')}`);
+            this.truncated = false;
+            return this._read();
+        }
+
+        /** The issues as a requirements model's spec, named as the connection is. */
+        async model() {
+            const json = await this.read();
+            const { tracker, ...spec } = new TrackerExport({ tracker: this.tracker, columns: this.connection.columns ?? {} }).read(json);
+            return { name: this.connection.name || `${this.label} issues`, ...spec };
+        }
+
+        /** @protected @abstract */
+        async _read() {
+            throw new Error(`${this.constructor.name} does not say how to read ${this.label}`);
+        }
+
+        /** The headers that sign in. @protected @abstract */
+        headers() {
+            return {};
+        }
+
+        /** A path on the tracker's address. @protected */
+        url(path) {
+            return `${String(this.connection.baseUrl).trim().replace(/\/+$/, '')}${path}`;
+        }
+
+        /**
+         * A request to the tracker, its answer's JSON and headers; an answer
+         * other than OK an error saying what the tracker said. @protected
+         */
+        async request(url, { method = 'GET', body } = {}) {
+            if (typeof this.fetch !== 'function') throw new Error('No fetch to read the tracker with');
+            const res = await this.fetch(url, {
+                method,
+                headers: { Accept: 'application/json', ...(body !== undefined ? { 'Content-Type': 'application/json' } : {}), ...this.headers() },
+                ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+            });
+            if (!res.ok) {
+                const text = await res.text().catch(() => '');
+                throw new Error(`${this.label} answered ${res.status}${res.statusText ? ` ${res.statusText}` : ''}${text ? `: ${text.slice(0, 300)}` : ''}`);
+            }
+            return { json: await res.json(), headers: res.headers };
+        }
+
+        /** Issues kept up to maxIssues; true once it is reached. @protected */
+        keep(into, more) {
+            for (const issue of more) {
+                if (into.length >= this.maxIssues) { this.truncated = true; return true; }
+                into.push(issue);
+            }
+            return into.length >= this.maxIssues;
+        }
+
+        /** @protected */
+        static base64 = base64;
+
+        /** @protected — the tracker's issue types not read (TRACKERS: its sub-tasks). */
+        get skipTypes() { return TRACKERS[this.tracker]?.skipTypes ?? []; }
+    }
+
+    /**
+     * Jira through its REST API: the issues a JQL query finds (a project's, by
+     * default), every field (custom ones too: story points, acceptance criteria).
+     * Jira Cloud signs in with an email and an API token and pages by token
+     * (`/rest/api/3/search/jql`); Jira Server and Data Center with a personal
+     * access token (no email), paging by offset (`/rest/api/2/search`).
+     */
+    class JiraApi extends TrackerApi {
+        static tracker = 'jira';
+
+        static PAGE = 100;
+
+        static baseUrlPlaceholder = 'https://your-site.atlassian.net';
+
+        static tokenHint = 'Jira Cloud: an API token (with the email above). Server / Data Center: a personal access token (no email).';
+
+        static get ownFields() {
+            return [
+                { key: 'edition', label: 'Jira', type: 'select', choices: [['cloud', 'Cloud'], ['server', 'Server / Data Center']], value: 'cloud' },
+                { key: 'user', label: 'Email', placeholder: 'The account the API token is for (Cloud)' },
+                { key: 'project', label: 'Project key', placeholder: 'SHOP — or leave it and give a JQL query' },
+                { key: 'query', label: 'JQL', placeholder: 'project = SHOP AND issuetype != Sub-task (instead of the project)' },
+            ];
+        }
+
+        problems() {
+            const out = super.problems();
+            if (!String(this.connection.project ?? '').trim() && !String(this.connection.query ?? '').trim()) out.push('A project key or a JQL query is needed.');
+            return out;
+        }
+
+        /** The JQL: the one given, else the project's issues in key order. */
+        get jql() {
+            const { query, project } = this.connection;
+            if (String(query ?? '').trim()) return String(query).trim();
+            return `project = "${String(project).trim().replace(/"/g, '\\"')}" ORDER BY key`;
+        }
+
+        headers() {
+            const { user, token } = this.connection;
+            return { Authorization: String(user ?? '').trim() ? `Basic ${TrackerApi.base64(`${String(user).trim()}:${token}`)}` : `Bearer ${token}` };
+        }
+
+        async _read() {
+            const issues = [];
+            const page = this.constructor.PAGE;
+            const query = (extra) => new URLSearchParams({ jql: this.jql, fields: '*all', maxResults: String(page), ...extra }).toString();
+            if (this.connection.edition === 'server') {
+                for (let startAt = 0; ; startAt += page) {
+                    const { json } = await this.request(this.url(`/rest/api/2/search?${query({ startAt: String(startAt) })}`));
+                    const got = json.issues ?? [];
+                    const more = got.length > 0 && startAt + got.length < (json.total ?? 0);
+                    if (this.keep(issues, got)) { this.truncated ||= more; break; }
+                    if (!more) break;
+                }
+            } else {
+                for (let token = null; ;) {
+                    const { json } = await this.request(this.url(`/rest/api/3/search/jql?${query(token ? { nextPageToken: token } : {})}`));
+                    const got = json.issues ?? [];
+                    token = json.isLast ? null : json.nextPageToken ?? null;
+                    if (this.keep(issues, got)) { this.truncated ||= !!token; break; }
+                    if (!token || !got.length) break;
+                }
+            }
+            return { issues };
+        }
+    }
+
+    /**
+     * Azure DevOps (Boards) through its REST API: a WIQL query for a project's
+     * work items (but its tasks — TRACKERS), then the items, 200 at a time. Signs
+     * in with a personal access token. Each item's link is its page in Boards.
+     */
+    class AzureDevOpsApi extends TrackerApi {
+        static tracker = 'azure';
+
+        /** Most ids one work-items request takes. */
+        static BATCH = 200;
+
+        static API_VERSION = '7.1';
+
+        static baseUrlPlaceholder = 'https://dev.azure.com/your-organisation';
+
+        static tokenHint = 'A personal access token with Work Items (Read)';
+
+        static get ownFields() {
+            return [
+                { key: 'project', label: 'Project', required: true, placeholder: 'The project, e.g. Shop' },
+                { key: 'query', label: 'WIQL condition', placeholder: "[System.AreaPath] UNDER 'Shop\\Checkout' (and the project's)" },
+            ];
+        }
+
+        headers() {
+            return { Authorization: `Basic ${TrackerApi.base64(`:${this.connection.token}`)}` };
+        }
+
+        /** The WIQL: the project's work items, not its tasks, and the condition given. */
+        get wiql() {
+            const types = this.skipTypes.map(t => `'${t.replace(/'/g, "''")}'`).join(', ');
+            const condition = String(this.connection.query ?? '').trim();
+            return `SELECT [System.Id] FROM WorkItems WHERE [System.TeamProject] = @project`
+                + (types ? ` AND [System.WorkItemType] NOT IN (${types})` : '')
+                + (condition ? ` AND (${condition})` : '')
+                + ' ORDER BY [System.Id]';
+        }
+
+        async _read() {
+            const project = encodeURIComponent(String(this.connection.project).trim());
+            const version = `api-version=${this.constructor.API_VERSION}`;
+            const { json } = await this.request(this.url(`/${project}/_apis/wit/wiql?${version}`), { method: 'POST', body: { query: this.wiql } });
+            const ids = (json.workItems ?? []).map(w => w.id);
+            const value = [];
+            for (let i = 0; i < ids.length; i += this.constructor.BATCH) {
+                const batch = ids.slice(i, i + this.constructor.BATCH);
+                const { json: items } = await this.request(this.url(`/${project}/_apis/wit/workitems?ids=${batch.join(',')}&${version}`));
+                const got = (items.value ?? []).map(w => ({ ...w, url: this.url(`/${project}/_workitems/edit/${w.id}`) }));
+                if (this.keep(value, got)) { this.truncated ||= i + batch.length < ids.length; break; }
+            }
+            return { value };
+        }
+    }
+
+    /**
+     * GitLab through its REST API: a project's issues, open and closed, 100 a
+     * page; filtered as its issues API filters (`labels=…&milestone=…`). Signs
+     * in with a personal, project or group access token. An issue's epic
+     * (GitLab Premium) is its epic.
+     */
+    class GitLabApi extends TrackerApi {
+        static tracker = 'gitlab';
+
+        static PAGE = 100;
+
+        static baseUrlPlaceholder = 'https://gitlab.com';
+
+        static tokenHint = 'An access token with read_api';
+
+        static get ownFields() {
+            return [
+                { key: 'project', label: 'Project', required: true, placeholder: 'group/project, or its id' },
+                { key: 'query', label: 'Filter', placeholder: 'labels=requirements&milestone=Release 2 (as the issues API takes)' },
+            ];
+        }
+
+        headers() {
+            return { 'PRIVATE-TOKEN': String(this.connection.token) };
+        }
+
+        async _read() {
+            const project = encodeURIComponent(String(this.connection.project).trim());
+            const issues = [];
+            for (let page = 1; page;) {
+                const params = new URLSearchParams(String(this.connection.query ?? '').trim());
+                for (const [k, v] of Object.entries({ state: params.get('state') ?? 'all', per_page: String(this.constructor.PAGE), page: String(page) })) params.set(k, v);
+                const { json, headers } = await this.request(this.url(`/api/v4/projects/${project}/issues?${params}`));
+                const got = Array.isArray(json) ? json : [];
+                const next = Number(headers?.get?.('x-next-page')) || (got.length === this.constructor.PAGE && !headers?.has?.('x-next-page') ? page + 1 : 0);
+                if (this.keep(issues, got)) { this.truncated ||= !!next; break; }
+                page = got.length ? next : 0;
+            }
+            return issues;
+        }
+    }
+
+    /** Each tracker's API, by its key in TRACKERS. */
+    const TRACKER_APIS = Object.freeze({ jira: JiraApi, azure: AzureDevOpsApi, gitlab: GitLabApi });
+
+    /**
+     * The API reader for a connection (`connection.tracker`: 'jira', 'azure',
+     * 'gitlab'); `options` as TrackerApi takes them.
+     */
+    function trackerApi(connection, options) {
+        const Api = TRACKER_APIS[connection?.tracker];
+        if (!Api) throw new Error(`No API reader for tracker "${connection?.tracker ?? ''}" (${Object.keys(TRACKER_APIS).join(', ')})`);
+        return new Api(connection, options);
+    }
+
+    /** What each tracker's connection asks for: `[{tracker, label, fields}]`, for a host's form. */
+    function trackerConnectionFields() {
+        return Object.entries(TRACKER_APIS).map(([tracker, Api]) => ({ tracker, label: new Api({}).label, fields: Api.fields }));
+    }
+
     /**
      * propertiesDialog — the "Show/Edit Properties" dialog, as a shipped feature.
      *
@@ -55801,6 +56125,7 @@ th { color: #555; font-weight: 500; }
     exports.ArrowMarker = ArrowMarker;
     exports.AssociationKind = AssociationKind;
     exports.AttributedLevel = AttributedLevel;
+    exports.AzureDevOpsApi = AzureDevOpsApi;
     exports.BUILTIN_PARTS = BUILTIN_PARTS;
     exports.BUILTIN_THEMES = BUILTIN_THEMES;
     exports.BackgroundCommand = BackgroundCommand;
@@ -55909,6 +56234,7 @@ th { color: #555; font-weight: 500; }
     exports.GRID_COLS = GRID_COLS;
     exports.GRID_GAP_PX = GRID_GAP_PX;
     exports.GeneralizationKind = GeneralizationKind;
+    exports.GitLabApi = GitLabApi;
     exports.Glyph = Glyph;
     exports.GlyphTemplate = GlyphTemplate;
     exports.GraphDataWindow = GraphDataWindow;
@@ -55925,6 +56251,7 @@ th { color: #555; font-weight: 500; }
     exports.ITIconNotation = ITIconNotation;
     exports.ImageSelector = ImageSelector;
     exports.ItemGroup = ItemGroup;
+    exports.JiraApi = JiraApi;
     exports.KIND_PREFERENCE = KIND_PREFERENCE;
     exports.LAYER_CHOICES = LAYER_CHOICES;
     exports.LIGHT_THEME = LIGHT_THEME;
@@ -56019,6 +56346,7 @@ th { color: #555; font-weight: 500; }
     exports.SwimlaneTemplate = SwimlaneTemplate;
     exports.THEME_VARS = THEME_VARS;
     exports.TRACKERS = TRACKERS;
+    exports.TRACKER_APIS = TRACKER_APIS;
     exports.TREE_LAYERS = TREE_LAYERS;
     exports.TREE_MODE_CATALOG = TREE_MODE_CATALOG;
     exports.TabsNode = TabsNode;
@@ -56033,6 +56361,7 @@ th { color: #555; font-weight: 500; }
     exports.ToolbarSelect = ToolbarSelect;
     exports.ToolbarSeparator = ToolbarSeparator;
     exports.ToolbarText = ToolbarText;
+    exports.TrackerApi = TrackerApi;
     exports.TrackerExport = TrackerExport;
     exports.TrackerExportFileFormat = TrackerExportFileFormat;
     exports.TrapezoidTemplate = TrapezoidTemplate;
@@ -56137,6 +56466,8 @@ th { color: #555; font-weight: 500; }
     exports.toArchimateModel = toArchimateModel;
     exports.toExchangeXML = toExchangeXML;
     exports.toPngBlob = toPngBlob;
+    exports.trackerApi = trackerApi;
+    exports.trackerConnectionFields = trackerConnectionFields;
     exports.treeLayerOf = treeLayerOf;
     exports.treeModeRegistry = treeModeRegistry;
     exports.viewItemChanges = viewItemChanges;

package/dist/renderengine.umd.js

@@ -45535,15 +45535,16 @@
             return found?.[0] ?? null;
         }
 
-        /** @private */
+        /** @private — an API's JSON, given as text or already parsed. */
         static _json(text) {
+            if (text && typeof text === 'object') return text;
             const s = String(text ?? '').trim();
             if (!s.startsWith('{') && !s.startsWith('[')) return null;
             try { return JSON.parse(s); } catch { return null; }
         }
 
         /**
-         * The export as a requirements model's spec.
+         * The export (its text; an API's JSON as text or parsed — TrackerApi) as a requirements model's spec.
          * @returns {{epics: Array, releases: Array, stories: Array, tracker: string|null}}
          */
         read(text) {
@@ -45777,6 +45778,329 @@
         }
     }
 
+    /** Text as base64, whatever its characters (btoa takes only Latin-1). */
+    function base64(text) {
+        const bytes = new TextEncoder().encode(String(text));
+        let binary = '';
+        for (const b of bytes) binary += String.fromCharCode(b);
+        return btoa(binary);
+    }
+
+    /**
+     * TrackerApi — a tracker read through its API rather than from an export: the
+     * issues a connection names, page by page, as the JSON `TrackerExport` reads
+     * (so an API's answer and a file saved from it make the same model). A
+     * subclass per tracker (`JiraApi`, `AzureDevOpsApi`, `GitLabApi`) says where
+     * its issues are, how it pages and how it is signed in to; what a connection
+     * asks for is `fields`, which a host builds its form from.
+     *
+     * `fetch` is given (a server's, or a test's): a tracker's token belongs where
+     * the request is made, which is seldom a browser. Nothing here keeps or logs
+     * the token; an error says what the tracker answered, not what was sent.
+     */
+    class TrackerApi {
+        /** The tracker's key in TRACKERS ('jira'). */
+        static tracker = null;
+
+        /** Most issues read from one connection: a connection naming a whole site is stopped there (`truncated`). */
+        static MAX_ISSUES = 5000;
+
+        /**
+         * What a connection asks for, in order: `{key, label, type?, choices?,
+         * required?, secret?, placeholder?, hint?}` — `secret` written, never
+         * shown back. The tracker's own between its address and its token.
+         */
+        static get fields() {
+            return [
+                { key: 'name', label: 'Name', required: true, placeholder: 'What people pick it by, e.g. "Shop backlog"' },
+                { key: 'baseUrl', label: 'Address', required: true, placeholder: this.baseUrlPlaceholder },
+                ...this.ownFields,
+                { key: 'token', label: 'Token', type: 'password', required: true, secret: true, hint: this.tokenHint },
+            ];
+        }
+
+        /** @protected */
+        static get ownFields() { return []; }
+
+        /** @protected */
+        static baseUrlPlaceholder = 'https://…';
+
+        /** @protected */
+        static tokenHint = 'An access token that may read the issues';
+
+        /**
+         * @param {Object} connection - Its `fields`' values (and `columns`, a TrackerExport's own columns)
+         * @param {Object} [options]
+         * @param {Function} [options.fetch] - The fetch to read with (default: the global one)
+         * @param {number} [options.maxIssues] - Most issues read (default MAX_ISSUES)
+         */
+        constructor(connection, { fetch = globalThis.fetch, maxIssues = new.target.MAX_ISSUES } = {}) {
+            this.connection = connection ?? {};
+            this.fetch = fetch;
+            this.maxIssues = maxIssues;
+            /** Whether the last read stopped at maxIssues. */
+            this.truncated = false;
+        }
+
+        get tracker() { return this.constructor.tracker; }
+
+        /** What the tracker is called ('Jira'). */
+        get label() { return TrackerExport.label(this.tracker); }
+
+        /** What is wrong with the connection, before anything is asked of the tracker: messages, none when it will do. */
+        problems() {
+            const c = this.connection;
+            const out = this.constructor.fields.filter(f => f.required && !String(c[f.key] ?? '').trim()).map(f => `${f.label} is needed.`);
+            if (c.baseUrl && !/^https?:\/\/[^\s/]+/i.test(String(c.baseUrl).trim())) out.push(`Address must start http:// or https:// ("${c.baseUrl}").`);
+            return out;
+        }
+
+        /** The issues, as the tracker's API gives them (the JSON TrackerExport reads). */
+        async read() {
+            const problems = this.problems();
+            if (problems.length) throw new Error(`${this.label} connection "${this.connection.name ?? ''}": ${problems.join(' ')}`);
+            this.truncated = false;
+            return this._read();
+        }
+
+        /** The issues as a requirements model's spec, named as the connection is. */
+        async model() {
+            const json = await this.read();
+            const { tracker, ...spec } = new TrackerExport({ tracker: this.tracker, columns: this.connection.columns ?? {} }).read(json);
+            return { name: this.connection.name || `${this.label} issues`, ...spec };
+        }
+
+        /** @protected @abstract */
+        async _read() {
+            throw new Error(`${this.constructor.name} does not say how to read ${this.label}`);
+        }
+
+        /** The headers that sign in. @protected @abstract */
+        headers() {
+            return {};
+        }
+
+        /** A path on the tracker's address. @protected */
+        url(path) {
+            return `${String(this.connection.baseUrl).trim().replace(/\/+$/, '')}${path}`;
+        }
+
+        /**
+         * A request to the tracker, its answer's JSON and headers; an answer
+         * other than OK an error saying what the tracker said. @protected
+         */
+        async request(url, { method = 'GET', body } = {}) {
+            if (typeof this.fetch !== 'function') throw new Error('No fetch to read the tracker with');
+            const res = await this.fetch(url, {
+                method,
+                headers: { Accept: 'application/json', ...(body !== undefined ? { 'Content-Type': 'application/json' } : {}), ...this.headers() },
+                ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+            });
+            if (!res.ok) {
+                const text = await res.text().catch(() => '');
+                throw new Error(`${this.label} answered ${res.status}${res.statusText ? ` ${res.statusText}` : ''}${text ? `: ${text.slice(0, 300)}` : ''}`);
+            }
+            return { json: await res.json(), headers: res.headers };
+        }
+
+        /** Issues kept up to maxIssues; true once it is reached. @protected */
+        keep(into, more) {
+            for (const issue of more) {
+                if (into.length >= this.maxIssues) { this.truncated = true; return true; }
+                into.push(issue);
+            }
+            return into.length >= this.maxIssues;
+        }
+
+        /** @protected */
+        static base64 = base64;
+
+        /** @protected — the tracker's issue types not read (TRACKERS: its sub-tasks). */
+        get skipTypes() { return TRACKERS[this.tracker]?.skipTypes ?? []; }
+    }
+
+    /**
+     * Jira through its REST API: the issues a JQL query finds (a project's, by
+     * default), every field (custom ones too: story points, acceptance criteria).
+     * Jira Cloud signs in with an email and an API token and pages by token
+     * (`/rest/api/3/search/jql`); Jira Server and Data Center with a personal
+     * access token (no email), paging by offset (`/rest/api/2/search`).
+     */
+    class JiraApi extends TrackerApi {
+        static tracker = 'jira';
+
+        static PAGE = 100;
+
+        static baseUrlPlaceholder = 'https://your-site.atlassian.net';
+
+        static tokenHint = 'Jira Cloud: an API token (with the email above). Server / Data Center: a personal access token (no email).';
+
+        static get ownFields() {
+            return [
+                { key: 'edition', label: 'Jira', type: 'select', choices: [['cloud', 'Cloud'], ['server', 'Server / Data Center']], value: 'cloud' },
+                { key: 'user', label: 'Email', placeholder: 'The account the API token is for (Cloud)' },
+                { key: 'project', label: 'Project key', placeholder: 'SHOP — or leave it and give a JQL query' },
+                { key: 'query', label: 'JQL', placeholder: 'project = SHOP AND issuetype != Sub-task (instead of the project)' },
+            ];
+        }
+
+        problems() {
+            const out = super.problems();
+            if (!String(this.connection.project ?? '').trim() && !String(this.connection.query ?? '').trim()) out.push('A project key or a JQL query is needed.');
+            return out;
+        }
+
+        /** The JQL: the one given, else the project's issues in key order. */
+        get jql() {
+            const { query, project } = this.connection;
+            if (String(query ?? '').trim()) return String(query).trim();
+            return `project = "${String(project).trim().replace(/"/g, '\\"')}" ORDER BY key`;
+        }
+
+        headers() {
+            const { user, token } = this.connection;
+            return { Authorization: String(user ?? '').trim() ? `Basic ${TrackerApi.base64(`${String(user).trim()}:${token}`)}` : `Bearer ${token}` };
+        }
+
+        async _read() {
+            const issues = [];
+            const page = this.constructor.PAGE;
+            const query = (extra) => new URLSearchParams({ jql: this.jql, fields: '*all', maxResults: String(page), ...extra }).toString();
+            if (this.connection.edition === 'server') {
+                for (let startAt = 0; ; startAt += page) {
+                    const { json } = await this.request(this.url(`/rest/api/2/search?${query({ startAt: String(startAt) })}`));
+                    const got = json.issues ?? [];
+                    const more = got.length > 0 && startAt + got.length < (json.total ?? 0);
+                    if (this.keep(issues, got)) { this.truncated ||= more; break; }
+                    if (!more) break;
+                }
+            } else {
+                for (let token = null; ;) {
+                    const { json } = await this.request(this.url(`/rest/api/3/search/jql?${query(token ? { nextPageToken: token } : {})}`));
+                    const got = json.issues ?? [];
+                    token = json.isLast ? null : json.nextPageToken ?? null;
+                    if (this.keep(issues, got)) { this.truncated ||= !!token; break; }
+                    if (!token || !got.length) break;
+                }
+            }
+            return { issues };
+        }
+    }
+
+    /**
+     * Azure DevOps (Boards) through its REST API: a WIQL query for a project's
+     * work items (but its tasks — TRACKERS), then the items, 200 at a time. Signs
+     * in with a personal access token. Each item's link is its page in Boards.
+     */
+    class AzureDevOpsApi extends TrackerApi {
+        static tracker = 'azure';
+
+        /** Most ids one work-items request takes. */
+        static BATCH = 200;
+
+        static API_VERSION = '7.1';
+
+        static baseUrlPlaceholder = 'https://dev.azure.com/your-organisation';
+
+        static tokenHint = 'A personal access token with Work Items (Read)';
+
+        static get ownFields() {
+            return [
+                { key: 'project', label: 'Project', required: true, placeholder: 'The project, e.g. Shop' },
+                { key: 'query', label: 'WIQL condition', placeholder: "[System.AreaPath] UNDER 'Shop\\Checkout' (and the project's)" },
+            ];
+        }
+
+        headers() {
+            return { Authorization: `Basic ${TrackerApi.base64(`:${this.connection.token}`)}` };
+        }
+
+        /** The WIQL: the project's work items, not its tasks, and the condition given. */
+        get wiql() {
+            const types = this.skipTypes.map(t => `'${t.replace(/'/g, "''")}'`).join(', ');
+            const condition = String(this.connection.query ?? '').trim();
+            return `SELECT [System.Id] FROM WorkItems WHERE [System.TeamProject] = @project`
+                + (types ? ` AND [System.WorkItemType] NOT IN (${types})` : '')
+                + (condition ? ` AND (${condition})` : '')
+                + ' ORDER BY [System.Id]';
+        }
+
+        async _read() {
+            const project = encodeURIComponent(String(this.connection.project).trim());
+            const version = `api-version=${this.constructor.API_VERSION}`;
+            const { json } = await this.request(this.url(`/${project}/_apis/wit/wiql?${version}`), { method: 'POST', body: { query: this.wiql } });
+            const ids = (json.workItems ?? []).map(w => w.id);
+            const value = [];
+            for (let i = 0; i < ids.length; i += this.constructor.BATCH) {
+                const batch = ids.slice(i, i + this.constructor.BATCH);
+                const { json: items } = await this.request(this.url(`/${project}/_apis/wit/workitems?ids=${batch.join(',')}&${version}`));
+                const got = (items.value ?? []).map(w => ({ ...w, url: this.url(`/${project}/_workitems/edit/${w.id}`) }));
+                if (this.keep(value, got)) { this.truncated ||= i + batch.length < ids.length; break; }
+            }
+            return { value };
+        }
+    }
+
+    /**
+     * GitLab through its REST API: a project's issues, open and closed, 100 a
+     * page; filtered as its issues API filters (`labels=…&milestone=…`). Signs
+     * in with a personal, project or group access token. An issue's epic
+     * (GitLab Premium) is its epic.
+     */
+    class GitLabApi extends TrackerApi {
+        static tracker = 'gitlab';
+
+        static PAGE = 100;
+
+        static baseUrlPlaceholder = 'https://gitlab.com';
+
+        static tokenHint = 'An access token with read_api';
+
+        static get ownFields() {
+            return [
+                { key: 'project', label: 'Project', required: true, placeholder: 'group/project, or its id' },
+                { key: 'query', label: 'Filter', placeholder: 'labels=requirements&milestone=Release 2 (as the issues API takes)' },
+            ];
+        }
+
+        headers() {
+            return { 'PRIVATE-TOKEN': String(this.connection.token) };
+        }
+
+        async _read() {
+            const project = encodeURIComponent(String(this.connection.project).trim());
+            const issues = [];
+            for (let page = 1; page;) {
+                const params = new URLSearchParams(String(this.connection.query ?? '').trim());
+                for (const [k, v] of Object.entries({ state: params.get('state') ?? 'all', per_page: String(this.constructor.PAGE), page: String(page) })) params.set(k, v);
+                const { json, headers } = await this.request(this.url(`/api/v4/projects/${project}/issues?${params}`));
+                const got = Array.isArray(json) ? json : [];
+                const next = Number(headers?.get?.('x-next-page')) || (got.length === this.constructor.PAGE && !headers?.has?.('x-next-page') ? page + 1 : 0);
+                if (this.keep(issues, got)) { this.truncated ||= !!next; break; }
+                page = got.length ? next : 0;
+            }
+            return issues;
+        }
+    }
+
+    /** Each tracker's API, by its key in TRACKERS. */
+    const TRACKER_APIS = Object.freeze({ jira: JiraApi, azure: AzureDevOpsApi, gitlab: GitLabApi });
+
+    /**
+     * The API reader for a connection (`connection.tracker`: 'jira', 'azure',
+     * 'gitlab'); `options` as TrackerApi takes them.
+     */
+    function trackerApi(connection, options) {
+        const Api = TRACKER_APIS[connection?.tracker];
+        if (!Api) throw new Error(`No API reader for tracker "${connection?.tracker ?? ''}" (${Object.keys(TRACKER_APIS).join(', ')})`);
+        return new Api(connection, options);
+    }
+
+    /** What each tracker's connection asks for: `[{tracker, label, fields}]`, for a host's form. */
+    function trackerConnectionFields() {
+        return Object.entries(TRACKER_APIS).map(([tracker, Api]) => ({ tracker, label: new Api({}).label, fields: Api.fields }));
+    }
+
     /**
      * propertiesDialog — the "Show/Edit Properties" dialog, as a shipped feature.
      *
@@ -48686,6 +49010,7 @@
     exports.ArrowMarker = ArrowMarker;
     exports.AssociationKind = AssociationKind;
     exports.AttributedLevel = AttributedLevel;
+    exports.AzureDevOpsApi = AzureDevOpsApi;
     exports.BackgroundCommand = BackgroundCommand;
     exports.BackgroundGroup = BackgroundGroup;
     exports.Benchmark = Benchmark;
@@ -48780,6 +49105,7 @@
     exports.FormDialog = FormDialog;
     exports.GLYPHS = GLYPHS;
     exports.GeneralizationKind = GeneralizationKind;
+    exports.GitLabApi = GitLabApi;
     exports.Glyph = Glyph;
     exports.GlyphTemplate = GlyphTemplate;
     exports.GraphDataWindow = GraphDataWindow;
@@ -48794,6 +49120,7 @@
     exports.ITIconNotation = ITIconNotation;
     exports.ImageSelector = ImageSelector;
     exports.ItemGroup = ItemGroup;
+    exports.JiraApi = JiraApi;
     exports.KIND_PREFERENCE = KIND_PREFERENCE;
     exports.LAYER_CHOICES = LAYER_CHOICES;
     exports.LINE_ONLY_PROPERTIES = LINE_ONLY_PROPERTIES;
@@ -48870,6 +49197,7 @@
     exports.StructuredType = StructuredType;
     exports.SwimlaneTemplate = SwimlaneTemplate;
     exports.TRACKERS = TRACKERS;
+    exports.TRACKER_APIS = TRACKER_APIS;
     exports.TREE_LAYERS = TREE_LAYERS;
     exports.TREE_MODE_CATALOG = TREE_MODE_CATALOG;
     exports.Template = Template;
@@ -48883,6 +49211,7 @@
     exports.ToolbarSelect = ToolbarSelect;
     exports.ToolbarSeparator = ToolbarSeparator;
     exports.ToolbarText = ToolbarText;
+    exports.TrackerApi = TrackerApi;
     exports.TrackerExport = TrackerExport;
     exports.TrackerExportFileFormat = TrackerExportFileFormat;
     exports.TrapezoidTemplate = TrapezoidTemplate;
@@ -48967,6 +49296,8 @@
     exports.toArchimateModel = toArchimateModel;
     exports.toExchangeXML = toExchangeXML;
     exports.toPngBlob = toPngBlob;
+    exports.trackerApi = trackerApi;
+    exports.trackerConnectionFields = trackerConnectionFields;
     exports.treeLayerOf = treeLayerOf;
     exports.treeModeRegistry = treeModeRegistry;
     exports.viewItemChanges = viewItemChanges;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peter.prib/renderengine",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "ArchiMate modeller, diagram editor and chart library for the browser, with no runtime dependencies.",
   "type": "module",
   "main": "src/index.js",

package/src/charting/requirements/AzureDevOpsApi.js

@@ -0,0 +1,55 @@
+import { TrackerApi } from './TrackerApi.js';
+
+/**
+ * Azure DevOps (Boards) through its REST API: a WIQL query for a project's
+ * work items (but its tasks — TRACKERS), then the items, 200 at a time. Signs
+ * in with a personal access token. Each item's link is its page in Boards.
+ */
+export class AzureDevOpsApi extends TrackerApi {
+    static tracker = 'azure';
+
+    /** Most ids one work-items request takes. */
+    static BATCH = 200;
+
+    static API_VERSION = '7.1';
+
+    static baseUrlPlaceholder = 'https://dev.azure.com/your-organisation';
+
+    static tokenHint = 'A personal access token with Work Items (Read)';
+
+    static get ownFields() {
+        return [
+            { key: 'project', label: 'Project', required: true, placeholder: 'The project, e.g. Shop' },
+            { key: 'query', label: 'WIQL condition', placeholder: "[System.AreaPath] UNDER 'Shop\\Checkout' (and the project's)" },
+        ];
+    }
+
+    headers() {
+        return { Authorization: `Basic ${TrackerApi.base64(`:${this.connection.token}`)}` };
+    }
+
+    /** The WIQL: the project's work items, not its tasks, and the condition given. */
+    get wiql() {
+        const types = this.skipTypes.map(t => `'${t.replace(/'/g, "''")}'`).join(', ');
+        const condition = String(this.connection.query ?? '').trim();
+        return `SELECT [System.Id] FROM WorkItems WHERE [System.TeamProject] = @project`
+            + (types ? ` AND [System.WorkItemType] NOT IN (${types})` : '')
+            + (condition ? ` AND (${condition})` : '')
+            + ' ORDER BY [System.Id]';
+    }
+
+    async _read() {
+        const project = encodeURIComponent(String(this.connection.project).trim());
+        const version = `api-version=${this.constructor.API_VERSION}`;
+        const { json } = await this.request(this.url(`/${project}/_apis/wit/wiql?${version}`), { method: 'POST', body: { query: this.wiql } });
+        const ids = (json.workItems ?? []).map(w => w.id);
+        const value = [];
+        for (let i = 0; i < ids.length; i += this.constructor.BATCH) {
+            const batch = ids.slice(i, i + this.constructor.BATCH);
+            const { json: items } = await this.request(this.url(`/${project}/_apis/wit/workitems?ids=${batch.join(',')}&${version}`));
+            const got = (items.value ?? []).map(w => ({ ...w, url: this.url(`/${project}/_workitems/edit/${w.id}`) }));
+            if (this.keep(value, got)) { this.truncated ||= i + batch.length < ids.length; break; }
+        }
+        return { value };
+    }
+}

package/src/charting/requirements/GitLabApi.js

@@ -0,0 +1,43 @@
+import { TrackerApi } from './TrackerApi.js';
+
+/**
+ * GitLab through its REST API: a project's issues, open and closed, 100 a
+ * page; filtered as its issues API filters (`labels=…&milestone=…`). Signs
+ * in with a personal, project or group access token. An issue's epic
+ * (GitLab Premium) is its epic.
+ */
+export class GitLabApi extends TrackerApi {
+    static tracker = 'gitlab';
+
+    static PAGE = 100;
+
+    static baseUrlPlaceholder = 'https://gitlab.com';
+
+    static tokenHint = 'An access token with read_api';
+
+    static get ownFields() {
+        return [
+            { key: 'project', label: 'Project', required: true, placeholder: 'group/project, or its id' },
+            { key: 'query', label: 'Filter', placeholder: 'labels=requirements&milestone=Release 2 (as the issues API takes)' },
+        ];
+    }
+
+    headers() {
+        return { 'PRIVATE-TOKEN': String(this.connection.token) };
+    }
+
+    async _read() {
+        const project = encodeURIComponent(String(this.connection.project).trim());
+        const issues = [];
+        for (let page = 1; page;) {
+            const params = new URLSearchParams(String(this.connection.query ?? '').trim());
+            for (const [k, v] of Object.entries({ state: params.get('state') ?? 'all', per_page: String(this.constructor.PAGE), page: String(page) })) params.set(k, v);
+            const { json, headers } = await this.request(this.url(`/api/v4/projects/${project}/issues?${params}`));
+            const got = Array.isArray(json) ? json : [];
+            const next = Number(headers?.get?.('x-next-page')) || (got.length === this.constructor.PAGE && !headers?.has?.('x-next-page') ? page + 1 : 0);
+            if (this.keep(issues, got)) { this.truncated ||= !!next; break; }
+            page = got.length ? next : 0;
+        }
+        return issues;
+    }
+}

package/src/charting/requirements/JiraApi.js

@@ -0,0 +1,69 @@
+import { TrackerApi } from './TrackerApi.js';
+
+/**
+ * Jira through its REST API: the issues a JQL query finds (a project's, by
+ * default), every field (custom ones too: story points, acceptance criteria).
+ * Jira Cloud signs in with an email and an API token and pages by token
+ * (`/rest/api/3/search/jql`); Jira Server and Data Center with a personal
+ * access token (no email), paging by offset (`/rest/api/2/search`).
+ */
+export class JiraApi extends TrackerApi {
+    static tracker = 'jira';
+
+    static PAGE = 100;
+
+    static baseUrlPlaceholder = 'https://your-site.atlassian.net';
+
+    static tokenHint = 'Jira Cloud: an API token (with the email above). Server / Data Center: a personal access token (no email).';
+
+    static get ownFields() {
+        return [
+            { key: 'edition', label: 'Jira', type: 'select', choices: [['cloud', 'Cloud'], ['server', 'Server / Data Center']], value: 'cloud' },
+            { key: 'user', label: 'Email', placeholder: 'The account the API token is for (Cloud)' },
+            { key: 'project', label: 'Project key', placeholder: 'SHOP — or leave it and give a JQL query' },
+            { key: 'query', label: 'JQL', placeholder: 'project = SHOP AND issuetype != Sub-task (instead of the project)' },
+        ];
+    }
+
+    problems() {
+        const out = super.problems();
+        if (!String(this.connection.project ?? '').trim() && !String(this.connection.query ?? '').trim()) out.push('A project key or a JQL query is needed.');
+        return out;
+    }
+
+    /** The JQL: the one given, else the project's issues in key order. */
+    get jql() {
+        const { query, project } = this.connection;
+        if (String(query ?? '').trim()) return String(query).trim();
+        return `project = "${String(project).trim().replace(/"/g, '\\"')}" ORDER BY key`;
+    }
+
+    headers() {
+        const { user, token } = this.connection;
+        return { Authorization: String(user ?? '').trim() ? `Basic ${TrackerApi.base64(`${String(user).trim()}:${token}`)}` : `Bearer ${token}` };
+    }
+
+    async _read() {
+        const issues = [];
+        const page = this.constructor.PAGE;
+        const query = (extra) => new URLSearchParams({ jql: this.jql, fields: '*all', maxResults: String(page), ...extra }).toString();
+        if (this.connection.edition === 'server') {
+            for (let startAt = 0; ; startAt += page) {
+                const { json } = await this.request(this.url(`/rest/api/2/search?${query({ startAt: String(startAt) })}`));
+                const got = json.issues ?? [];
+                const more = got.length > 0 && startAt + got.length < (json.total ?? 0);
+                if (this.keep(issues, got)) { this.truncated ||= more; break; }
+                if (!more) break;
+            }
+        } else {
+            for (let token = null; ;) {
+                const { json } = await this.request(this.url(`/rest/api/3/search/jql?${query(token ? { nextPageToken: token } : {})}`));
+                const got = json.issues ?? [];
+                token = json.isLast ? null : json.nextPageToken ?? null;
+                if (this.keep(issues, got)) { this.truncated ||= !!token; break; }
+                if (!token || !got.length) break;
+            }
+        }
+        return { issues };
+    }
+}

package/src/charting/requirements/TrackerApi.js

@@ -0,0 +1,142 @@
+import { TrackerExport, TRACKERS } from './TrackerExport.js';
+
+/** Text as base64, whatever its characters (btoa takes only Latin-1). */
+function base64(text) {
+    const bytes = new TextEncoder().encode(String(text));
+    let binary = '';
+    for (const b of bytes) binary += String.fromCharCode(b);
+    return btoa(binary);
+}
+
+/**
+ * TrackerApi — a tracker read through its API rather than from an export: the
+ * issues a connection names, page by page, as the JSON `TrackerExport` reads
+ * (so an API's answer and a file saved from it make the same model). A
+ * subclass per tracker (`JiraApi`, `AzureDevOpsApi`, `GitLabApi`) says where
+ * its issues are, how it pages and how it is signed in to; what a connection
+ * asks for is `fields`, which a host builds its form from.
+ *
+ * `fetch` is given (a server's, or a test's): a tracker's token belongs where
+ * the request is made, which is seldom a browser. Nothing here keeps or logs
+ * the token; an error says what the tracker answered, not what was sent.
+ */
+export class TrackerApi {
+    /** The tracker's key in TRACKERS ('jira'). */
+    static tracker = null;
+
+    /** Most issues read from one connection: a connection naming a whole site is stopped there (`truncated`). */
+    static MAX_ISSUES = 5000;
+
+    /**
+     * What a connection asks for, in order: `{key, label, type?, choices?,
+     * required?, secret?, placeholder?, hint?}` — `secret` written, never
+     * shown back. The tracker's own between its address and its token.
+     */
+    static get fields() {
+        return [
+            { key: 'name', label: 'Name', required: true, placeholder: 'What people pick it by, e.g. "Shop backlog"' },
+            { key: 'baseUrl', label: 'Address', required: true, placeholder: this.baseUrlPlaceholder },
+            ...this.ownFields,
+            { key: 'token', label: 'Token', type: 'password', required: true, secret: true, hint: this.tokenHint },
+        ];
+    }
+
+    /** @protected */
+    static get ownFields() { return []; }
+
+    /** @protected */
+    static baseUrlPlaceholder = 'https://…';
+
+    /** @protected */
+    static tokenHint = 'An access token that may read the issues';
+
+    /**
+     * @param {Object} connection - Its `fields`' values (and `columns`, a TrackerExport's own columns)
+     * @param {Object} [options]
+     * @param {Function} [options.fetch] - The fetch to read with (default: the global one)
+     * @param {number} [options.maxIssues] - Most issues read (default MAX_ISSUES)
+     */
+    constructor(connection, { fetch = globalThis.fetch, maxIssues = new.target.MAX_ISSUES } = {}) {
+        this.connection = connection ?? {};
+        this.fetch = fetch;
+        this.maxIssues = maxIssues;
+        /** Whether the last read stopped at maxIssues. */
+        this.truncated = false;
+    }
+
+    get tracker() { return this.constructor.tracker; }
+
+    /** What the tracker is called ('Jira'). */
+    get label() { return TrackerExport.label(this.tracker); }
+
+    /** What is wrong with the connection, before anything is asked of the tracker: messages, none when it will do. */
+    problems() {
+        const c = this.connection;
+        const out = this.constructor.fields.filter(f => f.required && !String(c[f.key] ?? '').trim()).map(f => `${f.label} is needed.`);
+        if (c.baseUrl && !/^https?:\/\/[^\s/]+/i.test(String(c.baseUrl).trim())) out.push(`Address must start http:// or https:// ("${c.baseUrl}").`);
+        return out;
+    }
+
+    /** The issues, as the tracker's API gives them (the JSON TrackerExport reads). */
+    async read() {
+        const problems = this.problems();
+        if (problems.length) throw new Error(`${this.label} connection "${this.connection.name ?? ''}": ${problems.join(' ')}`);
+        this.truncated = false;
+        return this._read();
+    }
+
+    /** The issues as a requirements model's spec, named as the connection is. */
+    async model() {
+        const json = await this.read();
+        const { tracker, ...spec } = new TrackerExport({ tracker: this.tracker, columns: this.connection.columns ?? {} }).read(json);
+        return { name: this.connection.name || `${this.label} issues`, ...spec };
+    }
+
+    /** @protected @abstract */
+    async _read() {
+        throw new Error(`${this.constructor.name} does not say how to read ${this.label}`);
+    }
+
+    /** The headers that sign in. @protected @abstract */
+    headers() {
+        return {};
+    }
+
+    /** A path on the tracker's address. @protected */
+    url(path) {
+        return `${String(this.connection.baseUrl).trim().replace(/\/+$/, '')}${path}`;
+    }
+
+    /**
+     * A request to the tracker, its answer's JSON and headers; an answer
+     * other than OK an error saying what the tracker said. @protected
+     */
+    async request(url, { method = 'GET', body } = {}) {
+        if (typeof this.fetch !== 'function') throw new Error('No fetch to read the tracker with');
+        const res = await this.fetch(url, {
+            method,
+            headers: { Accept: 'application/json', ...(body !== undefined ? { 'Content-Type': 'application/json' } : {}), ...this.headers() },
+            ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => '');
+            throw new Error(`${this.label} answered ${res.status}${res.statusText ? ` ${res.statusText}` : ''}${text ? `: ${text.slice(0, 300)}` : ''}`);
+        }
+        return { json: await res.json(), headers: res.headers };
+    }
+
+    /** Issues kept up to maxIssues; true once it is reached. @protected */
+    keep(into, more) {
+        for (const issue of more) {
+            if (into.length >= this.maxIssues) { this.truncated = true; return true; }
+            into.push(issue);
+        }
+        return into.length >= this.maxIssues;
+    }
+
+    /** @protected */
+    static base64 = base64;
+
+    /** @protected — the tracker's issue types not read (TRACKERS: its sub-tasks). */
+    get skipTypes() { return TRACKERS[this.tracker]?.skipTypes ?? []; }
+}

package/src/charting/requirements/TrackerExport.js

@@ -167,15 +167,16 @@ export class TrackerExport {
         return found?.[0] ?? null;
     }
 
-    /** @private */
+    /** @private — an API's JSON, given as text or already parsed. */
     static _json(text) {
+        if (text && typeof text === 'object') return text;
         const s = String(text ?? '').trim();
         if (!s.startsWith('{') && !s.startsWith('[')) return null;
         try { return JSON.parse(s); } catch { return null; }
     }
 
     /**
-     * The export as a requirements model's spec.
+     * The export (its text; an API's JSON as text or parsed — TrackerApi) as a requirements model's spec.
      * @returns {{epics: Array, releases: Array, stories: Array, tracker: string|null}}
      */
     read(text) {

package/src/charting/requirements/index.js

@@ -5,3 +5,8 @@ export { RequirementsFileFormat } from './RequirementsFileFormat.js';
 export { TrackerExportFileFormat, StoryboardFileFormat } from './RequirementsImportFormats.js';
 export { TrackerExport, TRACKERS, criteriaFrom, narrativeFrom, withoutNarrative } from './TrackerExport.js';
 export { Storyboard } from './Storyboard.js';
+export { TrackerApi } from './TrackerApi.js';
+export { JiraApi } from './JiraApi.js';
+export { AzureDevOpsApi } from './AzureDevOpsApi.js';
+export { GitLabApi } from './GitLabApi.js';
+export { TRACKER_APIS, trackerApi, trackerConnectionFields } from './trackerApis.js';

package/src/charting/requirements/trackerApis.js

@@ -0,0 +1,21 @@
+import { JiraApi } from './JiraApi.js';
+import { AzureDevOpsApi } from './AzureDevOpsApi.js';
+import { GitLabApi } from './GitLabApi.js';
+
+/** Each tracker's API, by its key in TRACKERS. */
+export const TRACKER_APIS = Object.freeze({ jira: JiraApi, azure: AzureDevOpsApi, gitlab: GitLabApi });
+
+/**
+ * The API reader for a connection (`connection.tracker`: 'jira', 'azure',
+ * 'gitlab'); `options` as TrackerApi takes them.
+ */
+export function trackerApi(connection, options) {
+    const Api = TRACKER_APIS[connection?.tracker];
+    if (!Api) throw new Error(`No API reader for tracker "${connection?.tracker ?? ''}" (${Object.keys(TRACKER_APIS).join(', ')})`);
+    return new Api(connection, options);
+}
+
+/** What each tracker's connection asks for: `[{tracker, label, fields}]`, for a host's form. */
+export function trackerConnectionFields() {
+    return Object.entries(TRACKER_APIS).map(([tracker, Api]) => ({ tracker, label: new Api({}).label, fields: Api.fields }));
+}

package/src/index.js

@@ -166,7 +166,7 @@ import { buildTypeCategoryTree, buildPropertyTree } from './charting/modelTree/b
 import { DiagramTabs } from './charting/modelTree/DiagramTabs.js';
 import { DataModelNotation, DataModelLevel, AttributedLevel, ConceptualLevel, LogicalLevel, PhysicalLevel, NotationStyle, RelationshipKind, AssociationKind, GeneralizationKind, EntityRole, FactRole, DimensionRole } from './datamodel.js';
 import { DataModel, DataModelPerspective, DataModelContext, LevelSchema, LevelMapping, ServiceDomain, DataModelFileFormat, ServiceLandscape, BianLandscapeReader, BianSemanticApiReader, DataType, EnumerationType, StructuredType, NamingStandard, NameStyle, ClassificationScheme, ClassificationLens, SqlDdl, SqlDdlFileFormat, ModelScorecard, ScorecardCategory, MeasuredCategory } from './charting/datamodel/index.js';
-import { RequirementsModel, RequirementsChecker, RequirementsFileFormat, TrackerExportFileFormat, StoryboardFileFormat, TrackerExport, TRACKERS, Storyboard } from './charting/requirements/index.js';
+import { RequirementsModel, RequirementsChecker, RequirementsFileFormat, TrackerExportFileFormat, StoryboardFileFormat, TrackerExport, TRACKERS, Storyboard, TrackerApi, JiraApi, AzureDevOpsApi, GitLabApi, TRACKER_APIS, trackerApi, trackerConnectionFields } from './charting/requirements/index.js';
 import { EditableModel } from './charting/model/EditableModel.js';
 import { ModelEditCommand } from './charting/model/ModelEditCommand.js';
 import { Benchmark } from './charting/model/Benchmark.js';
@@ -229,6 +229,7 @@ export {
   DataModelNotation, DataModelLevel, AttributedLevel, ConceptualLevel, LogicalLevel, PhysicalLevel, NotationStyle, RelationshipKind, AssociationKind, GeneralizationKind, EntityRole, FactRole, DimensionRole,
   DataModel, DataModelPerspective, DataModelContext, LevelSchema, LevelMapping, ServiceDomain, DataModelFileFormat, ServiceLandscape, BianLandscapeReader, BianSemanticApiReader, DataType, EnumerationType, StructuredType, NamingStandard, NameStyle, ClassificationScheme, ClassificationLens, SqlDdl, SqlDdlFileFormat, ModelScorecard, ScorecardCategory, MeasuredCategory,
   RequirementsModel, RequirementsChecker, RequirementsFileFormat, TrackerExportFileFormat, StoryboardFileFormat, TrackerExport, TRACKERS, Storyboard,
+  TrackerApi, JiraApi, AzureDevOpsApi, GitLabApi, TRACKER_APIS, trackerApi, trackerConnectionFields,
   EditableModel, ModelEditCommand, Benchmark,
   BianNotation, BianFunctionalPattern, BianActionTerm,
   exportElementsCSV, exportRelationshipsCSV, exportModelCSV,