create-orders-manager
Skill8 starsChanged 45 days agoMITView on GitHub
Build a single-page Orders Manager application powered by the DataDoe REST API. Use when the user asks to create, scaffold, or build an orders manager, orders dashboard, orders table, or order management app using DataDoe.
- Reads credentials
- Installs packages
In this repository26 other files it gives its agents.
- amazon-asin-search-auditorSkill
- amazon-listing-optimizerSkill
- buy-box-loss-root-causeSkill
- create-amazon-reconciliation-dashboardSkill
- daily-account-health-checkSkill
- daily-performance-health-checkSkill
- fba-inventory-ledger-reportSkill
- fba-stock-restock-plannerSkill
- keyword-rank-sqp-trackerSkill
- net-profit-pl-analyzerSkill
- ppc-asin-acos-alertSkill
- ppc-bid-optimizer-applySkill
- ppc-campaign-acos-alertSkill
- ppc-negative-keyword-applierSkill
- ppc-profit-bid-applySkill
- ppc-wasted-spend-watchdogSkill
- promotions-managerSkill
- restock-priority-alertSkill
- return-refund-analyzerSkill
- sales-movers-scannerSkill
- suppressed-inactive-listings-checkSkill
- vendor-inventory-reportSkill
- vendor-performance-dashboardSkill
- vendor-pnl-dashboardSkill
- weekly-business-reviewSkill
- weekly-sales-briefingSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
28 rules. About 0 are common, 17 are distinctive, and 11 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈17
Distinctive · estimate
This author's own choices. Worth a look.
11
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 37
Only sellers with sellerCentralConnection !== null are valid (Order Line Items source is SELLER_CENTRAL).
- Very specific: line 91
If VITE_DATADOE_API_KEY is set → attach datadoe-api-key header.
- Very specific: line 94
Always attach Content-Type: application/json and Accept: application/json.
- Distinctive: line 101
Single in-flight flow per seller: never run multiple export flows in parallel for the same seller.
- Distinctive: line 102
No parallel polling: only one active poll loop per export.
- Distinctive: line 103
Debounce filter-triggered exports: wait 400-800ms after filter changes before creating a new export.
- Distinctive: line 104
Serialize bursty steps: when chaining create → poll → raw download, avoid extra background fetches in parallel.
- Distinctive: line 107
If these constraints conflict with UI responsiveness, prioritize staying below rate limits.
- Very specific: line 127
Never hardcode the source id: resolve it at runtime from GET /api/v1/exports/sources by matching tableName == …
- Very specific: line 199
When status is COMPLETED, download.
- Very specific: line 332
If no filter rules are needed, either omit filters entirely or pass { "combinator": "and", "rules": [] }.
- Very specific: line 364
Add .env to .gitignore.
- Distinctive: line 366
Verify API connectivity with curl.
- Distinctive: line 368
Run build/lint checks.
- Distinctive: line 372
Every component lives in its own directory containing exactly two files: the component file and its CSS Module.
- Very specific: line 430
Import Google Sans in global.css: @import url('https://fonts.googleapis.com/css2?family=Google+Sans:wght@400;500;700&display=swap').
- Distinctive: line 432
No inline styles. No Tailwind.
- Very specific: line 436
Create a generic DataTable<T> component that:
- Distinctive: line 474
If 403: wrong API key for the target.
- Distinctive: line 478
After starting the dev server, read its output to find the actual port (may not be 5173 if that port is in use), then run:
- Distinctive: line 495
If either check fails, follow this mandatory debug strategy:
- Distinctive: line 500
After any fix, re-run both checks (direct target and localhost proxy).
- Distinctive: line 737
Test API calls first: before coding the full UI, verify the export flow works by running the mandatory connectivity checks.
- Distinctive: line 739
Handle empty states: no sellers, no orders, export still loading — all need UI.
- Distinctive: line 745
Run build and lint: before finalizing.
- Very specific: line 753
Use .env.example as reference and documentation target.
- Very specific: line 754
Never print .env secrets in output.
- Distinctive: line 758
Always run dev server in background:
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Orders Manager
Build a complete, working single-page Orders Manager app using the DataDoe REST API. The app must be functional after a single execution.
API docs: https://api.datadoe.com/api/v1/docs Data scheme: https://api.datadoe.com/api/v1/spec/data-scheme
Agent Type Detection
Determine your agent type before starting:
- Low-level agent (Cursor, Claude Code, Codex, Aider, etc.): follow the Default Tech Stack below.
- High-level vibe coding assistant (Lovable, Base44, Bolt, v0, etc.): ignore the tech stack section entirely; use whatever the platform provides. Follow only the App Features, DataDoe API Integration, and Implementation Rules sections.
App Features
1. Seller/Vendor Picker
- On load, fetch connected sellers and vendors from the API.
- Show a dropdown to select one. Orders cannot be loaded without a selection.
- Only sellers with
sellerCentralConnection !== nullare valid (Order Line Items source isSELLER_CENTRAL).
2. Orders Table
- Display orders in a table with expandable nested rows for line items.
- Parent row:
amazon_order_id,date,amazon_order_status,fulfillment_channel,sales_channel, total item count, total price. - Child rows (expanded):
sku,child_asin,product_name,quantity,item_price_value,item_price_currency,item_status— keyed byamazon_order_item_id(skucan repeat within an order). - Client-side pagination with configurable page size (10/25/50).
3. Filters
- Date range: date-from / date-to inputs. Default: last 30 days.
- Order status: multi-select checkboxes. Values documented by the DataDoe scheme:
Pending,Unshipped,Shipped,Canceled. Some marketplaces returnShipped/Unshippedwith a marketplace-specific prefix (Shipped*/Unshipped*), so filter those two withbeginsWith(never=);PendingandCanceledcan use=. - Applying filters triggers a new export.
4. Order Tagging (Local)
- Tags are NOT part of the DataDoe API — they are stored in
localStorage. - Each order (
amazon_order_id) can have zero or more text tags. - UI: inline tag chips with "add tag" button + text input.
- Prefix all localStorage keys with
datadoe-orders-manager::for collision safety. - Enforce via TypeScript branded type:
type StorageKey = `datadoe-orders-manager::${string}`;5. Loading & Error States
- Show a spinner/skeleton during export creation and polling.
- Show user-friendly error messages for API failures (network errors, 429 rate limits, 4xx/5xx).
- On 429: auto-retry after
Retry-Afterheader value.
DataDoe API Integration
Auth & Config
The app always targets the production DataDoe API at https://api.datadoe.com. During local development, Vite proxies /api requests to this domain to avoid CORS. There is no staging/production distinction — always use the same API target.
.env file structure (create .env.example with the placeholders below):
# Vite proxies /api → https://api.datadoe.com (CORS bypass for local dev)
VITE_API_BASE_URL=/api
VITE_PROXY_TARGET=https://api.datadoe.com
VITE_DATADOE_API_KEY=<your-api-key>VITE_API_BASE_URLmust always be/api— the browser app never callsapi.datadoe.comdirectly.VITE_PROXY_TARGETmust always behttps://api.datadoe.com— this is the Vite proxy upstream.VITE_DATADOE_API_KEY— the API key obtained from the DataDoe dashboard.
Header selection logic (mutually exclusive — never send both):
- If
VITE_DATADOE_API_KEYis set → attachdatadoe-api-keyheader. - Else if
VITE_DATADOE_ORGANIZATION_IDis set → attachdatadoe-organization-idheader.
Always attach Content-Type: application/json and Accept: application/json.
Rate limit: 2 req/s per org. On 429, read Retry-After header, wait, retry.
Anti-Rate-Limit Guardrails (Mandatory)
- Global client-side pacing: cap all DataDoe requests to max 1 request every 600ms (<= ~1.67 req/s), leaving headroom under 2 req/s.
- Single in-flight flow per seller: never run multiple export flows in parallel for the same seller.
- No parallel polling: only one active poll loop per export; cancel/replace stale loops before starting new ones.
- Debounce filter-triggered exports: wait 400-800ms after filter changes before creating a new export.
- Serialize bursty steps: when chaining create → poll → raw download, avoid extra background fetches in parallel.
- Respect
Retry-Afterexactly on429, then add incremental delay for subsequent retries.
If these constraints conflict with UI responsiveness, prioritize staying below rate limits.
Export Flow (5 steps)
1. Fetch sellers
GET /api/v1/util/sellers-and-vendors
→ { items: [{ id, name, sellerCentralConnection, vendorCentralConnection, amazonAdsConnection }] }Filter to items where sellerCentralConnection is not null.
2. Fetch export sources (get source ID)
GET /api/v1/exports/sources?sellerOrVendorIds=<sellerId>Find the source named Order Line Items (type SELLER_CENTRAL) and use the id it returns — always prefer the resolved id.
Never hardcode the source id: resolve it at runtime from GET /api/v1/exports/sources by matching tableName == "amazon_order_items_with_cogs" (the id format can differ between the REST and MCP surfaces).
3. Create export
POST /api/v1/exportsRequest body:
{
"sellerOrVendorIds": ["<sellerId>"],
"sourceId": "<id of amazon_order_items_with_cogs from GET /exports/sources>",
"columns": [
"amazon_order_id",
"amazon_order_item_id",
"date",
"amazon_order_status",
"fulfillment_channel",
"sales_channel",
"sku",
"line_item_number",
"child_asin",
"product_name",
"item_status",
"quantity",
"item_price_value",
"item_price_currency"
],
"from": "2025-01-01T00:00:00.000Z",
"to": "2025-01-31T23:59:59.999Z",
"outputType": "JSON",
"sendToAllOrganizationMembers": false
}To filter by status, add filters. Use beginsWith for Shipped and Unshipped so marketplace-prefixed variants (Shipped* / Unshipped*) are included; = is safe only for Pending and Canceled:
{
"filters": {
"combinator": "or",
"rules": [
{
"field": "amazon_order_status",
"operator": "beginsWith",
"value": "Shipped",
"not": false
},
{
"field": "amazon_order_status",
"operator": "=",
"value": "Pending",
"not": false
}
]
}
}Response: { id, status: "PENDING", ... }.
4. Poll status (every 5s, timeout 2min)
GET /api/v1/exports/<exportId>
→ { status: "PENDING" | "PROCESSING" | "COMPLETED" | "ERROR" }5. Download data
When status is COMPLETED, download. If ERROR, show error.
GET /api/v1/exports/<exportId>/raw200: redirects (302) to a pre-signed S3 URL — axios must follow the redirect automatically (followRedirects: truein Vite proxy handles this on the server side; the browser axios instance follows it natively).204: still processing — retry after a few seconds.404: export not found.
Example row returned in the flat array:
{
"seller_or_vendor_id": "3f2a9c1e-5b7d-4e8a-9c21-7d4e5f6a8b90",
"seller_or_vendor_name": "DataDoe UK",
"marketplace_country_name": "United Kingdom",
"amazon_order_id": "203-5492174-4518714",
"amazon_order_item_id": "12345678901234",
"sku": "341_SDA12D_117_FBA",
"line_item_number": 0,
"date": "2025-01-12",
"amazon_order_status": "Shipped",
"fulfillment_channel": "Amazon",
"sales_channel": "Amazon.co.uk",
"child_asin": "ABCDEFGHIJ",
"product_name": "xyz",
"item_status": "Shipped",
"quantity": 2,
"item_price_value": 14.76,
"item_price_currency": "GBP"
}For the full column reference, see: https://api.datadoe.com/api/v1/spec/data-scheme
Raw Data Shape & Client-Side Grouping Logic
The /raw endpoint returns a flat array of line items. Each element is one order item (amazon_order_item_id) within one order. An order with N order items produces N rows all sharing the same amazon_order_id; the same sku can appear on more than one of them.
CRITICAL — columns: [] (empty array) does NOT return all columns. It returns only seller-context metadata columns (seller id / name, marketplace, connection ids) and none of the Order Line Items fields (amazon_order_id, sku, amazon_order_status, etc.). Always specify the required columns explicitly. Every response also prepends those utility columns before your requested fields, so read values by key/name, never by column position.
Field roles:
| Field | Level | Notes |
amazon_order_id | Order | Grouping key — unique per order |
amazon_order_item_id | Line item | Amazon's order-item id — unique per line, never null. Use it as the row key (TanStack getRowId). |
amazon_order_status | Order | Consistent across all rows for the same order. Pending / Unshipped / Shipped / Canceled; some marketplaces prefix Shipped* / Unshipped* |
fulfillment_channel | Order | Consistent across all rows for the same order |
date | Order | Purchase date. Marketplace orders use the marketplace local date. Off-Amazon lines use the kept connection's country time zone. Use this for display and sorting. order_date duplicates date. |
sales_channel | Order | Amazon's supplied channel. A marketplace order uses an Amazon marketplace domain, such as Amazon.com. Any other non-empty value, including Non-Amazon, is off-Amazon Multi-Channel Fulfillment. That value does not name the external store. A blank channel is not off-Amazon. |
sku | Line item | Seller SKU of the line. Not unique within an order — the same SKU can be a separate order item more than once, so never key rows by it |
line_item_number | Line item | Occurrence index of the same SKU within the order (0 for the first line of each SKU; increments only when that SKU repeats). Not the line's position in the order — do not use it to order or key lines |
child_asin | Line item | Amazon ASIN |
product_name | Line item | Full product name |
item_status | Line item | Can differ from amazon_order_status |
quantity | Line item | Units for this SKU only |
item_price_value | Line item | Line-item total value — already includes quantity; use as-is, do NOT multiply by quantity. Null on cancelled lines (and on orders <4h old): coalesce to 0 and render "—" with a "cancelled" badge, never NaN. On an off-Amazon line this is the order-report amount, not verified sales. |
item_price_currency | Line item | Consistent across the priced rows of an order; null on cancelled lines — take it from another line of the same order, else fall back to the marketplace currency |
How to build the parent (order) row from the flat array:
// Group by amazon_order_id. Sort parent rows by date (purchase date).
// item_price_value is already the line TOTAL - sum it as-is, never multiply by quantity.
// item_price_value and item_price_currency are NULL on cancelled lines (and on orders <4h old):
// coalesce the price to 0 and take the currency from the first line that has one, so a
// cancelled line can never turn the order total into NaN.
const ordersMap = new Map<string, OrderRow>();
for (const item of lineItems) {
const linePrice = item.item_price_value ?? 0; // null on cancelled lines -> 0, never NaN
const existing = ordersMap.get(item.amazon_order_id);
if (existing) {
existing.lineItems.push(item); // child rows are keyed by amazon_order_item_id, not sku
existing.totalPrice += linePrice; // line total, NOT × quantity
existing.itemCount += item.quantity ?? 0;
existing.currency ??= item.item_price_currency ?? null; // first non-null currency wins
} else {
ordersMap.set(item.amazon_order_id, {
amazon_order_id: item.amazon_order_id,
amazon_order_status: item.amazon_order_status, // order-level, consistent
fulfillment_channel: item.fulfillment_channel, // order-level, consistent
sales_channel: item.sales_channel, // order-level, consistent
date: item.date, // local date in the kept connection's country time zone
currency: item.item_price_currency ?? null, // null on cancelled lines; filled from a later line
totalPrice: linePrice, // line total, NOT × quantity
itemCount: item.quantity ?? 0,
lineItems: [item],
});
}
}
const orders = Array.from(ordersMap.values());
// Sort by date descending. date is the purchase date. order_date is the same value.
// If currency is still null (every line cancelled), fall back to the seller's marketplace
// currency (e.g. GBP for Amazon.co.uk) and render the total as "—" with a "cancelled" badge.Parent row columns to display:
| Column | Source | Display |
| Order ID | amazon_order_id | Monospace, full string |
| Order Date | date | Purchase date |
| Status | amazon_order_status (first item) | Coloured badge |
| Channel | fulfillment_channel (first item) | Badge |
| Sales channel | sales_channel (first item) | Amazon domain, or the supplied off-Amazon value |
| Items | sum(quantity) across all line items | Number |
| Total | sum(item_price_value ?? 0) (already line totals; null on cancelled lines) | Formatted currency; "—" + "cancelled" badge when every line is null. For an off-Amazon order, label it as a declared amount, not sales revenue. |
| Tags | localStorage only | Tag chips |
Child (line item) row columns to display (row key: amazon_order_item_id via TanStack getRowId — not sku, not the array index):
| Column | Source |
| SKU | sku |
| ASIN | child_asin |
| Product | product_name |
| Qty | quantity |
| Price | item_price_value + item_price_currency ("—" when null, i.e. cancelled line) |
| Item Status | item_status |
An order is off-Amazon when sales_channel is non-empty and, after trim and lowercasing, is not an Amazon marketplace domain: amazon.ae, amazon.ca, amazon.co.jp, amazon.co.uk, amazon.co.za, amazon.com, amazon.com.au, amazon.com.be, amazon.com.br, amazon.com.mx, amazon.com.tr, amazon.de, amazon.eg, amazon.es, amazon.fr, amazon.ie, amazon.in, amazon.it, amazon.nl, amazon.pl, amazon.sa, amazon.se, or amazon.sg. Keep the row and the supplied channel. A blank channel stays a marketplace order. Do not name an external store from a generic value such as Non-Amazon.
CRITICAL — API parameter formats discovered through testing:
GET /exports/sourcesuses bare query paramsellerOrVendorIds=<uuid>— notsellerOrVendorIds[]=<uuid>and notsellerOrVendorIds[0]=<uuid>. The bracket syntax is rejected with 400.POST /exportscolumnsmust be an explicit list of the field names you need — never pass[](empty). An empty array returns only seller-context metadata with no order fields, causing the table to display empty rows.- Date range uses top-level
fromandtofields (ISO 8601 datetime strings like2025-01-01T00:00:00.000Z) — not insidefilters. filtersusescombinatorwith lowercase values:"and"or"or"(not"AND"/"OR").- Each filter rule must include the
notfield (boolean):{ "field": "...", "operator": "...", "value": "...", "not": false }. - If no filter rules are needed, either omit
filtersentirely or pass{ "combinator": "and", "rules": [] }.
Default Tech Stack (Low-Level Agents Only)
Skip this section if you are a high-level assistant.
| Tool | Version / Notes |
| Vite | Latest, React + TypeScript template (npm create vite@latest) |
| React | 18+ with TypeScript strict mode |
| axios | 1.13.6 only (security requirement) |
| TanStack Table | @tanstack/react-table latest |
| day.js | Latest, for date formatting and manipulation |
| Lucide React | Latest, for icons |
| CSS Modules | Native CSS, no Tailwind or component libraries |
| Google Sans | Font via Google Fonts CDN |
Setup
Vite creates a nested directory. Move all files up to the workspace root so the project lives at the top level:
npm create vite@latest orders-manager -- --template react-ts
shopt -s dotglob && mv orders-manager/* . && rmdir orders-manager
npm install axios@1.13.6 @tanstack/react-table dayjs lucide-reactRequired Execution Order
- Scaffold Vite app in
orders-manager. - Move generated files/folders to workspace root.
- Install dependencies.
- Add
.envto.gitignore. - Create
.env.example. - Verify API connectivity with curl.
- Implement app code using exact snippets from the Mandatory Code Snippets section.
- Run build/lint checks.
File Structure (Feature-Based)
Every component lives in its own directory containing exactly two files: the component file and its CSS Module. No component files sit loose in a parent folder.
src/
├── main.tsx
├── App.tsx
├── App.module.css
├── shared/
│ ├── styles/
│ │ ├── global.css # imports tokens, typography, palette
│ │ ├── tokens.css # CSS custom properties: colors, spacing
│ │ ├── typography.css # font families, sizes, weights
│ │ ├── colors.css # color palette utility classes
│ │ └── spacing.css # margin/padding utility classes
│ ├── components/
│ │ ├── DataTable/
│ │ │ ├── DataTable.tsx # generic TanStack Table wrapper
│ │ │ └── DataTable.module.css
│ │ ├── Spinner/
│ │ │ ├── Spinner.tsx
│ │ │ └── Spinner.module.css
│ │ └── ErrorMessage/
│ │ ├── ErrorMessage.tsx
│ │ └── ErrorMessage.module.css
│ ├── hooks/
│ │ └── useLocalStorage.ts
│ ├── utils/
│ │ └── localStorage.ts # branded StorageKey type, get/set helpers
│ └── api/
│ └── client.ts # axios instance + 429 retry interceptor
├── features/
│ └── orders/
│ ├── OrdersManager/
│ │ ├── OrdersManager.tsx
│ │ └── OrdersManager.module.css
│ ├── OrdersTable/
│ │ ├── OrdersTable.tsx
│ │ └── OrdersTable.module.css
│ ├── OrderFilters/
│ │ ├── OrderFilters.tsx
│ │ └── OrderFilters.module.css
│ ├── OrderTags/
│ │ ├── OrderTags.tsx
│ │ └── OrderTags.module.css
│ ├── SellerPicker/
│ │ ├── SellerPicker.tsx
│ │ └── SellerPicker.module.css
│ ├── hooks/
│ │ ├── useOrders.ts
│ │ ├── useExport.ts
│ │ └── useSellers.ts
│ ├── types.ts
│ └── utils.tsStyling Rules
- Define design tokens as CSS custom properties in
tokens.css. - Import Google Sans in
global.css:@import url('https://fonts.googleapis.com/css2?family=Google+Sans:wght@400;500;700&display=swap'); - Each component gets its own
.module.cssfile. - No inline styles. No Tailwind. No component libraries.
Generic DataTable Component
Create a generic DataTable<T> component that:
- Accepts
columns: ColumnDef<T>[],data: T[], and optionalrenderSubComponent. - Handles pagination (page size selector: 10/25/50).
- Uses
getExpandedRowModel()for nested row expansion. - Renders via CSS Modules — the orders feature passes its own column definitions.
localStorage Key Safety
type StorageKey = `datadoe-orders-manager::${string}`;
function getItem(key: StorageKey): string | null {
return localStorage.getItem(key);
}
function setItem(key: StorageKey, value: string): void {
localStorage.setItem(key, value);
}Mandatory API Connectivity Check (before UI)
Never edit .env automatically — treat it as a protected secrets file.
Step 1: Direct Target Connectivity
source .env
curl -sS -o /tmp/datadoe-sellers.json -D /tmp/datadoe-sellers.headers \
"$VITE_PROXY_TARGET/api/v1/util/sellers-and-vendors" \
-H "datadoe-api-key: $VITE_DATADOE_API_KEY" \
-H "Accept: application/json" \
-H "Content-Type: application/json"
cat /tmp/datadoe-sellers.headers | head -1Expected: HTTP/2 200. Continue only when direct check returns HTTP 200.
If 403: wrong API key for the target. If 502: DNS/network issue. Stop and fix before coding.
Step 2: Local Proxy Verification (after npm run dev)
After starting the dev server, read its output to find the actual port (may not be 5173 if that port is in use), then run:
source .env
DEV_PORT=<actual-port-from-vite-output>
curl -sS -o /tmp/datadoe-proxy-sellers.json -D /tmp/datadoe-proxy-sellers.headers \
"http://localhost:${DEV_PORT}/api/v1/util/sellers-and-vendors" \
-H "datadoe-api-key: $VITE_DATADOE_API_KEY" \
-H "Accept: application/json" \
-H "Content-Type: application/json"
cat /tmp/datadoe-proxy-sellers.headers | head -1Expected: HTTP/1.1 200 OK. Finish only when localhost proxy check also returns HTTP 200.
Debug Path for 403/502
If either check fails, follow this mandatory debug strategy:
502+ENOTFOUND: proxy target DNS/network mismatch. VerifyVITE_PROXY_TARGETis exactlyhttps://api.datadoe.comand that the process has network access. If running in a sandbox, restart with full network permissions.502on wrong localhost port: check actual Vite port from terminal output and retry on the correct port.403: API key/target environment mismatch (e.g., staging key used against production target). Verify the API key matches the target.- After any fix, re-run both checks (direct target and localhost proxy).
Mandatory Code Snippets
The following files must be implemented exactly as shown. These are verified working against the production API. Do not modify the proxy configuration, base URL logic, header logic, or request parameter shapes.
vite.config.ts — Proxy Configuration
import { defineConfig, loadEnv } from "vite";
import react from "@vitejs/plugin-react";
export default defineConfig(({ mode }) => {
const env = loadEnv(mode, process.cwd(), "");
const proxyTarget = env.VITE_PROXY_TARGET || "https://api.datadoe.com";
return {
plugins: [react()],
server: {
proxy: {
"/api": {
target: proxyTarget,
changeOrigin: true,
secure: true,
followRedirects: true,
},
},
},
};
});Why this works: The browser sends requests to /api/v1/... on localhost. Vite's dev server proxies them to https://api.datadoe.com/api/v1/.... changeOrigin: true sets the Host header to the target. secure: true enforces TLS verification. followRedirects: true handles any 3xx from the API.
src/api/client.ts — Axios Instance with Pacing & 429 Retry
import axios from "axios";
import type { AxiosInstance, AxiosRequestConfig, AxiosResponse } from "axios";
const BASE_URL = import.meta.env.VITE_API_BASE_URL || "/api";
const API_KEY = import.meta.env.VITE_DATADOE_API_KEY;
const ORG_ID = import.meta.env.VITE_DATADOE_ORGANIZATION_ID;
const MIN_REQUEST_INTERVAL_MS = 600;
let lastRequestTime = 0;
async function waitForPacing(): Promise<void> {
const now = Date.now();
const elapsed = now - lastRequestTime;
if (elapsed < MIN_REQUEST_INTERVAL_MS) {
await new Promise((resolve) =>
setTimeout(resolve, MIN_REQUEST_INTERVAL_MS - elapsed)
);
}
lastRequestTime = Date.now();
}
function buildAuthHeaders(): Record<string, string> {
if (API_KEY) {
return { "datadoe-api-key": API_KEY };
}
if (ORG_ID) {
return { "datadoe-organization-id": ORG_ID };
}
return {};
}
const instance: AxiosInstance = axios.create({
baseURL: BASE_URL,
headers: {
"Content-Type": "application/json",
Accept: "application/json",
...buildAuthHeaders(),
},
});
instance.interceptors.request.use(async (config) => {
await waitForPacing();
return config;
});
instance.interceptors.response.use(
(response) => response,
async (error) => {
const response = error.response as AxiosResponse | undefined;
if (response?.status === 429) {
const retryAfter = parseInt(response.headers["retry-after"] || "1", 10);
const delay = retryAfter * 1000 + 200;
await new Promise((resolve) => setTimeout(resolve, delay));
return instance.request(error.config as AxiosRequestConfig);
}
return Promise.reject(error);
}
);
export default instance;Critical details:
BASE_URLis always/api(from.env), never a full URL — all requests go through the Vite proxy.- Auth headers use
datadoe-api-key(notdatadoe-organization-id) when both are available. Never send both. - The pacing interceptor enforces 600ms minimum between requests (< 2 req/s limit).
- The 429 interceptor reads
Retry-After, waits, and retries once.
src/api/datadoe.ts — API Functions with Correct Request Shapes
import client from "./client";
// The Order Line Items source id is resolved at runtime from GET /exports/sources
// by table name. Never hardcode it: ids differ between the REST and MCP surfaces and
// can change; a stale id fails the export with FIELD/SOURCE errors.
const ORDER_LINE_ITEMS_TABLE = "amazon_order_items_with_cogs";
export async function fetchSellersAndVendors() {
const response = await client.get<{ items: any[] }>(
"/v1/util/sellers-and-vendors"
);
return response.data.items;
}
// IMPORTANT: query param is sellerOrVendorIds=<uuid> (no brackets)
export async function fetchOrderLineItemsSourceId(
sellerId: string
): Promise<string> {
try {
const response = await client.get<any[]>(
`/v1/exports/sources?sellerOrVendorIds=${sellerId}`
);
const orderSource = response.data.find(
(s: any) =>
s.tableName === ORDER_LINE_ITEMS_TABLE ||
(s.name === "Order Line Items" && s.type === "SELLER_CENTRAL")
);
if (!orderSource?.id) {
throw new Error(
`Source ${ORDER_LINE_ITEMS_TABLE} not found for seller ${sellerId} - check the connection and the Data settings.`
);
}
return orderSource.id;
} catch (error) {
// Surface the failure in the UI; do not fall back to a hardcoded id.
throw error;
}
}
// Required columns for the Order Line Items source.
// NEVER pass columns: [] — an empty array returns only seller-context metadata
// (seller_or_vendor_id, seller_or_vendor_name, marketplace_country_name, etc.) with NO order fields,
// which causes the table to display empty rows.
const ORDER_LINE_ITEMS_COLUMNS = [
"amazon_order_id",
"amazon_order_item_id", // unique per line - the row key (sku can repeat within an order)
"date",
"amazon_order_status",
"fulfillment_channel",
"sales_channel",
"sku",
"line_item_number",
"child_asin",
"product_name",
"item_status",
"quantity",
"item_price_value",
"item_price_currency",
];
// IMPORTANT: export creation request shape — all fields are mandatory.
// - from/to are TOP-LEVEL ISO datetime strings (not inside filters).
// - columns must be an EXPLICIT list of field names (never empty []).
// - sendToAllOrganizationMembers is required (use false).
// - filters.combinator is lowercase: "and" or "or".
// - each filter rule must have a "not" boolean field.
export async function createExport(
sellerId: string,
sourceId: string,
dateFrom: string,
dateTo: string,
orderStatusFilters: string[] = []
) {
const body: Record<string, unknown> = {
sourceId,
sellerOrVendorIds: [sellerId],
outputType: "JSON",
columns: ORDER_LINE_ITEMS_COLUMNS,
sendToAllOrganizationMembers: false,
from: `${dateFrom}T00:00:00.000Z`,
to: `${dateTo}T23:59:59.999Z`,
};
if (orderStatusFilters.length > 0) {
body.filters = {
combinator: "or",
rules: orderStatusFilters.map((status) => ({
field: "amazon_order_status",
// Shipped / Unshipped have marketplace-prefixed variants (Shipped*, Unshipped*):
// match them with beginsWith. Pending / Canceled are exact values.
operator:
status === "Shipped" || status === "Unshipped" ? "beginsWith" : "=",
value: status,
not: false,
})),
};
}
const response = await client.post<any>("/v1/exports", body);
return response.data;
}
export async function pollExport(exportId: string) {
const response = await client.get<any>(`/v1/exports/${exportId}`);
return response.data;
}
export async function fetchExportRaw(exportId: string) {
const response = await client.get(`/v1/exports/${exportId}/raw`, {
validateStatus: (status) => status === 200 || status === 204,
});
if (response.status === 204) return null;
return response.data;
}.env.example
# Vite proxies /api → https://api.datadoe.com (CORS bypass for local dev)
VITE_API_BASE_URL=/api
VITE_PROXY_TARGET=https://api.datadoe.com
VITE_DATADOE_API_KEY=<your-api-key>Implementation Rules
- Single run: the app must work after one execution. Do not leave TODOs or placeholders.
- Test API calls first: before coding the full UI, verify the export flow works by running the mandatory connectivity checks.
- Group line items by order: the API returns flat rows. Group by
amazon_order_idbefore rendering. - Handle empty states: no sellers, no orders, export still loading — all need UI.
- Date defaults: from = 30 days ago, to = today.
- Use
outputType: "JSON"for exports. - Poll interval: 5 seconds between status checks. Timeout after 2 minutes with an error message.
- Retry on 429: auto-retry with the
Retry-Aftervalue, with incrementally increasing delays. - Use the exact code snippets from the Mandatory Code Snippets section for
vite.config.ts,src/api/client.ts, andsrc/api/datadoe.ts. - Run build and lint before finalizing.
- Leave dev server running in background after implementation.
- Report local URL, proxy check result, and any residual risk explicitly.
Protected Files
Never modify .env.
- Use
.env.exampleas reference and documentation target. - Never print
.envsecrets in output.
Post-Implementation Startup
Always run dev server in background:
npm run devVerification Checklist
After implementation, verify:
- App starts without errors (
npm run dev). - Seller picker loads and shows sellers.
- Selecting a seller and clicking "Load Orders" triggers the export flow.
- Orders appear in the table grouped by
amazon_order_id. - Expanding a row shows line items.
- Date filter changes trigger new exports.
- Status filter with checkboxes works.
- Tags can be added, removed, and persist across page reloads.
- Loading spinner shows during export polling.
- Error messages display on API failure.
- Pagination controls work (10/25/50 per page).
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

