Skip to content

AGENTS.md

Latest commit

 

History

History
71 lines (48 loc) · 4 KB

AGENTS.md

File metadata and controls

71 lines (48 loc) · 4 KB

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

File Role
index.ts Browser entry point. Registers viInit on the global window/self context and replays any queued stub calls.
src/visearch.ts Core factory function ViSearch(configs). Returns a ViSearchClient instance. Owns tracker lifecycle, event sending, query-ID persistence, and A/B experiment wrapping.
src/productsearch.ts All API search functions (multisearch, searchByImage, searchById, etc.). Each function assembles query params and delegates to sendPostRequest or sendGetRequest.
src/common.ts Low-level HTTP helpers (sendGetRequest, sendPostRequest). Handles FormData construction, image resizing before upload, timeout racing, and response parsing.
src/resizer.ts Canvas-based image resize logic (default 512×512 max). Used by sendPostRequest automatically unless disable_resize is set.
types/shared.d.ts All public TypeScript types: ViSearchClient, ViSearchSettings, ProductSearchResponse, etc.

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.