@kusinta/iot-schema 0.2.0-beta.30 → 0.2.0-beta.32

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kusinta/iot-schema",
-  "version": "0.2.0-beta.30",
+  "version": "0.2.0-beta.32",
   "type": "module",
   "license": "MIT",
   "files": ["src"],

package/src/kusinta/iot/access/v1/roles_pb.d.ts

@@ -43,8 +43,9 @@ export declare const file_kusinta_iot_access_v1_roles: GenFile;
  * schema says "staff" or "a staff member" it means exactly that, as the gateway holds roles,
  * the registering administrator included; holding ROLE_RESIDENT besides changes nothing. The
  * term carries one rule about people: staff are named to whoever may list every member; a
- * resident is named only to the people they live with; and where anyone lives is told only
- * to their own household.
+ * resident is named only to the people they live with; and where anyone lives is told by
+ * user id only to their own household, and to anyone else only under a residency id
+ * (MembershipRelation, RESIDENCY IDS).
  *
  * @generated from enum kusinta.iot.access.v1.Role
  */
@@ -245,9 +246,19 @@ export declare const PermissionActionSchema: GenEnum<PermissionAction>;
  * property owner or the administrator out by force — they hold the building's filing
  * authority and the gateway itself — but it makes their seeing in a deliberate act on the
  * home, such as filing themselves on it, rather than something handed out by default. They
- * remove a resident who moves out, so they are shown each resident's homes, and since when
- * (webrtc.v1.ListGatewayMembers), but never a resident's name; and a staff member's own
- * residency is told only to the household they live in (see Role, STAFF).
+ * remove a resident who moves out, so they are shown every residency, and since when
+ * (webrtc.v1.ListGatewayMembers), but never who holds it (see RESIDENCY IDS).
+ *
+ * RESIDENCY IDS. To a caller who does not live in the home, a RESIDENT membership is told
+ * only under its residency id: an id the gateway mints for that residency alone, when it
+ * begins, holds for as long as it lasts unbroken, and never reuses. It is opaque, begins
+ * with "residency:", and is never a user's id or derived from one, so nothing told under it
+ * ties the residency to a name, a role or another membership — and nothing changes it when
+ * the person who holds it becomes staff or stops being staff (Role, STAFF). A relation
+ * change, or the residency ending, ends its id. The people of the home see one another
+ * under their user ids. Where a request below names a member, it says whether a residency
+ * id may stand for one; a request that does not say so refuses one as INVALID_REQUEST, so
+ * that no user is ever made under one.
  *
  * A membership recorded with no relation, made before relations existed, sees no more than
  * either relation would where it is held: on an apartment or a room, a home as service; on a

package/src/kusinta/iot/access/v1/roles_pb.js

@@ -50,8 +50,9 @@ export const RoleSchema = /*@__PURE__*/
  * schema says "staff" or "a staff member" it means exactly that, as the gateway holds roles,
  * the registering administrator included; holding ROLE_RESIDENT besides changes nothing. The
  * term carries one rule about people: staff are named to whoever may list every member; a
- * resident is named only to the people they live with; and where anyone lives is told only
- * to their own household.
+ * resident is named only to the people they live with; and where anyone lives is told by
+ * user id only to their own household, and to anyone else only under a residency id
+ * (MembershipRelation, RESIDENCY IDS).
  *
  * @generated from enum kusinta.iot.access.v1.Role
  */
@@ -149,9 +150,19 @@ export const MembershipRelationSchema = /*@__PURE__*/
  * property owner or the administrator out by force — they hold the building's filing
  * authority and the gateway itself — but it makes their seeing in a deliberate act on the
  * home, such as filing themselves on it, rather than something handed out by default. They
