@kusinta/iot-schema 0.2.0-beta.5 → 0.2.0-beta.51

package/src/kusinta/iot/connector/v1/connector_pb.d.ts

@@ -2,13 +2,16 @@
 // @generated from file kusinta/iot/connector/v1/connector.proto (package kusinta.iot.connector.v1, syntax proto3)
 /* eslint-disable */
 
-import type { GenFile, GenMessage } from "@bufbuild/protobuf/codegenv2";
+import type { GenEnum, GenFile, GenMessage } from "@bufbuild/protobuf/codegenv2";
 import type { Message } from "@bufbuild/protobuf";
 import type { ConnectorId, DeviceId, GatewayId } from "../../identity/v1/identity_pb.js";
-import type { ConnectorTransport } from "../../common/v1/types_pb.js";
-import type { Device } from "../../device/v1/device_pb.js";
+import type { BackendFailureReason, BackendHealth, ConnectorKind, ConnectorTransport } from "../../common/v1/types_pb.js";
+import type { LinkedService } from "../../accountlink/v1/account_link_pb.js";
 import type { Timestamp } from "@bufbuild/protobuf/wkt";
+import type { Device } from "../../device/v1/device_pb.js";
+import type { DeviceLink, LinkFunction, LinkState } from "../../link/v1/link_pb.js";
 import type { AttributeWriteRequest, CommandError, DeviceCommand } from "../../webrtc/v1/command_pb.js";
+import type { PairingErrorDetail, PairingWindow } from "../../common/v1/pairing_pb.js";
 import type { PropertyUpdateBatch } from "../../device/v1/property_update_pb.js";
 import type { DeviceEventBatch } from "../../device/v1/device_event_pb.js";
 
@@ -27,6 +30,10 @@ export declare type ConnectorInfo = Message<"kusinta.iot.connector.v1.ConnectorI
   connectorId?: ConnectorId | undefined;
 
   /**
+   * User-facing and free-form — "HomeMatic hub", "LoRaWAN". An interface may show
+   * it; nothing ever matches on it. connector_id is the routing key; this is only
+   * a label for a person.
+   *
    * @generated from field: string display_name = 2;
    */
   displayName: string;
@@ -52,6 +59,82 @@ export declare type ConnectorInfo = Message<"kusinta.iot.connector.v1.ConnectorI
    * @generated from field: repeated uint32 supported_device_type_ids = 6;
    */
   supportedDeviceTypeIds: number[];
+
+  /**
+   * The connector opens a radio window on request: the app may offer the pairing
+   * flow and target webrtc.v1.StartPairing.connector_id at it. A connector whose
+   * devices are registered rather than paired (see supports_provisioning) sets this
+   * false.
+   *
+   * @generated from field: bool supports_pairing = 7;
+   */
+  supportsPairing: boolean;
+
+  /**
+   * The connector registers a device from credentials it is handed, rather than
+   * adopting one that joins during a window — the webrtc.v1.ProvisionDevice path.
+   * This is how the app knows to show a credential-entry flow instead of pairing,
+   * and ProvisionDevice.connector_id is targeted at a connector that declares it.
+   *
+   * @generated from field: bool supports_provisioning = 8;
+   */
+  supportsProvisioning: boolean;
+
+  /**
+   * The connector brokers device-to-device (hard) links: the link picker may offer
+   * them and can name the hub behind an otherwise-hidden candidate. Declared here
+   * rather than inferred from both devices reporting LINK_MODE_HARD, so it is a
+   * statement the connector makes rather than a guess the app assembles.
+   *
+   * @generated from field: bool brokers_links = 9;
+   */
+  brokersLinks: boolean;
+
+  /**
+   * Presentation only — an icon or a phrase; see common.v1.ConnectorKind for why it
+   * never gates behaviour. Unset is CONNECTOR_KIND_UNSPECIFIED, a generic hub.
+   *
+   * @generated from field: kusinta.iot.common.v1.ConnectorKind kind = 10;
+   */
+  kind: ConnectorKind;
+
+  /**
+   * Installer or operator detail — where the hub is, which building leg it serves.
+   * Kept off connector_id, whose identity contract routing depends on, and off
+   * display_name, which is the short label. Free-form, for a person; never matched
+   * on.
+   *
+   * @generated from field: string description = 11;
+   */
+  description: string;
+
+  /**
+   * The connector answers ReinitializeBackend: it can drop and re-establish its connection
+   * to its backend on request. The gateway sends ReinitializeBackend only to a connector
+   * that declares this, and refuses a reconnect for any other without asking it — a
+   * connector whose schema predates the message would ignore it, and the gateway would wait
+   * out its deadline for nothing.
+   *
+   * @generated from field: bool supports_backend_reinitialize = 12;
+   */
+  supportsBackendReinitialize: boolean;
+
+  /**
+   * The linked services (accountlink.v1) whose accounts this connector reads devices from,
+   * with access tokens the gateway hands it (CredentialsUpdate). Declaring a service asks
+   * for its tokens; it does not earn them. The gateway sends a service's tokens only to a
+   * connector_id it trusts for that service, only after accepting its handshake, and to
+   * one live session at a time: a second session claiming the same service gets none, and
+   * a session that ends loses its links with it. Trust is the gateway's own setting, made
+   * by its administrators, naming the connector_id per service; with none made for a
+   * service, the gateway sends its tokens to no connector. A connector_id counts only on a
+   * session the gateway's transport authenticated as that connector (a local socket only
+   * the gateway's connectors can open, or mutual TLS); claimed in a handshake alone, it
+   * earns nothing.
+   *
+   * @generated from field: repeated kusinta.iot.accountlink.v1.LinkedService consumes_credentials = 13;
+   */
+  consumesCredentials: LinkedService[];
 };
 
 /**
@@ -60,6 +143,116 @@ export declare type ConnectorInfo = Message<"kusinta.iot.connector.v1.ConnectorI
  */
 export declare const ConnectorInfoSchema: GenMessage<ConnectorInfo>;
 
