NearIQ JavaScript SDK: full method reference and types

import { NearIQ } from '@neariq/sdk'
const client = new NearIQ({ apiKey: process.env.NEARIQ_API_KEY! })

get(): Promise<Business>

const biz = await client.me.get()
console.log(biz.name, biz.rating, biz.plan)

competitors(params?: {
  limit?: number
  offset?: number
  sort?: string
}): Promise<{ data: Competitor[]; count: number }>

const { data: competitors, count } = await client.me.competitors({
  sort: 'rating_desc',
})

console.log(`Tracking ${count} competitors`)
competitors.forEach((c) => console.log(`${c.name}: ${c.rating} ★`))

alerts(params?: {
  severity?: 'info' | 'warning' | 'opportunity' | 'danger'
  limit?: number
  offset?: number
  unread?: boolean
}): Promise<{ data: Alert[]; count: number }>

// Fetch unread danger alerts
const { data: alerts } = await client.me.alerts({
  unread: true,
  severity: 'danger',
})

alerts.forEach((a) => {
  console.log(`${a.title}`)
  if (a.recommendation) console.log(`  → ${a.recommendation}`)
})

snapshots(params?: {
  days?: number
  limit?: number
}): Promise<{ data: Snapshot[] }>

const { data: snaps } = await client.me.snapshots({ limit: 30 })
snaps.forEach((s) => console.log(`${s.capturedAt}: ${s.rating} ★`))

reviews(): Promise<ReviewsResponse>

const result = await client.me.reviews()
console.log(`${result.reviews.length} reviews fetched`)
console.log(`Owner response rate: ${result.ownerResponseRate}`)

gbpHealth(): Promise<GBPHealthResponse>

const health = await client.me.gbpHealth()
console.log(`GBP health score: ${health.score}/100`)

const failing = health.checks.filter((c) => !c.done)
failing.forEach((c) => console.log(`  ✗ ${c.label}: ${c.detail}`))

get(id: string): Promise<CompetitorDetail>

const c = await client.competitors.get('comp_abc123')
console.log(`${c.name} — ${c.rating} ★, health ${c.healthScore}`)
console.log(`Status: ${c.status}, last checked ${c.lastCheckedAt}`)

snapshots(
  id: string,
  params?: { days?: number; limit?: number }
): Promise<{
  competitor: { id: string; name: string }
  count: number
  snapshots: Snapshot[]
}>

const result = await client.competitors.snapshots('comp_abc123', { limit: 60 })

console.log(`${result.competitor.name} — ${result.count} snapshots`)
result.snapshots.forEach((s) =>
  console.log(`  ${s.capturedAt}: ${s.rating} ★ (${s.reviewCount} reviews)`)
)

reviews(id: string): Promise<ReviewsResponse & {
  competitor: { id: string; name: string }
}>

const result = await client.competitors.reviews('comp_abc123')

console.log(`${result.competitor.name} reviews (source: ${result.source})`)
result.reviews.slice(0, 5).forEach((r) =>
  console.log(`  ${r.rating}★ — ${r.text ?? '(no text)'}`)
)

list(): Promise<{ data: WebhookEndpoint[]; count: number }>

const { data: hooks, count } = await client.webhooks.list()
console.log(`${count} webhook endpoints registered`)
hooks.forEach((h) => console.log(`${h.url} — active: ${h.active}`))

create(body: {
  url: string
  events: string[]
}): Promise<WebhookEndpoint & { secret: string; note: string }>

const hook = await client.webhooks.create({
  url: 'https://example.com/hooks/neariq',
  events: ['competitor.rating_change', 'alert.created'],
})

// Store hook.secret securely — it will not be returned again
console.log(`Webhook created: ${hook.id}`)
console.log(`Secret (save this!): ${hook.secret}`)

update(
  id: string,
  body: { url?: string; events?: string[]; active?: boolean }
): Promise<WebhookEndpoint>

// Pause a webhook without deleting it
const updated = await client.webhooks.update('wh_abc123', { active: false })
console.log(`Webhook active: ${updated.active}`)

