visearch-sdk-javascript

Imported from visenze/visearch-sdk-javascript (AGENTS.md). Install upstream with npx skills add visenze/visearch-sdk-javascript. Copyright stays with the author.

Commands

# Install dependencies
npm install

# Lint TypeScript source
npm run lint

# Run all tests
npm test

# Run tests with coverage
npm run test-with-coverage

# Run a single test file
npx jest test/visearch.test.js

# Build browser bundle (production, uploads to S3)
npm run build

# Build browser bundle (development, no S3 upload)
npm run build-dev

# Build ESM package output
npm run build-esm

# Build CJS package output
npm run build-cjs

# Build both CJS+ESM and run fixup (used before npm publish)
npm run prepack

Tests that hit the live API require a .env file with SEARCH_APP_KEY, SEARCH_PLACEMENT_ID, REC_APP_KEY, REC_PLACEMENT_ID, ENDPOINT, SEARCH_IM_URL, and REC_PID.

Architecture

This is a JavaScript/TypeScript SDK for the ViSearch / Rezolve product search API, distributed in three forms:

• ESM (esm/) — tree-shakeable module build via tsconfig.json
• CJS (cjs/) — CommonJS build via tsconfig.cjs.json
• Browser bundle (dist/) — single-file UMD bundle produced by Webpack from index.ts

Source layout

Key data flows

Search by image upload: ViSearch.productSearchByImage → productsearch.searchByImage → common.sendPostRequest → resizer.resizeImage (auto-resize unless disable_resize) → fetch with FormData.

Search by ID (GET): ViSearch.productSearchById → productsearch.searchById → common.sendGetRequest → fetch with URL query params.

Tracking: A visenze-tracking-javascript (VAClient) instance is lazily created on first use. Analytics params (va_uid, va_sdk, va_sid, va_sdk_version) are injected into every search request via getAnalyticsParams. Successful responses persist reqid to localStorage under the key visenze_query_id_<placement_id>.

Endpoint resolution (productsearch.ts): defaults to https://multimodal.search.rezolve.com (legacy). Set cloud: 'aws' for https://multisearch-aw.rezolve.com or cloud: 'azure' for https://multisearch-az.rezolve.com; these also switch API paths to the new v1/visearch/* / v1/search/* / v1/autocomplete layout. settings.endpoint takes full precedence — if it matches a cloud domain URL, new paths are used automatically; any other value uses legacy paths regardless of cloud. settings.is_cn routes to https://search.visenze.com.cn with legacy paths.

Stub/async loading pattern (index.ts): The SDK supports async script loading. Before the bundle loads, callers push commands onto window.<clientName>.q. After load, viInit replays those queued commands against the real client via applyPrototypesCall.

Build notes

• npm run write-version generates src/version.ts from package.json — this file is not committed and must exist before any build or test run.
• The fixup shell script post-processes CJS output (run automatically by prepack).
• Production Webpack build uploads the minified bundle to S3 (visenze-static bucket, visearch/dist/js/). Requires AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY env vars.