operations.go

// GENERATED by sdk/build.py from openapi.json v1.13.1 — do not edit by hand.

package mindupload

import (
	"context"
	"errors"
	"math/rand"
	"time"
)

// CreateCloneParams holds the parameters for CreateClone.
type CreateCloneParams struct {
	// PreferredLanguage BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages.
	PreferredLanguage string `json:"preferred_language,omitempty"`
	// Username The end-user's username.
	Username string `json:"username,omitempty"`
	// Password The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage.
	Password                         string `json:"password,omitempty"`
	Codename                         string `json:"codename,omitempty"`
	Nickname                         string `json:"nickname,omitempty"`
	Gender                           string `json:"gender,omitempty"`
	AvatarID                         string `json:"avatar_id,omitempty"`
	AcceptChatroomInvitationByOthers *bool  `json:"accept_chatroom_invitation_by_others,omitempty"`
	ReinforcementLearning            *bool  `json:"reinforcement_learning,omitempty"`
}

// GetClonesParams holds the parameters for GetClones.
type GetClonesParams struct {
	// PreferredLanguage BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages.
	PreferredLanguage string `json:"preferred_language,omitempty"`
	// Username The end-user's username.
	Username string `json:"username,omitempty"`
	// Password The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage.
	Password string `json:"password,omitempty"`
}

// UpdateCloneParams holds the parameters for UpdateClone.
type UpdateCloneParams struct {
	// PreferredLanguage BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages.
	PreferredLanguage string `json:"preferred_language,omitempty"`
	// Username The end-user's username.
	Username string `json:"username,omitempty"`
	// Password The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage.
	Password                         string `json:"password,omitempty"`
	Codename                         string `json:"codename,omitempty"`
	Nickname                         string `json:"nickname,omitempty"`
	Gender                           string `json:"gender,omitempty"`
	AvatarID                         string `json:"avatar_id,omitempty"`
	AcceptChatroomInvitationByOthers *bool  `json:"accept_chatroom_invitation_by_others,omitempty"`
	AutoKeepExternalMemories         *bool  `json:"auto_keep_external_memories,omitempty"`
	ReinforcementLearning            *bool  `json:"reinforcement_learning,omitempty"`
}

// GetQuotaParams holds the parameters for GetQuota.
type GetQuotaParams struct {
	// PreferredLanguage BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages.
	PreferredLanguage string `json:"preferred_language,omitempty"`
	// Username The end-user's username.
	Username string `json:"username,omitempty"`
}

// CheckUsernameParams holds the parameters for CheckUsername.
type CheckUsernameParams struct {
	// PreferredLanguage BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages.
	PreferredLanguage string `json:"preferred_language,omitempty"`
	// Username The end-user's username.
	Username string `json:"username,omitempty"`
}

// LoginParams holds the parameters for Login.
type LoginParams struct {
	// PreferredLanguage BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages.
	PreferredLanguage string `json:"preferred_language,omitempty"`
	// Username The end-user's username.
	Username string `json:"username,omitempty"`
	// Password The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage.
	Password string `json:"password,omitempty"`
}

// LogoutParams holds the parameters for Logout.
type LogoutParams struct {
	// PreferredLanguage BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages.
	PreferredLanguage string `json:"preferred_language,omitempty"`
	// Username The end-user's username.
	Username string `json:"username,omitempty"`
	// Password The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage.
	Password string `json:"password,omitempty"`
}

// RegisterParams holds the parameters for Register.
type RegisterParams struct {
	// PreferredLanguage BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages.
	PreferredLanguage string `json:"preferred_language,omitempty"`
	// Username The end-user's username.
	Username string `json:"username,omitempty"`
	// Password The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage.
	Password                         string `json:"password,omitempty"`
	Email                            string `json:"email,omitempty"`
	EmailVerificationCode            string `json:"email_verification_code,omitempty"`
	FirstName                        string `json:"first_name,omitempty"`
	LastName                         string `json:"last_name,omitempty"`
	Nickname                         string `json:"nickname,omitempty"`
	Gender                           string `json:"gender,omitempty"`
	BirthDate                        *int64 `json:"birth_date,omitempty"`
	PhoneNumber                      string `json:"phone_number,omitempty"`
	AvatarID                         string `json:"avatar_id,omitempty"`
	AcceptChatroomInvitationByOthers *bool  `json:"accept_chatroom_invitation_by_others,omitempty"`
}

// CheckChatroomUpdatesParams holds the parameters for CheckChatroomUpdates.
type CheckChatroomUpdatesParams struct {
	// PreferredLanguage BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages.
	PreferredLanguage string `json:"preferred_language,omitempty"`
	// Username The end-user's username.
	Username string `json:"username,omitempty"`
	// Password The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage.
	Password string `json:"password,omitempty"`
	// Chatrooms Rooms to check. Each entry must include `chatroom_id`; include `known_updated_at` from the previous response, or null/omit it on the first poll.
	Chatrooms []map[string]any `json:"chatrooms,omitempty"`
}

// CreateChatroomParams holds the parameters for CreateChatroom.
type CreateChatroomParams struct {
	// PreferredLanguage BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages.
	PreferredLanguage string `json:"preferred_language,omitempty"`
	// Username The end-user's username.
	Username string `json:"username,omitempty"`
	// Password The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage.
	Password             string `json:"password,omitempty"`
	ChatroomName         string `json:"chatroom_name,omitempty"`
	IsPublic             *bool  `json:"is_public,omitempty"`
	AvatarID             string `json:"avatar_id,omitempty"`
	SoulmateCheckEnabled *bool  `json:"soulmate_check_enabled,omitempty"`
}

// CreateChatroomMembershipParams holds the parameters for CreateChatroomMembership.
type CreateChatroomMembershipParams struct {
	// PreferredLanguage BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages.
	PreferredLanguage string `json:"preferred_language,omitempty"`
	// Username The end-user's username.
	Username string `json:"username,omitempty"`
	// Password The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage.
	Password string `json:"password,omitempty"`
	// ChatroomID Chatroom id as returned by chatroom operations.
	ChatroomID      string `json:"chatroom_id,omitempty"`
	InviteeUsername string `json:"invitee_username,omitempty"`
	InviteeCodename string `json:"invitee_codename,omitempty"`
	AdminLevel      string `json:"admin_level,omitempty"`
}

// CreateChatroomMessageParams holds the parameters for CreateChatroomMessage.
type CreateChatroomMessageParams struct {
	// PreferredLanguage BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages.
	PreferredLanguage string `json:"preferred_language,omitempty"`
	// Username The end-user's username.
	Username string `json:"username,omitempty"`
	// Password The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage.
	Password string `json:"password,omitempty"`
	// ChatroomID Chatroom id as returned by chatroom operations.
	ChatroomID string `json:"chatroom_id,omitempty"`
	Text       string `json:"text,omitempty"`
}

// GetChatroomMembershipParams holds the parameters for GetChatroomMembership.
type GetChatroomMembershipParams struct {
	// PreferredLanguage BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages.
	PreferredLanguage string `json:"preferred_language,omitempty"`
	Page              *int64 `json:"page,omitempty"`
	// PageSize Maximum records requested for one server-capped page.
	PageSize *int64 `json:"page_size,omitempty"`
	SortBy   string `json:"sort_by,omitempty"`
	// SortOrder Sort direction; supported values depend on the operation.
	SortOrder           *int64 `json:"sort_order,omitempty"`
	UseCursorPagination *bool  `json:"use_cursor_pagination,omitempty"`
	// CursorValue Opaque pagination cursor value from the previous page (`next_cursor_value`).
	CursorValue string `json:"cursor_value,omitempty"`
	// CursorID Opaque pagination cursor id from the previous page (`next_cursor_id`).
	CursorID string `json:"cursor_id,omitempty"`
	// Username The end-user's username.
	Username string `json:"username,omitempty"`
	// Password The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage.
	Password string `json:"password,omitempty"`
	// ChatroomID Chatroom id as returned by chatroom operations.
	ChatroomID string `json:"chatroom_id,omitempty"`
}

// GetChatroomMessagesParams holds the parameters for GetChatroomMessages.
type GetChatroomMessagesParams struct {
	// PreferredLanguage BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages.
	PreferredLanguage string `json:"preferred_language,omitempty"`
	Page              *int64 `json:"page,omitempty"`
	// PageSize Maximum records requested for one server-capped page.
	PageSize *int64 `json:"page_size,omitempty"`
	SortBy   string `json:"sort_by,omitempty"`
	// SortOrder Sort direction; supported values depend on the operation.
	SortOrder           *int64 `json:"sort_order,omitempty"`
	UseCursorPagination *bool  `json:"use_cursor_pagination,omitempty"`
	// CursorValue Opaque pagination cursor value from the previous page (`next_cursor_value`).
	CursorValue string `json:"cursor_value,omitempty"`
	// CursorID Opaque pagination cursor id from the previous page (`next_cursor_id`).
	CursorID string `json:"cursor_id,omitempty"`
	// Username The end-user's username.
	Username string `json:"username,omitempty"`
	// Password The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage.
	Password string `json:"password,omitempty"`
	// ChatroomID Chatroom id as returned by chatroom operations.
	ChatroomID string   `json:"chatroom_id,omitempty"`
	SinceValue *float64 `json:"since_value,omitempty"`
	SinceID    string   `json:"since_id,omitempty"`
}