+/**
+ * An access token for one account link (accountlink.v1): one home's grant at a third-party
+ * service, handed to the connector that reads that home's devices there. The gateway holds
+ * the token pair and refreshes it; only the short-lived access token crosses, never a
+ * refresh token or a client secret. Neither side writes it to disk or a log, nor puts it in
+ * BackendHealthReport.detail or an error message, and the connector sends it nowhere but
+ * in calls to that service's own API.
+ *
+ * Sent after every refresh, at least five minutes before the previous token's expires_at,
+ * and for a link made while the session is up. After a handshake, every live link arrives
+ * in one CredentialsSnapshot instead.
+ *
+ * Once expires_at plus 60 seconds of clock skew passes without a newer token, or the
+ * service refuses a live token as unauthorised (revoked at the service), the connector
+ * stops reading the link and reports the link's devices unreachable, the way it reports any
+ * unreachable device, until an update arrives. That is the link's state, not the backend's:
+ * it does not put the backend in doubt or report it failing, and a connector with no live
+ * link reports its backend OK.
+ *
+ * An update may carry another account's grant under the same id (the home linked again,
+ * replaced its link, or relinked after the old grant lapsed). The connector reads with it
+ * from then on and removes the link's devices the account no longer has (DeviceRemoval);
+ * the devices it still has keep their ids.
+ *
+ * @generated from message kusinta.iot.connector.v1.CredentialsUpdate
+ */
+export declare type CredentialsUpdate = Message<"kusinta.iot.connector.v1.CredentialsUpdate"> & {
+  /**
+   * Opaque; it names no home, person or account. Stable for one home and service for as
+   * long as the home has that service linked: replacing the link, relinking after it
+   * needed relinking, or a cancelled replacement arrives as an update under the same id, so
+   * a device read through it keeps its id and its history. A link made after the old one
+   * ended (unlinked, or the home handed over or wiped) has a new id, so nothing of the
+   * previous household's carries over. The gateway revokes a replaced
+   * grant at the service itself. A device read through two links, as when two homes link
+   * one account, has a distinct id per link. Not related to a device link's id
+   * (CreateLink).
+   *
+   * @generated from field: string account_link_id = 1;
+   */
+  accountLinkId: string;
+
+  /**
+   * @generated from field: kusinta.iot.accountlink.v1.LinkedService service = 2;
+   */
+  service: LinkedService;
+
+  /**
+   * @generated from field: string access_token = 3;
+   */
+  accessToken: string;
+
+  /**
+   * Always set. When the service states no lifetime, the gateway states one of at most an
+   * hour.
+   *
+   * @generated from field: google.protobuf.Timestamp expires_at = 4;
+   */
+  expiresAt?: Timestamp | undefined;
+};
+
+/**
+ * Describes the message kusinta.iot.connector.v1.CredentialsUpdate.
+ * Use `create(CredentialsUpdateSchema)` to create a new message.
+ */
+export declare const CredentialsUpdateSchema: GenMessage<CredentialsUpdate>;
+
+/**
+ * Every live account link for the services this connector declares, sent once after each
+ * accepted handshake and before any CredentialsUpdate on that session. Empty when there
+ * are none. The connector drops every link it knows that is not listed, removing its
+ * devices (DeviceRemoval), so a link that ended while the connector was away does not
+ * survive the reconnect.
+ *
+ * @generated from message kusinta.iot.connector.v1.CredentialsSnapshot
+ */
+export declare type CredentialsSnapshot = Message<"kusinta.iot.connector.v1.CredentialsSnapshot"> & {
+  /**
+   * @generated from field: repeated kusinta.iot.connector.v1.CredentialsUpdate links = 1;
+   */
+  links: CredentialsUpdate[];
+};
+
+/**
+ * Describes the message kusinta.iot.connector.v1.CredentialsSnapshot.
+ * Use `create(CredentialsSnapshotSchema)` to create a new message.
+ */
+export declare const CredentialsSnapshotSchema: GenMessage<CredentialsSnapshot>;
+
+/**
+ * An account link ended: unlinked, its home handed over, or wiped. Not sent for a
+ * replacement, which is an update under the same id. Sent before the gateway revokes the
+ * grant at the service. The connector drops the token at once, stops
+ * reading the link and removes its devices (DeviceRemoval).
+ *
+ * @generated from message kusinta.iot.connector.v1.CredentialsRevoked
+ */
+export declare type CredentialsRevoked = Message<"kusinta.iot.connector.v1.CredentialsRevoked"> & {
+  /**
+   * @generated from field: string account_link_id = 1;
+   */
+  accountLinkId: string;
+};
+
+/**
+ * Describes the message kusinta.iot.connector.v1.CredentialsRevoked.
+ * Use `create(CredentialsRevokedSchema)` to create a new message.
+ */
+export declare const CredentialsRevokedSchema: GenMessage<CredentialsRevoked>;
+
 /**
  * @generated from message kusinta.iot.connector.v1.ConnectorHandshake
  */
