TypeScript SDK

npm install @airpinpoint/sdk
# or
bun add @airpinpoint/sdk

import { AirPinpoint } from "@airpinpoint/sdk";
 
const ap = new AirPinpoint({ apiKey: "your-api-key" });
 
// List all trackable devices
const { data: trackables } = await ap.trackables.list();
console.log(`Found ${trackables.length} devices`);
 
// Get current location
const location = await ap.trackables.currentLocation(trackables[0].id);
console.log(`${trackables[0].name}: ${location.latitude}, ${location.longitude}`);

const ap = new AirPinpoint({
  apiKey: process.env.AIRPINPOINT_API_KEY,
  baseURL: "https://api.airpinpoint.com/v1",
  timeout: 30000,
  maxRetries: 2,
});

const { data: trackables } = await ap.trackables.list({
  skip: 0,
  limit: 50,
});
 
for (const device of trackables) {
  console.log(`${device.name} (${device.model}) - enabled: ${device.enabled}`);
}

const device = await ap.trackables.retrieve("trk_abc123");
console.log(`${device.name} paired at ${device.pairedAt}`);

const loc = await ap.trackables.currentLocation("trk_abc123");
console.log(`Delivery Van #3: ${loc.latitude}, ${loc.longitude}`);
console.log(`Accuracy: ${loc.horizontalAccuracy}m`);
console.log(`Last seen: ${loc.timestamp}`);

const history = await ap.trackables.locationHistory("trk_abc123", {
  startTime: "2024-01-14T00:00:00Z",
  endTime: "2024-01-15T23:59:59Z",
  limit: 200,
});
 
console.log(`${history.length} location points`);
for (const point of history) {
  console.log(`  ${point.timestamp}: ${point.latitude}, ${point.longitude}`);
}

const battery = await ap.trackables.battery("trk_abc123");
console.log(`Level: ${battery.batteryLevel}`); // 0=full, 1=medium, 2=low, 3=critical
console.log(`Days remaining: ${battery.estimatedDaysRemaining}`);

const result = await ap.trackables.resetBattery("trk_abc123", {
  batteryMonths: 12,
});
console.log(result.message); // "Battery reset successfully"

const { data: fences } = await ap.geofences.list({
  limit: 20,
  trackableId: "trk_abc123", // optional filter
});
 
for (const fence of fences) {
  console.log(`${fence.name}: ${fence.radius}m radius at ${fence.latitude}, ${fence.longitude}`);
}

const fence = await ap.geofences.create({
  name: "Warehouse Zone A",
  latitude: 37.7749,
  longitude: -122.4194,
  radius: 200,
  trackableId: ["trk_abc123", "trk_def456"],
  notifyType: "both",
  notifyDestination: "https://yourapp.com/webhooks/geofence",
  webhookSecret: "whsec_your_secret",
  webhookEnabled: true,
});
 
console.log(`Created geofence: ${fence.id}`);

const updated = await ap.geofences.update("geofence_789012", {
  name: "Warehouse Zone A (Expanded)",
  radius: 300,
  webhookEnabled: true,
});
 
console.log(`Updated: ${updated.name}, radius: ${updated.radius}m`);

const result = await ap.geofences.del("geofence_789012");
console.log(result.message); // "Geofence deleted successfully"

const result = await ap.geofences.testWebhook("geofence_789012", {
  eventType: "entry",
});
 
console.log(`Test delivery: ${result.deliveryId}`);

const deliveries = await ap.geofences.webhooks.list("geofence_789012", {
  limit: 10,
  successful: true,
});
 
for (const d of deliveries.data) {
  console.log(`${d.id}: ${d.statusCode} at ${d.deliveredAt}`);
}

const delivery = await ap.geofences.webhooks.retrieve(
  "geofence_789012",
  "webhook_delivery_123456"
);
 
console.log(`Status: ${delivery.statusCode}`);
console.log(`Response: ${delivery.responseBody}`);

import { AirPinpoint } from "@airpinpoint/sdk";
 
const ap = new AirPinpoint();
 
// 1. Create a geofence around your job site
const fence = await ap.geofences.create({
  name: "Downtown Job Site",
  latitude: 40.7128,
  longitude: -74.0060,
  radius: 150,
  trackableId: ["trk_forklift42", "trk_excavator7"],
  notifyType: "both",
  notifyDestination: "https://yourapp.com/webhooks/geofence",
  webhookSecret: "whsec_abc123",
  webhookEnabled: true,
});
 
// 2. Test the webhook
await ap.geofences.testWebhook(fence.id, { eventType: "entry" });
 
// 3. Expand the radius after surveying
const updated = await ap.geofences.update(fence.id, {
  radius: 250,
});
 
