RedCircle API plugin

• Sorting and delivery values. sort_by takes best_seller, price_high_to_low, price_low_to_high, best_match, highest_rating, newly_listed or featured; delivery_type takes in_store_pickup, same_day_delivery, buy_at_store or ship_to_home.
• One route does the product work. GET /request is discriminated by type: product, search or reviews in this plugin. Each has its own typed operation and pins the type value, so an invalid one cannot be sent.
• Each page costs a credit. max_page retrieves several pages and concatenates them in one response, which is convenient but multiplies the cost; it is capped here, and a request that yields fewer pages than asked is charged only for what it returned.
• A 402 is a spent balance. It means the credits are exhausted or there is a payment problem, and no retry fixes it. The plugin matches it before the rate-limit handler and stops immediately.
• A 503 is a parsing incident. RedCircle raises it deliberately so it never serves unstable data, the body says the request was not charged, and it carries retry_after in seconds. The plugin retries delays up to 30 seconds. Longer delays are returned immediately on the error for the caller to schedule.
• Paging is page, and the response says where you are. pagination.current.page and pagination.next.page are returned as current_page and next_page, with total_pages and total_results. next_page is null on the last page.
• Some routes do not page. /categories has no pagination at all; it returns categories (with parent_id or search_term) or a single category.
• The account route echoes the key. RedCircle returns account_info.api_key; the plugin strips it before the output parse, so it cannot reach a caller or a log.
• The demo key is limited. api_key=demo works on /request and /account but answers 401 on other routes, which reads as an auth failure — check the message, not just the status.

• 5 typed API operations

​

Setup

npm install corsair @corsair-dev/redcircle better-sqlite3
npm install --save-dev @types/better-sqlite3

yarn add corsair @corsair-dev/redcircle better-sqlite3
yarn add --dev @types/better-sqlite3

pnpm install corsair @corsair-dev/redcircle better-sqlite3
pnpm install --save-dev @types/better-sqlite3

bun add corsair @corsair-dev/redcircle better-sqlite3
bun add --dev @types/better-sqlite3

import Database from 'better-sqlite3';
import { createCorsair } from 'corsair';
import { redcircle } from '@corsair-dev/redcircle';

export const corsair = createCorsair({
	plugins: [
		redcircle(),
	],
	database: new Database('corsair.db'),
	kek: process.env.CORSAIR_KEK!,
	multiTenancy: true,
	hub: {
		projectApiKey: process.env.CORSAIR_API_KEY!,
		signingSecret: process.env.CORSAIR_SIGNING_SECRET!,
	},
});

redcircle()

const { connectUrl } = await corsair.manage.connect.createLink({
	plugin: 'redcircle',
	tenantId: 'acme',
});
// redirect the user's browser to connectUrl

​

Example API calls

const tenant = corsair.withTenant('acme');
await tenant.redcircle.api.search.products({ search_term: 'highlighter pens' });

const tenant = corsair.withTenant('acme');
await tenant.redcircle.api.account.get({});

​

What’s next