npm package: @pulseprotocol/pulse-js
Description: PULSE Protocol for JavaScript. Send semantic messages between JS, Python, Go and C# apps. Connect to Claude, GPT-4, Binance, Bybit in one line. HMAC-SHA256 signing, replay protection, zero dependencies. Node.js 18+ and browser.
Author: PULSE Protocol
Latest version: 0.1.1

# pulse-js

**PULSE Protocol for JavaScript** — connect your JavaScript app to any language, any AI, any exchange with one universal message format.

[![npm version](https://img.shields.io/npm/v/@pulseprotocol/pulse-js)](https://www.npmjs.com/package/@pulseprotocol/pulse-js)
[![npm downloads](https://img.shields.io/npm/dw/@pulseprotocol/pulse-js)](https://www.npmjs.com/package/@pulseprotocol/pulse-js)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)

---

## The problem it solves

You have a JavaScript frontend. Your backend is Python. Your ML service is Go. Your trading engine is C#.

Every pair of services needs a custom integration. Different formats, different field names, different auth schemes. Every time you add a service, you write new glue code.

**pulse-js fixes this.** One message format that works across all languages, all systems, all AI providers. Write it once in JavaScript — Python, Go, and C# read it without any custom parsing.

---

## What developers get

**1. Cross-language communication out of the box**

A JavaScript app sends a PULSE message. A Python service receives it. A Go microservice forwards it. No format negotiation, no custom parsers, no documentation reading. The format is the same everywhere.

```javascript
// JavaScript sends
const msg = new PulseMessage({
  action: 'ACT.ANALYZE.SENTIMENT',
  params: { text: 'Great product!' }
});

// Python receives and understands — same format, zero config
```

**2. Connect to AI agents without custom integration**

PULSE Protocol already has adapters for Claude, GPT-4, Gemini, and Ollama. When your JavaScript app sends a PULSE message, any AI agent in the ecosystem can process it — no custom wrappers needed.

```javascript
const client = new PulseClient({ endpoint: 'http://your-ai-service:8888' });
const result = await client.send('ACT.GENERATE.TEXT', { prompt: 'Summarize this...' });
```

**3. Built-in security — no setup required**

Every message can be signed with HMAC-SHA256 in one line. Replay attack protection is built into the protocol. You don't configure it — it's just there.

```javascript
await msg.signWith('shared-secret');
// Signature is in the envelope, verified automatically on the other side
```

**4. Semantic vocabulary — no ambiguity between systems**

`ACT.QUERY.DATA` means the same thing in every language, on every platform. Not "query", not "getData", not "fetch" — one unambiguous concept that any PULSE system understands.

120+ predefined concepts covering actions, entities, properties, time, logic, data types, and market operations. Invalid concepts throw immediately with suggestions.

**5. Works in Node.js and the browser**

Uses Web Crypto API and native `fetch` — no Node.js-specific dependencies in the core. Same code runs server-side and client-side.

**6. Zero dependencies in the core**

No axios, no lodash, no bloat. The entire core is plain JavaScript using built-in APIs. Smaller bundle, fewer vulnerabilities, faster install.

---

## Install

```bash
npm install @pulseprotocol/pulse-js
```

Requires Node.js 18+ or a modern browser (Chrome 90+, Firefox 90+, Safari 15+).

---

## Quick Start

### Create a message

```javascript
import { PulseMessage } from '@pulseprotocol/pulse-js';

const msg = new PulseMessage({
  action: 'ACT.QUERY.DATA',
  object: 'ENT.DATA.TEXT',
  params: { query: 'hello world' },
  sender: 'my-app',
  receiver: 'data-service',
});

console.log(msg.toString()); // JSON string ready to send
```

### Send to any PULSE server

```javascript
import { PulseClient } from '@pulseprotocol/pulse-js';

const client = new PulseClient({
  endpoint: 'http://localhost:8888',
  sender: 'js-client',
  secret: 'optional-hmac-secret',  // enables signed requests
});

const response = await client.send('ACT.QUERY.DATA', { query: 'test' });
console.log(response.content.params);

// Check if server is alive
const alive = await client.ping(); // true / false
```

### Run a PULSE server

```javascript
import { PulseServer } from '@pulseprotocol/pulse-js';

const server = new PulseServer({ port: 8888 });

// Register handlers by action
server.on('ACT.QUERY.DATA', async (msg) => {
  const { query } = msg.content.params;
  return { result: `You asked: ${query}` };
});

server.on('ACT.GENERATE.TEXT', async (msg) => {
  // call your AI model here
  return { text: 'Generated response...' };
});

await server.start();
// PULSE Server listening on http://0.0.0.0:8888/pulse
```

### Sign and verify messages

```javascript
import { PulseMessage } from '@pulseprotocol/pulse-js';

// Sender signs
const msg = new PulseMessage({ action: 'ACT.TRADE.BUY', params: { symbol: 'BTC/USDT' } });
await msg.signWith('shared-secret');

// Receiver verifies
const received = PulseMessage.from(jsonString);
const valid = await received.verifyWith('shared-secret'); // true

// Tampered message fails verification automatically
```

---

## Cross-language example

JavaScript frontend → Python backend:

```javascript
// JavaScript (browser or Node.js)
import { PulseClient } from '@pulseprotocol/pulse-js';

const client = new PulseClient({ endpoint: 'http://python-service:8888' });
const result = await client.send('ACT.ANALYZE.SENTIMENT', { text: 'Excellent!' });
// result.content.params.sentiment === 'positive'
```

```python
# Python backend (pulse-python)
server.on('ACT.ANALYZE.SENTIMENT', lambda msg: {
    'sentiment': 'positive', 'score': 0.97
})
```

Switch the Python backend to Go or C# — your JavaScript code doesn't change. The protocol is the same.

---

## Vocabulary

PULSE concepts follow a dot-separated hierarchy: `CATEGORY.SUBCATEGORY.SPECIFIC`

| Category | What it covers | Examples |
|---|---|---|
| `ACT.*` | Actions — what to do | `ACT.QUERY.DATA`, `ACT.GENERATE.TEXT`, `ACT.TRADE.BUY`, `ACT.VOTE` |
| `ENT.*` | Entities — what to act on | `ENT.AGENT.AI`, `ENT.DATA.TEXT`, `ENT.MARKET.ORDER`, `ENT.BALLOT` |
| `META.*` | Protocol control | `META.STATUS.SUCCESS`, `META.PING`, `META.ACK`, `META.ERROR.AUTH` |
| `PROP.*` | Properties | `PROP.STATE.ACTIVE`, `PROP.PRIORITY.HIGH` |
| `REL.*` | Relations | `REL.PARENT.OF`, `REL.DEPENDS.ON` |
| `TIME.*` | Temporal | `TIME.NOW`, `TIME.BEFORE`, `TIME.AFTER` |
| `DATA.*` | Data types | `DATA.LIST`, `DATA.DICT`, `DATA.STRING` |
| `MATH.*` | Math operations | `MATH.SUM`, `MATH.AVERAGE`, `MATH.COUNT` |

Using an unknown concept throws immediately:

```
PulseError: Unknown concept: "ACT.QUERY". Did you mean: ACT.QUERY.DATA, ACT.QUERY.STATUS?
```

---

## Security

PULSE has a built-in 4-layer security model:

| Layer | What it does |
|---|---|
| **Message signing** | HMAC-SHA256 on every message — tampering is detectable |
| **Replay protection** | Unique nonce per message, 5-minute timestamp window |
| **Signature exclusion** | Signature field excluded from signing payload — no circular dependency |
| **Timing-safe comparison** | Constant-time signature check — no timing attacks |

---

## API Reference

### `PulseMessage`

```javascript
new PulseMessage({ action, object, params, type, sender, receiver })

msg.toJSON()          // → plain object
msg.toString()        // → JSON string
msg.signWith(secret)  // → Promise, sets envelope.signature
msg.verifyWith(secret)// → Promise<boolean>
msg.reply(action, params) // → new PulseMessage (RESPONSE type)

PulseMessage.from(jsonOrObject) // parse incoming message
```

### `PulseClient`

```javascript
new PulseClient({ endpoint, sender, secret, timeout })

client.send(action, params, { object, receiver }) // → Promise<PulseMessage>
client.ping()                                      // → Promise<boolean>
```

### `PulseServer`

```javascript
new PulseServer({ port, host, secret, checkFreshness, onMessage, onError })

server.on(action, handler)  // register action handler
server.start()              // → Promise
server.stop()               // → Promise
```

### Vocabulary helpers

```javascript
import { isValidConcept, getCategory, suggest, VOCABULARY } from '@pulseprotocol/pulse-js';

isValidConcept('ACT.QUERY.DATA') // true
getCategory('ACT')               // ['ACT.QUERY.DATA', 'ACT.GENERATE.TEXT', ...]
suggest('QUERY')                 // ['ACT.QUERY.DATA', 'ACT.QUERY.STATUS', ...]
VOCABULARY.size                  // 120+
```

---

## PULSE Protocol ecosystem

`pulse-js` is part of an open ecosystem of interoperable packages:

| Package | Language | Purpose |
|---|---|---|
| `pulse-python` | Python | Core protocol reference implementation |
| `pulse-js` | JavaScript | Browser + Node.js |
| `pulse-anthropic` | Python | Claude AI adapter |
| `pulse-openai` | Python | OpenAI adapter |
| `pulse-gemini` | Python | Gemini adapter |
| `pulse-bybit` | Python | Bybit exchange |
| `pulse-binance` | Python | Binance exchange |
| `pulse-tradingview` | Python | TradingView webhooks → exchange |
| `pulse-tax` | Python | Crypto tax reporting |

Any package in this list can talk to any other package — same protocol, same vocabulary, same message format.

---

## License

Apache 2.0 — free forever, open source.

[GitHub](https://github.com/pulseprotocolorg-cyber/pulse-js) · [npm](https://www.npmjs.com/package/@pulseprotocol/pulse-js) · [PULSE Protocol](https://github.com/pulseprotocolorg-cyber/pulse-python)