npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@castleio/castle-js

v2.6.0

Published

Castle Fingerprinting Script

Downloads

352,086

Readme

Castle Fingerprinting Script

Packaged version of Castle fingerprinting script.

Introduction

The Castle JavaScript automatically captures every user action in your web application, including clicks, taps, swipes, form submissions, and page views. We use this data to build profiles of good user behavior in order to detect the bad.

Installation

npm install --save @castleio/castle-js
yarn add @castleio/castle-js

Configuration

Basic configuration of the app

// @option options [string] :pk castle publishable key.
// @option options [object] :window (default `window`) eg JSDOM.window
// @option options [string] :apiUrl (default `https://m.castle.io/v1/monitor`) castle api url
// @option options [number] :timeout (default 1000) castle api response timeout
// @option options [boolean] :verbose (default true) verbose mode (console warnings)
// @option options [object] :storage (default name `__cuid`, default expireIn 400 days in seconds: `34560000`) used for storing uuid in the localStorage and the cookies, and for setting cookie expiration time.

import * as Castle from '@castleio/castle-js'

Castle.configure(options);

browser version (legacy setups)

If your environment does not support modules you can use the browser version

import '@castleio/castle-js/dist/castle.browser.js'

Castle.configure(options);

Usage

Getting castle request token

import * as Castle from '@castleio/castle-js'

Castle.createRequestToken().then( (requestToken) => {
  ....
});

// or
const requestToken = await Castle.createRequestToken();

See Castle Docs for more information and how to pass the token further.

form submit helper example (when cdn version is used)

// @param event [Event] submit event
// @param onDone [Function] optional form submit callback replacement
<form action="/" onsubmit="Castle.injectTokenOnSubmit(event)">
  <button type="submit">Submit</button>
</form>

helper is also available directly (when castle.umd.js is used)

import * as Castle from '@castleio/castle-js'

const submitHandler = (evt) => Castle.injectTokenOnSubmit(evt);
<form action="/" onsubmit="submitHandler(event)">
  <button type="submit">Submit</button>
</form>

Sending page event

// @param options [PageParams] castle page command params.
// @option user [UserParams] user object with the required `id`, optional `email`, `phone`, `registered_at`, `name`, `traits`
// @option userJwt [string] optiona jwt encoded UserParams
// @option name [String]
// @option referrer [String]
// @option url [String]

import * as Castle from '@castleio/castle-js'

const page = Castle.page(options);

event response can be verified with promise like call.

import * as Castle from '@castleio/castle-js'

// result - true - success response from the server
// result - false - error response from the server, missing configuration or data
// result - null - timeout or debounced event (300ms)

Castle.page(options).then( (result) => { } )

Sending form event

// @param options [FormParams] castle form command params.
// @option user [UserParams] user object with the required `id`, optional `email`, `phone`, `registered_at`, `name`, `traits`
// @option userJwt [string] JWT encoded UserParams (can be passed instead of the user)
// @option name [String]
// @option values [Record<string, string>]

import * as Castle from '@castleio/castle-js'

Castle.form(options);

event response can be verified with promise like call.

import * as Castle from '@castleio/castle-js'

// result - true - success response from the server
// result - false - error response from the server, missing configuration or data
// result - null - timeout or throttled event (300ms)

Castle.form(options).then( (result) => { } )

form submit helper for form events

import * as Castle from '@castleio/castle-js'

const user = YOUR_USER_DATA;
const submitHandler = (evt) => Castle.formEventOnSubmit(evt, user);
<form action="/" data-castle-name="Change Profile" onsubmit="submitHandler(event)">
  <input type="text" name="user_mail" data-castle-value="email">
  <button type="submit">Submit</button>
</form>

Sending custom event

// @param options [CustomParams] castle custom command params.
// @option user [UserParams] user object with the required `id`, optional `email`, `phone`, `registered_at`, `name`, `traits`
// @option userJwt [string] JWT encoded UserParams (can be passed instead of the user)
// @option name [String]
// @option properties [Record<string,string>]

import * as Castle from '@castleio/castle-js'

const custom = Castle.custom(options);

event response can be verified with promise like call.

import * as Castle from '@castleio/castle-js'

// result - true - success response from the server
// result - false - error response from the server, missing configuration or data
// result - null - timeout or debounced event (default 1000ms)

Castle.custom(options).then( (result) => { } )

Breaking changes

Upgrading from 1.x to 2.0.x

1.x

Legacy package: https://www.npmjs.com/package/castle.js

