@placeos/ts-client 4.5.0 → 4.7.0

package/src/edge/functions.ts

@@ -1,3 +1,4 @@
+import { apiEndpoint } from '../auth/functions';
 import { PlaceAuthSourceQueryOptions } from '../auth-sources/interfaces';
 import {
     create,
@@ -7,7 +8,6 @@ import {
     task,
     update,
 } from '../resources/functions';
-import { HashMap } from '../utilities/types';
 import { PlaceEdge } from './edge';
 
 /**
@@ -31,10 +31,9 @@ export function queryEdges(query_params: PlaceAuthSourceQueryOptions = {}) {
 /**
  * Get the data for an Edge
  * @param id ID of the Edge to retrieve
- * @param query_params Query parameters to add the to request URL
  */
-export function showEdge(id: string, query_params: HashMap = {}) {
-    return show({ id, query_params, fn: process, path: PATH });
+export function showEdge(id: string) {
+    return show({ id, query_params: {}, fn: process, path: PATH });
 }
 
 /**
@@ -71,23 +70,32 @@ export function addEdge(form_data: Partial<PlaceEdge>) {
 /**
  * Remove an Edge node from the database
  * @param id ID of the Edge
- * @param query_params Query parameters to add the to request URL
  */
-export function removeEdge(id: string, query_params: HashMap = {}) {
-    return remove({ id, query_params, path: PATH });
+export function removeEdge(id: string) {
+    return remove({ id, query_params: {}, path: PATH });
 }
 
 /**
  * Generate token for Edge connection
  * @param id ID of the Edge
- * @param query_params Query parameters to add the to request URL
  */
-export function retrieveEdgeToken(id: string, query_params: HashMap = {}) {
+export function retrieveEdgeToken(id: string) {
     return task<{ token: string }>({
         id,
         task_name: 'token',
-        form_data: query_params,
+        form_data: {},
         method: 'get',
         path: PATH,
     });
 }
+
+/**
+ * Get the edge control websocket URL.
+ * This is the endpoint that edge devices use to connect to the cluster.
+ */
+export function edgeControlUrl(): string {
+    const endpoint = apiEndpoint();
+    const wsProtocol = endpoint.startsWith('https') ? 'wss:' : 'ws:';
+    const httpProtocol = endpoint.startsWith('https') ? 'https:' : 'http:';
+    return endpoint.replace(httpProtocol, wsProtocol) + `${PATH}/control`;
+}

package/src/ldap-sources/functions.ts

@@ -1,6 +1,5 @@
 import { PlaceAuthSourceQueryOptions } from '../auth-sources/interfaces';
 import { create, query, remove, show, update } from '../resources/functions';
-import { HashMap } from '../utilities/types';
 import { PlaceLDAPSource } from './ldap-source';
 
 /**
@@ -26,10 +25,9 @@ export function queryLDAPSources(
 /**
  * Get the data for an LDAP source
  * @param id ID of the LDAP source to retrieve
- * @param query_params Query parameters to add the to request URL
  */
-export function showLDAPSource(id: string, query_params: HashMap = {}) {
-    return show({ id, query_params, fn: process, path: PATH });
+export function showLDAPSource(id: string) {
+    return show({ id, query_params: {}, fn: process, path: PATH });
 }
 
 /**
@@ -66,8 +64,7 @@ export function addLDAPSource(form_data: Partial<PlaceLDAPSource>) {
 /**
  * Remove an LDAP source from the database
  * @param id ID of the LDAP source
- * @param query_params Query parameters to add the to request URL
  */
-export function removeLDAPSource(id: string, query_params: HashMap = {}) {
-    return remove({ id, query_params, path: PATH });
+export function removeLDAPSource(id: string) {
+    return remove({ id, query_params: {}, path: PATH });
 }

package/src/metadata/functions.ts

@@ -1,7 +1,12 @@
 import { Observable } from 'rxjs';
 import { create, remove, show, task, update } from '../resources/functions';
 import { HashMap } from '../utilities/types';
-import { PlaceZoneMetadataOptions } from './interfaces';
+import {
+    PlaceMetadataDeleteOptions,
+    PlaceMetadataHistoryOptions,
+    PlaceMetadataOptions,
+    PlaceZoneMetadataOptions,
+} from './interfaces';
 import { PlaceMetadata } from './metadata';
 import { PlaceZoneMetadata } from './zone-metadata';
 
@@ -22,7 +27,7 @@ function process(item: Partial<PlaceMetadata>) {
  */
 export function listMetadata(
     id: string,
-    query_params: HashMap = {},
+    query_params: PlaceMetadataOptions = {},
 ): Observable<PlaceMetadata[]> {
     return show({
         id,
@@ -53,11 +58,11 @@ function flatten<T = any>(an_array: T[]): T {
 /**
  * List the metadata history for a database item
  * @param id ID of the item to retrieve metadata
- * @param form_data Data to pass to the request URL.
+ * @param query_params Query parameters to add to the request URL.
  */
 export function listMetadataHistory(
     id: string,
-    query_params: HashMap = {},
+    query_params: PlaceMetadataHistoryOptions = {},
 ): Observable<PlaceMetadata[]> {
     return task({
         id,
@@ -78,16 +83,14 @@ export function listMetadataHistory(
  * Get a metadata field for a database item
  * @param id ID of the item to retrieve metadata
  * @param name Name of the metadata field to retrieve
- * @param query_params Query parameters to add the to request URL.
  */
 export function showMetadata(
     id: string,
     name: string,
-    query_params: HashMap = {},
 ): Observable<PlaceMetadata> {
     return show({
         id,
-        query_params: { ...query_params, name },
+        query_params: { name },
         fn: (data: HashMap) => process(data[name]),
         path: PATH,
     });
@@ -120,11 +123,14 @@ export function addMetadata(form_data: Partial<PlaceMetadata>) {
 }
 
 /**
- * Remove an metadata from the database
+ * Remove metadata from the database
  * @param id ID of the item associated with the metadata
- * @param query_params Query parameters to add the to request URL
+ * @param query_params Query parameters including the metadata key name (required)
  */
-export function removeMetadata(id: string, query_params: HashMap = {}) {
+export function removeMetadata(
+    id: string,
+    query_params: PlaceMetadataDeleteOptions,
+) {
     return remove({ id, query_params, path: PATH });
 }
 

package/src/metadata/interfaces.ts

@@ -1,11 +1,27 @@
-/** Query param options for getting  metadata */
+/** Query param options for getting metadata */
 export interface PlaceMetadataOptions {
-    /** Specify key to return, i.e. catering */
+    /** The name of the metadata key to return */
     name?: string;
 }
 
+/** Query param options for deleting metadata */
+export interface PlaceMetadataDeleteOptions {
+    /** The name of the metadata key to delete (required) */
+    name: string;
+}
+
 /** Query param options for getting child metadata */
 export interface PlaceZoneMetadataOptions extends PlaceMetadataOptions {
-    /** Only return metadata from s with tags. Comma seperated string */
-    tags?: string;
+    /** Include parent metadata in the results (included by default) */
+    include_parent?: boolean;
+}
+
+/** Query param options for getting metadata history */
+export interface PlaceMetadataHistoryOptions {
+    /** The name of the metadata key */
+    name?: string;
+    /** Maximum number of results to return */
+    limit?: number;
+    /** Starting offset of the result set for pagination */
+    offset?: number;
 }

package/src/modules/functions.ts

@@ -9,7 +9,11 @@ import {
 } from '../resources/functions';
 import { PlaceSettings } from '../settings/settings';
 import { HashMap } from '../utilities/types';
-import { PlaceModulePingOptions, PlaceModuleQueryOptions } from './interfaces';
+import {
+    PlaceModulePingOptions,
+    PlaceModuleQueryOptions,
+    PlaceModuleShowOptions,
+} from './interfaces';
 import { PlaceModule } from './module';
 
 /**
@@ -35,7 +39,7 @@ export function queryModules(query_params: PlaceModuleQueryOptions = {}) {
  * @param id ID of the module to retrieve
  * @param query_params Query parameters to add the to request URL
  */
-export function showModule(id: string, query_params: HashMap = {}) {
+export function showModule(id: string, query_params: PlaceModuleShowOptions = {}) {
     return show({ id, query_params, fn: process, path: PATH });
 }
 
@@ -73,10 +77,9 @@ export function addModule(form_data: Partial<PlaceModule>) {
 /**
  * Remove a module from the database
  * @param id ID of the module
- * @param query_params Query parameters to add the to request URL
  */
-export function removeModule(id: string, query_params: HashMap = {}) {
-    return remove({ id, query_params, path: PATH });
+export function removeModule(id: string) {
+    return remove({ id, query_params: {}, path: PATH });
 }
 
 /**
@@ -100,7 +103,7 @@ export function stopModule(id: string) {
  * @param id Module ID
  */
 export function pingModule(id: string): Observable<PlaceModulePingOptions> {
-    return task({ id, task_name: 'stop', path: PATH });
+    return task({ id, task_name: 'ping', method: 'post', path: PATH });
 }
 
 /**
@@ -121,7 +124,7 @@ export function lookupModuleState(
     id: string,
     key: string,
 ): Observable<HashMap> {
-    return task({ id, task_name: `state${key}`, method: 'get', path: PATH });
+    return task({ id, task_name: `state/${key}`, method: 'get', path: PATH });
 }
 
 /**
@@ -159,3 +162,22 @@ export function moduleRuntimeError(id: string) {
         path: PATH,
     });
 }
+
+/**
+ * Execute a command on a module
+ * @param id Module ID
+ * @param method Name of the method to execute
+ * @param args Array of arguments to pass to the executed method
+ */
+export function executeOnModule(
+    id: string,
+    method: string,
+    args: any[] = [],
+): Observable<HashMap> {
+    return task({
+        id,
+        task_name: `exec/${encodeURIComponent(method)}`,
+        form_data: args,
+        path: PATH,
+    });
+}

package/src/modules/interfaces.ts

@@ -1,22 +1,25 @@
 import { PlaceResourceQueryOptions } from '../resources/interface';
 
-/** Mapping of available query paramters for the modules index */
+/** Mapping of available query parameters for the modules index endpoint */
 export interface PlaceModuleQueryOptions extends PlaceResourceQueryOptions {
-    /** Returns modules that are in the given system */
+    /** 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) */
     control_system_id?: string;
-    /** Returns modules with the given dependency */
-    driver_id?: string;
     /** Return results that connected state matches this value */
     connected?: boolean;
-    /** Return modules that are running or not stopped */
-    running?: boolean;
-    /** Returns modules that are not logic modules (i.e. they connect to a device or service) */
+    /** Only return instances of this driver */
+    driver_id?: string;
+    /** Do not return logic modules (return only modules that can exist in multiple systems) */
     no_logic?: boolean;
-    /**
-     * Returns modules that have not been updated since the
-     * value defined as seconds since UTC epoch
-     */
-    as_of?: number;
+    /** Return only running modules */
+    running?: boolean;
+}
+
+/** Mapping of available query parameters for the modules show endpoint */
+export interface PlaceModuleShowOptions {
+    /** Return the driver details along with the module */
+    complete?: boolean;
 }
 
 /** Place response from `ping` module task endpoint `/api/engine/v2/<mod_id>/ping` */

package/src/oauth-sources/functions.ts

@@ -1,6 +1,5 @@
 import { PlaceAuthSourceQueryOptions } from '../auth-sources/interfaces';
 import { create, query, remove, show, update } from '../resources/functions';
-import { HashMap } from '../utilities/types';
 import { PlaceOAuthSource } from './oauth-source';
 
 /**
@@ -26,10 +25,9 @@ export function queryOAuthSources(
 /**
  * Get the data for an OAuth source
  * @param id ID of the OAuth source to retrieve
- * @param query_params Query parameters to add the to request URL
  */
-export function showOAuthSource(id: string, query_params: HashMap = {}) {
-    return show({ id, query_params, fn: process, path: PATH });
+export function showOAuthSource(id: string) {
+    return show({ id, query_params: {}, fn: process, path: PATH });
 }
 
 /**
@@ -66,8 +64,7 @@ export function addOAuthSource(form_data: Partial<PlaceOAuthSource>) {
 /**
  * Remove an OAuth source from the database
  * @param id ID of the OAuth source
- * @param query_params Query parameters to add the to request URL
  */
-export function removeOAuthSource(id: string, query_params: HashMap = {}) {
-    return remove({ id, query_params, path: PATH });
+export function removeOAuthSource(id: string) {
+    return remove({ id, query_params: {}, path: PATH });
 }

package/src/repositories/functions.ts

@@ -8,13 +8,16 @@ import {
     task,
     update,
 } from '../resources/functions';
-import { PlaceResourceQueryOptions } from '../resources/interface';
 import { HashMap } from '../utilities/types';
 import {
     GitCommitDetails,
+    PlaceRemoteRepositoryCommitsQuery,
+    PlaceRemoteRepositoryQuery,
     PlaceRepositoryCommitQuery,
     PlaceRepositoryDetailsQuery,
+    PlaceRepositoryFoldersQuery,
     PlaceRepositoryPullQuery,
+    PlaceRepositoryQueryOptions,
 } from './interfaces';
 import { PlaceRepository } from './repository';
 
@@ -33,7 +36,7 @@ function process(item: Partial<PlaceRepository>) {
  * @param query_params Query parameters to add the to request URL
  */
 export function queryRepositories(
-    query_params: PlaceResourceQueryOptions = {},
+    query_params: PlaceRepositoryQueryOptions = {},
 ) {
     return query({ query_params, fn: process, path: PATH });
 }
@@ -41,10 +44,9 @@ export function queryRepositories(
 /**
  * Get the data for a repository
  * @param id ID of the repository to retrieve
- * @param query_params Query parameters to add the to request URL
  */
-export function showRepository(id: string, query_params: HashMap = {}) {
-    return show({ id, query_params, fn: process, path: PATH });
+export function showRepository(id: string) {
+    return show({ id, query_params: {}, fn: process, path: PATH });
 }
 
 /**
@@ -79,34 +81,30 @@ export function addRepository(form_data: Partial<PlaceRepository>) {
 }
 
 /**
- * Remove an repository from the database
+ * Remove a repository from the database
  * @param id ID of the repository
- * @param query_params Query parameters to add the to request URL
  */
-export function removeRepository(id: string, query_params: HashMap = {}) {
-    return remove({ id, query_params, path: PATH });
+export function removeRepository(id: string) {
+    return remove({ id, query_params: {}, path: PATH });
 }
 
 /**
  * Get a list of all the interfaces
- * @param query_params Addition query parameters to pass to the request
  */
-export function listInterfaceRepositories(
-    query_params: HashMap = {},
-): Observable<string[]> {
+export function listInterfaceRepositories(): Observable<string[]> {
     return show({
         id: 'interfaces',
-        query_params,
+        query_params: {},
         path: PATH,
     });
 }
 
 /**
- * Get name of the default branches for a new repository
+ * Get name of the default branch for a new repository
  * @param query_params Details about the repository
  */
 export function listRemoteRepositoryDefaultBranch(
-    query_params: RepositoryDetails,
+    query_params: PlaceRemoteRepositoryQuery,
 ): Observable<string> {
     return show({
         id: 'remote_default_branch',
@@ -115,21 +113,12 @@ export function listRemoteRepositoryDefaultBranch(
     });
 }
 
-export interface RepositoryDetails {
-    /** Git URL of the remote repository */
-    repository_url: string;
-    /** Username required to access the repository */
-    username?: string;
-    /** Password for the required user */
-    password?: string;
-}
-
 /**
  * Get a list of branches for a new repository
  * @param query_params Details about the repository
  */
 export function listRemoteRepositoryBranches(
-    query_params: RepositoryDetails,
+    query_params: PlaceRemoteRepositoryQuery,
 ): Observable<string[]> {
     return show({
         id: 'remote_branches',
@@ -138,19 +127,12 @@ export function listRemoteRepositoryBranches(
     });
 }
 
-export interface RepositoryBranchDetails extends RepositoryDetails {
-    /** Branch to grab details for. Defaults to the default branch */
-    branch?: string;
-    /** Number of commits to retrieve from the remote. Defaults to `50` */
-    depth?: number;
-}
-
 /**
  * Get a list of branch commits for a new repository
  * @param query_params Details about the repository
  */
 export function listRemoteRepositoryCommits(
-    query_params: RepositoryBranchDetails,
+    query_params: PlaceRemoteRepositoryCommitsQuery,
 ): Observable<GitCommitDetails[]> {
     return show({
         id: 'remote_commits',
@@ -164,7 +146,7 @@ export function listRemoteRepositoryCommits(
  * @param query_params Details about the repository
  */
 export function listRemoteRepositoryTags(
-    query_params: RepositoryDetails,
+    query_params: PlaceRemoteRepositoryQuery,
 ): Observable<string[]> {
     return show({
         id: 'remote_tags',
@@ -301,3 +283,21 @@ export function pullRepositoryChanges(
         path: PATH,
     });
 }
+
+/**
+ * Get the folder tree structure of a repository
+ * @param id ID of the repository
+ * @param query_params Query parameters to add to the request
+ */
+export function listRepositoryFolders(
+    id: string,
+    query_params?: PlaceRepositoryFoldersQuery,
+): Observable<string[]> {
+    return task({
+        id,
+        task_name: 'folders',
+        form_data: query_params,
+        method: 'get',
+        path: PATH,
+    });
+}

package/src/repositories/interfaces.ts

@@ -1,3 +1,5 @@
+import { PlaceResourceQueryOptions } from '../resources/interface';
+
 /** Type of repository */
 export enum PlaceRepositoryType {
     /** Repository is a collection of Driver logic */
@@ -6,6 +8,10 @@ export enum PlaceRepositoryType {
     Interface = 'interface',
 }
 
+/** Mapping of available query parameters for the repositories index endpoint */
+export interface PlaceRepositoryQueryOptions extends PlaceResourceQueryOptions {}
+
+/** Query parameters for repository commit listing */
 export interface PlaceRepositoryCommitQuery {
     /** URL encoded name of the branch being requested */
     branch?: string;
@@ -20,24 +26,50 @@ export interface GitCommitDetails {
     author: string;
     /** Short hash of the commit */
     commit: string;
-    /** ISO datetime string for commit  */
+    /** ISO datetime string for commit */
     date: string;
     /** Commit summary */
     subject: string;
 }
 
+/** Query parameters for repository driver details */
 export interface PlaceRepositoryDetailsQuery {
-    /** URL encoded name of the driver being requested */
+    /** URL encoded name of the driver being requested (required) */
     driver: string;
-    /** Hash of the commit being requested for the driver */
+    /** Hash of the commit being requested for the driver (required) */
     commit: string;
 }
 
+/** Query parameters for repository pull */
 export interface PlaceRepositoryPullQuery {
     /** Hash of the commit being requested */
     commit: string;
 }
 
+/** Query parameters for remote repository operations */
+export interface PlaceRemoteRepositoryQuery {
+    /** The git URL that represents the repository (required) */
+    repository_url: string;
+    /** A username for access if required */
+    username?: string;
+    /** The password or access token as required */
+    password?: string;
+}
+
+/** Query parameters for remote repository commits */
+export interface PlaceRemoteRepositoryCommitsQuery extends PlaceRemoteRepositoryQuery {
+    /** The branch to grab commits from */
+    branch?: string;
+    /** The number of commits to return */
+    depth?: number;
+}
+
+/** Query parameters for repository folders listing */
+export interface PlaceRepositoryFoldersQuery {
+    /** Include dot files and folders */
+    include_dots?: boolean;
+}
+
 /** Metadata for a repository commit */
 export interface PlaceRepositoryCommit {
     /** Hash associated with the commit */

package/src/resources/interface.ts

@@ -7,15 +7,20 @@ import { HashMap } from '../utilities/types';
 export interface PlaceResourceQueryOptions {
     /**
      * Search filter supporting the following syntax
-     * https://www.elastic.co/guide/en/elasticsearch/reference/5.5/query-dsl-simple-query-string-query.html
+     * https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-simple-query-string-query.html
      */
     q?: string;
-    /** Comma seperated list of fields to apply the query to */
+    /**
+     * Comma separated list of fields to search.
+     * Accepts wildcard expressions and boost relevance scores using caret ^ operator.
+     */
     fields?: string;
     /** Number of results to return. Defaults to `20`. Max `500` */
     limit?: number;
-    /** Offsets of the results to return. Max `10000` */
+    /** @deprecated Use `ref` for pagination. Offset of the results to return. Max `10000` */
     offset?: number;
+    /** Token for accessing the next page of results, provided in the `Link` header */
+    ref?: string;
     /** Number of milliseconds to cache the query response */
     cache?: number;
     /** Whether the request is a API poll request */
@@ -80,7 +85,7 @@ export interface TaskParameters<T> {
     id: string;
     task_name: string;
     form_data?: any;
-    method?: 'post' | 'get' | 'del' | 'put';
+    method?: 'post' | 'get' | 'del' | 'put' | 'patch';
     callback?: (_: any) => T;
     path: string;
 }

package/src/saml-sources/functions.ts

@@ -1,6 +1,5 @@
 import { PlaceAuthSourceQueryOptions } from '../auth-sources/interfaces';
 import { create, query, remove, show, update } from '../resources/functions';
-import { HashMap } from '../utilities/types';
 import { PlaceSAMLSource } from './saml-source';
 
 /**
@@ -24,12 +23,11 @@ export function querySAMLSources(
 }
 
 /**
- * Get the data for an SAML source
+ * Get the data for a SAML source
  * @param id ID of the SAML source to retrieve
- * @param query_params Query parameters to add the to request URL
  */
-export function showSAMLSource(id: string, query_params: HashMap = {}) {
-    return show({ id, query_params, fn: process, path: PATH });
+export function showSAMLSource(id: string) {
+    return show({ id, query_params: {}, fn: process, path: PATH });
 }
 
 /**
@@ -64,10 +62,9 @@ export function addSAMLSource(form_data: Partial<PlaceSAMLSource>) {
 }
 
 /**
- * Remove an SAML source from the database
+ * Remove a SAML source from the database
  * @param id ID of the SAML source
- * @param query_params Query parameters to add the to request URL
  */
-export function removeSAMLSource(id: string, query_params: HashMap = {}) {
-    return remove({ id, query_params, path: PATH });
+export function removeSAMLSource(id: string) {
+    return remove({ id, query_params: {}, path: PATH });
 }