npm package: @retic/geofence-sdk
Description: JavaScript SDK for Retic Geofence Pro - geofencing, IP geolocation, and location rules
Latest version: 0.1.2

# @retic/geofence-sdk

JavaScript SDK for [Retic Geofence Pro](https://geofencepro.retic.co) — geofencing, IP geolocation, fraud detection, and location-based rules.

- Zero dependencies
- Works in any browser or bundler (ESM + UMD)
- Full TypeScript support
- Automatic device fingerprinting
- Browser geolocation with IP fallback

## Install

```bash
npm install @retic/geofence-sdk
```

Or via CDN:

```html
<script src="https://unpkg.com/@retic/geofence-sdk/dist/retic.umd.js"></script>
```

## Quick Start

```js
import { Retic } from '@retic/geofence-sdk'

const retic = Retic.initialize('your_publishable_key')

const result = await retic.trackOnce()
console.log(result.user.location)  // { latitude, longitude, city, country_code, ... }
console.log(result.user.fraud)     // { passed, vpn, proxy, tor, mocked }
console.log(result.events)         // [{ type: 'entry', geofence: { tag, ... } }]
console.log(result.rules)          // { allowed: true }
```

## API Reference

### `Retic.initialize(key, options?)`

Creates and returns the SDK singleton. Must be called before any other method.

```js
const retic = Retic.initialize('retic_live_pk_...', {
  baseUrl: 'https://geofencepro.retic.co',  // default, can be omitted
  onEvents: (events) => { /* geofence entry/exit/dwell */ },
  onRuleAction: (action) => { /* location rule triggered */ },
  onError: (err) => { /* { code, message } */ },
})
```

#### Options

| Option | Type | Description |
|---|---|---|
| `baseUrl` | `string` | API base URL. Defaults to `https://geofencepro.retic.co` |
| `onEvents` | `(events: GeofenceEvent[]) => void` | Called when geofence events are triggered |
| `onRuleAction` | `(action: RuleAction) => void` | Called when a location rule blocks the user |
| `onError` | `(error: ReticError) => void` | Called on any API error |

### `Retic.getInstance()`

Returns the existing SDK instance. Throws if `initialize()` hasn't been called.

```js
const retic = Retic.getInstance()
```

### `retic.trackOnce(location?)`

Tracks the user's location and evaluates geofences and rules. Automatically requests browser geolocation; falls back to IP-based location if denied.

```js
// Auto-detect location
const result = await retic.trackOnce()

// Or provide coordinates manually
const result = await retic.trackOnce({
  latitude: 40.7128,
  longitude: -74.0060,
  accuracy: 10,
})
```

**Returns:** `TrackResponse`

```ts
{
  events: GeofenceEvent[]  // geofence entry/exit/dwell events
  user: TrackedUser        // user info, location, and fraud check
  rules: RuleResult        // whether the user is allowed
}
```

### `retic.ipGeocode()`

Returns geolocation data for the user's IP address without triggering geofence evaluation.

```js
const geo = await retic.ipGeocode()
console.log(geo.city, geo.state, geo.country)
```

**Returns:** `IpGeocodeResponse`

```ts
{
  ip_address: string
  latitude?: number
  longitude?: number
  country_code?: string
  country?: string
  state_code?: string
  state?: string
  city?: string
  postal_code?: string
  timezone?: string
}
```

### `retic.searchGeofences(options)`

Searches for geofences near a given point.

```js
const geofences = await retic.searchGeofences({
  latitude: 40.7128,
  longitude: -74.0060,
  radius: 5000,  // meters, optional
  limit: 10,     // optional
})
```

**Returns:** `GeofenceRef[]`

```ts
{
  id: string
  tag: string
  external_id: string
  description?: string
}
```

### `retic.setUserId(userId)`

Associates a user ID with subsequent tracking calls.

```js
retic.setUserId('user_123')
```

### `retic.setMetadata(metadata)`

Attaches custom key-value metadata to subsequent tracking calls.

```js
retic.setMetadata({ plan: 'pro', source: 'checkout' })
```

## Types

All types are exported for TypeScript users:

```ts
import type {
  ReticOptions,
  TrackResponse,
  GeofenceEvent,
  GeofenceRef,
  TrackedUser,
  UserLocation,
  FraudResult,
  RuleResult,
  RuleAction,
  IpGeocodeResponse,
  SearchGeofencesOptions,
  ReticError,
} from '@retic/geofence-sdk'
```

### `GeofenceEvent`

```ts
{
  id: string
  type: 'entry' | 'exit' | 'dwell'
  confidence: number
  geofence: GeofenceRef
  created_at: string
}
```

### `FraudResult`

```ts
{
  passed: boolean   // true if no fraud signals detected
  proxy: boolean
  vpn: boolean
  tor: boolean
  mocked: boolean   // spoofed GPS
}
```

### `RuleResult`

```ts
{
  allowed: boolean       // false if a location rule blocks the user
  action?: string        // 'block' | 'redirect' | ...
  redirect_url?: string  // set when action is 'redirect'
}
```

## Framework Examples

### React

```jsx
import { Retic } from '@retic/geofence-sdk'

// Initialize once at app entry
Retic.initialize('your_key', {
  onRuleAction: ({ action, redirect_url }) => {
    if (action === 'redirect') window.location.href = redirect_url
  },
})

function App() {
  useEffect(() => {
    Retic.getInstance().trackOnce()
  }, [])

  return <div>...</div>
}
```

### Vanilla JS

```html
<script src="https://unpkg.com/@retic/geofence-sdk/dist/retic.umd.js"></script>
<script>
  const retic = Retic.Retic.initialize('your_key')
  retic.trackOnce().then(result => {
    if (!result.rules.allowed) {
      document.body.innerHTML = '<h1>Access restricted in your region</h1>'
    }
  })
</script>
```

## License

MIT