@huythanh-dev/ht-recommend

Gửi sản phẩm từ backend website của bạn vào HT Recommendation.

Không dùng trong trình duyệt: khoá API là bí mật, lộ ra là người khác ghi đè được toàn bộ sản phẩm của bạn.

Yêu cầu Node 20 trở lên. Dùng được cả import và require.

Cài

npm install @huythanh-dev/ht-recommend

Bắt đầu

import { createClient } from '@huythanh-dev/ht-recommend'

const ht = createClient({
  appId: process.env.HT_APP_ID,
  apiKey: process.env.HT_API_KEY,
  baseUrl: 'https://hta-admin.giavanghomnay.cloud/api/v1/ingest',
})

await ht.saveObjects([
  { id: 'SKU-13', name: 'Vòng tay bạc', price: 1190000, colors: ['Bạc'], inStock: true },
  { id: 'SKU-14', name: 'Nhẫn vàng', price: 4900000, specs: [{ label: 'Tuổi vàng', value: '18K' }] },
])

Sản phẩm gửi gì giữ nguyên nấy. Chỉ bắt buộc id.

Các hàm

| Hàm | Làm gì | |---|---| | saveObject(obj) | Thêm hoặc thay toàn bộ một sản phẩm | | saveObjects(objs, { idField }) | Như trên nhưng nhiều món, tự chia lô | | partialUpdateObjects(objs) | Chỉ sửa các trường gửi lên. Gửi null là xoá trường đó | | deleteObject(id), deleteObjects(ids) | Xoá | | getObjects(ids) | Đọc lại, trả đúng thứ tự, null cho id không có | | replaceAllObjects(objs, { takeOver }) | Đồng bộ toàn bộ: món nào không gửi sẽ bị xoá |

Mã sản phẩm nằm ở trường khác

await ht.saveObjects(products, { idField: 'sku' })

Đồng bộ toàn bộ

Dùng khi muốn HT khớp đúng y kho của bạn, kể cả những món đã gỡ bán:

const summary = await ht.replaceAllObjects(allProducts)
console.log(summary) // { kept, created, deleted, sent }

Mỗi website chỉ mở được một phiên đồng bộ cùng lúc. Nếu lần chạy trước chết giữa chừng và để lại phiên treo, gọi kèm { takeOver: true } để huỷ phiên cũ rồi chạy lại từ đầu.

Tự động chia lô và thử lại

• Tự chia theo 1.000 món và 900KB mỗi request, gửi lần lượt.
• Kiểm toàn bộ mảng trước khi gửi. Sai một món là không gửi gì cả, báo đúng vị trí.
• Tự thử lại khi lỗi mạng, 408, 429, 5xx. Chờ tăng dần, tôn trọng Retry-After.
• Không thử lại với lỗi do dữ liệu sai như 400, 401.

Bắt lỗi

import { ValidationError, RateLimitError, isHtError } from '@huythanh-dev/ht-recommend'

try {
  await ht.saveObjects(products)
} catch (error) {
  if (error instanceof ValidationError) {
    console.error('dữ liệu sai:', error.fields, 'ở vị trí', error.index)
  } else if (isHtError(error)) {
    console.error('HT trả về', error.status, error.code, '— đã ghi được', error.written)
  }
}

Lỗi giữa chừng có written (đã ghi được bao nhiêu món) và index (lô hỏng bắt đầu từ món thứ mấy trong mảng gốc), để bạn gửi tiếp từ đó thay vì làm lại từ đầu.

Các lớp lỗi: ValidationError, AuthError, NotFoundError, RateLimitError, PayloadTooLargeError, SyncInProgressError, NetworkError, ApiError.

Giới hạn

| Thứ | Mức | |---|---| | Mỗi request | 900KB, 1.000 thao tác | | Mỗi sản phẩm | 100KB, lồng nhau 20 tầng | | id | 1–255 ký tự, chuỗi hoặc số nguyên | | Đọc getObjects | 8MB mỗi lần trả về | | Tần suất | 20 request/giây mỗi website |

Nội dung phải là UTF-8 hợp lệ, không chứa ký tự NUL.

Tuỳ chọn khác

createClient({
  appId, apiKey, baseUrl,
  timeoutMs: 30000,
  maxRetries: 4,
})