Raily TypeScript SDK

Official TypeScript/JavaScript client for the Raily search API — search your own sources from your app with a typed, one-call client.

Documentation · Source

Install

npm install @raily/sdk

Quickstart

import { Raily } from "@raily/sdk";

const client = new Raily({ apiKey: "rly_...", endpoint: "https://<your-endpoint-url>" });

const hits = await client.search("anti-aging serum", { limit: 5 });
for (const hit of hits) {
  console.log(hit.score, hit.fields.title);
}

Authentication

Create an API key in your Raily workspace (Identities → API keys) and pass it as apiKey. The endpoint is your endpoint's URL. A key is scoped to one workspace and to the endpoint it was issued for — using it elsewhere is rejected.

const client = new Raily({
  apiKey: process.env.RAILY_API_KEY!,
  endpoint: process.env.RAILY_ENDPOINT!,
});

Results

search() resolves to SearchHit[]:

| field | type | meaning | |---|---|---| | score | number \| null | relevance score | | fields | Record<string, string> | flat {name: value} map of the source's display fields, e.g. hit.fields.title | | text | string \| null | a rendered text summary | | image_url | string \| null | the result's image, for image sources | | is_relevant | boolean \| null | false for an exploratory (below-threshold) hit | | source_collection | string \| null | the source the hit came from | | id | string \| null | stable result id | | raw | Record<string, unknown> | the full original result, for anything not surfaced above |

fields is a flat object, so you read a value by name:

hit.fields.title;          // e.g. "Anti-Aging Vitamin C Serum"
hit.fields.published_date; // undefined if this source doesn't expose it

The exact keys come from the source's configured display fields (e.g. title, author, published_date). Log one hit's fields to see what your source exposes.

Debugging empty results

A bare [] doesn't say why. Pass { explain: true } for the endpoint's message plus a hint:

const res = await client.search("articles", { explain: true });
console.log(res.info.count, res.info.message, res.info.note); // note is set only when empty

Most empty results are a too-generic query ("articles" matches nothing — search a topic), a freshness filter, or an unindexed corpus. Or construct with debug: true to console.warn a hint on every empty result.

Errors

import { RailyError, RailyAuthError } from "@raily/sdk";

try {
  await client.search("query");
} catch (err) {
  if (err instanceof RailyAuthError) {
    // key missing / invalid / expired / not authorized for this endpoint
  } else if (err instanceof RailyError) {
    // everything else (network, server, protocol)
  }
}

License

Apache-2.0