delete(id: string): Promise<void>

await client.webhooks.delete('wh_abc123')
console.log('Webhook deleted')

export(params?: { include?: string }): Promise<ExportResponse>

// Export everything
const data = await client.export()
console.log(`Exported at ${data.exportedAt}`)
console.log(`${data.competitors?.length} competitors`)
console.log(`${data.alerts?.length} alerts`)

// Export only alerts
const alertsOnly = await client.export({ include: 'alerts' })

usage(): Promise<UsageResponse>

const stats = await client.usage()
console.log(`Plan: ${stats.plan}`)
console.log(`Tracking ${stats.competitors.tracked} competitors`)
console.log(`${stats.alerts.last30Days} alerts in the last 30 days`)
stats.apiKeys.forEach((k) =>
  console.log(`Key "${k.name ?? k.id}" — last used ${k.lastUsedAt ?? 'never'}`)
)

interface Business {
  id: string
  name: string
  category: string | null
  address: string | null
  website: string | null
  phone: string | null
  googlePlaceId: string | null
  rating: number | null
  reviewCount: number | null
  plan: string | null
  createdAt: string
  updatedAt: string | null
}

interface Competitor {
  id: string
  name: string
  rating: number | null
  reviewCount: number | null
  address: string | null
  placeId: string | null
  category: string | null
  ratingDelta30d: number | null
  reviewDelta30d: number | null
}

interface CompetitorDetail extends Competitor {
  phone: string | null
  website: string | null
  status: string | null
  priceLevel: string | null
  editorialSummary: string | null
  services: string[]
  openNow: boolean | null
  hours: Record<string, string> | null
}

interface Snapshot {
  id: string
  rating: number | null
  reviewCount: number | null
  capturedAt: string
}

interface Alert {
  id: string
  title: string
  description: string | null
  recommendation: string | null
  severity: 'info' | 'warning' | 'opportunity' | 'danger'
  type: string
  competitorName: string | null
  createdAt: string
}

interface Review {
  rating: number
  text: { text: string } | undefined
  authorAttribution: { displayName: string; photoUri?: string }
  relativePublishTimeDescription: string
  publishTime: string
  likes: number | null
  ownerResponse: string | null
  ownerResponseDate: string | null
  reviewerReviewCount: number | null
  isLocalGuide: boolean
}

interface ReviewSentiment {
  summary: string
  themes: Array<{
    label: string
    sentiment: 'positive' | 'negative' | 'mixed'
    count: number
    examples?: string[]
  }>
  keywords: string[]
  trend?: 'improving' | 'declining' | 'stable' | null
  trendNote?: string | null
}

interface ReviewsResponse {
  reviews: Review[]
  sentiment: ReviewSentiment | null
  ratingDistribution: Record<number, number> | null
  ownerResponseRate: number | null
  source: 'serp' | 'places' | 'cache' | null
  fromCache?: boolean
}

interface GBPHealthResponse {
  score: number
  checks: Array<{
    id: string
    label: string
    status: 'pass' | 'fail' | 'warn'
    message?: string
  }>
}

interface WebhookEndpoint {
  id: string
  url: string
  events: string[]
  active: boolean
  secret?: string
  createdAt: string
  lastTriggeredAt: string | null
}

interface UsageResponse {
  accountId: string
  plan: string
  trialEndsAt: string | null
  memberSince: string | null
  competitors: { tracked: number }
  alerts: { last30Days: number }
  apiKeys: Array<{
    id: string
    name: string | null
    createdAt: string
    lastUsedAt: string | null
    revoked: boolean
  }>
}

interface ExportResponse {
  exportedAt: string
  accountId: string
  business?: Business | null
  competitors?: Array<
    CompetitorDetail & { latestSnapshot: Snapshot | null; snapshotCount: number }
  >
  alerts?: Alert[]
}

interface NearIQError extends Error {
  status: number  // HTTP status code
  body: unknown   // Parsed JSON response body
}