npm install @navvo/sdk
# أو: pnpm add @navvo/sdk / yarn add @navvo/sdk

import { NavvoClient } from "@navvo/sdk";

const navvo = NavvoClient.fromEnv();              // يستخدم $NAVVO_API_KEY
const navvo2 = new NavvoClient({ apiKey: "nvvo_your_key_here" });

import { NavvoClient } from "@navvo/sdk";

const navvo = new NavvoClient();

// ترميز جغرافي أمامي — تُحوَّل الإحداثيات النصية إلى أرقام تلقائيًا
const hits = await navvo.geocode("مستشفى العبدلي، عمّان", { limit: 5 });
console.log(hits[0].lat, hits[0].lng, hits[0].displayName);

// خطّط مسارًا — تمرّر { lat, lng } والمكتبة تُسلسل lon/lat على الشبكة
const plan = await navvo.route({
  locations: [
    { lat: 31.95, lng: 35.91, name: "A" },
    { lat: 31.99, lng: 35.95, name: "B" },
  ],
  costing: "auto",
});
const trip = plan.engine?.data?.trip;
console.log("الوقت المتوقّع بالثواني:", trip?.summary?.time);

// فُكّ خطّ المرحلة (polyline6) إلى نقاط
const line = NavvoClient.decodePolyline(trip?.legs?.[0]?.shape ?? "");

// بيانات حيّة وفق الظروف
const wx = await navvo.weatherPoint(31.95, 35.91);
const inc = await navvo.incidents({ bbox: { west: 35.85, south: 31.9, east: 35.99, north: 31.99 }, limit: 10 });

import {
  NavvoRateLimitError,
  NavvoForbiddenError,
  NavvoServiceUnavailableError,
} from "@navvo/sdk";

try {
  const r = await navvo.geocode("مستشفى العبدلي، عمّان");
} catch (e) {
  if (e instanceof NavvoRateLimitError) {
    console.warn("تجاوز الحدّ، أعد المحاولة بعد", e.retryAfter, "ثانية");
  } else if (e instanceof NavvoForbiddenError) {
    console.error("مشكلة نطاق/حصّة:", e.reason ?? e.message);
  } else if (e instanceof NavvoServiceUnavailableError) {
    console.error("محرّك الترميز معطّل مؤقتًا — استخدم بديلًا");
  } else {
    throw e;
  }
}

const ac = new AbortController();
const p = navvo.list({ category: "cafe" }, { signal: ac.signal });
setTimeout(() => ac.abort(), 1000);

const res = await navvo.search("صيدلية", {
  near: { lat: 31.95, lng: 35.91 },   // رتّب الأماكن الأقرب أولًا
  originType: "device",               // "map" عندما تكون near مركز الخريطة (انحياز أضعف للمسافة)
  radiusKm: 3, sort: "distance",      // كلاهما يحتاج near
  openNow: true, minRating: 4,
  amenities: ["wheelchair-accessible-entrance"],
  facets: ["category", "amenities"],  // res.facets.category و res.facets.amenities
  highlight: true,                    // items[].highlight.nameEn / nameAr
});
res.queryId;                          // لاستخدامه مع sendSearchEvent()
res.places?.items;                    // قد تحمل imageUrl و distanceKm و highlight و promoted
res.didYouMean; res.suggestions;      // عند انعدام النتائج فقط: تصحيح إملائي وأماكن شائعة

await navvo.search("rumi caf", { mode: "typeahead" });                          // أثناء الكتابة
await navvo.search("مكان هادئ للعمل مع قهوة جيدة", { semantic: "on" });        // المطابقة حسب المعنى
await navvo.search("صيدلية", { analytics: false });                             // أبقِ هذا الاستدعاء خارج التحليلات
await navvo.suggestions("صيد", { limit: 6 });                                    // GET /search/suggestions
await navvo.similar({ slug: "jordan-museum-994700", limit: 6 });                 // GET /search/similar ← { items, source }

const res = await navvo.search("مقهى", { near: { lat: 31.95, lng: 35.91 }, price: [1, 2] });
for (const p of res.places?.items ?? []) {
  console.log(p.nameEn, p.categoryName, p.priceRange, p.priceLevel, p.reviewCount);
  console.log(p.address, p.area, p.highlights);
  if (p.hours) console.log(p.hours.state, p.hours.closesAt, p.hours.opensAt, p.hours.opensDay); // اليوم، بتوقيت الأردن
}
await navvo.similar({ slug: "jordan-museum-994700", locale: "ar" }); // categoryName و address بالعربية

import { createSearchSessionId } from "@navvo/sdk";

const session = createSearchSessionId();
const res = await navvo.search("rumi cafe", { session, near: userLocation });
const place = res.places!.items[0]!;
const position = (res.places!.page - 1) * res.places!.limit + 1; // يبدأ من 1 عبر الصفحات

await navvo.sendSearchEvent({ queryId: res.queryId!, type: "click", placeId: place.id, position });
await navvo.sendSearchEvent({ queryId: res.queryId!, type: "conversion", name: "directions", placeId: place.id, position });