feat: added utility class

Author: czernika

README.md

@@ -112,6 +112,15 @@ Component appends captcha script into head section of application. If you alread
 </template>
 ```
 
+> Package checks if `window.smartCaptcha` object was defined. However when using multiple captcha instances at once all of them will have `window.smartCaptcha === undefined` on initial load. Therefore it is better either load script on your own and disable widget loading for every captcha or disable it for every captcha but first, e.g.
+
+```vue
+<template>
+    <SmartCaptcha />
+    <SmartCaptcha :load-widget="false" />
+</template>
+```
+
 ### Rendering timeout
 
 On a mount component will try to resolve global `window.smartCaptcha` object. If it was not defined component will "die". You may set `timeout` property in milliseconds to specify amount of time package will try to resolve this object
@@ -250,6 +259,18 @@ const captcha = useSmartCaptcha(container, {
 }, false)
 ```
 
+> Package checks if `window.smartCaptcha` object was defined. However when using multiple captcha instances at once all of them will have `window.smartCaptcha === undefined` on initial load.. Therefore it is better either load script on your own and disable widget loading for every captcha or disable it for every captcha but first, e.g.
+
+```js
+const firstCaptcha = useSmartCaptcha(container, {
+    // render props
+})
+
+const secondCaptcha = useSmartCaptcha(container, {
+    // render props
+}, false) // disable script appending as it will be appended by first captcha
+```
+
 ### Rendering timeout
 
 When being called composable will try to resolve global `window.smartCaptcha` object. If it was not defined component will "die". You may set `timeout` as fourth argument in milliseconds to specify amount of time package will try to resolve this object