@@ -73,6 +266,62 @@ export declare type ConnectorHandshake = Message<"kusinta.iot.connector.v1.Conne
    * @generated from field: repeated kusinta.iot.device.v1.Device known_devices = 2;
    */
   knownDevices: Device[];
+
+  /**
+   * Every link the hub currently holds, reported the way known_devices is.
+   *
+   * Links are hub state, not gateway state: they outlive a connector restart and
+   * can be changed by anyone with access to the hub. The gateway's records are a
+   * statement of intent that can drift, so the handshake is the moment to
+   * reconcile them against what is really there. A link in the gateway's records
+   * and not here has gone; one here and not in the records was made elsewhere.
+   *
+   * Empty means "states nothing" — a connector that does not model linking is not
+   * asserting that no links exist.
+   *
+   * @generated from field: repeated kusinta.iot.link.v1.DeviceLink known_links = 3;
+   */
+  knownLinks: DeviceLink[];
+
+  /**
+   * The backend's health as the connector handshakes, so the gateway starts every session
+   * from the current state rather than from whatever it held before the stream dropped.
+   * From then on, changes arrive as BackendHealthReport on the session.
+   *
+   * Unset states nothing, and the gateway reads it as OK: a connector that predates backend
+   * health never sends it, and is never taken to be failing. A connector whose backend has
+   * not answered a call since it connected to the gateway — its backend is still in
+   * doubt — leaves it unset, or states FAILING only where BackendHealthReport's rules for
+   * FAILING already hold; never OK.
+   *
+   * After connecting to a gateway that sets HandshakeAck.supports_backend_health, a
+   * connector that reports backend health follows the rules on BackendHealthReport: its
+   * backend is in doubt from connecting to the gateway until it first answers, so the
+   * connector states OK (once it has answered) or FAILING within 60 seconds, here or in a
+   * BackendHealthReport, reports none of its devices as unreachable while its backend is in
+   * doubt, and re-reports them once it is not, as BackendHealthReport says. Toward a gateway
+   * that does not set it, none of those rules applies: the connector reports its devices as
+   * it did before backend health existed.
+   *
+   * Safe to set whatever the gateway: the handshake goes before the connector knows which
+   * gateway it reached, and a gateway that predates backend health skips the field as
+   * unknown. Everything after the handshake waits for HandshakeAck.supports_backend_health.
+   *
+   * @generated from field: kusinta.iot.connector.v1.BackendHealthReport backend_health = 4;
+   */
+  backendHealth?: BackendHealthReport | undefined;
+
+  /**
+   * For each device in known_devices read through an account link, that link's
+   * account_link_id, keyed by the device's id: the handshake's form of
+   * DeviceAnnouncement.account_link_id, so a reconnecting connector's linked devices are
+   * filed in their homes again. A known device absent here is read through no link. The
+   * map only restores a filing the gateway already recorded for that device and link, and
+   * only for a link it is sending this session; it never files a device anew.
+   *
+   * @generated from field: map<string, string> known_device_account_links = 5;
+   */
+  knownDeviceAccountLinks: { [key: string]: string };
 };
 
 /**
@@ -81,6 +330,319 @@ export declare type ConnectorHandshake = Message<"kusinta.iot.connector.v1.Conne
  */
 export declare const ConnectorHandshakeSchema: GenMessage<ConnectorHandshake>;
 