// GetChatroomMessagesAroundParams holds the parameters for GetChatroomMessagesAround.
type GetChatroomMessagesAroundParams struct {
	// PreferredLanguage BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages.
	PreferredLanguage string `json:"preferred_language,omitempty"`
	// Username The end-user's username.
	Username string `json:"username"`
	// Password The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage.
	Password string `json:"password"`
	// ChatroomID Chatroom id as returned by chatroom operations.
	ChatroomID string `json:"chatroom_id"`
	// MessageID Chatroom message id.
	MessageID string `json:"message_id"`
	// Before How many earlier neighbors to include around the anchor id.
	Before *int64 `json:"before,omitempty"`
	// After How many later neighbors to include around the anchor id.
	After *int64 `json:"after,omitempty"`
}

// GetChatroomsParams holds the parameters for GetChatrooms.
type GetChatroomsParams struct {
	// PreferredLanguage BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages.
	PreferredLanguage string `json:"preferred_language,omitempty"`
	Page              *int64 `json:"page,omitempty"`
	// PageSize Maximum records requested for one server-capped page.
	PageSize *int64 `json:"page_size,omitempty"`
	SortBy   string `json:"sort_by,omitempty"`
	// SortOrder Sort direction; supported values depend on the operation.
	SortOrder           *int64 `json:"sort_order,omitempty"`
	UseCursorPagination *bool  `json:"use_cursor_pagination,omitempty"`
	// CursorValue Opaque pagination cursor value from the previous page (`next_cursor_value`).
	CursorValue string `json:"cursor_value,omitempty"`
	// CursorID Opaque pagination cursor id from the previous page (`next_cursor_id`).
	CursorID string `json:"cursor_id,omitempty"`
	// Username The end-user's username.
	Username string `json:"username,omitempty"`
	// Password The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage.
	Password   string `json:"password,omitempty"`
	GetPublic  *bool  `json:"get_public,omitempty"`
	GetPrivate *bool  `json:"get_private,omitempty"`
}

// SearchChatroomMessagesParams holds the parameters for SearchChatroomMessages.
type SearchChatroomMessagesParams struct {
	// PreferredLanguage BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages.
	PreferredLanguage string `json:"preferred_language,omitempty"`
	// Username The end-user's username.
	Username string `json:"username"`
	// Password The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage.
	Password string `json:"password"`
	// ChatroomID Chatroom id as returned by chatroom operations.
	ChatroomID string `json:"chatroom_id"`
	// Keyword Optional find query. Whole-word tokens across alphabetic and numeric scripts; character phrases for Chinese / Japanese / Korean; mixed language supported.
	Keyword string `json:"keyword,omitempty"`
	// ContentMediaTypes Optional list of media kinds to match: `image`, `video`, and/or `audio`.
	ContentMediaTypes []string `json:"content_media_types,omitempty"`
	// CreatedAfter Optional lower bound on message time as a UNIX timestamp in seconds.
	CreatedAfter *int64 `json:"created_after,omitempty"`
	// CreatedBefore Optional upper bound on message time as a UNIX timestamp in seconds.
	CreatedBefore *int64 `json:"created_before,omitempty"`
	// SortOrder Message send-time order: `-1` newest first (default), `1` oldest first.
	SortOrder *int64 `json:"sort_order,omitempty"`
	// SenderUserID Optional human member id; only messages from that user match. Mutually exclusive with `sender_clone_id`.
	SenderUserID string `json:"sender_user_id,omitempty"`
	// SenderCloneID Optional AI member id; only messages from that AI match. Mutually exclusive with `sender_user_id`.
	SenderCloneID string `json:"sender_clone_id,omitempty"`
	// PageSize Maximum Find hits for one page.
	PageSize *int64 `json:"page_size,omitempty"`
	// CursorValue Opaque pagination cursor value from the previous page (`next_cursor_value`).
	CursorValue *float64 `json:"cursor_value,omitempty"`
	// CursorID Opaque pagination cursor id from the previous page (`next_cursor_id`).
	CursorID string `json:"cursor_id,omitempty"`
}

// TranslateChatroomMessageParams holds the parameters for TranslateChatroomMessage.
type TranslateChatroomMessageParams struct {
	// PreferredLanguage BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages.
	PreferredLanguage string `json:"preferred_language,omitempty"`
	// Username The end-user's username.
	Username string `json:"username,omitempty"`
	// Password The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage.
	Password string `json:"password,omitempty"`
	// ChatroomID Chatroom id as returned by chatroom operations.
	ChatroomID string `json:"chatroom_id,omitempty"`
	// MessageID Chatroom message id.
	MessageID string `json:"message_id,omitempty"`
}

// GetChatParams holds the parameters for GetChat.
type GetChatParams struct {
	// PreferredLanguage BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages.
	PreferredLanguage string `json:"preferred_language,omitempty"`
	Page              *int64 `json:"page,omitempty"`
	// PageSize Maximum records requested for one server-capped page.
	PageSize *int64 `json:"page_size,omitempty"`
	SortBy   string `json:"sort_by,omitempty"`
	// SortOrder Sort direction; supported values depend on the operation.
	SortOrder           *int64 `json:"sort_order,omitempty"`
	UseCursorPagination *bool  `json:"use_cursor_pagination,omitempty"`
	// CursorValue Opaque pagination cursor value from the previous page (`next_cursor_value`).
	CursorValue string `json:"cursor_value,omitempty"`
	// CursorID Opaque pagination cursor id from the previous page (`next_cursor_id`).
	CursorID string `json:"cursor_id,omitempty"`
	// Username The end-user's username.
	Username string `json:"username,omitempty"`
	// Password The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage.
	Password string `json:"password,omitempty"`
	Codename string `json:"codename,omitempty"`
}

// GetChatAroundParams holds the parameters for GetChatAround.
type GetChatAroundParams struct {
	// PreferredLanguage BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages.
	PreferredLanguage string `json:"preferred_language,omitempty"`
	// Username The end-user's username.
	Username string `json:"username"`
	// Password The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage.
	Password string `json:"password"`
	// CloneID Owner AI consciousness id from `get_clones` (required for one-on-one jump).
	CloneID string `json:"clone_id"`
	// ChatID One-on-one chat turn id.
	ChatID string `json:"chat_id"`
	// Before How many earlier neighbors to include around the anchor id.
	Before *int64 `json:"before,omitempty"`
	// After How many later neighbors to include around the anchor id.
	After *int64 `json:"after,omitempty"`
}

// RagParams holds the parameters for Rag.
type RagParams struct {
	// PreferredLanguage BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages.
	PreferredLanguage string `json:"preferred_language,omitempty"`
	// Username The end-user's username.
	Username string `json:"username,omitempty"`
	// Password The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage.
	Password string `json:"password,omitempty"`
	Codename string `json:"codename,omitempty"`
	Text     string `json:"text,omitempty"`
	// ChatroomID Chatroom id as returned by chatroom operations.
	ChatroomID string `json:"chatroom_id,omitempty"`
}

// SearchChatsParams holds the parameters for SearchChats.
type SearchChatsParams struct {
	// PreferredLanguage BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages.
	PreferredLanguage string `json:"preferred_language,omitempty"`
	// Username The end-user's username.
	Username string `json:"username"`
	// Password The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage.
	Password string `json:"password"`
	// CloneID Owner AI consciousness id from `get_clones` (required for one-on-one find).
	CloneID string `json:"clone_id"`
	// Keyword Optional find query. Whole-word tokens across alphabetic and numeric scripts; character phrases for Chinese / Japanese / Korean; mixed language supported.
	Keyword string `json:"keyword,omitempty"`
	// ContentMediaTypes Optional list of media kinds to match: `image`, `video`, and/or `audio`.
	ContentMediaTypes []string `json:"content_media_types,omitempty"`
	// CreatedAfter Optional lower bound on message time as a UNIX timestamp in seconds.
	CreatedAfter *int64 `json:"created_after,omitempty"`
	// CreatedBefore Optional upper bound on message time as a UNIX timestamp in seconds.
	CreatedBefore *int64 `json:"created_before,omitempty"`
	// SortOrder Turn send-time order: `-1` newest first (default), `1` oldest first.
	SortOrder *int64 `json:"sort_order,omitempty"`
	// Side Optional 1v1 side filter: `user` (human), `assistant` (AI), or `both` (turns that include both sides).
	Side string `json:"side,omitempty"`
	// PageSize Maximum Find hits for one page.
	PageSize *int64 `json:"page_size,omitempty"`
	// CursorValue Opaque pagination cursor value from the previous page (`next_cursor_value`).
	CursorValue *float64 `json:"cursor_value,omitempty"`
	// CursorID Opaque pagination cursor id from the previous page (`next_cursor_id`).
	CursorID string `json:"cursor_id,omitempty"`
}

