@fingerru/vue 1.0.0-next.0

package/README.md

@@ -0,0 +1,157 @@
+# @fingerru/vue
+
+Vue 3-обёртка над `@fingerru/agent`. Подключите плагин один раз при создании
+приложения и получайте данные visitor через Composition API или Options API.
+
+## Установка
+
+```bash
+pnpm add @fingerru/vue @fingerru/agent
+```
+
+## Подключение плагина
+
+Создайте Fingprint-плагин при инициализации приложения:
+
+```ts
+import { createApp } from 'vue'
+import { createFingprint } from '@fingerru/vue'
+import App from './App.vue'
+
+createApp(App)
+  .use(
+    createFingprint({
+      apiKey: 'pk_live_example',
+    }),
+  )
+  .mount('#app')
+```
+
+`endpoint` — полный абсолютный URL API или proxy. Если его не передавать,
+`@fingerru/agent` использует URL по умолчанию, встроенный в bundle.
+
+```ts
+createFingprint({
+  apiKey: 'pk_live_example',
+  endpoint: 'https://api.example.com/api/visit',
+  runtimeUrl: 'https://cdn.example.com/agent.min.js',
+  loadTimeout: 10_000,
+  cache: {
+    storage: 'sessionStorage',
+    duration: 3600,
+  },
+})
+```
+
+## Composition API
+
+`useVisitorData()` доступен в компонентах, которые находятся внутри приложения
+с подключённым `createFingprint()`. Он возвращает реактивные refs `data`,
+`error`, `isLoading` и `isFetched`, а также метод `getData()`.
+
+```vue
+<script setup lang="ts">
+import { useVisitorData } from '@fingerru/vue'
+import { watch } from 'vue'
+
+const { data, error, isFetched, isLoading, getData } = useVisitorData({
+  // Укажите true, если идентификация нужна сразу после mount.
+  immediate: false,
+})
+
+watch(data, (visitor) => {
+  if (visitor) {
+    console.log(visitor.user)
+  }
+})
+</script>
+
+<template>
+  <button type="button" :disabled="isLoading" @click="getData()">Получить visitor</button>
+
+  <p v-if="isLoading">Получаем visitor…</p>
+  <p v-else-if="error">{{ error.message }}</p>
+  <p v-else-if="isFetched">Visitor: {{ data?.user }}</p>
+</template>
+```
+
+В `<template>` Vue автоматически разворачивает refs. В обычном TypeScript-коде
+используйте `.value`, например `data.value?.user`.
+
+По умолчанию запрос не запускается автоматически. Передайте
+`{ immediate: true }`, чтобы выполнить его после монтирования компонента.
+Повторные вызовы `getData()` одного composable во время активного запроса
+получают один и тот же `Promise`.
+
+### Параметры запроса
+
+Параметры можно указать при создании composable или передать в конкретный
+вызов. Параметры вызова имеют приоритет:
+
+```ts
+const { getData } = useVisitorData({ timeout: 5_000 })
+
+// Запрашивает новые данные, игнорируя cache.
+const visitor = await getData({ ignoreCache: true })
+```
+
+| Параметр      | Описание                                                |
+| ------------- | ------------------------------------------------------- |
+| `immediate`   | Выполнить запрос после mount. По умолчанию — `false`.   |
+| `timeout`     | Максимальное время API-запроса в миллисекундах.         |
+| `ignoreCache` | Не использовать сохранённый результат для этого вызова. |
+
+## Options API
+
+После подключения плагин добавляет типизированный `$fingprint` во все
+компоненты. Через него доступен `getVisitorData()`:
+
+```vue
+<script lang="ts">
+import { defineComponent } from 'vue'
+
+export default defineComponent({
+  methods: {
+    async getVisitorData(): Promise<void> {
+      const visitor = await this.$fingprint.getVisitorData()
+      console.log(visitor.user)
+    },
+  },
+})
+</script>
+
+<template>
+  <button type="button" @click="getVisitorData">Получить visitor</button>
+</template>
+```
+
+## Nuxt
+
+Fingerprinting использует browser runtime, поэтому подключайте плагин только
+на клиенте. Создайте `plugins/fingprint.client.ts`:
+
+```ts
+import { createFingprint } from '@fingerru/vue'
+
+export default defineNuxtPlugin((nuxtApp) => {
+  const config = useRuntimeConfig()
+
+  nuxtApp.vueApp.use(
+    createFingprint({
+      apiKey: config.public.fingprintApiKey,
+    }),
+  )
+})
+```
+
+Публичный ключ передавайте через публичную runtime-конфигурацию:
+
+```ts
+export default defineNuxtConfig({
+  runtimeConfig: {
+    public: {
+      fingprintApiKey: process.env.FINGPRINT_API_KEY,
+    },
+  },
+})
+```

