/**
 * Represents a new email to be added to a contact.
 */
export type NewEmail = {
  /**
   * Label associated with the email. If not provided, a label "other" will be used.
   * @example "work", "home"
   */
  label?: string;
  /**
   * Represents the email address.
   * @example "user@example.com"
   */
  address?: string;
};

/**
 * Represents an existing email associated with a contact.
 * This object can be obtained from `Contact.getEmails` or 'contact.getDetails' methods.
 */
export type ExistingEmail = NewEmail & {
  /**
   * Unique identifier for the existing email. It is generated by the system when an email is added.
   * For iOS its an identifier from CNLabeledValue,
   * for Android it's the _ID column from ContactsContract.CommonDataKinds.Email table.
   */
  id: string;
};

/**
 * Represents a new phone number to be added to a contact.
 */
export type NewPhone = {
  /**
   * Label associated with the phone number. If not provided, a label "other" will be used.
   * @example "work", "home"
   */
  label?: string;
  /**
   * Represents the phone number. It is recommended to use E.164 format for phone numbers.
   * The database does not enforce any specific format, so any string can be used.
   * @example "+12123456789"
   */
  number?: string;
};

/**
 * Represents an existing phone number associated with a contact.
 */
export type ExistingPhone = NewPhone & {
  /**
   * Unique identifier for the existing phone. For iOS its an identifier from CNLabeledValue,
   * for Android it's the _ID column from ContactsContract.CommonDataKinds.Phone table.
   */
  id: string;
};

/**
 * Represents a date associated with a contact.
 */
export type NewDate = {
  /**
   * Label associated with the date. If not provided, a label "other" will be used.
   * @example "anniversary", "birthday"
   */
  label?: string;
  /**
   * Represents the date.
   */
  date?: ContactDate;
};

/**
 * Represents an existing date associated with a contact.
 */
export type ExistingDate = NewDate & {
  /**
   * Unique identifier for the existing date. For iOS its an identifier from CNLabeledValue,
   * for Android it's the _ID column from ContactsContract.CommonDataKinds.Date table.
   */
  id: string;
};

/**
 * Represents a new extra name to be added to a contact.
 * @platform android
 */
export type NewExtraName = {
  /**
   * Label associated with the extra name. If not provided, a label "other" will be used.
   * @example "maiden", "nickname", "alias"
   */
  label?: string;
  /**
   * Represents the extra name.
   * @example "Johnny"
   */
  name?: string;
};

/**
 * Represents an existing extra name associated with a contact.
 * This object can be obtained from `Contact.getExtraNames` or 'contact.getDetails' methods.
 * @platform android
 */
export type ExistingExtraName = NewExtraName & {
  /**
   * Unique identifier for the existing extra name. This value is generated by the system.
   * It's the _ID column from ContactsContract.CommonDataKinds.Nickname table.
   */
  id: string;
};

/**
 * Represents a new postal address to be added to a contact.
 */
export type NewAddress = {
  /**
   * Label associated with the address. If not provided, a label "other" will be used.
   * @example "work", "home"
   */
  label?: string;
  /**
   * Can be street, avenue road etc. This element also includes the house number and apartment/suite number if applicable.
   * @example "123 Main St"
   */
  street?: string;
  /**
   * Can be city, town village etc.
   * @example "San Francisco"
   */
  city?: string;
  /**
   * A state, province, county (in Ireland), Land (in Germany), departement (in France), etc.
   * @example "CA"
   */
  state?: string;
  /**
   * Postal code.
   * @example "94105"
   */
  postcode?: string;
  /**
   * Region name.
   * @example "California"
   */
  region?: string;
  /**
   * Country name.
   * @example "USA"
   */
  country?: string;
};

/**
 * Represents an existing postal address associated with a contact.
 */
export type ExistingAddress = NewAddress & {
  /**
   * Unique identifier for the existing address. For iOS its an identifier from CNLabeledValue,
   * for Android it's the _ID column from ContactsContract.CommonDataKinds.StructuredPostal table.
   */
  id: string;
};