// TriggerSocialParams holds the parameters for TriggerSocial.
type TriggerSocialParams struct {
	// PreferredLanguage BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages.
	PreferredLanguage string `json:"preferred_language,omitempty"`
	// Username The end-user's username.
	Username string `json:"username,omitempty"`
	// Password The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage.
	Password     string `json:"password,omitempty"`
	MembershipID string `json:"membership_id,omitempty"`
	// ChatroomID Chatroom id as returned by chatroom operations.
	ChatroomID string `json:"chatroom_id,omitempty"`
}

// CreateExternalAuthorizationRequestParams holds the parameters for CreateExternalAuthorizationRequest.
type CreateExternalAuthorizationRequestParams struct {
	// PreferredLanguage BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages.
	PreferredLanguage string `json:"preferred_language,omitempty"`
	// IdempotencyKey A stable opaque event key that makes exact retries return the same outcome.
	IdempotencyKey string `json:"idempotency_key"`
	// InstallationID Your stable opaque identifier for this app installation.
	InstallationID string `json:"installation_id"`
	// ExternalSubject Your stable opaque identifier for the person authorizing this installation.
	ExternalSubject string `json:"external_subject"`
	// InstallationLabel Optional user-readable name for the installation shown during consent.
	InstallationLabel string `json:"installation_label,omitempty"`
	// ExternalIdentityLabel Optional user-readable external identity shown during consent.
	ExternalIdentityLabel string `json:"external_identity_label,omitempty"`
	// RequestedScopes Capabilities the owner is being asked to delegate.
	RequestedScopes []string `json:"requested_scopes"`
}

// ExchangeExternalAuthorizationParams holds the parameters for ExchangeExternalAuthorization.
type ExchangeExternalAuthorizationParams struct {
	// PreferredLanguage BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages.
	PreferredLanguage string `json:"preferred_language,omitempty"`
	// DeviceCode Short-lived high-entropy secret used only to poll and exchange this request.
	DeviceCode string `json:"device_code"`
}

// InspectExternalAuthorizationParams holds the parameters for InspectExternalAuthorization.
type InspectExternalAuthorizationParams struct {
	// PreferredLanguage BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages.
	PreferredLanguage string `json:"preferred_language,omitempty"`
	// AccessToken Opaque grant token accepted only by grant inspection and external clone invocation; store it as a secret and never expose it to users.
	AccessToken string `json:"access_token"`
}

// InvokeExternalCloneParams holds the parameters for InvokeExternalClone.
type InvokeExternalCloneParams struct {
	// PreferredLanguage BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages.
	PreferredLanguage string `json:"preferred_language,omitempty"`
	// AccessToken Opaque grant token accepted only by grant inspection and external clone invocation; store it as a secret and never expose it to users.
	AccessToken string `json:"access_token"`
	// InstallationID Your stable opaque identifier for this app installation.
	InstallationID string `json:"installation_id"`
	// ExternalSubject Your stable opaque identifier for the person authorizing this installation.
	ExternalSubject string `json:"external_subject"`
	// CloneID AI consciousness id as returned by clone operations.
	CloneID string `json:"clone_id"`
	Text    string `json:"text"`
	// IdempotencyKey A stable opaque event key that makes exact retries return the same outcome.
	IdempotencyKey string `json:"idempotency_key"`
	// ConversationID Stable opaque id of the conversation or thread this event belongs to. Each conversation keeps its own separate history; omit for a plain one-on-one event.
	ConversationID string `json:"conversation_id,omitempty"`
	// SpeakerLabel Neutral display name of whoever is sending this message, shown to the AI consciousness as who it is currently talking to.
	SpeakerLabel string `json:"speaker_label,omitempty"`
	// IsGroup Set true when this event is one turn of a multi-party conversation so the AI consciousness replies as a single participant among several.
	IsGroup *bool `json:"is_group,omitempty"`
	// ContextMessages Recent surrounding conversation for group mode (issue #172): an ordered, bounded list of prior turns the AI consciousness reads as quoted context. Each entry has a `display_name` and `text`, plus optional `is_ai`, `timestamp` (seconds), and `gender`. It carries no platform identifiers and is never treated as instructions.
	ContextMessages []map[string]any `json:"context_messages,omitempty"`
	Learn           *bool            `json:"learn,omitempty"`
	SourceLabel     string           `json:"source_label,omitempty"`
}

// RefreshExternalAuthorizationParams holds the parameters for RefreshExternalAuthorization.
type RefreshExternalAuthorizationParams struct {
	// PreferredLanguage BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages.
	PreferredLanguage string `json:"preferred_language,omitempty"`
	// RefreshToken Opaque grant-lifetime token used only with refresh_external_authorization; store it as a secret.
	RefreshToken string `json:"refresh_token"`
	// InstallationID Your stable opaque identifier for this app installation.
	InstallationID string `json:"installation_id"`
	// ExternalSubject Your stable opaque identifier for the person authorizing this installation.
	ExternalSubject string `json:"external_subject"`
}

// UploadExternalMindDataParams holds the parameters for UploadExternalMindData.
type UploadExternalMindDataParams struct {
	// PreferredLanguage BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages.
	PreferredLanguage string `json:"preferred_language,omitempty"`
	// AccessToken Opaque grant token accepted only by grant inspection and external clone invocation; store it as a secret and never expose it to users.
	AccessToken string `json:"access_token"`
	// InstallationID Your stable opaque identifier for this app installation.
	InstallationID string `json:"installation_id"`
	// ExternalSubject Your stable opaque identifier for the person authorizing this installation.
	ExternalSubject string `json:"external_subject"`
	// CloneID AI consciousness id as returned by clone operations.
	CloneID  string `json:"clone_id"`
	Text     string `json:"text"`
	TextType string `json:"text_type,omitempty"`
	// IdempotencyKey Optional. Accepted for forward compatibility but ignored for deduplication today — retries may create another quarantine item. Not a safe replay key.
	IdempotencyKey string `json:"idempotency_key,omitempty"`
	SourceLabel    string `json:"source_label,omitempty"`
}

// GetMindClusterParams holds the parameters for GetMindCluster.
type GetMindClusterParams struct {
	// PreferredLanguage BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages.
	PreferredLanguage string `json:"preferred_language,omitempty"`
	// Username The end-user's username.
	Username string `json:"username,omitempty"`
	// Password The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage.
	Password      string `json:"password,omitempty"`
	Codename      string `json:"codename,omitempty"`
	NodeID        string `json:"node_id,omitempty"`
	TextsOffset   *int64 `json:"texts_offset,omitempty"`
	TextsPageSize *int64 `json:"texts_page_size,omitempty"`
	ForceRebuild  *bool  `json:"force_rebuild,omitempty"`
}

// GetSoulmateReportParams holds the parameters for GetSoulmateReport.
type GetSoulmateReportParams struct {
	// PreferredLanguage BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages.
	PreferredLanguage string `json:"preferred_language,omitempty"`
	// Username The end-user's username.
	Username string `json:"username,omitempty"`
	// Password The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage.
	Password     string `json:"password,omitempty"`
	MyCloneID    string `json:"my_clone_id,omitempty"`
	OtherCloneID string `json:"other_clone_id,omitempty"`
	// ChatroomID Chatroom id as returned by chatroom operations.
	ChatroomID string `json:"chatroom_id,omitempty"`
}

// CreateCallSessionParams holds the parameters for CreateCallSession.
type CreateCallSessionParams struct {
	// PreferredLanguage BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages.
	PreferredLanguage string `json:"preferred_language,omitempty"`
	// Username The end-user's username.
	Username string `json:"username,omitempty"`
	// Password The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage.
	Password string `json:"password,omitempty"`
	// ChatroomID Chatroom id as returned by chatroom operations.
	ChatroomID string `json:"chatroom_id,omitempty"`
	// Mode What kind of call to start. `conversation` (the default) admits everyone able to speak and show their camera. `broadcast` admits everyone except the chatroom owner and admins able to watch, listen and ask to speak, until somebody running the call lets them. Only the chatroom owner and admins may start a broadcast; anyone else asking for one starts a conversation.
	Mode string `json:"mode,omitempty"`
	// MediaTier Whether this call carries a picture. `video` (the default) is a call with cameras; `voice` is a call with none at all — sound only, which asks far less of a slow or metered connection. It is fixed for the whole call and applies to everybody in it — nobody can turn a camera on in a voice call, and nobody can join one as a video participant — so switching means starting a new call. Two things override it. A call already running in the room wins: the caller joins that one, in the kind it is already in. And `mode: broadcast` wins: a broadcast is always a video call, counted and capped as one. Read `media_tier` back off the call in the response to see which kind you got.
	MediaTier string `json:"media_tier,omitempty"`
	// HostInheritance Whether whoever starts this call runs it. False, and absent, mean the call controls rest only on chatroom standing — so a call whose owner and admins have all left carries on with nobody running it until one of them returns. Only the chatroom owner and admins may turn it on; anyone else asking for it is ignored. Set once, when the call starts.
	HostInheritance *bool `json:"host_inheritance,omitempty"`
}

