@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á | | batch(operations) | Thêm, sửa một phần và xoá lẫn lộn trong một lần gửi, giữ đúng thứ tự | | catalog(options) | Tự động đồng bộ, xem phần dưới |

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 đồng bộ

Gắn một lần vào chỗ shop lưu và xoá sản phẩm. Từ đó thêm, sửa, xoá món nào thì tự gửi lên HT, không ai phải bấm gì.

const catalog = ht.catalog({ idField: 'sku' })

await catalog.reindex(() => db.products.findAll())

onProductSaved((product) => catalog.upsert(product))
onProductDeleted((product) => catalog.remove(product.sku))

onProductSaved và onProductDeleted là hook "sau khi lưu" và "sau khi xoá" của thư viện bạn đang dùng để lưu sản phẩm (ORM, CMS, hoặc chính hàm lưu của bạn). Thư viện nào có hook đó đều gắn được.

| Hàm | Làm gì | |---|---| | catalog.upsert(doc) | Món mới hoặc đã sửa: thay toàn bộ món đó | | catalog.update(patch) | Chỉ đổi các trường gửi lên, null là xoá trường đó. Cần có mã sản phẩm | | catalog.remove(id) | Món đã xoá hoặc ngừng bán | | catalog.reindex(source, options) | Nạp lại toàn bộ: lần đầu, hoặc chạy định kỳ để tự sửa mọi sai lệch | | catalog.flush() | Gửi ngay những gì đang chờ, trả về số thao tác đã gửi | | await catalog.close() | Gửi nốt rồi dừng. Gọi khi tắt server | | catalog.pending | Số thao tác đang chờ gửi |

Gọi upsert, update, remove không cần await và không bao giờ ném lỗi, nên không làm hỏng luồng lưu sản phẩm của bạn.

Cách nó chạy

• Gom lô. Mọi thay đổi trong vòng 1 giây được gom thành một lần gửi, đúng thứ tự xảy ra. Đủ 1.000 thao tác thì gửi ngay.
• Chụp lại lúc gọi. Món được sao chép ngay khi gọi, sửa đối tượng sau đó không đổi gì thứ đã xếp hàng.
• Lỗi mạng hay HT bận: giữ lại và thử lại sau, chờ tăng dần tới 30 giây. Thay đổi mới vẫn xếp sau những thay đổi cũ chưa gửi được.
• Một món bị HT từ chối (ví dụ lồng quá sâu): chỉ bỏ món đó và báo lỗi, các món còn lại vẫn gửi.
• Khoá sai hoặc đã thu hồi: bỏ các thay đổi đó và báo lỗi, không thử lại.
• Báo lỗi: truyền onError(error, info). Không truyền thì ghi ra console.error. info.willRetry cho biết SDK có còn thử lại không.

Tuỳ chọn

ht.catalog({
  idField: 'sku',
  transform: (row) => (row.status === 'live' ? { sku: row.sku, name: row.title } : null),
  flushIntervalMs: 1000,
  maxBatchSize: 1000,
  maxPending: 20000,
  onError: (error, info) => console.warn(info.operation, info.ids, error.message),
})

• transform đổi hình dạng món trước khi gửi. Trả null, undefined hoặc false nghĩa là món này không nên có trên HT: SDK gửi lệnh xoá. Dùng để ẩn món nháp hoặc ngừng bán.
• maxPending: hàng đợi đầy thì bỏ các thay đổi cũ nhất và báo lỗi. Đây là lúc nên chạy reindex.

Nạp lại toàn bộ và chốt chặn

reindex nhận một mảng, một hàm trả về mảng, hoặc nguồn async. Nó gửi nốt những gì đang chờ, rồi thay toàn bộ catalog, và món nào không có trong nguồn sẽ bị xoá.

Vì xoá là việc nguy hiểm, reindex từ chối chạy khi:

• nguồn trả về rỗng (thường là database đang lỗi chứ không phải shop hết hàng). Muốn thật sự xoá sạch thì truyền { allowEmpty: true };
• nguồn nhỏ đi hơn một nửa so với lần reindex trước trong cùng tiến trình. Đổi ngưỡng bằng { maxShrinkRatio: 0.9 }.

Lúc bị từ chối, nó ném CatalogGuardError và không đổi gì trên HT. Chốt chặn thứ hai chỉ nhớ lần trước trong cùng tiến trình, nên lần reindex đầu tiên sau khi khởi động chỉ có chốt chặn rỗng.

Cần biết

• Hàng đợi nằm trong bộ nhớ. Server chết đột ngột thì mất những thay đổi chưa gửi (tối đa khoảng 1 giây, hoặc lâu hơn nếu HT đang lỗi). Chạy reindex định kỳ, ví dụ mỗi đêm, để tự sửa.
• Chạy nhiều bản server thì mỗi bản gửi thay đổi của mình. Đặt reindex ở một nơi thôi, vì mỗi website chỉ có một phiên đồng bộ cùng lúc.
• Hosting không chạy liên tục (serverless): gọi await catalog.flush() trước khi hàm kết thúc.

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,
})