@kusinta/iot-schema 0.2.0-beta.3 → 0.2.0-beta.31

package/src/kusinta/iot/webrtc/v1/envelope_pb.d.ts

@@ -4,12 +4,18 @@
 
 import type { GenEnum, GenFile, GenMessage } from "@bufbuild/protobuf/codegenv2";
 import type { Message } from "@bufbuild/protobuf";
-import type { DeviceId } from "../../identity/v1/identity_pb.js";
+import type { ConnectorId, DeviceId, SpaceId } from "../../identity/v1/identity_pb.js";
 import type { AttributeRef } from "../../access/v1/acl_pb.js";
 import type { Space } from "../../space/v1/space_pb.js";
-import type { ManagementAck, ManagementRequest, SpaceTree } from "./management_pb.js";
+import type { ManagementAck, ManagementRequest, PrivacyDisclosure, SpaceTree } from "./management_pb.js";
+import type { DeviceLink, DeviceLinkList } from "../../link/v1/link_pb.js";
+import type { ApartmentClimateSummary, ClimateMode, RoomClimate, RoomClimateList, RoomHistory } from "../../climate/v1/climate_pb.js";
+import type { IssuedInvite, SpaceInvites } from "./invite_pb.js";
+import type { GatewayMembers } from "./members_pb.js";
+import type { PairingErrorDetail, PairingWindow } from "../../common/v1/pairing_pb.js";
+import type { BackendHealth, ConnectorKind, DeviceOwnershipType } from "../../common/v1/types_pb.js";
 import type { Timestamp } from "@bufbuild/protobuf/wkt";
-import type { DeviceAdded, DeviceRemoved, DeviceStateSnapshot, PropertyReport } from "./device_state_pb.js";
+import type { DeviceAdded, DeviceRemoved, DeviceStateSnapshot, PropertyReport, ServiceStatusChanged } from "./device_state_pb.js";
 import type { LivePermissionUpdate } from "./permission_push_pb.js";
 import type { AttributeWriteRequest, CommandResult, DeviceCommand } from "./command_pb.js";
 import type { DeviceEventBatch } from "../../device/v1/device_event_pb.js";
@@ -316,6 +322,70 @@ export declare type ManagementResult = Message<"kusinta.iot.webrtc.v1.Management
      */
     value: ManagementAck;
     case: "ack";
+  } | {
+    /**
+     * list_device_links
+     *
+     * @generated from field: kusinta.iot.link.v1.DeviceLinkList links = 6;
+     */
+    value: DeviceLinkList;
+    case: "links";
+  } | {
+    /**
+     * list_room_climates
+     *
+     * @generated from field: kusinta.iot.climate.v1.RoomClimateList room_climates = 7;
+     */
+    value: RoomClimateList;
+    case: "roomClimates";
+  } | {
+    /**
+     * get_room_history
+     *
+     * @generated from field: kusinta.iot.climate.v1.RoomHistory room_history = 8;
+     */
+    value: RoomHistory;
+    case: "roomHistory";
+  } | {
+    /**
+     * get_privacy_disclosure
+     *
+     * @generated from field: kusinta.iot.webrtc.v1.PrivacyDisclosure privacy_disclosure = 9;
+     */
+    value: PrivacyDisclosure;
+    case: "privacyDisclosure";
+  } | {
+    /**
+     * get_apartment_climate_summary
+     *
+     * @generated from field: kusinta.iot.climate.v1.ApartmentClimateSummary apartment_climate_summary = 10;
+     */
+    value: ApartmentClimateSummary;
+    case: "apartmentClimateSummary";
+  } | {
+    /**
+     * create_invite, resend_invite
+     *
+     * @generated from field: kusinta.iot.webrtc.v1.IssuedInvite issued_invite = 11;
+     */
+    value: IssuedInvite;
+    case: "issuedInvite";
+  } | {
+    /**
+     * list_space_invites
+     *
+     * @generated from field: kusinta.iot.webrtc.v1.SpaceInvites space_invites = 12;
+     */
+    value: SpaceInvites;
+    case: "spaceInvites";
+  } | {
+    /**
+     * list_gateway_members
+     *
+     * @generated from field: kusinta.iot.webrtc.v1.GatewayMembers gateway_members = 13;
+     */
+    value: GatewayMembers;
+    case: "gatewayMembers";
   } | { case: undefined; value?: undefined };
 };
 