// EndCallSessionParams holds the parameters for EndCallSession.
type EndCallSessionParams struct {
	// PreferredLanguage BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages.
	PreferredLanguage string `json:"preferred_language,omitempty"`
	// Username The end-user's username.
	Username string `json:"username,omitempty"`
	// Password The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage.
	Password      string `json:"password,omitempty"`
	CallSessionID string `json:"call_session_id,omitempty"`
	OnlyIfEmpty   *bool  `json:"only_if_empty,omitempty"`
}

// GetActiveCallSessionParams holds the parameters for GetActiveCallSession.
type GetActiveCallSessionParams struct {
	// PreferredLanguage BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages.
	PreferredLanguage string `json:"preferred_language,omitempty"`
	// Username The end-user's username.
	Username string `json:"username,omitempty"`
	// Password The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage.
	Password string `json:"password,omitempty"`
	// ChatroomID Chatroom id as returned by chatroom operations.
	ChatroomID string `json:"chatroom_id,omitempty"`
}

// JoinCallSessionParams holds the parameters for JoinCallSession.
type JoinCallSessionParams struct {
	// PreferredLanguage BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages.
	PreferredLanguage string `json:"preferred_language,omitempty"`
	// Username The end-user's username.
	Username string `json:"username,omitempty"`
	// Password The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage.
	Password      string `json:"password,omitempty"`
	CallSessionID string `json:"call_session_id,omitempty"`
}

// LeaveCallSessionParams holds the parameters for LeaveCallSession.
type LeaveCallSessionParams struct {
	// PreferredLanguage BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages.
	PreferredLanguage string `json:"preferred_language,omitempty"`
	// Username The end-user's username.
	Username string `json:"username,omitempty"`
	// Password The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage.
	Password      string `json:"password,omitempty"`
	CallSessionID string `json:"call_session_id,omitempty"`
}

// RefreshCallTokenParams holds the parameters for RefreshCallToken.
type RefreshCallTokenParams struct {
	// PreferredLanguage BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages.
	PreferredLanguage string `json:"preferred_language,omitempty"`
	// Username The end-user's username.
	Username string `json:"username,omitempty"`
	// Password The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage.
	Password      string `json:"password,omitempty"`
	CallSessionID string `json:"call_session_id,omitempty"`
}

// SetCallHostParams holds the parameters for SetCallHost.
type SetCallHostParams struct {
	// PreferredLanguage BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages.
	PreferredLanguage string `json:"preferred_language,omitempty"`
	// Username The end-user's username.
	Username string `json:"username,omitempty"`
	// Password The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage.
	Password      string `json:"password,omitempty"`
	CallSessionID string `json:"call_session_id,omitempty"`
	// TargetUserID User id of the person whose standing in the call is changing.
	TargetUserID string `json:"target_user_id,omitempty"`
	// RunsTheCall True to give that person the call controls for the length of this call; false to take them back.
	RunsTheCall *bool `json:"runs_the_call,omitempty"`
}

// AbortMultipartUploadParams holds the parameters for AbortMultipartUpload.
type AbortMultipartUploadParams struct {
	// PreferredLanguage BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages.
	PreferredLanguage string `json:"preferred_language,omitempty"`
	// Username The end-user's username.
	Username string `json:"username,omitempty"`
	// Password The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage.
	Password string `json:"password,omitempty"`
	// R2Key Opaque media object key returned by upload-start operations and reused for multipart upload calls.
	R2Key string `json:"r2_key,omitempty"`
	// UploadID Multipart upload session id returned by `request_multipart_upload`.
	UploadID string `json:"upload_id,omitempty"`
}

// CancelUploadParams holds the parameters for CancelUpload.
type CancelUploadParams struct {
	// PreferredLanguage BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages.
	PreferredLanguage string `json:"preferred_language,omitempty"`
	// Username The end-user's username.
	Username string `json:"username,omitempty"`
	// Password The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage.
	Password string `json:"password,omitempty"`
	// R2Key Opaque media object key returned by upload-start operations and reused for multipart upload calls.
	R2Key string `json:"r2_key,omitempty"`
}

// CompleteMultipartUploadParams holds the parameters for CompleteMultipartUpload.
type CompleteMultipartUploadParams struct {
	// PreferredLanguage BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages.
	PreferredLanguage string `json:"preferred_language,omitempty"`
	// Username The end-user's username.
	Username string `json:"username,omitempty"`
	// Password The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage.
	Password string `json:"password,omitempty"`
	// R2Key Opaque media object key returned by upload-start operations and reused for multipart upload calls.
	R2Key string `json:"r2_key,omitempty"`
	// UploadID Multipart upload session id returned by `request_multipart_upload`.
	UploadID string `json:"upload_id,omitempty"`
	// Parts The successfully uploaded parts, using the `part_number` and `etag` returned by each part upload.
	Parts []map[string]any `json:"parts,omitempty"`
}

// ListUploadPartsParams holds the parameters for ListUploadParts.
type ListUploadPartsParams struct {
	// PreferredLanguage BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages.
	PreferredLanguage string `json:"preferred_language,omitempty"`
	// Username The end-user's username.
	Username string `json:"username,omitempty"`
	// Password The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage.
	Password string `json:"password,omitempty"`
	// R2Key Opaque media object key returned by upload-start operations and reused for multipart upload calls.
	R2Key string `json:"r2_key,omitempty"`
	// UploadID Multipart upload session id returned by `request_multipart_upload`.
	UploadID string `json:"upload_id,omitempty"`
}

// RequestMultipartUploadParams holds the parameters for RequestMultipartUpload.
type RequestMultipartUploadParams struct {
	// PreferredLanguage BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages.
	PreferredLanguage string `json:"preferred_language,omitempty"`
	// Username The end-user's username.
	Username string `json:"username,omitempty"`
	// Password The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage.
	Password      string `json:"password,omitempty"`
	Filename      string `json:"filename,omitempty"`
	ContentType   string `json:"content_type,omitempty"`
	FileSizeBytes *int64 `json:"file_size_bytes,omitempty"`
	// MediaType The kind of media: `image`, `video`, or `audio`.
	MediaType    string `json:"media_type,omitempty"`
	HasThumbnail *bool  `json:"has_thumbnail,omitempty"`
}

// RequestUploadURLParams holds the parameters for RequestUploadURL.
type RequestUploadURLParams struct {
	// PreferredLanguage BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages.
	PreferredLanguage string `json:"preferred_language,omitempty"`
	// Username The end-user's username.
	Username string `json:"username,omitempty"`
	// Password The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage.
	Password      string `json:"password,omitempty"`
	Filename      string `json:"filename,omitempty"`
	ContentType   string `json:"content_type,omitempty"`
	FileSizeBytes *int64 `json:"file_size_bytes,omitempty"`
	// MediaType The kind of media: `image`, `video`, or `audio`.
	MediaType    string `json:"media_type,omitempty"`
	HasThumbnail *bool  `json:"has_thumbnail,omitempty"`
}

// SignUploadPartParams holds the parameters for SignUploadPart.
type SignUploadPartParams struct {
	// PreferredLanguage BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages.
	PreferredLanguage string `json:"preferred_language,omitempty"`
	// Username The end-user's username.
	Username string `json:"username,omitempty"`
	// Password The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage.
	Password string `json:"password,omitempty"`
	// R2Key Opaque media object key returned by upload-start operations and reused for multipart upload calls.
	R2Key string `json:"r2_key,omitempty"`
	// UploadID Multipart upload session id returned by `request_multipart_upload`.
	UploadID string `json:"upload_id,omitempty"`
	// PartNumber One-based multipart part number.
	PartNumber *int64 `json:"part_number,omitempty"`
}

// SignUploadPartsBatchParams holds the parameters for SignUploadPartsBatch.
type SignUploadPartsBatchParams struct {
	// PreferredLanguage BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages.
	PreferredLanguage string `json:"preferred_language,omitempty"`
	// Username The end-user's username.
	Username string `json:"username,omitempty"`
	// Password The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage.
	Password string `json:"password,omitempty"`
	// R2Key Opaque media object key returned by upload-start operations and reused for multipart upload calls.
	R2Key string `json:"r2_key,omitempty"`
	// UploadID Multipart upload session id returned by `request_multipart_upload`.
	UploadID string `json:"upload_id,omitempty"`
	// PartNumbers One-based multipart part numbers to sign in a single batch.
	PartNumbers []int64 `json:"part_numbers,omitempty"`
}

