feat(organisations): multi-tenancy resources and ownership fields

src/api.ts

@@ -111,6 +111,45 @@ export {
     updateDomain,
 } from './domains/functions';
 
+export { PlaceGrant } from './grants/grant';
+export {
+    addGrant,
+    queryGrants,
+    removeGrant,
+    showGrant,
+} from './grants/functions';
+export type {
+    PlaceGrantCreatePayload,
+    PlaceGrantQueryOptions,
+} from './grants/interfaces';
+
+export { PlaceOrganisation } from './organisations/organisation';
+export {
+    addOrganisation,
+    claimZonesForOrganisation,
+    currentReach,
+    queryOrganisations,
+    removeOrganisation,
+    showOrganisation,
+    updateOrganisation,
+} from './organisations/functions';
+export type {
+    PlaceOrganisationClaimResult,
+    PlaceOrganisationOwnerOptions,
+    PlaceOrganisationQueryOptions,
+    PlaceOrganisationWriteOptions,
+    PlaceReach,
+} from './organisations/interfaces';
+
+export { PlacePartner } from './partners/partner';
+export {
+    addPartner,
+    queryPartners,
+    removePartner,
+    showPartner,
+    updatePartner,
+} from './partners/functions';
+
 export { PlaceDriver } from './drivers/driver';
 export { PlaceDriverRole } from './drivers/enums';
 export {

src/broker/broker.ts

@@ -7,6 +7,8 @@ export enum AuthType {
 }
 
 export class PlaceMQTTBroker extends PlaceResource {
+    /** ID of the organisation that owns this row; empty when unowned */
+    public readonly organisation_id: string;
     /** Unique identifier for the Broker */
     public readonly id: string;
     /** Name of the Broker */
@@ -34,6 +36,7 @@ export class PlaceMQTTBroker extends PlaceResource {
 
     constructor(data: Partial<PlaceMQTTBroker> = {}) {
         super();
+        this.organisation_id = data.organisation_id || '';
         this.id = data.id || '';
         this.name = data.name || '';
         this.auth_type = data.auth_type || AuthType.UserPassword;

src/domains/domain.ts

@@ -2,6 +2,8 @@ import { PlaceResource } from '../resources/resource';
 import { HashMap } from '../utilities/types';
 
 export class PlaceDomain extends PlaceResource {
+    /** ID of the organisation that owns this row; empty when unowned */
+    public readonly organisation_id: string;
     /** Domain name */
     public readonly domain: string;
     /** Login URL for the domain */
@@ -19,6 +21,7 @@ export class PlaceDomain extends PlaceResource {
 
     constructor(raw_data: Partial<PlaceDomain> = {}) {
         super(raw_data);
+        this.organisation_id = raw_data.organisation_id || '';
         this.description = raw_data.description || '';
         this.domain = raw_data.domain || '';
         this.login_url = raw_data.login_url || '';

src/domains/functions.ts

@@ -1,6 +1,7 @@
 import { apiEndpoint } from '../auth/functions';
 import { get } from '../http/functions';
 import { create, query, remove, show, update } from '../resources/functions';
+import { PlaceOrganisationOwnerOptions } from '../organisations/interfaces';
 import { PlaceResourceQueryOptions } from '../resources/interface';
 import { PlaceDomain } from './domain';
 
@@ -18,7 +19,9 @@ function process(item: Partial<PlaceDomain>) {
  * Query the available domains
  * @param query_params Query parameters to add the to request URL
  */
-export function queryDomains(query_params: PlaceResourceQueryOptions = {}) {
+export function queryDomains(
+    query_params: PlaceResourceQueryOptions & PlaceOrganisationOwnerOptions = {},
+) {
     return query({ query_params, fn: process, path: PATH });
 }
 
@@ -36,16 +39,18 @@ export function showDomain(id: string) {
  * @param form_data New values for the domain
  * @param query_params Query parameters to add the to request URL
  * @param method HTTP verb to use on request. Defaults to `patch`
+ * @param options Organisation to move the domain to (cluster admins only)
  */
 export function updateDomain(
     id: string,
     form_data: Partial<PlaceDomain>,
     method: 'put' | 'patch' = 'patch',
+    options: PlaceOrganisationOwnerOptions = {},
 ) {
     return update({
         id,
         form_data,
-        query_params: {},
+        query_params: options,
         method,
         fn: process,
         path: PATH,
@@ -55,10 +60,13 @@ export function updateDomain(
 /**
  * Add a new domain to the database
  * @param form_data Domain data
- * @param query_params Query parameters to add the to request URL
+ * @param options Organisation that owns the new domain (cluster admins only; defaults to the caller's)
  */
-export function addDomain(form_data: Partial<PlaceDomain>) {
-    return create({ form_data, query_params: {}, fn: process, path: PATH });
+export function addDomain(
+    form_data: Partial<PlaceDomain>,
+    options: PlaceOrganisationOwnerOptions = {},
+) {
+    return create({ form_data, query_params: options, fn: process, path: PATH });
 }
 
 /**

src/edge/edge.ts

@@ -2,6 +2,8 @@ import { PlaceResource } from '../resources/resource';
 import { HashMap } from '../utilities/types';
 
 export class PlaceEdge extends PlaceResource {
+    /** ID of the organisation that owns this row; empty when unowned */
+    public readonly organisation_id: string;
     public readonly description: string;
     public readonly secret: string;
     public readonly x_api_key: string;
@@ -10,6 +12,7 @@ export class PlaceEdge extends PlaceResource {
 
     constructor(raw_data: Partial<PlaceEdge> = {}) {
         super(raw_data);
+        this.organisation_id = raw_data.organisation_id || '';
         this.description = raw_data.description || '';
         this.secret = raw_data.secret || '';
         this.x_api_key = raw_data.x_api_key || '';

src/grants/functions.ts

@@ -0,0 +1,45 @@
+import { create, query, remove, show } from '../resources/functions';
+import { PlaceGrant } from './grant';
+import { PlaceGrantCreatePayload, PlaceGrantQueryOptions } from './interfaces';
+
+/**
+ * @private
+ */
+const PATH = 'grants';
+
+/** Convert raw server data to a grant object */
+function process(item: Partial<PlaceGrant>) {
+    return new PlaceGrant(item);
+}
+
+/**
+ * Query grants on a scope or held by a user
+ * @param query_params Query parameters to add the to request URL
+ */
+export function queryGrants(query_params: PlaceGrantQueryOptions = {}) {
+    return query({ query_params, fn: process, path: PATH });
+}
+
+/**
+ * Get the data for a grant
+ * @param id ID of the grant to retrieve
+ */
+export function showGrant(id: string) {
+    return show({ id, query_params: {}, fn: process, path: PATH });
+}
+
+/**
+ * Issue a grant
+ * @param form_data Grant data
+ */
+export function addGrant(form_data: PlaceGrantCreatePayload) {
+    return create({ form_data, query_params: {}, fn: process, path: PATH });
+}
+
+/**
+ * Revoke a grant
+ * @param id ID of the grant
+ */
+export function removeGrant(id: string) {
+    return remove({ id, query_params: {}, path: PATH });
+}

src/grants/grant.ts

@@ -0,0 +1,27 @@
+import { PlaceResource } from '../resources/resource';
+
+/** Explicit, revocable, optionally time-boxed reach for a user into a partner, organisation or domain */
+export class PlaceGrant extends PlaceResource {
+    /** ID of the user holding the grant */
+    public readonly user_id: string;
+    /** `partner`, `organisation` or `authority` */
+    public readonly scope_type: 'partner' | 'organisation' | 'authority';
+    /** ID of the partner, organisation or domain */
+    public readonly scope_id: string;
+    /** Permission bitmask (same flags as group memberships) */
+    public readonly permissions: number;
+    /** When the grant stops applying; empty for a standing grant */
+    public readonly expires_at: string;
+    /** ID of the user who issued the grant */
+    public readonly granted_by: string;
+
+    constructor(raw_data: Partial<PlaceGrant> = {}) {
+        super(raw_data);
+        this.user_id = raw_data.user_id || '';
+        this.scope_type = raw_data.scope_type || 'organisation';
+        this.scope_id = raw_data.scope_id || '';
+        this.permissions = raw_data.permissions || 0;
+        this.expires_at = raw_data.expires_at || '';
+        this.granted_by = raw_data.granted_by || '';
+    }
+}

src/grants/interfaces.ts

@@ -0,0 +1,22 @@
+import { PlaceResourceQueryOptions } from '../resources/interface';
+
+/** Mapping of available query parameters for the grants index endpoint */
+export interface PlaceGrantQueryOptions extends PlaceResourceQueryOptions {
+    /** `partner`, `organisation` or `authority` */
+    scope_type?: 'partner' | 'organisation' | 'authority';
+    /** ID of the partner, organisation or domain */
+    scope_id?: string;
+    /** Grants held by this user */
+    user_id?: string;
+}
+
+/** Body for creating a grant */
+export interface PlaceGrantCreatePayload {
+    user_id: string;
+    scope_type: 'partner' | 'organisation' | 'authority';
+    scope_id: string;
+    /** Permission bitmask; defaults to Read */
+    permissions?: number;
+    /** ISO 8601 time the grant stops applying; omit for a standing grant */
+    expires_at?: string;
+}

src/modules/functions.ts

@@ -1,3 +1,4 @@
+import { PlaceOrganisationOwnerOptions } from '../organisations/interfaces';
 import {
     create,
     query,
@@ -72,8 +73,11 @@ export function updateModule(
  * @param form_data Module data
  * @param query_params Query parameters to add the to request URL
  */
-export function addModule(form_data: Partial<PlaceModule>) {
-    return create({ form_data, query_params: {}, fn: process, path: PATH });
+export function addModule(
+    form_data: Partial<PlaceModule>,
+    options: PlaceOrganisationOwnerOptions = {},
+) {
+    return create({ form_data, query_params: options, fn: process, path: PATH });
 }
 
 /**

src/modules/interfaces.ts

@@ -2,6 +2,8 @@ import { PlaceResourceQueryOptions } from '../resources/interface';
 
 /** Mapping of available query parameters for the modules index endpoint */
 export interface PlaceModuleQueryOptions extends PlaceResourceQueryOptions {
+    /** Only modules owned by this organisation (must be within reach) */
+    organisation_id?: string;
     /** Only return modules updated before this time (unix epoch) */
     as_of?: number;
     /** Only return modules running in this system (query params are ignored if this is provided) */

src/modules/module.ts

@@ -20,6 +20,8 @@ export interface PlaceModuleComplete extends Partial<PlaceModule> {
 export type EndDebugFn = () => void;
 
 export class PlaceModule extends PlaceResource {
+    /** ID of the organisation that owns this row; empty when unowned */
+    public readonly organisation_id: string;
     /** Whether the associated hardware is connected */
     public readonly connected: boolean | undefined;
     /** Whether the module driver is running */
@@ -76,6 +78,7 @@ export class PlaceModule extends PlaceResource {
 
     constructor(raw_data: PlaceModuleComplete = {}) {
         super(raw_data);
+        this.organisation_id = raw_data.organisation_id || '';
         this.driver_id = raw_data.driver_id || raw_data.dependency_id || '';
         this.control_system_id = raw_data.control_system_id || '';
         this.edge_id = raw_data.edge_id || '';