VectorHook JavaScript Client

The official JavaScript client for VectorHook, a modern search-as-a-service platform offering AI-powered search capabilities for applications of all sizes.

Installation

Using npm

npm install @vectorhook/client

Using yarn

yarn add @vectorhook/client

Using CDN

<script src="https://cdn.vectorhook.com/sdk/v1/vectorhook-client.min.js"></script>

Initialization

// ES Module import
import VectorHook from '@vectorhook/client';

// CommonJS require
// const VectorHook = require('@vectorhook/client');

// Initialize the client
const vectorhook = new VectorHook({
  apiKey: 'your_api_key',
  baseUrl: 'https://api.vectorhook.com', // Optional, this is the default
  timeout: 30000 // Optional, timeout in milliseconds (30 seconds by default)
});

Quick Start

Create a collection

// Define a collection schema
const schema = {
  name: 'products',
  fields: [
    { name: 'id', type: 'string' },
    { name: 'name', type: 'string' },
    { name: 'description', type: 'string' },
    { name: 'price', type: 'float' },
    { name: 'categories', type: 'string[]', facet: true },
    { name: 'in_stock', type: 'bool', facet: true }
  ],
  default_sorting_field: 'price'
};

// Create the collection
const collection = await vectorhook.collections.create(schema);

Add documents

// Add a single document
const document = {
  id: '1',
  name: 'Wireless Headphones',
  description: 'Premium noise-cancelling wireless headphones with 20-hour battery life',
  price: 199.99,
  categories: ['electronics', 'audio'],
  in_stock: true
};

const result = await vectorhook.documents.create('products', document);

// Add multiple documents
const documents = [
  {
    id: '2',
    name: 'Smart Watch',
    description: 'Fitness tracker and smartwatch with heart rate monitoring',
    price: 149.99,
    categories: ['electronics', 'wearables'],
    in_stock: true
  },
  {
    id: '3',
    name: 'Bluetooth Speaker',
    description: 'Portable bluetooth speaker with 360-degree sound',
    price: 79.99,
    categories: ['electronics', 'audio'],
    in_stock: true
  }
];

const results = await vectorhook.documents.import('products', documents);

Search documents

// Perform a basic search
const searchParams = {
  q: 'wireless headphones',
  query_by: 'name,description',
  sort_by: 'price:asc',
  per_page: 10
};

const results = await vectorhook.search.search('products', searchParams);

Track events

// Track a search event
await vectorhook.events.track({
  event_type: 'search',
  collection: 'products',
  user_id: '123', // Optional user ID
  anonymous_id: 'anon_456', // Optional anonymous user ID
  properties: {
    query: 'wireless headphones',
    filters: { price_range: '100-200', in_stock: true },
    results_count: 15,
    page: 1
  }
});

// Track a click event
await vectorhook.events.track({
  event_type: 'click',
  collection: 'products',
  document_id: '1234', // ID of the clicked document
  user_id: '123',
  anonymous_id: 'anon_456',
  properties: {
    position: 3, // Position in search results
    query: 'wireless headphones',
    source: 'search_results'
  }
});

Documentation

For complete documentation, visit https://docs.vectorhook.com.

Features

Collections API: Create, retrieve, and manage collections
Documents API: Create, retrieve, update, and delete documents
Search API: Perform search operations with filtering, faceting, and sorting
Events API: Track user interactions with search results
Users API: Identify and track users for personalized search experiences
Analytics API: Get insights into search behavior and system performance

Core Modules

Collections API

// List all collections
const collections = await vectorhook.collections.list();

// Create a collection
const collection = await vectorhook.collections.create(schema);

// Get a collection by name
const collection = await vectorhook.collections.get('products');

// Delete a collection
await vectorhook.collections.delete('products');

// Create a synonym
await vectorhook.collections.createSynonym('products', {
  symbols: ['phone', 'mobile', 'smartphone'],
  root: 'phone'
}, 'phone-synonyms');

// Create an override (curation)
await vectorhook.collections.createOverride('products', {
  rule: { query: 'headphones', match: 'exact' },
  includes: [{ id: '1234', position: 1 }]
}, 'headphones-curation');

Documents API

// Create a document
const document = await vectorhook.documents.create('products', {
  id: '1',
  name: 'Product Name',
  price: 99.99
});

// Import multiple documents
const results = await vectorhook.documents.import('products', documents);

// Get a document by ID
const document = await vectorhook.documents.get('products', '1');

// Update a document
const result = await vectorhook.documents.update('products', '1', updatedDocument);

// Delete a document
await vectorhook.documents.delete('products', '1');

Search API

// Basic search
const results = await vectorhook.search.search('products', {
  q: 'wireless',
  query_by: 'name,description'
});

// Faceted search
const results = await vectorhook.search.search('products', {
  q: 'wireless',
  query_by: 'name,description',
  facet_by: 'categories,brand,in_stock'
});

// Filtered search
const results = await vectorhook.search.search('products', {
  q: 'wireless',
  query_by: 'name,description',
  filter_by: 'price:< 200 && in_stock:true'
});

// Multi-search
const results = await vectorhook.search.multiSearch({
  searches: [
    {
      collection: 'products',
      q: 'headphones'
    },
    {
      collection: 'blog_posts',
      q: 'headphones'
    }
  ]
});

Events API

// Track an event
await vectorhook.events.track({
  event_type: 'view',
  collection: 'products',
  document_id: '123',
  user_id: 'user_456'
});

// Get all events
const events = await vectorhook.events.getEvents({
  page: 1,
  per_page: 20
});

// Get events for a collection
const events = await vectorhook.events.getCollectionEvents('products', {
  event_type: 'click'
});

// Get events for a user
const events = await vectorhook.events.getUserEvents({
  user_id: 'user_123'
});

Users API

// Identify a user
await vectorhook.users.identify({
  user_id: 'user_123',
  properties: {
    name: 'John Doe',
    email: 'john@example.com'
  }
});

// Get a user profile
const profile = await vectorhook.users.getProfile('user_123', {
  include_recent_activity: 'true'
});

// Get user activity
const activity = await vectorhook.users.getActivity('user_123', {
  limit: 20,
  include_documents: 'true'
});

Analytics API

// Get analytics overview
const overview = await vectorhook.analytics.getOverview({
  start_date: 1620000000,
  end_date: 1620086400
});

// Get event timeline
const timeline = await vectorhook.analytics.getTimeline({
  event_type: 'search',
  interval: 'day'
});

// Get system health
const health = await vectorhook.analytics.getHealth();

Error Handling

try {
  const results = await vectorhook.search.search('products', {
    q: 'wireless headphones',
    query_by: 'name,description'
  });
  
  // Process results
  console.log(results);
} catch (error) {
  if (error.status === 404) {
    console.error('Collection not found:', error.message);
  } else if (error.status === 401) {
    console.error('Authentication error:', error.message);
  } else {
    console.error('API error:', error.message);
  }
}

Support

If you have any questions or need further assistance, don't hesitate to reach out to our support team at support@vectorhook.com or visit our Community Forum.

License

This project is licensed under the MIT License - see the LICENSE file for details.