+/**
+ * The health of the backend the connector drives, connector to gateway: whether the radio
+ * central or network server behind it is working. See common.v1.BackendHealth.
+ *
+ * Sent on the session only to a gateway that sets HandshakeAck.supports_backend_health; the
+ * handshake's ConnectorHandshake.backend_health is set whatever the gateway, since the ack is
+ * not yet known. To a gateway that does not set it — one that predates backend health — the
+ * connector sends neither this on the session nor
+ * ReinitializeBackendResult, and keeps working as it did before: its backend failing is
+ * then only in its own logs.
+ *
+ * Sent in the handshake (ConnectorHandshake.backend_health), then whenever state or reason
+ * changes, and once after every requested re-initialisation (ReinitializeBackend) it
+ * attempts, changed or not, before the
+ * result that answers it. Not sent for a change of detail alone. Each report replaces the
+ * last.
+ *
+ * The connector's backend is in doubt from when the connector connects to the gateway (each
+ * session, whether or not the backend kept answering meanwhile), from any failed call
+ * to the backend, and from a re-initialisation the connector attempts, until the backend
+ * answers a call again; OK
+ * is stated only once it has. While it is in doubt the
+ * connector reports none of its devices as unreachable, by whatever its technology uses to
+ * say so: a device it cannot reach then may be the backend's fault. The gateway applies no
+ * debounce of its own, so the connector never reports FAILING for a single failed call: it
+ * reports FAILING once its backend has been in doubt for 60 seconds in all within the last
+ * 120 — so a backend that hangs, or answers only now and then, reaches it, and brief failures
+ * between answers do not — or sooner when its own
+ * retries are used up, with the reason of its latest failed call, or UNREACHABLE when none
+ * has failed yet. After a ReinitializeBackend it reports the attempt's true outcome at once,
+ * FAILING included, or OK, before the result: the request is the retry a person asked for.
+ * A backend outage the connector rides out within 60 seconds opens no problem, and what the
+ * backend then says of its devices is reported as it is.
+ *
+ * When its backend stops being in doubt, whatever started it, the connector reports, within
+ * 30 seconds, the current reachability of every device it knows, reachable ones included. If
+ * doubt comes back before it is done, it still reports the devices it knows to be reachable,
+ * and the rest once the doubt ends. The gateway closes
+ * a device's offline problem as recovered only on a report that the device is reachable —
+ * this one or any later one — never on silence; it closes for other reasons as reporting.v1
+ * says.
+ *
+ * The gateway raises reporting.v1.PROBLEM_KIND_CONNECTOR_ERROR for this connector while its
+ * stream is up and the latest report is FAILING, and clears it when one is anything else; a
+ * stream that drops closes it too, and the next handshake decides afresh (see reporting.v1).
+ * A connector that never sends one is OK throughout. CONNECTOR_OFFLINE is the other problem
+ * and is not this one: that is the stream to the gateway down, this is the stream up and
+ * the backend failing.
+ *
+ * @generated from message kusinta.iot.connector.v1.BackendHealthReport
+ */
+export declare type BackendHealthReport = Message<"kusinta.iot.connector.v1.BackendHealthReport"> & {
+  /**
+   * @generated from field: kusinta.iot.common.v1.BackendHealth health = 1;
+   */
+  health?: BackendHealth | undefined;
+
+  /**
+   * What went wrong, in the connector's words — an error message, the host it could not
+   * reach. For the gateway's logs only. The gateway never forwards it: not to the app, not
+   * to the cloud, not into a problem report. Empty when there is nothing to add.
+   *
+   * @generated from field: string detail = 2;
+   */
+  detail: string;
+};
+
+/**
+ * Describes the message kusinta.iot.connector.v1.BackendHealthReport.
+ * Use `create(BackendHealthReportSchema)` to create a new message.
+ */
+export declare const BackendHealthReportSchema: GenMessage<BackendHealthReport>;
+
+/**
+ * Asks the connector to re-initialise its backend connection, gateway to connector: drop
+ * the connection to its radio central or network server and establish it again, as it would
+ * at startup. Sent only to a connector that declares
+ * ConnectorInfo.supports_backend_reinitialize.
+ *
+ * Idempotent. Re-initialising a healthy backend is harmless, and asking twice is the same as
+ * asking once: a ReinitializeBackend that arrives while one is running starts nothing new,
+ * and is answered with the running one's outcome when it finishes. The gateway sends at most
+ * one at a time per connector and refuses a second request from above while one is
+ * outstanding; the connector's coalescing covers the case where the gateway gave up waiting
+ * and asked again.
+ *
+ * Sent only by a gateway that sets HandshakeAck.supports_backend_health, so a connector
+ * that receives it may answer. Answered once, by ReinitializeBackendResult with the same
+ * request_id. The connector bounds its attempt so that it answers within 30 seconds of
+ * receiving this; the gateway waits at least 45 and at most 60 seconds before it treats the
+ * request as timed out. A result arriving after the gateway has given up is ignored, but the
+ * health report sent before it still applies.
+ *
+ * @generated from message kusinta.iot.connector.v1.ReinitializeBackend
+ */
+export declare type ReinitializeBackend = Message<"kusinta.iot.connector.v1.ReinitializeBackend"> & {
+  /**
+   * minted by the gateway, echoed in the result
+   *
+   * @generated from field: string request_id = 1;
+   */
+  requestId: string;
+};
+
+/**
+ * Describes the message kusinta.iot.connector.v1.ReinitializeBackend.
+ * Use `create(ReinitializeBackendSchema)` to create a new message.
+ */
+export declare const ReinitializeBackendSchema: GenMessage<ReinitializeBackend>;
+
+/**
+ * What became of a ReinitializeBackend, connector to gateway.
+ *
+ * DONE means the attempt was made and has finished — not that it succeeded. Whether the
+ * backend works now is stated by the BackendHealthReport the connector sends after every
+ * attempt, before this result, so a gateway reading DONE already holds the outcome. Keeping
+ * the two apart means there is one place that says whether a backend is healthy, and a
+ * result cannot contradict it.
+ *
+ * @generated from message kusinta.iot.connector.v1.ReinitializeBackendResult
+ */
+export declare type ReinitializeBackendResult = Message<"kusinta.iot.connector.v1.ReinitializeBackendResult"> & {
+  /**
+   * @generated from field: string request_id = 1;
+   */
+  requestId: string;
+
+  /**
+   * @generated from field: kusinta.iot.connector.v1.ReinitializeOutcome outcome = 2;
+   */
+  outcome: ReinitializeOutcome;
+
+  /**
+   * Why it could not be attempted, when outcome is FAILED: MISCONFIGURED or INTERNAL.
+   * UNSPECIFIED otherwise. Never a failure found by attempting — rejected credentials, a
+   * backend that does not answer: the attempt was made, so the outcome is DONE and the
+   * health report before it says FAILING with AUTH_FAILED, UNREACHABLE or the like.
+   *
+   * @generated from field: kusinta.iot.common.v1.BackendFailureReason reason = 3;
+   */
+  reason: BackendFailureReason;
+
+  /**
+   * For the gateway's logs only, as BackendHealthReport.detail; never forwarded.
+   *
+   * @generated from field: string detail = 4;
+   */
+  detail: string;
+};
+
+/**
+ * Describes the message kusinta.iot.connector.v1.ReinitializeBackendResult.
+ * Use `create(ReinitializeBackendResultSchema)` to create a new message.
+ */
+export declare const ReinitializeBackendResultSchema: GenMessage<ReinitializeBackendResult>;
+
+/**
+ * Asks the connector to make a link, gateway to connector.
+ *
+ * Names two devices and a function; resolving that into whatever set of
+ * underlying connections the hub needs is the connector's work. It is expected to
+ * build the set atomically and roll back a partial one, because a half-built set
+ * is a link that lists as healthy and carries nothing.
+ *
+ * The connector is also expected to repair whatever the operation disturbs. On at
+ * least one vendor, both making and removing a link leaves the receiving device
+ * in a state it was not in before, with settings that must be captured
+ * beforehand and put back after.
+ *
+ * @generated from message kusinta.iot.connector.v1.CreateLink
+ */
+export declare type CreateLink = Message<"kusinta.iot.connector.v1.CreateLink"> & {
+  /**
+   * assigned by the gateway, echoed in the result
+   *
+   * @generated from field: string link_id = 1;
+   */
+  linkId: string;
+
+  /**
+   * @generated from field: kusinta.iot.identity.v1.DeviceId sender = 2;
+   */
+  sender?: DeviceId | undefined;
+
+  /**
+   * @generated from field: kusinta.iot.identity.v1.DeviceId receiver = 3;
+   */
+  receiver?: DeviceId | undefined;
+
+  /**
+   * @generated from field: kusinta.iot.link.v1.LinkFunction function = 4;
+   */
+  function: LinkFunction;
+};
+
+/**
+ * Describes the message kusinta.iot.connector.v1.CreateLink.
+ * Use `create(CreateLinkSchema)` to create a new message.
+ */
+export declare const CreateLinkSchema: GenMessage<CreateLink>;
+
+/**
+ * Asks the connector to remove a link it previously made.
+ *
+ * @generated from message kusinta.iot.connector.v1.RemoveLink
+ */
+export declare type RemoveLink = Message<"kusinta.iot.connector.v1.RemoveLink"> & {
+  /**
+   * @generated from field: string link_id = 1;
+   */
+  linkId: string;
+
+  /**
+   * @generated from field: kusinta.iot.identity.v1.DeviceId sender = 2;
+   */
+  sender?: DeviceId | undefined;
+
+  /**
+   * @generated from field: kusinta.iot.identity.v1.DeviceId receiver = 3;
+   */
+  receiver?: DeviceId | undefined;
+
+  /**
+   * @generated from field: kusinta.iot.link.v1.LinkFunction function = 4;
+   */
+  function: LinkFunction;
+};
+
+/**
+ * Describes the message kusinta.iot.connector.v1.RemoveLink.
+ * Use `create(RemoveLinkSchema)` to create a new message.
+ */
+export declare const RemoveLinkSchema: GenMessage<RemoveLink>;
+
+/**
+ * Asks the connector what links the hub holds, for reconciliation outside a
+ * handshake.
+ *
+ * @generated from message kusinta.iot.connector.v1.ListLinks
+ */
+export declare type ListLinks = Message<"kusinta.iot.connector.v1.ListLinks"> & {
+  /**
+   * Unset asks for every link the hub holds.
+   *
+   * @generated from field: kusinta.iot.identity.v1.DeviceId device_id = 1;
+   */
+  deviceId?: DeviceId | undefined;
+};
+
+/**
+ * Describes the message kusinta.iot.connector.v1.ListLinks.
+ * Use `create(ListLinksSchema)` to create a new message.
+ */
+export declare const ListLinksSchema: GenMessage<ListLinks>;
+
+/**
+ * What became of a CreateLink or RemoveLink, connector to gateway.
+ *
+ * Reports the link's observed state rather than merely whether the call was
+ * accepted. A hub will report a link as present and healthy while the devices
+ * ignore it, so "the request did not fail" is not the same claim as "the link is
+ * carrying" and must not be encoded as though it were.
+ *
+ * @generated from message kusinta.iot.connector.v1.LinkResult
+ */
+export declare type LinkResult = Message<"kusinta.iot.connector.v1.LinkResult"> & {
+  /**
+   * @generated from field: string link_id = 1;
+   */
+  linkId: string;
+
+  /**
+   * @generated from field: bool success = 2;
+   */
+  success: boolean;
+
+  /**
+   * @generated from field: kusinta.iot.link.v1.LinkState state = 3;
+   */
+  state: LinkState;
+
+  /**
+   * Why not, when success is false. For a person; never parsed.
+   *
+   * @generated from field: string detail = 4;
+   */
+  detail: string;
+};
+
+/**
+ * Describes the message kusinta.iot.connector.v1.LinkResult.
+ * Use `create(LinkResultSchema)` to create a new message.
+ */
+export declare const LinkResultSchema: GenMessage<LinkResult>;
+
+/**
+ * Every link the hub holds, connector to gateway, in reply to ListLinks.
+ *
+ * @generated from message kusinta.iot.connector.v1.LinksReported
+ */
+export declare type LinksReported = Message<"kusinta.iot.connector.v1.LinksReported"> & {
+  /**
+   * @generated from field: repeated kusinta.iot.link.v1.DeviceLink links = 1;
+   */
+  links: DeviceLink[];
+};
+
+/**
+ * Describes the message kusinta.iot.connector.v1.LinksReported.
+ * Use `create(LinksReportedSchema)` to create a new message.
+ */
+export declare const LinksReportedSchema: GenMessage<LinksReported>;
+
 /**
  * @generated from message kusinta.iot.connector.v1.HandshakeAck
  */
