watch_ip_sdk 0.1.2

Official Dart/Flutter SDK for the Watch-IP visitor geolocation API (GET /v1/geo).

watch_ip_sdk

Official Dart/Flutter SDK for the Watch-IP visitor geolocation API.

Watch-IP looks up the geolocation of whoever is currently loading your page — it's designed to be called directly from the visitor's own browser with a publishable, origin-locked API key. There is no server-to-server or arbitrary-IP lookup mode; see the docs for why.

Calling it from a Flutter app running natively (iOS/Android/desktop) or from Dart on a server therefore means calling it somewhere that isn't a browser tab, so the request won't naturally carry the Origin header a browser fetch sends automatically — and origin-locking means the API will reject it with origin_not_allowed unless you pass origin: set to one of the key's allowed origins yourself. (A Flutter web build running in an actual browser already sends Origin correctly and doesn't need this.) That makes the origin: option best suited to testing and internal tooling that stands in for the browser, not a general server-to-server bypass.

Note on the package name: pub.dev requires lowercase_with_underscores package names, so this package is watch_ip_sdk, living at packages/sdk_flutter in the Digitload/watch-ip monorepo — a deliberate deviation from the other SDKs' sdk-<lang> directory convention, not an inconsistency. Unlike the Go and PHP SDKs, this one does not need a public mirror repo: pub.dev publishes from an uploaded archive (dart pub publish), the same as PyPI and npm, so the monorepo staying private doesn't block installation.

Install

flutter pub add watch_ip_sdk
# or, for a plain Dart project:
dart pub add watch_ip_sdk

Usage

See example/watch_ip_sdk_example.dart for a runnable example.

import 'package:watch_ip_sdk/watch_ip_sdk.dart';

final client = WatchIP('wip_pub_xxxxxxxx');
final geo = await client.getGeo();

print('${geo.country} ${geo.city} ${geo.timezone}');

Or, for a one-off call without holding onto a client instance:

final geo = await getGeo('wip_pub_xxxxxxxx');

Error handling

Every failure — a rejected request (invalid key, disallowed origin, rate limit) or a network error — throws a WatchIPError with a status and a stable code:

try {
  final geo = await client.getGeo();
} on WatchIPError catch (e) {
  print('${e.code} ${e.status} ${e.message}');
  // e.g. origin_not_allowed 403 This origin is not authorized for this API key.
}

Optional fields

final geo = await client.getGeo(include: ['hostname']);

Timeouts

final geo = await client.getGeo(timeout: const Duration(seconds: 5));

A request that doesn't complete within timeout throws a WatchIPError with code network_error — this package's equivalent of the JS SDK's AbortSignal or the Go SDK's context.WithTimeout.

Setting the Origin header (non-browser callers)

final client = WatchIP('wip_pub_xxxxxxxx', origin: 'https://example.com');

See the caveat above — this is for testing/tooling standing in for a browser, not a server-to-server bypass.

Options

• baseUrl — override the API origin (e.g. for testing against wrangler dev).
• origin — set the Origin header sent with every request.
• httpClient — inject a custom package:http Client (e.g. MockClient from package:http/testing.dart in tests, or a client with different proxy/certificate settings).

Requirements

Dart 3.0+ / any Flutter version on a current stable channel. Depends on package:http (maintained by the Dart team) — this is a deliberate deviation from the other SDKs' zero-runtime-dependency convention, since dart:io's HttpClient isn't available on Flutter web and a stdlib-only client couldn't support all of Flutter's build targets.

License

MIT