utiller 1.0.394 → 1.0.396

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);
       }));
     }
@@ -4243,6 +4393,11 @@ var Utiller = /*#__PURE__*/function () {
     value: function isFirestoreAutoId(id) {
       return _lodash["default"].isString(id) && id.length === 20 && /^[A-Za-z0-9]{20}$/.test(id);
     }
+  }, {
+    key: "getAutoIdOfFirestore",
+    value: function getAutoIdOfFirestore() {
+      return this.getRandomHashV2(20);
+    }
   }, {
     key: "getStringOfConvertTimeRange",
     value:
@@ -4271,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) {
@@ -4389,15 +4544,14 @@ var Utiller = /*#__PURE__*/function () {
      * 🧩 範例：
      * ```js
      * const array = [
-     *   { a: { c: 1 } },
-     *   { b: { d: 2 } },
-     *   { a: { f: 3 } }
+     *   { a: { b: { c: 2 } } },
+     *   { b: { d: { g: 1 } }, a: { b: { y: 1 }, h: { e: 1 } } }
      * ];
      *
      * ArrayHelper.mergeArrayByKey(array);
      *
      * console.log(array);
-     * // 👉 [ { a: { c: 1, f: 3 } }, { b: { d: 2 } } ]
+     * // 👉 [ { a: { b: { c: 2, y: 1 }, h: { e: 1 } } }, { b: { d: { g: 1 } } } ]
      * ```
      *
      * @param {Array<Object>} array - 需被合併的物件陣列
@@ -4406,21 +4560,65 @@ var Utiller = /*#__PURE__*/function () {
     function mergeArrayByKey(array) {
       if (!Array.isArray(array)) return array;
 
-      // 1️⃣ 利用 lodash 深層合併所有物件（例如 {a:{x}} + {a:{y}} => {a:{x,y}})
-      var merged = _lodash["default"].merge.apply(_lodash["default"], [{}].concat((0, _toConsumableArray2["default"])(array)));
+      // 收集所有 key 的合併結果
+      var resultMap = {};
+      var _iterator20 = _createForOfIteratorHelper(array),
+        _step20;
+      try {
+        for (_iterator20.s(); !(_step20 = _iterator20.n()).done;) {
+          var obj = _step20.value;
+          if (!_lodash["default"].isPlainObject(obj)) continue;
+          for (var _i16 = 0, _Object$entries = Object.entries(obj); _i16 < _Object$entries.length; _i16++) {
+            var _Object$entries$_i = (0, _slicedToArray2["default"])(_Object$entries[_i16], 2),
+              _key45 = _Object$entries$_i[0],
+              value = _Object$entries$_i[1];
+            if (!resultMap[_key45]) {
+              resultMap[_key45] = _lodash["default"].cloneDeep(value);
+            } else {
+              _lodash["default"].merge(resultMap[_key45], value);
+            }
+          }
+        }
 
-      // 2️⃣ 清空原陣列（mutate）
+        // 清空原陣列（mutate）
+      } catch (err) {
+        _iterator20.e(err);
+      } finally {
+        _iterator20.f();
+      }
       array.length = 0;
 
-      // 3️⃣ 將合併結果重新拆成 [{a:{...}}, {b:{...}}] 結構
-      Object.entries(merged).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;
     }
+  }, {
+    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 函式庫未載入，無法執行。');
+      }
+      */
 
     /** ============== 排課系統公式 開始 ============== */
 
@@ -4439,9 +4637,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.394",
+  "version": "1.0.396",
   "description": "",
   "main": "index.js",
   "scripts": {

package/template/sample.package.json

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