@haatlabs-core/services
The client for the Haatlabs API on RapidAPI: Amazon search and product pages, image search, background removal, AI product descriptions and image checks, and jobs that chain them. One RapidAPI key; the work runs on Haatlabs' servers.
Install
pnpm add @haatlabs-core/services
Subscribe to the Haatlabs API on RapidAPI (the BASIC plan is free) and put the key in your app's
environment as HAATLABS_API_KEY. Plans and limits: https://haatlabs.shop/docs/services/
Use
import { createHaatlabsApi } from '@haatlabs-core/services';
const api = createHaatlabsApi({ apiKey: process.env.HAATLABS_API_KEY! });
const page = await api.amazon.search({ q: 'desk lamp', market: 'US' });
const cutout = await api.images.removeBackground({ image: bytes }); // or { imageUrl }
const job = await api.jobs.start('find-clean', { query: 'desk lamp', limit: 5 });
const done = await api.jobs.wait(job.jobId);
amazon.search(query),amazon.product({ market, id })images.search(q, { limit }),images.removeBackground({ image } | { imageUrl }): an image by its bytes (at most 5 MB,MAX_UPLOAD_BYTES) or a public https URL; the cut-out's URL is signed untilexpiresAt.ai.describe({ product, tone, language, keywords }),ai.vision({ image } | { imageUrl }, expect, minMatch): the image with itsverdict.jobs.start(kind, body)forenrich,find-clean,listing,find-checkedandpipeline;jobs.get(id);jobs.wait(id, { intervalMs, timeoutMs }).verifyWebhook({ secret, headers, body }): whether a job's callback is really the API's (Standard Webhooks signatures, five minutes either way). Pass the raw body.
Options: host (the listing's RapidAPI host), baseUrl, fetch, timeoutMs (35 s).
Errors
Every failure is an AppError (@haatlabs-core/errors); a project spreads SERVICES_ERRORS into
defineErrors. A ServiceError also carries the API's own serviceCode and requestId.
SERVICE_QUOTA_EXCEEDED(503): the plan's quota is used up; upgrade or wait for the period.SERVICE_RATE_LIMITED(503, transient): too many requests a second.SERVICE_KEY_REFUSED(503): a wrong key, or one not subscribed to the API.SERVICE_REQUEST_REJECTED(422): the API refused what was sent (IMAGE_REJECTED,PIPELINE_INVALID);VALIDATION_FAILED(400) andNOT_FOUND(404) pass through.SERVICE_UNAVAILABLE(503): the API or a service behind it is away or busy (transient), or answered something unusable (not transient).SERVICE_JOB_TIMEOUT(503, transient):jobs.waitstopped before the job ended.
An image over 5 MB is refused with VALIDATION_FAILED before anything is sent.
Testing
@haatlabs-core/services/testing has startFakeApi(), a local stand-in that answers like the API
and like RapidAPI's refusals (refuse('quota'), failNext(path, status, code),
jobsNeverFinish()), and records every request. pnpm test:real makes one live call per
method with HAATLABS_API_KEY.