TypeScript SDK for the Cart e-commerce intelligence API.
Requires Node.js 18+ (uses native fetch). Zero runtime dependencies.
npm install @usecart/sdkimport { CartClient } from "@usecart/sdk";
const cart = new CartClient("cart_sk_live_...");
// Search stores selling pet supplies
const { data: stores } = await cart.stores.search({
keyword: "pet supplies",
platform: "shopify",
per_page: 10,
});
console.log(stores);const cart = new CartClient("cart_sk_live_...", {
baseUrl: "https://api.usecart.com/v1", // default
});Every method returns a typed ApiResponse<T> containing:
{
data: T;
meta: {
request_id: string;
timestamp: string;
page: number;
total_pages: number;
total_results: number;
};
usage: {
requests_today: number;
limit: number;
};
}Search for e-commerce stores.
const response = await cart.stores.search({
keyword: "fitness",
platform: "shopify",
language: "en",
currency: "USD",
biz_model: "dropshipping",
has_ads: true,
status: "live",
min_traffic: 10000,
page: 1,
per_page: 25,
sort: "monthly_visitors:desc",
});Get detailed information about a single store.
const { data: store } = await cart.stores.get("example-store.myshopify.com");
console.log(store.platform, store.monthly_visitors);Get products listed on a store.
const { data: products } = await cart.stores.getProducts("example.com", {
page: 1,
per_page: 50,
sort: "price:desc",
});Get ads detected for a store.
const { data: ads } = await cart.stores.getAds("example.com");Get traffic analytics for a store.
const { data: traffic } = await cart.stores.getTraffic("example.com");
console.log(traffic.monthly_visitors, traffic.traffic_by_source);Get the technology stack of a store.
const { data: tech } = await cart.stores.getTech("example.com");
// tech = [{ name: "Shopify", category: "ecommerce" }, ...]Compare multiple stores side by side.
const { data: stores } = await cart.stores.compare([
"store-a.com",
"store-b.com",
"store-c.com",
]);Search for products across all tracked stores.
const response = await cart.products.search({
keyword: "yoga mat",
min_price: 10,
max_price: 50,
currency: "USD",
page: 1,
per_page: 25,
});Get a single product by its ID.
const { data: product } = await cart.products.get("prod_abc123");Get trending products.
const { data: trending } = await cart.products.trending({
page: 1,
per_page: 20,
category: "electronics",
});Search for ads across all tracked stores.
const response = await cart.ads.search({
keyword: "wireless earbuds",
platform: "facebook",
store_domain: "example.com",
page: 1,
});Get a single ad by ID.
const { data: ad } = await cart.ads.get("ad_xyz789");Search for suppliers.
const response = await cart.suppliers.search({
keyword: "electronics",
location: "CN",
type: "manufacturer",
});Get a niche overview for a keyword, including top stores and trending products.
const { data: niche } = await cart.niches.get("sustainable fashion");
console.log(niche.total_stores, niche.avg_price, niche.top_stores);Get globally trending stores and products.
const { data } = await cart.trending({ page: 1, per_page: 10 });
console.log(data.stores, data.products);Get the authenticated account details and current usage.
const { data: acct } = await cart.account();
console.log(`Used ${acct.requests_today} of ${acct.requests_limit} requests`);The client automatically parses rate limit headers from every response. You can check the current state at any time:
await cart.stores.search({ keyword: "shoes" });
console.log(cart.rateLimit);
// { remaining: 97, limit: 100 }When the rate limit is exceeded the client throws a CartRateLimitError with a retryAfter property (seconds).
All API errors are thrown as typed error instances:
import {
CartClient,
CartApiError,
CartAuthError,
CartRateLimitError,
} from "@usecart/sdk";
const cart = new CartClient("cart_sk_live_...");
try {
await cart.stores.get("nonexistent.com");
} catch (error) {
if (error instanceof CartAuthError) {
// 401 - invalid or expired API key
console.error("Auth failed:", error.message);
} else if (error instanceof CartRateLimitError) {
// 429 - rate limited
console.error(`Rate limited. Retry after ${error.retryAfter}s`);
} else if (error instanceof CartApiError) {
// Any other API error (400, 404, 500, etc.)
console.error(`API error ${error.status}: ${error.message}`);
console.error("Request ID:", error.requestId);
} else {
throw error;
}
}All types are exported for your convenience:
import type { Store, Product, ApiResponse, StoreSearchParams } from "@usecart/sdk";
async function findStores(params: StoreSearchParams): Promise<Store[]> {
const cart = new CartClient(process.env.CART_API_KEY!);
const response: ApiResponse<Store[]> = await cart.stores.search(params);
return response.data;
}MIT