MessageOptions.java

/*---------------------------------------------------------------------------------------------
 *  Copyright (c) Microsoft Corporation. All rights reserved.
 *--------------------------------------------------------------------------------------------*/

package com.github.copilot.sdk.json;

import java.util.ArrayList;
import java.util.Collections;
import java.util.List;

import com.fasterxml.jackson.annotation.JsonInclude;

/**
 * Options for sending a message to a Copilot session.
 * <p>
 * This class specifies the message content and optional attachments to send to
 * the assistant. All setter methods return {@code this} for method chaining.
 *
 * <h2>Example Usage</h2>
 *
 * <pre>{@code
 * var options = new MessageOptions().setPrompt("Explain this code")
 * 		.setAttachments(List.of(new Attachment("file", "/path/to/file.java", null)));
 *
 * session.send(options).get();
 * }</pre>
 *
 * <h2>Blob Attachment Example</h2>
 *
 * <pre>{@code
 * var options = new MessageOptions().setPrompt("Describe this image").setAttachments(List.of(new BlobAttachment()
 * 		.setData("iVBORw0KGgoAAAANSUhEUg...").setMimeType("image/png").setDisplayName("screenshot.png")));
 *
 * session.send(options).get();
 * }</pre>
 *
 * @see com.github.copilot.sdk.CopilotSession#send(MessageOptions)
 * @since 1.0.0
 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public class MessageOptions {

    private String prompt;
    private List<MessageAttachment> attachments;
    private String mode;

    /**
     * Gets the message prompt.
     *
     * @return the prompt text
     */
    public String getPrompt() {
        return prompt;
    }

    /**
     * Sets the message prompt to send to the assistant.
     *
     * @param prompt
     *            the message text
     * @return this options instance for method chaining
     */
    public MessageOptions setPrompt(String prompt) {
        this.prompt = prompt;
        return this;
    }

    /**
     * Gets the attachments.
     *
     * @return the list of attachments
     */
    public List<MessageAttachment> getAttachments() {
        return attachments == null ? null : Collections.unmodifiableList(attachments);
    }

    /**
     * Sets attachments to include with the message.
     * <p>
     * Attachments provide additional context to the assistant. Supported types:
     * <ul>
     * <li>{@link Attachment} — file, directory, code selection, or GitHub
     * reference</li>
     * <li>{@link BlobAttachment} — inline base64-encoded binary data (e.g. images)
     * </li>
     * </ul>
     *
     * @param attachments
     *            the list of attachments
     * @return this options instance for method chaining
     * @see Attachment
     * @see BlobAttachment
     */
    public MessageOptions setAttachments(List<? extends MessageAttachment> attachments) {
        this.attachments = attachments != null ? new ArrayList<>(attachments) : null;
        return this;
    }

    /**
     * Sets the message delivery mode.
     * <p>
     * Valid modes:
     * <ul>
     * <li>"enqueue" - Queue the message for processing (default)</li>
     * <li>"immediate" - Process the message immediately</li>
     * </ul>
     *
     * @param mode
     *            the delivery mode
     * @return this options instance for method chaining
     */
    public MessageOptions setMode(String mode) {
        this.mode = mode;
        return this;
    }

    /**
     * Gets the delivery mode.
     *
     * @return the delivery mode
     */
    public String getMode() {
        return mode;
    }

    /**
     * Creates a shallow clone of this {@code MessageOptions} instance.
     * <p>
     * Mutable collection properties are copied into new collection instances so
     * that modifications to those collections on the clone do not affect the
     * original. Other reference-type properties (like attachment items) are not
     * deep-cloned; the original and the clone will share those objects.
     *
     * @return a clone of this options instance
     */
    @Override
    public MessageOptions clone() {
        MessageOptions copy = new MessageOptions();
        copy.prompt = this.prompt;
        copy.attachments = this.attachments != null ? new ArrayList<>(this.attachments) : null;
        copy.mode = this.mode;
        return copy;
    }

}