@@ -99,6 +661,25 @@ export declare type HandshakeAck = Message<"kusinta.iot.connector.v1.HandshakeAc
    * @generated from field: kusinta.iot.identity.v1.GatewayId gateway_id = 3;
    */
   gatewayId?: GatewayId | undefined;
+
+  /**
+   * The gateway understands BackendHealthReport and ReinitializeBackendResult. A connector
+   * sends either on the session only when this is set. Unset — a gateway that predates
+   * backend health — the connector sends neither and works as before; such a gateway never
+   * sends ReinitializeBackend.
+   *
+   * @generated from field: bool supports_backend_health = 4;
+   */
+  supportsBackendHealth: boolean;
+
+  /**
+   * The gateway sends account link tokens (CredentialsSnapshot, CredentialsUpdate) to a
+   * connector that declares ConnectorInfo.consumes_credentials and that it trusts for the
+   * service. Unset, no token will arrive on this session; the connector reads no link.
+   *
+   * @generated from field: bool sends_credentials = 5;
+   */
+  sendsCredentials: boolean;
 };
 
 /**
@@ -122,6 +703,38 @@ export declare type DeviceAnnouncement = Message<"kusinta.iot.connector.v1.Devic
    * @generated from field: kusinta.iot.device.v1.Device device = 2;
    */
   device?: Device | undefined;