@@ -325,9 +395,383 @@ export declare type ManagementResult = Message<"kusinta.iot.webrtc.v1.Management
  */
 export declare const ManagementResultSchema: GenMessage<ManagementResult>;
 
+/**
+ * Asks the gateway to put a connector into pairing mode, so a device joined during the
+ * window becomes the caller's rather than belonging to nobody.
+ *
+ * A payload case of its own rather than a ManagementRequest. Those are gated on a target —
+ * a space, a device — and that is the justification for keeping them behind one wrapper.
+ * A connector is not a target the caller must reach the way a space is, so this is
+ * authorized against the caller's role and nothing else — but it must still name the
+ * connector to open (see connector_id), never every connector at once.
+ *
+ * Answered twice, and the two answers say different things at different times.
+ * PairingStarted reports whether the window opened; PairingFinished reports what came of
+ * it, seconds or minutes later, once someone has pressed a button on hardware that may be
+ * asleep or out of range.
+ *
+ * @generated from message kusinta.iot.webrtc.v1.StartPairing
+ */
+export declare type StartPairing = Message<"kusinta.iot.webrtc.v1.StartPairing"> & {
+  /**
+   * Which connector to open. Required: pairing always targets exactly one connector,
+   * picked from the connector enumeration (see ConnectorsAnnounced and
+   * ConnectorInfo.supports_pairing). An untargeted request is refused with
+   * PairingError.CONNECTOR_REQUIRED, never fanned out across every hub — so that no
+   * client can open every radio at once, and so a device is paired onto the specific hub
+   * that will broker its links. The field is a message, so proto cannot mark it required;
+   * the gateway enforces it.
+   *
+   * @generated from field: kusinta.iot.identity.v1.ConnectorId connector_id = 1;
+   */
+  connectorId?: ConnectorId | undefined;
+
+  /**
+   * How long, which device, how many. See PairingWindow.
+   *
+   * @generated from field: kusinta.iot.common.v1.PairingWindow window = 2;
+   */
+  window?: PairingWindow | undefined;
+
+  /**
+   * Where to file the device once it arrives. Into a home only as PlaceDeviceInSpace
+   * allows.
+   *
+   * Optional, and the two cases differ. A caller pairing a device of their own must name a
+   * space they reach, so it is theirs and placed on arrival rather than sitting unfiled and
+   * invisible to them. A caller commissioning for a building may leave it unset: a building
+   * is commissioned before its spaces are recorded, and an unfiled device is visible to the
+   * administrator, who is the person doing the pairing.
+   *
+   * @generated from field: kusinta.iot.identity.v1.SpaceId initial_space_id = 3;
+   */
+  initialSpaceId?: SpaceId | undefined;
+
+  /**
+   * What the device should become. Unset lets the gateway decide from the caller's role,
+   * which is the reading that scales: someone commissioning fifty devices for a building
+   * should not come to own fifty devices because a field defaulted.
+   *
+   * The gateway refuses an ownership the caller may not confer, and never mints ownership
+   * for a third party — handing a device to someone else is a transfer, a separate operation
+   * with its own authority.
+   *
+   * @generated from field: kusinta.iot.common.v1.DeviceOwnershipType ownership = 4;
+   */
+  ownership: DeviceOwnershipType;
+};
+
+/**
+ * Describes the message kusinta.iot.webrtc.v1.StartPairing.
+ * Use `create(StartPairingSchema)` to create a new message.
+ */
+export declare const StartPairingSchema: GenMessage<StartPairing>;
+
+/**
+ * Whether the pairing window opened, gateway → app. The first of two answers to a
+ * StartPairing.
+ *
+ * @generated from message kusinta.iot.webrtc.v1.PairingStarted
+ */
+export declare type PairingStarted = Message<"kusinta.iot.webrtc.v1.PairingStarted"> & {
+  /**
+   * AppMessage.message_id of the StartPairing
+   *
+   * @generated from field: string in_reply_to = 1;
+   */
+  inReplyTo: string;
+
+  /**
+   * When the window closes. Present when it opened, and this is the value to count down
+   * from — not the duration that was asked for, which both the gateway and the connector
+   * clamp. A countdown run on the request rather than on this one disagrees with the hub.
+   *
+   * @generated from field: google.protobuf.Timestamp expires_at = 2;
+   */
+  expiresAt?: Timestamp | undefined;
+
+  /**
+   * Why it did not open. Present instead of expires_at.
+   *
+   * @generated from field: kusinta.iot.common.v1.PairingErrorDetail error = 3;
+   */
+  error?: PairingErrorDetail | undefined;
+};
+
+/**
+ * Describes the message kusinta.iot.webrtc.v1.PairingStarted.
+ * Use `create(PairingStartedSchema)` to create a new message.
+ */
+export declare const PairingStartedSchema: GenMessage<PairingStarted>;
+
+/**
+ * What the pairing window produced, gateway → app. The second and last answer, sent once
+ * when the window closes.
+ *
+ * One message per request, not per device: a batch window attributes several, and a client
+ * given one message each has nothing telling it the window is over and no defined moment to
+ * stop waiting. The devices are listed here; each also arrives as an ordinary DeviceAdded
+ * as it appears, so a client may show them as they come and use this to finish.
+ *
+ * An error and a non-empty device list are not exclusive. A batch of five that attributed
+ * three and then expired reports both — three devices and NO_DEVICE_APPEARED — because
+ * "some worked" and "the window ran out" are both true and a user needs to be told both.
+ *
+ * @generated from message kusinta.iot.webrtc.v1.PairingFinished
+ */
+export declare type PairingFinished = Message<"kusinta.iot.webrtc.v1.PairingFinished"> & {
+  /**
+   * AppMessage.message_id of the StartPairing
+   *
+   * @generated from field: string in_reply_to = 1;
+   */
+  inReplyTo: string;
+
+  /**
+   * @generated from field: repeated kusinta.iot.identity.v1.DeviceId device_ids = 2;
+   */
+  deviceIds: DeviceId[];
+
+  /**
+   * Why the window produced fewer devices than asked for, absent when it produced them all.
+   * Note this is not always a failure of the request: a window that simply expired unused
+   * ends here too, and is the ordinary result of a user changing their mind.
+   *
+   * @generated from field: kusinta.iot.common.v1.PairingErrorDetail error = 3;
+   */
+  error?: PairingErrorDetail | undefined;
+};
+
+/**
+ * Describes the message kusinta.iot.webrtc.v1.PairingFinished.
+ * Use `create(PairingFinishedSchema)` to create a new message.
+ */
+export declare const PairingFinishedSchema: GenMessage<PairingFinished>;
+
 /**
  * GatewayMessage: gateway → app
+ * A link between two devices has changed, gateway to app.
+ *
+ * Sent without being asked for, like device_added, and for the same reason: a link's
+ * state is not settled when it is made. A hub accepting a link is not the two devices
+ * honouring it, and a link that was carrying stops when its sender goes quiet — so the
+ * interesting transitions all happen long after the request that created it was
+ * answered. Without this an app can only learn by listing every link again and
+ * diffing, which means a room that has quietly stopped following its wall thermostat
+ * looks correct until somebody reloads.
+ *
+ * Apply as an upsert keyed on link.link_id, never as an insert: the same link is sent
+ * again whenever its state moves.
+ *
+ * Sent only for links the recipient is entitled to see. An unfiltered one would say
+ * which devices exist and how they are arranged, to somebody entitled to neither. A link
+ * with an end in a home reaches a recipient who sees it as service with details_withheld,
+ * and is pushed to them only when it appears and when it is removed — never for anything
+ * else, its state and settings included, which are not theirs to see. Its removal is pushed
+ * to them at once, as every loss is — to those who were shown it, and to nobody else.
+ *
+ * @generated from message kusinta.iot.webrtc.v1.LinkChanged
+ */
+export declare type LinkChanged = Message<"kusinta.iot.webrtc.v1.LinkChanged"> & {
+  /**
+   * @generated from field: kusinta.iot.link.v1.DeviceLink link = 1;
+   */
+  link?: DeviceLink | undefined;
+
+  /**
+   * The link is gone, rather than merely not carrying. Distinct from a BROKEN state
+   * because the two need opposite responses: a removal is finished business, while a
+   * link that has stopped carrying is a fault worth showing somebody. Announcing a
+   * deletion as BROKEN would leave every removed link looking like something to go
+   * and repair.
+   *
+   * `link` still carries the whole link when this is set, so the app can name what
+   * went rather than only its id — as much of it as the recipient was shown, so with
+   * details_withheld to one who saw it as service. To such a recipient it means the link is
+   * gone from their view, which need not mean it is gone.
+   *
+   * @generated from field: bool removed = 2;
+   */
+  removed: boolean;
+};
+
+/**
+ * Describes the message kusinta.iot.webrtc.v1.LinkChanged.
+ * Use `create(LinkChangedSchema)` to create a new message.
+ */
+export declare const LinkChangedSchema: GenMessage<LinkChanged>;
+
+/**
+ * One connected connector, described for the app, gateway → app.
+ *
+ * Deliberately not connector.v1.ConnectorInfo: that carries transport and endpoint,
+ * which are the gateway↔connector wiring and no business of the app. This is the
+ * app-facing projection — who the connector is and what it can do — and nothing
+ * about how the gateway reaches it.
+ *
+ * @generated from message kusinta.iot.webrtc.v1.ConnectorDescriptor
+ */
+export declare type ConnectorDescriptor = Message<"kusinta.iot.webrtc.v1.ConnectorDescriptor"> & {
+  /**
+   * The routing key. Stable and unique; what StartPairing.connector_id and
+   * ProvisionDevice.connector_id name.
+   *
+   * @generated from field: kusinta.iot.identity.v1.ConnectorId connector_id = 1;
+   */
+  connectorId?: ConnectorId | undefined;
+
+  /**
+   * User-facing label, free-form, never matched on.
+   *
+   * @generated from field: string display_name = 2;
+   */
+  displayName: string;
+
+  /**
+   * @generated from field: repeated uint32 supported_device_type_ids = 3;
+   */
+  supportedDeviceTypeIds: number[];
+
+  /**
+   * The capabilities the app branches on. Copied from the connector's handshake;
+   * see ConnectorInfo for what each means. The app decides pairing-vs-provisioning
+   * and whether to offer hard links from these, never from kind.
+   *
+   * @generated from field: bool supports_pairing = 4;
+   */
+  supportsPairing: boolean;
+
+  /**
+   * @generated from field: bool supports_provisioning = 5;
+   */
+  supportsProvisioning: boolean;
+
+  /**
+   * @generated from field: bool brokers_links = 6;
+   */
+  brokersLinks: boolean;
+
+  /**
+   * Presentation only — an icon or an "unknown hub" fallback; see
+   * common.v1.ConnectorKind. Unset renders as a generic hub.
+   *
+   * @generated from field: kusinta.iot.common.v1.ConnectorKind kind = 7;
+   */
+  kind: ConnectorKind;
+
+  /**
+   * Installer or operator detail, free-form, for a person.
+   *
+   * @generated from field: string description = 8;
+   */
+  description: string;
+
+  /**
+   * Whether the backend the connector drives is working, as the connector last reported it
+   * (see connector.v1.BackendHealthReport): state and category only — the connector's own
+   * detail stays in the gateway's logs. Unset when the connector has stated nothing, which
+   * reads as OK. FAILING is what opens a reporting.v1.PROBLEM_KIND_CONNECTOR_ERROR, and
+   * while it holds the app may offer ReconnectConnector.
+   *
+   * @generated from field: kusinta.iot.common.v1.BackendHealth backend_health = 9;
+   */
+  backendHealth?: BackendHealth | undefined;
+
+  /**
+   * The connector can re-initialise its backend on request: ReconnectConnector is
+   * refused for any connector without it. Copied from the handshake, as the other
+   * capabilities are.
+   *
+   * @generated from field: bool supports_backend_reinitialize = 10;
+   */
+  supportsBackendReinitialize: boolean;
+};
+
+/**
+ * Describes the message kusinta.iot.webrtc.v1.ConnectorDescriptor.
+ * Use `create(ConnectorDescriptorSchema)` to create a new message.
+ */
+export declare const ConnectorDescriptorSchema: GenMessage<ConnectorDescriptor>;
+
+/**
+ * The connectors the gateway currently holds, gateway → app: those connected now. A
+ * connector whose stream drops leaves the list, and its backend health with it; it is
+ * listed again when it reconnects. The app offers ReconnectConnector only for a listed
+ * connector.
+ *
+ * A push, not a ManagementResult arm: a new result-oneof member is a compile error
+ * in a consumer whose match on the result is exhaustive, whereas a new push case is
+ * absorbed by that switch's default. Sent on connect and whenever the set changes —
+ * a connector arriving, leaving, revising its capabilities, or its backend health
+ * changing — and replaces the app's whole picture each time rather than being a delta,
+ * so a client that missed one re-syncs from the next.
+ *
+ * @generated from message kusinta.iot.webrtc.v1.ConnectorsAnnounced
+ */
+export declare type ConnectorsAnnounced = Message<"kusinta.iot.webrtc.v1.ConnectorsAnnounced"> & {
+  /**
+   * @generated from field: repeated kusinta.iot.webrtc.v1.ConnectorDescriptor connectors = 1;
+   */
+  connectors: ConnectorDescriptor[];
+};
+
+/**
+ * Describes the message kusinta.iot.webrtc.v1.ConnectorsAnnounced.
+ * Use `create(ConnectorsAnnouncedSchema)` to create a new message.
+ */
+export declare const ConnectorsAnnouncedSchema: GenMessage<ConnectorsAnnounced>;
+
+/**
+ * A room's climate changed, gateway → app: its target, what set it, what it is being
+ * held at, its condition. Apply as an upsert keyed on room.space_id. Sent only for rooms
+ * the recipient may see, and whenever any field the recipient is sent moves — a knob
+ * turned by hand shows up here without the app asking. To a recipient who sees the room
+ * as service, what is new is sent as it happens and what is lost at once. A recipient who
+ * is sent the room with state_withheld is therefore not sent it when only withheld fields
+ * move.
  *
+ * @generated from message kusinta.iot.webrtc.v1.RoomClimateChanged
+ */
+export declare type RoomClimateChanged = Message<"kusinta.iot.webrtc.v1.RoomClimateChanged"> & {
+  /**
+   * @generated from field: kusinta.iot.climate.v1.RoomClimate room = 1;
+   */
+  room?: RoomClimate | undefined;
+};
+
+/**
+ * Describes the message kusinta.iot.webrtc.v1.RoomClimateChanged.
+ * Use `create(RoomClimateChangedSchema)` to create a new message.
+ */
+export declare const RoomClimateChangedSchema: GenMessage<RoomClimateChanged>;
+
+/**
+ * A mode on a space was switched on, changed or ended, gateway → app. `ended` rather than
+ * kind UNSPECIFIED, so an app can still name the mode that finished. A mode on an
+ * apartment or a room in one is sent to its residents only — whether a home stands empty
+ * is theirs to know; one on any other space, to whoever reaches it.
+ *
+ * @generated from message kusinta.iot.webrtc.v1.ClimateModeChanged
+ */
+export declare type ClimateModeChanged = Message<"kusinta.iot.webrtc.v1.ClimateModeChanged"> & {
+  /**
+   * @generated from field: kusinta.iot.climate.v1.ClimateMode mode = 1;
+   */
+  mode?: ClimateMode | undefined;
+
+  /**
+   * @generated from field: bool ended = 2;
+   */
+  ended: boolean;
+};
+
+/**
+ * Describes the message kusinta.iot.webrtc.v1.ClimateModeChanged.
+ * Use `create(ClimateModeChangedSchema)` to create a new message.
+ */
+export declare const ClimateModeChangedSchema: GenMessage<ClimateModeChanged>;
+
+/**
  * @generated from message kusinta.iot.webrtc.v1.GatewayMessage
  */
 export declare type GatewayMessage = Message<"kusinta.iot.webrtc.v1.GatewayMessage"> & {
@@ -421,6 +865,56 @@ export declare type GatewayMessage = Message<"kusinta.iot.webrtc.v1.GatewayMessa
      */
     value: DeviceEventBatch;
     case: "deviceEvents";
+  } | {
+    /**
+     * @generated from field: kusinta.iot.webrtc.v1.PairingStarted pairing_started = 17;
+     */
+    value: PairingStarted;
+    case: "pairingStarted";
+  } | {
+    /**
+     * @generated from field: kusinta.iot.webrtc.v1.PairingFinished pairing_finished = 18;
+     */
+    value: PairingFinished;
+    case: "pairingFinished";
+  } | {
+    /**
+     * @generated from field: kusinta.iot.webrtc.v1.LinkChanged link_changed = 19;
+     */
+    value: LinkChanged;
+    case: "linkChanged";
+  } | {
+    /**
+     * @generated from field: kusinta.iot.webrtc.v1.ConnectorsAnnounced connectors_announced = 20;
+     */
+    value: ConnectorsAnnounced;
+    case: "connectorsAnnounced";
+  } | {
+    /**
+     * @generated from field: kusinta.iot.webrtc.v1.RoomClimateChanged room_climate_changed = 21;
+     */
+    value: RoomClimateChanged;
+    case: "roomClimateChanged";
+  } | {
+    /**
+     * @generated from field: kusinta.iot.webrtc.v1.ClimateModeChanged climate_mode_changed = 22;
+     */
+    value: ClimateModeChanged;
+    case: "climateModeChanged";
+  } | {
+    /**
+     * @generated from field: kusinta.iot.webrtc.v1.ServiceStatusChanged service_status_changed = 23;
+     */
+    value: ServiceStatusChanged;
+    case: "serviceStatusChanged";
+  } | {
+    /**
+     * A space's pending invites and join requests changed; see SpaceInvites.
+     *
+     * @generated from field: kusinta.iot.webrtc.v1.SpaceInvites space_invites = 24;
+     */
+    value: SpaceInvites;
+    case: "spaceInvites";
   } | { case: undefined; value?: undefined };
 };
 