/**
 * Represents a new relation (brother, sister, etc.) to be added to a contact.
 */
export type NewRelation = {
  /**
   * Label associated with the relation. If not provided, a label "other" will be used.
   * @example "brother", "sister"
   */
  label?: string;
  /**
   * The name of the relative.
   * @example "Anna"
   */
  name?: string;
};

/**
 * Represents an existing relation associated with a contact.
 */
export type ExistingRelation = NewRelation & {
  /**
   * Unique identifier for the existing relation. For iOS its an identifier from CNLabeledValue,
   * for Android it's the _ID column from ContactsContract.CommonDataKinds.Relation table.
   */
  id: string;
};

/**
 * Represents a new URL address to be added to a contact.
 */
export type NewUrlAddress = {
  /**
   * Label associated with the URL address. If not provided, a label "other" will be used.
   * @example "homepage", "blog"
   */
  label?: string;
  /**
   * The URL address.
   * @example "https://example.com"
   */
  url?: string;
};

/**
 * Represents an existing URL address associated with a contact.
 */
export type ExistingUrlAddress = NewUrlAddress & {
  /**
   * Unique identifier for the existing URL address. For iOS its an identifier from CNLabeledValue,
   * for Android it's the _ID column from ContactsContract.CommonDataKinds.Website table.
   */
  id: string;
};

/**
 * Represents a new instant messaging address to be added to a contact.
 * @platform ios
 */
export type NewImAddress = {
  /**
   * Label associated with the instant messaging address. If not provided, a label "other" will be used.
   * @example "WhatsApp"
   */
  label?: string;
  /**
   * The user name for instant message service address.
   * @example "user123"
   */
  username?: string;
  /**
   * The name of the instant message address service.
   * @example "WhatsApp", "Skype"
   */
  service?: string;
};

/**
 * Represents an existing instant messaging address associated with a contact.
 * @platform ios
 */
export type ExistingImAddress = NewImAddress & {
  /**
   * Unique identifier for the existing instant messaging address. Its an identifier from CNLabeledValue.
   */
  id: string;
};

/**
 * Represents a new social profile to be added to a contact.
 */
export type NewSocialProfile = {
  /**
   * Label associated with the social profile.
   */
  label?: string;
  /**
   * Username for the social profile.
   */
  username?: string;
  /**
   * Service name (e.g., Twitter, Facebook).
   */
  service?: string;
  /**
   * URL to the social profile.
   */
  url?: string;
  /**
   * User identifier for the social profile.
   */
  userId?: string;
};

/**
 * Represents an existing social profile associated with a contact.
 */
export type ExistingSocialProfile = NewSocialProfile & {
  /**
   * Unique identifier for the existing social profile. Its an identifier from CNLabeledValue.
   */
  id: string;
};

/**
 * Contact date representation.
 */
export type ContactDate = {
  /**
   * Year component of the date. For birthday dates, this field can be omitted to represent a date without a year.
   */
  year?: number;
  /**
   * Month component of the date in format 1-12.
   */
  month: number;
  /**
   * Day component of the date in format 1-31.
   */
  day: number;
};

/**
 * Enum representing non-Gregorian calendar types.
 * @platform ios
 */
export enum NonGregorianCalendar {
  buddhist = 'buddhist',
  chinese = 'chinese',
  coptic = 'coptic',
  ethiopicAmeteMihret = 'ethiopicAmeteMihret',
  ethiopicAmeteAlem = 'ethiopicAmeteAlem',
  hebrew = 'hebrew',
  indian = 'indian',
  islamic = 'islamic',
  islamicCivil = 'islamicCivil',
  japanese = 'japanese',
  persian = 'persian',
  republicOfChina = 'republicOfChina',
}

/**
 * Represents a non-Gregorian birthday date.
 * @platform ios
 */
