@placeos/ts-client 4.5.0 → 4.7.0

package/src/systems/interfaces.ts

@@ -14,18 +14,78 @@ export interface PlaceModuleFunction {
 
 /** Allowable query parameters for systems index endpoint */
 export interface PlaceSystemsQueryOptions extends PlaceResourceQueryOptions {
-    /** Comma seperated list of email addresses to filter on */
-    in?: string;
+    /** Return only bookable or non-bookable rooms (returns both when not specified) */
+    bookable?: boolean;
+    /** Return only rooms with capacity equal or greater than provided */
+    capacity?: number;
+    /** Return only systems whose resource address matches one of the emails provided */
+    email?: string;
+    /** Comma separated list of features. Return only rooms with all requested features */
+    features?: string;
+    /** Return only systems which have this module ID */
+    module_id?: string;
+    /** Return systems using this trigger ID */
+    trigger_id?: string;
     /** Zone ID to filter the returned values on */
     zone_id?: string;
-    /** Driver ID to filter the returned values on */
-    module_id?: string;
+    /** Return systems which are public */
+    public?: boolean;
     /** Only return systems that have signage capabilities */
     signage?: boolean;
 }
 
+/** Allowable query parameters for systems with_emails endpoint */
+export interface PlaceSystemsWithEmailsOptions {
+    /** Comma separated list of email addresses (required) */
+    in: string;
+}
+
 /** Allowable query parameters for systems show endpoint */
 export interface PlaceSystemShowOptions {
-    /** Whether to return zone and module data for the system */
+    /** Return the system with zone, module, and driver information collected */
+    complete?: boolean;
+}
+
+/** Allowable query parameters for systems update endpoint */
+export interface PlaceSystemUpdateOptions {
+    /** Version number to prevent overwriting newer config (required for PUT/PATCH) */
+    version: number;
+}
+
+/** Allowable query parameters for system start/stop endpoints */
+export interface PlaceSystemStartStopOptions {
+    /** Start/stop modules that only occur in the selected system */
+    single_occurrence?: boolean;
+}
+
+/** Allowable query parameters for system triggers index endpoint */
+export interface PlaceSystemTriggersQueryOptions extends PlaceResourceQueryOptions {
+    /** Provide the control system details */
+    complete?: boolean;
+    /** Only return triggers marked as important */
+    important?: boolean;
+    /** Only return triggers that have recently been triggered */
+    triggered?: boolean;
+    /** Filter by a particular trigger type */
+    trigger_id?: string;
+    /** Return triggers updated before the time specified (unix epoch) */
+    as_of?: number;
+}
+
+/** Allowable query parameters for systems control endpoint */
+export interface PlaceSystemControlOptions {
+    /** Fixed device identifier */
+    fixed_device?: boolean;
+}
+
+/** Allowable query parameters for system metadata endpoint */
+export interface PlaceSystemMetadataOptions {
+    /** Name of the metadata key */
+    name?: string;
+}
+
+/** Allowable query parameters for system trigger show endpoint */
+export interface PlaceSystemTriggerShowOptions {
+    /** Return the full trigger details */
     complete?: boolean;
 }

package/src/triggers/functions.ts

@@ -7,8 +7,10 @@ import {
     task,
     update,
 } from '../resources/functions';
-import { PlaceResourceQueryOptions } from '../resources/interface';
-import { HashMap } from '../utilities/types';
+import {
+    PlaceTriggerQueryOptions,
+    PlaceTriggerShowOptions,
+} from './interfaces';
 import { PlaceTrigger } from './trigger';
 
 /**
@@ -25,7 +27,7 @@ function process(item: Partial<PlaceTrigger>) {
  * Query the available triggers
  * @param query_params Query parameters to add the to request URL
  */
-export function queryTriggers(query_params: PlaceResourceQueryOptions = {}) {
+export function queryTriggers(query_params: PlaceTriggerQueryOptions = {}) {
     return query({ query_params, fn: process, path: PATH });
 }
 
@@ -36,7 +38,7 @@ export function queryTriggers(query_params: PlaceResourceQueryOptions = {}) {
  */
 export function showTrigger(
     id: string,
-    query_params: PlaceResourceQueryOptions = {},
+    query_params: PlaceTriggerShowOptions = {},
 ) {
     return show({ id, query_params, fn: process, path: PATH });
 }
@@ -73,12 +75,11 @@ export function addTrigger(form_data: Partial<PlaceTrigger>) {
 }
 
 /**
- * Remove an trigger from the database
+ * Remove a trigger from the database
  * @param id ID of the trigger
- * @param query_params Query parameters to add the to request URL
  */
-export function removeTrigger(id: string, query_params: HashMap = {}) {
-    return remove({ id, query_params, path: PATH });
+export function removeTrigger(id: string) {
+    return remove({ id, query_params: {}, path: PATH });
 }
 
 /**

package/src/triggers/interfaces.ts

@@ -1,5 +1,15 @@
+import { PlaceResourceQueryOptions } from '../resources/interface';
 import { HashMap } from '../utilities/types';
 
+/** Mapping of available query parameters for the triggers index endpoint */
+export interface PlaceTriggerQueryOptions extends PlaceResourceQueryOptions {}
+
+/** Mapping of available query parameters for the triggers show endpoint */
+export interface PlaceTriggerShowOptions {
+    /** Return the instances associated with this trigger */
+    instances?: boolean;
+}
+
 export interface TriggerActions {
     /** List of functions to execute when the trigger is activated */
     functions: TriggerFunction[];

package/src/users/functions.ts

@@ -1,6 +1,18 @@
-import { create, query, remove, show, update } from '../resources/functions';
+import { Observable } from 'rxjs';
+import { map } from 'rxjs/operators';
+import { apiEndpoint } from '../auth/functions';
+import { del, get, post } from '../http/functions';
+import { create, query, remove, show, task, update } from '../resources/functions';
+import { toQueryString } from '../utilities/api';
 import { HashMap } from '../utilities/types';
-import { PlaceUserQueryOptions } from './interfaces';
+import {
+    PlaceUserDeleteOptions,
+    PlaceUserGroupsOptions,
+    PlaceUserMetadataOptions,
+    PlaceUserMetadataSearchOptions,
+    PlaceUserQueryOptions,
+    PlaceUserShowOptions,
+} from './interfaces';
 import { PlaceUser } from './user';
 
 /**
@@ -22,11 +34,11 @@ export function queryUsers(query_params: PlaceUserQueryOptions = {}) {
 }
 
 /**
- * Get the data for a trigger
- * @param id ID of the trigger to retrieve
+ * Get the data for a user
+ * @param id ID of the user to retrieve
  * @param query_params Query parameters to add the to request URL
  */
-export function showUser(id: string, query_params: PlaceUserQueryOptions = {}) {
+export function showUser(id: string, query_params: PlaceUserShowOptions = {}) {
     return show({ id, query_params, fn: process, path: PATH });
 }
 
@@ -34,7 +46,7 @@ export function showUser(id: string, query_params: PlaceUserQueryOptions = {}) {
  * Get the data for the currently logged in user
  * @param query_params Query parameters to add the to request URL
  */
-export function currentUser(query_params: PlaceUserQueryOptions = {}) {
+export function currentUser(query_params: PlaceUserShowOptions = {}) {
     return show({ id: 'current', query_params, fn: process, path: PATH });
 }
 
@@ -70,10 +82,93 @@ export function addUser(form_data: Partial<PlaceUser>) {
 }
 
 /**
- * Remove an trigger from the database
- * @param id ID of the trigger
+ * Remove a user from the database
+ * @param id ID of the user
  * @param query_params Query parameters to add the to request URL
  */
-export function removeUser(id: string, query_params: HashMap = {}) {
+export function removeUser(id: string, query_params: PlaceUserDeleteOptions = {}) {
     return remove({ id, query_params, path: PATH });
 }
+
+/**
+ * Get the groups that users are in
+ * @param query_params Query parameters including email addresses
+ */
+export function queryUserGroups(
+    query_params: PlaceUserGroupsOptions,
+): Observable<HashMap<string[]>> {
+    const q = toQueryString(query_params);
+    const url = `${apiEndpoint()}${PATH}/groups${q ? '?' + q : ''}`;
+    return get(url).pipe(map((resp: HashMap) => resp as HashMap<string[]>));
+}
+
+/**
+ * Search user metadata with provided JSON Path query
+ * @param query_params Query parameters including filter
+ */
+export function searchUserMetadata(
+    query_params: PlaceUserMetadataSearchOptions,
+): Observable<HashMap[]> {
+    const q = toQueryString(query_params);
+    const url = `${apiEndpoint()}${PATH}/metadata/search${q ? '?' + q : ''}`;
+    return get(url).pipe(map((resp: HashMap) => resp as HashMap[]));
+}
+
+/**
+ * Obtain a token to the current user's SSO resources
+ */
+export function currentUserResourceToken(): Observable<{ token: string }> {
+    const url = `${apiEndpoint()}${PATH}/resource_token`;
+    return post(url, {}).pipe(map((resp: HashMap) => resp as { token: string }));
+}
+
+/**
+ * Get a user's metadata
+ * @param id User ID
+ * @param query_params Query parameters to add to the request
+ */
+export function userMetadata(
+    id: string,
+    query_params: PlaceUserMetadataOptions = {},
+): Observable<HashMap> {
+    return task({
+        id,
+        task_name: 'metadata',
+        form_data: query_params,
+        method: 'get',
+        path: PATH,
+    });
+}
+
+/**
+ * Remove the saved resource token of a user
+ * @param id User ID
+ */
+export function removeUserResourceToken(id: string): Observable<void> {
+    const url = `${apiEndpoint()}${PATH}/${encodeURIComponent(id)}/resource_token`;
+    return del(url, { response_type: 'void' });
+}
+
+/**
+ * Obtain a token to the specified user's SSO resources
+ * @param id User ID
+ */
+export function userResourceToken(id: string): Observable<{ token: string }> {
+    const url = `${apiEndpoint()}${PATH}/${encodeURIComponent(id)}/resource_token`;
+    return post(url, {}).pipe(map((resp: HashMap) => resp as { token: string }));
+}
+
+/**
+ * Undelete a user
+ * @param id User ID
+ */
+export function reviveUser(id: string): Observable<PlaceUser> {
+    return task({
+        id,
+        task_name: 'revive',
+        form_data: {},
+        method: 'post',
+        callback: (item: Partial<PlaceUser>) => process(item),
+        path: PATH,
+    });
+}

package/src/users/interfaces.ts

@@ -1,7 +1,45 @@
 import { PlaceResourceQueryOptions } from '../resources/interface';
 
-/** Mapping of available query paramters for the users index */
+/** Mapping of available query parameters for the users index endpoint */
 export interface PlaceUserQueryOptions extends PlaceResourceQueryOptions {
-    /** Return only users on the given domain */
+    /** Include soft deleted users in the results */
+    include_deleted?: boolean;
+    /** Include user metadata in the response */
+    include_metadata?: boolean;
+    /** Admin users can view other domains (ignored for other users) */
     authority_id?: string;
 }
+
+/** Mapping of available query parameters for the users show endpoint */
+export interface PlaceUserShowOptions {
+    /** Include user metadata in the response */
+    include_metadata?: boolean;
+}
+
+/** Mapping of available query parameters for the users delete endpoint */
+export interface PlaceUserDeleteOptions {
+    /** Force permanent removal of user */
+    force_removal?: boolean;
+}
+
+/** Mapping of available query parameters for the users groups endpoint */
+export interface PlaceUserGroupsOptions {
+    /** Comma-separated list of email addresses */
+    emails: string;
+}
+
+/** Mapping of available query parameters for the users metadata search endpoint */
+export interface PlaceUserMetadataSearchOptions {
+    /** JSON Path query filter */
+    filter: string;
+    /** Maximum number of results to return */
+    limit?: number;
+    /** Offset for pagination */
+    offset?: number;
+}
+
+/** Mapping of available query parameters for the user metadata endpoint */
+export interface PlaceUserMetadataOptions {
+    /** Name of the metadata key */
+    name?: string;
+}

package/src/webrtc/functions.ts

@@ -0,0 +1,120 @@
+import { Observable } from 'rxjs';
+import { map } from 'rxjs/operators';
+import { apiEndpoint } from '../auth';
+import { get, post } from '../http/functions';
+import { toQueryString } from '../utilities/api';
+import { HashMap } from '../utilities/types';
+import {
+    PlaceGuestParticipant,
+    PlaceKickReason,
+    PlaceWebrtcMember,
+    PlaceWebrtcRoomDetails,
+    PlaceWebrtcRoomsQueryOptions,
+} from './interfaces';
+
+/**
+ * @private
+ */
+const PATH = 'webrtc';
+
+/**
+ * Query the list of public chat rooms for the current domain
+ * @param query_params Query parameters to add to the request URL
+ */
+export function queryWebrtcRooms(
+    query_params: PlaceWebrtcRoomsQueryOptions = {},
+): Observable<PlaceWebrtcRoomDetails[]> {
+    const query = toQueryString(query_params);
+    const url = `${apiEndpoint()}${PATH}/rooms${query ? '?' + query : ''}`;
+    return get(url).pipe(map((resp: HashMap) => resp as PlaceWebrtcRoomDetails[]));
+}
+
+/**
+ * Get the details of a public chat room
+ * @param system_id Either a system ID or a unique permalink
+ */
+export function showWebrtcRoom(
+    system_id: string,
+): Observable<PlaceWebrtcRoomDetails> {
+    const url = `${apiEndpoint()}${PATH}/room/${encodeURIComponent(system_id)}`;
+    return get(url).pipe(map((resp: HashMap) => resp as PlaceWebrtcRoomDetails));
+}
+
+/**
+ * Get a list of connected users in a chat session
+ * @param session_id ID of the chat session
+ */
+export function webrtcSessionMembers(
+    session_id: string,
+): Observable<PlaceWebrtcMember[]> {
+    const url = `${apiEndpoint()}${PATH}/members/${encodeURIComponent(session_id)}`;
+    return get(url).pipe(map((resp: HashMap) => resp as PlaceWebrtcMember[]));
+}
+
+/**
+ * Request guest access to an anonymous chat room.
+ * The guest participant details will be forwarded to any listening systems.
+ * Additional fields provided as part of the guest post will also be forwarded.
+ * @param system_id Either a system ID or a unique permalink
+ * @param participant Guest participant details
+ */
+export function webrtcGuestEntry(
+    system_id: string,
+    participant: PlaceGuestParticipant,
+): Observable<void> {
+    const url = `${apiEndpoint()}${PATH}/guest_entry/${encodeURIComponent(system_id)}`;
+    return post(url, participant).pipe(map(() => undefined));
+}
+
+/**
+ * End a guest call gracefully.
+ * This will remove the authentication token and close any open websockets.
+ */
+export function webrtcGuestExit(): Observable<void> {
+    const url = `${apiEndpoint()}${PATH}/guest/exit`;
+    return post(url, {}).pipe(map(() => undefined));
+}
+
+/**
+ * Kick a user from a chat session.
+ * Similar to guest exit without the token expiration.
+ * Other members of the call will stop communicating with them.
+ * @param user_id ID of the user to kick
+ * @param session_id ID of the chat session
+ * @param reason Reason for kicking the user
+ */
+export function webrtcKickUser(
+    user_id: string,
+    session_id: string,
+    reason: PlaceKickReason,
+): Observable<void> {
+    const url = `${apiEndpoint()}${PATH}/kick/${encodeURIComponent(user_id)}/${encodeURIComponent(session_id)}`;
+    return post(url, reason).pipe(map(() => undefined));
+}
+
+/**
+ * Transfer a user from one chat to another.
+ * For authorized users to move people from one chat to another.
+ * @param user_id ID of the user to transfer
+ * @param session_id ID of the current chat session
+ * @param connection_details Optional custom connection details for the transfer
+ */
+export function webrtcTransferUser(
+    user_id: string,
+    session_id: string,
+    connection_details?: Record<string, unknown>,
+): Observable<void> {
+    const url = `${apiEndpoint()}${PATH}/transfer/${encodeURIComponent(user_id)}/${encodeURIComponent(session_id)}`;
+    return post(url, connection_details || {}).pipe(map(() => undefined));
+}
+
+/**
+ * Get the WebRTC signaller websocket URL.
+ * This is the endpoint for managing call participants.
+ */
+export function webrtcSignallerUrl(): string {
+    const endpoint = apiEndpoint();
+    const wsProtocol = endpoint.startsWith('https') ? 'wss:' : 'ws:';
+    const httpProtocol = endpoint.startsWith('https') ? 'https:' : 'http:';
+    return endpoint.replace(httpProtocol, wsProtocol) + `${PATH}/signaller`;
+}

package/src/webrtc/interfaces.ts

@@ -0,0 +1,77 @@
+import { PlaceResourceQueryOptions } from '../resources/interface';
+
+/** Mapping of available query parameters for the webrtc rooms index endpoint */
+export interface PlaceWebrtcRoomsQueryOptions extends PlaceResourceQueryOptions {}
+
+/** Guest participant details for joining an anonymous chat room */
+export interface PlaceGuestParticipant {
+    /** Captcha token for verification (required) */
+    captcha: string;
+    /** Display name for the guest (required) */
+    name: string;
+    /** User ID for the guest (required) */
+    user_id: string;
+    /** Session ID for the chat (required) */
+    session_id: string;
+    /** Email address of the guest */
+    email?: string;
+    /** Phone number of the guest */
+    phone?: string;
+    /** Type of participant */
+    type?: string;
+    /** User ID of the person to chat with directly */
+    chat_to_user_id?: string;
+}
+
+/** Reason for kicking a user from a chat */
+export interface PlaceKickReason {
+    /** Reason for ending the call (required) */
+    reason: string;
+}
+
+/** Details of a WebRTC public chat room */
+export interface PlaceWebrtcRoomDetails {
+    /** System information for the room */
+    system?: {
+        created_at?: number;
+        updated_at?: number;
+        name?: string;
+        description?: string;
+        features?: string[];
+        email?: string;
+        bookable?: boolean;
+        public?: boolean;
+        display_name?: string;
+        code?: string;
+        type?: string;
+        capacity?: number;
+        map_id?: string;
+        approval?: boolean;
+        images?: string[];
+        timezone?: Record<string, unknown>;
+        support_url?: string;
+        timetable_url?: string;
+        camera_snapshot_url?: string;
+        camera_url?: string;
+        room_booking_url?: string;
+        version?: number;
+        installed_ui_devices?: number;
+        zones?: string[];
+        modules?: string[];
+        orientation?: 'unspecified' | 'landscape' | 'portrait' | 'square';
+        playlists?: string[];
+        signage?: boolean;
+    };
+}
+
+/** Member details in a WebRTC chat session */
+export interface PlaceWebrtcMember {
+    /** User ID of the member */
+    user_id?: string;
+    /** Display name of the member */
+    name?: string;
+    /** Email of the member */
+    email?: string;
+    /** Whether the member is a guest */
+    is_guest?: boolean;
+}

package/src/zones/functions.ts

@@ -7,9 +7,10 @@ import {
     task,
     update,
 } from '../resources/functions';
+import { PlaceResourceQueryOptions } from '../resources/interface';
 import { PlaceTrigger } from '../triggers/trigger';
 import { HashMap } from '../utilities/types';
-import { PlaceZoneQueryOptions, PlaceZoneShowOptions } from './interfaces';
+import { PlaceZoneMetadataQueryOptions, PlaceZoneQueryOptions, PlaceZoneShowOptions } from './interfaces';
 import { PlaceZone } from './zone';
 
 /**
@@ -84,12 +85,11 @@ export function addZone(form_data: Partial<PlaceZone>) {
 }
 
 /**
- * Remove an application from the database
- * @param id ID of the application
- * @param query_params Query parameters to add the to request URL
+ * Remove a zone from the database
+ * @param id ID of the zone
  */
-export function removeZone(id: string, query_params: HashMap = {}) {
-    return remove({ id, query_params, path: PATH });
+export function removeZone(id: string) {
+    return remove({ id, query_params: {}, path: PATH });
 }
 
 /**
@@ -97,7 +97,10 @@ export function removeZone(id: string, query_params: HashMap = {}) {
  * @param id ID of the zone
  * @param query_params Query parameters to add the to request URL
  */
-export function listZoneTriggers(id: string, query_params: HashMap = {}) {
+export function listZoneTriggers(
+    id: string,
+    query_params: PlaceResourceQueryOptions = {},
+) {
     return query({
         query_params,
         fn: (i: Partial<PlaceTrigger>) => new PlaceTrigger(i),
@@ -129,3 +132,21 @@ export function executeOnZone(
         path: PATH,
     });
 }
+
+/**
+ * Get metadata associated with the selected zone
+ * @param id Zone ID
+ * @param query_params Query parameters to add to the request
+ */
+export function zoneMetadata(
+    id: string,
+    query_params: PlaceZoneMetadataQueryOptions = {},
+): Observable<HashMap> {
+    return task({
+        id,
+        task_name: 'metadata',
+        form_data: query_params,
+        method: 'get',
+        path: PATH,
+    });
+}

package/src/zones/interfaces.ts

@@ -1,13 +1,13 @@
 import { PlaceResourceQueryOptions } from '../resources/interface';
 
-/** Mapping of available query paramters for the zones index endpoint */
+/** Mapping of available query parameters for the zones index endpoint */
 export interface PlaceZoneQueryOptions extends PlaceResourceQueryOptions {
-    /** List of space seperated tags to filter the results */
+    /** ID of the parent zone to filter the results (supports comma-separated list) */
+    parent_id?: string;
+    /** List of space separated tags to filter the results */
     tags?: string;
     /** ID of the system to filter the results */
     control_system_id?: string;
-    /** ID of the parent zone to filter the results */
-    parent_id?: string;
 }
 
 /** Mapping of available query parameters for the zones show endpoint */
@@ -20,3 +20,9 @@ export interface PlaceZoneShowOptions {
      */
     data?: string;
 }
+
+/** Mapping of available query parameters for the zone metadata endpoint */
+export interface PlaceZoneMetadataQueryOptions {
+    /** The name of the metadata key to retrieve */
+    name?: string;
+}