@@ -497,6 +991,12 @@ export declare type AppMessage = Message<"kusinta.iot.webrtc.v1.AppMessage"> & {
      */
     value: AttributeWriteRequest;
     case: "attributeWrite";
+  } | {
+    /**
+     * @generated from field: kusinta.iot.webrtc.v1.StartPairing start_pairing = 11;
+     */
+    value: StartPairing;
+    case: "startPairing";
   } | { case: undefined; value?: undefined };
 };
 
@@ -570,6 +1070,23 @@ export enum GatewayErrorCode {
    * @generated from enum value: GATEWAY_ERROR_CODE_SESSION_LIMIT_REACHED = 5;
    */
   SESSION_LIMIT_REACHED = 5,
+
+  /**
+   * The request was well formed and the caller may make it, but it will not succeed without
+   * a change on the receiving side — a capability the target lacks, configuration only a
+   * person can fix. Do not retry as is. Distinct from INVALID_REQUEST, which is the app's
+   * bug, and from UNAVAILABLE, which clears on its own. GatewayError.metadata says which
+   * precondition failed where the operation documents one. Sent only in answer to a request
+   * whose operation documents it, never as a session-level error that refuses or ends a
+   * session.
+   *
+   * Rollout note: a client whose schema predates this value decodes it as UNSPECIFIED,
+   * which is retryable by design, so it may offer a retry that fails the same way again.
+   * Harmless, but client handling should ship before or with the gateway that emits it.
+   *
+   * @generated from enum value: GATEWAY_ERROR_CODE_FAILED_PRECONDITION = 6;
+   */
+  FAILED_PRECONDITION = 6,
 }
 
 /**