@allternit/gizzi-code 1.0.0

package/src/types/message.d.ts

@@ -0,0 +1,190 @@
+/**
+ * @fileoverview Message types for gizzi-code integration
+ * @module types/message
+ *
+ * Defines core message interfaces and types used across the application
+ * for chat, notifications, and system communications.
+ */
+/**
+ * Represents the possible roles a message can have in a conversation
+ * @typedef {'user' | 'assistant' | 'system'} MessageRole
+ */
+export type MessageRole = 'user' | 'assistant' | 'system';
+/**
+ * Valid message role values for runtime validation
+ * @constant {MessageRole[]}
+ */
+export declare const MESSAGE_ROLES: readonly MessageRole[];
+/**
+ * Supported MIME types for message attachments
+ * @typedef {string} AttachmentMimeType
+ */
+export type AttachmentMimeType = 'image/png' | 'image/jpeg' | 'image/gif' | 'image/webp' | 'image/svg+xml' | 'text/plain' | 'text/markdown' | 'text/html' | 'application/json' | 'application/pdf' | 'application/zip' | 'audio/mpeg' | 'audio/wav' | 'video/mp4' | 'video/webm' | string;
+/**
+ * Attachment metadata and content structure
+ * @interface Attachment
+ */
+export interface Attachment {
+    /** Unique identifier for the attachment */
+    readonly id: string;
+    /** Original filename */
+    readonly name: string;
+    /** MIME type of the attachment */
+    readonly mimeType: AttachmentMimeType;
+    /** File size in bytes */
+    readonly size: number;
+    /** Data URL or storage reference for the attachment content */
+    readonly url: string;
+    /** Optional preview/thumbnail URL for image/video attachments */
+    readonly previewUrl?: string;
+    /** Optional caption or description */
+    readonly caption?: string;
+    /** Timestamp when the attachment was created */
+    readonly createdAt: Date;
+    /** Optional metadata for specific attachment types */
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Message status indicators
+ * @typedef {'pending' | 'sent' | 'delivered' | 'read' | 'error'} MessageStatus
+ */
+export type MessageStatus = 'pending' | 'sent' | 'delivered' | 'read' | 'error';
+/**
+ * Core message structure for all communications
+ * @interface Message
+ */
+export interface Message {
+    /** Unique message identifier */
+    readonly id: string;
+    /** Message role identifying the sender type */
+    readonly role: MessageRole;
+    /** Message content - can be text or structured data */
+    readonly content: string;
+    /** Optional timestamp when the message was created */
+    readonly timestamp?: Date;
+    /** Optional array of file attachments */
+    readonly attachments?: readonly Attachment[];
+    /** Current status of the message delivery */
+    readonly status?: MessageStatus;
+    /** Optional metadata for extended message properties */
+    readonly metadata?: Readonly<Record<string, unknown>>;
+    /** Optional ID of the message this is replying to */
+    readonly replyTo?: string;
+    /** Optional edit history for tracking modifications */
+    readonly edits?: ReadonlyArray<{
+        readonly content: string;
+        readonly timestamp: Date;
+    }>;
+}
+/**
+ * System-specific message with additional metadata
+ * @interface SystemMessage
+ * @extends Message
+ */
+export interface SystemMessage extends Message {
+    readonly role: 'system';
+    /** System message type categorization */
+    readonly systemType: 'notification' | 'error' | 'warning' | 'info' | 'command';
+    /** Optional action button or link */
+    readonly action?: {
+        readonly label: string;
+        readonly handler: string;
+        readonly payload?: unknown;
+    };
+}
+/**
+ * User message with optional context
+ * @interface UserMessage
+ * @extends Message
+ */
+export interface UserMessage extends Message {
+    readonly role: 'user';
+    /** Optional session or conversation context */
+    readonly context?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Assistant/AI response message with optional thinking/reasoning
+ * @interface AssistantMessage
+ * @extends Message
+ */
+export interface AssistantMessage extends Message {
+    readonly role: 'assistant';
+    /** Optional thinking/reasoning process for the response */
+    readonly reasoning?: string;
+    /** Token usage statistics for the response */
+    readonly tokenUsage?: {
+        readonly prompt: number;
+        readonly completion: number;
+        readonly total: number;
+    };
+    /** Model identifier that generated the response */
+    readonly model?: string;
+}
+/**
+ * Union type for all message variants
+ * @typedef {UserMessage | AssistantMessage | SystemMessage} TypedMessage
+ */
+export type TypedMessage = UserMessage | AssistantMessage | SystemMessage;
+/**
+ * Message thread/conversation structure
+ * @interface MessageThread
+ */
+export interface MessageThread {
+    /** Unique thread identifier */
+    readonly id: string;
+    /** Thread title or subject */
+    readonly title?: string;
+    /** Array of messages in the thread */
+    readonly messages: readonly TypedMessage[];
+    /** Thread creation timestamp */
+    readonly createdAt: Date;
+    /** Last activity timestamp */
+    readonly updatedAt: Date;
+    /** Optional metadata for the thread */
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Type guard to check if a message is from a user
+ * @param {Message} message - The message to check
+ * @returns {boolean} True if the message is from a user
+ */
+export declare function isUserMessage(message: Message): message is UserMessage;
+/**
+ * Type guard to check if a message is from the assistant
+ * @param {Message} message - The message to check
+ * @returns {boolean} True if the message is from the assistant
+ */
+export declare function isAssistantMessage(message: Message): message is AssistantMessage;
+/**
+ * Type guard to check if a message is a system message
+ * @param {Message} message - The message to check
+ * @returns {boolean} True if the message is a system message
+ */
+export declare function isSystemMessage(message: Message): message is SystemMessage;
+/**
+ * Type guard to check if a value is a valid MessageRole
+ * @param {unknown} value - The value to check
+ * @returns {boolean} True if the value is a valid MessageRole
+ */
+export declare function isMessageRole(value: unknown): value is MessageRole;
+/**
+ * Creates a new message with proper defaults
+ * @param {Object} params - Message creation parameters
+ * @returns {Message} A new message object
+ */
+export declare function createMessage(params: {
+    role: MessageRole;
+    content: string;
+    attachments?: Attachment[];
+    metadata?: Record<string, unknown>;
+    replyTo?: string;
+}): Message;
+declare const _default: {
+    MESSAGE_ROLES: readonly MessageRole[];
+    isUserMessage: typeof isUserMessage;
+    isAssistantMessage: typeof isAssistantMessage;
+    isSystemMessage: typeof isSystemMessage;
+    isMessageRole: typeof isMessageRole;
+    createMessage: typeof createMessage;
+};
+export default _default;

package/src/types/message.js

@@ -0,0 +1,77 @@
+/**
+ * @fileoverview Message types for gizzi-code integration
+ * @module types/message
+ *
+ * Defines core message interfaces and types used across the application
+ * for chat, notifications, and system communications.
+ */
+/**
+ * Valid message role values for runtime validation
+ * @constant {MessageRole[]}
+ */
+export const MESSAGE_ROLES = ['user', 'assistant', 'system'];
+/**
+ * Type guard to check if a message is from a user
+ * @param {Message} message - The message to check
+ * @returns {boolean} True if the message is from a user
+ */
+export function isUserMessage(message) {
+    return message.role === 'user';
+}
+/**
+ * Type guard to check if a message is from the assistant
+ * @param {Message} message - The message to check
+ * @returns {boolean} True if the message is from the assistant
+ */
+export function isAssistantMessage(message) {
+    return message.role === 'assistant';
+}
+/**
+ * Type guard to check if a message is a system message
+ * @param {Message} message - The message to check
+ * @returns {boolean} True if the message is a system message
+ */
+export function isSystemMessage(message) {
+    return message.role === 'system';
+}
+/**
+ * Type guard to check if a value is a valid MessageRole
+ * @param {unknown} value - The value to check
+ * @returns {boolean} True if the value is a valid MessageRole
+ */
+export function isMessageRole(value) {
+    return typeof value === 'string' && MESSAGE_ROLES.includes(value);
+}
+/**
+ * Creates a new message with proper defaults
+ * @param {Object} params - Message creation parameters
+ * @returns {Message} A new message object
+ */
+export function createMessage(params) {
+    return {
+        id: generateMessageId(),
+        role: params.role,
+        content: params.content,
+        timestamp: new Date(),
+        status: 'pending',
+        ...(params.attachments && { attachments: params.attachments }),
+        ...(params.metadata && { metadata: params.metadata }),
+        ...(params.replyTo && { replyTo: params.replyTo }),
+    };
+}
+/**
+ * Generates a unique message ID
+ * @returns {string} A unique identifier
+ */
+function generateMessageId() {
+    return `msg_${Date.now()}_${Math.random().toString(36).substring(2, 11)}`;
+}
+// Default export for convenient importing
+export default {
+    MESSAGE_ROLES,
+    isUserMessage,
+    isAssistantMessage,
+    isSystemMessage,
+    isMessageRole,
+    createMessage,
+};

package/src/types/message.ts

@@ -0,0 +1,277 @@
+/**
+ * @fileoverview Message types for gizzi-code integration
+ * @module types/message
+ *
+ * Defines core message interfaces and types used across the application
+ * for chat, notifications, and system communications.
+ */
+
+/**
+ * Represents the possible roles a message can have in a conversation
+ * @typedef {'user' | 'assistant' | 'system'} MessageRole
+ */
+export type MessageRole = 'user' | 'assistant' | 'system';
+
+/**
+ * Valid message role values for runtime validation
+ * @constant {MessageRole[]}
+ */
+export const MESSAGE_ROLES: readonly MessageRole[] = ['user', 'assistant', 'system'] as const;
+
+/**
+ * Supported MIME types for message attachments
+ * @typedef {string} AttachmentMimeType
+ */
+export type AttachmentMimeType =
+  | 'image/png'
+  | 'image/jpeg'
+  | 'image/gif'
+  | 'image/webp'
+  | 'image/svg+xml'
+  | 'text/plain'
+  | 'text/markdown'
+  | 'text/html'
+  | 'application/json'
+  | 'application/pdf'
+  | 'application/zip'
+  | 'audio/mpeg'
+  | 'audio/wav'
+  | 'video/mp4'
+  | 'video/webm'
+  | string;
+
+/**
+ * Attachment metadata and content structure
+ * @interface Attachment
+ */
+export interface Attachment {
+  /** Unique identifier for the attachment */
+  readonly id: string;
+
+  /** Original filename */
+  readonly name: string;
+
+  /** MIME type of the attachment */
+  readonly mimeType: AttachmentMimeType;
+
+  /** File size in bytes */
+  readonly size: number;
+
+  /** Data URL or storage reference for the attachment content */
+  readonly url: string;
+
+  /** Optional preview/thumbnail URL for image/video attachments */
+  readonly previewUrl?: string;
+
+  /** Optional caption or description */
+  readonly caption?: string;
+
+  /** Timestamp when the attachment was created */
+  readonly createdAt: Date;
+
+  /** Optional metadata for specific attachment types */
+  readonly metadata?: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * Message status indicators
+ * @typedef {'pending' | 'sent' | 'delivered' | 'read' | 'error'} MessageStatus
+ */
+export type MessageStatus = 'pending' | 'sent' | 'delivered' | 'read' | 'error';
+
+/**
+ * Core message structure for all communications
+ * @interface Message
+ */
+export interface Message {
+  /** Unique message identifier */
+  readonly id: string;
+
+  /** Message role identifying the sender type */
+  readonly role: MessageRole;
+
+  /** Message content - can be text or structured data */
+  readonly content: string;
+
+  /** Optional timestamp when the message was created */
+  readonly timestamp?: Date;
+
+  /** Optional array of file attachments */
+  readonly attachments?: readonly Attachment[];
+
+  /** Current status of the message delivery */
+  readonly status?: MessageStatus;
+
+  /** Optional metadata for extended message properties */
+  readonly metadata?: Readonly<Record<string, unknown>>;
+
+  /** Optional ID of the message this is replying to */
+  readonly replyTo?: string;
+
+  /** Optional edit history for tracking modifications */
+  readonly edits?: ReadonlyArray<{
+    readonly content: string;
+    readonly timestamp: Date;
+  }>;
+}
+
+/**
+ * System-specific message with additional metadata
+ * @interface SystemMessage
+ * @extends Message
+ */
+export interface SystemMessage extends Message {
+  readonly role: 'system';
+
+  /** System message type categorization */
+  readonly systemType: 'notification' | 'error' | 'warning' | 'info' | 'command';
+
+  /** Optional action button or link */
+  readonly action?: {
+    readonly label: string;
+    readonly handler: string;
+    readonly payload?: unknown;
+  };
+}
+
+/**
+ * User message with optional context
+ * @interface UserMessage
+ * @extends Message
+ */
+export interface UserMessage extends Message {
+  readonly role: 'user';
+
+  /** Optional session or conversation context */
+  readonly context?: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * Assistant/AI response message with optional thinking/reasoning
+ * @interface AssistantMessage
+ * @extends Message
+ */
+export interface AssistantMessage extends Message {
+  readonly role: 'assistant';
+
+  /** Optional thinking/reasoning process for the response */
+  readonly reasoning?: string;
+
+  /** Token usage statistics for the response */
+  readonly tokenUsage?: {
+    readonly prompt: number;
+    readonly completion: number;
+    readonly total: number;
+  };
+
+  /** Model identifier that generated the response */
+  readonly model?: string;
+}
+
+/**
+ * Union type for all message variants
+ * @typedef {UserMessage | AssistantMessage | SystemMessage} TypedMessage
+ */
+export type TypedMessage = UserMessage | AssistantMessage | SystemMessage;
+
+/**
+ * Message thread/conversation structure
+ * @interface MessageThread
+ */
+export interface MessageThread {
+  /** Unique thread identifier */
+  readonly id: string;
+
+  /** Thread title or subject */
+  readonly title?: string;
+
+  /** Array of messages in the thread */
+  readonly messages: readonly TypedMessage[];
+
+  /** Thread creation timestamp */
+  readonly createdAt: Date;
+
+  /** Last activity timestamp */
+  readonly updatedAt: Date;
+
+  /** Optional metadata for the thread */
+  readonly metadata?: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * Type guard to check if a message is from a user
+ * @param {Message} message - The message to check
+ * @returns {boolean} True if the message is from a user
+ */
+export function isUserMessage(message: Message): message is UserMessage {
+  return message.role === 'user';
+}
+
+/**
+ * Type guard to check if a message is from the assistant
+ * @param {Message} message - The message to check
+ * @returns {boolean} True if the message is from the assistant
+ */
+export function isAssistantMessage(message: Message): message is AssistantMessage {
+  return message.role === 'assistant';
+}
+
+/**
+ * Type guard to check if a message is a system message
+ * @param {Message} message - The message to check
+ * @returns {boolean} True if the message is a system message
+ */
+export function isSystemMessage(message: Message): message is SystemMessage {
+  return message.role === 'system';
+}
+
+/**
+ * Type guard to check if a value is a valid MessageRole
+ * @param {unknown} value - The value to check
+ * @returns {boolean} True if the value is a valid MessageRole
+ */
+export function isMessageRole(value: unknown): value is MessageRole {
+  return typeof value === 'string' && MESSAGE_ROLES.includes(value as MessageRole);
+}
+
+/**
+ * Creates a new message with proper defaults
+ * @param {Object} params - Message creation parameters
+ * @returns {Message} A new message object
+ */
+export function createMessage(params: {
+  role: MessageRole;
+  content: string;
+  attachments?: Attachment[];
+  metadata?: Record<string, unknown>;
+  replyTo?: string;
+}): Message {
+  return {
+    id: generateMessageId(),
+    role: params.role,
+    content: params.content,
+    timestamp: new Date(),
+    status: 'pending',
+    ...(params.attachments && { attachments: params.attachments }),
+    ...(params.metadata && { metadata: params.metadata }),
+    ...(params.replyTo && { replyTo: params.replyTo }),
+  };
+}
+
+/**
+ * Generates a unique message ID
+ * @returns {string} A unique identifier
+ */
+function generateMessageId(): string {
+  return `msg_${Date.now()}_${Math.random().toString(36).substring(2, 11)}`;
+}
+
+// Default export for convenient importing
+export default {
+  MESSAGE_ROLES,
+  isUserMessage,
+  isAssistantMessage,
+  isSystemMessage,
+  isMessageRole,
+  createMessage,
+};

package/src/utils/format.d.ts

@@ -0,0 +1,126 @@
+/**
+ * @fileoverview Format utilities for gizzi-code integration
+ * @module utils/format
+ *
+ * Provides formatting utilities for durations, byte sizes, and numbers.
+ * These functions are commonly used in CLI output and display components.
+ */
+/**
+ * Number format options
+ * @interface NumberFormatOptions
+ */
+export interface NumberFormatOptions {
+    /** Minimum number of decimal places */
+    readonly minimumFractionDigits?: number;
+    /** Maximum number of decimal places */
+    readonly maximumFractionDigits?: number;
+    /** Use thousands separator */
+    readonly useGrouping?: boolean;
+    /** Locale for formatting (default: 'en-US') */
+    readonly locale?: string;
+}
+/**
+ * Duration format options
+ * @interface DurationFormatOptions
+ */
+export interface DurationFormatOptions {
+    /** Format style (default: 'auto') */
+    readonly style?: 'short' | 'long' | 'narrow' | 'auto';
+    /** Maximum number of units to display (default: 2) */
+    readonly maxUnits?: number;
+    /** Include milliseconds in output */
+    readonly includeMs?: boolean;
+    /** Round to nearest unit */
+    readonly round?: boolean;
+}
+/**
+ * Byte format options
+ * @interface ByteFormatOptions
+ */
+export interface ByteFormatOptions {
+    /** Number of decimal places (default: 2) */
+    readonly decimals?: number;
+    /** Use binary units (KiB, MiB) instead of decimal (KB, MB) */
+    readonly binary?: boolean;
+    /** Include space between value and unit */
+    readonly space?: boolean;
+}
+/**
+ * Formats a duration in milliseconds to a human-readable string
+ *
+ * @param {number} ms - Duration in milliseconds
+ * @param {DurationFormatOptions} [options] - Format options
+ * @returns {string} Formatted duration string
+ * @example
+ * ```typescript
+ * formatDuration(5000); // "5s"
+ * formatDuration(65000); // "1m 5s"
+ * formatDuration(3600000); // "1h"
+ * formatDuration(90000, { style: 'long' }); // "1 minute 30 seconds"
+ * ```
+ */
+export declare function formatDuration(ms: number, options?: DurationFormatOptions): string;
+/**
+ * Formats a byte size to a human-readable string
+ *
+ * @param {number} bytes - Size in bytes
+ * @param {ByteFormatOptions} [options] - Format options
+ * @returns {string} Formatted size string
+ * @example
+ * ```typescript
+ * formatBytes(1024); // "1 KB"
+ * formatBytes(1536); // "1.50 KB"
+ * formatBytes(1048576); // "1 MB"
+ * formatBytes(1024, { binary: true }); // "1 KiB"
+ * ```
+ */
+export declare function formatBytes(bytes: number, options?: ByteFormatOptions): string;
+/**
+ * Formats a number with locale-aware formatting
+ *
+ * @param {number} num - Number to format
+ * @param {NumberFormatOptions} [options] - Format options
+ * @returns {string} Formatted number string
+ * @example
+ * ```typescript
+ * formatNumber(1234567); // "1,234,567"
+ * formatNumber(1234.5678, { maximumFractionDigits: 2 }); // "1,234.57"
+ * formatNumber(0.001234, { minimumFractionDigits: 6 }); // "0.001234"
+ * ```
+ */
+export declare function formatNumber(num: number, options?: NumberFormatOptions): string;
+/**
+ * Formats a number as a percentage
+ *
+ * @param {number} value - Value to format (0.5 = 50%)
+ * @param {number} [decimals=1] - Number of decimal places
+ * @returns {string} Formatted percentage string
+ * @example
+ * ```typescript
+ * formatPercentage(0.5); // "50%"
+ * formatPercentage(0.1234, 2); // "12.34%"
+ * ```
+ */
+export declare function formatPercentage(value: number, decimals?: number): string;
+/**
+ * Formats a number as compact notation (1K, 1M, etc.)
+ *
+ * @param {number} num - Number to format
+ * @param {number} [decimals=1] - Number of decimal places
+ * @returns {string} Compact formatted string
+ * @example
+ * ```typescript
+ * formatCompact(1234); // "1.2K"
+ * formatCompact(1000000); // "1M"
+ * formatCompact(1234567890); // "1.2B"
+ * ```
+ */
+export declare function formatCompact(num: number, decimals?: number): string;
+declare const _default: {
+    formatDuration: typeof formatDuration;
+    formatBytes: typeof formatBytes;
+    formatNumber: typeof formatNumber;
+    formatPercentage: typeof formatPercentage;
+    formatCompact: typeof formatCompact;
+};
+export default _default;