+
+  /**
+   * The pairing request this device arrived for, empty for a device that arrived on its own.
+   *
+   * This field is the whole attribution mechanism. A connector is the only party that knows
+   * when its own hub was accepting devices, so it decides whether an arrival belongs to a
+   * request and says so here.
+   *
+   * Set it only when the arrival was actually checked. An arrival that fails the check is
+   * still announced — the device exists and has joined — but with this empty, which files it
+   * as belonging to nobody rather than to the wrong person.
+   *
+   * This is EnterPairingMode.request_id, minted per connector, and NOT an app message id:
+   * whoever forwards the outcome to the app has to map it back. The name avoids `in_reply_to`
+   * for that reason, which everywhere else in this schema means the app's own message id.
+   *
+   * @generated from field: string pairing_request_id = 3;
+   */
+  pairingRequestId: string;
+
+  /**
+   * The account link (CredentialsUpdate) the device is read through, empty for a device
+   * that is not. The gateway files the device in that link's home and nowhere else, and
+   * accepts only an id it sent this session and has not revoked; a device naming any other
+   * is filed in no home, and the gateway logs the mismatch. A
+   * device read through two links, as when two homes link the same account, is announced
+   * once per link under distinct device ids, each in its own home; revoking one link
+   * removes only that link's.
+   *
+   * @generated from field: string account_link_id = 4;
+   */
+  accountLinkId: string;
 };
 
 /**
@@ -309,6 +922,127 @@ export declare type ConnectorCommandResult = Message<"kusinta.iot.connector.v1.C
  */
 export declare const ConnectorCommandResultSchema: GenMessage<ConnectorCommandResult>;
 
