utiller 1.0.395 → 1.0.397

package/lib/utiller/index.js

@@ -699,6 +699,156 @@ var Utiller = /*#__PURE__*/function () {
       var factor = Math.pow(10, precision);
       return Math.ceil(a * b * factor) / factor;
     });
+    /**
+     * 根據課程資訊生成 Google Calendar 的行事曆新增連結。
+     * @param {object} event - 行程物件。
+     * @param {string} event.title - 行程主題 (e.g., '吉他課')。
+     * @param {string} event.startDate - 開始日期 (e.g., '2025/11/10')。
+     * @param {string} event.startTime - 開始時間 (e.g., '14:00')。
+     * @param {string} event.endDate - 結束日期 (e.g., '2025/11/10')。
+     * @param {string} event.endTime - 結束時間 (e.g., '16:00')。
+     * @param {string} event.location - 地點/地址 (e.g., '台北市大安區信義路三段 162 號')。
+     * @param {string} event.details - 描述/備註 (e.g., '請攜帶吉他，並預習第5頁。')。
+     * @returns {string} Google Calendar 的新增連結。
+     */
+    (0, _defineProperty2["default"])(this, "generateGoogleCalendarLink", function (_ref4) {
+      var title = _ref4.title,
+        startDate = _ref4.startDate,
+        startTime = _ref4.startTime,
+        endDate = _ref4.endDate,
+        endTime = _ref4.endTime,
+        location = _ref4.location,
+        details = _ref4.details;
+      // 使用 moment 結合日期和時間，並格式化為 YYYYMMDDTHHMMSS
+      // 注意: 日期格式已從 YYYY-MM-DD 變更為 YYYY/MM/DD
+      var startDateTime = (0, _momentTimezone["default"])("".concat(startDate, " ").concat(startTime), "YYYY/MM/DD HH:mm").format("YYYYMMDDTHHMMSS");
+      var endDateTime = (0, _momentTimezone["default"])("".concat(endDate, " ").concat(endTime), "YYYY/MM/DD HH:mm").format("YYYYMMDDTHHMMSS");
+
+      // 進行 URL 編碼
+      var encodedTitle = encodeURIComponent(title);
+      var encodedLocation = encodeURIComponent(location);
+      var encodedDetails = encodeURIComponent(details);
+
+      // --- Google Calendar 連結 (使用 https://calendar.google.com/calendar/r/eventedit) ---
+      var googleCalendarLink = "https://calendar.google.com/calendar/r/eventedit?" + "text=".concat(encodedTitle) + "&dates=".concat(startDateTime, "/").concat(endDateTime) + "&details=".concat(encodedDetails) + "&location=".concat(encodedLocation) + "&ctz=Asia/Taipei" + // 台灣時區
+      "&trp=true"; // 設為忙碌 (Busy)
+
+      return googleCalendarLink;
+    });
+    /**
+     * 根據課程資訊生成 TimeTree 的行事曆新增連結。
+     * (此函式不需要 moment.js，但維持其結構)
+     * @param {object} event - 行程物件。
+     * @param {string} event.title - 行程主題 (e.g., '吉他課')。
+     * @param {string} event.startDate - 開始日期 (YYYY/MM/DD, e.g., '2025/11/10')。
+     * @param {string} event.startTime - 開始時間 (HH:MM, e.g., '14:00')。
+     * @param {string} event.endDate - 結束日期 (YYYY/MM/DD, e.g., '2025/11/10')。
+     * @param {string} event.endTime - 結束時間 (HH:MM, e.g., '16:00')。
+     * @param {string} [event.location=''] - 地點/地址 (選填)。
+     * @param {string} [event.memo=''] - 描述/備註 (選填，TimeTree 使用 'memo')。
+     * @returns {string} TimeTree 行事曆新增連結。
+     */
+    (0, _defineProperty2["default"])(this, "generateTimeTreeLink", function (_ref5) {
+      var title = _ref5.title,
+        startDate = _ref5.startDate,
+        startTime = _ref5.startTime,
+        endDate = _ref5.endDate,
+        endTime = _ref5.endTime,
+        _ref5$location = _ref5.location,
+        location = _ref5$location === void 0 ? "" : _ref5$location,
+        _ref5$memo = _ref5.memo,
+        memo = _ref5$memo === void 0 ? "" : _ref5$memo;
+      // 進行 URL 編碼
+      var encodedTitle = encodeURIComponent(title);
+      var encodedLocation = encodeURIComponent(location);
+      var encodedMemo = encodeURIComponent(memo);
+
+      // TimeTree 網址結構相對簡單，直接使用模板字串
+      // 注意: TimeTree 連結直接使用 YYYY-MM-DD 格式，故此函式仍傳遞原始 YYYY/MM/DD 字串
+      // 在實際應用中，如果 TimeTree 不接受 YYYY/MM/DD，則需要在傳入前轉換 (但 TimeTree 連結通常較為寬鬆)
+      var timeTreeLink = "https://timetreeapp.com/plans/new?" + "title=".concat(encodedTitle) + "&start_date=".concat(startDate.replace(/\//g, "-")) + // 將 YYYY/MM/DD 轉換回 YYYY-MM-DD
+      "&start_time=".concat(startTime) + "&end_date=".concat(endDate.replace(/\//g, "-")) + // 將 YYYY/MM/DD 轉換回 YYYY-MM-DD
+      "&end_time=".concat(endTime) + "".concat(location ? "&location=".concat(encodedLocation) : "") + "".concat(memo ? "&memo=".concat(encodedMemo) : "");
+      return timeTreeLink;
+    });
+    /**
+     * 根據課程資訊生成 iCalendar (.ics) 檔案內容。
+     * @param {object} event - 行程物件。
+     * @param {string} event.title - 行程主題。
+     * @param {string} event.startDate - 開始日期 (YYYY/MM/DD)。
+     * @param {string} event.startTime - 開始時間 (HH:MM)。
+     * @param {string} event.endDate - 結束日期 (YYYY/MM/DD)。
+     * @param {string} event.endTime - 結束時間 (HH:MM)。
+     * @param {string} event.location - 地點/地址。
+     * @param {string} event.details - 描述/備註。
+     * @returns {string} 遵循 iCalendar 規範的字串內容。
+     */
+    (0, _defineProperty2["default"])(this, "generateIcsContent", function (_ref6) {
+      var title = _ref6.title,
+        startDate = _ref6.startDate,
+        startTime = _ref6.startTime,
+        endDate = _ref6.endDate,
+        endTime = _ref6.endTime,
+        location = _ref6.location,
+        details = _ref6.details;
+      // 使用 moment-timezone 結合日期和時間，並格式化為 YYYYMMDDTHHMMSS
+      // 注意: 日期格式已從 YYYY-MM-DD 變更為 YYYY/MM/DD
+      var startDateTime = _momentTimezone["default"].tz("".concat(startDate, " ").concat(startTime), "YYYY/MM/DD HH:mm", "Asia/Taipei").format("YYYYMMDDTHHMMSS");
+      var endDateTime = _momentTimezone["default"].tz("".concat(endDate, " ").concat(endTime), "YYYY/MM/DD HH:mm", "Asia/Taipei").format("YYYYMMDDTHHMMSS");
+
+      // DTSTAMP 必須是 UTC 格式 (以 Z 結尾)
+      var stamp = (0, _momentTimezone["default"])().utc().format("YYYYMMDDTHHMMSS") + "Z";
+
+      // 唯一識別碼 (UID)
+      var uid = Date.now().toString(36) + Math.random().toString(36).substring(2, 5) + "@gemini-app.com";
+
+      // 確保內容中的特殊字元（如換行、逗號、分號）被正確逸出
+      var escapeIcs = function escapeIcs(text) {
+        return text.replace(/\\/g, "\\\\").replace(/,/g, "\\,").replace(/;/g, "\\;").replace(/\n/g, "\\n");
+      };
+      var escapedTitle = escapeIcs(title);
+      var escapedLocation = escapeIcs(location);
+      var escapedDetails = escapeIcs(details);
+
+      // 產生 ICS 內容
+      var icsContent = "BEGIN:VCALENDAR\n" + "VERSION:2.0\n" + "PRODID:-//Gemini AI//NONSGML v1.0//EN\n" + "BEGIN:VEVENT\n" + "UID:".concat(uid, "\n") + "DTSTAMP:".concat(stamp, "\n") + // 採用 Asia/Taipei 時區
+      "DTSTART;TZID=Asia/Taipei:".concat(startDateTime, "\n") + "DTEND;TZID=Asia/Taipei:".concat(endDateTime, "\n") + "SUMMARY:".concat(escapedTitle, "\n") + "LOCATION:".concat(escapedLocation, "\n") + "DESCRIPTION:".concat(escapedDetails, "\n") + "END:VEVENT\n" + "END:VCALENDAR";
+
+      // 確保使用 CRLF (\r\n) 換行符號，這是 ICS 規範的要求
+      return icsContent.replace(/\n/g, "\r\n");
+    });
+    /**
+     * 根據行程物件，生成所有主要的行事曆新增連結 (Google, TimeTree, iCalendar/ICS)。
+     * @param {object} event - 行程物件。
+     * @param {string} event.title - 行程主題。
+     * @param {string} event.startDate - 開始日期 (YYYY/MM/DD)。
+     * @param {string} event.startTime - 開始時間 (HH:MM)。
+     * @param {string} event.endDate - 結束日期 (YYYY/MM/DD)。
+     * @param {string} event.endTime - 結束時間 (HH:MM)。
+     * @param {string} event.location - 地點/地址。
+     * @param {string} event.details - 描述/備註。
+     * @returns {{google: string, timeTree: string, ics: string}} 包含所有連結的物件。
+     */
+    (0, _defineProperty2["default"])(this, "generateAllCalendarLinks", function (event) {
+      // 1. Google Calendar Link
+      var googleLink = _this.generateGoogleCalendarLink(event);
+
+      // 2. TimeTree Link
+      // TimeTree 使用 'memo' 參數，因此將 event.details 映射到 memo
+      var timeTreeEvent = _objectSpread(_objectSpread({}, event), {}, {
+        memo: event.details
+      });
+      var timeTreeLink = _this.generateTimeTreeLink(timeTreeEvent);
+
+      // 3. iCalendar (ICS) Link (Data URI 格式，用於 iOS/Outlook/下載)
+      var icsContent = _this.generateIcsContent(event);
+      var icsLink = "data:text/calendar;charset=utf8,".concat(encodeURIComponent(icsContent));
+      return {
+        google: googleLink,
+        timeTree: timeTreeLink,
+        ics: icsLink // iCalendar 連結
+      };
+    });
     /**
      * @param {Array<Object>} current - 要更新的目標陣列
      * @param {Array<Object>} reference - 用來替換屬性的參照陣列
@@ -3987,9 +4137,9 @@ var Utiller = /*#__PURE__*/function () {
     key: "mutateRemoveKeys",
     value: function mutateRemoveKeys(array, keysToRemove) {
       _lodash["default"].forEach(array, function (obj, index) {
-        var filtered = Object.fromEntries(Object.entries(obj).filter(function (_ref5) {
-          var _ref6 = (0, _slicedToArray2["default"])(_ref5, 1),
-            key = _ref6[0];
+        var filtered = Object.fromEntries(Object.entries(obj).filter(function (_ref8) {
+          var _ref9 = (0, _slicedToArray2["default"])(_ref8, 1),
+            key = _ref9[0];
           return !keysToRemove.includes(key);
         }));
         // 原地替換每個 object 的 key
@@ -4016,9 +4166,9 @@ var Utiller = /*#__PURE__*/function () {
     key: "removeKeysFromArrayObjects",
     value: function removeKeysFromArrayObjects(array, keysToRemove) {
       return _lodash["default"].map(array, function (obj) {
-        return Object.fromEntries(Object.entries(obj).filter(function (_ref7) {
-          var _ref8 = (0, _slicedToArray2["default"])(_ref7, 1),
-            key = _ref8[0];
+        return Object.fromEntries(Object.entries(obj).filter(function (_ref10) {
+          var _ref11 = (0, _slicedToArray2["default"])(_ref10, 1),
+            key = _ref11[0];
           return !keysToRemove.includes(key);
         }));
       });
@@ -4077,10 +4227,10 @@ var Utiller = /*#__PURE__*/function () {
       var predict = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : function (attr) {
         return attr.checked !== true;
       };
-      return _lodash["default"].fromPairs(_lodash["default"].toPairs(obj).filter(function (_ref9) {
-        var _ref10 = (0, _slicedToArray2["default"])(_ref9, 2),
-          _ = _ref10[0],
-          value = _ref10[1];
+      return _lodash["default"].fromPairs(_lodash["default"].toPairs(obj).filter(function (_ref12) {
+        var _ref13 = (0, _slicedToArray2["default"])(_ref12, 2),
+          _ = _ref13[0],
+          value = _ref13[1];
         return predict(value);
       }));
     }
@@ -4276,9 +4426,9 @@ var Utiller = /*#__PURE__*/function () {
   }, {
     key: "getTSOfSpecificDate",
     value: function getTSOfSpecificDate(dateStr) {
-      var _ref11 = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {},
-        _ref11$end = _ref11.end,
-        end = _ref11$end === void 0 ? false : _ref11$end;
+      var _ref14 = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {},
+        _ref14$end = _ref14.end,
+        end = _ref14$end === void 0 ? false : _ref14$end;
       return Number((0, _lodash["default"])(dateStr).thru(function (str) {
         return (0, _momentTimezone["default"])(str.split("(")[0], "YYYY/MM/DD");
       }).thru(function (m) {
@@ -4439,15 +4589,117 @@ var Utiller = /*#__PURE__*/function () {
       array.length = 0;
 
       // 重建結構
-      Object.entries(resultMap).forEach(function (_ref12) {
-        var _ref13 = (0, _slicedToArray2["default"])(_ref12, 2),
-          key = _ref13[0],
-          value = _ref13[1];
+      Object.entries(resultMap).forEach(function (_ref15) {
+        var _ref16 = (0, _slicedToArray2["default"])(_ref15, 2),
+          key = _ref16[0],
+          value = _ref16[1];
         array.push((0, _defineProperty2["default"])({}, key, value));
       });
       return array;
     }
 
+    /**
+     * 將時間字串解析為物件，回傳 {startDate, startTime, endDate, endTime}
+     *
+     * 支援格式：
+     * 1. '2025/11/10 (一)｜13:00-15:00'
+     *    => { startDate:'2025/11/10', startTime:'13:00', endDate:'2025/11/10', endTime:'15:00' }
+     *
+     * 2. '2025/11/10 (一) 13:00 - 2025/11/12 (三) 15:00'
+     *    => { startDate:'2025/11/10', startTime:'13:00', endDate:'2025/11/12', endTime:'15:00' }
+     *
+     * @param {string} input - 欲解析的時間字串
+     * @returns {{startDate: string, startTime: string, endDate: string, endTime: string}} 解析後的時間物件
+     *
+     * @example
+     * getObjectOfStartEndDateTime('2025/11/10 (一)｜13:00-15:00');
+     * // => { startDate:'2025/11/10', startTime:'13:00', endDate:'2025/11/10', endTime:'15:00' }
+     *
+     * @example
+     * getObjectOfStartEndDateTime('2025/11/10 (一) 13:00 - 2025/11/12 (三) 15:00');
+     * // => { startDate:'2025/11/10', startTime:'13:00', endDate:'2025/11/12', endTime:'15:00' }
+     */
+  }, {
+    key: "getObjectOfStartEndDateTime",
+    value: function getObjectOfStartEndDateTime(input) {
+      if (!input || typeof input !== "string") {
+        return {
+          startDate: "",
+          startTime: "",
+          endDate: "",
+          endTime: ""
+        };
+      }
+
+      // 將全形符號與多餘空白轉換為標準形式
+      var cleaned = input.replace(/｜/g, " ").replace(/－/g, "-") // 全形破折號轉半形
+      .replace(/\s+/g, " ").trim();
+
+      // 跨日期格式 (例：2025/11/10 13:00 - 2025/11/12 15:00)
+      var crossDatePattern = /(\d{4}\/\d{1,2}\/\d{1,2})(?:\s*\([^)]*\))?\s*(\d{2}:\d{2})\s*-\s*(\d{4}\/\d{1,2}\/\d{1,2})(?:\s*\([^)]*\))?\s*(\d{2}:\d{2})/;
+
+      // 同日期格式 (例：2025/11/10 13:00 - 15:00)
+      var sameDatePattern = /(\d{4}\/\d{1,2}\/\d{1,2})(?:\s*\([^)]*\))?\s*(\d{2}:\d{2})\s*-\s*(\d{2}:\d{2})/;
+      var startDate, startTime, endDate, endTime;
+      if (crossDatePattern.test(cleaned)) {
+        var _cleaned$match = cleaned.match(crossDatePattern);
+        var _cleaned$match2 = (0, _slicedToArray2["default"])(_cleaned$match, 5);
+        startDate = _cleaned$match2[1];
+        startTime = _cleaned$match2[2];
+        endDate = _cleaned$match2[3];
+        endTime = _cleaned$match2[4];
+      } else if (sameDatePattern.test(cleaned)) {
+        var _cleaned$match3 = cleaned.match(sameDatePattern);
+        var _cleaned$match4 = (0, _slicedToArray2["default"])(_cleaned$match3, 4);
+        startDate = _cleaned$match4[1];
+        startTime = _cleaned$match4[2];
+        endTime = _cleaned$match4[3];
+        endDate = startDate;
+      } else {
+        return {
+          startDate: "",
+          startTime: "",
+          endDate: "",
+          endTime: ""
+        };
+      }
+
+      // 將日期時間轉為可比較的 Date 物件
+      var start = new Date("".concat(startDate, " ").concat(startTime));
+      var end = new Date("".concat(endDate, " ").concat(endTime));
+      if (end < start) {
+        throw new Error("End time cannot be earlier than start time: ".concat(input));
+      }
+      return {
+        startDate: startDate,
+        startTime: startTime,
+        endDate: endDate,
+        endTime: endTime
+      };
+    }
+  }, {
+    key: "getFilteredHeraPeriods",
+    value:
+    // 範例用法 (請確保 moment.js 已載入)
+    /*
+      const myEvent = {
+          title: '吉他課 (Moment.js)',
+          startDate: '2026/01/15', // 使用新的 YYYY/MM/DD 格式
+          startTime: '10:30',
+          endDate: '2026/01/15',
+          endTime: '12:00',
+          location: '新北市板橋區縣民大道一段 1 號',
+          details: 'Moment.js 測試：請記得帶譜架。'
+      };
+       if (typeof moment !== 'undefined') {
+          const links = generateAllCalendarLinks(myEvent);
+          console.log('--- 使用 Moment.js 生成的連結 ---');
+          console.log(links);
+      } else {
+          console.warn('moment.js 函式庫未載入，無法執行。');
+      }
+      */
+
     /** ============== 排課系統公式 開始 ============== */
 
     /**
@@ -4465,9 +4717,7 @@ var Utiller = /*#__PURE__*/function () {
      * 2. idOfBooze和idOfVariant為PK， 重複的只保留一組
      * 3. 回傳filter array,(反查出哪些課程重複會用到其他資訊)
      * */
-  }, {
-    key: "getFilteredHeraPeriods",
-    value: function getFilteredHeraPeriods(arr, idOfCurrentBooze) {
+    function getFilteredHeraPeriods(arr, idOfCurrentBooze) {
       return _lodash["default"].chain(arr)
       // 1️⃣ 刪掉 idOfBooze 等於目標值的項目
       .filter(function (item) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "utiller",
-  "version": "1.0.395",
+  "version": "1.0.397",
   "description": "",
   "main": "index.js",
   "scripts": {

package/template/sample.package.json

@@ -11,7 +11,7 @@
   "license": "ISC",
   "dependencies": {
     "configerer": "^1.0.23",
-    "utiller": "^1.0.394",
+    "utiller": "^1.0.396",
     "linepayer": "^1.0.15",
     "databazer": "^1.0.17",
     "lodash": "^4.17.20",