@kusinta/iot-schema 0.2.0-beta.1 → 0.2.0-beta.11

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

@@ -5,12 +5,14 @@
 import type { 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 { ConnectorKind, ConnectorTransport } from "../../common/v1/types_pb.js";
 import type { Device } from "../../device/v1/device_pb.js";
+import type { DeviceLink, LinkFunction, LinkState } from "../../link/v1/link_pb.js";
 import type { Timestamp } from "@bufbuild/protobuf/wkt";
+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";
-import type { AttributeWriteRequest, DeviceCommand } from "../../webrtc/v1/command_pb.js";
 
 /**
  * Describes the file kusinta/iot/connector/v1/connector.proto.
@@ -27,6 +29,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 +58,54 @@ 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;
 };
 
 /**
@@ -73,6 +127,22 @@ 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[];
 };
 
 /**
@@ -81,6 +151,163 @@ export declare type ConnectorHandshake = Message<"kusinta.iot.connector.v1.Conne
  */
 export declare const ConnectorHandshakeSchema: GenMessage<ConnectorHandshake>;
 
+/**
+ * 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
  */
@@ -122,6 +349,25 @@ 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;
 };
 
 /**
@@ -196,6 +442,15 @@ export declare type UnsubscribeDevice = Message<"kusinta.iot.connector.v1.Unsubs
 export declare const UnsubscribeDeviceSchema: GenMessage<UnsubscribeDevice>;
 
 /**
+ * Session-level error, gateway → connector. NOT how a command or a write fails: that is
+ * an ordinary ConnectorCommandResult with success = false and a typed CommandError, and
+ * one operation failing says nothing about the session, which continues.
+ *
+ * code stays a free-form string here, unlike webrtc.v1.GatewayError's closed
+ * GatewayErrorCode and unlike the CommandError below. A connector is versioned on its own
+ * schedule and one may be a third party's, so the set of things that can go wrong between
+ * a gateway and a connector is not closed the way the app leg's is.
+ *
  * @generated from message kusinta.iot.connector.v1.GatewayError
  */
 export declare type GatewayError = Message<"kusinta.iot.connector.v1.GatewayError"> & {
@@ -210,7 +465,7 @@ export declare type GatewayError = Message<"kusinta.iot.connector.v1.GatewayErro
   message: string;
 
   /**
-   * non-empty if the error answers a command or a write
+   * non-empty if the error refers to a specific request
    *
    * @generated from field: string request_id = 3;
    */
@@ -245,14 +500,53 @@ export declare type ConnectorCommandResult = Message<"kusinta.iot.connector.v1.C
   success: boolean;
 
   /**
-   * @generated from field: kusinta.iot.connector.v1.GatewayError error = 3;
+   * @generated from field: google.protobuf.Timestamp completed_at = 4;
    */
-  error?: GatewayError | undefined;
+  completedAt?: Timestamp | undefined;
 
   /**
-   * @generated from field: google.protobuf.Timestamp completed_at = 4;
+   * Why it failed, in the same closed vocabulary the app is eventually given. The gateway
+   * forwards this into webrtc.v1.CommandResult.error unchanged; it does not translate.
+   *
+   * Shared rather than mirrored on purpose. The free-form string this replaces left every
+   * connector to invent its own spellings ("TIMEOUT", "UNSUPPORTED_MODE") and the gateway
+   * to keep a mapping table that silently fell behind whenever a connector coined a new
+   * one — which is the drift a closed vocabulary exists to prevent.
+   *
+   * A connector produces the subset it can actually observe: REJECTED_BY_DEVICE,
+   * UNREACHABLE, TIMEOUT, INVALID_COMMAND, INTERNAL. NOT_ENTITLED and
+   * CONSTRAINT_VIOLATED are the gateway's, decided before a command is forwarded at all;
+   * a connector never sees the caller's permissions and must not claim to.
+   *
+   * Rollout note: a connector whose schema predates this sends nothing on field 5 and the
+   * gateway reads UNSPECIFIED. Set success = false with no code and the meaning is "it
+   * failed, reason unstated" — which is what the string codes amounted to anyway.
+   *
+   * @generated from field: kusinta.iot.webrtc.v1.CommandError error = 5;
    */
-  completedAt?: Timestamp | undefined;
+  error?: CommandError | undefined;
+
+  /**
+   * When this connector's own optimistic window closes: by this time the value has either
+   * been confirmed by the device or restored, and either way the connector will have
+   * published a PropertyUpdate saying so.
+   *
+   * Set it when the connector applied the value optimistically and runs a rollback timer
+   * of its own — a downstream device with a known, device-specific timeout. The gateway
+   * carries it into webrtc.v1.CommandResult.settles_by instead of applying a fixed guess:
+   * the connector is the only party that knows the timer, and a gateway-side constant
+   * chasing it is the same hardcoded-window problem one level up.
+   *
+   * Absent means no claim — either the connector confirms synchronously, or it cannot
+   * state a bound. Absent is NOT "settles immediately", and the gateway is free to fall
+   * back to a deadline of its own when nothing is stated here.
+   *
+   * This bounds the wait; it does not label the values that arrive. Which update was the
+   * optimistic one is device.v1.PropertyUpdate.provenance.
+   *
+   * @generated from field: optional google.protobuf.Timestamp settles_by = 6;
+   */
+  settlesBy?: Timestamp | undefined;
 };
 
 /**
@@ -261,6 +555,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
  */
@@ -320,6 +735,30 @@ 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";
   } | { case: undefined; value?: undefined };
 };
 
@@ -385,6 +824,36 @@ 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";
   } | { case: undefined; value?: undefined };
 };