export type NonGregorianBirthday = {
  /**
   * Year component of the date. For birthday dates, this field can be omitted to represent a date without a year.
   */
  year?: number;
  /**
   * Month component of the date in format 1-12.
   */
  month: number;
  /**
   * Day component of the date in format 1-31.
   */
  day: number;
  /**
   * The calendar system used for the date.
   */
  calendar: NonGregorianCalendar;
};

/**
 * Represents a set of fields to be patched on a contact. Undefined fields will be ignored.
 * To remove a value, set the field to null.
 */
export type ContactPatch = {
  /**
   * Whether the contact is marked as a favorite.
   * @platform android
   * @example true
   */
  isFavourite?: boolean | null;
  /**
   * Given name of the contact.
   * @example "John"
   */
  givenName?: string | null;
  /**
   * Middle name of the contact.
   * @example "Andrew"
   */
  middleName?: string | null;
  /**
   * Family name (last name) of the contact.
   * @example "Smith"
   */
  familyName?: string | null;
  /**
   * Nickname of the contact.
   * @platform ios
   * @example "Johnny"
   */
  nickname?: string | null;
  /**
   * Maiden name of the contact.
   * @platform ios
   * @example "Johnson"
   */
  maidenName?: string | null;
  /**
   * Prefix (title) of the contact.
   * @example "Dr."
   */
  prefix?: string | null;
  /**
   * Suffix of the contact.
   * @example "Jr."
   */
  suffix?: string | null;
  /**
   * Phonetic given name of the contact.
   * @example "Jon"
   */
  phoneticGivenName?: string | null;
  /**
   * Phonetic middle name of the contact.
   * @example "Andrews"
   */
  phoneticMiddleName?: string | null;
  /**
   * Phonetic family name of the contact.
   * @example "Smith"
   */
  phoneticFamilyName?: string | null;
  /**
   * Company name of the contact.
   * @example "Expo"
   */
  company?: string | null;
  /**
   * Department of the contact.
   * @example "Engineering"
   */
  department?: string | null;
  /**
   * Job title of the contact.
   * @example "Software Engineer"
   */
  jobTitle?: string | null;
  /**
   * Phonetic company name of the contact.
   * @example "Ekspo"
   */
  phoneticCompanyName?: string | null;
  /**
   * Note associated with the contact.
   * @example "Met at the conference."
   */
  note?: string | null;
  /**
   * URI of the contact's image. Network URLs are not supported.
   * @example "file:///path/to/image.jpg"
   */
  image?: string | null;
  /**
   * Birthday of the contact.
   * @platform ios
   */
  birthday?: ContactDate | null;
  /**
   * Non-Gregorian birthday of the contact.
   * @platform ios
   */
  nonGregorianBirthday?: NonGregorianBirthday | null;
  /**
   * Emails associated with the contact. It can be a mix of existing and new emails.
   * Existing emails will be updated; new emails will be added; not present emails will be deleted.
   */
  emails?: (ExistingEmail | NewEmail)[];
  /**
   * Phone numbers associated with the contact. It can be a mix of existing and new phone numbers.
   * Existing phone numbers will be updated; new phone numbers will be added; not present phone numbers will be deleted.
   */
  phones?: (ExistingPhone | NewPhone)[];
  /**
   * Dates associated with the contact. It can be a mix of existing and new dates.
   * Existing dates will be updated; new dates will be added; not present dates will be deleted.
   */
  dates?: (ExistingDate | NewDate)[];
  /**
   * Extra names associated with the contact. It can be a mix of existing and new extra names.
   * Existing extra names will be updated; new extra names will be added; not present extraNames will be deleted.
   * @platform android
   */
  extraNames?: (ExistingExtraName | NewExtraName)[];
  /**
   * Addresses associated with the contact. It can be a mix of existing and new addresses.
   * Existing addresses will be updated; new addresses will be added; not present addresses will be deleted.
   */
  addresses?: (ExistingAddress | NewAddress)[];
  /**
   * Relations associated with the contact. It can be a mix of existing and new relations.
   * Existing relations will be updated; new relations will be added; not present relations will be deleted.
   */
  relations?: (ExistingRelation | NewRelation)[];
  /**
   * URL addresses associated with the contact. It can be a mix of existing and new URL addresses.
   * Existing URL addresses will be updated; new URL addresses will be added; not present urlAddresses will be deleted.
   */
  urlAddresses?: (ExistingUrlAddress | NewUrlAddress)[];
  /**
   * Social profiles associated with the contact. It can be a mix of existing and new social profiles.
   * Existing social profiles will be updated; new social profiles will be added; not present socialProfiles will be deleted.
   * @platform ios
   */
  socialProfiles?: (ExistingSocialProfile | NewSocialProfile)[];
  /**
   * Instant messaging addresses associated with the contact. It can be a mix of existing and new instant messaging addresses.
   * Existing instant messaging addresses will be updated, new instant messaging addresses will be added; not present imAddresses will be deleted.
   * @platform ios
   */
  imAddresses?: (ExistingImAddress | NewImAddress)[];
};

