@parseapi/sdk 1.9.0 → 1.10.1

package/README.md

@@ -451,3 +451,35 @@ Successful checks may be reused for up to 24 hours. `pretty` optionally formats
 Stack defaults to 35 seconds per attempt so a first scan has time to finish. Other lookups retain their 10-second default. An explicit client timeout applies to every operation; JavaScript also supports a per-call `timeoutMs` override.
 
 Vehicle lookups use `vin` as the input and response field. Existing VIN methods remain available for compatibility.
+
+## Emoji catalog additions
+
+Resolve Unicode emoji or a named shortcode, search or browse a bounded catalog,
+parse emoji positions in text, and convert between Unicode and a selected shortcode source.
+The ordinary lookup remains four fields:
+
+```http
+GET /emoji/rocket
+```
+
+```json
+{"emoji":"🚀","name":"Rocket","shortcodes":[":rocket:","rocket"],"category":"Travel & Places"}
+```
+
+Use `deep=true` for Unicode facts, keywords, tone families and available artwork.
+Artwork is keyed by style: `deep.artwork.openmoji.svg` is the SVG URL, and
+`deep.artwork.openmoji.png["72"]` is the 72×72 PNG URL (use your language’s map
+access syntax). The same shape applies to `noto` and `twemoji`. Missing styles
+and formats are omitted. URLs pin immutable artwork editions and retain their bytes.
+Core values stay unchanged. Text parsing returns `emojis` with UTF-16 `positions`;
+conversion returns `text` and unresolved tokens with positions and reasons.
+
+The compact JSON catalog contains offline identity, qualification-form and
+shortcode indexes. Request `profile=full` when artwork is needed and `lang` when
+localized names and keywords are needed. `/emoji/metadata` carries dataset
+coverage and shared source notices once. Artwork supports Google Noto, Twemoji
+and OpenMoji, with real SVG/PNG availability and immutable first-party URLs.
+A device's emoji font remains the ordinary display.
+
+These additions are a local release candidate until the matching SDK and
+backend are published. Existing lookup and search contracts are preserved.

package/dist/index.cjs

@@ -20,11 +20,272 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  EmojiCatalog: () => EmojiCatalog,
+  EmojiCatalogError: () => EmojiCatalogError,
   ParseAPIError: () => ParseAPIError,
   parseAPI: () => parseAPI
 });
 module.exports = __toCommonJS(index_exports);