// StartMediaAnalysisParams holds the parameters for StartMediaAnalysis.
type StartMediaAnalysisParams struct {
	// PreferredLanguage BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages.
	PreferredLanguage string `json:"preferred_language,omitempty"`
	// Username The end-user's username.
	Username string `json:"username"`
	// Password The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage.
	Password string `json:"password"`
	// Media The attachment to start describing, as its own call. Send each one as soon as it is uploaded or pasted, while the person is still typing, so nothing is left to do at send time. `maxItems` is the cap; a longer array is rejected, not truncated.
	Media []map[string]any `json:"media"`
	// Codename The AI consciousness this attachment is for, named the way `rag` and `get_chat` name it. Send this for a one-on-one conversation, or `chatroom_id` for a room — exactly one of the two, and the person must be able to reach it.
	Codename string `json:"codename,omitempty"`
	// ChatroomID The chatroom this attachment is for, as returned by chatroom operations. Send this for a room, or `codename` for a one-on-one conversation — exactly one of the two, and the person must already be in the room.
	ChatroomID string `json:"chatroom_id,omitempty"`
}

// CreateTextParams holds the parameters for CreateText.
type CreateTextParams struct {
	// PreferredLanguage BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages.
	PreferredLanguage string `json:"preferred_language,omitempty"`
	// Username The end-user's username.
	Username string `json:"username,omitempty"`
	// Password The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage.
	Password string `json:"password,omitempty"`
	Codename string `json:"codename,omitempty"`
	// CloneID AI consciousness id as returned by clone operations.
	CloneID string `json:"clone_id,omitempty"`
	// Text The mind data itself. At most 50000 characters, counted in Unicode code points; longer text is rejected with 400 and nothing is stored.
	Text string `json:"text,omitempty"`
	Type string `json:"type,omitempty"`
}

// GetTextsParams holds the parameters for GetTexts.
type GetTextsParams struct {
	// PreferredLanguage BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages.
	PreferredLanguage string `json:"preferred_language,omitempty"`
	Page              *int64 `json:"page,omitempty"`
	// PageSize Maximum records requested for one server-capped page.
	PageSize *int64 `json:"page_size,omitempty"`
	SortBy   string `json:"sort_by,omitempty"`
	// SortOrder Sort direction; supported values depend on the operation.
	SortOrder           *int64 `json:"sort_order,omitempty"`
	UseCursorPagination *bool  `json:"use_cursor_pagination,omitempty"`
	// CursorValue Opaque pagination cursor value from the previous page (`next_cursor_value`).
	CursorValue string `json:"cursor_value,omitempty"`
	// CursorID Opaque pagination cursor id from the previous page (`next_cursor_id`).
	CursorID string `json:"cursor_id,omitempty"`
	// Username The end-user's username.
	Username string `json:"username,omitempty"`
	// Password The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage.
	Password string `json:"password,omitempty"`
	Codename string `json:"codename,omitempty"`
	Type     string `json:"type,omitempty"`
}

// GetTransactionHistoryParams holds the parameters for GetTransactionHistory.
type GetTransactionHistoryParams struct {
	// PreferredLanguage BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages.
	PreferredLanguage string `json:"preferred_language,omitempty"`
	Page              *int64 `json:"page,omitempty"`
	// PageSize Maximum records requested for one server-capped page.
	PageSize *int64 `json:"page_size,omitempty"`
	SortBy   string `json:"sort_by,omitempty"`
	// SortOrder Sort direction; supported values depend on the operation.
	SortOrder           *int64 `json:"sort_order,omitempty"`
	UseCursorPagination *bool  `json:"use_cursor_pagination,omitempty"`
	// CursorValue Opaque pagination cursor value from the previous page (`next_cursor_value`).
	CursorValue string `json:"cursor_value,omitempty"`
	// CursorID Opaque pagination cursor id from the previous page (`next_cursor_id`).
	CursorID string `json:"cursor_id,omitempty"`
	// Username The end-user's username.
	Username string `json:"username,omitempty"`
	// Password The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage.
	Password   string `json:"password,omitempty"`
	TypeFilter string `json:"type_filter,omitempty"`
}

// GetUserParams holds the parameters for GetUser.
type GetUserParams struct {
	// PreferredLanguage BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages.
	PreferredLanguage string `json:"preferred_language,omitempty"`
	// Username The end-user's username.
	Username string `json:"username,omitempty"`
	// Password The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage.
	Password string `json:"password,omitempty"`
}

// UpdateUserParams holds the parameters for UpdateUser.
type UpdateUserParams struct {
	// PreferredLanguage BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages.
	PreferredLanguage string `json:"preferred_language,omitempty"`
	// Username The end-user's username.
	Username string `json:"username,omitempty"`
	// Password The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage.
	Password                         string `json:"password,omitempty"`
	Email                            string `json:"email,omitempty"`
	EmailVerificationCode            string `json:"email_verification_code,omitempty"`
	FirstName                        string `json:"first_name,omitempty"`
	LastName                         string `json:"last_name,omitempty"`
	Nickname                         string `json:"nickname,omitempty"`
	Gender                           string `json:"gender,omitempty"`
	BirthDate                        *int64 `json:"birth_date,omitempty"`
	PhoneNumber                      string `json:"phone_number,omitempty"`
	AvatarID                         string `json:"avatar_id,omitempty"`
	AcceptChatroomInvitationByOthers *bool  `json:"accept_chatroom_invitation_by_others,omitempty"`
}

// --- AI Consciousnesses ---
// CreateClone Create a new AI consciousness for the user.
//
// Response fields: success, error_message.
// See https://docs.mindupload.app
func (c *Client) CreateClone(ctx context.Context, params CreateCloneParams) (*Response, error) {
	return c.do(ctx, "create_clone", structToMap(params))
}

// GetClones List the user's AI consciousnesses.
//
// Response fields: success, error_message, clones.
// See https://docs.mindupload.app
func (c *Client) GetClones(ctx context.Context, params GetClonesParams) (*Response, error) {
	return c.do(ctx, "get_clones", structToMap(params))
}

// UpdateClone Update an AI consciousness's profile.
//
// Response fields: success, error_message.
// See https://docs.mindupload.app
func (c *Client) UpdateClone(ctx context.Context, params UpdateCloneParams) (*Response, error) {
	return c.do(ctx, "update_clone", structToMap(params))
}

// --- Account ---
// GetQuota Check your partner API rate limits, credit caps, and current usage.
//
// Response fields: success, error_message, per_user_rate_limit_per_min, per_user_daily_credit_cap, partner_rate_limit_per_min, external_authorization_rate_limit_per_min, partner_daily_credit_cap, max_users, registered_users, partner_requests_last_minute, partner_credit_spends_last_day, user, user_requests_last_minute, user_credit_spends_last_day, credit_spending_tasks, calls_enabled, call_minutes_cap_monthly, call_max_concurrent_sessions, call_voice_minutes_cap_monthly, call_video_minutes_cap_monthly, call_voice_participant_minutes_this_month, call_video_participant_minutes_this_month, call_month_start_timestamp, call_sessions_this_month, call_participant_minutes_this_month, call_live_participant_minutes, call_data_transferred_bytes_this_month, call_data_transferred_is_complete, call_live_sessions, call_spending_tasks, operation_duration_ms.
// See https://docs.mindupload.app
func (c *Client) GetQuota(ctx context.Context, params GetQuotaParams) (*Response, error) {
	return c.do(ctx, "get_quota", structToMap(params))
}

// --- Authentication ---
// CheckUsername Check whether a username is still available before registering.
//
// Response fields: success, error_message, exists, disabled, rate_limited, flood_window, wait_seconds, operation_duration_ms.
// See https://docs.mindupload.app
func (c *Client) CheckUsername(ctx context.Context, params CheckUsernameParams) (*Response, error) {
	return c.do(ctx, "check_username", structToMap(params))
}

// Login Sign a user in and receive a session token (JWT) for subsequent calls.
//
// Response fields: success, error_message, jwt, decrypted_user.
// See https://docs.mindupload.app
func (c *Client) Login(ctx context.Context, params LoginParams) (*Response, error) {
	return c.do(ctx, "login", structToMap(params))
}

// Logout End the current user session.
//
// Response fields: success, error_message, revoked, operation_duration_ms.
// See https://docs.mindupload.app
func (c *Client) Logout(ctx context.Context, params LogoutParams) (*Response, error) {
	return c.do(ctx, "logout", structToMap(params))
}

// Register Create a user account on your platform.
//
// Response fields: success, error_message, jwt, decrypted_user.
// See https://docs.mindupload.app
func (c *Client) Register(ctx context.Context, params RegisterParams) (*Response, error) {
	return c.do(ctx, "register", structToMap(params))
}

// --- Chatrooms ---
// CheckChatroomUpdates Cheaply poll whether the user's chatrooms have new activity.
//
// Response fields: success, error_message, server_time, poll_config, chatrooms.
// See https://docs.mindupload.app
func (c *Client) CheckChatroomUpdates(ctx context.Context, params CheckChatroomUpdatesParams) (*Response, error) {
	return c.do(ctx, "check_chatroom_updates", structToMap(params))
}