+/**
+ * Tells a connector to accept new devices for a while, gateway → connector.
+ *
+ * Named for what the connector does rather than for what the app asked. The two legs are
+ * named differently on purpose: the app starts one pairing, and the gateway may put several
+ * connectors into pairing mode to serve it.
+ *
+ * @generated from message kusinta.iot.connector.v1.EnterPairingMode
+ */
+export declare type EnterPairingMode = Message<"kusinta.iot.connector.v1.EnterPairingMode"> & {
+  /**
+   * echoed on PairingModeResult, PairingModeEnded and the announcement
+   *
+   * @generated from field: string request_id = 1;
+   */
+  requestId: string;
+
+  /**
+   * How long, which device, how many. See PairingWindow — and clamp the duration again here.
+   * A connector is the last thing standing between a number on the wire and a radio that
+   * accepts anything nearby for that long.
+   *
+   * @generated from field: kusinta.iot.common.v1.PairingWindow window = 2;
+   */
+  window?: PairingWindow | undefined;
+};
+
+/**
+ * Describes the message kusinta.iot.connector.v1.EnterPairingMode.
+ * Use `create(EnterPairingModeSchema)` to create a new message.
+ */
+export declare const EnterPairingModeSchema: GenMessage<EnterPairingMode>;
+
+/**
+ * A connector's answer to EnterPairingMode: whether the window opened, and nothing more.
+ *
+ * The same accept-now-report-later split as ConnectorCommandResult, for the same reason — a
+ * connector that waited for a device to wake before answering would blow every deadline
+ * above it. What the window produced arrives later, as PairingModeEnded.
+ *
+ * @generated from message kusinta.iot.connector.v1.PairingModeResult
+ */
+export declare type PairingModeResult = Message<"kusinta.iot.connector.v1.PairingModeResult"> & {
+  /**
+   * @generated from field: string request_id = 1;
+   */
+  requestId: string;
+
+  /**
+   * @generated from field: bool accepted = 2;
+   */
+  accepted: boolean;
+
+  /**
+   * Why the window did not open. Only what a connector can observe at this point:
+   * CONNECTOR_UNAVAILABLE, INTERNAL. NOT_ENTITLED and ALREADY_IN_PROGRESS are the gateway's,
+   * decided before this message is sent, and a connector must not claim them.
+   *
+   * @generated from field: kusinta.iot.common.v1.PairingErrorDetail error = 3;
+   */
+  error?: PairingErrorDetail | undefined;
+
+  /**
+   * When the window closes, if it opened. Lets the gateway expire its own record against the
+   * connector's clock rather than a guess — the connector is the party that clamped it.
+   *
+   * @generated from field: google.protobuf.Timestamp expires_at = 4;
+   */
+  expiresAt?: Timestamp | undefined;
+};
+
+/**
+ * Describes the message kusinta.iot.connector.v1.PairingModeResult.
+ * Use `create(PairingModeResultSchema)` to create a new message.
+ */
+export declare const PairingModeResultSchema: GenMessage<PairingModeResult>;
+
+/**
+ * What the window produced, connector → gateway, sent once when it closes.
+ *
+ * Without this the connector has no way to report anything it learned after the window
+ * opened: a device that joined and cannot be modelled, or one that joined and was not the
+ * device the hint named. Neither can travel on a DeviceAnnouncement — the first has nothing
+ * announceable, and the second is announced but unattributed, which says a device arrived
+ * and not why it was refused.
+ *
+ * It also gives a batch window a definite end. Counting announcements cannot distinguish
+ * "three of five so far" from "three of five, and that is all".
+ *
+ * @generated from message kusinta.iot.connector.v1.PairingModeEnded
+ */
+export declare type PairingModeEnded = Message<"kusinta.iot.connector.v1.PairingModeEnded"> & {
+  /**
+   * @generated from field: string request_id = 1;
+   */
+  requestId: string;
+
+  /**
+   * How many arrivals this connector attributed to the request. The gateway can count the
+   * announcements it received, but only the connector knows it has stopped.
+   *
+   * @generated from field: uint32 devices_attributed = 2;
+   */
+  devicesAttributed: number;
+
+  /**
+   * Why it produced fewer than asked for, absent when it produced them all. DEVICE_UNUSABLE
+   * and WRONG_DEVICE are reported here and should name the device in the message, since that
+   * is the only place a user learns which device is now sitting on their hub.
+   *
+   * @generated from field: kusinta.iot.common.v1.PairingErrorDetail error = 3;
+   */
+  error?: PairingErrorDetail | undefined;
+};
+
+/**
+ * Describes the message kusinta.iot.connector.v1.PairingModeEnded.
+ * Use `create(PairingModeEndedSchema)` to create a new message.
+ */
+export declare const PairingModeEndedSchema: GenMessage<PairingModeEnded>;
+
 /**
  * @generated from message kusinta.iot.connector.v1.SessionRequest
  */
@@ -368,6 +1102,44 @@ export declare type SessionRequest = Message<"kusinta.iot.connector.v1.SessionRe
      */
     value: DeviceEventBatch;
     case: "deviceEvents";
