@meshery/schemas 1.3.86 → 1.3.88

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -21,7 +21,9 @@ export interface paths {
21
21
  * Register a new connection
22
22
  * @description Register a new connection with credentials. Meshery Cloud reserves the GitHub App connection's identity (name `GitHub App`, sub_type `git`): only its GitHub authorization flow creates that connection, so a request naming it is refused with a `409` MeshKit error that names the reserved GitHub App connection identity.
23
23
  *
24
- * Desktop registration uses this shared operation, but kind `desktop` is implemented by Cloud: a server that does not support it rejects a `desktop` body with `400`. The heartbeat and deregistration routes are Cloud-only. A client desktop app install registers itself on sign-in with kind `desktop`, type `platform`, sub_type `management`, status `connected`, and `metadata` matching `DesktopConnectionMetadata`. Servers implementing this contract must take the organization from the `X-Current-Orgid` header, refuse a `desktop` registration without it with `400`, and refuse a caller who is not a live member of that organization with `403`. They must deduplicate on (organization, owner, `metadata.machineId`): registering the same machine again updates that connection and returns `200`, while a new connection returns `201`. A `desktop` body whose metadata lacks `machineId` is refused with `400`. The kind names the connection type, never the product that runs on the machine.
24
+ * Desktop registration uses this shared operation, but kind `desktop` is implemented by Cloud: a server that does not support it rejects a `desktop` body with `400`. The heartbeat and deregistration routes are Cloud-only. A client desktop app install registers itself on every connect to Cloud, sign-in included, with kind `desktop`, type `platform`, sub_type `management`, status `connected`, and `metadata` matching `DesktopConnectionMetadata`. Servers implementing this contract must take the organization from the `X-Current-Orgid` header, refuse a `desktop` registration without it with `400`, and refuse a caller who is not a live member of that organization with `403`. They must deduplicate on (organization, owner, `metadata.machineId`): registering the same machine again updates that connection and returns `200`, while a new connection returns `201`. A `desktop` body whose metadata lacks `machineId` is refused with `400`. The kind names the connection type, never the product that runs on the machine.
25
+ *
26
+ * A `desktop` registration whose `metadata.clientName` and `metadata.appVersion` fall below the server's minimum version for that client is refused with `426` and a `ClientUpgradeRequiredError` body; the connection, when it exists, is set to `maintenance`. Servers must link the API token that authenticated the registration to the connection (`metadata.tokenId`, server-written) and revoke that token when the connection is deregistered or deleted. When a later registration of the same connection authenticates with a different token, the server revokes the token previously linked to it. Registrations beyond the organization's device limit are accepted; the organization is flagged through the capabilities document's `session.deviceUsage` instead.
25
27
  */
26
28
  post: operations["registerConnection"];
27
29
  delete?: never;
@@ -90,7 +92,7 @@ export interface paths {
90
92
  post?: never;
91
93
  /**
92
94
  * Delete a connection
93
- * @description Delete a specific connection
95
+ * @description Delete a specific connection. Deleting a connection that has a `metadata.tokenId` revokes that token.
94
96
  */
95
97
  delete: operations["deleteConnection"];
96
98
  options?: never;
@@ -150,7 +152,7 @@ export interface paths {
150
152
  post?: never;
151
153
  /**
152
154
  * Deregister a desktop app install
153
- * @description Delete the caller's `desktop` connection whose `metadata.machineId` matches, as a desktop app install does on sign-out or uninstall. Servers implementing this contract must scope the deletion to the caller: a connection registered by another user is not found.
155
+ * @description Delete the caller's `desktop` connection whose `metadata.machineId` matches, as a desktop app install does on sign-out or uninstall. Servers implementing this contract must scope the deletion to the caller: a connection registered by another user is not found. Servers must revoke the API token linked to each deleted connection (`metadata.tokenId`).
154
156
  */
155
157
  delete: operations["deregisterDesktopConnection"];
156
158
  options?: never;
@@ -169,7 +171,7 @@ export interface paths {
169
171
  put?: never;
170
172
  /**
171
173
  * Record a connection heartbeat
172
- * @description Mark the caller's connection as alive. Servers implementing this contract must set `metadata.lastSeenAt` to the current time and, when the connection is `disconnected`, set its status back to `connected`. Servers must report a connection whose `metadata.lastSeenAt` is older than 3 minutes as `disconnected` until its next heartbeat. The request has no body, so a heartbeat cannot change anything else about the connection.
174
+ * @description Mark the caller's connection as alive. Servers implementing this contract must set `metadata.lastSeenAt` to the current time and, when the connection is `disconnected`, set its status back to `connected`. Servers must report a connection whose `metadata.lastSeenAt` is older than 3 minutes as `disconnected` until its next heartbeat. The request has no body, so a heartbeat cannot change anything else about the connection. When the connection's `metadata.clientName` and `metadata.appVersion`, as stored by the latest registration (which every connect makes before its first heartbeat), fall below the server's minimum version for that client, servers must answer `426` with a `ClientUpgradeRequiredError` body and set the connection to `maintenance` instead of recording the heartbeat.
173
175
  */
174
176
  post: operations["recordConnectionHeartbeat"];
175
177
  delete?: never;
@@ -1292,16 +1294,27 @@ export interface components {
1292
1294
  };
1293
1295
  /** @description Stable identifier of a desktop app install, generated once per install. It is the machine part of the deduplication key and the `machineId` path parameter. */
1294
1296
  DesktopMachineId: string;
1295
- /** @description Metadata of a `desktop` connection: a desktop app install that registered itself on sign-in. Servers implementing this contract must validate `metadata` against this schema when a registration has kind `desktop`. The deduplication key is (organization, owner, `machineId`). `lastSeenAt` is set by the server on registration and on each heartbeat. Servers must show this metadata in organization listings only to the connection's owner and to organization admins. */
1297
+ /** @description Metadata of a `desktop` connection: a desktop app install that registered itself on every connect to Cloud. Servers implementing this contract must validate `metadata` against this schema when a registration has kind `desktop`. The deduplication key is (organization, owner, `machineId`). `lastSeenAt` is set by the server on registration and on each heartbeat. Servers must show this metadata in organization listings only to the connection's owner and to organization admins. */
1296
1298
  DesktopConnectionMetadata: {
1297
- /** @description Stable identifier of a desktop app install, generated once per install. It is the machine part of the deduplication key. */
1299
+ /** @description Stable identifier of a desktop app install: generated once on the install's first launch (a UUID is recommended), kept with the app's local state, and never derived from the host name, a process id or a hardware serial. A reinstall that discards local state is a new install. It is the machine part of the deduplication key. */
1298
1300
  machineId: string;
1299
1301
  /** @description Host name of the machine. */
1300
1302
  hostname?: string;
1301
1303
  /** @description Operating system, for example `macos`. */
1302
1304
  os?: string;
1303
- /** @description Version of the desktop app. */
1305
+ /** @description Version of the desktop app as `MAJOR.MINOR.PATCH` with an optional leading `v`, for example `v1.25.0`. Compared with the server's minimum for `clientName`. */
1304
1306
  appVersion?: string;
1307
+ /** @description Identifier of the desktop app, for example its product name, lowercase. A value, never a kind: it selects the server's minimum version for this client. */
1308
+ clientName?: string;
1309
+ /** @description Source revision the desktop app was built from. */
1310
+ buildSha?: string;
1311
+ /** @description Operating system version, for example `26.0.1`. */
1312
+ osVersion?: string;
1313
+ /**
1314
+ * Format: uuid
1315
+ * @description Server-written id of the API token that authenticated the latest registration. Deregistering or deleting the connection revokes this token. A value sent by the client is ignored.
1316
+ */
1317
+ tokenId?: string;
1305
1318
  /**
1306
1319
  * Format: date-time
1307
1320
  * @description Server time of the last registration or heartbeat.
@@ -3325,6 +3338,33 @@ export interface operations {
3325
3338
  };
3326
3339
  };
3327
3340
  };
3341
+ /** @description The client's version is below the provider's minimum for that client. The client must update before it can register or keep a connection alive; the body names the minimum and where to get an update. */
3342
+ 426: {
3343
+ headers: {
3344
+ [name: string]: unknown;
3345
+ };
3346
+ content: {
3347
+ "application/json": {
3348
+ /** @description The sentence the caller is shown. */
3349
+ error: string;
3350
+ /** @description MeshKit error code allocated by the emitting service; not a stable part of this contract. */
3351
+ code?: string;
3352
+ /** @description Whether a client application's version meets the provider's minimum for that client. A client whose `compatible` is false must update before it registers or keeps a connection alive; the provider answers those calls with 426. A client the provider has no minimum for is compatible and has no `minimumVersion`. */
3353
+ compatibility: {
3354
+ /** @description Identifier of a client application, for example the product name of a desktop app, lowercase. It is a value chosen by the client; the provider keys its minimum client versions by it. */
3355
+ clientName: string;
3356
+ /** @description The client's version as it reported it, as `MAJOR.MINOR.PATCH` with an optional leading `v`, for example `v1.25.0`. Versions are ordered by their numeric parts, so `v1.9.0` is older than `v1.25.0`. */
3357
+ clientVersion: string;
3358
+ /** @description Oldest client version the provider accepts for this client. Absent when the provider sets no minimum. */
3359
+ minimumVersion?: string;
3360
+ /** @description True when `clientVersion` is at or above `minimumVersion`, or when there is no minimum. */
3361
+ compatible: boolean;
3362
+ /** @description Where the client can get an update, when the provider knows one. */
3363
+ upgradeUrl?: string;
3364
+ };
3365
+ };
3366
+ };
3367
+ };
3328
3368
  /** @description Internal server error */
3329
3369
  500: {
3330
3370
  headers: {
@@ -5474,6 +5514,33 @@ export interface operations {
5474
5514
  "text/plain": string;
5475
5515
  };
5476
5516
  };
5517
+ /** @description The client's version is below the provider's minimum for that client. The client must update before it can register or keep a connection alive; the body names the minimum and where to get an update. */
5518
+ 426: {
5519
+ headers: {
5520
+ [name: string]: unknown;
5521
+ };
5522
+ content: {
5523
+ "application/json": {
5524
+ /** @description The sentence the caller is shown. */
5525
+ error: string;
5526
+ /** @description MeshKit error code allocated by the emitting service; not a stable part of this contract. */
5527
+ code?: string;
5528
+ /** @description Whether a client application's version meets the provider's minimum for that client. A client whose `compatible` is false must update before it registers or keeps a connection alive; the provider answers those calls with 426. A client the provider has no minimum for is compatible and has no `minimumVersion`. */
5529
+ compatibility: {
5530
+ /** @description Identifier of a client application, for example the product name of a desktop app, lowercase. It is a value chosen by the client; the provider keys its minimum client versions by it. */
5531
+ clientName: string;
5532
+ /** @description The client's version as it reported it, as `MAJOR.MINOR.PATCH` with an optional leading `v`, for example `v1.25.0`. Versions are ordered by their numeric parts, so `v1.9.0` is older than `v1.25.0`. */
5533
+ clientVersion: string;
5534
+ /** @description Oldest client version the provider accepts for this client. Absent when the provider sets no minimum. */
5535
+ minimumVersion?: string;
5536
+ /** @description True when `clientVersion` is at or above `minimumVersion`, or when there is no minimum. */
5537
+ compatible: boolean;
5538
+ /** @description Where the client can get an update, when the provider knows one. */
5539
+ upgradeUrl?: string;
5540
+ };
5541
+ };
5542
+ };
5543
+ };
5477
5544
  /** @description Internal server error */
5478
5545
  500: {
5479
5546
  headers: {