// CreateChatroom Create a chatroom.
//
// Response fields: success, error_message, chatroom_id.
// See https://docs.mindupload.app
func (c *Client) CreateChatroom(ctx context.Context, params CreateChatroomParams) (*Response, error) {
	return c.do(ctx, "create_chatroom", structToMap(params))
}

// CreateChatroomMembership Invite a user or an AI consciousness into a chatroom.
//
// Response fields: success, error_message, membership_id.
// See https://docs.mindupload.app
func (c *Client) CreateChatroomMembership(ctx context.Context, params CreateChatroomMembershipParams) (*Response, error) {
	return c.do(ctx, "create_chatroom_membership", structToMap(params))
}

// CreateChatroomMessage Send a message to a chatroom.
//
// Response fields: success, error_message, message_id.
// See https://docs.mindupload.app
func (c *Client) CreateChatroomMessage(ctx context.Context, params CreateChatroomMessageParams) (*Response, error) {
	return c.do(ctx, "create_chatroom_message", structToMap(params))
}

// GetChatroomMembership List the members of a chatroom the user belongs to.
//
// Response fields: success, error_message, total_count, page, page_size, total_pages, has_next, has_prev, next_cursor_value, next_cursor_id, memberships.
// See https://docs.mindupload.app
func (c *Client) GetChatroomMembership(ctx context.Context, params GetChatroomMembershipParams) (*Response, error) {
	return c.do(ctx, "get_chatroom_membership", structToMap(params))
}

// GetChatroomMessages Fetch messages from a chatroom the user belongs to.
//
// Response fields: success, error_message, total_count, page, page_size, total_pages, has_next, has_prev, next_cursor_value, next_cursor_id, messages, media_thumbnails, media_fallbacks, since_overflow.
// See https://docs.mindupload.app
func (c *Client) GetChatroomMessages(ctx context.Context, params GetChatroomMessagesParams) (*Response, error) {
	return c.do(ctx, "get_chatroom_messages", structToMap(params))
}

// GetChatroomMessagesAround Fetch a window of chatroom messages around one message id (for jump-to).
//
// Response fields: success, error_message, messages, media_thumbnails, media_fallbacks, anchor_message_id.
// See https://docs.mindupload.app
func (c *Client) GetChatroomMessagesAround(ctx context.Context, params GetChatroomMessagesAroundParams) (*Response, error) {
	if params.Username == "" {
		return nil, errors.New("username is required")
	}
	if params.Password == "" {
		return nil, errors.New("password is required")
	}
	if params.ChatroomID == "" {
		return nil, errors.New("chatroom_id is required")
	}
	if params.MessageID == "" {
		return nil, errors.New("message_id is required")
	}
	return c.do(ctx, "get_chatroom_messages_around", structToMap(params))
}

// GetChatrooms List the chatrooms the user belongs to.
//
// Response fields: success, error_message, total_count, page, page_size, total_pages, has_next, has_prev, next_cursor_value, next_cursor_id, chatrooms.
// See https://docs.mindupload.app
func (c *Client) GetChatrooms(ctx context.Context, params GetChatroomsParams) (*Response, error) {
	return c.do(ctx, "get_chatrooms", structToMap(params))
}

// SearchChatroomMessages Find messages in a chatroom by keyword, date, media type, and/or sender.
//
// Response fields: success, error_message, messages, media_thumbnails, media_fallbacks, has_next, next_cursor_value, next_cursor_id, page_size, media_urls_expire_at.
// See https://docs.mindupload.app
func (c *Client) SearchChatroomMessages(ctx context.Context, params SearchChatroomMessagesParams) (*Response, error) {
	if params.Username == "" {
		return nil, errors.New("username is required")
	}
	if params.Password == "" {
		return nil, errors.New("password is required")
	}
	if params.ChatroomID == "" {
		return nil, errors.New("chatroom_id is required")
	}
	// Reject unsupported enum values locally before sending the request.
	for _, contentMediaTypeValue := range params.ContentMediaTypes {
		switch contentMediaTypeValue {
		case "image", "video", "audio":
		default:
			return nil, errors.New("content_media_types contains an unsupported value")
		}
	}
	return c.do(ctx, "search_chatroom_messages", structToMap(params))
}

// TranslateChatroomMessage Translate a text chatroom message into the viewer language.
//
// Response fields: success, error_message, translated_text, target_language, cached.
// See https://docs.mindupload.app
func (c *Client) TranslateChatroomMessage(ctx context.Context, params TranslateChatroomMessageParams) (*Response, error) {
	return c.do(ctx, "translate_chatroom_message", structToMap(params))
}

// --- Conversation ---
// GetChat Fetch the one-on-one conversation history with an AI consciousness.
//
// Response fields: success, error_message, total_count, page, page_size, total_pages, has_next, has_prev, next_cursor_value, next_cursor_id, chats, media_thumbnails, media_fallbacks.
// See https://docs.mindupload.app
func (c *Client) GetChat(ctx context.Context, params GetChatParams) (*Response, error) {
	return c.do(ctx, "get_chat", structToMap(params))
}

// GetChatAround Fetch a window of one-on-one turns around one chat id (for jump-to).
//
// Response fields: success, error_message, chats, media_thumbnails, media_fallbacks, anchor_chat_id.
// See https://docs.mindupload.app
func (c *Client) GetChatAround(ctx context.Context, params GetChatAroundParams) (*Response, error) {
	if params.Username == "" {
		return nil, errors.New("username is required")
	}
	if params.Password == "" {
		return nil, errors.New("password is required")
	}
	if params.CloneID == "" {
		return nil, errors.New("clone_id is required")
	}
	if params.ChatID == "" {
		return nil, errors.New("chat_id is required")
	}
	return c.do(ctx, "get_chat_around", structToMap(params))
}

// Rag Send a message to an AI consciousness and receive its reply.
//
// Response fields: success, error_message, response_text, clone_nickname, consolidation_summary, consolidation_count, consolidation_dispatched.
// See https://docs.mindupload.app
func (c *Client) Rag(ctx context.Context, params RagParams) (*Response, error) {
	return c.do(ctx, "rag", structToMap(params))
}

// SearchChats Find turns in a one-on-one AI conversation by keyword, date, media type, and/or Human/AI side.
//
// Response fields: success, error_message, chats, media_thumbnails, media_fallbacks, has_next, next_cursor_value, next_cursor_id, page_size, media_urls_expire_at.
// See https://docs.mindupload.app
func (c *Client) SearchChats(ctx context.Context, params SearchChatsParams) (*Response, error) {
	if params.Username == "" {
		return nil, errors.New("username is required")
	}
	if params.Password == "" {
		return nil, errors.New("password is required")
	}
	if params.CloneID == "" {
		return nil, errors.New("clone_id is required")
	}
	// Reject unsupported enum values locally before sending the request.
	for _, contentMediaTypeValue := range params.ContentMediaTypes {
		switch contentMediaTypeValue {
		case "image", "video", "audio":
		default:
			return nil, errors.New("content_media_types contains an unsupported value")
		}
	}
	return c.do(ctx, "search_chats", structToMap(params))
}

// TriggerSocial Have an AI consciousness proactively join the conversation in a chatroom.
//
// Response fields: success, error_message, response_text, chatroom_digests_count, chatroom_digests_summary, consolidation_summary, consolidation_count, consolidation_dispatched.
// See https://docs.mindupload.app
func (c *Client) TriggerSocial(ctx context.Context, params TriggerSocialParams) (*Response, error) {
	return c.do(ctx, "trigger_social", structToMap(params))
}

// --- External Authorization ---
// CreateExternalAuthorizationRequest Start passwordless grant issuance for an external identity and installation.
//
// Response fields: success, error_message, device_code, user_code, verification_uri, verification_uri_complete, expires_in, poll_interval, grant_duration_seconds.
// See https://docs.mindupload.app
func (c *Client) CreateExternalAuthorizationRequest(ctx context.Context, params CreateExternalAuthorizationRequestParams) (*Response, error) {
	if params.IdempotencyKey == "" {
		return nil, errors.New("idempotency_key is required")
	}
	if params.InstallationID == "" {
		return nil, errors.New("installation_id is required")
	}
	if params.ExternalSubject == "" {
		return nil, errors.New("external_subject is required")
	}
	if len(params.RequestedScopes) == 0 {
		return nil, errors.New("requested_scopes is required")
	}
	// Reject unsupported enum values locally before sending the request.
	for _, requestedScopeValue := range params.RequestedScopes {
		switch requestedScopeValue {
		case "clone:invoke", "clone:learn", "clone:invoke_shared", "clone:upload":
		default:
			return nil, errors.New("requested_scopes contains an unsupported value")
		}
	}
	return c.do(ctx, "create_external_authorization_request", structToMap(params))
}