package/dist/index.js

@@ -0,0 +1,69 @@
+import { start as h } from "@fingerru/agent";
+import { inject as m, shallowRef as F, computed as a, onMounted as L } from "vue";
+const l = Symbol("fingprint"), y = (n) => {
+  const s = h(n), o = {
+    getVisitorData: (t) => s.get(t)
+  };
+  return {
+    install: (t) => {
+      t.provide(l, o), t.config.globalProperties.$fingprint = o;
+    }
+  };
+}, D = {
+  data: void 0,
+  error: void 0,
+  isFetched: !1,
+  isLoading: !1
+}, V = {
+  data: void 0,
+  error: void 0,
+  isFetched: !1,
+  isLoading: !0
+}, x = ({
+  immediate: n,
+  timeout: s,
+  ignoreCache: o
+} = {}) => {
+  const t = m(l);
+  if (!t)
+    throw new Error("useVisitorData must be used after app.use(createFingprint(...)).");
+  let i = null;
+  const e = F(D), u = a(() => e.value.data), g = a(() => e.value.error), f = a(() => e.value.isLoading), v = a(() => e.value.isFetched), d = (p) => {
+    if (i)
+      return i;
+    e.value = V;
+    const r = t.getVisitorData({ timeout: s, ignoreCache: o, ...p });
+    return i = r, r.then((c) => {
+      e.value = {
+        data: c,
+        error: void 0,
+        isFetched: !0,
+        isLoading: !1
+      };
+    }).catch((c) => {
+      e.value = {
+        data: void 0,
+        error: c,
+        isFetched: !1,
+        isLoading: !1
+      };
+    }).finally(() => {
+      i === r && (i = null);
+    }), r;
+  };
+  return L(() => {
+    n && d().catch(() => {
+    });
+  }), {
+    data: u,
+    error: g,
+    isLoading: f,
+    isFetched: v,
+    getData: d
+  };
+};
+export {
+  y as createFingprint,
+  x as useVisitorData
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../src/config.ts","../src/plugin.ts","../src/use-visitor-data.ts"],"sourcesContent":["import type { GetOptions, VisitorResult } from '@fingerru/agent'\nimport { type InjectionKey } from 'vue'\n\nexport interface FingprintContextValue {\n  getVisitorData: (config?: GetOptions) => Promise<VisitorResult>\n}\n\nexport const pluginKey: InjectionKey<FingprintContextValue> = Symbol('fingprint')\n","import { start, type GetOptions, type StartOptions } from '@fingerru/agent'\nimport type { App } from 'vue'\nimport { pluginKey, type FingprintContextValue } from './config'\n\nexport type CreateFingprintOptions = StartOptions\n\ndeclare module 'vue' {\n  interface ComponentCustomProperties {\n    $fingprint: FingprintContextValue\n  }\n}\n\nexport const createFingprint = (options: CreateFingprintOptions) => {\n  const agent = start(options)\n\n  const client = {\n    getVisitorData: (getOptions?: GetOptions) => agent.get(getOptions),\n  }\n\n  return {\n    install: (app: App) => {\n      app.provide(pluginKey, client)\n      app.config.globalProperties.$fingprint = client\n    },\n  }\n}\n","import { computed, inject, onMounted, shallowRef, type ComputedRef } from 'vue'\nimport { pluginKey } from './config'\nimport type { GetOptions, VisitorResult } from '@fingerru/agent'\nimport type { QueryIdle, QueryLoading, QueryResult } from './types'\n\ninterface UseVisitorDataConfig {\n  /**\n   * Если `true`, автоматически запрашивает данные посетителя после монтирования\n   * компонента. По умолчанию запрос выполняется только при явном вызове `getData()`.\n   */\n  immediate?: boolean\n}\n\nexport type QueryResultRefs<TData, TError = Error> = {\n  [K in keyof QueryResult<TData, TError>]: ComputedRef<QueryResult<TData, TError>[K]>\n}\n\nexport type UseVisitorDataOptions = GetOptions & UseVisitorDataConfig\n\nexport type UseVisitorDataReturn = QueryResultRefs<VisitorResult> & {\n  /**\n   * Выполняет запрос на идентификацию к серверу и возвращает данные посетителя.\n   */\n  getData: (options?: GetOptions) => Promise<VisitorResult>\n}\n\nconst idle: QueryIdle = {\n  data: undefined,\n  error: undefined,\n  isFetched: false,\n  isLoading: false,\n}\n\nconst loading: QueryLoading = {\n  data: undefined,\n  error: undefined,\n  isFetched: false,\n  isLoading: true,\n}\n\nexport const useVisitorData = ({\n  immediate,\n  timeout,\n  ignoreCache,\n}: UseVisitorDataOptions = {}): UseVisitorDataReturn => {\n  const context = inject(pluginKey)\n\n  if (!context) {\n    throw new Error('useVisitorData must be used after app.use(createFingprint(...)).')\n  }\n\n  let pendingPromise: Promise<VisitorResult> | null = null\n  const result = shallowRef<QueryResult<VisitorResult>>(idle)\n  const data = computed(() => result.value.data)\n  const error = computed(() => result.value.error)\n  const isLoading = computed(() => result.value.isLoading)\n  const isFetched = computed(() => result.value.isFetched)\n\n  const getData = (overrideOptions?: GetOptions): Promise<VisitorResult> => {\n    if (pendingPromise) {\n      return pendingPromise\n    }\n\n    result.value = loading\n\n    const request = context.getVisitorData({ timeout, ignoreCache, ...overrideOptions })\n\n    pendingPromise = request\n\n    request\n      .then((visitor) => {\n        result.value = {\n          data: visitor,\n          error: undefined,\n          isFetched: true,\n          isLoading: false,\n        }\n      })\n      .catch((error) => {\n        result.value = {\n          data: undefined,\n          error: error,\n          isFetched: false,\n          isLoading: false,\n        }\n      })\n      .finally(() => {\n        if (pendingPromise === request) {\n          pendingPromise = null\n        }\n      })\n\n    return request\n  }\n\n  onMounted(() => {\n    if (immediate) {\n      getData().catch(() => undefined)\n    }\n  })\n\n  return {\n    data,\n    error,\n    isLoading,\n    isFetched,\n    getData,\n  }\n}\n"],"names":["pluginKey","createFingprint","options","agent","start","client","getOptions","app","idle","loading","useVisitorData","immediate","timeout","ignoreCache","context","inject","pendingPromise","result","shallowRef","data","computed","error","isLoading","isFetched","getData","overrideOptions","request","visitor","onMounted"],"mappings":";;AAOO,MAAMA,IAAiD,OAAO,WAAW,GCKnEC,IAAkB,CAACC,MAAoC;AAClE,QAAMC,IAAQC,EAAMF,CAAO,GAErBG,IAAS;AAAA,IACb,gBAAgB,CAACC,MAA4BH,EAAM,IAAIG,CAAU;AAAA,EAAA;AAGnE,SAAO;AAAA,IACL,SAAS,CAACC,MAAa;AACrB,MAAAA,EAAI,QAAQP,GAAWK,CAAM,GAC7BE,EAAI,OAAO,iBAAiB,aAAaF;AAAA,IAC3C;AAAA,EAAA;AAEJ,GCCMG,IAAkB;AAAA,EACtB,MAAM;AAAA,EACN,OAAO;AAAA,EACP,WAAW;AAAA,EACX,WAAW;AACb,GAEMC,IAAwB;AAAA,EAC5B,MAAM;AAAA,EACN,OAAO;AAAA,EACP,WAAW;AAAA,EACX,WAAW;AACb,GAEaC,IAAiB,CAAC;AAAA,EAC7B,WAAAC;AAAA,EACA,SAAAC;AAAA,EACA,aAAAC;AACF,IAA2B,OAA6B;AACtD,QAAMC,IAAUC,EAAOf,CAAS;AAEhC,MAAI,CAACc;AACH,UAAM,IAAI,MAAM,kEAAkE;AAGpF,MAAIE,IAAgD;AACpD,QAAMC,IAASC,EAAuCV,CAAI,GACpDW,IAAOC,EAAS,MAAMH,EAAO,MAAM,IAAI,GACvCI,IAAQD,EAAS,MAAMH,EAAO,MAAM,KAAK,GACzCK,IAAYF,EAAS,MAAMH,EAAO,MAAM,SAAS,GACjDM,IAAYH,EAAS,MAAMH,EAAO,MAAM,SAAS,GAEjDO,IAAU,CAACC,MAAyD;AACxE,QAAIT;AACF,aAAOA;AAGT,IAAAC,EAAO,QAAQR;AAEf,UAAMiB,IAAUZ,EAAQ,eAAe,EAAE,SAAAF,GAAS,aAAAC,GAAa,GAAGY,GAAiB;AAEnF,WAAAT,IAAiBU,GAEjBA,EACG,KAAK,CAACC,MAAY;AACjB,MAAAV,EAAO,QAAQ;AAAA,QACb,MAAMU;AAAA,QACN,OAAO;AAAA,QACP,WAAW;AAAA,QACX,WAAW;AAAA,MAAA;AAAA,IAEf,CAAC,EACA,MAAM,CAACN,MAAU;AAChB,MAAAJ,EAAO,QAAQ;AAAA,QACb,MAAM;AAAA,QACN,OAAOI;AAAAA,QACP,WAAW;AAAA,QACX,WAAW;AAAA,MAAA;AAAA,IAEf,CAAC,EACA,QAAQ,MAAM;AACb,MAAIL,MAAmBU,MACrBV,IAAiB;AAAA,IAErB,CAAC,GAEIU;AAAA,EACT;AAEA,SAAAE,EAAU,MAAM;AACd,IAAIjB,KACFa,EAAA,EAAU,MAAM,MAAA;AAAA,KAAe;AAAA,EAEnC,CAAC,GAEM;AAAA,IACL,MAAAL;AAAA,IACA,OAAAE;AAAA,IACA,WAAAC;AAAA,IACA,WAAAC;AAAA,IACA,SAAAC;AAAA,EAAA;AAEJ;"}

package/dist/types/config.d.ts

@@ -0,0 +1,6 @@
+import { GetOptions, VisitorResult } from '@fingerru/agent';
+import { InjectionKey } from 'vue';
+export interface FingprintContextValue {
+    getVisitorData: (config?: GetOptions) => Promise<VisitorResult>;
+}
+export declare const pluginKey: InjectionKey<FingprintContextValue>;

package/dist/types/index.d.ts

@@ -0,0 +1,2 @@
+export { createFingprint, type CreateFingprintOptions } from './plugin';
+export { useVisitorData, type UseVisitorDataReturn, type UseVisitorDataOptions, } from './use-visitor-data';

package/dist/types/plugin.d.ts

@@ -0,0 +1,12 @@
+import { StartOptions } from '@fingerru/agent';
+import { App } from 'vue';
+import { FingprintContextValue } from './config';
+export type CreateFingprintOptions = StartOptions;
+declare module 'vue' {
+    interface ComponentCustomProperties {
+        $fingprint: FingprintContextValue;
+    }
+}
+export declare const createFingprint: (options: CreateFingprintOptions) => {
+    install: (app: App) => void;
+};

package/dist/types/types.d.ts

@@ -0,0 +1,25 @@
+export type QueryError<TError = Error> = {
+    data: undefined;
+    isLoading: false;
+    isFetched: false;
+    error: TError;
+};
+export type QueryFetched<TData> = {
+    data: TData;
+    isLoading: false;
+    isFetched: true;
+    error: undefined;
+};
+export type QueryIdle = {
+    data: undefined;
+    isLoading: false;
+    isFetched: false;
+    error: undefined;
+};
+export type QueryLoading = {
+    data: undefined;
+    isLoading: true;
+    isFetched: false;
+    error: undefined;
+};
+export type QueryResult<TData, TError = Error> = QueryIdle | QueryLoading | QueryFetched<TData> | QueryError<TError>;

package/dist/types/use-visitor-data.d.ts

@@ -0,0 +1,22 @@
+import { ComputedRef } from 'vue';
+import { GetOptions, VisitorResult } from '@fingerru/agent';
+import { QueryResult } from './types';
+interface UseVisitorDataConfig {
+    /**
+     * Если `true`, автоматически запрашивает данные посетителя после монтирования
+     * компонента. По умолчанию запрос выполняется только при явном вызове `getData()`.
+     */
+    immediate?: boolean;
+}
+export type QueryResultRefs<TData, TError = Error> = {
+    [K in keyof QueryResult<TData, TError>]: ComputedRef<QueryResult<TData, TError>[K]>;
+};
+export type UseVisitorDataOptions = GetOptions & UseVisitorDataConfig;
+export type UseVisitorDataReturn = QueryResultRefs<VisitorResult> & {
+    /**
+     * Выполняет запрос на идентификацию к серверу и возвращает данные посетителя.
+     */
+    getData: (options?: GetOptions) => Promise<VisitorResult>;
+};
+export declare const useVisitorData: ({ immediate, timeout, ignoreCache, }?: UseVisitorDataOptions) => UseVisitorDataReturn;
+export {};

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@fingerru/vue",
+  "version": "1.0.0-next.0",
+  "description": "Vue SDK for the Fingprint service.",
+  "type": "module",
+  "module": "./dist/index.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@fingerru/agent": "1.0.0-next.0"
+  },
+  "devDependencies": {
+    "vue": "^3.0.0",
+    "@fingerru/protocol": "0.1.0",
+    "@fingerru/tsconfig": "0.1.0"
+  },
+  "peerDependencies": {
+    "vue": "^3.0.0"
+  },
+  "repository": "https://github.com/ifksco/fingerprint_agent",
+  "license": "MIT",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "vite build",
+    "check:typecheck": "tsc --noEmit -p tsconfig.typecheck.json"
+  }
+}