- * remove a resident who moves out, so they are shown each resident's homes, and since when
- * (webrtc.v1.ListGatewayMembers), but never a resident's name; and a staff member's own
- * residency is told only to the household they live in (see Role, STAFF).
+ * remove a resident who moves out, so they are shown every residency, and since when
+ * (webrtc.v1.ListGatewayMembers), but never who holds it (see RESIDENCY IDS).
+ *
+ * RESIDENCY IDS. To a caller who does not live in the home, a RESIDENT membership is told
+ * only under its residency id: an id the gateway mints for that residency alone, when it
+ * begins, holds for as long as it lasts unbroken, and never reuses. It is opaque, begins
+ * with "residency:", and is never a user's id or derived from one, so nothing told under it
+ * ties the residency to a name, a role or another membership — and nothing changes it when
+ * the person who holds it becomes staff or stops being staff (Role, STAFF). A relation
+ * change, or the residency ending, ends its id. The people of the home see one another
+ * under their user ids. Where a request below names a member, it says whether a residency
+ * id may stand for one; a request that does not say so refuses one as INVALID_REQUEST, so
+ * that no user is ever made under one.
  *
  * A membership recorded with no relation, made before relations existed, sees no more than
  * either relation would where it is held: on an apartment or a room, a home as service; on a

package/src/kusinta/iot/space/v1/space_pb.d.ts

