JavaScript SDK

function createEngine(
  input: Pack | Pack[],
  options?: { minCoverage?: number; culture?: Culture },
): AliasEngine;

interface AliasEngine {
  search(query: string, options?: AliasSearchOptions): AliasSearchOutput;
  // culture: false gives the canonical ranking, typed as alias results only
  search(query: string, options: AliasSearchOptions & { culture: false }): CanonicalSearchOutput;
  get(id: string): EmojiEntry | undefined;
  withCulture(culture: Culture | undefined): AliasEngine; // shares the index
  readonly culture: Culture | undefined;
  readonly entries: readonly EmojiEntry[];
  readonly locales: readonly string[];
  readonly packVersion: string;
}

interface AliasSearchOptions {
  limit?: number; // default 24
  locale?: string;
  prefix?: boolean; // default true
  culture?: boolean; // false = canonical ranking only
  region?: string; // ISO 3166-1 alpha-2, for regional culture entries
  now?: Date | number; // the day culture windows are checked against
  day?: string; // "YYYY-MM-DD", wins over now
}

const packs = await loadPacks({ baseUrl: "https://api.emojisense.com/v1/pack/0.1.0" });
const engine = createEngine(packs);
engine.search("greatest of all time").results;
// [{ emoji: "🐐", id: "1F410", score: 0.88, source: "alias" }, …]

type ResultSource = "alias" | "semantic" | "custom" | "culture";

interface SearchResult {
  emoji: string; // "🦖", or ":shortcode:" for a custom emoji
  id: string; // Emojibase hexcode of the base emoji, "1F996"; "C-<id>" for a custom emoji
  score: number; // 0–1, comparable within one source only
  source: ResultSource;
  imageUrl?: string; // custom emoji: the image to draw
  shortcode?: string; // custom emoji: the shortcode without colons
}

interface AliasResult extends SearchResult {
  source: "alias" | "custom";
  label: string; // the emoji's name
  match: string; // the phrase that matched best
  field: "name" | "shortcode" | "keyword" | "alias" | "typo" | "low";
}

interface CultureResult extends SearchResult {
  source: "culture";
  context: string; // why the emoji fits, in the culture file's language
  cultureId: string; // e.g. "goat-football"
  match: string; // the trigger that matched
  field: "culture";
}

interface AliasSearchOutput {
  query: string; // normalized
  tokens: string[];
  results: (AliasResult | CultureResult)[]; // culture results only with a culture file
  confidence: number; // score of the best canonical result, 0 when nothing matched
}

interface CanonicalSearchOutput extends AliasSearchOutput {
  results: AliasResult[];
}

interface EmojiEntry {
  emoji: string;
  id: string;
  group: string;
  version: number;
  hasSkinTones: boolean;
  labels: Record<string, string>; // per loaded locale
  imageUrl?: string; // custom emoji only
  shortcode?: string; // custom emoji only
}

function loadPacks(options: {
  baseUrl: string; // "https://api.emojisense.com/v1/pack/0.1.0"
  locales?: string[]; // default ["en"]; English always loads first
  part?: "core" | "ext"; // default "core"
  fetch?: typeof fetch;
  signal?: AbortSignal;
}): Promise<Pack[]>;

// Your app's custom emoji as a pack, searched on the device next to the standard set.
function loadCustomPack(options: {
  endpoint: string; // the API base URL
  key: string; // publishable key
  tenant?: string; // your customer's external id (tenants, Scale plan)
  fetch?: typeof fetch;
  signal?: AbortSignal;
}): Promise<Pack>;

function createSearchSession(options: {
  engine: AliasEngine;
  semantic?: SemanticProvider; // omit for fully offline search
  locale?: string;
  limit?: number; // default 24
  debounceMs?: number; // default 200
  shouldUseSemantic?: (alias: AliasSearchOutput) => boolean;
  culture?: Culture | false; // default: the engine's; false = canonical ranking only
  region?: string; // for regional culture entries, e.g. "BR"
  onChange: (state: SessionState) => void;
}): { update(query: string): void; dispose(): void };

interface SessionState {
  query: string;
  results: SearchResult[]; // with culture results after the top result
  alias: CanonicalSearchOutput; // the dictionary answer, no culture
  status: "idle" | "alias" | "loading" | "fused" | "error";
  aliasMs: number;
  semanticMs?: number;
  semanticCached?: boolean;
  layer?: "device" | "shard" | "api";
  error?: unknown;
}

interface SemanticProvider {
  // undefined means "no answer here": the next provider gets the query.
  search(
    query: string,
    options?: { locale?: string; limit?: number; signal?: AbortSignal },
  ): Promise<SemanticResponse | undefined>;
}

// Layer 3, the API (GET /v1/search?mode=semantic)
createSemanticClient({ endpoint: "https://api.emojisense.com", key: "pk_live_…" });

// Layer 2, precomputed results as static files
createShardProvider({ baseUrl: "https://api.emojisense.com/p/0.1.0" });

// Both, cheapest first. Returns undefined when neither is configured.
createLayeredSemantic({ shardsUrl, endpoint, key, packVersion });

// Any providers, in order: the first answer wins.
chainProviders(shards, api);

normalize("¡Feliz cumpleaños!"); // "feliz cumpleanos"
tokenize(normalize("Ship it!")); // ["ship","it"]
applySkinTone("👍", "medium-dark"); // "👍🏾"
baseId("1F44D-1F3FD"); // "1F44D"
groupLabel("food-drink", "tr"); // "Yiyecek ve içecek"
hexcodeOf("❤️‍🔥"); // "2764-FE0F-200D-1F525"

const culture = await loadCulture({ baseUrl: "https://api.emojisense.com/v1/culture/0.1.0", locale: "es" });
const cultured = engine.withCulture(culture); // shares the index

cultured.search("goat", { locale: "es" }).results;
// [🐐 (alias), ⚽ 🇦🇷 🇵🇹 (source "culture", context, cultureId), …]
cultured.search("goat", { culture: false }); // the canonical ranking only

relevantNow(culture, { region: "MX", limit: 8 });
// [{ emoji: "💀", hexcode: "1F480", context: "Día de Muertos, 1 y 2 de noviembre", cultureId: "dia-de-muertos" }, …]

EMOJI_SETS; // ["native", "twemoji", "noto", "fluent"]
isEmojiSet("noto"); // true

emojiImageUrl("🦖", { endpoint: "https://api.emojisense.com", emojiSet: "noto" });
// "https://api.emojisense.com/v1/sets/noto/1F996.svg"