/**
 * Represents the data required to create a new contact.
 */
export type CreateContactRecord = {
  /**
   * Whether the contact is marked as a favorite.
   * @platform android
   * @example true
   */
  isFavourite?: boolean;
  /**
   * Given name of the contact.
   * @example "John"
   */
  givenName?: string;
  /**
   * Middle name of the contact.
   * @example "Andrew"
   */
  middleName?: string;
  /**
   * Family name (last name) of the contact.
   * @example "Smith"
   */
  familyName?: string;
  /**
   * Maiden name of the contact.
   * @platform ios
   * @example "Johnson"
   */
  maidenName?: string;
  /**
   * Nickname of the contact.
   * @platform ios
   * @example "Johnny"
   */
  nickname?: string;
  /**
   * Prefix (title) of the contact.
   * @example "Dr."
   */
  prefix?: string;
  /**
   * Suffix of the contact.
   * @example "Jr."
   */
  suffix?: string;
  /**
   * Phonetic given name of the contact.
   * @example "Jon"
   */
  phoneticGivenName?: string;
  /**
   * Phonetic middle name of the contact.
   * @example "Andrews"
   */
  phoneticMiddleName?: string;
  /**
   * Phonetic family name of the contact.
   * @example "Smith"
   */
  phoneticFamilyName?: string;
  /**
   * Company name of the contact.
   * @example "Expo"
   */
  company?: string;
  /**
   * Department of the contact.
   * @example "Engineering"
   */
  department?: string;
  /**
   * Job title of the contact.
   * @example "Software Engineer"
   */
  jobTitle?: string;
  /**
   * Phonetic company name of the contact.
   * @example "Ekspo"
   */
  phoneticCompanyName?: string;
  /**
   * Note associated with the contact.
   * @example "Met at the conference."
   */
  note?: string;
  /**
   * URI of the contact's image. Network URLs are not supported.
   * @example "file:///path/to/image.jpg"
   */
  image?: string;
  /**
   * Birthday of the contact.
   * @platform ios
   */
  birthday?: ContactDate;
  /**
   * Non-Gregorian birthday of the contact.
   * @platform ios
   */
  nonGregorianBirthday?: NonGregorianBirthday;
  /**
   * List of new emails to be added to the contact.
   */
  emails?: NewEmail[];
  /**
   * List of new dates to be added to the contact.
   */
  dates?: NewDate[];
  /**
   * List of new phone numbers to be added to the contact.
   */
  phones?: NewPhone[];
  /**
   * List of new postal addresses to be added to the contact.
   */
  addresses?: NewAddress[];
  /**
   * List of new relations to be added to the contact.
   */
  relations?: NewRelation[];
  /**
   * List of new URL addresses to be added to the contact.
   */
  urlAddresses?: NewUrlAddress[];
  /**
   * List of new instant messaging addresses to be added to the contact.
   * @platform ios
   */
  imAddresses?: NewImAddress[];
  /**
   * List of new social profiles to be added to the contact.
   */
  socialProfiles?: NewSocialProfile[];
  /**
   * List of new extra names to be added to the contact.
   * @platform android
   */
  extraNames?: NewExtraName[];
};

