vCard Time Handling

/**
 * VCardTime constructor
 * @param {Object} data - Time initialization data (optional)
 * @param {number} data.year - The year for this date (optional for reduced precision)
 * @param {number} data.month - The month for this date (optional for reduced precision)
 * @param {number} data.day - The day for this date (optional for reduced precision)
 * @param {number} data.hour - The hour for this date (optional for time)
 * @param {number} data.minute - The minute for this date (optional for time)
 * @param {number} data.second - The second for this date (optional for time)
 * @param {ICAL.Timezone|ICAL.UtcOffset} zone - Timezone or UTC offset (optional)
 * @param {string} icaltype - Specific vCard type ("date-and-or-time", "date", "time", "date-time")
 */
class ICAL.VCardTime extends ICAL.Time {
  constructor(data, zone, icaltype);
  
  // Properties
  icalclass: string;                        // Always "vcardtime"
  icaltype: string;                        // "date-and-or-time", "date", "time", "date-time"
  zone: ICAL.Timezone | ICAL.UtcOffset;   // Timezone or UTC offset
}

const ICAL = require('ical.js');

// Create a full date-time with UTC offset
const vCardDateTime = new ICAL.VCardTime({
  year: 2023,
  month: 6,
  day: 15,
  hour: 14,
  minute: 30,
  second: 0
}, ICAL.UtcOffset.fromString('-05:00'), 'date-time');

// Create a date-only value
const vCardDate = new ICAL.VCardTime({
  year: 2023,
  month: 6,
  day: 15
}, null, 'date');

// Create a time-only value
const vCardTime = new ICAL.VCardTime({
  hour: 14,
  minute: 30,
  second: 0
}, null, 'time');

// Create a reduced precision date (year and month only)
const vCardPartialDate = new ICAL.VCardTime({
  year: 2023,
  month: 6
}, null, 'date-and-or-time');

/**
 * Parse vCard date/time string into VCardTime instance
 * @param {string} value - vCard date/time string to parse
 * @param {string} icalType - Expected vCard type for parsing context
 * @returns {ICAL.VCardTime} Parsed VCardTime instance
 */
static fromDateAndOrTimeString(value: string, icalType: string): ICAL.VCardTime;

const ICAL = require('ical.js');

// Parse various vCard date/time formats
const fullDateTime = ICAL.VCardTime.fromDateAndOrTimeString('20230615T143000-0500', 'date-time');
console.log(fullDateTime.icaltype); // 'date-time'

const dateOnly = ICAL.VCardTime.fromDateAndOrTimeString('20230615', 'date');
console.log(dateOnly.icaltype); // 'date'

const timeOnly = ICAL.VCardTime.fromDateAndOrTimeString('143000', 'time');
console.log(timeOnly.icaltype); // 'time'

// Reduced precision formats
const yearMonth = ICAL.VCardTime.fromDateAndOrTimeString('2023-06', 'date-and-or-time');
const yearOnly = ICAL.VCardTime.fromDateAndOrTimeString('2023', 'date-and-or-time');

/**
 * Clone the VCardTime instance
 * @returns {ICAL.VCardTime} Cloned VCardTime instance
 */
clone(): ICAL.VCardTime;

/**
 * Get UTC offset in seconds (supports both Timezone and UtcOffset zones)
 * @returns {number} UTC offset in seconds
 */
utcOffset(): number;

/**
 * Convert to vCard-compliant string representation
 * @returns {string} vCard string representation
 */
toICALString(): string;

/**
 * Convert to string representation
 * @returns {string} String representation for vCard format
 */
toString(): string;

const ICAL = require('ical.js');

const vCardTime = new ICAL.VCardTime({
  year: 2023,
  month: 6,
  day: 15,
  hour: 14,
  minute: 30,
  second: 0
}, ICAL.UtcOffset.fromString('-05:00'), 'date-time');

// Clone the time
const clonedTime = vCardTime.clone();
console.log(clonedTime.icalclass); // 'vcardtime'

// Get UTC offset
const offset = vCardTime.utcOffset(); // -18000 (seconds)