-var VERSION = "1.9.0";
+
+// src/emoji-catalog.ts
+var EmojiCatalogError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "EmojiCatalogError";
+  }
+};
+var sources = ["cldr", "github", "slack", "discord"];
+var stripColons = (value) => value.trim().replace(/^:+|:+$/g, "");
+var normalizeName = (value) => stripColons(value).toLowerCase().replace(/[\s_-]+/g, "_");
+var normalizeSearch = (value) => normalizeName(value).normalize("NFD").replace(new RegExp("\\p{M}", "gu"), "").replace(/œ/g, "oe").replace(/æ/g, "ae").replace(/ß/g, "ss");
+var legacyName = (value) => stripColons(value).toLowerCase().replace(/\s+/g, "_");
+var filterKey = (value) => value.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_|_$/g, "");
+var versionCompare = (a, b) => {
+  const left = a.split(".").map(Number), right = b.split(".").map(Number);
+  return (left[0] ?? 0) - (right[0] ?? 0) || (left[1] ?? 0) - (right[1] ?? 0);
+};
+var invalid = (message) => {
+  throw new EmojiCatalogError("validation_error", message);
+};
+var EmojiCatalog = class {
+  data;
+  byGlyph = /* @__PURE__ */ new Map();
+  names = /* @__PURE__ */ new Map();
+  aliases = /* @__PURE__ */ new Map();
+  sourceAliases = /* @__PURE__ */ new Map();
+  encodings = /* @__PURE__ */ new Map();
+  searchFacts = /* @__PURE__ */ new Map();
+  categoryKeys = /* @__PURE__ */ new Set();
+  subcategoryKeys = /* @__PURE__ */ new Set();
+  filterCache = /* @__PURE__ */ new Map();
+  searchReady = false;
+  compareNames;
+  segmenter;
+  constructor(data) {
+    if (!data || !Array.isArray(data.emojis) || !data.forms || !data.shortcodes || !data.legacy || !data.metadata?.source_version) {
+      throw new EmojiCatalogError("invalid_catalog", "Use the JSON response from GET /emoji/catalog.");
+    }
+    this.data = structuredClone(data);
+    this.compareNames = new Intl.Collator(this.data.localization?.resolved_locale ?? void 0).compare;
+    const add = (map, key, glyph) => {
+      if (!key) return;
+      if (!map.has(key)) map.set(key, /* @__PURE__ */ new Set());
+      map.get(key).add(glyph);
+    };
+    for (const row of this.data.emojis) {
+      if (!row?.emoji || !row.deep?.version || !Array.isArray(row.deep.keywords)) {
+        throw new EmojiCatalogError("invalid_catalog", "Offline catalogs require the default deep=true export.");
+      }
+      this.byGlyph.set(row.emoji, row);
+      add(this.names, normalizeName(row.name), row.emoji);
+      for (const alias of row.shortcodes) add(this.aliases, normalizeName(alias), row.emoji);
+      this.categoryKeys.add(filterKey(row.category ?? ""));
+      this.subcategoryKeys.add(filterKey(row.deep.subcategory ?? ""));
+    }
+    for (const source of sources) {
+      if (!this.data.shortcodes[source]) throw new EmojiCatalogError("invalid_catalog", `Catalog is missing the ${source} shortcode map.`);
+    }
+  }
+  /** Build once on first search; shared normalized strings avoid repeated annotation copies. */
+  ensureSearch() {
+    if (this.searchReady) return;
+    const cache = /* @__PURE__ */ new Map(), normal = (value) => {
+      let result = cache.get(value);
+      if (result === void 0) {
+        result = normalizeSearch(value);
+        cache.set(value, result);
+      }
+      return result;
+    };
+    for (const source of sources) for (const [alias, glyphs] of Object.entries(this.data.shortcodes[source])) {
+      const value = normal(alias);
+      for (const glyph of glyphs) if (this.byGlyph.has(glyph)) {
+        if (!this.sourceAliases.has(glyph)) this.sourceAliases.set(glyph, /* @__PURE__ */ new Set());
+        this.sourceAliases.get(glyph).add(value);
+      }
+    }
+    const localizedKeywords = new Set(this.data.search?.localized_keywords ?? []);
+    for (const row of this.data.emojis) {
+      const native = this.data.search?.native[row.emoji];
+      const names = [...new Set([row.name, native?.name].filter((name) => typeof name === "string").map(normal))];
+      const primaryShorts = [...new Set(row.shortcodes.map(normal))];
+      const shorts = [.../* @__PURE__ */ new Set([...primaryShorts, ...this.sourceAliases.get(row.emoji) ?? []])];
+      const keywords = [...new Set([...row.deep?.keywords ?? [], ...native?.keywords ?? []].map(normal))];
+      const allNames = [...names, ...shorts];
+      this.searchFacts.set(row.emoji, { names, primaryShorts, shorts, keywords, translatedKeywords: this.data.localization?.resolved_locale && localizedKeywords.has(row.emoji) ? (row.deep?.keywords ?? []).map(normal) : [], allNames, blob: [.../* @__PURE__ */ new Set([...allNames, ...keywords])].join(" ") });
+    }
+    this.sourceAliases.clear();
+    this.searchReady = true;
+  }
+  encoding(source) {
+    let map = this.encodings.get(source);
+    if (!map) {
+      map = /* @__PURE__ */ new Map();
+      for (const [alias, glyphs] of Object.entries(this.data.shortcodes[source])) if (glyphs.length === 1 && this.byGlyph.has(glyphs[0]) && !map.has(glyphs[0])) map.set(glyphs[0], `:${stripColons(alias)}:`);
+      this.encodings.set(source, map);
+    }
+    return map;
+  }
+  /** Evidence for the full server inventory; scope() identifies this downloaded subset. */
+  metadata() {
+    return structuredClone(this.data.metadata);
+  }
+  /** Filters, local record count and whether this download contains the full server inventory. */
+  scope() {
+    return structuredClone({ ...this.data.scope, filters: this.data.scope?.filters ?? {}, total: this.data.total, complete_inventory: this.data.scope?.complete_inventory ?? this.data.total === this.data.metadata.total });
+  }
+  lookup(input, options = {}) {
+    if (typeof input !== "string" || !input.trim() || input.trim().length > 512) invalid("Emoji input must contain 1\u2013512 characters.");
+    const value = input.trim(), source = options.shortcodeSource;
+    if (source && !sources.includes(source)) invalid("shortcodeSource must be cldr, github, slack or discord.");
+    let glyph = this.byGlyph.has(value) ? value : void 0;
+    if (!glyph && !source && Object.hasOwn(this.data.legacy, legacyName(value))) glyph = this.data.legacy[legacyName(value)];
+    if (!glyph) {
+      let form = value;
+      if (/^(?:U\+)?[0-9A-F]{4,6}(?:[\s,-]+(?:U\+)?[0-9A-F]{4,6})*$/i.test(value)) {
+        const points = value.split(/[\s,-]+/).map((part) => Number.parseInt(part.replace(/^U\+/i, ""), 16));
+        if (points.length > 32 || points.some((cp) => cp > 1114111 || cp >= 55296 && cp <= 57343)) invalid("Unicode codepoints must be valid scalar values.");
+        form = String.fromCodePoint(...points);
+      } else if (/^U\+/i.test(value)) invalid("Use Unicode codepoints such as U+1F680 or U+2764 U+FE0F.");
+      const canonical = Object.hasOwn(this.data.forms, form) ? this.data.forms[form] : form;
+      if (canonical && this.byGlyph.has(canonical)) glyph = canonical;
+    }
+    if (!glyph) {
+      const candidates = /* @__PURE__ */ new Set();
+      for (const key of /* @__PURE__ */ new Set([stripColons(value).toLowerCase(), normalizeName(value)])) {
+        for (const name of source ? [source] : sources) {
+          const dictionary = this.data.shortcodes[name];
+          if (Object.hasOwn(dictionary, key)) {
+            for (const candidate of dictionary[key] ?? []) if (this.byGlyph.has(candidate)) candidates.add(candidate);
+          }
+        }
+      }
+      if (!source) for (const candidate of this.aliases.get(normalizeName(value)) ?? []) candidates.add(candidate);
+      if (!source || !candidates.size && !/^:.*:$/.test(value)) for (const candidate of this.names.get(normalizeName(value)) ?? []) candidates.add(candidate);
+      if (candidates.size > 1) invalid("Emoji shortcode is ambiguous. Set shortcodeSource to cldr, github, slack or discord.");
+      glyph = candidates.values().next().value;
+    }
+    const row = glyph ? this.byGlyph.get(glyph) : void 0;
+    if (!row) throw new EmojiCatalogError("not_found", "Emoji not found in this downloaded catalog.");
+    return this.project(row, options.deep === true);
+  }
+  search(query, options = {}) {
+    if (typeof query !== "string" || !query.trim() || query.trim().length > 256) invalid("Search query must contain 1\u2013256 characters.");
+    return this.page(query.trim(), options);
+  }
+  browse(options = {}) {
+    const { q, ...result } = this.page("", options);
+    return result;
+  }
+  /** Unknown and ambiguous inputs remain literal; positions refer to untouched input. */
+  convert(text, options) {
+    if (!options || !["to_shortcodes", "to_emoji"].includes(options.direction)) invalid("Direction must be to_shortcodes or to_emoji.");
+    if (!sources.includes(options.shortcodeSource)) invalid("shortcodeSource must be cldr, github, slack or discord.");
+    const parsed = this.parse(text), replacements = [], unresolved = [];
+    if (options.direction === "to_shortcodes") {
+      const encodings = this.encoding(options.shortcodeSource);
+      for (const row of parsed.emojis) {
+        const shortcode = encodings.get(row.emoji);
+        for (const position of row.positions) if (shortcode) replacements.push({ emoji: row.emoji, shortcode, ...position });
+        else unresolved.push({ emoji: row.emoji, ...position, reason: "unavailable" });
+      }
+    } else for (const match of text.matchAll(/:[^:\s]{1,128}:/gu)) {
+      const shortcode = match[0], start = match.index, end = start + shortcode.length;
+      try {
+        const row = this.lookup(shortcode, { shortcodeSource: options.shortcodeSource });
+        replacements.push({ emoji: row.emoji, shortcode, start, end });
+      } catch (error) {
+        if (!(error instanceof EmojiCatalogError)) throw error;
+        unresolved.push({ shortcode, start, end, reason: error.code === "not_found" ? "unknown" : "ambiguous" });
+      }
+    }
+    replacements.sort((a, b) => a.start - b.start);
+    unresolved.sort((a, b) => a.start - b.start);
+    let cursor = 0;
+    const chunks = [];
+    for (const row of replacements) {
+      chunks.push(text.slice(cursor, row.start), options.direction === "to_shortcodes" ? row.shortcode : row.emoji);
+      cursor = row.end;
+    }
+    chunks.push(text.slice(cursor));
+    return { text: chunks.join(""), unresolved };
+  }
+  /** Whole-grapheme predicate. Use parse() to extract emoji from prose with positions. */
+  regex(options = {}) {
+    const forms = options.qualifiedOnly ? [...this.byGlyph.keys()] : Object.keys(this.data.forms).filter((form) => this.byGlyph.has(this.data.forms[form]));
+    if (options.components) forms.push(...["\u{1F3FB}", "\u{1F3FC}", "\u{1F3FD}", "\u{1F3FE}", "\u{1F3FF}", "\u{1F9B0}", "\u{1F9B1}", "\u{1F9B2}", "\u{1F9B3}"]);
+    const escaped = [...new Set(forms)].sort((a, b) => b.length - a.length || (a < b ? -1 : 1)).map((form) => form.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+    return new RegExp(`^(?:${escaped.length ? escaped.join("|") : "(?!)"})$`, "u");
+  }
+  categories() {
+    const groups = /* @__PURE__ */ new Map();
+    for (const row of this.data.emojis) {
+      if (!row.category) continue;
+      if (!groups.has(row.category)) groups.set(row.category, /* @__PURE__ */ new Set());
+      if (row.deep?.subcategory) groups.get(row.category).add(row.deep.subcategory);
+    }
+    return { categories: [...groups].map(([category, subcategories]) => ({ category, subcategories: [...subcategories] })) };
+  }
+  parse(text, options = {}) {
+    if (typeof text !== "string" || text.length > 16e3) invalid("Text must be a string of at most 16000 UTF-16 code units.");
+    const found = /* @__PURE__ */ new Map();
+    this.segmenter ??= new Intl.Segmenter("en", { granularity: "grapheme" });
+    for (const { segment, index } of this.segmenter.segment(text)) {
+      const canonical = Object.hasOwn(this.data.forms, segment) ? this.data.forms[segment] : segment;
+      const row = canonical ? this.byGlyph.get(canonical) : void 0;
+      if (!row) continue;
+      if (!found.has(row.emoji)) found.set(row.emoji, { ...this.project(row, options.deep === true), positions: [] });
+      const result = found.get(row.emoji);
+      result.positions.push({ start: index, end: index + segment.length });
+    }
+    return { emojis: [...found.values()] };
+  }
+  project(row, deep) {
+    const { emoji, name, shortcodes, category } = row;
+    return { emoji, name, shortcodes: [...shortcodes], category, ...deep ? { deep: structuredClone(row.deep) } : {} };
+  }
+  page(query, options) {
+    if (options.limit !== void 0 && (!Number.isSafeInteger(options.limit) || options.limit < 1)) invalid("Limit must be a positive integer.");
+    const limit = Math.min(options.limit ?? 20, 50), offset = options.offset ?? 0;
+    if (!Number.isSafeInteger(offset) || offset < 0 || offset > 1e5) invalid("Offset must be an integer between 0 and 100000.");
+    for (const [key, known] of [["category", this.categoryKeys], ["subcategory", this.subcategoryKeys]]) {
+      if (options[key] !== void 0 && (!options[key].trim() || !known.has(filterKey(options[key])))) invalid(`Unknown emoji ${key}. Use categories() to find supported values.`);
+    }
+    for (const key of ["version", "maxVersion"]) if (options[key] !== void 0 && (!/^\d{1,2}\.\d{1,2}$/.test(options[key]) || versionCompare(options[key], this.data.metadata.source_version) > 0)) invalid(`${key} must be an Emoji version no newer than ${this.data.metadata.source_version}.`);
+    let rows = this.filtered(options);
+    if (query) {
+      this.ensureSearch();
+      const needle = normalizeSearch(query), words = needle.split("_").filter(Boolean);
+      const scored = rows.flatMap((row) => {
+        const { names, primaryShorts, shorts, keywords, translatedKeywords, allNames, blob } = this.searchFacts.get(row.emoji);
+        if (!blob.includes(needle) && !(words.length > 1 && words.every((word) => blob.includes(word)))) return [];
+        const score = primaryShorts.includes(needle) || names.includes(needle) ? 0 : shorts.includes(needle) ? 0.5 : allNames.some((value) => value.startsWith(needle)) ? 1 : translatedKeywords.includes(needle) ? 1.5 : allNames.some((value) => value.includes(needle)) ? 2 : words.length > 1 && allNames.some((value) => words.every((word) => value.includes(word))) ? 2.5 : keywords.some((value) => value.includes(needle)) ? 3 : words.length > 1 && words.every((word) => blob.includes(word)) ? 4 : 100;
+        return score === 100 ? [] : [{ row, score }];
+      });
+      rows = scored.sort((a, b) => a.score - b.score || (this.data.localization?.resolved_locale ? this.compareNames(a.row.name, b.row.name) || a.row.emoji.localeCompare(b.row.emoji) : a.row.name.localeCompare(b.row.name))).map(({ row }) => row);
+    }
+    const page = rows.slice(offset, offset + limit), paged = !query || ["category", "subcategory", "version", "maxVersion", "includeSkinTones", "offset"].some((key) => options[key] !== void 0);
+    return { q: query, emojis: page.map((row) => this.project(row, options.deep === true)), ...paged ? { total: rows.length, next_offset: offset + page.length < rows.length ? offset + page.length : null } : {} };
+  }
+  filtered(options) {
+    for (const [key2, known] of [["category", this.categoryKeys], ["subcategory", this.subcategoryKeys]]) {
+      if (options[key2] !== void 0 && (!options[key2].trim() || !known.has(filterKey(options[key2])))) invalid(`Unknown emoji ${key2}. Use categories() to find supported values.`);
+    }
+    for (const key2 of ["version", "maxVersion"]) if (options[key2] !== void 0 && (!/^\d{1,2}\.\d{1,2}$/.test(options[key2]) || versionCompare(options[key2], this.data.metadata.source_version) > 0)) invalid(`${key2} must be an Emoji version no newer than ${this.data.metadata.source_version}.`);
+    if (options.includeSkinTones !== false && options.category === void 0 && options.subcategory === void 0 && options.version === void 0 && options.maxVersion === void 0) return this.data.emojis;
+    const key = JSON.stringify([options.includeSkinTones === false, options.category === void 0 ? null : filterKey(options.category), options.subcategory === void 0 ? null : filterKey(options.subcategory), options.version, options.maxVersion]);
+    const cached = this.filterCache.get(key);
+    if (cached) return cached;
+    const rows = this.data.emojis.filter((row) => (options.includeSkinTones !== false || !/[\u{1F3FB}-\u{1F3FF}]/u.test(row.emoji)) && (options.category === void 0 || filterKey(row.category ?? "") === filterKey(options.category)) && (options.subcategory === void 0 || filterKey(row.deep?.subcategory ?? "") === filterKey(options.subcategory)) && (options.version === void 0 || versionCompare(row.deep.version, options.version) === 0) && (options.maxVersion === void 0 || versionCompare(row.deep.version, options.maxVersion) <= 0));
+    if (this.filterCache.size >= 32) this.filterCache.delete(this.filterCache.keys().next().value);
+    this.filterCache.set(key, rows);
+    return rows;
+  }
+};
+
+// src/index.ts
+var VERSION = "1.10.0";
 var API_VERSION = "2.0.0";
 var DEFAULT_BASE_URL = "https://api.parseapi.com";
 var DEFAULT_TIMEOUT_MS = 1e4;
@@ -214,6 +475,16 @@ function parseAPI(apiKey, options = {}) {
     }
   );
   return {
+    /** Create a bounded task. Reuse the same request ID and inputs on retries. */
+    task: Object.assign(
+      (input, requestId, opts) => request("/task", void 0, { "Idempotency-Key": requestId }, opts, input),
+      {
+        get: (id, opts) => request(`/task/${enc(id)}`, void 0, void 0, opts),
+        cancel: (id, opts) => request(`/task/${enc(id)}/cancel`, void 0, void 0, opts, {}),
+        /** Reuse requestId with identical inputs to recover the saved result without another lookup or charge. */
+        lookup: (id, input, requestId, opts) => request(`/task/${enc(id)}/lookup`, void 0, { "Idempotency-Key": requestId }, opts, input)
+      }
+    ),
     /** Estimate task access, capacity and additional charges. Requires a secret key. Reserves no units or money and does not enforce the supplied budget. */
     preflight: (task, opts) => request("/preflight", void 0, void 0, opts, task),
     /** Look up an IP. `deep: true` adds enrichment included with a paid plan, without a separate check meter. */
@@ -418,13 +689,23 @@ function parseAPI(apiKey, options = {}) {
     /** Get current conditions in metric and imperial units. Paid deep adds specialist current measurements, forecasts and related detail. With deep, date selects a past UTC day (YYYY-MM-DD) in deep.history alongside current conditions. Date alone does not request history. */
     weather: (lat, lon, opts) => request("/weather", { lat, lon, date: opts?.date, ...deepQuery(opts) }, void 0, opts),
     emoji: Object.assign(
-      (emoji, opts) => request(`/emoji/${enc(emoji)}`, deepQuery(opts), void 0, opts),
+      (emoji, opts) => request(`/emoji/${enc(emoji)}`, { shortcode_source: opts?.shortcodeSource, ...deepQuery(opts) }, void 0, opts),
       {
-        search: (query, opts) => request("/emoji", { q: query, limit: opts?.limit, ...deepQuery(opts) }, void 0, opts)
+        search: (query, opts) => request("/emoji", { q: query, ...emojiFilters(opts), ...deepQuery(opts) }, void 0, opts),
+        browse: (opts) => request("/emoji", { ...emojiFilters(opts), ...deepQuery(opts) }, void 0, opts),
+        categories: (opts) => request("/emoji/categories", void 0, void 0, requestControls(opts)),
+        convert: (text, opts) => request("/emoji/convert", { direction: opts.direction, shortcode_source: opts.shortcodeSource }, void 0, opts, { text }),
+        /** Extract complete sequences. Positions use UTF-16 code units; end is exclusive. */
+        catalog: (opts) => request("/emoji/catalog", { ...emojiFilters(opts), profile: opts?.profile, deep: opts?.deep ?? true }, void 0, opts),
+        metadata: (opts) => request("/emoji/metadata", void 0, void 0, requestControls(opts)),
+        parse: (text, opts) => request("/emoji/parse", deepQuery(opts), void 0, opts, { text })
       }
     )
   };
 }
+function emojiFilters(opts) {
+  return { limit: opts?.limit, category: opts?.category, subcategory: opts?.subcategory, version: opts?.version, max_version: opts?.maxVersion, include_skin_tones: opts?.includeSkinTones, offset: opts?.offset };
+}
 function timeSource(timezone, options = {}) {
   const values = { ip: options.ip, city: options.city, country: options.country, state: options.state, iata: options.iata, icao: options.icao, unlocode: options.unlocode, address: options.address };
   const primary = [options.ip, options.city, options.iata, options.icao, options.unlocode, options.address].filter((value) => value !== void 0);
@@ -445,6 +726,8 @@ function timeTargets(targets, to) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  EmojiCatalog,
+  EmojiCatalogError,
   ParseAPIError,
   parseAPI
 });