/**
 * Represents the full details of an existing contact.
 * This object is returned by `Contact.getContact` or similar methods.
 */
export type ContactDetails = {
  /**
   * Whether the contact is marked as a favorite.
   * @platform android
   */
  isFavourite: boolean;
  /**
   * The composite full name of the contact.
   * @example "Dr. John Andrew Smith Jr."
   */
  fullName: string | null;
  /**
   * Given name of the contact.
   * @example "John"
   */
  givenName: string | null;
  /**
   * Middle name of the contact.
   * @example "Andrew"
   */
  middleName: string | null;
  /**
   * Family name (last name) of the contact.
   * @example "Smith"
   */
  familyName: string | null;
  /**
   * Maiden name of the contact.
   * @platform ios
   * @example "Johnson"
   */
  maidenName?: string | null;
  /**
   * Nickname of the contact.
   * @platform ios
   * @example "Johnny"
   */
  nickname?: string | null;
  /**
   * Prefix (title) of the contact.
   * @example "Dr."
   */
  prefix: string | null;
  /**
   * Suffix of the contact.
   * @example "Jr."
   */
  suffix: string | null;
  /**
   * Phonetic given name of the contact.
   * @example "Jon"
   */
  phoneticGivenName: string | null;
  /**
   * Phonetic middle name of the contact.
   * @example "Andrews"
   */
  phoneticMiddleName: string | null;
  /**
   * Phonetic family name of the contact.
   * @example "Smith"
   */
  phoneticFamilyName: string | null;
  /**
   * Company name of the contact.
   * @example "Expo"
   */
  company: string | null;
  /**
   * Department of the contact.
   * @example "Engineering"
   */
  department: string | null;
  /**
   * Job title of the contact.
   * @example "Software Engineer"
   */
  jobTitle?: string;
  /**
   * Phonetic company name of the contact.
   * @example "Ekspo"
   */
  phoneticCompanyName?: string;
  /**
   * Note associated with the contact.
   * @example "Met at the conference."
   */
  note: string | null;
  /**
   * URI of the contact's image.
   * @example "file:///path/to/image.jpg"
   */
  image: string | null;
  /**
   * URI of the contact's thumbnail.
   * @example "file:///path/to/image.jpg"
   */
  thumbnail: string | null;
  /**
   * Birthday of the contact.
   * @platform ios
   */
  birthday?: ContactDate | null;
  /**
   * Non-Gregorian birthday of the contact.
   * @platform ios
   */
  nonGregorianBirthday?: NonGregorianBirthday | null;
  /**
   * List of existing emails associated with the contact.
   */
  emails: ExistingEmail[];
  /**
   * List of existing dates associated with the contact.
   */
  dates: ExistingDate[];
  /**
   * List of existing phone numbers associated with the contact.
   */
  phones: ExistingPhone[];
  /**
   * List of existing extra names associated with the contact.
   * @platform android
   */
  extraNames: ExistingExtraName[];
  /**
   * List of existing postal addresses associated with the contact.
   */
  addresses: ExistingAddress[];
  /**
   * List of existing relations associated with the contact.
   */
  relations: ExistingRelation[];
  /**
   * List of existing URL addresses associated with the contact.
   */
  urlAddresses: ExistingUrlAddress[];
  /**
   * List of existing social profiles associated with the contact.
   */
  socialProfiles: ExistingSocialProfile[];
  /**
   * List of existing instant messaging addresses associated with the contact.
   * @platform ios
   */
  imAddresses: ExistingImAddress[];
};