export type ClientPlatform = 'ios' | 'android';

export type CommandEnvelope =
  | 'message-field'
  | 'top-level'
  | 'command-alias'
  | 'empty'
  | 'init-only';

export type FieldType = 'string' | 'number' | 'boolean' | 'object';

export interface FieldSpec {
  type: FieldType;
  optional?: boolean;
}

export type PayloadVariant =
  | { kind: 'empty' }
  | { kind: 'string'; description: string }
  | { kind: 'number'; description?: string }
  | { kind: 'object'; fields: Record<string, FieldSpec>; required?: string[] };

export interface ResponseContract {
  type: string;
  fields?: Record<string, FieldType>;
  optional?: boolean;
}

export interface CommandContract {
  direction: 'client-to-server' | 'server-to-client';
  envelope: CommandEnvelope;
  payloads: PayloadVariant[];
  responses?: ResponseContract[];
  clients: ClientPlatform[];
  flags?: ('legacy' | 'dev-only' | 'init-only')[];
  semanticNote?: string;
  /** Keys accepted by resolvePayloadId / resolvePayloadField for this command */
  idKeys?: string[];
}

export type CommandManifest = Record<string, CommandContract>;