// ExchangeExternalAuthorization Poll owner consent and exchange an approval for a clone-scoped grant token.
//
// Response fields: success, error_message, status, access_token, refresh_token, token_type, grant_id, scopes, clone_ids, clone_nicknames, access_token_expires_at, expires_at, poll_interval.
// See https://docs.mindupload.app
func (c *Client) ExchangeExternalAuthorization(ctx context.Context, params ExchangeExternalAuthorizationParams) (*Response, error) {
	if params.DeviceCode == "" {
		return nil, errors.New("device_code is required")
	}
	return c.do(ctx, "exchange_external_authorization", structToMap(params))
}

// InspectExternalAuthorization Inspect the scopes, clone resources, expiry, and revocation state of a grant token.
//
// Response fields: success, error_message, grant_id, status, scopes, clone_ids, created_at, access_token_expires_at, expires_at, revoked_at.
// See https://docs.mindupload.app
func (c *Client) InspectExternalAuthorization(ctx context.Context, params InspectExternalAuthorizationParams) (*Response, error) {
	if params.AccessToken == "" {
		return nil, errors.New("access_token is required")
	}
	return c.do(ctx, "inspect_external_authorization", structToMap(params))
}

// InvokeExternalClone Send one idempotent text event to an owner-approved AI consciousness.
//
// Response fields: success, error_message, invocation_id, status, response_text, clone_id, clone_nickname, generated_by_ai, idempotent_replay, retry_after_seconds.
// See https://docs.mindupload.app
func (c *Client) InvokeExternalClone(ctx context.Context, params InvokeExternalCloneParams) (*Response, error) {
	if params.AccessToken == "" {
		return nil, errors.New("access_token is required")
	}
	if params.InstallationID == "" {
		return nil, errors.New("installation_id is required")
	}
	if params.ExternalSubject == "" {
		return nil, errors.New("external_subject is required")
	}
	if params.CloneID == "" {
		return nil, errors.New("clone_id is required")
	}
	if params.Text == "" {
		return nil, errors.New("text is required")
	}
	if params.IdempotencyKey == "" {
		return nil, errors.New("idempotency_key is required")
	}
	return c.do(ctx, "invoke_external_clone", structToMap(params))
}

// RefreshExternalAuthorization Refresh a short-lived clone-invocation access token.
//
// Response fields: success, error_message, status, access_token, refresh_token, token_type, grant_id, scopes, clone_ids, clone_nicknames, access_token_expires_at, expires_at.
// See https://docs.mindupload.app
func (c *Client) RefreshExternalAuthorization(ctx context.Context, params RefreshExternalAuthorizationParams) (*Response, error) {
	if params.RefreshToken == "" {
		return nil, errors.New("refresh_token is required")
	}
	if params.InstallationID == "" {
		return nil, errors.New("installation_id is required")
	}
	if params.ExternalSubject == "" {
		return nil, errors.New("external_subject is required")
	}
	return c.do(ctx, "refresh_external_authorization", structToMap(params))
}

// UploadExternalMindData Upload mind data (text and media) into the owner's own AI consciousness.
//
// Response fields: success, error_message, clone_id, text_type, pending_owner_review.
// See https://docs.mindupload.app
func (c *Client) UploadExternalMindData(ctx context.Context, params UploadExternalMindDataParams) (*Response, error) {
	if params.AccessToken == "" {
		return nil, errors.New("access_token is required")
	}
	if params.InstallationID == "" {
		return nil, errors.New("installation_id is required")
	}
	if params.ExternalSubject == "" {
		return nil, errors.New("external_subject is required")
	}
	if params.CloneID == "" {
		return nil, errors.New("clone_id is required")
	}
	if params.Text == "" {
		return nil, errors.New("text is required")
	}
	return c.do(ctx, "upload_external_mind_data", structToMap(params))
}

// --- Insights ---
// GetMindCluster Fetch the mind-graph visualization data of an AI consciousness.
//
// Response fields: success, error_message, root_node_id, node, children, texts, total_texts, texts_offset, has_more_texts, is_building.
// See https://docs.mindupload.app
func (c *Client) GetMindCluster(ctx context.Context, params GetMindClusterParams) (*Response, error) {
	return c.do(ctx, "get_mind_cluster", structToMap(params))
}

// GetSoulmateReport Generate or fetch the compatibility report between two chatroom members.
//
// Response fields: success, error_message, report, report_generated_at, is_generating, charged.
// See https://docs.mindupload.app
func (c *Client) GetSoulmateReport(ctx context.Context, params GetSoulmateReportParams) (*Response, error) {
	return c.do(ctx, "get_soulmate_report", structToMap(params))
}

// --- Live calls ---
// CreateCallSession Start a live voice and video call in a chatroom, or join the one already running.
//
// Response fields: success, error_message, call_session_id, auth_token, participant_id, expires_at, is_host, call_session.
// See https://docs.mindupload.app
func (c *Client) CreateCallSession(ctx context.Context, params CreateCallSessionParams) (*Response, error) {
	return c.do(ctx, "create_call_session", structToMap(params))
}

// EndCallSession End a live call for everyone in it.
//
// Response fields: success, error_message.
// See https://docs.mindupload.app
func (c *Client) EndCallSession(ctx context.Context, params EndCallSessionParams) (*Response, error) {
	return c.do(ctx, "end_call_session", structToMap(params))
}

// GetActiveCallSession Check whether a chatroom has a live call, and how many people are in it.
//
// Response fields: success, error_message, call_session.
// See https://docs.mindupload.app
func (c *Client) GetActiveCallSession(ctx context.Context, params GetActiveCallSessionParams) (*Response, error) {
	return c.do(ctx, "get_active_call_session", structToMap(params))
}

// JoinCallSession Join a live call that is already running in a chatroom.
//
// Response fields: success, error_message, call_session_id, auth_token, participant_id, expires_at, is_host, call_session.
// See https://docs.mindupload.app
func (c *Client) JoinCallSession(ctx context.Context, params JoinCallSessionParams) (*Response, error) {
	return c.do(ctx, "join_call_session", structToMap(params))
}

// LeaveCallSession Say that this person has left a call the others are still in.
//
// Response fields: success, error_message.
// See https://docs.mindupload.app
func (c *Client) LeaveCallSession(ctx context.Context, params LeaveCallSessionParams) (*Response, error) {
	return c.do(ctx, "leave_call_session", structToMap(params))
}

// RefreshCallToken Get a fresh joining pass for a call, before the current one expires.
//
// Response fields: success, error_message, call_session_id, auth_token, participant_id, expires_at, is_host.
// See https://docs.mindupload.app
func (c *Client) RefreshCallToken(ctx context.Context, params RefreshCallTokenParams) (*Response, error) {
	return c.do(ctx, "refresh_call_token", structToMap(params))
}

// SetCallHost Make somebody a co-host of a live call, or stand them down again.
//
// Response fields: success, error_message.
// See https://docs.mindupload.app
func (c *Client) SetCallHost(ctx context.Context, params SetCallHostParams) (*Response, error) {
	return c.do(ctx, "set_call_host", structToMap(params))
}

// --- Media ---
// AbortMultipartUpload Cancel a multipart upload and discard its parts.
//
// Response fields: success, error_message.
// See https://docs.mindupload.app
func (c *Client) AbortMultipartUpload(ctx context.Context, params AbortMultipartUploadParams) (*Response, error) {
	return c.do(ctx, "abort_multipart_upload", structToMap(params))
}

// CancelUpload Cancel a pending upload.
//
// Response fields: success, error_message.
// See https://docs.mindupload.app
func (c *Client) CancelUpload(ctx context.Context, params CancelUploadParams) (*Response, error) {
	return c.do(ctx, "cancel_upload", structToMap(params))
}

// CompleteMultipartUpload Finish a multipart upload.
//
// Response fields: success, error_message, media_url.
// See https://docs.mindupload.app
func (c *Client) CompleteMultipartUpload(ctx context.Context, params CompleteMultipartUploadParams) (*Response, error) {
	return c.do(ctx, "complete_multipart_upload", structToMap(params))
}

// ListUploadParts List the parts already uploaded in a multipart upload.
//
// Response fields: success, error_message, parts.
// See https://docs.mindupload.app
func (c *Client) ListUploadParts(ctx context.Context, params ListUploadPartsParams) (*Response, error) {
	return c.do(ctx, "list_upload_parts", structToMap(params))
}

// RequestMultipartUpload Start a large-file upload in multiple parts.
//
// Response fields: success, error_message, upload_id, r2_key, media_url, signed_media_url, thumbnail_r2_key, thumbnail_presigned_url, signed_thumbnail_url.
// See https://docs.mindupload.app
func (c *Client) RequestMultipartUpload(ctx context.Context, params RequestMultipartUploadParams) (*Response, error) {
	return c.do(ctx, "request_multipart_upload", structToMap(params))
}

