@astralweb/nova-recently-viewed 0.0.1 → 1.0.1

package/LICENSE

@@ -1,23 +1,24 @@
-Proprietary License
+PROPRIETARY LICENSE
 
-Copyright (c) 2024 Astral Web
+Copyright (c) 2025 Astral Web
 
 This software and associated documentation files (the "Software") are proprietary 
-to Astral Web and are intended for internal use only.
+to Astral Web and are intended solely for internal use by Astral Web and its 
+authorized personnel.
 
 RESTRICTIONS:
-- This Software is for internal use by Astral Web employees and authorized personnel only.
-- No part of this Software may be reproduced, distributed, or transmitted in any form 
-  or by any means, including photocopying, recording, or other electronic or mechanical 
-  methods, without the prior written permission of Astral Web.
-- This Software may not be used outside of Astral Web's business operations.
-- Reverse engineering, decompilation, or disassembly of this Software is prohibited.
+- The Software may not be copied, modified, distributed, or used by any party 
+  other than Astral Web without express written permission.
+- No part of the Software may be reverse engineered, decompiled, or disassembled.
+- The Software may not be sublicensed, sold, or transferred to any third party.
+- Use of the Software is restricted to internal business operations of Astral Web.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, 
-INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A 
-PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL ASTRAL WEB BE LIABLE FOR 
-ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR 
-OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR 
-OTHER DEALINGS IN THE SOFTWARE.
+DISCLAIMER:
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL 
+ASTRAL WEB BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN 
+AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
-For permissions beyond the scope of this license, please contact Astral Web.
+For licensing inquiries, contact: Astral Web

package/README.md

@@ -1,10 +1,10 @@
-# Recently Viewed 套件使用指南
+# Recently Viewed 模組使用指南
 
 > ⚠️ **內部使用套件** - 此套件僅供 Astral Web 內部使用，未經授權不得用於其他用途。
 
 ## 概覽
 
-Recently Viewed 套件採用 Composable 模式設計，提供完整的最近瀏覽商品功能。支援本地儲存管理、後端同步、訪客與會員資料合併，以及靈活的配置選項。
+Recently Viewed 是一個 Nuxt 3 模組，提供完整的最近瀏覽商品追蹤與管理功能。模組採用 Nuxt Module 架構設計，支援本地儲存與伺服器同步、訪客與會員資料自動合併，並提供靈活的配置選項。
 
 ## 安裝與設定
 
@@ -16,296 +16,159 @@ Recently Viewed 套件採用 Composable 模式設計，提供完整的最近瀏
 yarn add @astralweb/nova-recently-viewed
 ```
 
-### 2. middleware 擴充
+### 2. Middleware 擴充
+
 ```typescript
 // apps/server/extendApiMethods/index.ts
 
 export {
-  recentlyViewedProducts, 
+  recentlyViewedProducts,
   addRecentlyViewedProducts,
 } from '@astralweb/nova-recently-viewed/api';
 ```
 
-### 3. SDK 設定
-```typescript
-// apps/web/plugins/sdk.client.ts
-import { setSdk } from '@astralweb/nova-recently-viewed/api';
-
-export default defineNuxtPlugin(() => {
-  // 設定 SDK 實例
-  setSdk(sdkInstance);
-});
-```
+### 3. 註冊模組
 
-### 4. 新增 nuxt.config.ts 設定
 ```typescript
+// apps/web/nuxt.config.ts
+
 export default defineNuxtConfig({
-  vite: {
-    ssr: {
-      noExternal: ['@astralweb/nova-recently-viewed'],
-    },
-  },
+  modules: [
+    '@astralweb/nova-recently-viewed',
+  ],
 })
 ```
 
-## 組件基本使用
+## 架構設計
+
+### 三層架構
+
+1. **API Layer** (`useRecentlyViewedApi`)
+   - 處理與 GraphQL 後端的通信
+   - 提供 `syncToServer` 和 `fetchFromServer` 方法
 
-### 在商品頁面中使用
+2. **Storage Layer** (`useRecentlyViewedStorage`)
+   - 管理本地儲存與核心業務邏輯
+   - 處理訪客/會員資料合併
+   - 提供完整的 CRUD 操作
+
+3. **List Layer** (`useRecentlyViewedList`)
+   - 高階封裝，適用於產品詳情頁
+   - 自動處理初始化、登入狀態變化、SKU 更新
+   - 提供開箱即用的體驗
+
+## 使用方式
+
+適合產品詳情頁，自動處理所有邏輯。
 
 ```vue
 <template>