// Get vCard string representation
const vCardString = vCardTime.toICALString(); // '20230615T143000-0500'
const stringRep = vCardTime.toString(); // Same as toICALString for vCard format

// With timezone offset
const dateTimeWithOffset = ICAL.VCardTime.fromDateAndOrTimeString('20230615T143000-0500', 'date-time');

// UTC time
const utcDateTime = ICAL.VCardTime.fromDateAndOrTimeString('20230615T143000Z', 'date-time');

// Local time (floating)
const localDateTime = ICAL.VCardTime.fromDateAndOrTimeString('20230615T143000', 'date-time');

// Complete date
const completeDate = ICAL.VCardTime.fromDateAndOrTimeString('20230615', 'date');

// Truncated date formats (date-and-or-time type)
const yearMonth = ICAL.VCardTime.fromDateAndOrTimeString('2023-06', 'date-and-or-time');
const yearOnly = ICAL.VCardTime.fromDateAndOrTimeString('2023', 'date-and-or-time');

// With timezone offset
const timeWithOffset = ICAL.VCardTime.fromDateAndOrTimeString('143000-0500', 'time');

// UTC time
const utcTime = ICAL.VCardTime.fromDateAndOrTimeString('143000Z', 'time');

// Local time
const localTime = ICAL.VCardTime.fromDateAndOrTimeString('143000', 'time');

// Reduced precision time
const hourMinute = ICAL.VCardTime.fromDateAndOrTimeString('1430', 'time');
const hourOnly = ICAL.VCardTime.fromDateAndOrTimeString('14', 'time');

// Can represent any of the above formats
const flexible = ICAL.VCardTime.fromDateAndOrTimeString('2023-06-15T14:30', 'date-and-or-time');

const ICAL = require('ical.js');

// Using UTC offset (common in vCard)
const utcOffset = ICAL.UtcOffset.fromString('-05:00');
const timeWithOffset = new ICAL.VCardTime({
  year: 2023, month: 6, day: 15,
  hour: 14, minute: 30
}, utcOffset, 'date-time');

// Using timezone (when VTIMEZONE is available)
const timezone = ICAL.TimezoneService.get('America/New_York');
const timeWithTimezone = new ICAL.VCardTime({
  year: 2023, month: 6, day: 15,
  hour: 14, minute: 30
}, timezone, 'date-time');

// Get UTC offset works with both
console.log(timeWithOffset.utcOffset()); // -18000
console.log(timeWithTimezone.utcOffset()); // Calculated based on date/time

const ICAL = require('ical.js');

// Year only (for birth years when exact date unknown)
const birthYear = ICAL.VCardTime.fromDateAndOrTimeString('1990', 'date-and-or-time');

// Year and month only
const graduationMonth = ICAL.VCardTime.fromDateAndOrTimeString('2012-05', 'date-and-or-time');

// Month and day only (for anniversaries without year)
const anniversary = ICAL.VCardTime.fromDateAndOrTimeString('--12-25', 'date-and-or-time');

// Time precision variations
const hourOnly = ICAL.VCardTime.fromDateAndOrTimeString('14', 'time');
const hourMinute = ICAL.VCardTime.fromDateAndOrTimeString('14:30', 'time');

const ICAL = require('ical.js');

// Parse a vCard with various date/time properties
const vcardString = `BEGIN:VCARD
VERSION:4.0
FN:John Doe
BDAY:1990-06-15
ANNIVERSARY:--12-25
REV:20230615T143000Z
END:VCARD`;

const jCardData = ICAL.parse(vcardString);
const vcard = new ICAL.Component(jCardData);

// Extract and convert date/time properties
const bdayProp = vcard.getFirstProperty('bday');
if (bdayProp) {
  const birthday = ICAL.VCardTime.fromDateAndOrTimeString(
    bdayProp.getFirstValue(), 
    bdayProp.type
  );
  console.log('Birthday:', birthday.toString());
}

const revProp = vcard.getFirstProperty('rev');
if (revProp) {
  const revision = ICAL.VCardTime.fromDateAndOrTimeString(
    revProp.getFirstValue(),
    revProp.type
  );
  console.log('Last revision:', revision.toString());
}