// RequestUploadURL Request an upload slot and a signed viewing link for a media attachment.
//
// Response fields: success, error_message, r2_key, presigned_url, media_url, signed_media_url, thumbnail_r2_key, thumbnail_presigned_url, signed_thumbnail_url.
// See https://docs.mindupload.app
func (c *Client) RequestUploadURL(ctx context.Context, params RequestUploadURLParams) (*Response, error) {
	return c.do(ctx, "request_upload_url", structToMap(params))
}

// SignUploadPart Get the signed link for one part of a multipart upload.
//
// Response fields: success, error_message, presigned_url.
// See https://docs.mindupload.app
func (c *Client) SignUploadPart(ctx context.Context, params SignUploadPartParams) (*Response, error) {
	return c.do(ctx, "sign_upload_part", structToMap(params))
}

// SignUploadPartsBatch Get signed links for several parts of a multipart upload at once.
//
// Response fields: success, error_message, presigned_urls.
// See https://docs.mindupload.app
func (c *Client) SignUploadPartsBatch(ctx context.Context, params SignUploadPartsBatchParams) (*Response, error) {
	return c.do(ctx, "sign_upload_parts_batch", structToMap(params))
}

// StartMediaAnalysis Begin analysing an uploaded or linked attachment so its description is ready before the message is sent.
//
// Response fields: success, error_message, analyses.
// See https://docs.mindupload.app
func (c *Client) StartMediaAnalysis(ctx context.Context, params StartMediaAnalysisParams) (*Response, error) {
	if params.Username == "" {
		return nil, errors.New("username is required")
	}
	if params.Password == "" {
		return nil, errors.New("password is required")
	}
	if len(params.Media) == 0 {
		return nil, errors.New("media is required")
	}
	return c.do(ctx, "start_media_analysis", structToMap(params))
}

// --- Memories ---
// CreateText Upload a memory or persona entry to an AI consciousness.
//
// Response fields: success, error_message, cluster_label, cluster_modified_count.
// See https://docs.mindupload.app
func (c *Client) CreateText(ctx context.Context, params CreateTextParams) (*Response, error) {
	return c.do(ctx, "create_text", structToMap(params))
}

// GetTexts List the memories and persona entries uploaded to an AI consciousness.
//
// Response fields: success, error_message, total_count, page, page_size, total_pages, has_next, has_prev, next_cursor_value, next_cursor_id, texts.
// See https://docs.mindupload.app
func (c *Client) GetTexts(ctx context.Context, params GetTextsParams) (*Response, error) {
	return c.do(ctx, "get_texts", structToMap(params))
}

// --- Users ---
// GetTransactionHistory List the user's Rabbit balance history (top-ups, spending, earnings, withdrawals, tax), newest first, filterable by category and paged with a cursor.
//
// Response fields: success, error_message, total_count, page, page_size, total_pages, has_next, has_prev, next_cursor_value, next_cursor_id, transactions, operation_duration_ms.
// See https://docs.mindupload.app
func (c *Client) GetTransactionHistory(ctx context.Context, params GetTransactionHistoryParams) (*Response, error) {
	return c.do(ctx, "get_transaction_history", structToMap(params))
}

// GetUser Fetch the signed-in user's profile.
//
// Response fields: success, error_message, jwt, decrypted_user.
// See https://docs.mindupload.app
func (c *Client) GetUser(ctx context.Context, params GetUserParams) (*Response, error) {
	return c.do(ctx, "get_user", structToMap(params))
}

// UpdateUser Update the signed-in user's profile.
//
// Response fields: success, error_message.
// See https://docs.mindupload.app
func (c *Client) UpdateUser(ctx context.Context, params UpdateUserParams) (*Response, error) {
	return c.do(ctx, "update_user", structToMap(params))
}

// ExternalAuthorizationStatus is a stable device-flow polling state.
type ExternalAuthorizationStatus string

const (
	ExternalAuthorizationPending   ExternalAuthorizationStatus = "pending"
	ExternalAuthorizationSlowDown  ExternalAuthorizationStatus = "slow_down"
	ExternalAuthorizationDenied    ExternalAuthorizationStatus = "denied"
	ExternalAuthorizationExpired   ExternalAuthorizationStatus = "expired"
	ExternalAuthorizationRevoked   ExternalAuthorizationStatus = "revoked"
	ExternalAuthorizationExchanged ExternalAuthorizationStatus = "exchanged"
)

const (
	defaultAuthorizationPoll = 5 * time.Second
	maximumPendingPoll       = 15 * time.Second
	maximumSlowDownPoll      = 30 * time.Second
	slowDownIncrement        = 5 * time.Second
	pollJitterRatio          = 0.2
)

const (
	defaultInvocationPoll              = 2 * time.Second
	maximumInvocationPoll              = 10 * time.Second
	externalInvocationProcessingStatus = "processing"
)

// invocationRetryStatuses are transient gateway faults worth replaying an
// idempotent invocation through; a slow in-request clone reply can surface as
// one of these before the receipt is ready.
var invocationRetryStatuses = map[int]bool{502: true, 503: true, 504: true}

// WaitForExternalAuthorization polls at the server-advised cadence until
// exchange succeeds or the provided context is canceled.
func (c *Client) WaitForExternalAuthorization(
	ctx context.Context, deviceCode string,
) (*Response, error) {
	pollInterval := defaultAuthorizationPoll
	// Poll sequentially because every response controls the next
	// server-advised delay.
	for {
		result, err := c.ExchangeExternalAuthorization(
			ctx, ExchangeExternalAuthorizationParams{DeviceCode: deviceCode},
		)
		if err != nil {
			return nil, err
		}
		status := ExternalAuthorizationStatus(result.String("status"))
		switch status {
		case ExternalAuthorizationExchanged:
			return result, nil
		case ExternalAuthorizationDenied, ExternalAuthorizationExpired, ExternalAuthorizationRevoked:
			return nil, &Error{
				Operation: "exchange_external_authorization",
				Message:   "external authorization ended with status: " + string(status),
				Response:  result.Data,
			}
		}
		serverInterval := defaultAuthorizationPoll
		if seconds, ok := result.Get("poll_interval").(float64); ok && seconds > 0 {
			serverInterval = time.Duration(seconds * float64(time.Second))
		}
		if status == ExternalAuthorizationSlowDown {
			pollInterval += slowDownIncrement
			if pollInterval > maximumSlowDownPoll {
				pollInterval = maximumSlowDownPoll
			}
		} else {
			pollInterval = pollInterval * 3 / 2
			if pollInterval > maximumPendingPoll {
				pollInterval = maximumPendingPoll
			}
		}
		if serverInterval > pollInterval {
			pollInterval = serverInterval
		}
		jitter := time.Duration(
			rand.Float64() * pollJitterRatio * float64(pollInterval),
		)
		if err := sleepCtx(ctx, pollInterval+jitter); err != nil {
			return nil, err
		}
	}
}

// WaitForExternalCloneInvocation invokes a clone and waits out slow in-request
// generation via idempotent retries, until the reply is ready or ctx is canceled.
//
// Because the invocation is idempotent on the params' idempotency key, re-sending
// the same event is safe: a still-generating call returns status "processing" (or
// a per-call timeout, connection failure, or transient gateway fault), and the
// finished result is replayed once ready. Pass a ctx with a deadline
// (context.WithTimeout) to bound the total wait; a deadline-less ctx polls until
// the reply is ready.
func (c *Client) WaitForExternalCloneInvocation(
	ctx context.Context, params InvokeExternalCloneParams,
) (*Response, error) {
	pollInterval := defaultInvocationPoll
	// Poll sequentially; the same idempotency key coalesces to one server-side
	// generation and one charge, so re-sending is safe.
	for {
		result, err := c.InvokeExternalClone(ctx, params)
		if err != nil {
			if ctx.Err() != nil {
				// The caller's own context was canceled or hit its deadline: stop.
				return nil, err
			}
			// A per-call timeout or connection failure means the reply may still be
			// generating server-side, and a transient gateway fault is worth replaying;
			// the same idempotency key makes the retry safe. Surface everything else
			// (4xx, 429, and a failed receipt, all of which carry no retry sentinel).
			var apiErr *Error
			switch {
			case errors.Is(err, ErrConnection), errors.Is(err, context.DeadlineExceeded):
				result = nil
			case errors.As(err, &apiErr) && invocationRetryStatuses[apiErr.Status]:
				result = nil
			default:
				return nil, err
			}
		}
		if result != nil && result.String("status") != externalInvocationProcessingStatus {
			return result, nil
		}
		if result != nil {
			if seconds, ok := result.Get("retry_after_seconds").(float64); ok && seconds > 0 {
				pollInterval = time.Duration(seconds * float64(time.Second))
			}
		}
		if pollInterval > maximumInvocationPoll {
			pollInterval = maximumInvocationPoll
		}
		jitter := time.Duration(rand.Float64() * pollJitterRatio * float64(pollInterval))
		if err := sleepCtx(ctx, pollInterval+jitter); err != nil {
			return nil, err
		}
	}
}