Getting started with the JS SDK

What is the JS SDK ?

The JS SDK is the foundation to:

• Build Gally connectors that will interact with Gally using Javascript (using Medusa JS, Strapi, etc...)
• Implement front-end features that uses Gally (autocomplete, user behavior analytics, etc...)

Using the Gally JS SDK you will be able to interact with your catalog using Javascript on both client and server side.
The SDK can help you do the following operations:

• Catalog Management: syncing catalogs, metadata, source fields, and field options
• Indexation: Creating, bulk indexing, and managing search indexes
• Search: Full-text search, filtering, faceting, sorting, and pagination
• Track user interactions: views, searches, add-to-cart, orders

Requirements

In order to use the SDK you will need

• Node.js >= 18.0.0 (uses native fetch)
• NPM (if your application uses a bundler)

Install

npm install @elastic-suite/gally-sdk

Configuration

The Gally SDK requires configuration to connect to your Gally instance.

import { Configuration } from '@gally/sdk'

const config = new Configuration({
  baseUri: 'https://your-gally-instance.com/api/',
  user: 'admin@example.com',
  password: 'your-password',
  checkSSL: true,
})

Configuration Options

Option	Type	Required	Default	Description
baseUri	string	✅	-	Base URI of your Gally API (must end with /)
user	string	⚠️	-	User email for authentication (not required for browser/public APIs)
password	string	⚠️	-	User password (not required for browser/public APIs)
checkSSL	boolean	❌	true	Enable SSL certificate verification

Note: user and password are only required for backend operations (catalog sync, indexing). For browser usage (search and tracking), credentials are not needed as these are public APIs.

Browser Configuration

For client-side applications, for easier usage, you can pass the config object or juste the baseUri directly.

import { SearchManager, TrackingEventManager, Configuration } from '@gally/sdk/browser'

// Use for search
const searchManager = new SearchManager({ baseUri })

// Use for tracking
const trackingManager = new TrackingEventManager({ baseUri })

Why No Credentials?

Search and tracking are public-facing APIs designed to be called directly from the browser:

• ✅ Search - Users need to search your catalog
• ✅ Tracking - Track user behavior for analytics

Authentication is only required for administrative operations:

• ⚠️ Catalog sync - Modifying catalog structure
• ⚠️ Indexing - Managing search indexes

Security Considerations

When using the SDK in the browser:

• ✅ Use HTTPS - Always use secure connections
• ✅ Rate limiting - Implement client-side rate limiting
• ✅ CORS - Ensure your Gally instance allows your domain
• ❌ Never expose admin credentials - Use the browser bundle only for search and tracking

Environment-Specific Configuration

See environments specific configurations

Development

const devConfig = new Configuration({
  baseUri: 'http://localhost:8000/api/',
  user: 'dev@example.com',
  password: 'dev-password',
  checkSSL: false, // Disable SSL check for local development
})

Production

const prodConfig = new Configuration({
  baseUri: 'https://gally.yourcompany.com/api/',
  user: process.env.GALLY_USER,
  password: process.env.GALLY_PASSWORD,
  checkSSL: true, // Always enable SSL check in production
})

Environment Variables

Store sensitive configuration in environment variables:

# .env
GALLY_BASE_URI=https://your-gally-instance.com/api/
GALLY_USER=admin@example.com
GALLY_PASSWORD=your-secure-password
GALLY_CHECK_SSL=true

Load with dotenv:

import 'dotenv/config'

const config = new Configuration({
  baseUri: process.env.GALLY_BASE_URI!,
  user: process.env.GALLY_USER!,
  password: process.env.GALLY_PASSWORD!,
  checkSSL: process.env.GALLY_CHECK_SSL === 'true',
})

Token Cache Manager

You can implement custom token caching to improve performance and reduce authentication requests

See example of token cache manager implementations

import { TokenCacheManager } from '@gally/sdk'

// Example: In-memory cache
const tokenCache: TokenCacheManager = {
  async getToken(getToken, useCache = true) {
    if (useCache) {
      const cached = await myCache.get('gally_token')
      if (cached) return cached
    }
    const token = await getToken()
    await myCache.set('gally_token', token)
    return token
  },
}

// Use with services
const indexOp = new IndexOperation(config, tokenCache)
const trackingManager = new TrackingEventManager(config, tokenCache)

Redis Token Cache Example

import Redis from 'ioredis'

const redis = new Redis()

const tokenCache: TokenCacheManager = {
  async getToken(getToken, useCache = true) {
    const cacheKey = 'gally:auth:token'
    
    if (useCache) {
      const cached = await redis.get(cacheKey)
      if (cached) {
        return JSON.parse(cached)
      }
    }
    
    const token = await getToken()
    
    // Cache for 1 hour (tokens typically expire after 1 hour)
    await redis.setex(cacheKey, 3600, JSON.stringify(token))
    
    return token
  },
}

Configuration Validation

The SDK validates configuration on initialization:

try {
  const config = new Configuration({
    baseUri: 'invalid-url', // ❌ Missing protocol
    user: '',               // ❌ Empty user
    password: '',           // ❌ Empty password
  })
} catch (error) {
  console.error('Configuration error:', error.message)
}

Best Practices

1. Use environment variables for sensitive data
2. Enable SSL verification in production
3. Implement token caching to reduce authentication overhead
4. Validate configuration at application startup
5. Use separate configurations for different environments
6. Rotate credentials regularly for security
7. Never commit credentials to version control

An isomorphic SDK

The SDK is designed to be as isomorphic as possible so you can use it on both server and client side. But some operations are better done on one side by design.

The provides a full export for Node and reduced export for browser specific functions

Node bundle:

Catalog management and indexation are typically done on server side because they are heavy operation that will use your database. The Node bundle theoretically allows access to the full SDK, but using the tracking feature on node side is not recommended as it is not guaranteed to work in the future

import { StructureSynchronizer, IndexOperation } from '@gally/sdk'

Browser bundle:

Tracking will be done on client side most of the time as it relies on real time user interactions.
Searching is also included in the browser bundle as SearchManager handles autocompletion, facets etc...

import { SearchManager, TrackingEventManager } from '@gally/sdk/browser'

Server and client side:

Search can be done on both depending on your needs

Next Steps

Now you can start to manage your content with the JS SDK