@placeos/ts-client 4.6.0 → 4.7.0

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 });
 }

package/src/settings/functions.ts

@@ -7,7 +7,10 @@ import {
     update,
 } from '../resources/functions';
 import { HashMap } from '../utilities/types';
-import { PlaceSettingsQueryOptions } from './interfaces';
+import {
+    PlaceSettingsHistoryOptions,
+    PlaceSettingsQueryOptions,
+} from './interfaces';
 import { PlaceSettings } from './settings';
 
 /**
@@ -31,10 +34,9 @@ export function querySettings(query_params: PlaceSettingsQueryOptions = {}) {
 /**
  * Get the data for settings
  * @param id ID of the settings to retrieve
- * @param query_params Query parameters to add the to request URL
  */
-export function showSettings(id: string, query_params: HashMap = {}) {
-    return show({ id, query_params, fn: process, path: PATH });
+export function showSettings(id: string) {
+    return show({ id, query_params: {}, fn: process, path: PATH });
 }
 
 /**
@@ -73,20 +75,22 @@ export function addSettings(
 }
 
 /**
- * Remove an settings from the database
+ * Remove settings from the database
  * @param id ID of the settings
- * @param query_params Query parameters to add the to request URL
  */
-export function removeSettings(id: string, query_params: HashMap = {}) {
-    return remove({ id, query_params, path: PATH });
+export function removeSettings(id: string) {
+    return remove({ id, query_params: {}, path: PATH });
 }
 
 /**
- * Get historical version of settings
+ * Get historical versions of settings
  * @param id ID of the settings to retrieve
  * @param query_params Query parameters to add the to request URL
  */
-export function settingsHistory(id: string, query_params: HashMap = {}) {
+export function settingsHistory(
+    id: string,
+    query_params: PlaceSettingsHistoryOptions = {},
+) {
     return task({
         id,
         task_name: 'history',

package/src/settings/interfaces.ts

@@ -17,3 +17,11 @@ export interface PlaceSettingsQueryOptions extends PlaceResourceQueryOptions {
     /** ID of the parent zone, system, module or driver to grab settings for */
     parent_id?: string;
 }
+
+/** Allowable query parameters for settings history endpoint */
+export interface PlaceSettingsHistoryOptions {
+    /** Maximum number of results to return */
+    limit?: number;
+    /** Starting offset of the result set for pagination */
+    offset?: number;
+}

package/src/short-url/functions.ts

@@ -0,0 +1,155 @@
+import { create, query, remove, show, update } from '../api';
+import { apiEndpoint } from '../auth';
+import { get } from '../http/functions';
+import { toQueryString } from '../utilities/api';
+import { PlaceShortUrl } from './short-url.class';
+import {
+    PlaceQrCodeOptions,
+    PlaceShortUrlPngQrOptions,
+    PlaceShortUrlQueryOptions,
+} from './interfaces';
+
+/**
+ * @private
+ */
+const PATH = 'short_url';
+
+/** Convert raw server data to a short URL object */
+function processShortUrl(item: Partial<PlaceShortUrl>) {
+    return new PlaceShortUrl(item);
+}
+
+/**
+ * Query the available short URLs
+ * @param query_params Query parameters to add to the request URL
+ */
+export function queryShortUrls(query_params: PlaceShortUrlQueryOptions = {}) {
+    return query({
+        query_params,
+        fn: processShortUrl,
+        path: PATH,
+    });
+}
+
+/**
+ * Get the data for a short URL
+ * @param id ID of the short URL to retrieve
+ * @param query_params Query parameters to add to the request URL
+ */
+export function showShortUrl(
+    id: string,
+    query_params: Record<string, any> = {},
+) {
+    return show({
+        id,
+        query_params,
+        fn: processShortUrl,
+        path: PATH,
+    });
+}
+
+/**
+ * Update a short URL in the database
+ * @param id ID of the short URL
+ * @param form_data New values for the short URL
+ * @param method HTTP verb to use on request. Defaults to `patch`
+ */
+export function updateShortUrl(
+    id: string,
+    form_data: Partial<PlaceShortUrl>,
+    method: 'put' | 'patch' = 'patch',
+) {
+    return update({
+        id,
+        form_data,
+        query_params: {},
+        method,
+        fn: processShortUrl,
+        path: PATH,
+    });
+}
+
+/**
+ * Add a new short URL to the database
+ * @param form_data Short URL data
+ */
+export function addShortUrl(form_data: Partial<PlaceShortUrl>) {
+    return create({
+        form_data,
+        query_params: {},
+        fn: processShortUrl,
+        path: PATH,
+    });
+}
+
+/**
+ * Remove a short URL from the database
+ * @param id ID of the short URL
+ * @param query_params Query parameters to add to the request URL
+ */
+export function removeShortUrl(
+    id: string,
+    query_params: Record<string, any> = {},
+) {
+    return remove({ id, query_params, path: PATH });
+}
+
+/**
+ * Get the redirect URL for a short URL.
+ * Returns the full redirect URL that can be used to navigate to the short URL destination.
+ * @param id ID of the short URL
+ */
+export function shortUrlRedirectUrl(
+    id: string,
+): string {
+    return `${apiEndpoint()}${PATH}/${encodeURIComponent(id)}/redirect`;
+}
+
+/**
+ * Get an SVG QR code for a short URL
+ * @param id ID of the short URL
+ */
+export function getShortUrlQrCodeSvg(id: string) {
+    return get(
+        `${apiEndpoint()}${PATH}/${encodeURIComponent(id)}/qr_code.svg`,
+        { response_type: 'text' },
+    );
+}
+
+/**
+ * Get the URL for a PNG QR code for a short URL.
+ * Use this URL directly in an img tag or fetch it separately.
+ * @param id ID of the short URL
+ * @param options Options including size (between 72px and 512px)
+ */
+export function shortUrlQrCodePngUrl(
+    id: string,
+    options: PlaceShortUrlPngQrOptions = {},
+): string {
+    const q = toQueryString(options);
+    return `${apiEndpoint()}${PATH}/${encodeURIComponent(id)}/qr_code.png${q ? '?' + q : ''}`;
+}
+
+/**
+ * Get the URL for generating a QR code with user-defined content.
+ * @param options Options for QR code generation including content, format, and size
+ */
+export function qrCodeUrl(options: PlaceQrCodeOptions): string {
+    const { format = 'svg', ...params } = options;
+    const query_params = { ...params, format };
+    const q = toQueryString(query_params);
+    return `${apiEndpoint()}${PATH}/qr_code${q ? '?' + q : ''}`;
+}
+
+/**
+ * Generate an SVG QR code with user-defined content.
+ * For PNG format, use qrCodeUrl() and fetch the URL directly.
+ * @param options Options for QR code generation including content and size
+ */
+export function generateQrCode(options: Omit<PlaceQrCodeOptions, 'format'>) {
+    const query_params = { ...options, format: 'svg' };
+    const q = toQueryString(query_params);
+    return get(`${apiEndpoint()}${PATH}/qr_code${q ? '?' + q : ''}`, {
+        response_type: 'text',
+    });
+}

package/src/short-url/interfaces.ts

@@ -0,0 +1,25 @@
+import { PlaceResourceQueryOptions } from '../resources/interface';
+
+/** Mapping of available query parameters for the short_url index endpoint */
+export interface PlaceShortUrlQueryOptions extends PlaceResourceQueryOptions {}
+
+/** Format options for QR code generation */
+export type QrCodeFormat = 'svg' | 'png';
+
+/** Options for generating a QR code with custom content */
+export interface PlaceQrCodeOptions {
+    /** The contents of the QR code (required) */
+    content: string;
+    /** Identifier for the QR code (required) */
+    id: string;
+    /** File format of the response */
+    format?: QrCodeFormat;
+    /** Size of the QR code in pixels (between 72px and 512px) */
+    size?: number;
+}
+
+/** Options for generating a PNG QR code for a short URL */
+export interface PlaceShortUrlPngQrOptions {
+    /** Size of the QR code in pixels (between 72px and 512px) */
+    size?: number;
+}

package/src/short-url/short-url.class.ts

@@ -0,0 +1,33 @@
+export class PlaceShortUrl {
+    readonly id: string;
+    readonly name: string;
+    readonly uri: string;
+    readonly description: string;
+    readonly user_id: string;
+    readonly user_email: string;
+    readonly user_name: string;
+    readonly redirect_count: number;
+    readonly enabled: boolean;
+    readonly valid_from: string;
+    readonly valid_until: string;
+    readonly authority_id: string;
+    readonly created_at: number;
+    readonly updated_at: number;
+
+    constructor(data: Partial<PlaceShortUrl>) {
+        this.id = data.id || '';
+        this.name = data.name || '';
+        this.uri = data.uri || '';
+        this.description = data.description || '';
+        this.user_id = data.user_id || '';
+        this.user_email = data.user_email || '';
+        this.user_name = data.user_name || '';
+        this.redirect_count = data.redirect_count || 0;
+        this.enabled = data.enabled ?? true;
+        this.valid_from = data.valid_from || '';
+        this.valid_until = data.valid_until || '';
+        this.authority_id = data.authority_id || '';
+        this.created_at = data.created_at || 0;
+        this.updated_at = data.updated_at || 0;
+    }
+}

package/src/signage/interfaces.ts

@@ -6,8 +6,17 @@ export interface SignageMetrics {
     media_counts: Record<string, number>;
 }
 
-/** Allowable query parameters for systems index endpoint */
+/** Allowable query parameters for signage media index endpoint */
 export interface SignageMediaQueryOptions extends PlaceResourceQueryOptions {
     /** ID of the authority to filter the returned values on */
     authority_id?: string;
 }
+
+/** Allowable query parameters for signage playlists index endpoint */
+export interface SignagePlaylistQueryOptions extends PlaceResourceQueryOptions {}
+
+/** Allowable query parameters for signage playlist media revisions endpoint */
+export interface SignagePlaylistRevisionsOptions {
+    /** Maximum number of revisions to return */
+    limit?: number;
+}

package/src/storages/functions.ts

@@ -0,0 +1,88 @@
+import { create, query, remove, show, update } from '../resources/functions';
+import { PlaceStorage } from './storage.class';
+import { PlaceStorageQueryOptions } from './interfaces';
+
+/**
+ * @private
+ */
+const PATH = 'storages';
+
+/** Convert raw server data to a storage object */
+function processStorage(item: Partial<PlaceStorage>) {
+    return new PlaceStorage(item);
+}
+
+/**
+ * Query the available storages
+ * @param query_params Query parameters to add to the request URL
+ */
+export function queryStorages(query_params: PlaceStorageQueryOptions = {}) {
+    return query({
+        query_params,
+        fn: processStorage,
+        path: PATH,
+    });
+}
+
+/**
+ * Get the data for a storage
+ * @param id ID of the storage to retrieve
+ * @param query_params Query parameters to add to the request URL
+ */
+export function showStorage(
+    id: string,
+    query_params: Record<string, any> = {},
+) {
+    return show({
+        id,
+        query_params,
+        fn: processStorage,
+        path: PATH,
+    });
+}
+
+/**
+ * Update a storage in the database
+ * @param id ID of the storage
+ * @param form_data New values for the storage
+ * @param method HTTP verb to use on request. Defaults to `patch`
+ */
+export function updateStorage(
+    id: string,
+    form_data: Partial<PlaceStorage>,
+    method: 'put' | 'patch' = 'patch',
+) {
+    return update({
+        id,
+        form_data,
+        query_params: {},
+        method,
+        fn: processStorage,
+        path: PATH,
+    });
+}
+
+/**
+ * Add a new storage to the database
+ * @param form_data Storage data
+ */
+export function addStorage(form_data: Partial<PlaceStorage>) {
+    return create({
+        form_data,
+        query_params: {},
+        fn: processStorage,
+        path: PATH,
+    });
+}
+
+/**
+ * Remove a storage from the database
+ * @param id ID of the storage
+ * @param query_params Query parameters to add to the request URL
+ */
+export function removeStorage(
+    id: string,
+    query_params: Record<string, any> = {},
+) {
+    return remove({ id, query_params, path: PATH });
+}

package/src/storages/interfaces.ts

@@ -0,0 +1,7 @@
+import { PlaceResourceQueryOptions } from '../resources/interface';
+
+/** Mapping of available query parameters for the storages index endpoint */
+export interface PlaceStorageQueryOptions extends PlaceResourceQueryOptions {
+    /** Return storages which are in the authority provided */
+    auth_id?: string;
+}

package/src/storages/storage.class.ts

@@ -0,0 +1,34 @@
+/** Storage type enumeration */
+export type StorageType = 's3' | 'azure' | 'google';
+
+export class PlaceStorage {
+    readonly id: string;
+    readonly storage_type: StorageType | null;
+    readonly bucket_name: string;
+    readonly region: string;
+    readonly access_key: string;
+    readonly access_secret: string;
+    readonly authority_id: string;
+    readonly endpoint: string;
+    readonly is_default: boolean;
+    readonly ext_filter: string[];
+    readonly mime_filter: string[];
+    readonly created_at: number;
+    readonly updated_at: number;
+
+    constructor(data: Partial<PlaceStorage>) {
+        this.id = data.id || '';
+        this.storage_type = data.storage_type || null;
+        this.bucket_name = data.bucket_name || '';
+        this.region = data.region || '';
+        this.access_key = data.access_key || '';
+        this.access_secret = data.access_secret || '';
+        this.authority_id = data.authority_id || '';
+        this.endpoint = data.endpoint || '';
+        this.is_default = data.is_default ?? false;
+        this.ext_filter = data.ext_filter || [];
+        this.mime_filter = data.mime_filter || [];
+        this.created_at = data.created_at || 0;
+        this.updated_at = data.updated_at || 0;
+    }
+}

package/src/systems/functions.ts

@@ -1,4 +1,5 @@
 import { Observable } from 'rxjs';
+import { apiEndpoint } from '../auth/functions';
 import {
     create,
     query,
@@ -11,7 +12,17 @@ import { PlaceSettings } from '../settings/settings';
 import { PlaceTrigger } from '../triggers/trigger';
 import { HashMap } from '../utilities/types';
 import { PlaceZone } from '../zones/zone';
-import { PlaceModuleFunctionMap, PlaceSystemsQueryOptions } from './interfaces';
+import {
+    PlaceModuleFunctionMap,
+    PlaceSystemControlOptions,
+    PlaceSystemMetadataOptions,
+    PlaceSystemShowOptions,
+    PlaceSystemsQueryOptions,
+    PlaceSystemsWithEmailsOptions,
+    PlaceSystemStartStopOptions,
+    PlaceSystemTriggerShowOptions,
+    PlaceSystemTriggersQueryOptions,
+} from './interfaces';
 import { PlaceSystem } from './system';
 
 /**
@@ -33,11 +44,11 @@ export function querySystems(query_params: PlaceSystemsQueryOptions = {}) {
 }
 
 /**
- * Query the available systems
+ * Query the available systems by email addresses
  * @param query_params Query parameters to add the to request URL
  */
 export function querySystemsWithEmails(
-    query_params: PlaceSystemsQueryOptions = {},
+    query_params: PlaceSystemsWithEmailsOptions,
 ) {
     return query({ query_params, fn: process, path: `${PATH}/with_emails` });
 }
@@ -49,7 +60,7 @@ export function querySystemsWithEmails(
  */
 export function showSystem(
     id: string,
-    query_params: PlaceSystemsQueryOptions = {},
+    query_params: PlaceSystemShowOptions = {},
 ) {
     return show({ id, query_params, fn: process, path: PATH });
 }
@@ -86,12 +97,11 @@ export function addSystem(form_data: Partial<PlaceSystem>) {
 }
 
 /**
- * Remove an system from the database
+ * Remove a system from the database
  * @param id ID of the system
- * @param query_params Query parameters to add the to request URL
  */
-export function removeSystem(id: string, query_params: HashMap = {}) {
-    return remove({ id, query_params, path: PATH });
+export function removeSystem(id: string) {
+    return remove({ id, query_params: {}, path: PATH });
 }
 
 /**
@@ -136,12 +146,16 @@ export function removeSystemModule(
 /**
  * Start the given system and clears any existing caches
  * @param id System ID
+ * @param query_params Query parameters to add the to request URL
  */
-export function startSystem(id: string): Observable<void> {
+export function startSystem(
+    id: string,
+    query_params: PlaceSystemStartStopOptions = {},
+): Observable<void> {
     return task<void>({
         id,
         task_name: 'start',
-        form_data: {},
+        form_data: query_params,
         path: PATH,
     });
 }
@@ -149,11 +163,16 @@ export function startSystem(id: string): Observable<void> {
 /**
  * Stops all modules in the given system
  * @param id System ID
+ * @param query_params Query parameters to add the to request URL
  */
-export function stopSystem(id: string): Observable<void> {
+export function stopSystem(
+    id: string,
+    query_params: PlaceSystemStartStopOptions = {},
+): Observable<void> {
     return task<void>({
         id,
         task_name: 'stop',
+        form_data: query_params,
         path: PATH,
     });
 }
@@ -282,10 +301,14 @@ export function listSystemZones(id: string) {
 /**
  * Get list of triggers for system
  * @param id System ID
+ * @param query_params Query parameters to add the to request URL
  */
-export function listSystemTriggers(id: string) {
+export function listSystemTriggers(
+    id: string,
+    query_params: PlaceSystemTriggersQueryOptions = {},
+) {
     return query({
-        query_params: {},
+        query_params,
         fn: (i: HashMap) => new PlaceTrigger(i),
         path: `${PATH}/${id}/triggers`,
     });
@@ -341,3 +364,80 @@ export function systemSettings(id: string): Observable<PlaceSettings[]> {
         path: PATH,
     });
 }
+
+/**
+ * Get the websocket API endpoint URL for system control.
+ * @param query_params Query parameters to add to the URL
+ */
+export function systemControlUrl(query_params: PlaceSystemControlOptions = {}): string {
+    const endpoint = apiEndpoint();
+    const wsProtocol = endpoint.startsWith('https') ? 'wss:' : 'ws:';
+    const httpProtocol = endpoint.startsWith('https') ? 'https:' : 'http:';
+    let url = endpoint.replace(httpProtocol, wsProtocol) + `${PATH}/control`;
+    if (query_params.fixed_device) {
+        url += `?fixed_device=${encodeURIComponent(String(query_params.fixed_device))}`;
+    }
+    return url;
+}
+
+/**
+ * Get metadata for the system
+ * @param id System ID
+ * @param query_params Query parameters to add to the request
+ */
+export function systemMetadata(
+    id: string,
+    query_params: PlaceSystemMetadataOptions = {},
+): Observable<HashMap> {
+    return task({
+        id,
+        task_name: 'metadata',
+        form_data: query_params,
+        method: 'get',
+        path: PATH,
+    });
+}
+
+/**
+ * Get a particular trigger instance
+ * @param sys_id System ID
+ * @param trig_id Trigger ID
+ * @param query_params Query parameters to add to the request
+ */
+export function showSystemTrigger(
+    sys_id: string,
+    trig_id: string,
+    query_params: PlaceSystemTriggerShowOptions = {},
+): Observable<PlaceTrigger> {
+    return task({
+        id: sys_id,
+        task_name: `triggers/${encodeURIComponent(trig_id)}`,
+        form_data: query_params,
+        method: 'get',
+        callback: (item: Partial<PlaceTrigger>) => new PlaceTrigger(item),
+        path: PATH,
+    });
+}
+
+/**
+ * Update the details of a trigger instance
+ * @param sys_id System ID
+ * @param trig_id Trigger ID
+ * @param data Values for trigger properties
+ * @param method HTTP verb to use on request. Defaults to `patch`
+ */
+export function updateSystemTrigger(
+    sys_id: string,
+    trig_id: string,
+    data: Partial<PlaceTrigger>,
+    method: 'put' | 'patch' = 'patch',
+): Observable<PlaceTrigger> {
+    return task({
+        id: sys_id,
+        task_name: `triggers/${encodeURIComponent(trig_id)}`,
+        form_data: data,
+        method,
+        callback: (item: Partial<PlaceTrigger>) => new PlaceTrigger(item),
+        path: PATH,
+    });
+}