@xiboplayer/utils 0.3.7 → 0.4.0

package/src/cms-api.js

@@ -2,7 +2,8 @@
  * CMS API Client — OAuth2-authenticated REST client for Xibo CMS
  *
  * Full CRUD client for all Xibo CMS REST API entities: displays, layouts,
- * regions, widgets, media, campaigns, schedules, display groups, resolutions.
+ * regions, widgets, media, campaigns, schedules, display groups, resolutions,
+ * commands, dayparts, playlists, datasets, notifications, folders, and tags.
  * Implements OAuth2 client_credentials flow (machine-to-machine).
  *
  * Usage:
@@ -747,6 +748,805 @@ export class CmsApiClient {
   async editLayout(layoutId, params) {
     return this.request('PUT', `/layout/${layoutId}`, params);
   }
+
+  // ── Layout Copy / Discard (#25) ────────────────────────────────────
+
+  /**
+   * Copy a layout
+   * @param {number} layoutId
+   * @param {Object} [opts] - Options (name, description, copyMediaFiles)
+   * @returns {Promise<Object>} Copied layout
+   */
+  async copyLayout(layoutId, opts = {}) {
+    return this.post(`/layout/copy/${layoutId}`, opts);
+  }
+
+  /**
+   * Discard a draft layout (revert to last published version)
+   * @param {number} layoutId
+   * @returns {Promise<void>}
+   */
+  async discardLayout(layoutId) {
+    await this.put(`/layout/discard/${layoutId}`);
+  }
+
+  // ── Campaign Edit / Unassign (#26) ─────────────────────────────────
+
+  /**
+   * Edit campaign properties
+   * @param {number} campaignId
+   * @param {Object} params - Properties to update (name, etc.)
+   * @returns {Promise<Object>} Updated campaign
+   */
+  async editCampaign(campaignId, params) {
+    return this.put(`/campaign/${campaignId}`, params);
+  }
+
+  /**
+   * Get a single campaign by ID
+   * @param {number} campaignId
+   * @returns {Promise<Object>}
+   */
+  async getCampaign(campaignId) {
+    return this.get(`/campaign/${campaignId}`);
+  }
+
+  /**
+   * Unassign a layout from a campaign
+   * @param {number} campaignId
+   * @param {number} layoutId
+   * @returns {Promise<void>}
+   */
+  async unassignLayoutFromCampaign(campaignId, layoutId) {
+    await this.post(`/campaign/layout/unassign/${campaignId}`, { layoutId });
+  }
+
+  // ── Schedule Edit (#27) ────────────────────────────────────────────
+
+  /**
+   * Edit a schedule event
+   * @param {number} eventId
+   * @param {Object} params - Properties to update (fromDt, toDt, isPriority, etc.)
+   * @returns {Promise<Object>} Updated schedule event
+   */
+  async editSchedule(eventId, params) {
+    return this.put(`/schedule/${eventId}`, params);
+  }
+
+  // ── Layout Retire / Status / Tag (#34) ─────────────────────────────
+
+  /**
+   * Retire a layout (hide from new scheduling but keep existing schedules)
+   * @param {number} layoutId
+   * @returns {Promise<void>}
+   */
+  async retireLayout(layoutId) {
+    await this.put(`/layout/retire/${layoutId}`);
+  }
+
+  /**
+   * Unretire a previously retired layout
+   * @param {number} layoutId
+   * @returns {Promise<void>}
+   */
+  async unretireLayout(layoutId) {
+    await this.put(`/layout/unretire/${layoutId}`);
+  }
+
+  /**
+   * Get layout status (build status, validity)
+   * @param {number} layoutId
+   * @returns {Promise<Object>}
+   */
+  async getLayoutStatus(layoutId) {
+    return this.get(`/layout/status/${layoutId}`);
+  }
+
+  /**
+   * Tag a layout
+   * @param {number} layoutId
+   * @param {string[]} tags - Tag names to add
+   * @returns {Promise<void>}
+   */
+  async tagLayout(layoutId, tags) {
+    await this.post(`/layout/${layoutId}/tag`, { tag: tags.join(',') });
+  }
+
+  /**
+   * Remove tags from a layout
+   * @param {number} layoutId
+   * @param {string[]} tags - Tag names to remove
+   * @returns {Promise<void>}
+   */
+  async untagLayout(layoutId, tags) {
+    await this.post(`/layout/${layoutId}/untag`, { tag: tags.join(',') });
+  }
+
+  // ── Command CRUD (#36) ─────────────────────────────────────────────
+
+  /**
+   * List commands
+   * @param {Object} [filters] - Filters (commandId, command)
+   * @returns {Promise<Array>}
+   */
+  async listCommands(filters = {}) {
+    const data = await this.get('/command', filters);
+    return Array.isArray(data) ? data : [];
+  }
+
+  /**
+   * Create a command
+   * @param {Object} params - { command, description, code }
+   * @returns {Promise<Object>}
+   */
+  async createCommand(params) {
+    return this.post('/command', params);
+  }
+
+  /**
+   * Edit a command
+   * @param {number} commandId
+   * @param {Object} params - Properties to update
+   * @returns {Promise<Object>}
+   */
+  async editCommand(commandId, params) {
+    return this.put(`/command/${commandId}`, params);
+  }
+
+  /**
+   * Delete a command
+   * @param {number} commandId
+   * @returns {Promise<void>}
+   */
+  async deleteCommand(commandId) {
+    await this.del(`/command/${commandId}`);
+  }
+
+  // ── Display Extras (#41) ───────────────────────────────────────────
+
+  /**
+   * Delete a display
+   * @param {number} displayId
+   * @returns {Promise<void>}
+   */
+  async deleteDisplay(displayId) {
+    await this.del(`/display/${displayId}`);
+  }
+
+  /**
+   * Send Wake-on-LAN to a display
+   * @param {number} displayId
+   * @returns {Promise<void>}
+   */
+  async wolDisplay(displayId) {
+    await this.post(`/display/wol/${displayId}`);
+  }
+
+  /**
+   * Set the default layout for a display
+   * @param {number} displayId
+   * @param {number} layoutId - Layout to set as default
+   * @returns {Promise<Object>}
+   */
+  async setDefaultLayout(displayId, layoutId) {
+    return this.put(`/display/${displayId}`, { defaultLayoutId: layoutId });
+  }
+
+  /**
+   * Purge all content from a display (force re-download)
+   * @param {number} displayId
+   * @returns {Promise<void>}
+   */
+  async purgeDisplay(displayId) {
+    await this.post(`/display/purge/${displayId}`);
+  }
+
+  // ── DayPart CRUD (#24) ─────────────────────────────────────────────
+
+  /**
+   * List day parts
+   * @param {Object} [filters] - Filters (dayPartId, name)
+   * @returns {Promise<Array>}
+   */
+  async listDayParts(filters = {}) {
+    const data = await this.get('/daypart', filters);
+    return Array.isArray(data) ? data : [];
+  }
+
+  /**
+   * Create a day part
+   * @param {Object} params - { name, description, startTime, endTime, exceptionDays, ... }
+   * @returns {Promise<Object>}
+   */
+  async createDayPart(params) {
+    return this.post('/daypart', params);
+  }
+
+  /**
+   * Edit a day part
+   * @param {number} dayPartId
+   * @param {Object} params - Properties to update
+   * @returns {Promise<Object>}
+   */
+  async editDayPart(dayPartId, params) {
+    return this.put(`/daypart/${dayPartId}`, params);
+  }
+
+  /**
+   * Delete a day part
+   * @param {number} dayPartId
+   * @returns {Promise<void>}
+   */
+  async deleteDayPart(dayPartId) {
+    await this.del(`/daypart/${dayPartId}`);
+  }
+
+  // ── Library Extensions (#33) ───────────────────────────────────────
+
+  /**
+   * Upload media from a URL
+   * @param {string} url - Remote URL to download
+   * @param {string} name - Name for the media item
+   * @returns {Promise<Object>}
+   */
+  async uploadMediaUrl(url, name) {
+    return this.post('/library', { url, name, type: 'uri' });
+  }
+
+  /**
+   * Copy a media item
+   * @param {number} mediaId
+   * @returns {Promise<Object>} Copied media
+   */
+  async copyMedia(mediaId) {
+    return this.post(`/library/copy/${mediaId}`);
+  }
+
+  /**
+   * Download a media file (returns raw response for streaming)
+   * @param {number} mediaId
+   * @returns {Promise<Response>} Raw fetch response
+   */
+  async downloadMedia(mediaId) {
+    await this.ensureToken();
+    const url = `${this.baseUrl}/api/library/download/${mediaId}`;
+    const response = await fetch(url, {
+      headers: { 'Authorization': `Bearer ${this.accessToken}` }
+    });
+    if (!response.ok) {
+      const text = await response.text();
+      throw new CmsApiError('GET', `/library/download/${mediaId}`, response.status, text);
+    }
+    return response;
+  }
+
+  /**
+   * Edit media properties
+   * @param {number} mediaId
+   * @param {Object} params - Properties to update (name, duration, retired, etc.)
+   * @returns {Promise<Object>}
+   */
+  async editMedia(mediaId, params) {
+    return this.put(`/library/${mediaId}`, params);
+  }
+
+  /**
+   * Get media usage (which layouts/playlists reference this media)
+   * @param {number} mediaId
+   * @returns {Promise<Object>}
+   */
+  async getMediaUsage(mediaId) {
+    return this.get(`/library/usage/${mediaId}`);
+  }
+
+  /**
+   * Tidy the library (remove unused/old revisions)
+   * @returns {Promise<void>}
+   */
+  async tidyLibrary() {
+    await this.post('/library/tidy');
+  }
+
+  // ── Playlist CRUD (#35) ────────────────────────────────────────────
+
+  /**
+   * List playlists
+   * @param {Object} [filters] - Filters (playlistId, name, etc.)
+   * @returns {Promise<Array>}
+   */
+  async listPlaylists(filters = {}) {
+    const data = await this.get('/playlist', filters);
+    return Array.isArray(data) ? data : [];
+  }
+
+  /**
+   * Create a playlist
+   * @param {string} name
+   * @returns {Promise<Object>}
+   */
+  async createPlaylist(name) {
+    return this.post('/playlist', { name });
+  }
+
+  /**
+   * Get a single playlist by ID
+   * @param {number} playlistId
+   * @returns {Promise<Object>}
+   */
+  async getPlaylist(playlistId) {
+    return this.get(`/playlist/${playlistId}`);
+  }
+
+  /**
+   * Edit playlist properties
+   * @param {number} playlistId
+   * @param {Object} params - Properties to update
+   * @returns {Promise<Object>}
+   */
+  async editPlaylist(playlistId, params) {
+    return this.put(`/playlist/${playlistId}`, params);
+  }
+
+  /**
+   * Delete a playlist
+   * @param {number} playlistId
+   * @returns {Promise<void>}
+   */
+  async deletePlaylist(playlistId) {
+    await this.del(`/playlist/${playlistId}`);
+  }
+
+  /**
+   * Reorder widgets in a playlist
+   * @param {number} playlistId
+   * @param {number[]} widgetIds - Ordered widget IDs
+   * @returns {Promise<void>}
+   */
+  async reorderPlaylist(playlistId, widgetIds) {
+    await this.ensureToken();
+    const url = `${this.baseUrl}/api/playlist/order/${playlistId}`;
+    const urlParams = new URLSearchParams();
+    for (const id of widgetIds) {
+      urlParams.append('widgets[]', String(id));
+    }
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${this.accessToken}`,
+        'Content-Type': 'application/x-www-form-urlencoded'
+      },
+      body: urlParams
+    });
+    if (!response.ok) {
+      const text = await response.text();
+      throw new CmsApiError('POST', `/playlist/order/${playlistId}`, response.status, text);
+    }
+  }
+
+  /**
+   * Copy a playlist
+   * @param {number} playlistId
+   * @returns {Promise<Object>} Copied playlist
+   */
+  async copyPlaylist(playlistId) {
+    return this.post(`/playlist/copy/${playlistId}`);
+  }
+
+  // ── Widget Extras (#37) ────────────────────────────────────────────
+
+  /**
+   * Set transition for a widget
+   * @param {number} widgetId
+   * @param {string} type - Transition type (e.g. 'fly', 'fade')
+   * @param {Object} [config] - Transition config (duration, direction)
+   * @returns {Promise<Object>}
+   */
+  async setWidgetTransition(widgetId, type, config = {}) {
+    return this.put(`/playlist/widget/transition/${widgetId}`, { type, ...config });
+  }
+
+  /**
+   * Set audio for a widget
+   * @param {number} widgetId
+   * @param {Object} params - { mediaId, volume, loop }
+   * @returns {Promise<Object>}
+   */
+  async setWidgetAudio(widgetId, params) {
+    return this.put(`/playlist/widget/${widgetId}/audio`, params);
+  }
+
+  /**
+   * Remove audio from a widget
+   * @param {number} widgetId
+   * @returns {Promise<void>}
+   */
+  async removeWidgetAudio(widgetId) {
+    await this.del(`/playlist/widget/${widgetId}/audio`);
+  }
+
+  /**
+   * Set expiry dates for a widget
+   * @param {number} widgetId
+   * @param {Object} params - { fromDt, toDt, deleteOnExpiry }
+   * @returns {Promise<Object>}
+   */
+  async setWidgetExpiry(widgetId, params) {
+    return this.put(`/playlist/widget/${widgetId}/expiry`, params);
+  }
+
+  // ── Template Save / Manage (#39) ───────────────────────────────────
+
+  /**
+   * Save a layout as a template
+   * @param {number} layoutId
+   * @param {Object} params - { name, description, includeWidgets }
+   * @returns {Promise<Object>}
+   */
+  async saveAsTemplate(layoutId, params) {
+    return this.post(`/template/${layoutId}`, params);
+  }
+
+  /**
+   * Get a single template by ID
+   * @param {number} templateId
+   * @returns {Promise<Object>}
+   */
+  async getTemplate(templateId) {
+    return this.get(`/template/${templateId}`);
+  }
+
+  /**
+   * Delete a template
+   * @param {number} templateId
+   * @returns {Promise<void>}
+   */
+  async deleteTemplate(templateId) {
+    await this.del(`/template/${templateId}`);
+  }
+
+  // ── Dataset CRUD (#28) ─────────────────────────────────────────────
+
+  /**
+   * List datasets
+   * @param {Object} [filters] - Filters (dataSetId, dataSet)
+   * @returns {Promise<Array>}
+   */
+  async listDatasets(filters = {}) {
+    const data = await this.get('/dataset', filters);
+    return Array.isArray(data) ? data : [];
+  }
+
+  /**
+   * Create a dataset
+   * @param {Object} params - { dataSet, description }
+   * @returns {Promise<Object>}
+   */
+  async createDataset(params) {
+    return this.post('/dataset', params);
+  }
+
+  /**
+   * Edit a dataset
+   * @param {number} dataSetId
+   * @param {Object} params
+   * @returns {Promise<Object>}
+   */
+  async editDataset(dataSetId, params) {
+    return this.put(`/dataset/${dataSetId}`, params);
+  }
+
+  /**
+   * Delete a dataset
+   * @param {number} dataSetId
+   * @returns {Promise<void>}
+   */
+  async deleteDataset(dataSetId) {
+    await this.del(`/dataset/${dataSetId}`);
+  }
+
+  /**
+   * List columns in a dataset
+   * @param {number} dataSetId
+   * @returns {Promise<Array>}
+   */
+  async listDatasetColumns(dataSetId) {
+    const data = await this.get(`/dataset/${dataSetId}/column`);
+    return Array.isArray(data) ? data : [];
+  }
+
+  /**
+   * Create a column in a dataset
+   * @param {number} dataSetId
+   * @param {Object} params - { heading, dataTypeId, dataSetColumnTypeId, listContent, ... }
+   * @returns {Promise<Object>}
+   */
+  async createDatasetColumn(dataSetId, params) {
+    return this.post(`/dataset/${dataSetId}/column`, params);
+  }
+
+  /**
+   * Edit a dataset column
+   * @param {number} dataSetId
+   * @param {number} columnId
+   * @param {Object} params
+   * @returns {Promise<Object>}
+   */
+  async editDatasetColumn(dataSetId, columnId, params) {
+    return this.put(`/dataset/${dataSetId}/column/${columnId}`, params);
+  }
+
+  /**
+   * Delete a dataset column
+   * @param {number} dataSetId
+   * @param {number} columnId
+   * @returns {Promise<void>}
+   */
+  async deleteDatasetColumn(dataSetId, columnId) {
+    await this.del(`/dataset/${dataSetId}/column/${columnId}`);
+  }
+
+  /**
+   * List rows (data) in a dataset
+   * @param {number} dataSetId
+   * @param {Object} [filters] - Filters (page, length)
+   * @returns {Promise<Array>}
+   */
+  async listDatasetData(dataSetId, filters = {}) {
+    const data = await this.get(`/dataset/data/${dataSetId}`, filters);
+    return Array.isArray(data) ? data : [];
+  }
+
+  /**
+   * Add a row to a dataset
+   * @param {number} dataSetId
+   * @param {Object} rowData - Column heading → value pairs
+   * @returns {Promise<Object>}
+   */
+  async addDatasetRow(dataSetId, rowData) {
+    return this.post(`/dataset/data/${dataSetId}`, rowData);
+  }
+
+  /**
+   * Edit a dataset row
+   * @param {number} dataSetId
+   * @param {number} rowId
+   * @param {Object} rowData - Column heading → value pairs
+   * @returns {Promise<Object>}
+   */
+  async editDatasetRow(dataSetId, rowId, rowData) {
+    return this.put(`/dataset/data/${dataSetId}/${rowId}`, rowData);
+  }
+
+  /**
+   * Delete a dataset row
+   * @param {number} dataSetId
+   * @param {number} rowId
+   * @returns {Promise<void>}
+   */
+  async deleteDatasetRow(dataSetId, rowId) {
+    await this.del(`/dataset/data/${dataSetId}/${rowId}`);
+  }
+
+  /**
+   * Import CSV data into a dataset
+   * @param {number} dataSetId
+   * @param {FormData} formData - Must include CSV file
+   * @returns {Promise<Object>}
+   */
+  async importDatasetCsv(dataSetId, formData) {
+    return this.requestMultipart('POST', `/dataset/import/${dataSetId}`, formData);
+  }
+
+  /**
+   * Clear all data from a dataset
+   * @param {number} dataSetId
+   * @returns {Promise<void>}
+   */
+  async clearDataset(dataSetId) {
+    await this.del(`/dataset/data/${dataSetId}`);
+  }
+
+  // ── Notification CRUD (#29) ────────────────────────────────────────
+
+  /**
+   * List notifications
+   * @param {Object} [filters] - Filters (notificationId, subject)
+   * @returns {Promise<Array>}
+   */
+  async listNotifications(filters = {}) {
+    const data = await this.get('/notification', filters);
+    return Array.isArray(data) ? data : [];
+  }
+
+  /**
+   * Create a notification
+   * @param {Object} params - { subject, body, isEmail, isInterrupt, displayGroupIds, ... }
+   * @returns {Promise<Object>}
+   */
+  async createNotification(params) {
+    return this.post('/notification', params);
+  }
+
+  /**
+   * Edit a notification
+   * @param {number} notificationId
+   * @param {Object} params
+   * @returns {Promise<Object>}
+   */
+  async editNotification(notificationId, params) {
+    return this.put(`/notification/${notificationId}`, params);
+  }
+
+  /**
+   * Delete a notification
+   * @param {number} notificationId
+   * @returns {Promise<void>}
+   */
+  async deleteNotification(notificationId) {
+    await this.del(`/notification/${notificationId}`);
+  }
+
+  // ── Folder CRUD (#30) ─────────────────────────────────────────────
+
+  /**
+   * List folders
+   * @param {Object} [filters] - Filters (folderId, text)
+   * @returns {Promise<Array>}
+   */
+  async listFolders(filters = {}) {
+    const data = await this.get('/folder', filters);
+    return Array.isArray(data) ? data : [];
+  }
+
+  /**
+   * Create a folder
+   * @param {Object} params - { text, parentId }
+   * @returns {Promise<Object>}
+   */
+  async createFolder(params) {
+    return this.post('/folder', params);
+  }
+
+  /**
+   * Edit a folder
+   * @param {number} folderId
+   * @param {Object} params
+   * @returns {Promise<Object>}
+   */
+  async editFolder(folderId, params) {
+    return this.put(`/folder/${folderId}`, params);
+  }
+
+  /**
+   * Delete a folder
+   * @param {number} folderId
+   * @returns {Promise<void>}
+   */
+  async deleteFolder(folderId) {
+    await this.del(`/folder/${folderId}`);
+  }
+
+  // ── Tag CRUD + Entity Tagging (#31) ────────────────────────────────
+
+  /**
+   * List tags
+   * @param {Object} [filters] - Filters (tagId, tag)
+   * @returns {Promise<Array>}
+   */
+  async listTags(filters = {}) {
+    const data = await this.get('/tag', filters);
+    return Array.isArray(data) ? data : [];
+  }
+
+  /**
+   * Create a tag
+   * @param {Object} params - { tag }
+   * @returns {Promise<Object>}
+   */
+  async createTag(params) {
+    return this.post('/tag', params);
+  }
+
+  /**
+   * Edit a tag
+   * @param {number} tagId
+   * @param {Object} params
+   * @returns {Promise<Object>}
+   */
+  async editTag(tagId, params) {
+    return this.put(`/tag/${tagId}`, params);
+  }
+
+  /**
+   * Delete a tag
+   * @param {number} tagId
+   * @returns {Promise<void>}
+   */
+  async deleteTag(tagId) {
+    await this.del(`/tag/${tagId}`);
+  }
+
+  /**
+   * Tag an entity (layout, media, campaign, etc.)
+   * @param {string} entity - Entity type (layout, media, campaign, displaygroup, playlist)
+   * @param {number} id - Entity ID
+   * @param {string[]} tags - Tag names
+   * @returns {Promise<void>}
+   */
+  async tagEntity(entity, id, tags) {
+    await this.post(`/${entity}/${id}/tag`, { tag: tags.join(',') });
+  }
+
+  /**
+   * Remove tags from an entity
+   * @param {string} entity - Entity type
+   * @param {number} id - Entity ID
+   * @param {string[]} tags - Tag names to remove
+   * @returns {Promise<void>}
+   */
+  async untagEntity(entity, id, tags) {
+    await this.post(`/${entity}/${id}/untag`, { tag: tags.join(',') });
+  }
+
+  // ── DisplayGroup Actions (#32) ─────────────────────────────────────
+
+  /**
+   * Change the layout on a display group (immediate override)
+   * @param {number} displayGroupId
+   * @param {number} layoutId
+   * @returns {Promise<void>}
+   */
+  async dgChangeLayout(displayGroupId, layoutId) {
+    await this.post(`/displaygroup/${displayGroupId}/action/changeLayout`, { layoutId });
+  }
+
+  /**
+   * Overlay a layout on a display group
+   * @param {number} displayGroupId
+   * @param {number} layoutId
+   * @returns {Promise<void>}
+   */
+  async dgOverlayLayout(displayGroupId, layoutId) {
+    await this.post(`/displaygroup/${displayGroupId}/action/overlayLayout`, { layoutId });
+  }
+
+  /**
+   * Revert a display group to its scheduled content
+   * @param {number} displayGroupId
+   * @returns {Promise<void>}
+   */
+  async dgRevertToSchedule(displayGroupId) {
+    await this.post(`/displaygroup/${displayGroupId}/action/revertToSchedule`);
+  }
+
+  /**
+   * Trigger immediate content collection on a display group
+   * @param {number} displayGroupId
+   * @returns {Promise<void>}
+   */
+  async dgCollectNow(displayGroupId) {
+    await this.post(`/displaygroup/${displayGroupId}/action/collectNow`);
+  }
+
+  /**
+   * Send a command to a display group
+   * @param {number} displayGroupId
+   * @param {number} commandId
+   * @returns {Promise<void>}
+   */
+  async dgSendCommand(displayGroupId, commandId) {
+    await this.post(`/displaygroup/${displayGroupId}/action/command`, { commandId });
+  }
+
+  /**
+   * Edit display group properties
+   * @param {number} displayGroupId
+   * @param {Object} params - Properties to update
+   * @returns {Promise<Object>}
+   */
+  async editDisplayGroup(displayGroupId, params) {
+    return this.put(`/displaygroup/${displayGroupId}`, params);
+  }
 }
 
 /**