LumoSearch Cloud SDK

Official client for LumoSearch Cloud — hosted full-text search with BM25F ranking, fuzzy matching, and autocomplete. Zero infrastructure, one API call.

LumoSearch Cloud is the managed upgrade path for @lumosearch/search. Same scoring engine, but the index lives on our servers: upload documents, issue API keys, and search from any frontend or backend without managing infrastructure.

Features

• Two clients — LumoCloud for search/autocomplete, LumoAdmin for project and collection management
• Full-text search — BM25F ranking with field weights, fuzzy matching, and character-level highlights
• Autocomplete — prefix-aware suggestions with the same scoring pipeline
• Faceted search — count results by field values alongside search results
• Semantic reranking — optional hybrid scoring via semanticAlpha parameter
• Project & collection management — create, list, and delete projects and collections
• Document ingestion — replace-only upload with async indexing
• API key management — admin keys (full access) and public search keys (single collection, read-only)
• Works everywhere — browser, Node.js, edge runtimes — anything with fetch
• TypeScript-first — full type definitions with generics for your document shape
• Zero dependencies — pure ES modules, no runtime deps

Install

npm install @lumosearch/cloud

Quick Start

Search (public key)

import { LumoCloud } from '@lumosearch/cloud'

const client = new LumoCloud({
  publicKey: 'pk_search_xxxxxxxx',
  collection: 'col_abc123',
})

const { results } = await client.search('javascript patterns')
// => [{ item: { title: 'JavaScript Patterns', ... }, score: 0.94, highlights: [...] }]

const { results: suggestions } = await client.autocomplete('jav', { limit: 5 })

Admin (admin key)

import { LumoAdmin } from '@lumosearch/cloud'

const admin = new LumoAdmin({
  adminKey: 'sk_admin_xxxxxxxx',
})

// Create a project
const { project } = await admin.createProject('My App')

// Create a collection with weighted fields
const { collection } = await admin.createCollection(project.projectId, 'Articles', {
  keys: [{ name: 'title', weight: 3 }, { name: 'body', weight: 1 }],
})

// Upload documents (replace-only)
await admin.replaceDocuments(collection.collectionId, project.projectId, [
  { title: 'JavaScript Patterns', body: 'Reusable design patterns for JavaScript.' },
  { title: 'TypeScript Handbook', body: 'Core TypeScript syntax and type system.' },
])

// Issue a public search key scoped to this collection
const searchKey = await admin.createSearchKey(
  collection.collectionId,
  project.projectId,
  'frontend-key'
)
console.log(searchKey.key) // pk_search_... (shown once)

API

LumoCloud — Search Client

new LumoCloud({
  publicKey: string,
  collection: string,
  endpoint?: string,  // default: https://api.lumosearch.com
})

| Method | Description | |--------|-------------| | search<T>(query, options?) | Full-text search with ranking and highlights | | autocomplete<T>(query, options?) | Prefix-aware autocomplete suggestions |

Search Options

interface SearchOptions {
  limit?: number
  filters?: Record<string, unknown>
  facets?: string[]
  semanticAlpha?: number  // 0-1, blend between lexical and semantic scoring
}

LumoAdmin — Admin Client

new LumoAdmin({
  adminKey: string,
  endpoint?: string,  // default: https://api.lumosearch.com
})

Projects

| Method | Description | |--------|-------------| | listProjects() | List all projects | | createProject(name) | Create a new project | | deleteProject(projectId) | Delete a project |

Collections

| Method | Description | |--------|-------------| | listCollections(projectId) | List collections in a project | | createCollection(projectId, name, schema) | Create a collection with field weights | | getCollection(collectionId, projectId) | Get collection details and status | | deleteCollection(collectionId, projectId) | Delete a collection |

Documents

| Method | Description | |--------|-------------| | replaceDocuments(collectionId, projectId, docs) | Replace all documents (triggers async indexing) |

API Keys

| Method | Description | |--------|-------------| | listKeys(projectId) | List all keys for a project | | createAdminKey(projectId, name) | Create an admin key (full project access) | | createSearchKey(collectionId, projectId, name) | Create a public search key (single collection) | | revokeKey(keyId, projectId) | Revoke a key |

Collection Schema

interface CollectionSchema {
  keys: SchemaKey[]
  synonyms?: Record<string, string[]>
  semantic?: {
    enabled: boolean
    provider?: string
    model?: string
    dimensions?: number
  }
}

interface SchemaKey {
  name: string
  weight?: number  // default: 1
}

Result Shape

interface SearchResult<T> {
  refIndex: number
  score: number
  item: T
  matchedFields: string[]
  highlights: Highlight[]
}

interface Highlight {
  field: string
  value: string
  indices: [number, number][]  // character ranges
}

interface SearchResponse<T> {
  results: SearchResult<T>[]
  facets?: { [field: string]: { [value: string]: number } }
  meta?: { collection?: string; queryTimeMs?: number; semanticReranking?: boolean }
}

Error Handling

All API errors throw LumoCloudError:

import { LumoCloudError } from '@lumosearch/cloud'

try {
  await client.search('test')
} catch (err) {
  if (err instanceof LumoCloudError) {
    console.log(err.code)       // e.g. "invalid_key"
    console.log(err.statusCode) // e.g. 401
    console.log(err.message)    // human-readable message
  }
}

LumoSearch OSS vs Cloud

| | @lumosearch/search | @lumosearch/cloud | |--|--|--| | Runs | In-browser / in-process | Hosted API | | Index | Client builds and holds in memory | Server builds async, stored in S3 | | Best for | Static sites, small datasets (<100K docs) | Production apps, large datasets, multi-tenant | | Dependencies | Zero | Zero |

Contributing

Contributions are welcome. Please open an issue first to discuss what you'd like to change.

git clone https://github.com/lumosearch/cloud.git
cd cloud
npm install
npm run build

License

MIT