@@ -408,6 +429,19 @@ const onCaptchaFired = async (tkn: Token) => {
 </script>
 ```
 
+## Utilities
+
+Package provides utility class with every method but `render` in order if you need call captcha methods "manually" outside of current captcha (since both composable and captcha do not allows you to specify "custom" widget id)
+
+```js
+import { SmartCaptchaUtils } from 'vue3-smart-captcha'
+
+const widgetId = 0 // example
+const utils = new SmartCaptchaUtils()
+
+utils.execute(widgetId)
+```
+
 ## License
 
 Open-source under [MIT license](LICENSE)

package.json

@@ -9,7 +9,7 @@
     "vue3"
   ],
   "license": "MIT",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",

src/composables/useSmartCaptcha.ts

@@ -1,32 +1,31 @@
 import { onMounted, onUnmounted, ref, type Ref } from 'vue'
 import type {
-    BaseEventCallback,
-    JavascriptErrorEventCallback,
+    CaptchaSubscriptionEventCallback,
     SmartCaptchaRenderProps,
     SubscribeEvent,
-    SuccessEventCallback,
     Token,
     WidgetId,
 } from '@/types/smartcaptcha'
+import SmartCaptchaUtils from '@/utils/smartcaptcha'
 
 type RenderProps = Partial<SmartCaptchaRenderProps> | string
 type CaptchaContainer = Ref | HTMLElement | string
-type CaptchaSubscriptionEventCallback = BaseEventCallback | SuccessEventCallback | JavascriptErrorEventCallback
 
 export const useSmartCaptcha = (container: CaptchaContainer, renderProps?: RenderProps, load = true, timeout = 2000) => {
+    const utils = new SmartCaptchaUtils()
+
     const widgetId = ref<WidgetId>()
     const token = ref<Token>()
 
     const __container = ref()
-    const __scriptWasAppended = ref(false)
 
     const __subscriptions: Record<SubscribeEvent, CaptchaSubscriptionEventCallback[]> = {
-        success: [] as SuccessEventCallback[],
-        'javascript-error': [] as JavascriptErrorEventCallback[],
-        'network-error': [] as BaseEventCallback[],
-        'token-expired': [] as BaseEventCallback[],
-        'challenge-hidden': [] as BaseEventCallback[],
-        'challenge-visible': [] as BaseEventCallback[],
+        success: [],
+        'javascript-error': [],
+        'network-error': [],
+        'token-expired': [],
+        'challenge-hidden': [],
+        'challenge-visible': [],
     }
 
     const __setContainer = () => {
@@ -41,14 +40,12 @@ export const useSmartCaptcha = (container: CaptchaContainer, renderProps?: Rende
 
     const __addScript = () => {
         const scriptElement = document.createElement('script')
-        scriptElement.src = 'https://smartcaptcha.yandexcloud.net/captcha.js?render=onload'
+        scriptElement.src = utils.SCRIPT_RENDER_ONLOAD_SRC
         scriptElement.defer = true
         scriptElement.type = 'text/javascript'
         scriptElement.crossOrigin = 'anonymous'
         scriptElement.dataset.captcha = 'true'
         document.head.appendChild(scriptElement)
-
-        __scriptWasAppended.value = true
     }
 
     const __renderProps = (): SmartCaptchaRenderProps => {
@@ -64,7 +61,7 @@ export const useSmartCaptcha = (container: CaptchaContainer, renderProps?: Rende
 
         return {
             ...renderProps,
-            sitekey, // the only required parameter
+            sitekey,
         }
     }
 
@@ -75,9 +72,7 @@ export const useSmartCaptcha = (container: CaptchaContainer, renderProps?: Rende
     const __subscribeToCaptchaEvent = (event: SubscribeEvent) => {
         if (__subscriptions[event].length > 0) {
             __subscriptions[event].forEach(cb => {
-                // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-                // @ts-ignore Yelling because of callback type
-                window.smartCaptcha?.subscribe(widgetId.value as WidgetId, event, cb)
+                utils.subscribe(widgetId.value as WidgetId, event, cb)
             })
         }
     }
@@ -88,7 +83,7 @@ export const useSmartCaptcha = (container: CaptchaContainer, renderProps?: Rende
         }
 
         // Required to set token value
-        window.smartCaptcha?.subscribe(widgetId.value, 'success', __onSuccess)
+        utils.subscribe(widgetId.value, 'success', __onSuccess)
 
         Array.from(Object.keys(__subscriptions) as SubscribeEvent[]).forEach(event => {
             __subscribeToCaptchaEvent(event)
@@ -112,7 +107,8 @@ export const useSmartCaptcha = (container: CaptchaContainer, renderProps?: Rende
     onMounted(() => {
         __setContainer()
 
-        if (! __scriptWasAppended.value && load) {
+        // Try not to load multiple instances per time
+        if (window.smartCaptcha === undefined && load) {
             __addScript()
         }
 
@@ -145,24 +141,27 @@ export const useSmartCaptcha = (container: CaptchaContainer, renderProps?: Rende
     })
 
     const execute = () => {
-        window.smartCaptcha?.execute(widgetId.value)
+        utils.execute(widgetId.value)
     }
 
-    const reset = () => {
-        window.smartCaptcha?.reset(widgetId.value)
-
+    const __reset = () => {
         widgetId.value = undefined
         token.value = undefined
     }
 
+    const reset = () => {
+        utils.reset(widgetId.value)
+
+        __reset()
+    }
+
     const destroy = () => {
-        window.smartCaptcha?.destroy(widgetId.value)
+        utils.destroy(widgetId.value)
 
-        widgetId.value = undefined
-        token.value = undefined
+        __reset()
     }
 
-    const getResponse = (): Token | undefined => window.smartCaptcha?.getResponse(widgetId.value)
+    const getResponse = (): Token | undefined => utils.getResponse(widgetId.value)
 
     const subscribeTo = <T extends CaptchaSubscriptionEventCallback>(event: SubscribeEvent, cb: T) => {
         __subscriptions[event].push(cb)

src/plugin.ts

@@ -1,5 +1,6 @@
 import SmartCaptcha from '@/components/SmartCaptcha.vue'
 import { useSmartCaptcha } from '@/composables/useSmartCaptcha'
+import SmartCaptchaUtils from '@/utils/smartcaptcha'
 import type { Plugin } from 'vue'
 import type {
     SmartCaptcha as WindowSmartCaptcha,
@@ -19,6 +20,7 @@ export {
     SmartCaptcha, // to keep backward compatibility
     SmartCaptchaPlugin,
     useSmartCaptcha,
+    SmartCaptchaUtils,
     type WindowSmartCaptcha,
     type WidgetId,
     type Token,

src/types/smartcaptcha.d.ts

@@ -49,6 +49,7 @@ export type BaseEventCallback = () => void
 export type SuccessEventCallback = (token: Token) => void
 export type JavascriptError = { filename: string, message: string, col: number, line: number }
 export type JavascriptErrorEventCallback = (error: JavascriptError) => void
+export type CaptchaSubscriptionEventCallback = BaseEventCallback | SuccessEventCallback | JavascriptErrorEventCallback
 
 /**
  * @link https://cloud.yandex.ru/docs/smartcaptcha/concepts/widget-methods#methods

src/utils/smartcaptcha.ts

@@ -0,0 +1,30 @@
+import type { SubscribeEvent, Token, WidgetId, CaptchaSubscriptionEventCallback } from '@/types/smartcaptcha'
+
+class SmartCaptchaUtils
+{
+    readonly SCRIPT_RENDER_ONLOAD_SRC = 'https://smartcaptcha.yandexcloud.net/captcha.js?render=onload'
+
+    execute (widgetID?: WidgetId) {
+        window.smartCaptcha?.execute(widgetID)
+    }
+
+    reset (widgetID?: WidgetId) {
+        window.smartCaptcha?.reset(widgetID)
+    }
+
+    destroy (widgetID?: WidgetId) {
+        window.smartCaptcha?.destroy(widgetID)
+    }
+
+    getResponse(widgetID?: WidgetId): Token | undefined {
+        return window.smartCaptcha?.getResponse(widgetID)
+    }
+
+    subscribe(widgetId: WidgetId, event: SubscribeEvent, cb: CaptchaSubscriptionEventCallback) {
+        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+        // @ts-ignore Yelling because of callback type
+        window.smartCaptcha?.subscribe(widgetId, event, cb)
+    }
+}
+
+export default SmartCaptchaUtils