@moveris/cognito-check

v0.3.0

Published

5 days ago

Embeddable CognitoCheck verification widget — framework-agnostic Web Component

0High
0Medium
0Low

japalacio0108

mstjern

moveris cognito-check liveness captcha web-component verification

`@moveris/cognito-check`

Embeddable human verification widget — framework-agnostic Web Component.

Drop <cognito-check> anywhere in your app. Works with Angular, Vue, Svelte, Astro, WordPress, plain HTML, or any stack that can render HTML elements.

React user? Use @moveris/cognito-check-react for idiomatic props/callbacks instead of DOM events.

How it works

User clicks the widget checkbox (disabled once verified — cannot be clicked again)
Camera modal opens — oval guide + liveness capture runs
Frames are sent to Moveris for analysis
Widget fires cognitoSuccess or cognitoError
Your app decides what to do next (enable a submit button, redirect, etc.)

Installation

npm install @moveris/cognito-check react react-dom
# or
pnpm add @moveris/cognito-check react react-dom

react and react-dom are required peer dependencies — the widget uses React internally for its UI, but this is transparent to your app.

Quick start — plain HTML

<!DOCTYPE html>
<html>
  <body>
    <form id="signup-form">
      <input type="email" placeholder="Email" />

      <cognito-check id="verify" api-key="your-api-key"></cognito-check>

      <button type="submit" id="submit-btn" disabled>Create account</button>
    </form>

    <script type="module">
      import '@moveris/cognito-check';

      const widget = document.getElementById('verify');
      const submitBtn = document.getElementById('submit-btn');

      widget.addEventListener('cognitoSuccess', (e) => {
        // e.detail: { outcome: 'pass', sessionId: string }
        // Always verify sessionId on your server before granting access
        submitBtn.disabled = false;
      });

      widget.addEventListener('cognitoError', (e) => {
        // e.detail: { outcome: 'fail' | 'cancelled', reason: string }
        console.warn('Verification failed:', e.detail.reason);
      });
    </script>
  </body>
</html>

Attributes

| Attribute | Required | Description | | ------------------- | -------- | -------------------------------------------------------------------------------------------------------------- | | api-key | Yes | Your Moveris API key. Sent as X-API-Key on verification requests. | | style | No | Standard HTML inline style. Controls the widget container's appearance and layout. | | consumer-url | No | The consumer app's URL — used for transaction tracing per app (e.g. https://app.example.com). | | consumer-env | No | Consumer app environment: development, staging, or production. Defaults to production when omitted. | | track-client-time | No | Boolean attribute (presence = true). When set, fires a fire-and-forget PATCH with client_time after verdict. |

<!-- Example: consumer context + client time tracking -->
<cognito-check
  api-key="your-api-key"
  consumer-url="https://app.example.com"
  consumer-env="production"
  track-client-time
></cognito-check>

Events

`cognitoSuccess`

Fired when the user passes verification.

widget.addEventListener('cognitoSuccess', (e: CustomEvent) => {
  const { outcome, sessionId } = e.detail;
  // outcome: 'pass'
  // sessionId: string — verify this on your server
});

`cognitoError`

Fired when verification fails, the user cancels, or the request times out.

widget.addEventListener('cognitoError', (e: CustomEvent) => {
  const { outcome, reason } = e.detail;
  // outcome: 'fail'      — liveness check completed but verdict was fake
  // outcome: 'cancelled' — user closed the modal, or request timed out (30s)
  // reason: string       — human-readable description
});

Framework examples

Angular

// app.module.ts — allow custom elements
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import '@moveris/cognito-check';

@NgModule({
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

<!-- signup.component.html -->
<cognito-check
  api-key="your-api-key"
  (cognitoSuccess)="onVerified($event)"
  (cognitoError)="onFailed($event)"
></cognito-check>

// signup.component.ts
onVerified(e: CustomEvent) {
  const { sessionId } = e.detail;
  this.verified = true;
}

onFailed(e: CustomEvent) {
  console.warn(e.detail.reason);
}

Vue 3

// main.ts — tell Vue to ignore the custom element
import { createApp } from 'vue';
import '@moveris/cognito-check';
import App from './App.vue';

const app = createApp(App);
app.config.compilerOptions.isCustomElement = (tag) => tag === 'cognito-check';
app.mount('#app');

<!-- SignupForm.vue -->
<template>
  <cognito-check api-key="your-api-key" @cognitoSuccess="onVerified" @cognitoError="onFailed" />
</template>

<script setup lang="ts">
import { ref } from 'vue';
import '@moveris/cognito-check';

const verified = ref(false);

function onVerified() {
  verified.value = true;
}

function onFailed(e: CustomEvent) {
  console.warn(e.detail.reason);
}
</script>

Svelte

<script>
  import '@moveris/cognito-check';

  let verified = false;

  function onVerified(e) {
    verified = true;
  }

  function onFailed(e) {
    console.warn(e.detail.reason);
  }
</script>

<cognito-check
  api-key="your-api-key"
  on:cognitoSuccess={onVerified}
  on:cognitoError={onFailed}
/>

TypeScript

If you use TypeScript and reference <cognito-check> in JSX or templates, add the element to your project's type declarations:

// global.d.ts
declare global {
  interface HTMLElementTagNameMap {
    'cognito-check': HTMLElement & {
      'api-key': string;
      'consumer-url'?: string;
      'consumer-env'?: 'development' | 'staging' | 'production';
      'track-client-time'?: boolean;
    };
  }
}

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme