@ipgeotrace/vue 0.1.0

package/README.md

@@ -0,0 +1,75 @@
+# @ipgeotrace/vue
+
+Vue 3 bindings for [IPGeoTrace](https://ipgeotrace.com). Resolve the visitor's location **once** and
+share it across your app with a composable. Built on [`@ipgeotrace/browser`](../browser) — it uses a
+publishable key, so it's safe in the client.
+
+Sign up and grab your publishable key at [ipgeotrace.com](https://ipgeotrace.com).
+
+## Install
+
+```sh
+npm add @ipgeotrace/vue vue
+```
+
+## Usage
+
+Install the plugin once. It calls `me()` a single time and shares the result app-wide.
+
+```ts
+import { createApp } from 'vue';
+import { ipgeotrace } from '@ipgeotrace/vue';
+import App from './App.vue';
+
+createApp(App)
+  .use(ipgeotrace, { publishableKey: 'pk_live_...' })
+  .mount('#app');
+```
+
+Then read it in any component with `useVisitorGeo()`:
+
+```vue
+<script setup lang="ts">
+import { computed } from 'vue';
+import { useVisitorGeo } from '@ipgeotrace/vue';
+
+const { data, loading, error } = useVisitorGeo();
+const currency = computed(() => data.value?.country?.currency ?? 'USD');
+</script>
+
+<template>
+  <p v-if="loading">Locating…</p>
+  <p v-else-if="error">Couldn't detect your location.</p>
+  <p v-else>Prices in {{ currency }}</p>
+</template>
+```
+
+## What the composable gives you
+
+All reactive — `data`, `error`, and `loading` are `Ref`s:
+
+- `data` — the `GeoResponse`, or `undefined` until it resolves.
+- `error` — a `GeoError` if the lookup failed (`rate_limited`, `network_error`, …).
+- `loading` — `true` while the request is in flight.
+- `refresh()` — run `me()` again. Useful after you know the network changed (e.g. the user toggled a
+  VPN), since the result is never cached — every call reflects the visitor's location right now.
+
+## Options
+
+Pass browser-client options, defer the first call, or bring your own client:
+
+```ts
+// defer the initial lookup until you call refresh()
+app.use(ipgeotrace, { publishableKey: 'pk_live_...', immediate: false });
+
+// pass through browser-client options
+app.use(ipgeotrace, { publishableKey: 'pk_live_...', options: { timeoutMs: 3_000 } });
+
+// or share a pre-built client
+import { createBrowserClient } from '@ipgeotrace/browser';
+const client = createBrowserClient({ publishableKey: 'pk_live_...' });
+app.use(ipgeotrace, { client });
+```
+
+See the [`@ipgeotrace/browser` README](../browser) for the underlying `me()` client and publishable
+keys.

package/dist/index.cjs

@@ -0,0 +1,59 @@
+'use strict';
+
+var browser = require('@ipgeotrace/browser');
+var vue = require('vue');
+
+// src/plugin.ts
+
+// src/context.ts
+var VISITOR_GEO = /* @__PURE__ */ Symbol("ipgeotrace:visitor-geo");
+
+// src/plugin.ts
+var ipgeotrace = {
+  install(app, options) {
+    const opts = options ?? {};
+    const client = resolveClient(opts);
+    app.provide(VISITOR_GEO, createVisitorGeo(client, opts.immediate ?? true));
+  }
+};
+function createVisitorGeo(client, immediate) {
+  const data = vue.ref(void 0);
+  const error = vue.ref(void 0);
+  const loading = vue.ref(false);
+  async function refresh(signal) {
+    loading.value = true;
+    try {
+      const result = await client.me(signal);
+      if (result.ok) {
+        data.value = result.value;
+        error.value = void 0;
+      } else {
+        error.value = result.error;
+      }
+    } finally {
+      loading.value = false;
+    }
+  }
+  if (immediate) void refresh();
+  return { data, error, loading, refresh: () => refresh() };
+}
+function resolveClient(options) {
+  if (options.client) return options.client;
+  if (!options.publishableKey) {
+    throw new Error("IPGeoTrace: pass either a client or a publishableKey to app.use(ipgeotrace, \u2026).");
+  }
+  return browser.createBrowserClient({ publishableKey: options.publishableKey, ...options.options });
+}
+function useVisitorGeo() {
+  const state = vue.inject(VISITOR_GEO);
+  if (!state) {
+    throw new Error("IPGeoTrace: install the plugin with app.use(ipgeotrace, { publishableKey }) before calling useVisitorGeo().");
+  }
+  return state;
+}
+
+exports.VISITOR_GEO = VISITOR_GEO;
+exports.ipgeotrace = ipgeotrace;
+exports.useVisitorGeo = useVisitorGeo;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/context.ts","../src/plugin.ts","../src/use-visitor-geo.ts"],"names":["ref","createBrowserClient","inject"],"mappings":";;;;;;;;AAUO,IAAM,WAAA,0BAA+C,wBAAwB;;;ACO7E,IAAM,UAAA,GAAa;AAAA,EACxB,OAAA,CAAQ,KAAU,OAAA,EAAyC;AACzD,IAAA,MAAM,IAAA,GAAO,WAAW,EAAC;AACzB,IAAA,MAAM,MAAA,GAAS,cAAc,IAAI,CAAA;AACjC,IAAA,GAAA,CAAI,QAAQ,WAAA,EAAa,gBAAA,CAAiB,QAAQ,IAAA,CAAK,SAAA,IAAa,IAAI,CAAC,CAAA;AAAA,EAC3E;AACF;AAEA,SAAS,gBAAA,CAAiB,QAAuB,SAAA,EAAgC;AAC/E,EAAA,MAAM,IAAA,GAAOA,QAA6B,MAAS,CAAA;AACnD,EAAA,MAAM,KAAA,GAAQA,QAA0B,MAAS,CAAA;AACjD,EAAA,MAAM,OAAA,GAAUA,QAAa,KAAK,CAAA;AAElC,EAAA,eAAe,QAAQ,MAAA,EAAqC;AAC1D,IAAA,OAAA,CAAQ,KAAA,GAAQ,IAAA;AAChB,IAAA,IAAI;AACF,MAAA,MAAM,MAAA,GAAS,MAAM,MAAA,CAAO,EAAA,CAAG,MAAM,CAAA;AACrC,MAAA,IAAI,OAAO,EAAA,EAAI;AACb,QAAA,IAAA,CAAK,QAAQ,MAAA,CAAO,KAAA;AACpB,QAAA,KAAA,CAAM,KAAA,GAAQ,KAAA,CAAA;AAAA,MAChB,CAAA,MAAO;AACL,QAAA,KAAA,CAAM,QAAQ,MAAA,CAAO,KAAA;AAAA,MACvB;AAAA,IACF,CAAA,SAAE;AACA,MAAA,OAAA,CAAQ,KAAA,GAAQ,KAAA;AAAA,IAClB;AAAA,EACF;AAEA,EAAA,IAAI,SAAA,OAAgB,OAAA,EAAQ;AAE5B,EAAA,OAAO,EAAE,IAAA,EAAM,KAAA,EAAO,SAAS,OAAA,EAAS,MAAM,SAAQ,EAAE;AAC1D;AAEA,SAAS,cAAc,OAAA,EAAiD;AACtE,EAAA,IAAI,OAAA,CAAQ,MAAA,EAAQ,OAAO,OAAA,CAAQ,MAAA;AACnC,EAAA,IAAI,CAAC,QAAQ,cAAA,EAAgB;AAC3B,IAAA,MAAM,IAAI,MAAM,sFAAiF,CAAA;AAAA,EACnG;AACA,EAAA,OAAOC,2BAAA,CAAoB,EAAE,cAAA,EAAgB,OAAA,CAAQ,gBAAgB,GAAG,OAAA,CAAQ,SAAS,CAAA;AAC3F;ACrDO,SAAS,aAAA,GAA4B;AAC1C,EAAA,MAAM,KAAA,GAAQC,WAAO,WAAW,CAAA;AAChC,EAAA,IAAI,CAAC,KAAA,EAAO;AACV,IAAA,MAAM,IAAI,MAAM,6GAA6G,CAAA;AAAA,EAC/H;AACA,EAAA,OAAO,KAAA;AACT","file":"index.cjs","sourcesContent":["import type { GeoError, GeoResponse } from '@ipgeotrace/browser';\nimport type { InjectionKey, Ref } from 'vue';\n\nexport interface VisitorGeo {\n  data: Ref<GeoResponse | undefined>;\n  error: Ref<GeoError | undefined>;\n  loading: Ref<boolean>;\n  refresh: () => Promise<void>;\n}\n\nexport const VISITOR_GEO: InjectionKey<VisitorGeo> = Symbol('ipgeotrace:visitor-geo');\n","import {\n  createBrowserClient,\n  type BrowserClient,\n  type BrowserClientOptions,\n  type GeoError,\n  type GeoResponse,\n} from '@ipgeotrace/browser';\nimport { ref, type App } from 'vue';\nimport { VISITOR_GEO, type VisitorGeo } from './context.js';\n\nexport interface IpGeoTracePluginOptions {\n  publishableKey?: string;\n  options?: Omit<BrowserClientOptions, 'publishableKey'>;\n  client?: BrowserClient;\n  immediate?: boolean;\n}\n\nexport const ipgeotrace = {\n  install(app: App, options?: IpGeoTracePluginOptions): void {\n    const opts = options ?? {};\n    const client = resolveClient(opts);\n    app.provide(VISITOR_GEO, createVisitorGeo(client, opts.immediate ?? true));\n  },\n};\n\nfunction createVisitorGeo(client: BrowserClient, immediate: boolean): VisitorGeo {\n  const data = ref<GeoResponse | undefined>(undefined);\n  const error = ref<GeoError | undefined>(undefined);\n  const loading = ref<boolean>(false);\n\n  async function refresh(signal?: AbortSignal): Promise<void> {\n    loading.value = true;\n    try {\n      const result = await client.me(signal);\n      if (result.ok) {\n        data.value = result.value;\n        error.value = undefined;\n      } else {\n        error.value = result.error;\n      }\n    } finally {\n      loading.value = false;\n    }\n  }\n\n  if (immediate) void refresh();\n\n  return { data, error, loading, refresh: () => refresh() };\n}\n\nfunction resolveClient(options: IpGeoTracePluginOptions): BrowserClient {\n  if (options.client) return options.client;\n  if (!options.publishableKey) {\n    throw new Error('IPGeoTrace: pass either a client or a publishableKey to app.use(ipgeotrace, …).');\n  }\n  return createBrowserClient({ publishableKey: options.publishableKey, ...options.options });\n}\n","import { inject } from 'vue';\nimport { VISITOR_GEO, type VisitorGeo } from './context.js';\n\nexport function useVisitorGeo(): VisitorGeo {\n  const state = inject(VISITOR_GEO);\n  if (!state) {\n    throw new Error('IPGeoTrace: install the plugin with app.use(ipgeotrace, { publishableKey }) before calling useVisitorGeo().');\n  }\n  return state;\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,25 @@
+import { BrowserClientOptions, BrowserClient, GeoResponse, GeoError } from '@ipgeotrace/browser';
+export { GeoError, GeoResponse } from '@ipgeotrace/browser';
+import { App, InjectionKey, Ref } from 'vue';
+
+interface IpGeoTracePluginOptions {
+    publishableKey?: string;
+    options?: Omit<BrowserClientOptions, 'publishableKey'>;
+    client?: BrowserClient;
+    immediate?: boolean;
+}
+declare const ipgeotrace: {
+    install(app: App, options?: IpGeoTracePluginOptions): void;
+};
+
+interface VisitorGeo {
+    data: Ref<GeoResponse | undefined>;
+    error: Ref<GeoError | undefined>;
+    loading: Ref<boolean>;
+    refresh: () => Promise<void>;
+}
+declare const VISITOR_GEO: InjectionKey<VisitorGeo>;
+
+declare function useVisitorGeo(): VisitorGeo;
+
+export { type IpGeoTracePluginOptions, VISITOR_GEO, type VisitorGeo, ipgeotrace, useVisitorGeo };

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+import { BrowserClientOptions, BrowserClient, GeoResponse, GeoError } from '@ipgeotrace/browser';
+export { GeoError, GeoResponse } from '@ipgeotrace/browser';
+import { App, InjectionKey, Ref } from 'vue';
+
+interface IpGeoTracePluginOptions {
+    publishableKey?: string;
+    options?: Omit<BrowserClientOptions, 'publishableKey'>;
+    client?: BrowserClient;
+    immediate?: boolean;
+}
+declare const ipgeotrace: {
+    install(app: App, options?: IpGeoTracePluginOptions): void;
+};
+
+interface VisitorGeo {
+    data: Ref<GeoResponse | undefined>;
+    error: Ref<GeoError | undefined>;
+    loading: Ref<boolean>;
+    refresh: () => Promise<void>;
+}
+declare const VISITOR_GEO: InjectionKey<VisitorGeo>;
+
+declare function useVisitorGeo(): VisitorGeo;
+
+export { type IpGeoTracePluginOptions, VISITOR_GEO, type VisitorGeo, ipgeotrace, useVisitorGeo };

package/dist/index.js

@@ -0,0 +1,55 @@
+import { createBrowserClient } from '@ipgeotrace/browser';
+import { ref, inject } from 'vue';
+
+// src/plugin.ts
+
+// src/context.ts
+var VISITOR_GEO = /* @__PURE__ */ Symbol("ipgeotrace:visitor-geo");
+
+// src/plugin.ts
+var ipgeotrace = {
+  install(app, options) {
+    const opts = options ?? {};
+    const client = resolveClient(opts);
+    app.provide(VISITOR_GEO, createVisitorGeo(client, opts.immediate ?? true));
+  }
+};
+function createVisitorGeo(client, immediate) {
+  const data = ref(void 0);
+  const error = ref(void 0);
+  const loading = ref(false);
+  async function refresh(signal) {
+    loading.value = true;
+    try {
+      const result = await client.me(signal);
+      if (result.ok) {
+        data.value = result.value;
+        error.value = void 0;
+      } else {
+        error.value = result.error;
+      }
+    } finally {
+      loading.value = false;
+    }
+  }
+  if (immediate) void refresh();
+  return { data, error, loading, refresh: () => refresh() };
+}
+function resolveClient(options) {
+  if (options.client) return options.client;
+  if (!options.publishableKey) {
+    throw new Error("IPGeoTrace: pass either a client or a publishableKey to app.use(ipgeotrace, \u2026).");
+  }
+  return createBrowserClient({ publishableKey: options.publishableKey, ...options.options });
+}
+function useVisitorGeo() {
+  const state = inject(VISITOR_GEO);
+  if (!state) {
+    throw new Error("IPGeoTrace: install the plugin with app.use(ipgeotrace, { publishableKey }) before calling useVisitorGeo().");
+  }
+  return state;
+}
+
+export { VISITOR_GEO, ipgeotrace, useVisitorGeo };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/context.ts","../src/plugin.ts","../src/use-visitor-geo.ts"],"names":[],"mappings":";;;;;;AAUO,IAAM,WAAA,0BAA+C,wBAAwB;;;ACO7E,IAAM,UAAA,GAAa;AAAA,EACxB,OAAA,CAAQ,KAAU,OAAA,EAAyC;AACzD,IAAA,MAAM,IAAA,GAAO,WAAW,EAAC;AACzB,IAAA,MAAM,MAAA,GAAS,cAAc,IAAI,CAAA;AACjC,IAAA,GAAA,CAAI,QAAQ,WAAA,EAAa,gBAAA,CAAiB,QAAQ,IAAA,CAAK,SAAA,IAAa,IAAI,CAAC,CAAA;AAAA,EAC3E;AACF;AAEA,SAAS,gBAAA,CAAiB,QAAuB,SAAA,EAAgC;AAC/E,EAAA,MAAM,IAAA,GAAO,IAA6B,MAAS,CAAA;AACnD,EAAA,MAAM,KAAA,GAAQ,IAA0B,MAAS,CAAA;AACjD,EAAA,MAAM,OAAA,GAAU,IAAa,KAAK,CAAA;AAElC,EAAA,eAAe,QAAQ,MAAA,EAAqC;AAC1D,IAAA,OAAA,CAAQ,KAAA,GAAQ,IAAA;AAChB,IAAA,IAAI;AACF,MAAA,MAAM,MAAA,GAAS,MAAM,MAAA,CAAO,EAAA,CAAG,MAAM,CAAA;AACrC,MAAA,IAAI,OAAO,EAAA,EAAI;AACb,QAAA,IAAA,CAAK,QAAQ,MAAA,CAAO,KAAA;AACpB,QAAA,KAAA,CAAM,KAAA,GAAQ,KAAA,CAAA;AAAA,MAChB,CAAA,MAAO;AACL,QAAA,KAAA,CAAM,QAAQ,MAAA,CAAO,KAAA;AAAA,MACvB;AAAA,IACF,CAAA,SAAE;AACA,MAAA,OAAA,CAAQ,KAAA,GAAQ,KAAA;AAAA,IAClB;AAAA,EACF;AAEA,EAAA,IAAI,SAAA,OAAgB,OAAA,EAAQ;AAE5B,EAAA,OAAO,EAAE,IAAA,EAAM,KAAA,EAAO,SAAS,OAAA,EAAS,MAAM,SAAQ,EAAE;AAC1D;AAEA,SAAS,cAAc,OAAA,EAAiD;AACtE,EAAA,IAAI,OAAA,CAAQ,MAAA,EAAQ,OAAO,OAAA,CAAQ,MAAA;AACnC,EAAA,IAAI,CAAC,QAAQ,cAAA,EAAgB;AAC3B,IAAA,MAAM,IAAI,MAAM,sFAAiF,CAAA;AAAA,EACnG;AACA,EAAA,OAAO,mBAAA,CAAoB,EAAE,cAAA,EAAgB,OAAA,CAAQ,gBAAgB,GAAG,OAAA,CAAQ,SAAS,CAAA;AAC3F;ACrDO,SAAS,aAAA,GAA4B;AAC1C,EAAA,MAAM,KAAA,GAAQ,OAAO,WAAW,CAAA;AAChC,EAAA,IAAI,CAAC,KAAA,EAAO;AACV,IAAA,MAAM,IAAI,MAAM,6GAA6G,CAAA;AAAA,EAC/H;AACA,EAAA,OAAO,KAAA;AACT","file":"index.js","sourcesContent":["import type { GeoError, GeoResponse } from '@ipgeotrace/browser';\nimport type { InjectionKey, Ref } from 'vue';\n\nexport interface VisitorGeo {\n  data: Ref<GeoResponse | undefined>;\n  error: Ref<GeoError | undefined>;\n  loading: Ref<boolean>;\n  refresh: () => Promise<void>;\n}\n\nexport const VISITOR_GEO: InjectionKey<VisitorGeo> = Symbol('ipgeotrace:visitor-geo');\n","import {\n  createBrowserClient,\n  type BrowserClient,\n  type BrowserClientOptions,\n  type GeoError,\n  type GeoResponse,\n} from '@ipgeotrace/browser';\nimport { ref, type App } from 'vue';\nimport { VISITOR_GEO, type VisitorGeo } from './context.js';\n\nexport interface IpGeoTracePluginOptions {\n  publishableKey?: string;\n  options?: Omit<BrowserClientOptions, 'publishableKey'>;\n  client?: BrowserClient;\n  immediate?: boolean;\n}\n\nexport const ipgeotrace = {\n  install(app: App, options?: IpGeoTracePluginOptions): void {\n    const opts = options ?? {};\n    const client = resolveClient(opts);\n    app.provide(VISITOR_GEO, createVisitorGeo(client, opts.immediate ?? true));\n  },\n};\n\nfunction createVisitorGeo(client: BrowserClient, immediate: boolean): VisitorGeo {\n  const data = ref<GeoResponse | undefined>(undefined);\n  const error = ref<GeoError | undefined>(undefined);\n  const loading = ref<boolean>(false);\n\n  async function refresh(signal?: AbortSignal): Promise<void> {\n    loading.value = true;\n    try {\n      const result = await client.me(signal);\n      if (result.ok) {\n        data.value = result.value;\n        error.value = undefined;\n      } else {\n        error.value = result.error;\n      }\n    } finally {\n      loading.value = false;\n    }\n  }\n\n  if (immediate) void refresh();\n\n  return { data, error, loading, refresh: () => refresh() };\n}\n\nfunction resolveClient(options: IpGeoTracePluginOptions): BrowserClient {\n  if (options.client) return options.client;\n  if (!options.publishableKey) {\n    throw new Error('IPGeoTrace: pass either a client or a publishableKey to app.use(ipgeotrace, …).');\n  }\n  return createBrowserClient({ publishableKey: options.publishableKey, ...options.options });\n}\n","import { inject } from 'vue';\nimport { VISITOR_GEO, type VisitorGeo } from './context.js';\n\nexport function useVisitorGeo(): VisitorGeo {\n  const state = inject(VISITOR_GEO);\n  if (!state) {\n    throw new Error('IPGeoTrace: install the plugin with app.use(ipgeotrace, { publishableKey }) before calling useVisitorGeo().');\n  }\n  return state;\n}\n"]}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@ipgeotrace/vue",
+  "version": "0.1.0",
+  "description": "Vue 3 bindings for IPGeoTrace. Resolve the visitor's location once and share it across your app with useVisitorGeo().",
+  "keywords": [
+    "ipgeotrace",
+    "geolocation",
+    "geoip",
+    "vue",
+    "composable",
+    "typescript"
+  ],
+  "license": "MIT",
+  "homepage": "https://ipgeotrace.com",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18.17"
+  },
+  "dependencies": {
+    "@ipgeotrace/browser": "0.1.0"
+  },
+  "peerDependencies": {
+    "vue": "^3.3.0"
+  },
+  "devDependencies": {
+    "vue": "^3.5.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.6.3"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  }
+}