// 4. Check delivery history
const deliveries = await ap.geofences.webhooks.list(fence.id, { limit: 5 });
console.log(`${deliveries.data.length} webhook deliveries`);
 
// 5. Clean up when the project ends
await ap.geofences.del(fence.id);

const link = await ap.shareLinks.create({
  trackableId: "trk_abc123",
  hours: 24, // valid for 1-168 hours
});
 
console.log(`Share this link: ${link.shareUrl}`);
// https://airpinpoint.com/share/8a7b6c5d-4e3f-2d1c-0b9a-8c7d6e5f4g3h

const account = await ap.account.retrieve();
console.log(`${account.name} (${account.email})`);
console.log(`Status: ${account.subscription_status}`);

// Get usage breakdown for a date range
const usage = await ap.usage.retrieve({
  startDate: "2024-01-01",
  endDate: "2024-01-31",
});
 
console.log(`API calls: ${usage.apiCalls}`);
console.log(`Tracked devices: ${usage.trackedDevices}`);
 
// Get total usage summary
const total = await ap.usage.total({
  startDate: "2024-01-01",
  endDate: "2024-01-31",
});
 
console.log(`Total requests: ${total.totalRequests}`);

const page1 = await ap.trackables.list({ limit: 10, skip: 0 });
const page2 = await ap.trackables.list({ limit: 10, skip: 10 });

for await (const trackable of ap.trackables.list()) {
  console.log(`${trackable.name}: ${trackable.enabled ? "active" : "disabled"}`);
}

import {
  AirPinpoint,
  AuthenticationError,
  NotFoundError,
  ValidationError,
  RateLimitError,
  InternalError,
  APIConnectionError,
} from "@airpinpoint/sdk";
 
const ap = new AirPinpoint();
 
try {
  const location = await ap.trackables.currentLocation("trk_invalid");
} catch (err) {
  if (err instanceof AuthenticationError) {
    console.error("Invalid API key. Check your AIRPINPOINT_API_KEY.");
  } else if (err instanceof NotFoundError) {
    console.error("Device not found. Verify the trackable ID.");
  } else if (err instanceof ValidationError) {
    console.error(`Bad request: ${err.message}`);
  } else if (err instanceof RateLimitError) {
    console.error(`Rate limited. Retry after ${err.retryAfter}s`);
  } else if (err instanceof InternalError) {
    console.error("Server error. Try again later.");
  } else if (err instanceof APIConnectionError) {
    console.error("Network error. Check your connection.");
  }
}

import { webhooks } from "@airpinpoint/sdk";
 
const event = await webhooks.constructEvent(
  rawBody,            // raw request body string
  signature,          // X-AirPinpoint-Signature header
  "whsec_your_secret" // your webhook secret
);
 
if (event.event === "geofence.entry") {
  console.log(`${event.beacon.name} entered ${event.geofence.name}`);
}
 
if (event.event === "geofence.exit") {
  console.log(`${event.beacon.name} left ${event.geofence.name}`);
}

// app/api/webhooks/geofence/route.ts
import { webhooks } from "@airpinpoint/sdk";
import { NextRequest, NextResponse } from "next/server";
 
export async function POST(req: NextRequest) {
  const rawBody = await req.text();
  const signature = req.headers.get("x-airpinpoint-signature");
 
  if (!signature) {
    return NextResponse.json({ error: "Missing signature" }, { status: 400 });
  }
 
  try {
    const event = await webhooks.constructEvent(
      rawBody,
      signature,
      process.env.AIRPINPOINT_WEBHOOK_SECRET!
    );
 
    if (event.event === "geofence.entry") {
      // Forklift #42 arrived at Warehouse Zone A
      await notifyDispatch(event.beacon.name, event.geofence.name);
    }
 
    return NextResponse.json({ received: true });
  } catch (err) {
    return NextResponse.json({ error: "Invalid signature" }, { status: 403 });
  }
}

import express from "express";
import { webhooks } from "@airpinpoint/sdk";
 
const app = express();
 
app.post(
  "/webhooks/geofence",
  express.raw({ type: "application/json" }),
  async (req, res) => {
    const signature = req.headers["x-airpinpoint-signature"] as string;
 
    try {
      const event = await webhooks.constructEvent(
        req.body.toString(),
        signature,
        process.env.AIRPINPOINT_WEBHOOK_SECRET!
      );
 
      switch (event.event) {
        case "geofence.entry":
          console.log(`${event.beacon.name} entered ${event.geofence.name}`);
          break;
        case "geofence.exit":
          console.log(`${event.beacon.name} left ${event.geofence.name}`);
          break;
      }
 
      res.sendStatus(200);
    } catch (err) {
      res.sendStatus(403);
    }
  }
);

