@openmeshtak/sdk 0.2.0 → 0.2.2

package/README.md

@@ -1,33 +1,15 @@
 # OpenMeshTak SDK
 
+[![npm](https://img.shields.io/npm/v/@openmeshtak/sdk)](https://www.npmjs.com/package/@openmeshtak/sdk) [![License](https://img.shields.io/github/license/OpenMeshTAK/openmeshtak-sdk)](LICENSE) [![CI](https://github.com/OpenMeshTAK/openmeshtak-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/OpenMeshTAK/openmeshtak-sdk/actions/workflows/ci.yml)
+
 The official TypeScript and JavaScript client for the OpenMeshTak REST API.
 
 The SDK is generated from the released OpenAPI contract and adds a small handwritten layer for
 authentication, common operations and predictable problem-details errors. It does not duplicate
-Core business rules.
-
-## Local development
+Core business rules. The SDK version always matches the OpenMeshTak version it was built from and
+works with the later patch releases of that version line. Node.js 24 or newer is required.
 
-This checkout currently targets OpenMeshTak API `>=0.2.0 <0.3.0` and contains the OpenAPI artifact
-from Core `v0.2.0`. It requires Node.js 24 or newer.
-
-```powershell
-pnpm install
-pnpm check
-```
-
-The SDK is a library, not a server, so there is no long-running development process. `pnpm build`
-generates the contract types and writes the importable package to `dist/`.
-
-To refresh the checked-in contract from a verified Core release checkout:
-
-```powershell
-pnpm api:sync -- ..\openmeshtak\openapi\openapi.json
-pnpm check
-```
-
-Commit the OpenAPI artifact and generated declarations together. Do not edit
-`src/generated/schema.ts` or `src/version.ts` by hand.
+Documentation: https://openmeshtak.github.io/openmeshtak-docs/sdk/
 
 ## Usage
 
@@ -94,42 +76,6 @@ for await (const member of paginate((page) => client.listEventMembers(eventId, {
 Generated DTOs and operation types for every other operation are exported from
 `@openmeshtak/sdk/generated`.
 
-## Releases
-
-The SDK version always equals the OpenMeshTak Core version it was built from: SDK `0.2.0` belongs
-to Core `0.2.0`, SDK `0.2.1` to Core `0.2.1`. It supports every Core patch release of the same
-minor version (`>=0.2.0 <0.3.0`), so an older SDK keeps working after a Core patch update. The SDK
-is released together with Core and Web.
-
-Releases are driven by annotated `vMAJOR.MINOR.PATCH[-PRERELEASE]` tags. The release workflow:
-
-1. verifies the tag, package version, API compatibility range and OpenAPI checksum;
-2. installs with the frozen lockfile, audits dependencies and runs the complete check;
-3. packs the npm tarball and generates third-party notices plus a CycloneDX SBOM;
-4. publishes `@openmeshtak/sdk` to npm (`latest` for stable versions, `next` for prereleases);
-5. creates a GitHub Release containing the verified tarball, notices and SBOM.
-
-To prepare a release for Core `0.2.1` by hand:
-
-```powershell
-pnpm api:sync -- ..openmeshtakopenapiopenapi.json   # from Core at tag v0.2.1
-pnpm version:set -- 0.2.1
-# set openmeshtak.apiVersionRange in package.json to ">=0.2.1 <0.3.0"
-pnpm generate
-pnpm check
-git commit -am "chore(release): 0.2.1"
-git tag -a v0.2.1 -m "OpenMeshTak SDK 0.2.1"
-git push origin main
-git push origin v0.2.1
-```
-
-The workflow refuses mismatched tags or version metadata. Publishing happens only after the pushed
-tag passes all checks.
-
-npm publishing uses trusted publishing for organization `OpenMeshTAK`, repository
-`openmeshtak-sdk` and workflow `release.yml`. For the package's very first publication, a
-short-lived granular `NPM_TOKEN` repository secret is used once and removed afterwards.
-
 ## License
 
 Apache-2.0

package/dist/generated/schema.d.ts

@@ -322,7 +322,7 @@ export interface paths {
         put: operations["AddTakServerCertificate"];
         post?: never;
         /**
-         * @description Removes an added or ACME certificate and disables ACME; the server then uses one issued by the
+         * @description Removes an added, ACME or file certificate and disables ACME and the file reload; the server then uses one issued by the
          *     OpenMeshTak CA.
          */
         delete: operations["RemoveTakServerCertificate"];
@@ -331,6 +331,26 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/tak-server/server-certificate/files": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        /**
+         * @description Uses the reverse proxy's certificate files, mounted read-only below `certificateDirectory`.
+         *     Core reloads them every twelve hours, so a certificate the proxy renews is picked up. Disables ACME.
+         */
+        put: operations["UseTakCertificateFiles"];
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/events/{eventId}/tak-traffic": {
         parameters: {
             query?: never;
@@ -575,6 +595,26 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/tak-server/acme/test": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * @description Runs the saved settings against Let's Encrypt staging to check the setup without touching the
+         *     production rate limits. Nothing is installed; a failure is returned as `succeeded: false`.
+         */
+        post: operations["Test"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/events/{eventId}/tak/configuration": {
         parameters: {
             query?: never;
@@ -2420,16 +2460,22 @@ export interface components {
         /** @description The certificate the TAK listeners present. The private key is never returned. */
         TakServerCertificateDto: {
             /**
-             * @description OpenMeshTak-issued, administrator-added, or obtained automatically through ACME.
+             * @description OpenMeshTak-issued, administrator-added, obtained automatically through ACME, or read from the reverse proxy's files.
              * @enum {string}
              */
-            source: "issued" | "added" | "acme";
+            source: "issued" | "added" | "acme" | "file";
             hostName: string;
             subject: string;
             fingerprintSha256: string;
             /** Format: date-time */
             notAfter: string;
         };
+        TakCertificateFilesDto: {
+            /** @description Full chain, server certificate first, e.g. `live/tak.example.org/fullchain.pem`. */
+            certificateFile: string;
+            /** @description Unencrypted private key, e.g. `live/tak.example.org/privkey.pem`. */
+            keyFile: string;
+        };
         TakServerSettingsDto: {
             /** @description Whether the TAK listeners run. Requires a host name. */
             enabled: boolean;
@@ -2448,6 +2494,10 @@ export interface components {
             clientCertificateDays: number;
             /** @description `null` until the server first starts or a certificate is added. */
             serverCertificate: components["schemas"]["TakServerCertificateDto"] | null;
+            /** @description The reverse proxy's certificate files Core reads, relative to `certificateDirectory`; `null` unless used. */
+            certificateFiles: components["schemas"]["TakCertificateFilesDto"] | null;
+            /** @description Where the proxy's certificate directory must be mounted for `certificateFiles`. */
+            certificateDirectory: string;
             /**
              * Format: date-time
              * @description When the public host name or a port last changed after setup; `null` if never. Apps enrolled
@@ -2505,6 +2555,11 @@ export interface components {
              */
             privateKeyPem: string;
         };
+        /** @description Use the reverse proxy's certificate files; both paths are relative to the mounted directory. */
+        UseTakCertificateFilesRequest: {
+            certificateFile: string;
+            keyFile: string;
+        };
         LiveTakConnectionDto: {
             id: components["schemas"]["Uuid"];
             userId: components["schemas"]["Uuid"];
@@ -2669,18 +2724,19 @@ export interface components {
             /** @description Omit to keep the stored token, `null` to remove it. The token is encrypted and write-only. */
             apiToken?: string | null;
         };
+        /** @description Result of a test run against Let's Encrypt staging. */
+        TakAcmeTestResultDto: {
+            succeeded: boolean;
+            /** @description What happened, safe to show to the administrator. */
+            message: string;
+        };
         /**
-         * @description - `none`: OpenMeshTak gives no TAK connection guidance.
-         *     - `meshtastic-local-server`: each participant enables the Meshtastic app's local TAK server and
-         *       connects ATAK/iTAK on the same phone to it. The app creates its own certificates, so
-         *       OpenMeshTak provides guidance and settings, not a ready-made connection package.
-         *     - `built-in-server`: participants enroll ATAK/iTAK with the built-in OpenMeshTak TAK server.
-         * @enum {string}
+         * @description TAK settings of a Meshtastic event. Every event sends TAK clients to the built-in TAK server;
+         *     Meshtastic events (`meshtasticEnabled` on the event) also connect them to the Meshtastic app's
+         *     local TAK server, which carries CoT over this channel.
          */
-        TakConnectionMode: "none" | "meshtastic-local-server" | "built-in-server";
         TakConfigurationDto: {
             eventId: components["schemas"]["Uuid"];
-            mode: components["schemas"]["TakConnectionMode"];
             /** @description Channel for the app's "TAK Mesh Channel"; `null` uses the primary channel. */
             meshChannelId: components["schemas"]["Uuid"] | null;
             /**
@@ -2697,7 +2753,6 @@ export interface components {
              * @description Version the client last read.
              */
             version: number;
-            mode: components["schemas"]["TakConnectionMode"];
             meshChannelId: components["schemas"]["Uuid"] | null;
         };
         SetupStatusResponse: {
@@ -2820,29 +2875,25 @@ export interface components {
          * @enum {string}
          */
         TakRole: "Team Member" | "Team Lead" | "HQ" | "Sniper" | "Medic" | "Forward Observer" | "RTO" | "K9";
+        /** @description The built-in TAK server participants enroll with from the dashboard. */
+        ProfileTakServer: {
+            /** @description `null` while the TAK server is not enabled. */
+            hostName: string | null;
+            /** Format: double */
+            streamingPort: number;
+        };
         /**
-         * @description Connection through the Meshtastic app's local TAK server. `meshChannel` is the value for the
-         *     app's "TAK Mesh Channel": the channel's slot on this member's device, or `null` while that
-         *     channel has not reached the device yet (then the primary channel is used).
+         * @description The Meshtastic app's local TAK server, which carries CoT over the mesh when there is no network.
+         *     `meshChannel` is the value for the app's "TAK Mesh Channel": the channel's slot on this member's
+         *     device, or `null` while that channel has not reached the device yet (then the primary channel
+         *     is used).
          */
-        ProfileTakConnection: {
+        ProfileMeshtasticTakServer: {
             meshChannel: {
                 /** Format: double */
                 slot: number;
                 name: string;
             } | null;
-            /** @enum {string} */
-            mode: "meshtastic-local-server";
-        } | {
-            /** Format: double */
-            streamingPort: number;
-            /** @description `null` while the TAK server is not enabled. */
-            hostName: string | null;
-            /**
-             * @description Enroll with the built-in TAK server from the dashboard.
-             * @enum {string}
-             */
-            mode: "built-in-server";
         };
         /**
          * @description A channel the member receives. `included` channels come with the member's channel set;
@@ -2899,14 +2950,17 @@ export interface components {
             eventRole: components["schemas"]["ProfileAssignment"];
             group: components["schemas"]["ProfileAssignment"];
             tak: {
-                /** @description How this member connects ATAK/iTAK; `null` when the event gives no guidance. */
-                connection: components["schemas"]["ProfileTakConnection"] | null;
+                /** @description Meshtastic events also connect ATAK/iTAK to the Meshtastic app; `null` otherwise. */
+                meshtasticLocalServer: components["schemas"]["ProfileMeshtasticTakServer"] | null;
+                /** @description Every member enrolls with the built-in TAK server for Data Packages and CoT over the network. */
+                server: components["schemas"]["ProfileTakServer"];
                 /** @description The group's TAK server groups for an external TAK server; the built-in server ignores them. */
                 serverGroups: string[];
                 role: components["schemas"]["TakRole"];
                 team: components["schemas"]["TakTeam"];
                 callsign: string;
             };
+            /** @description `null` when the event does not use Meshtastic. */
             meshtastic: {
                 /** @description `null` for configurations published before events had a firmware version. */
                 firmware: components["schemas"]["ProfileFirmware"] | null;
@@ -2915,7 +2969,7 @@ export interface components {
                 /** @description `null` only in previews while the group has no short-name prefix. */
                 shortName: string | null;
                 longName: string;
-            };
+            } | null;
         };
         MyEventMembershipDto: {
             eventId: components["schemas"]["Uuid"];
@@ -3305,6 +3359,10 @@ export interface components {
             revision: number;
             /** Format: date-time */
             publishedAt: string;
+            /** @description The built-in TAK server installs it in the app right after the app enrolls. */
+            installOnEnrollment: boolean;
+            /** @description The built-in TAK server installs it, and every new revision, whenever the app connects. */
+            installOnConnection: boolean;
         };
         /** @enum {string} */
         MemberClaimStatus: "open" | "consumed" | "revoked" | "expired";
@@ -3448,6 +3506,12 @@ export interface components {
              *     of event accounts that are deleted when the event is archived.
              */
             permanentAccounts: boolean;
+            /**
+             * @description The event provisions Meshtastic radios. When off, profiles carry no Meshtastic part, radio
+             *     downloads are unavailable and channels and radio settings stay stored but unused. Like other
+             *     configuration it reaches participants of an active event with the next published revision.
+             */
+            meshtasticEnabled: boolean;
             /** Format: date-time */
             createdAt: string;
             /** Format: date-time */
@@ -3486,6 +3550,12 @@ export interface components {
              *     of event accounts that are deleted when the event is archived.
              */
             permanentAccounts: boolean;
+            /**
+             * @description The event provisions Meshtastic radios. When off, profiles carry no Meshtastic part, radio
+             *     downloads are unavailable and channels and radio settings stay stored but unused. Like other
+             *     configuration it reaches participants of an active event with the next published revision.
+             */
+            meshtasticEnabled: boolean;
             /** Format: date-time */
             createdAt: string;
             /** Format: date-time */
@@ -3518,6 +3588,8 @@ export interface components {
              *     of event accounts that are deleted when the event is archived. Defaults to `false`.
              */
             permanentAccounts?: boolean;
+            /** @description The event provisions Meshtastic radios. Defaults to `false`, a TAK-only event. */
+            meshtasticEnabled?: boolean;
         };
         UpdateEventRequest: {
             /**
@@ -3544,6 +3616,8 @@ export interface components {
              *     of event accounts that are deleted when the event is archived. Omitted keeps the current value.
              */
             permanentAccounts?: boolean;
+            /** @description The event provisions Meshtastic radios. Omitted keeps the current value. */
+            meshtasticEnabled?: boolean;
         };
         EventTransitionRequest: {
             /**
@@ -3658,6 +3732,12 @@ export interface components {
             shortName: string | null;
             eventRole: components["schemas"]["EventAssignmentSummary"];
             eventGroup: components["schemas"]["EventAssignmentSummary"];
+            /**
+             * Format: double
+             * @description TAK apps the member's user has enrolled with the built-in TAK server and that may still
+             *     connect (valid client certificates). Certificates belong to the user, not to one event.
+             */
+            enrolledTakApps: number;
             /** Format: double */
             version: number;
             /** Format: date-time */
@@ -3868,19 +3948,27 @@ export interface components {
             settings: components["schemas"]["FirmwareSettingsDocument"];
         };
         CurrentTakConfiguration: {
-            mode: components["schemas"]["TakConnectionMode"];
             meshChannelId: string | null;
         };
-        /** @description How TAK clients connect; `null` in revisions created before version 4. */
+        /**
+         * @description The Meshtastic app's TAK mesh channel; `null` in revisions created before version 4. Revisions
+         *     before version 6 also stored a connection mode, which the switch `meshtasticEnabled` replaced.
+         */
         SnapshotTak: components["schemas"]["CurrentTakConfiguration"];
         /**
          * @description Bump `schemaVersion` whenever the snapshot shape changes; old revisions are never rewritten.
          *     Version 2 added `channels` in device order, the first being the primary channel; version 3
-         *     added `meshtastic`; version 4 added `tak`.
+         *     added `meshtastic`; version 4 added `tak`; version 5 added role TAK overrides; version 6 added
+         *     `meshtasticEnabled`.
          */
         ConfigurationSnapshot: {
             /** @enum {number} */
-            schemaVersion: 1 | 2 | 3 | 4 | 5;
+            schemaVersion: 1 | 2 | 3 | 4 | 5 | 6;
+            /**
+             * @description Whether the event provisions Meshtastic radios; `true` in revisions before version 6. When
+             *     `false`, `channels` is empty and `meshtastic` is `null`.
+             */
+            meshtasticEnabled: boolean;
             roles: components["schemas"]["SnapshotRole"][];
             groups: components["schemas"]["SnapshotGroup"][];
             channels: components["schemas"]["SnapshotChannel"][];
@@ -5935,6 +6023,57 @@ export interface operations {
             };
         };
     };
+    UseTakCertificateFiles: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["UseTakCertificateFilesRequest"];
+            };
+        };
+        responses: {
+            /** @description Certificate files in use */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["TakServerSettingsDto"];
+                };
+            };
+            /** @description Authentication required */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ProblemDetails"];
+                };
+            };
+            /** @description Access denied */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ProblemDetails"];
+                };
+            };
+            /** @description Validation failed */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ProblemDetails"];
+                };
+            };
+        };
+    };
     GetLiveTakTraffic: {
         parameters: {
             query?: never;
@@ -6570,6 +6709,53 @@ export interface operations {
             };
         };
     };
+    Test: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Test finished */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["TakAcmeTestResultDto"];
+                };
+            };
+            /** @description Authentication required */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ProblemDetails"];
+                };
+            };
+            /** @description Access denied */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ProblemDetails"];
+                };
+            };
+            /** @description Validation failed */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ProblemDetails"];
+                };
+            };
+        };
+    };
     GetTakConfiguration: {
         parameters: {
             query?: never;
@@ -8309,7 +8495,7 @@ export interface operations {
                     "application/json": components["schemas"]["ProblemDetails"];
                 };
             };
-            /** @description Meshtastic configuration not published */
+            /** @description Meshtastic configuration not published or event without Meshtastic */
             409: {
                 headers: {
                     [name: string]: unknown;