-  <div>
-    <!-- 商品內容 -->
-    <ProductDetails :product="product" />
-    
-    <!-- 最近瀏覽商品區塊 -->
-    <section v-if="recentlyViewedSkus && recentlyViewedSkus.length > 0" class="mb-10">
-      <ProductSlider
-        :title="t('product.section.recentlyViewed')"
-        :products-sku="recentlyViewedSkus"
-        maintain-order
-      />
-    </section>
-  </div>
+  <ProductSlider :products-sku="recentlyViewedSkus" />
 </template>
 
 <script setup lang="ts">
-import { useRecentlyViewed } from '@astralweb/nova-recently-viewed';
-
-const route = useRoute();
-const { t } = useI18n();
-
-// 獲取當前商品資料
-const { data: product } = await useAsyncData('product', () => 
-  fetchProduct(route.params.slug)
-);
-
-// 使用最近瀏覽功能
-const { 
-  addRecentlyViewed, 
-  getRecentlyViewedSkus, 
-  mergeGuestToCustomer,
-  isLoggedIn 
-} = useRecentlyViewed();
-
-const recentlyViewedSkus = ref<string[]>([]);
-
-// 初始化最近瀏覽商品
-const initializeRecentlyViewed = async (currentSku: string) => {
-  if (!currentSku) return;
-
-  if (isLoggedIn.value) {
-    // 登入用戶：先合併資料 > 再添加當前商品 > 最後獲取列表
-    await mergeGuestToCustomer();
-    await addRecentlyViewed(currentSku);
-    recentlyViewedSkus.value = await getRecentlyViewedSkus(currentSku);
-  } else {
-    // 訪客用戶：先顯示現有資料 > 再添加當前商品
-    recentlyViewedSkus.value = await getRecentlyViewedSkus(currentSku);
-    await addRecentlyViewed(currentSku);
-  }
-};
-
-// 在商品頁面掛載時調用
-onMounted(() => {
-  if (product.value?.sku) {
-    initializeRecentlyViewed(product.value.sku);
-  }
+const { recentlyViewedSkus } = useRecentlyViewedList({
+  currentSku: computed(() => product.value?.sku ?? ''),
+  isLoggedIn: computed(() => !!user.value),
+  enableServerSync: true,
 });
 </script>
 ```
 
-### 登入狀態處理
+**自動處理：**
+- ✅ 組件掛載時初始化
+- ✅ SKU 變化時更新列表
+- ✅ 登入狀態變化時合併資料
+- ✅ 本地緩存優化
 
-```typescript
-<script setup lang="ts">
-import { useRecentlyViewed } from '@astralweb/nova-recently-viewed';
 
-const { mergeGuestToCustomer, isLoggedIn } = useRecentlyViewed();
+## API 參考
+
+### useRecentlyViewedList
 
-// 監聽登入狀態變化
-watch(isLoggedIn, async (newValue, oldValue) => {
-  // 當用戶從未登入變為登入狀態時，合併訪客資料
-  if (!oldValue && newValue) {
-    await mergeGuestToCustomer();
-  }
+```typescript
+const { recentlyViewedSkus } = useRecentlyViewedList({
+  currentSku: Ref<string> | ComputedRef<string>,
+  isLoggedIn: ComputedRef<boolean>,
+  maxItems?: number,              // 預設：20
+  guestStorageKey?: string,       // 預設：'recently-viewed-guest'
+  customerStorageKey?: string,    // 預設：'recently-viewed-customer'
+  enableServerSync?: boolean,     // 預設：true
+  autoInit?: boolean,             // 預設：true
 });
-</script>
 ```
 
-## API 參考
+**返回值：**
+- `recentlyViewedSkus`: `Ref<string[]>` - 最近瀏覽商品的 SKU 列表
 
-### Composables
+### useRecentlyViewedStorage
 
-#### useRecentlyViewed
+核心 composable，提供完整的儲存管理功能。
 
 ```typescript
 const {
   addRecentlyViewed,
   getRecentlyViewedSkus,
+  getSkusFromLocalStorage,
   clearAllRecentlyViewed,
   mergeGuestToCustomer,
-  isLoggedIn
-} = useRecentlyViewed(
-  config?: RecentlyViewedConfig,
-  isLoggedIn?: ComputedRef<boolean>
-): UseRecentlyViewedReturn;
-```
-
-##### 參數
-
-| 參數 | 類型 | 預設值 | 說明 |
-|------|------|--------|------|
-| `config` | `RecentlyViewedConfig` | `{}` | 可選的配置選項 |
-| `isLoggedIn` | `ComputedRef<boolean>` | `computed(() => false)` | 可選的登入狀態 |
-
-##### 配置選項 (RecentlyViewedConfig)
-
-| 屬性 | 類型 | 預設值 | 說明 |
-|------|------|--------|------|
-| `maxItems` | `number` | `20` | 最大儲存商品數量 |
-| `guestStorageKey` | `string` | `'recently_viewed_products_guest'` | 訪客本地儲存鍵 |
-| `customerStorageKey` | `string` | `'recently_viewed_products_customer'` | 會員本地儲存鍵 |
-| `enableServerSync` | `boolean` | `true` | 是否啟用後端同步 |
-
-##### 返回值 (UseRecentlyViewedReturn)
-
-| 方法 | 類型 | 說明 |
-|------|------|------|
-| `addRecentlyViewed` | `(sku: string) => Promise<void>` | 添加商品到最近瀏覽 |
-| `getRecentlyViewedSkus` | `(excludeSku?: string) => Promise<string[]>` | 獲取最近瀏覽商品 SKU 列表 |
-| `clearAllRecentlyViewed` | `() => Promise<void>` | 清除所有最近瀏覽記錄 |
-| `mergeGuestToCustomer` | `() => Promise<void>` | 合併訪客資料到會員帳戶 |
-| `isLoggedIn` | `ComputedRef<boolean>` | 登入狀態響應式引用 |
-
-### API Functions
-
-#### Web 客戶端 API
-
-```typescript
-import { 
-  fetchRecentlyViewedWeb, 
-  addRecentlyViewedWeb, 
-  setSdk, 
-  getSdk 
-} from '@astralweb/nova-recently-viewed/api';
-
-// 設定 SDK
-setSdk(sdkInstance);
-
-// 獲取最近瀏覽商品
-const products = await fetchRecentlyViewedWeb();
-
-// 添加最近瀏覽商品
-const result = await addRecentlyViewedWeb([
-  { product_sku: 'SKU001', viewed_at: 1234567890 }
-]);
+  isLoggedIn,
+} = useRecentlyViewedStorage(config, isLoggedIn);
 ```
 
-#### Middleware API
-
+**配置選項：**
 ```typescript
-import { 
-  recentlyViewedProducts, 
-  addRecentlyViewedProducts 
-} from '@astralweb/nova-recently-viewed/api';
-
-// 在 middleware 中使用
-export const customRecentlyViewedProducts = async (context, variables) => {
-  return await recentlyViewedProducts(context, variables);
-};
-
-export const customAddRecentlyViewedProducts = async (context, variables) => {
-  return await addRecentlyViewedProducts(context, variables);
-};
-```
-
-### 類型定義
-
-#### 核心類型
-
-```typescript
-// 最近瀏覽商品項目
-interface RecentlyViewedItem {
-  sku: string;
-  viewedAt: number; // JavaScript timestamp (毫秒)
-}
-
-// API 輸入類型
-interface AddRecentlyViewedInputItem {
-  product_sku: string;
-  viewed_at: number; // Unix timestamp (秒)
-}
-
-// API 回應類型
-interface AddRecentlyViewedResponse {
-  success: boolean;
-  message?: string;
+interface RecentlyViewedConfig {
+  maxItems?: number;              // 最多儲存數量（預設：20）
+  guestStorageKey?: string;       // 訪客 localStorage key
+  customerStorageKey?: string;    // 會員 localStorage key
+  enableServerSync?: boolean;     // 啟用伺服器同步（預設：true）
 }
 ```
 
-## 故障排除
-
-### 常見問題
+**方法：**
+- `addRecentlyViewed(sku: string): Promise<void>` - 添加商品到最近瀏覽
+- `getRecentlyViewedSkus(excludeSku?: string): Promise<string[]>` - 獲取 SKU 列表（伺服器優先）
+- `getSkusFromLocalStorage(excludeSku?: string): string[]` - 從本地儲存獲取 SKU 列表
+- `clearAllRecentlyViewed(): void` - 清除所有記錄
+- `mergeGuestToCustomer(): Promise<void>` - 合併訪客資料到會員帳戶
 
-#### 1. 最近瀏覽商品不顯示
+### useRecentlyViewedApi
 
-**問題**：調用 `getRecentlyViewedSkus()` 返回空陣列
-
-**解決方案**：
-- 檢查是否正確調用了 `addRecentlyViewed()`
-- 確認 localStorage 是否可用
-- 檢查是否有 JavaScript 錯誤
+API 層 composable，處理與後端的通信。
 
 ```typescript
-// 調試用的詳細日誌
-const debugRecentlyViewed = async () => {
-  console.log('Browser check:', typeof window !== 'undefined');
-  console.log('LocalStorage check:', typeof localStorage !== 'undefined');
-  
-  const skus = await getRecentlyViewedSkus();
-  console.log('Recently viewed SKUs:', skus);
-};
+const {
+  syncToServer,
+  fetchFromServer,
+} = useRecentlyViewedApi();
 ```
 
-#### 2. 後端同步失敗
+**方法：**
+- `syncToServer(input: AddRecentlyViewedInputItem[]): Promise<void>` - 同步資料到伺服器
+- `fetchFromServer(): Promise<AddRecentlyViewedInputItem[]>` - 從伺服器獲取資料
 
-**問題**：商品添加到本地但不同步到後端
+## 工作原理
 
-**解決方案**：
-- 檢查 SDK 是否正確設定
-- 確認 middleware 是否正確導出
-- 檢查網路連接和 API 權限
+### 訪客模式
 
-```typescript
-// 檢查 SDK 設定
-try {
-  const sdk = getSdk();
-  console.log('SDK configured:', !!sdk);
-} catch (error) {
-  console.error('SDK not configured:', error);
-}
-```
+- 資料保存在 `localStorage`（key: `recently-viewed-guest`）
+- 不進行伺服器同步
+- 本地去重與數量限制
 
-#### 3. 訪客資料合併問題
+### 登入模式
 
-**問題**：登入後訪客資料沒有合併
+- 主要資料來源：伺服器
+- 本地緩存：加速 UI 更新
+- 新增時：同步到伺服器 → 更新本地緩存
 
-**解決方案**：
-- 確認 `mergeGuestToCustomer()` 在適當時機被調用
-- 檢查登入狀態監聽是否正確設定
+### 登入時資料合併
 
-```typescript
-// 確保合併在登入後執行
-const handleLogin = async () => {
-  // 執行登入邏輯
-  await loginUser();
-  
-  // 登入成功後合併資料
-  await mergeGuestToCustomer();
-};
-```
+1. 讀取訪客 `localStorage` 資料
+2. 同步到伺服器（合併到會員帳戶）
+3. 清除訪客資料
+4. 從伺服器獲取最新資料
 
-## 授權聲明
+## 授權
 
 此套件僅供 Astral Web 內部使用，未經授權不得用於其他用途。

package/dist/module.d.mts

@@ -0,0 +1,5 @@
+import * as _nuxt_schema from '@nuxt/schema';
+
+declare const _default: _nuxt_schema.NuxtModule<_nuxt_schema.ModuleOptions, _nuxt_schema.ModuleOptions, false>;
+
+export { _default as default };

package/dist/module.json

@@ -0,0 +1,12 @@
+{
+  "name": "recently-viewed",
+  "configKey": "recentlyViewed",
+  "compatibility": {
+    "nuxt": ">=3.0.0"
+  },
+  "version": "1.0.1",
+  "builder": {
+    "@nuxt/module-builder": "1.0.2",
+    "unbuild": "3.6.1"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,26 @@
+import { defineNuxtModule, createResolver, addImports } from '@nuxt/kit';
+
+const module = defineNuxtModule({
+  meta: {
+    name: "recently-viewed",
+    configKey: "recentlyViewed",
+    compatibility: {
+      nuxt: ">=3.0.0"
+    }
+  },
+  // Default configuration options of the Nuxt module
+  defaults: {},
+  setup(_options, _nuxt) {
+    const resolver = createResolver(import.meta.url);
+    addImports({
+      name: "useRecentlyViewedStorage",
+      from: resolver.resolve("./runtime/composables/useRecentlyViewedStorage")
+    });
+    addImports({
+      name: "useRecentlyViewedList",
+      from: resolver.resolve("./runtime/composables/useRecentlyViewedList")
+    });
+  }
+});
+
+export { module as default };

package/dist/{api → runtime/api}/extendMiddleware.d.ts

@@ -1,6 +1,6 @@
-import { ApolloQueryResult } from '@apollo/client/core';
-import { Context, TObject } from '@vue-storefront/middleware';
-import { AddRecentlyViewedInputItem, AddRecentlyViewedResponse } from '../types';
+import type { ApolloQueryResult, FetchResult } from '@apollo/client/core';
+import type { Context, TObject } from '@vue-storefront/middleware';
+import type { AddRecentlyViewedInputItem, AddRecentlyViewedResponse } from '../types/index.js';
 /**
  * 查詢最近瀏覽商品
  */
@@ -10,7 +10,6 @@ export declare const recentlyViewedProducts: (context: Context, variables: TObje
 /**
  * 添加商品到最近瀏覽列表
  */
-export declare const addRecentlyViewedProducts: (context: Context, variables: TObject) => Promise<ApolloQueryResult<{
+export declare const addRecentlyViewedProducts: (context: Context, variables: TObject) => Promise<FetchResult<{
     addRecentlyViewedProducts: AddRecentlyViewedResponse;
 }>>;
-//# sourceMappingURL=extendMiddleware.d.ts.map

package/dist/runtime/api/extendMiddleware.js

@@ -0,0 +1,64 @@
+import { consola } from "consola";
+import { gql } from "graphql-tag";
+const getHeaders = (context, customHeaders = {}) => {
+  const { getCustomerToken, getStore, getCurrency } = context.config.state;
+  return {
+    ...getCustomerToken() && { Authorization: `Bearer ${getCustomerToken()}` },
+    ...getStore() && { store: getStore() },
+    ...getCurrency() && { "Content-Currency": getCurrency() },
+    ...customHeaders
+  };
+};
+export const recentlyViewedProducts = async (context, variables) => {
+  const { client } = context;
+  try {
+    return await client.query({
+      query: gql`
+        query recentlyViewedProducts {
+          recentlyViewedProducts {
+            product_sku
+            viewed_at
+          }
+        }
+      `,
+      variables,
+      context: { headers: getHeaders(context) }
+    });
+  } catch (error) {
+    const typedError = error;
+    throw typedError;
+  }
+};
+export const addRecentlyViewedProducts = async (context, variables) => {
+  const { client } = context;
+  try {
+    return await client.mutate({
+      mutation: gql`
+        mutation addRecentlyViewedProducts($input: [RecentlyViewedProductInput!]!) {
+          addRecentlyViewedProducts(input: $input) {
+            success
+            message
+          }
+        }
+      `,
+      variables,
+      context: { headers: getHeaders(context) }
+    });
+  } catch (error) {
+    const typedError = error;
+    if (typedError.graphQLErrors) {
+      consola.debug(typedError);
+      return {
+        errors: typedError.graphQLErrors,
+        data: null
+      };
+    }
+    const networkError = typedError.networkError;
+    if (networkError && "result" in networkError) {
+      consola.error(networkError.result);
+      throw networkError.result;
+    }
+    consola.error(typedError);
+    throw error;
+  }
+};

package/dist/runtime/api/index.d.ts

@@ -0,0 +1 @@
+export * from './extendMiddleware.js';

package/dist/runtime/api/index.js

@@ -0,0 +1 @@
+export * from "./extendMiddleware.js";

package/dist/runtime/composables/index.d.ts

@@ -0,0 +1,3 @@
+export * from './useRecentlyViewedApi.js';
+export * from './useRecentlyViewedStorage.js';
+export * from './useRecentlyViewedList.js';

package/dist/runtime/composables/index.js

@@ -0,0 +1,3 @@
+export * from "./useRecentlyViewedApi.js";
+export * from "./useRecentlyViewedStorage.js";
+export * from "./useRecentlyViewedList.js";

package/dist/runtime/composables/useRecentlyViewedApi.d.ts

@@ -0,0 +1,5 @@
+import type { AddRecentlyViewedInputItem } from '../types/index.js';
+export declare function useRecentlyViewedApi(): {
+    syncToServer: (input: AddRecentlyViewedInputItem[]) => Promise<void>;
+    fetchFromServer: () => Promise<AddRecentlyViewedInputItem[]>;
+};

package/dist/runtime/composables/useRecentlyViewedApi.js

@@ -0,0 +1,21 @@
+import { useNuxtApp } from "#app";
+export function useRecentlyViewedApi() {
+  const { sdk } = useNuxtApp().$alokai;
+  const syncToServer = async (input) => {
+    const { errors } = await sdk.magento.addRecentlyViewedProducts({ input });
+    if (errors && errors.length > 0) {
+      throw new Error(errors.map((e) => e.message).join(", "));
+    }
+  };
+  const fetchFromServer = async () => {
+    const { data, errors } = await sdk.magento.recentlyViewedProducts({});
+    if (errors && errors.length > 0) {
+      throw new Error(errors.map((e) => e.message).join(", "));
+    }
+    return data?.recentlyViewedProducts ?? [];
+  };
+  return {
+    syncToServer,
+    fetchFromServer
+  };
+}

package/dist/runtime/composables/useRecentlyViewedList.d.ts

@@ -0,0 +1,2 @@
+import type { UseRecentlyViewedListOptions, UseRecentlyViewedListReturn } from '../types/index.js';
+export declare function useRecentlyViewedList(options: UseRecentlyViewedListOptions): UseRecentlyViewedListReturn;