JavaScript SDK

The feeef npm package — typed repositories over the whole API, cart service, realtime and OAuth helpers.

The feeef package is the official TypeScript client. It powers the Feeef storefront and the admin dashboard, so every surface it exposes is exercised in production.

npm install feeef

Initialize

import { FeeeF } from 'feeef'

const feeef = new FeeeF({
  apiKey: process.env.FEEEF_TOKEN!, // bearer token ('' for anonymous/public calls)
  baseURL: 'https://api.feeef.org/v1',
})

Option	Notes
`apiKey`	Set as `Authorization: Bearer …` default header
`baseURL`	Defaults to `http://localhost:3333/api/v1` — always set it in production
`client`	Optional Axios instance. Pass a dedicated instance (`axios.create()`) in apps that make non-Feeef requests, since the SDK sets default headers on the instance it receives
`cache`	Optional response-cache TTL in seconds, or `false`

Swap tokens at runtime with feeef.setHeader('Authorization', 'Bearer ' + token) and feeef.removeHeader('Authorization').

Every resource is a repository property with a consistent surface: list(params?), find({ id, by?, params? }), create({ data }), update({ id, data }), delete({ id }), plus domain-specific methods.

Property	Resource	Highlights
`stores`	Stores	`find({ id, by: 'slug' })` for public storefront lookup, member management
`products`	Products	Flat filters (`q`, `status`, `price_min`…) + filterator, variants
`orders`	Orders	`calculate` (totals preview), status transitions, batch ops
`categories`	Categories	Per-store trees
`pages` → `productLandingPages`	Landing pages	Draft/publish
`productLandingPageTemplates`	LP templates	Marketplace listing
`templateComponents`	Custom components	Per-store library + cross-store marketplace, `refId` resolution
`storeTemplates`	Store templates	Full-site templates + marketplace + `install`
`imagePromptTemplates` / `imageGenerations`	AI imaging	Prompt templates, async generations
`shippingPrices` / `shippingMethods`	Shipping	Price matrices per state/city
`users`	Auth & profile	See below
`apps`	OAuth clients	Registration CRUD + data buckets
`oauth`	OAuth 2.0	`exchangeAuthorizationCode`, `revokeToken`, `introspectToken`
`promos`	Promo codes	`validate` before applying
`feedbacks`	Product feedback	Reviews/ratings
`inventory`	Inventory (Pro)	Warehouses, stock items, reservations (+`batchRelease`)
`finance`	Finance (Pro)	Accounts, entries, procurement
`deposits` / `transfers`	Billing	Account funding and transfers
`countries` / `states` / `cities` / `currencies`	Reference data	Static lookups (e.g. 58 DZ wilayas)

Services: cart (below), storage (uploads), actions, notifications (push), integrations (per-store integration APIs).

Authentication

// Email + password
const { user, token } = await feeef.users.signin({ email, password })
feeef.setHeader('Authorization', `Bearer ${token.token}`)

// Restore a saved session ("who am I")
const auth = await feeef.users.signinWithToken(savedToken)

// Sessions
await feeef.users.listTokens()
await feeef.users.revokeToken(tokenId)
await feeef.users.signout()

For third-party apps, use OAuth — the SDK ships buildAuthorizeUrl and feeef.oauth.exchangeAuthorizationCode.

Listing, filtering, batch

// Flat params
const page1 = await feeef.products.list({
  params: { store_id: storeId, status: 'published', order_by: 'sold:desc', page: 1, limit: 24 },
})

// Filterator for arbitrary conditions
const cheap = await feeef.products.list({
  params: {
    store_id: storeId,
    filterator: JSON.stringify({
      filtering: {
        condition: 'and',
        filters: [{ field: 'price', operation: 'lessOrEqual', value: 2000 }],
        groups: [],
      },
      ordering: [{ field: 'createdAt', dir: 'desc' }],
      paging: { limit: 12, offset: 0 },
    }),
  },
})

// Batch operations return a partial-success envelope — always check `summary`
const res = await feeef.orders.batchUpdate({
  ids: orderIds,
  updateMask: ['status'],
  fields: { status: 'confirmed' },
})
if (res.summary.failed > 0) console.warn(res.failedRequests)

See API conventions for the full filterator operator table.

Cart service

feeef.cart is a framework-agnostic cart with the entire checkout math built in — quantities, variant paths, offers (with min/max clamping and forced-offer rules), addons, and shipping price resolution by state/city and shipping type (home / pickup / store).

feeef.cart.setStore(store)
feeef.cart.addItem({ product, quantity: 1, variantPath: 'Black/M' })
feeef.cart.setShippingAddress({ ...address, type: ShippingType.home })

feeef.cart.getSubtotal()
feeef.cart.getShippingPrice()
feeef.cart.getTotal()

It extends a notifiable service — subscribe to changes, or in React use the built-in useSyncExternalStore snapshot:

const version = useSyncExternalStore(
  (cb) => feeef.cart.subscribe(cb),
  () => feeef.cart.getReactSnapshot(),
)

Realtime

Live CRUD events over SSE (AdonisJS Transmit). The stream lives on the API origin (no /v1); the helper derives it for you and attaches the bearer token to subscriptions:

import { createFeeefTransmitFromAxios, type RealtimeCrudEvent } from 'feeef'

const transmit = createFeeefTransmitFromAxios(feeef.client)

const sub = transmit.subscription(`stores/${storeId}/orders`)
await sub.create()

sub.onMessage<RealtimeCrudEvent>(({ event, data }) => {
  // event: 'created' | 'updated' | 'deleted'
})

Or without Axios: createFeeefTransmit({ apiBaseUrl, getAccessToken }).

File uploads

const { url } = await feeef.storage.upload(file, { folder: 'products' })

OAuth apps (developer surface)

// Manage your registered apps
const apps = await feeef.apps.list()
const created = await feeef.apps.create({
  data: { name: 'My integration', redirectUris: ['https://…/callback'], scopes: ['auth'] },
})
created.clientSecret // shown once!

// App data buckets
await feeef.apps.putPublicData(appId, { branding: { tagline: 'Hi' } })
const me = await feeef.apps.getUserDataMe(appId)

Full bucket semantics: App data.