seatalk-components 0.0.0-alpha1

package/README.md

@@ -0,0 +1,25 @@
+# seatalk-components
+
+seatalk-components is a versatile npm package designed to provide a wide range of reusable UI components for web development. It simplifies the process of building user interfaces by offering pre-built components that can be easily integrated into any project.
+
+## Installation
+
+To install seatalk-components, run the following command in your terminal:
+
+```
+npm install seatalk-components
+```
+
+## Features
+
+- **Responsive Design**: seatalk-components includes components that adapt to different screen sizes, ensuring a seamless user experience across devices.
+- **Customization**: Each component offers customization options, allowing developers to tailor the appearance and behavior to their specific needs.
+- **Accessibility**: seatalk-components prioritizes accessibility, ensuring that all components are compatible with assistive technologies and follow best practices for inclusivity.
+
+## Contributing
+
+Contributions to seatalk-components are welcome! If you have any ideas for new components or improvements to existing ones, please feel free to submit a pull request. We appreciate your help in making seatalk-components even better.
+
+## License
+
+seatalk-components is released under the MIT license. See the LICENSE file for more information.

package/index.js

@@ -0,0 +1,1071 @@
+// index.js
+// This package provides data structures and utilities for handling SeaTalk-related components
+// such as messages, users, teams, and channels, along with validation and formatting helpers.
+// It focuses on structuring and validating data typically exchanged or used within a SeaTalk
+// integration context, simulating component-like behavior through data manipulation and validation
+// without relying on external UI frameworks.
+
+// --- Constants ---
+
+/**
+ * @typedef {'text' | 'card' | 'file' | 'unknown'} SeaTalkMessageType
+ */
+
+/**
+ * Enum for standard SeaTalk message types.
+ * @readonly
+ * @enum {SeaTalkMessageType}
+ */
+const SeaTalkMessageTypes = {
+  TEXT: 'text',
+  CARD: 'card',
+  FILE: 'file',
+  UNKNOWN: 'unknown'
+};
+
+/**
+ * @typedef {'user' | 'team' | 'channel' | 'unknown'} SeaTalkEntityType
+ */
+
+/**
+ * Enum for standard SeaTalk entity types.
+ * @readonly
+ * @enum {SeaTalkEntityType}
+ */
+const SeaTalkEntityTypes = {
+  USER: 'user',
+  TEAM: 'team',
+  CHANNEL: 'channel',
+  UNKNOWN: 'unknown'
+};
+
+/**
+ * Maximum length for a text message content.
+ * @type {number}
+ */
+const MAX_TEXT_MESSAGE_LENGTH = 20000;
+
+/**
+ * Maximum length for a card title.
+ * @type {number}
+ */
+const MAX_CARD_TITLE_LENGTH = 1000;
+
+/**
+ * Maximum number of sections allowed in a card.
+ * @type {number}
+ */
+const MAX_CARD_SECTIONS = 20;
+
+/**
+ * Maximum number of actions allowed in a card.
+ * @type {number}
+ */
+const MAX_CARD_ACTIONS = 10;
+
+/**
+ * Regular expression for validating a basic URL format.
+ * @type {RegExp}
+ */
+const URL_REGEX = /^(?:\w+:)?\/\/[\w.-]+(?:\.[\w\.-]+)+[\w\-\._~:/?#[\]@!\$&'\(\)\*\+,;=.]+$/;
+
+/**
+ * Regular expression for validating a SeaTalk entity ID (basic alphanumeric, potentially with hyphens/underscores).
+ * @type {RegExp}
+ */
+const SEATALK_ID_REGEX = /^[a-zA-Z0-9_-]+$/;
+
+// --- Utility Functions ---
+
+/**
+ * Checks if a value is a string.
+ * @param {*} value - The value to check.
+ * @returns {boolean} True if the value is a string, false otherwise.
+ */
+function isString(value) {
+  return typeof value === 'string';
+}
+
+/**
+ * Checks if a value is a number.
+ * @param {*} value - The value to check.
+ * @returns {boolean} True if the value is a number, false otherwise.
+ */
+function isNumber(value) {
+  return typeof value === 'number';
+}
+
+/**
+ * Checks if a value is a boolean.
+ * @param {*} value - The value to check.
+ * @returns {boolean} True if the value is a boolean, false otherwise.
+ */
+function isBoolean(value) {
+  return typeof value === 'boolean';
+}
+
+/**
+ * Checks if a value is an array.
+ * @param {*} value - The value to check.
+ * @returns {boolean} True if the value is an array, false otherwise.
+ */
+function isArray(value) {
+  return Array.isArray(value);
+}
+
+/**
+ * Checks if a value is an object (and not null or an array).
+ * @param {*} value - The value to check.
+ * @returns {boolean} True if the value is an object, false otherwise.
+ */
+function isObject(value) {
+  return typeof value === 'object' && value !== null && !isArray(value);
+}
+
+/**
+ * Checks if a string is a valid basic URL.
+ * @param {*} value - The value to check.
+ * @returns {boolean} True if the value is a valid URL string, false otherwise.
+ */
+function isValidUrl(value) {
+  if (!isString(value)) {
+    return false;
+  }
+  try {
+    // Use URL constructor for a stricter check first
+    new URL(value);
+    // Then check against a basic regex for common patterns not covered by URL constructor alone (like relative paths, though SeaTalk URLs are likely absolute)
+    return URL_REGEX.test(value);
+  } catch (e) {
+    return false; // Invalid URL constructor input
+  }
+}
+
+/**
+ * Checks if a string is a valid non-empty SeaTalk entity ID.
+ * @param {*} value - The value to check.
+ * @returns {boolean} True if the value is a valid SeaTalk ID string, false otherwise.
+ */
+function isValidSeaTalkId(value) {
+  return isString(value) && value.length > 0 && SEATALK_ID_REGEX.test(value);
+}
+
+/**
+ * Formats a timestamp (Date object or number) into a SeaTalk-friendly string.
+ * Example: "YYYY-MM-DD HH:mm:ss"
+ * @param {Date | number} timestamp - The timestamp to format.
+ * @returns {string | null} The formatted date string or null if invalid input.
+ */
+function formatSeaTalkTimestamp(timestamp) {
+  let date;
+  if (timestamp instanceof Date) {
+    date = timestamp;
+  } else if (isNumber(timestamp)) {
+    date = new Date(timestamp);
+  } else {
+    // Try parsing as string if it's a string
+    if (isString(timestamp)) {
+       const parsedDate = new Date(timestamp);
+       if (!isNaN(parsedDate.getTime())) {
+           date = parsedDate;
+       } else {
+           return null; // Invalid string format
+       }
+    } else {
+       return null; // Invalid input type
+    }
+  }
+
+  if (isNaN(date.getTime())) {
+    return null; // Invalid date value
+  }
+
+  const pad = (num) => num.toString().padStart(2, '0');
+
+  const year = date.getFullYear();
+  const month = pad(date.getMonth() + 1); // Months are 0-indexed
+  const day = pad(date.getDate());
+  const hours = pad(date.getHours());
+  const minutes = pad(date.getMinutes());
+  const seconds = pad(date.getSeconds());
+
+  // Basic ISO-like format
+  return `${year}-${month}-${day} ${hours}:${minutes}:${seconds}`;
+}
+
+/**
+ * Escapes a string for potential use in a SeaTalk text message or card text (basic markdown escaping).
+ * @param {string} text - The text to escape.
+ * @returns {string} The escaped text.
+ */
+function escapeSeaTalkText(text) {
+  if (!isString(text)) {
+    return String(text); // Coerce to string if not already
+  }
+  // Escape common markdown special characters
+  return text.replace(/[\\`*_[\]()#+\-.!]/g, '\\$&');
+}
+
+// --- Base Component / Entity Class ---
+
+/**
+ * Base class for all SeaTalk entities (User, Team, Channel, etc.).
+ * Provides common properties like ID and basic validation.
+ */
+class SeaTalkEntity {
+  /**
+   * @param {object} data - The raw data object for the entity.
+   * @param {string} data.id - The unique identifier for the entity.
+   * @param {SeaTalkEntityType} [entityType=SeaTalkEntityTypes.UNKNOWN] - The type of the entity.
+   * @throws {Error} If the ID is missing or invalid.
+   */
+  constructor(data, entityType = SeaTalkEntityTypes.UNKNOWN) {
+    if (!isObject(data)) {
+      throw new Error(`Invalid initialization data for SeaTalkEntity. Expected object, got ${typeof data}.`);
+    }
+    if (!isValidSeaTalkId(data.id)) {
+      throw new Error(`Invalid or missing ID for SeaTalkEntity. ID: "${data.id}".`);
+    }
+
+    /**
+     * The unique identifier for the entity.
+     * @type {string}
+     * @private
+     */
+    this._id = data.id;
+
+    /**
+     * The type of the entity.
+     * @type {SeaTalkEntityType}
+     * @private
+     */
+    this._type = entityType;
+  }
+
+  /**
+   * Gets the unique identifier of the entity.
+   * @returns {string} The entity ID.
+   */
+  getId() {
+    return this._id;
+  }
+
+  /**
+   * Gets the type of the entity.
+   * @returns {SeaTalkEntityType} The entity type.
+   */
+  getType() {
+    return this._type;
+  }
+
+  /**
+   * Validates the entity instance.
+   * @returns {boolean} True if the entity is valid.
+   * @throws {Error} If the entity is invalid.
+   */
+  validate() {
+    if (!isValidSeaTalkId(this._id)) {
+      throw new Error(`Validation Error: Invalid ID "${this._id}" for ${this._type} entity.`);
+    }
+     if (!Object.values(SeaTalkEntityTypes).includes(this._type)) {
+         throw new Error(`Validation Error: Invalid internal type "${this._type}" for entity ID "${this._id}".`);
+     }
+    return true;
+  }
+
+  /**
+   * Converts the entity instance to a plain JavaScript object.
+   * Should be overridden by subclasses.
+   * @returns {object} A plain object representation of the entity.
+   */
+  toJSON() {
+    return {
+      id: this._id,
+      type: this._type,
+    };
+  }
+}
+
+// --- Specific Entity Components ---
+
+/**
+ * Represents a SeaTalk User entity.
+ */
+class SeaTalkUser extends SeaTalkEntity {
+  /**
+   * @param {object} data - The raw data object for the user.
+   * @param {string} data.id - The unique user ID.
+   * @param {string} data.name - The user's name.
+   * @param {string} [data.displayName] - The user's display name (if different).
+   * @param {string} [data.avatarUrl] - URL to the user's avatar image.
+   * @param {boolean} [data.isActive=true] - Whether the user account is active.
+   * @throws {Error} If required properties are missing or invalid.
+   */
+  constructor(data) {
+    super(data, SeaTalkEntityTypes.USER);
+
+    if (!isString(data.name) || data.name.length === 0) {
+      throw new Error(`Invalid or missing 'name' for SeaTalkUser ID "${this.getId()}".`);
+    }
+
+    /** @private */ this._name = data.name;
+    /** @private */ this._displayName = isString(data.displayName) && data.displayName.length > 0 ? data.displayName : data.name;
+    /** @private */ this._avatarUrl = isValidUrl(data.avatarUrl) ? data.avatarUrl : undefined;
+    /** @private */ this._isActive = isBoolean(data.isActive) ? data.isActive : true;
+  }
+
+  /** @returns {string} The user's name. */
+  getName() { return this._name; }
+  /** @returns {string} The user's display name. */
+  getDisplayName() { return this._displayName; }
+  /** @returns {string | undefined} The avatar URL or undefined. */
+  getAvatarUrl() { return this._avatarUrl; }
+  /** @returns {boolean} True if active. */
+  isActive() { return this._isActive; }
+
+  /**
+   * Validates the SeaTalkUser instance.
+   * @returns {boolean} True if the user is valid.
+   * @throws {Error} If the user is invalid.
+   */
+  validate() {
+    super.validate();
+    if (!isString(this._name) || this._name.length === 0) {
+      throw new Error(`Validation Error: Invalid name "${this._name}" for user "${this.getId()}".`);
+    }
+    if (!isString(this._displayName) || this._displayName.length === 0) {
+       throw new Error(`Validation Error: Invalid display name "${this._displayName}" for user "${this.getId()}".`);
+    }
+    if (this._avatarUrl !== undefined && !isValidUrl(this._avatarUrl)) {
+       throw new Error(`Validation Error: Invalid avatar URL "${this._avatarUrl}" for user "${this.getId()}".`);
+    }
+    if (!isBoolean(this._isActive)) {
+       throw new Error(`Validation Error: Invalid isActive status for user "${this.getId()}".`);
+    }
+    return true;
+  }
+
+  /** @returns {object} A plain object representation of the user. */
+  toJSON() {
+    return {
+      ...super.toJSON(),
+      name: this._name,
+      displayName: this._displayName,
+      avatarUrl: this._avatarUrl,
+      isActive: this._isActive,
+    };
+  }
+}
+
+/**
+ * Represents a SeaTalk Team entity.
+ */
+class SeaTalkTeam extends SeaTalkEntity {
+  /**
+   * @param {object} data - The raw data object for the team.
+   * @param {string} data.id - The unique team ID.
+   * @param {string} data.name - The team's name.
+   * @param {string} [data.description] - A description for the team.
+   * @throws {Error} If required properties are missing or invalid.
+   */
+  constructor(data) {
+    super(data, SeaTalkEntityTypes.TEAM);
+    if (!isString(data.name) || data.name.length === 0) {
+      throw new Error(`Invalid or missing 'name' for SeaTalkTeam ID "${this.getId()}".`);
+    }
+    /** @private */ this._name = data.name;
+    /** @private */ this._description = isString(data.description) ? data.description : undefined;
+  }
+  /** @returns {string} The team's name. */
+  getName() { return this._name; }
+  /** @returns {string | undefined} The team description. */
+  getDescription() { return this._description; }
+
+  /**
+   * Validates the SeaTalkTeam instance.
+   * @returns {boolean} True if the team is valid.
+   * @throws {Error} If the team is invalid.
+   */
+  validate() {
+    super.validate();
+    if (!isString(this._name) || this._name.length === 0) {
+      throw new Error(`Validation Error: Invalid name "${this._name}" for team "${this.getId()}".`);
+    }
+    if (this._description !== undefined && !isString(this._description)) {
+        throw new Error(`Validation Error: Invalid description type for team "${this.getId()}".`);
+    }
+    return true;
+  }
+  /** @returns {object} A plain object representation of the team. */
+  toJSON() {
+    return {
+      ...super.toJSON(),
+      name: this._name,
+      description: this._description,
+    };
+  }
+}
+
+/**
+ * Represents a SeaTalk Channel entity.
+ */
+class SeaTalkChannel extends SeaTalkEntity {
+  /**
+   * @param {object} data - The raw data object for the channel.
+   * @param {string} data.id - The unique channel ID.
+   * @param {string} data.name - The channel's name.
+   * @param {string} [data.topic] - A topic for the channel.
+   * @throws {Error} If required properties are missing or invalid.
+   */
+  constructor(data) {
+    super(data, SeaTalkEntityTypes.CHANNEL);
+    if (!isString(data.name) || data.name.length === 0) {
+      throw new Error(`Invalid or missing 'name' for SeaTalkChannel ID "${this.getId()}".`);
+    }
+    /** @private */ this._name = data.name;
+    /** @private */ this._topic = isString(data.topic) ? data.topic : undefined;
+  }
+  /** @returns {string} The channel's name. */
+  getName() { return this._name; }
+  /** @returns {string | undefined} The channel topic. */
+  getTopic() { return this._topic; }
+
+  /**
+   * Validates the SeaTalkChannel instance.
+   * @returns {boolean} True if the channel is valid.
+   * @throws {Error} If the channel is invalid.
+   */
+  validate() {
+    super.validate();
+    if (!isString(this._name) || this._name.length === 0) {
+      throw new Error(`Validation Error: Invalid name "${this._name}" for channel "${this.getId()}".`);
+    }
+    if (this._topic !== undefined && !isString(this._topic)) {
+        throw new Error(`Validation Error: Invalid topic type for channel "${this.getId()}".`);
+    }
+    return true;
+  }
+  /** @returns {object} A plain object representation of the channel. */
+  toJSON() {
+    return {
+      ...super.toJSON(),
+      name: this._name,
+      topic: this._topic,
+    };
+  }
+}
+
+// --- Base Message Class ---
+
+/**
+ * Base class for all SeaTalk messages.
+ * Provides common properties like ID, sender, timestamp, and type.
+ */
+class SeaTalkMessage {
+  /**
+   * @param {object} data - The raw data object for the message.
+   * @param {string} data.id - The unique identifier for the message.
+   * @param {string | object} data.sender - The ID string or raw object for the sender.
+   * @param {Date | number | string} [data.timestamp] - The timestamp when the message was sent (defaults to now).
+   * @param {SeaTalkMessageType} messageType - The specific type of the message.
+   * @throws {Error} If required properties are missing or invalid.
+   */
+  constructor(data, messageType) {
+    if (!isObject(data)) {
+       throw new Error(`Invalid initialization data for SeaTalkMessage. Expected object, got ${typeof data}.`);
+    }
+    if (!isValidSeaTalkId(data.id)) {
+      throw new Error(`Invalid or missing ID for SeaTalkMessage. ID: "${data.id}".`);
+    }
+    if (!isString(data.sender) && !isObject(data.sender)) {
+       throw new Error(`Invalid or missing sender for SeaTalkMessage ID "${data.id}". Sender: "${data.sender}".`);
+    }
+    if (!Object.values(SeaTalkMessageTypes).includes(messageType)) {
+        throw new Error(`Invalid message type "${messageType}" provided for SeaTalkMessage ID "${data.id}".`);
+    }
+
+    /** @private */ this._id = data.id;
+    /** @private */ this._sender = data.sender;
+    /** @private */ this._timestamp = (data.timestamp instanceof Date || isNumber(data.timestamp))
+                       ? new Date(data.timestamp)
+                       : (isString(data.timestamp) ? new Date(data.timestamp) : new Date());
+
+    if (isNaN(this._timestamp.getTime())) {
+         // If Date construction from string/number failed
+         throw new Error(`Invalid timestamp value "${data.timestamp}" for SeaTalkMessage ID "${data.id}".`);
+    }
+
+    /** @private */ this._type = messageType;
+  }
+
+  /** @returns {string} The unique identifier of the message. */
+  getId() { return this._id; }
+  /** @returns {string | object} The sender's ID string or raw object. */
+  getSender() { return this._sender; }
+  /** @returns {Date} The timestamp of the message. */
+  getTimestamp() { return this._timestamp; }
+  /** @returns {string | null} The formatted timestamp string. */
+  getFormattedTimestamp() { return formatSeaTalkTimestamp(this._timestamp); }
+  /** @returns {SeaTalkMessageType} The type of the message. */
+  getType() { return this._type; }
+
+  /**
+   * Checks if the message is of a specific type.
+   * @param {SeaTalkMessageType} type - The type to check against.
+   * @returns {boolean} True if the message type matches.
+   */
+  isOfType(type) {
+    return this._type === type;
+  }
+
+  /**
+   * Validates the SeaTalkMessage instance.
+   * @returns {boolean} True if the message is valid.
+   * @throws {Error} If the message is invalid.
+   */
+  validate() {
+    if (!isValidSeaTalkId(this._id)) {
+      throw new Error(`Validation Error: Invalid ID "${this._id}" for message of type "${this._type}".`);
+    }
+    if (!isString(this._sender) && !isObject(this._sender)) {
+       throw new Error(`Validation Error: Invalid sender "${this._sender}" for message ID "${this._id}".`);
+    }
+    if (isNaN(this._timestamp.getTime())) {
+        throw new Error(`Validation Error: Invalid timestamp for message ID "${this._id}".`);
+    }
+     if (!Object.values(SeaTalkMessageTypes).includes(this._type)) {
+         throw new Error(`Validation Error: Invalid internal type "${this._type}" for message ID "${this._id}".`);
+     }
+    return true;
+  }
+
+  /**
+   * Converts the message instance to a plain JavaScript object.
+   * @returns {object} A plain object representation.
+   */
+  toJSON() {
+    return {
+      id: this._id,
+      sender: this._sender, // Keep sender as is in base toJSON
+      timestamp: this._timestamp.toISOString(),
+      type: this._type,
+    };
+  }
+}
+
+// --- Specific Message Components ---
+
+/**
+ * Represents a SeaTalk Text Message.
+ */
+class SeaTalkTextMessage extends SeaTalkMessage {
+  /**
+   * @param {object} data - The raw data object for the text message.
+   * @param {string} data.id - The unique message ID.
+   * @param {string | object} data.sender - The ID string or raw object for the sender.
+   * @param {string} data.text - The text content.
+   * @param {Date | number | string} [data.timestamp] - The timestamp.
+   * @throws {Error} If required properties are missing or invalid.
+   */
+  constructor(data) {
+    super(data, SeaTalkMessageTypes.TEXT);
+
+    if (!isString(data.text) || data.text.length === 0) {
+      throw new Error(`Invalid or missing 'text' content for SeaTalkTextMessage ID "${this.getId()}".`);
+    }
+    if (data.text.length > MAX_TEXT_MESSAGE_LENGTH) {
+        throw new Error(`'text' content exceeds maximum length of ${MAX_TEXT_MESSAGE_LENGTH} for SeaTalkTextMessage ID "${this.getId()}".`);
+    }
+
+    /** @private */ this._text = data.text;
+  }
+
+  /** @returns {string} The text content. */
+  getText() { return this._text; }
+  /** @returns {string} The escaped text content. */
+  getEscapedText() { return escapeSeaTalkText(this._text); }
+
+  /**
+   * Validates the SeaTalkTextMessage instance.
+   * @returns {boolean} True if valid.
+   * @throws {Error} If invalid.
+   */
+  validate() {
+    super.validate();
+    if (!isString(this._text) || this._text.length === 0) {
+       throw new Error(`Validation Error: Invalid text content for text message "${this.getId()}".`);
+    }
+    if (this._text.length > MAX_TEXT_MESSAGE_LENGTH) {
+        throw new Error(`Validation Error: Text content exceeds max length for text message "${this.getId()}".`);
+    }
+    return true;
+  }
+  /** @returns {object} A plain object representation. */
+  toJSON() {
+    return {
+      ...super.toJSON(),
+      text: this._text,
+    };
+  }
+}
+
+/**
+ * Represents a SeaTalk Card Message.
+ */
+class SeaTalkCardMessage extends SeaTalkMessage {
+  /**
+   * @param {object} data - The raw data object for the card message.
+   * @param {string} data.id - The unique message ID.
+   * @param {string | object} data.sender - The ID string or raw object for the sender.
+   * @param {object} data.card - The card structure object.
+   * @param {string} data.card.title - The title of the card.
+   * @param {Array<object>} [data.card.sections] - Array of card sections.
+   * @param {Array<object>} [data.card.actions] - Array of card actions.
+   * @param {Date | number | string} [data.timestamp] - The timestamp.
+   * @throws {Error} If required properties are missing or invalid.
+   */
+  constructor(data) {
+    super(data, SeaTalkMessageTypes.CARD);
+
+    if (!isObject(data.card)) {
+      throw new Error(`Invalid or missing 'card' structure for SeaTalkCardMessage ID "${this.getId()}".`);
+    }
+    if (!isString(data.card.title) || data.card.title.length === 0) {
+       throw new Error(`Invalid or missing 'card.title' for SeaTalkCardMessage ID "${this.getId()}".`);
+    }
+    if (data.card.title.length > MAX_CARD_TITLE_LENGTH) {
+        throw new Error(`'card.title' exceeds maximum length of ${MAX_CARD_TITLE_LENGTH} for SeaTalkCardMessage ID "${this.getId()}".`);
+    }
+    if (data.card.sections !== undefined && (!isArray(data.card.sections) || data.card.sections.length > MAX_CARD_SECTIONS)) {
+        throw new Error(`Invalid or too many sections in 'card.sections' for SeaTalkCardMessage ID "${this.getId()}". Max ${MAX_CARD_SECTIONS}.`);
+    }
+    if (data.card.actions !== undefined && (!isArray(data.card.actions) || data.card.actions.length > MAX_CARD_ACTIONS)) {
+        throw new Error(`Invalid or too many actions in 'card.actions' for SeaTalkCardMessage ID "${this.getId()}". Max ${MAX_CARD_ACTIONS}.`);
+    }
+
+    /**
+     * @type {{title: string, sections: Array<object>, actions: Array<object>}}
+     * @private
+     */
+    this._card = {
+      title: data.card.title,
+      sections: isArray(data.card.sections) ? data.card.sections.map(s => ({...s})) : [], // Clone sections
+      actions: isArray(data.card.actions) ? data.card.actions.map(a => ({...a})) : [], // Clone actions
+    };
+
+     // Perform initial basic validation of structure components
+    this._validateSections(this._card.sections, this.getId());
+    this._validateActions(this._card.actions, this.getId());
+  }
+
+  /** @returns {{title: string, sections: Array<object>, actions: Array<object>}} The card structure. */
+  getCard() { return {...this._card, sections: [...this._card.sections], actions: [...this._card.actions]}; } // Return clones
+  /** @returns {string} The card title. */
+  getCardTitle() { return this._card.title; }
+  /** @returns {Array<object>} An array of card sections (cloned). */
+  getCardSections() { return [...this._card.sections]; }
+  /** @returns {Array<object>} An array of card actions (cloned). */
+  getCardActions() { return [...this._card.actions]; }
+
+  /**
+   * Adds a section to the card.
+   * @param {object} section - The section object to add.
+   * @throws {Error} If the section is invalid or exceeds max sections.
+   */
+  addSection(section) {
+    if (!isObject(section)) {
+      throw new Error(`Invalid section object provided for card message "${this.getId()}".`);
+    }
+    if (this._card.sections.length >= MAX_CARD_SECTIONS) {
+       throw new Error(`Cannot add section. Maximum number of sections (${MAX_CARD_SECTIONS}) reached for card message "${this.getId()}".`);
+    }
+    // Perform basic validation on the section before adding
+    try {
+       this._validateSections([section], this.getId(), this._card.sections.length);
+    } catch (e) {
+       throw new Error(`Validation Error adding section to card message "${this.getId()}": ${e.message}`);
+    }
+    this._card.sections.push({...section}); // Add a clone
+  }
+
+  /**
+   * Adds an action to the card.
+   * @param {object} action - The action object to add. Must have 'type' and 'text'.
+   * @throws {Error} If the action is invalid or exceeds max actions.
+   */
+  addAction(action) {
+    if (!isObject(action) || !isString(action.type) || action.type.length === 0 || !isString(action.text) || action.text.length === 0) {
+      throw new Error(`Invalid action object provided for card message "${this.getId()}". Must have non-empty 'type' and 'text'.`);
+    }
+     if (this._card.actions.length >= MAX_CARD_ACTIONS) {
+       throw new Error(`Cannot add action. Maximum number of actions (${MAX_CARD_ACTIONS}) reached for card message "${this.getId()}".`);
+    }
+     // Perform basic validation on the action before adding
+     try {
+        this._validateActions([action], this.getId(), this._card.actions.length);
+     } catch (e) {
+        throw new Error(`Validation Error adding action to card message "${this.getId()}": ${e.message}`);
+     }
+    this._card.actions.push({...action}); // Add a clone
+  }
+
+   /**
+    * Internal helper to validate an array of card sections.
+    * @private
+    * @param {Array<object>} sections - The sections array.
+    * @param {string} messageId - The ID of the parent message.
+    * @param {number} [startIndex=0] - The starting index for error reporting.
+    * @throws {Error} If validation fails.
+    */
+   _validateSections(sections, messageId, startIndex = 0) {
+       if (!isArray(sections)) throw new Error('Internal Error: Sections must be an array.');
+       sections.forEach((section, index) => {
+            const currentIndex = startIndex + index;
+            if (!isObject(section)) {
+                 throw new Error(`Invalid section structure at index ${currentIndex} for card message ID "${messageId}". Expected object.`);
+            }
+            // Example section validation: must have text or image or fields
+            const hasText = isString(section.text) && section.text.length > 0;
+            const hasImage = isObject(section.image);
+            const hasFields = isArray(section.fields) && section.fields.length > 0;
+
+            if (!hasText && !hasImage && !hasFields) {
+                  throw new Error(`Section at index ${currentIndex} must contain 'text', 'image', or 'fields' for card message ID "${messageId}".`);
+            }
+
+            // More detailed validation for section properties
+            if (section.text !== undefined && !isString(section.text)) {
+                 throw new Error(`Invalid 'text' property type in section at index ${currentIndex} for card message ID "${messageId}". Expected string.`);
+            }
+            if (hasImage) {
+               if (!isString(section.image.url) || !isValidUrl(section.image.url)) {
+                    throw new Error(`Invalid or missing 'url' property in 'image' object in section at index ${currentIndex} for card message ID "${messageId}". Expected valid URL string.`);
+               }
+                if (section.image.altText !== undefined && !isString(section.image.altText)) {
+                     throw new Error(`Invalid 'altText' property type in 'image' object in section at index ${currentIndex} for card message ID "${messageId}". Expected string.`);
+                }
+            }
+             if (hasFields) {
+                section.fields.forEach((field, fieldIndex) => {
+                    if (!isObject(field) || !isString(field.title) || field.title.length === 0 || !isString(field.value) || field.value.length === 0) {
+                         throw new Error(`Invalid field structure at index ${fieldIndex} in section ${currentIndex} for card message ID "${messageId}". Must have non-empty 'title' and 'value'.`);
+                    }
+                });
+             }
+       });
+   }
+
+   /**
+    * Internal helper to validate an array of card actions.
+    * @private
+    * @param {Array<object>} actions - The actions array.
+    * @param {string} messageId - The ID of the parent message.
+    * @param {number} [startIndex=0] - The starting index for error reporting.
+    * @throws {Error} If validation fails.
+    */
+   _validateActions(actions, messageId, startIndex = 0) {
+       if (!isArray(actions)) throw new Error('Internal Error: Actions must be an array.');
+        actions.forEach((action, index) => {
+             const currentIndex = startIndex + index;
+             if (!isObject(action) || !isString(action.type) || action.type.length === 0 || !isString(action.text) || action.text.length === 0) {
+                  throw new Error(`Invalid action structure at index ${currentIndex} for card message ID "${messageId}". Must have non-empty 'type' and 'text'.`);
+             }
+             // Detailed validation based on action type
+              if (action.type === 'open_url') {
+                 if (!isString(action.url) || !isValidUrl(action.url)) {
+                      throw new Error(`Invalid or missing 'url' property for 'open_url' action at index ${currentIndex} for card message ID "${messageId}". Expected valid URL string.`);
+                 }
+              }
+             // Add validation for other action types here as needed (e.g., 'submit', 'message', etc.)
+         });
+   }
+
+
+  /**
+   * Validates the SeaTalkCardMessage instance and its card structure.
+   * @returns {boolean} True if valid.
+   * @throws {Error} If invalid.
+   */
+  validate() {
+    super.validate();
+    if (!isObject(this._card)) {
+       throw new Error(`Validation Error: Invalid internal card object for card message "${this.getId()}".`);
+    }
+    if (!isString(this._card.title) || this._card.title.length === 0) {
+       throw new Error(`Validation Error: Invalid card title "${this._card.title}" for card message "${this.getId()}".`);
+    }
+    if (this._card.title.length > MAX_CARD_TITLE_LENGTH) {
+        throw new Error(`Validation Error: Card title exceeds max length for card message "${this.getId()}".`);
+    }
+    if (!isArray(this._card.sections)) {
+       throw new Error(`Validation Error: Invalid internal sections array for card message "${this.getId()}".`);
+    }
+    if (this._card.sections.length > MAX_CARD_SECTIONS) {
+       throw new Error(`Validation Error: Too many sections for card message "${this.getId()}".`);
+    }
+    // Validate all current sections
+    this._validateSections(this._card.sections, this.getId());
+
+    if (!isArray(this._card.actions)) {
+       throw new Error(`Validation Error: Invalid internal actions array for card message "${this.getId()}".`);
+    }
+    if (this._card.actions.length > MAX_CARD_ACTIONS) {
+       throw new Error(`Validation Error: Too many actions for card message "${this.getId()}".`);
+    }
+     // Validate all current actions
+    this._validateActions(this._card.actions, this.getId());
+
+    return true;
+  }
+
+  /** @returns {object} A plain object representation. */
+  toJSON() {
+    return {
+      ...super.toJSON(),
+      card: {
+        title: this._card.title,
+        sections: this._card.sections.map(s => ({...s})), // Return clones
+        actions: this._card.actions.map(a => ({...a})), // Return clones
+      },
+    };
+  }
+}
+
+/**
+ * Represents a SeaTalk File Message.
+ */
+class SeaTalkFileMessage extends SeaTalkMessage {
+  /**
+   * @param {object} data - The raw data object for the file message.
+   * @param {string} data.id - The unique message ID.
+   * @param {string | object} data.sender - The ID string or raw object for the sender.
+   * @param {object} data.file - The file details object.
+   * @param {string} data.file.name - The name of the file.
+   * @param {number} data.file.size - The size of the file in bytes.
+   * @param {string} data.file.url - The URL to the file.
+   * @param {string} [data.file.mimeType] - The MIME type.
+   * @param {Date | number | string} [data.timestamp] - The timestamp.
+   * @throws {Error} If required properties are missing or invalid.
+   */
+  constructor(data) {
+    super(data, SeaTalkMessageTypes.FILE);
+
+    if (!isObject(data.file)) {
+      throw new Error(`Invalid or missing 'file' structure for SeaTalkFileMessage ID "${this.getId()}".`);
+    }
+    if (!isString(data.file.name) || data.file.name.length === 0) {
+       throw new Error(`Invalid or missing 'file.name' for SeaTalkFileMessage ID "${this.getId()}".`);
+    }
+    if (!isNumber(data.file.size) || data.file.size < 0) {
+       throw new Error(`Invalid or missing 'file.size' for SeaTalkFileMessage ID "${this.getId()}". Must be a non-negative number.`);
+    }
+    if (!isString(data.file.url) || !isValidUrl(data.file.url)) {
+       throw new Error(`Invalid or missing 'file.url' for SeaTalkFileMessage ID "${this.getId()}".`);
+    }
+    if (data.file.mimeType !== undefined && !isString(data.file.mimeType)) {
+        throw new Error(`Invalid 'file.mimeType' type for SeaTalkFileMessage ID "${this.getId()}". Expected string.`);
+    }
+
+    /**
+     * @type {{name: string, size: number, url: string, mimeType?: string}}
+     * @private
+     */
+    this._file = {
+      name: data.file.name,
+      size: data.file.size,
+      url: data.file.url,
+      mimeType: isString(data.file.mimeType) ? data.file.mimeType : undefined,
+    };
+  }
+
+  /** @returns {{name: string, size: number, url: string, mimeType?: string}} The file details. */
+  getFile() { return {...this._file}; } // Return clone
+  /** @returns {string} The file name. */
+  getFileName() { return this._file.name; }
+  /** @returns {number} The file size. */
+  getFileSize() { return this._file.size; }
+  /** @returns {string} The file URL. */
+  getFileUrl() { return this._file.url; }
+  /** @returns {string | undefined} The file MIME type or undefined. */
+  getFileMimeType() { return this._file.mimeType; }
+
+  /**
+   * Validates the SeaTalkFileMessage instance and its file structure.
+   * @returns {boolean} True if valid.
+   * @throws {Error} If invalid.
+   */
+  validate() {
+    super.validate();
+    if (!isObject(this._file)) {
+        throw new Error(`Validation Error: Invalid internal file object for file message "${this.getId()}".`);
+    }
+    if (!isString(this._file.name) || this._file.name.length === 0) {
+        throw new Error(`Validation Error: Invalid file name "${this._file.name}" for file message "${this.getId()}".`);
+    }
+    if (!isNumber(this._file.size) || this._file.size < 0) {
+        throw new Error(`Validation Error: Invalid file size "${this._file.size}" for file message "${this.getId()}".`);
+    }
+    if (!isString(this._file.url) || !isValidUrl(this._file.url)) {
+        throw new Error(`Validation Error: Invalid file URL "${this._file.url}" for file message "${this.getId()}".`);
+    }
+    if (this._file.mimeType !== undefined && !isString(this._file.mimeType)) {
+        throw new Error(`Validation Error: Invalid file mimeType "${this._file.mimeType}" for file message "${this.getId()}".`);
+    }
+    return true;
+  }
+
+  /** @returns {object} A plain object representation. */
+  toJSON() {
+    return {
+      ...super.toJSON(),
+      file: {...this._file}, // Return clone
+    };
+  }
+}
+
+
+// --- Factory / Parser Functions ---
+
+/**
+ * Attempts to parse a raw data object into a specific SeaTalk message class instance.
+ * It requires the 'type' property to determine which class to instantiate.
+ * @param {object} rawData - The raw data object received, potentially from an API.
+ * @returns {SeaTalkMessage | SeaTalkTextMessage | SeaTalkCardMessage | SeaTalkFileMessage | null} An instance of the appropriate message class, or null if parsing fails or type is unknown/invalid.
+ * @throws {Error} If basic message properties (id, sender, type) are missing or invalid.
+ */
+function parseSeaTalkMessage(rawData) {
+    if (!isObject(rawData)) {
+        console.error('parseSeaTalkMessage Error: Input is not an object.');
+        throw new Error('parseSeaTalkMessage Error: Input is not an object.');
+    }
+     if (!isValidSeaTalkId(rawData.id)) {
+        console.error(`parseSeaTalkMessage Error: Invalid or missing message ID "${rawData.id}".`);
+        throw new Error(`parseSeaTalkMessage Error: Invalid or missing message ID "${rawData.id}".`);
+    }
+    if (!isString(rawData.sender) && !isObject(rawData.sender)) {
+        console.error(`parseSeaTalkMessage Error: Invalid or missing message sender for ID "${rawData.id}".`);
+         throw new Error(`parseSeaTalkMessage Error: Invalid or missing message sender for ID "${rawData.id}".`);
+     }
+     if (!Object.values(SeaTalkMessageTypes).includes(rawData.type)) {
+        console.warn(`parseSeaTalkMessage Warning: Unknown or invalid message type "${rawData.type}" for message ID "${rawData.id}". Cannot parse into specific type.`);
+        return null; // Return null for unknown types
+     }
+
+    try {
+        switch (rawData.type) {
+            case SeaTalkMessageTypes.TEXT:
+                return new SeaTalkTextMessage(rawData);
+            case SeaTalkMessageTypes.CARD:
+                return new SeaTalkCardMessage(rawData);
+            case SeaTalkMessageTypes.FILE:
+                return new SeaTalkFileMessage(rawData);
+             case SeaTalkMessageTypes.UNKNOWN:
+                 console.warn(`parseSeaTalkMessage Warning: Explicitly unknown message type for ID "${rawData.id}". Returning null.`);
+                 return null;
+            default:
+                 // This case should be covered by the initial type check, but as a safeguard
+                 console.warn(`parseSeaTalkMessage Warning: Unhandled message type "${rawData.type}" for ID "${rawData.id}". Returning null.`);
+                 return null;
+        }
+    } catch (error) {
+        // Catch errors during specific class construction (e.g., detailed validation errors)
+        console.error(`parseSeaTalkMessage Error: Failed to construct message instance for ID "${rawData.id}" with type "${rawData.type}".`, error.message);
+        throw new Error(`parseSeaTalkMessage Error: Failed to construct message instance for ID "${rawData.id}" with type "${rawData.type}". Details: ${error.message}`);
+    }
+}
+
+/**
+ * Attempts to parse a raw data object into a specific SeaTalk entity class instance.
+ * Requires the 'type' property to determine which class to instantiate.
+ * @param {object} rawData - The raw data object.
+ * @returns {SeaTalkEntity | SeaTalkUser | SeaTalkTeam | SeaTalkChannel | null} An instance of the appropriate entity class, or null if parsing fails or type is unknown/invalid.
+ * @throws {Error} If basic entity properties (id, type) are missing or invalid.
+ */
+function parseSeaTalkEntity(rawData) {
+     if (!isObject(rawData)) {
+        console.error('parseSeaTalkEntity Error: Input is not an object.');
+        throw new Error('parseSeaTalkEntity Error: Input is not an object.');
+    }
+     if (!isValidSeaTalkId(rawData.id)) {
+        console.error(`parseSeaTalkEntity Error: Invalid or missing entity ID "${rawData.id}".`);
+        throw new Error(`parseSeaTalkEntity Error: Invalid or missing entity ID "${rawData.id}".`);
+    }
+     if (!Object.values(SeaTalkEntityTypes).includes(rawData.type)) {
+         console.warn(`parseSeaTalkEntity Warning: Unknown or invalid entity type "${rawData.type}" for entity ID "${rawData.id}". Cannot parse into specific type.`);
+         return null; // Return null for unknown types
+     }
+
+    try {
+        switch (rawData.type) {
+            case SeaTalkEntityTypes.USER:
+                 return new SeaTalkUser(rawData);
+            case SeaTalkEntityTypes.TEAM:
+                 return new SeaTalkTeam(rawData);
+            case SeaTalkEntityTypes.CHANNEL:
+                 return new SeaTalkChannel(rawData);
+             case SeaTalkEntityTypes.UNKNOWN:
+                  console.warn(`parseSeaTalkEntity Warning: Explicitly unknown entity type for ID "${rawData.id}". Returning base entity or null.`);
+                  try {
+                    return new SeaTalkEntity(rawData); // Return base if explicitly unknown type is given
+                  } catch (e) {
+                     console.error(`parseSeaTalkEntity Error: Failed to construct base entity for ID "${rawData.id}".`, e.message);
+                     return null; // Return null if even base construction fails
+                  }
+            default:
+                 // This case should be covered by the initial type check, but as a safeguard
+                 console.warn(`parseSeaTalkEntity Warning: Unhandled entity type "${rawData.type}" for ID "${rawData.id}". Returning null.`);
+                 return null;
+        }
+    } catch (error) {
+        // Catch errors during specific class construction (e.g., detailed validation errors)
+        console.error(`parseSeaTalkEntity Error: Failed to construct entity instance for ID "${rawData.id}" with type "${rawData.type}".`, error.message);
+        throw new Error(`parseSeaTalkEntity Error: Failed to construct entity instance for ID "${rawData.id}" with type "${rawData.type}". Details: ${error.message}`);
+    }
+}
+
+
+// --- Main Export ---
+
+/**
+ * @namespace SeaTalkComponents
+ * @description Provides data structures, utilities, and validation for SeaTalk-related components.
+ */
+const SeaTalkComponents = {
+  // Constants
+  SeaTalkMessageTypes,
+  SeaTalkEntityTypes,
+  MAX_TEXT_MESSAGE_LENGTH,
+  MAX_CARD_TITLE_LENGTH,
+  MAX_CARD_SECTIONS,
+  MAX_CARD_ACTIONS,
+
+  // Utility Functions
+  isString,
+  isNumber,
+  isBoolean,
+  isArray,
+  isObject,
+  isValidUrl,
+  isValidSeaTalkId,
+  formatSeaTalkTimestamp,
+  escapeSeaTalkText,
+
+  // Entity Classes
+  SeaTalkEntity,
+  SeaTalkUser,
+  SeaTalkTeam,
+  SeaTalkChannel,
+
+  // Message Classes
+  SeaTalkMessage,
+  SeaTalkTextMessage,
+  SeaTalkCardMessage,
+  SeaTalkFileMessage,
+
+  // Parsing/Factory Functions
+  parseSeaTalkMessage,
+  parseSeaTalkEntity,
+};
+
+// Export the main object
+module.exports = SeaTalkComponents;

package/package.json

@@ -0,0 +1 @@
+{"author":"","description":"seatalk-components: A collection of reusable UI components for building modern web applications.","keywords":[],"license":"MIT","main":"index.js","name":"seatalk-components","scripts":{"test":"echo \"test\" \u0026\u0026 exit 1"},"version":"0.0.0-alpha1"}