@fasla/agora-sdk

TypeScript SDK for the Agora Storefront API. Wraps every public and customer-session endpoint with typed methods, and handles the response envelope, CSRF tokens, and session cookies automatically (including a minimal cookie jar for Node.js / SSR).

Install

The SDK lives in this repo; consume it via a workspace or file dependency:

npm install file:../agora/sdk/storefront

Quick start

import { AgoraStorefront } from '@fasla/agora-sdk'

const agora = new AgoraStorefront('https://shop.example.com')

// Catalog + content
const products = await agora.catalog.listProducts({ page_size: 12 })
const posts = await agora.blog.listPosts()
const footerPages = await agora.pages.list()
const heroBanners = await agora.banners.list('home_hero')

// Star badges for product cards
const ratings = await agora.reviews.summary(products.items.map((p) => p.id))

// Cart → checkout (guest or logged-in)
await agora.cart.addLine(variantId, 1)
const order = await agora.orders.checkout({ /* contact + shipping */ })

// Buyer account
await agora.auth.login({ email, password })
await agora.reviews.create({ product_id: 42, rating: 5, body: 'Tuyệt vời!' })

Resources

| Resource | Purpose | |---|---| | catalog | Categories and products | | blog | Published blog posts | | pages | Published static content pages (about, FAQ, policies) | | banners | Active promotional banners per theme placement key | | reviews | Approved reviews, rating summaries, and the buyer's own review | | cart | Guest or authenticated shopping cart | | orders | Checkout, guest tracking, buyer order history | | auth | Register, login, logout, password reset | | customer | Profile and addresses of the authenticated buyer |

Error handling

Every failed call throws AgoraError carrying the API's dot-namespaced code (e.g. review.not_purchased), message, and HTTP status. Match on code, not message.

import { AgoraError } from '@fasla/agora-sdk'

try {
  await agora.reviews.create({ product_id: 42, rating: 5, body: '...' })
} catch (e) {
  if (e instanceof AgoraError && e.code === 'review.not_purchased') {
    // show "only buyers can review"
  }
}

Options

new AgoraStorefront(baseUrl, {
  fetch: customFetch,               // e.g. cookie-jar-aware fetch for SSR
  headers: { 'Accept-Language': 'vi' },
})

See CHANGELOG.md for release history.