{"id":48350,"library":"khenshin-js-protocol","title":"Khenshin JS Protocol","description":"A JavaScript/TypeScript library implementing the Khenshin websocket protocol for real-time communication with Khenshin payment services. Current stable version is 1.0.59. The library provides WebSocket-based messaging with automatic reconnection, message validation, and TypeScript type definitions. It is actively maintained by the Khenshin team, with frequent releases addressing protocol updates and bug fixes. Differentiates from generic WebSocket clients by offering domain-specific message types and built-in handling of Khenshin's authentication and session management.","status":"active","version":"1.0.59","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","typescript"],"install":[{"cmd":"npm install khenshin-js-protocol","lang":"bash","label":"npm"},{"cmd":"yarn add khenshin-js-protocol","lang":"bash","label":"yarn"},{"cmd":"pnpm add khenshin-js-protocol","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Library is ESM-only since v1.0. CommonJS require will not work.","wrong":"const KhenshinProtocol = require('khenshin-js-protocol');","symbol":"KhenshinProtocol","correct":"import { KhenshinProtocol } from 'khenshin-js-protocol'"},{"note":"The correct enum name is MessageType (singular), not MessageTypes.","wrong":"import { MessageTypes } from 'khenshin-js-protocol'","symbol":"MessageType","correct":"import { MessageType } from 'khenshin-js-protocol'"},{"note":"createConnection is a named export, not a default export.","wrong":"import createConnection from 'khenshin-js-protocol'","symbol":"createConnection","correct":"import { createConnection } from 'khenshin-js-protocol'"}],"quickstart":{"code":"import { createConnection, MessageType } from 'khenshin-js-protocol';\n\nconst wsUrl = process.env.KHENSHIN_WS_URL ?? 'wss://example.com/ws';\nconst apiKey = process.env.KHENSHIN_API_KEY ?? '';\n\nasync function main() {\n  const connection = createConnection(wsUrl, { apiKey });\n\n  connection.on('open', () => {\n    console.log('WebSocket connected');\n    connection.send({ type: MessageType.PING, payload: {} });\n  });\n\n  connection.on('message', (data) => {\n    if (data.type === MessageType.PONG) {\n      console.log('Received pong');\n    }\n  });\n\n  connection.on('error', (err) => {\n    console.error('Connection error:', err);\n  });\n\n  await connection.connect();\n}\n\nmain().catch(console.error);","lang":"typescript","description":"Demonstrates creating a WebSocket connection, handling open/message/error events, and sending a PING message."},"warnings":[{"fix":"Wrap the connection logic in a loop with exponential backoff, or upgrade to version 1.0.60+ which may include built-in reconnection.","message":"The library does not automatically reconnect on WebSocket close. You must implement reconnection logic yourself or use the 'reconnect' option if available.","severity":"gotcha","affected_versions":">=1.0.0 <1.0.60"},{"fix":"Always wrap primitive values in an object, e.g., { payload: { id: 123 } }.","message":"The payload property in messages is required and must be an object. Sending a string or number directly will cause validation errors.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use connection.on('message', handler) instead of connection.onMessage(handler).","message":"The 'onMessage' event handler is deprecated in favor of the 'message' event.","severity":"deprecated","affected_versions":">=1.0.40 <1.0.59"},{"fix":"Change 'import Khenshin from ...' to '{ KhenshinProtocol } from ...'. For 'createConnection', use named import.","message":"In version 1.0.50, the default export was removed. All exports are now named.","severity":"breaking","affected_versions":">=1.0.50"}],"env_vars":null,"search_vec":"'1.0.59':25 'activ':44 'address':53 'authent':79 'automat':34 'base':31 'bug':57 'built':73 'built-in':72 'client':63 'communic':16 'current':21 'definit':41 'differenti':59 'domain':67 'domain-specif':66 'fix':58 'frequent':51 'generic':61 'handl':75 'implement':7 'javascript':83 'javascript/typescript':5 'js':2 'khenshin':1,9,18,48,77 'librari':6,27 'maintain':45 'manag':82 'messag':32,36,69 'offer':65 'payment':19 'protocol':3,11,54 'provid':28 'real':14 'real-tim':13 'reconnect':35 'releas':52 'servic':20 'session':81 'specif':68 'stabl':22 'team':49 'time':15 'type':40,70 'typescript':39,84 'updat':55 'valid':37 'version':23 'websocket':10,30,62 'websocket-bas':29","created_at":"2026-06-07T16:56:12.840132+00:00","updated_at":"2026-06-07T16:56:12.840132+00:00","problems":[{"fix":"Use { KhenshinProtocol } from 'khenshin-js-protocol'","cause":"Using default import in TypeScript when the library only exports named exports.","error":"TypeError: KhenshinProtocol is not a constructor"},{"fix":"Always include a payload object, e.g., send({ type: 'PING', payload: {} })","cause":"Sending a message without a payload property.","error":"Error: Validation failed: payload is required"},{"fix":"Check that the WebSocket server is running and the URL is correct. Ensure no firewall blocks the connection.","cause":"WebSocket server is not running or URL is incorrect.","error":"WebSocket connection to 'wss://...' failed: Error in connection establishment: net::ERR_CONNECTION_REFUSED"},{"fix":"Provide apiKey and other required options. Example: createConnection(url, { apiKey: '...' })","cause":"Options object passed to createConnection is missing required fields.","error":"Uncaught (in promise) TypeError: Cannot read properties of undefined (reading 'apiKey')"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":null,"github":null,"docs":null,"changelog":null,"pypi":null,"npm":"khenshin-js-protocol","openapi_spec":null,"status_page":null,"smithery":null,"categories":["payments","messaging"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}