// Generated from types/*.ts — do not edit.
// Regenerate with: npm run generate:typescript

/**
 * Automation Catalogue Channel Actions — mutations of the
 * `ahp-automations://` catalogue.
 *
 * @module channels-automation/actions
 */

import { ActionType } from '../common/actions.js';
import type { Message } from '../channels-chat/state.js';
import type { URI } from '../common/state.js';
import type {
  AutomationDefinition,
  AutomationEntry,
  AutomationOperation,
  AutomationSessionTemplate,
  AutomationState,
  AutomationTrigger,
} from './state.js';

/**
 * Partial replacement of editable {@link AutomationDefinition} fields.
 *
 * Omitted fields are unchanged. Supplied arrays and objects replace their
 * corresponding values in full; they are not merged recursively.
 *
 * @category Automation Actions
 */
export interface AutomationDefinitionPatch {
  /** Replacement {@link AutomationDefinition.title}. */
  title?: string;
  /** Replacement {@link AutomationDefinition.message}. */
  message?: Message;
  /**
   * Replacement {@link AutomationDefinition.session}. The host revalidates
   * affected event triggers when their discovery context changes.
   */
  session?: AutomationSessionTemplate;
  /** Replacement {@link AutomationDefinition.enabled}. */
  enabled?: boolean;
  /**
   * Complete replacement {@link AutomationDefinition.triggers}. The host
   * validates event ids and normalizes event-trigger titles and descriptions.
   */
  triggers?: AutomationTrigger[];
  /** Complete replacement {@link AutomationDefinition._meta}. */
  _meta?: Record<string, unknown>;
}

/**
 * Ask the host to create a durable automation at a client-chosen resource.
 *
 * Clients may dispatch this action only when the host advertises its `create`
 * automation capability. {@link AutomationCreateRequestedAction.resource |
 * `resource`} MUST use the `ahp-automation:` scheme and MUST NOT already
 * identify an unrelated automation.
 *
 * This side-effect request leaves optimistic catalogue state unchanged. The
 * host validates trigger ids and configuration, normalizes event-trigger
 * titles and descriptions, persists the definition, then publishes the
 * authoritative result with {@link AutomationSetAction | `automation/set`}.
 * Rejections leave the catalogue unchanged.
 *
 * @category Automation Actions
 * @version 1
 * @clientDispatchable
 */
export interface AutomationCreateRequestedAction {
  type: ActionType.AutomationCreateRequested;
  /** Client-chosen `ahp-automation:` URI that becomes {@link AutomationEntry.resource}. */
  resource: URI;
  /** Complete initial {@link AutomationEntry.definition}. */
  definition: AutomationDefinition;
}

/**
 * Ask the host to update editable fields of an existing automation.
 *
 * Clients may dispatch this action only while the target advertises
 * {@link AutomationOperation.Update}. The host revalidates that operation and
 * the client's authorization.
 *
 * This side-effect request leaves optimistic catalogue state unchanged. The
 * host applies accepted patches to its current authoritative definition in
 * action order, revalidates and normalizes affected event triggers, then
 * publishes the result with
 * {@link AutomationSetAction | `automation/set`}. Omitted fields remain
 * unchanged; when accepted actions replace the same field, the later action in
 * server order wins.
 *
 * @category Automation Actions
 * @version 1
 * @clientDispatchable
 */
export interface AutomationUpdateRequestedAction {
  type: ActionType.AutomationUpdateRequested;
  /** Target {@link AutomationEntry.resource}. */
  resource: URI;
  /** Editable {@link AutomationDefinition} fields to replace. */
  changes: AutomationDefinitionPatch;
}

/**
 * Add or replace one full automation state in
 * {@link AutomationState.entries}.
 *
 * Existing entries are matched by {@link AutomationEntry.resource} and
 * replaced in place. A previously unseen resource is appended.
 *
 * @category Automation Actions
 * @version 1
 */
export interface AutomationSetAction {
  type: ActionType.AutomationSet;
  /** Full new or replacement automation state. */
  automation: AutomationEntry;
}

/**
 * Remove one automation from {@link AutomationState.entries}.
 *
 * Clients may dispatch this action only while the target advertises
 * {@link AutomationOperation.Remove}. The host revalidates that operation
 * before permanently deleting the automation. A rejected action leaves the
 * authoritative catalogue and durable definition unchanged.
 *
 * Removing an unknown resource is a no-op.
 *
 * @category Automation Actions
 * @version 1
 * @clientDispatchable
 */
export interface AutomationRemovedAction {
  type: ActionType.AutomationRemoved;
  /** {@link AutomationEntry.resource} to remove. */
  resource: URI;
}