/**
 * March Agent SDK - Artifact Structural Streamer
 * Port of Python march_agent/structural/artifact.py
 *
 * Artifact structural streamer for file/image/iframe artifacts.
 */

import { StructuralStreamer, generateShortId } from './base.js'

/**
 * Manages artifact lifecycle: generating -> done.
 *
 * Artifacts are files, images, iframes that are generated and displayed.
 * Artifact data is persisted to database on done().
 *
 * @example
 * ```typescript
 * const artifact = new Artifact()  // ID auto-generated
 * s.streamBy(artifact).generating("Creating chart...", 0.5)
 * s.streamBy(artifact).done({
 *     url: "https://example.com/chart.png",
 *     type: "image",
 *     title: "Sales Chart"
 * })
 * ```
 */
export class Artifact extends StructuralStreamer {
    protected _generateId(): string {
        return `artifact-${generateShortId()}`
    }

    getEventTypePrefix(): string {
        return 'artifact'
    }

    /**
     * Signal artifact is being generated.
     *
     * @param message - Status message (e.g., "Creating chart...")
     * @param progress - Progress value 0.0-1.0
     * @returns this for method chaining
     */
    generating(message?: string, progress?: number): this {
        const data: Record<string, unknown> = {}
        if (message !== undefined) {
            data.message = message
        }
        if (progress !== undefined) {
            data.progress = progress
        }
        return this._sendEvent('generating', data)
    }

    /**
     * Signal artifact is complete and persist to database.
     *
     * @param options - Artifact completion options
     * @param options.url - URL to artifact
     * @param options.type - Artifact type (image, iframe, document, video, audio, code, link, file)
     * @param options.title - Display title
     * @param options.description - Optional description
     * @param options.metadata - Additional metadata (size, mimeType, dimensions, etc.)
     * @returns this for method chaining
     */
    done(options: {
        url: string
        type: string
        title?: string
        description?: string
        metadata?: Record<string, unknown>
    }): this {
        const data: Record<string, unknown> = {
            url: options.url,
            type: options.type,
        }
        if (options.title) {
            data.title = options.title
        }
        if (options.description) {
            data.description = options.description
        }
        if (options.metadata) {
            data.metadata = options.metadata
        }
        return this._sendEvent('done', data)
    }

    /**
     * Signal artifact generation failed.
     *
     * @param message - Error message
     * @returns this for method chaining
     */
    error(message: string): this {
        return this._sendEvent('error', { message })
    }
}