import { geo } from "@airpinpoint/sdk";

import { geo } from "@airpinpoint/sdk";
 
const warehouse = { latitude: 37.7749, longitude: -122.4194 };
const vanLocation = { latitude: 37.7755, longitude: -122.4188 };
 
// Distance between two points
const meters = geo.distance(warehouse, vanLocation);
console.log(`Van is ${meters.toFixed(0)}m from warehouse`);
 
// Check if a device is inside a geofence
const fence = { latitude: 37.7749, longitude: -122.4194, radius: 200 };
const inside = geo.isInsideGeofence(vanLocation, fence);
console.log(`Van inside geofence: ${inside}`);
 
// Bearing from warehouse to van
const heading = geo.bearing(warehouse, vanLocation);
console.log(`Van is at bearing ${heading.toFixed(0)}°`);

import { analysis } from "@airpinpoint/sdk";

import { AirPinpoint, analysis } from "@airpinpoint/sdk";
 
const ap = new AirPinpoint();
 
const history = await ap.trackables.locationHistory("trk_forklift42", {
  startTime: "2024-01-15T06:00:00Z",
  endTime: "2024-01-15T18:00:00Z",
});
 
// Find where the forklift stopped for more than 10 minutes
const stops = analysis.detectStops(history, {
  minDurationSeconds: 600,
  maxRadiusMeters: 30,
});
 
for (const stop of stops) {
  console.log(
    `Stopped at ${stop.latitude}, ${stop.longitude} ` +
    `for ${(stop.durationSeconds / 60).toFixed(0)} min`
  );
}
 
// Detect trips between stops
const trips = analysis.detectTrips(history);
for (const trip of trips) {
  console.log(
    `Trip: ${trip.distanceMeters.toFixed(0)}m ` +
    `in ${(trip.durationSeconds / 60).toFixed(0)} min`
  );
}

import { format } from "@airpinpoint/sdk";

import { AirPinpoint, format } from "@airpinpoint/sdk";
import { writeFileSync } from "fs";
 
const ap = new AirPinpoint();
 
const history = await ap.trackables.locationHistory("trk_van3", {
  startTime: "2024-01-15T00:00:00Z",
  endTime: "2024-01-15T23:59:59Z",
});
 
// Export as GeoJSON for use in Mapbox, Leaflet, QGIS, etc.
const geojson = format.toGeoJSON(history);
writeFileSync("van3-route.geojson", JSON.stringify(geojson, null, 2));
 
// Convert to a route line
const route = format.toGeoJSONLineString(history);
console.log(`Route with ${route.geometry.coordinates.length} points`);
 
// Encode as polyline for Google Maps API
const polyline = format.encodePolyline(history);
console.log(`Encoded polyline: ${polyline.substring(0, 40)}...`);

import { filter } from "@airpinpoint/sdk";

import { AirPinpoint, filter } from "@airpinpoint/sdk";
 
const ap = new AirPinpoint();
 
const raw = await ap.trackables.locationHistory("trk_excavator7", {
  startTime: "2024-01-15T00:00:00Z",
  endTime: "2024-01-15T23:59:59Z",
});
 
// GPS cleanup pipeline
const cleaned = filter.deduplicate(
  filter.filterBySpeed(
    filter.filterByAccuracy(raw, 50),  // drop points with >50m accuracy
    30                                  // drop points implying >30 m/s (108 km/h)
  ),
  5                                     // drop points within 5m of each other
);
 
console.log(`Raw: ${raw.length} points, cleaned: ${cleaned.length} points`);

import { battery } from "@airpinpoint/sdk";

import { AirPinpoint, battery } from "@airpinpoint/sdk";
 
const ap = new AirPinpoint();
const { data: trackables } = await ap.trackables.list();
 
// Check battery health across all devices
for (const device of trackables) {
  const info = await ap.trackables.battery(device.id);
  const status = battery.batteryHealthStatus(info);
  const days = battery.estimateBatteryDaysRemaining(info);
 
  if (status === "low" || status === "critical") {
    console.log(`[!] ${device.name}: ${status}, ~${days} days remaining`);
  }
}

import type {
  Coordinates,
  LocationBase,
  TrackableDetail,
  BatteryInfo,
  GeofenceBase,
  GeofenceCreateParams,
  GeofenceUpdateParams,
  WebhookEvent,
  WebhookDeliveryBase,
  WebhookDeliveryDetail,
  PaginatedList,
  AccountInfo,
  UsageInfo,
  ShareLinkResponse,
  Message,
  Stop,
  Trip,
  LocationCluster,
  StopOptions,
  TripOptions,
  ClientConfig,
  AirPinpointError,
} from "@airpinpoint/sdk";