require "castle.js"
_castle('setAppId', "YOUR_APP_ID")
_castle('getClientId')

2.0.x

New package:

import * as Castle from "@castleio/castle-js"
  1. Renamed the main object from _castle to Castle in the new module, but kept the _castle in the CDN version as well as the browser-specific module @castleio/castle-js/dist/castle.browser.js
  2. Introduced the concept of request tokens that need to be generated for each call to Castle's server-side API.
Castle.createRequestToken().then( (requestToken) => {
});

// or

const token = await Castle.createRequestToken();
  1. Request tokens can no longer be retrieved from the cookie string.
  2. All the following methods were removed:

autoForwardClientId, autoTrack, catchHistoryErrors, identify, setUserId, setAccount, setKey, setAccount, sessionId, reset, page, trackPageView, setTrackerUrl

Request Token is now required to be passed in the request params and it is no longer available in the cookie. Check the docs

Upgrading from 2.0.x to 2.1.x or later

2.0.x

Castle.configure(YOUR_CASTLE_APP_ID);

2.1.x or later

  1. Removed the _castle object for all versions and now only relying on Castle.

  2. Switched to use the Publishable Key that can be found in the same place as the now deprecated App ID.

Castle.configure({pk: YOUR_PUBLISHABLE_KEY});
  1. onFormSubmit has been renamed to injectTokenOnSubmit

  2. _castle global method is no longer supported and has been replaced with Castle (for the CDN and castle.browser.js versions) check docs

  3. CDN version no longer needs appID in the url and requires

<script>Castle.configure({pk: YOUR_CASTLE_PUBLISHABLE_KEY});</script>

to be added. The CDN version can't be used for generating request tokens, but only for tracking client-side events.

  1. Introduced page, form, and custom methods for client-side event tracking

More info can be found in the docs

Changelog

  • 2.6.0 - bug fixes and internal features
  • 2.5.3 - security updates
  • 2.5.2 - internal release
  • 2.5.1 - extended browser support range and bug fixes
  • 2.5.0 - enhanced bot detection capabilities, performance improvements, bug fixes
  • 2.4.3 - internal enhancements
  • 2.4.2 - force https for the monitor requests, bug fixes, utf enhancements
  • 2.4.1 – internal enhancement
  • 2.4.0 – larger set of enhancements and internal features
  • 2.3.6 – internal enhancements
  • 2.3.5 – fixed issue with exporting types in the d.ts file
  • 2.3.4 – internal enhancements
  • 2.3.3 – internal enhancements
  • 2.3.2 – bug fixes
  • 2.3.1 – internal stability fixes
  • 2.3.0 – new configuration option throttling, enabled by default, and set to 500ms, is used when multiple custom events are being sent within short time intervals.
  • 2.2.0 – new configuration option storage, deprecated storageNamespace, and stability improvements.
  • 2.1.15 – new configuration option storageNamespace, for specifing localStorage and cookie storage namespace, stability improvements
  • 2.1.14 – stability improvements
  • 2.1.13 – throw error when pk is not configured
  • 2.1.12 – made Castle.configure to return Castle interface object
  • 2.1.11 – added address support to user for page, form, custom events
  • 2.1.10 – bug fixes and stability improvements
  • 2.1.9 – bug fixes and stability improvements
  • 2.1.8 – pk validation and internal enhancements
  • 2.1.7 – page command bug fixes and improvements
  • 2.1.6 – fixed JWT validation issue
  • 2.1.5 – readme update
  • 2.1.4 – stability improvements
  • 2.1.3 – view events bug fixes and stability improvements
  • 2.1.2 – view events bug fixes
  • 2.1.1 – internal enhancements and stability improvements
  • 2.1.0 – added page, form, custom events support, changed configuration DSL, added formEventOnSubmit helper, renamed onFormSubmit to injectTokenOnSubmit (breaking changes - check docs )
  • 2.0.4 – bug fixes
  • 2.0.3 – bug fixes and stability improvements
  • 2.0.2 – bug fixes
  • 2.0.1 – internal enhancements
  • 2.0.0 – migration from 1.x, modularization, updated DSL, (breaking changes - check docs )

Minimal Requirements:

createRequestToken() is supported by the following browsers:

  • Chrome 5+
  • Firefox 3+
  • IE 6+
  • Safari 4+
  • All modern browsers (desktop and mobile)

page(), form() and custom() events are supported by the following browsers:

  • Chrome 9+
  • Firefox 6+
  • IE 10+
  • Safari 5+
  • All modern browsers (desktop and mobile)

License

MIT