+  } | {
+    /**
+     * @generated from field: kusinta.iot.connector.v1.PairingModeResult pairing_mode_result = 10;
+     */
+    value: PairingModeResult;
+    case: "pairingModeResult";
+  } | {
+    /**
+     * @generated from field: kusinta.iot.connector.v1.PairingModeEnded pairing_mode_ended = 11;
+     */
+    value: PairingModeEnded;
+    case: "pairingModeEnded";
+  } | {
+    /**
+     * @generated from field: kusinta.iot.connector.v1.LinkResult link_result = 12;
+     */
+    value: LinkResult;
+    case: "linkResult";
+  } | {
+    /**
+     * @generated from field: kusinta.iot.connector.v1.LinksReported links_reported = 13;
+     */
+    value: LinksReported;
+    case: "linksReported";
+  } | {
+    /**
+     * The backend's health; see BackendHealthReport.
+     *
+     * @generated from field: kusinta.iot.connector.v1.BackendHealthReport backend_health = 14;
+     */
+    value: BackendHealthReport;
+    case: "backendHealth";
+  } | {
+    /**
+     * @generated from field: kusinta.iot.connector.v1.ReinitializeBackendResult reinitialize_backend_result = 15;
+     */
+    value: ReinitializeBackendResult;
+    case: "reinitializeBackendResult";
   } | { case: undefined; value?: undefined };
 };
 
@@ -433,6 +1205,64 @@ export declare type SessionResponse = Message<"kusinta.iot.connector.v1.SessionR
      */
     value: AttributeWriteRequest;
     case: "executeAttributeWrite";
+  } | {
+    /**
+     * The connector-leg half of the pairing flow. See EnterPairingMode.
+     *
+     * @generated from field: kusinta.iot.connector.v1.EnterPairingMode enter_pairing_mode = 10;
+     */
+    value: EnterPairingMode;
+    case: "enterPairingMode";
+  } | {
+    /**
+     * The link operations. Separate cases rather than one with a verb, so a
+     * connector that models none of them fails to match rather than having to
+     * decode a request it cannot serve.
+     *
+     * @generated from field: kusinta.iot.connector.v1.CreateLink create_link = 11;
+     */
+    value: CreateLink;
+    case: "createLink";
+  } | {
+    /**
+     * @generated from field: kusinta.iot.connector.v1.RemoveLink remove_link = 12;
+     */
+    value: RemoveLink;
+    case: "removeLink";
+  } | {
+    /**
+     * @generated from field: kusinta.iot.connector.v1.ListLinks list_links = 13;
+     */
+    value: ListLinks;
+    case: "listLinks";
+  } | {
+    /**
+     * See ReinitializeBackend.
+     *
+     * @generated from field: kusinta.iot.connector.v1.ReinitializeBackend reinitialize_backend = 14;
+     */
+    value: ReinitializeBackend;
+    case: "reinitializeBackend";
+  } | {
+    /**
+     * A linked account's access token, and its end; see CredentialsUpdate.
+     *
+     * @generated from field: kusinta.iot.connector.v1.CredentialsUpdate credentials_update = 15;
+     */
+    value: CredentialsUpdate;
+    case: "credentialsUpdate";
+  } | {
+    /**
+     * @generated from field: kusinta.iot.connector.v1.CredentialsRevoked credentials_revoked = 16;
+     */
+    value: CredentialsRevoked;
+    case: "credentialsRevoked";
+  } | {
+    /**
+     * @generated from field: kusinta.iot.connector.v1.CredentialsSnapshot credentials_snapshot = 17;
+     */
+    value: CredentialsSnapshot;
+    case: "credentialsSnapshot";
   } | { case: undefined; value?: undefined };
 };
 
@@ -442,3 +1272,44 @@ export declare type SessionResponse = Message<"kusinta.iot.connector.v1.SessionR
  */
 export declare const SessionResponseSchema: GenMessage<SessionResponse>;
 
+/**
+ * @generated from enum kusinta.iot.connector.v1.ReinitializeOutcome
+ */
+export enum ReinitializeOutcome {
+  /**
+   * Not stated, or a value this gateway's schema does not know. Read as FAILED.
+   *
+   * @generated from enum value: REINITIALIZE_OUTCOME_UNSPECIFIED = 0;
+   */
+  UNSPECIFIED = 0,
+
+  /**
+   * The connection was dropped and an attempt to establish it again has finished. Its
+   * outcome is the BackendHealthReport sent just before.
+   *
+   * @generated from enum value: REINITIALIZE_OUTCOME_DONE = 1;
+   */
+  DONE = 1,
+
+  /**
+   * The connector could not attempt it at all — no configuration to reconnect with, a fault
+   * of its own. Health is unchanged and no report precedes this.
+   *
+   * @generated from enum value: REINITIALIZE_OUTCOME_FAILED = 2;
+   */
+  FAILED = 2,
+
+  /**
+   * The connector has no backend connection it can re-initialise. A connector that answers
+   * this should not declare supports_backend_reinitialize, but the gateway must handle it.
+   *
+   * @generated from enum value: REINITIALIZE_OUTCOME_NOT_SUPPORTED = 3;
+   */
+  NOT_SUPPORTED = 3,
+}
+
+/**
+ * Describes the enum kusinta.iot.connector.v1.ReinitializeOutcome.
+ */
+export declare const ReinitializeOutcomeSchema: GenEnum<ReinitializeOutcome>;
+