@@ -113,10 +113,11 @@ export declare type Space = Message<"kusinta.iot.space.v1.Space"> & {
    *     hold it, and who, without saying where anyone lives;
    *   * anyone else sees none, residents of a building or floor included.
    *
-   * Whoever it is listed to, a member who is staff (access.v1.Role, STAFF) and lives in a
-   * home has that RESIDENT membership left out for every caller who does not live in that
-   * home, a property owner and an administrator included: a staff member's residency is
-   * told only to its household. Their SERVICE memberships are listed as any member's.
+   * To a caller who does not live in the home, a RESIDENT member is listed under the
+   * residency's id (access.v1.MembershipRelation, RESIDENCY IDS) and never by name, so that
+   * a home's residents are told apart from one another and from anyone's other memberships
+   * without saying who they are. The people of the home see one another under their user
+   * ids.
    *
    * @generated from field: repeated kusinta.iot.space.v1.SpaceMember members = 13;
    */
@@ -144,6 +145,9 @@ export declare const SpaceSchema: GenMessage<Space>;
  */
 export declare type SpaceMember = Message<"kusinta.iot.space.v1.SpaceMember"> & {
   /**
+   * The member's user id, or for a RESIDENT member listed to a caller who does not live in
+   * the home, the residency's id (Space.members).
+   *
    * @generated from field: kusinta.iot.identity.v1.UserId user_id = 1;
    */
   userId?: UserId | undefined;

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

@@ -59,7 +59,9 @@ export declare type CreateInvite = Message<"kusinta.iot.webrtc.v1.CreateInvite">
    *
    * One pending invite per space and address: a second for the same address on the same
    * space is refused as FAILED_PRECONDITION with metadata {"reason": "already_invited",
-   * "invite_id": <the pending one>}, so the app can offer to resend that one instead.
+   * "invite_id": <the pending one>}, so the app can offer to resend that one instead. A
+   * household invite and one made by a property owner or an administrator are counted
+   * apart, so the refusal never names an invite the caller is not shown (ListSpaceInvites).
    *
    * The gateway keeps the address only while the invite is pending, and drops it once the
    * invite is redeemed, revoked or expired.

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

@@ -198,6 +198,11 @@ export declare const DeleteSpaceSchema: GenMessage<DeleteSpace>;
  * Who may change who belongs to a home is restricted by the gateway; a caller not allowed is
  * refused as NOT_ENTITLED. Residents see who is filed on their home in Space.members.
  *
+ * A membership the caller is not told of under this user id (a residency, to anyone outside
+ * its household: access.v1.MembershipRelation, RESIDENCY IDS) is never changed through it:
+ * assigning onto it is refused as NOT_ENTITLED, and RemoveUserFromSpace answers as for one
+ * that does not exist. user_id is never a residency id.
+ *
  * @generated from message kusinta.iot.webrtc.v1.AssignUserToSpace
  */
 export declare type AssignUserToSpace = Message<"kusinta.iot.webrtc.v1.AssignUserToSpace"> & {
@@ -231,7 +236,14 @@ export declare const AssignUserToSpaceSchema: GenMessage<AssignUserToSpace>;
  * Removes a user's membership of a space. Losing reach also drops whatever the
  * user was streaming from it, announced by LivePermissionUpdate.
  *
- * Removing someone else from a home is guarded as assigning is.
+ * Removing someone else from a home is guarded as assigning is. A membership the caller is
+ * not told of under the user id given (see AssignUserToSpace) is answered as one that does
+ * not exist, and stays.
+ *
+ * user_id may be a residency id (access.v1.MembershipRelation, RESIDENCY IDS): it then ends
+ * that residency, if space_id is its home, and answers as for one that does not exist
+ * otherwise. This is how a property owner or an administrator ends the residency of
+ * someone who moved out.
  *
  * @generated from message kusinta.iot.webrtc.v1.RemoveUserFromSpace
  */

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

@@ -19,13 +19,16 @@ export declare const file_kusinta_iot_webrtc_v1_members: GenFile;
  * NOT_ENTITLED.
  *
  * Those two roles answer for the whole property, and a resident who moves out is removed by
- * them (RemoveFromGateway), so every member is listed to them. Each is told apart as the rule
- * for staff allows (access.v1.Role, STAFF):
- *   * a resident by their memberships — the homes they live in, and since when
- *     (MemberSpace.since) — never by name or address;
- *   * staff by name and email address (MemberDetail.name, MemberDetail.email), and by their
- *     memberships save where they live: a staff member's residency is left out of every
- *     entry but the caller's own, since a residency is told only to its household.
+ * them (RemoveUserFromSpace or RemoveFromGateway), so every member is listed to them, as the
+ * rule for staff allows (access.v1.Role, STAFF):
+ *   * every residency as an entry of its own, under its residency id: the one RESIDENT
+ *     membership and since when (MemberSpace.since), with no name, no email and no roles;
+ *   * every user under their user id, while they hold a role or a membership other than a
+ *     residency: their roles save ROLE_RESIDENT, and those other memberships. Staff are
+ *     given by name and email address (MemberDetail.name, MemberDetail.email); anyone else
+ *     by neither;
+ *   * the caller themselves as one entry under their user id, with everything they hold.
+ * So becoming staff, or stopping, changes a user's entry and never a residency's.
  * Seeing into a home's life — its devices, readings and history — still takes filing on it.
  *
  * @generated from message kusinta.iot.webrtc.v1.ListGatewayMembers
@@ -44,6 +47,11 @@ export declare const ListGatewayMembersSchema: GenMessage<ListGatewayMembers>;
  * ManagementAck. Only a caller holding ROLE_GATEWAY_ADMIN may; any other role named is
  * INVALID_REQUEST.
  *
+ * user_id is never a residency id (INVALID_REQUEST): the member's entry would then appear
+ * under their user id, named, and tie the residency to them. A resident becomes staff by
+ * an act of their own — redeeming a SERVICE invite (invite.proto) — and is promoted from
+ * the entry that gives.
+ *
  * Granting a role already held, or taking away one not held, changes nothing and is
  * acknowledged. A caller may take a role away from themselves: the registering
  * administrator always remains, so the gateway cannot be left without one. Naming
@@ -87,16 +95,22 @@ export declare type SetMemberRole = Message<"kusinta.iot.webrtc.v1.SetMemberRole
 export declare const SetMemberRoleSchema: GenMessage<SetMemberRole>;
 
 /**
- * Removes a member from the whole gateway in one step: every membership they hold, every
- * role the gateway holds for them, every pending invite they created and every join request
- * of their own. Answered with ManagementAck. Their open sessions end, and the api-server drops
- * them from the gateway. Join requests made through their invites end where those were
- * invites a resident made, as when a residency ends, and stay otherwise.
+ * Removes a member from the gateway in one step: every membership they hold, every role the
+ * gateway holds for them, every pending invite they created and every join request of their
+ * own. Answered with ManagementAck. Their open sessions end, and the api-server drops them
+ * from the gateway. Join requests made through their invites end where those were invites
+ * a resident made, as when a residency ends, and stay otherwise.
+ *
+ * What a caller is not told of under the id given stays: by a user id, a caller who does not
+ * live in a home they hold leaves that residency in place, and ends only the rest; the user
+ * then stays a member, a resident of it. By a residency id, it ends that residency alone, as
+ * RemoveUserFromSpace would, with the invites the holder made as its resident.
  *
  * A caller holding ROLE_GATEWAY_ADMIN may remove anyone but the registering administrator
  * ("registering_admin"). A caller holding ROLE_PROPERTY_OWNER, and not ROLE_GATEWAY_ADMIN,
  * may remove only a member who holds neither ROLE_PROPERTY_OWNER nor ROLE_GATEWAY_ADMIN;
- * anyone else, the registering administrator included, is refused NOT_ENTITLED.
+ * anyone else, the registering administrator included, is refused NOT_ENTITLED. A residency
+ * id is never refused for its holder's roles, since it tells none.
  *
  * @generated from message kusinta.iot.webrtc.v1.RemoveFromGateway
  */
@@ -116,8 +130,9 @@ export declare const RemoveFromGatewaySchema: GenMessage<RemoveFromGateway>;
 /**
  * Sets, moves or clears when a technician's access ends. Answered with ManagementAck. A
  * caller holding ROLE_GATEWAY_ADMIN or ROLE_PROPERTY_OWNER may. Only for a member holding
- * ROLE_TECHNICIAN and no other role but ROLE_RESIDENT ("not_a_technician" otherwise): an end
- * date never reaches a property owner or an administrator.
+ * ROLE_TECHNICIAN and no other role but ROLE_RESIDENT ("not_a_technician" otherwise, and for a
+ * residency id, which names no technician): an end date never reaches a property owner or
+ * an administrator.
  *
  * access_until is the instant the access ends; a time not after now is INVALID_REQUEST. The
  * app chooses it, typically the end of a chosen day where the building is. Within a quarter
@@ -221,12 +236,15 @@ export declare type GatewayMembers = Message<"kusinta.iot.webrtc.v1.GatewayMembe
 export declare const GatewayMembersSchema: GenMessage<GatewayMembers>;
 
 /**
- * One member, as an administrator or a property owner sees them.
+ * One member, as an administrator or a property owner sees them: a user, or a residency
+ * (ListGatewayMembers).
  *
  * @generated from message kusinta.iot.webrtc.v1.MemberDetail
  */
 export declare type MemberDetail = Message<"kusinta.iot.webrtc.v1.MemberDetail"> & {
   /**
+   * The user's id, or on a residency's entry its residency id.
+   *
    * @generated from field: kusinta.iot.identity.v1.UserId user_id = 1;
    */
   userId?: UserId | undefined;
@@ -235,8 +253,8 @@ export declare type MemberDetail = Message<"kusinta.iot.webrtc.v1.MemberDetail">
    * The name they gave their account, as the gateway last learnt it: from AppTokenClaims.name
    * when they connect, or from signaling.v1.RedeemInvite.display_name when they redeem with
    * none learnt yet. Self-chosen, so the app shows it as such. Given only for a member who is
-   * staff (access.v1.Role, STAFF), and on the caller's own entry; empty for every other
-   * resident, and when none is learnt. The gateway keeps it only while they are a member,
+   * staff (access.v1.Role, STAFF), and on the caller's own entry; empty for anyone else, on
+   * every residency's entry, and when none is learnt. The gateway keeps it only while they are a member,
    * and drops it when they stop being one.
    *
    * @generated from field: string name = 2;
@@ -245,15 +263,17 @@ export declare type MemberDetail = Message<"kusinta.iot.webrtc.v1.MemberDetail">
 
   /**
    * Every role they hold here, the registering administrator's ROLE_GATEWAY_ADMIN included,
-   * each once.
+   * each once — save that ROLE_RESIDENT is left out of every entry but the caller's own,
+   * since it would say they live in the building. None on a residency's entry.
    *
    * @generated from field: repeated kusinta.iot.access.v1.Role roles = 3;
    */
   roles: Role[];
 
   /**
-   * Every space they are filed on, save that a staff member's RESIDENT memberships are left
-   * out of every entry but the caller's own. A member with none left is still listed.
+   * Every space they are filed on but where they live, which is listed under each
+   * residency's id; on the caller's own entry, every one. On a residency's entry, that
+   * residency alone.
    *
    * @generated from field: repeated kusinta.iot.webrtc.v1.MemberSpace memberships = 4;
    */
@@ -277,8 +297,8 @@ export declare type MemberDetail = Message<"kusinta.iot.webrtc.v1.MemberDetail">
 
   /**
    * Their verified email address, as AppTokenClaims.email last gave it, so that staff who
-   * gave the same name can be told apart. Given only for a member who is staff; empty for a
-   * resident, and when none is learnt. The gateway keeps it only while they hold a staff
+   * gave the same name can be told apart. Given only for a member who is staff; empty for
+   * anyone else, on every residency's entry, and when none is learnt. The gateway keeps it only while they hold a staff
    * role.
    *
    * @generated from field: string email = 7;