@pulsealarm/pulse-event-sdk 0.1.0

package/.github/workflows/npm-publish.yml

@@ -0,0 +1,28 @@
+name: Publish Package to npmjs
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install Dependencies
+        run: npm install
+
+      - name: Publish to NPM
+        # 'npm publish' komutu otomatik olarak .npmrc içindeki token'ı kullanır
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/README.md

@@ -0,0 +1,326 @@
+# Pulse Event SDK (JavaScript)
+
+Framework-agnostic, non-blocking event and error tracking SDK for:
+- Browser apps
+- Node.js services
+- React / Vue
+- Express / Fastify
+- Next.js / Nuxt
+- Custom integrations
+
+## Features
+
+- Non-blocking event delivery (queue + background flush)
+- Dynamic webhook endpoint updates (`setEndpoint`, `setWebhookCredentials`)
+- Manual custom event tracking
+- Manual exception capture (`captureException`, `captureError`)
+- Global runtime error handlers (browser + Node.js)
+- Automatic `session_id` generation when missing
+- Lightweight adapters for modern frameworks
+- TypeScript support
+- Fully tested
+- 100% code coverage
+
+## Installation
+
+```bash
+npm install
+```
+
+## Quick Start (Core SDK)
+
+```js
+import { createPulseClient } from "pulse-event-sdk";
+
+const pulse = createPulseClient({
+  baseUrl: "https://pulsealarm.dev",
+  projectCode: "PUL",
+  webhookToken: "1b6ab14728893skXd2e4926f16869290c1c44ddz3xb3",
+  defaults: {
+    environment: "production",
+    app_version: "2.3.1",
+    platform: "web"
+  }
+});
+
+pulse.track({
+  title: "Payment failed for order #1234",
+  description: "Stripe returned card_declined error during checkout",
+  level: "error",
+  type: "exception",
+  timestamp: "2026-02-11T14:30:00Z",
+  data: {
+    stack_trace: "Error: card_declined\n  at processPayment (checkout.js:42)",
+    user_agent: "Mozilla/5.0...",
+    any_key: "any_value"
+  },
+  session_id: "sess_abc123",
+  customer_id: "cust_456",
+  ip_address: "203.0.113.10",
+  request_url: "https://myapp.com/api/checkout",
+  country: "Turkey",
+  country_code: "TR",
+  tags: ["payment", "critical-path"],
+  revenue: {
+    currency: "USD",
+    price: 49.99
+  },
+  group: true,
+  resolved: false
+});
+```
+
+## Dynamic Endpoint
+
+```js
+import { buildWebhookEndpoint } from "pulse-event-sdk";
+
+pulse.setEndpoint(
+  buildWebhookEndpoint("https://pulsealarm.dev", "PUL", "new-token")
+);
+```
+
+```js
+pulse.setWebhookCredentials("PUL", "new-token");
+```
+
+## Webhook Credentials (Project + Token)
+
+- `projectCode` is your project identifier (example: `PUL`).
+- `webhookToken` is your webhook token.
+- SDK builds endpoint as: `${baseUrl}/webhook/${projectCode}/${webhookToken}`.
+
+```js
+import { createPulseClient, buildWebhookEndpoint } from "pulse-event-sdk";
+
+const endpoint = buildWebhookEndpoint(
+  "https://pulsealarm.dev",
+  "PUL",
+  "1b6ab14728893skXd2e4926f16869290c1c44ddz3xb3"
+);
+
+const pulse = createPulseClient({
+  projectCode: "PUL",
+  webhookToken: "1b6ab14728893skXd2e4926f16869290c1c44ddz3xb3"
+});
+```
+
+## Session Tracking
+
+- If `session_id` is not provided, SDK auto-generates `sess_*`.
+- In browsers, generated session ID is reused in the same tab via `sessionStorage`.
+- If you pass `session_id` explicitly in an event, it is preserved.
+
+```js
+console.log(pulse.getSessionId());
+```
+
+## Custom Event Tracking
+
+```js
+pulse.event("checkout.step.completed", {
+  level: "info",
+  tags: ["checkout"]
+});
+```
+
+## Manual Exception Capture
+
+```js
+try {
+  doPayment();
+} catch (error) {
+  pulse.captureException(error, {
+    tags: ["payment"],
+    request_url: window.location.href
+  });
+}
+```
+
+## Global Error Capture
+
+```js
+pulse.installGlobalHandlers();
+```
+
+- Browser: `error` and `unhandledrejection`
+- Node.js: `uncaughtException` and `unhandledRejection`
+
+## Runtime-Specific Usage
+
+### Node.js service
+
+```js
+import { createPulseClient } from "pulse-event-sdk";
+
+const pulse = createPulseClient({
+  baseUrl: "https://pulsealarm.dev",
+  projectCode: "PUL",
+  webhookToken: "1b6ab14728893skXd2e4926f16869290c1c44ddz3xb3",
+  defaults: { platform: "server", environment: "production" }
+});
+
+pulse.installGlobalHandlers();
+pulse.event("worker.started");
+
+process.on("SIGTERM", () => {
+  pulse.close();
+  process.exit(0);
+});
+```
+
+### Browser app
+
+```js
+const pulse = createPulseClient({
+  baseUrl: "https://pulsealarm.dev",
+  projectCode: "PUL",
+  webhookToken: "1b6ab14728893skXd2e4926f16869290c1c44ddz3xb3",
+  defaults: { platform: "web" }
+});
+
+pulse.installGlobalHandlers();
+```
+
+## React Integration
+
+```jsx
+import { usePulse, PulseErrorBoundary, withPulseErrorBoundary } from "pulse-event-sdk/react";
+```
+
+Error boundary component:
+
+```jsx
+<PulseErrorBoundary pulse={pulse} fallback={<div>Something failed</div>}>
+  <Checkout />
+</PulseErrorBoundary>
+```
+
+HOC wrapper:
+
+```jsx
+const SafeCheckout = withPulseErrorBoundary(Checkout, { pulse });
+```
+
+## Vue Integration
+
+```js
+import { createPulseVuePlugin } from "pulse-event-sdk/vue";
+
+app.use(
+  createPulseVuePlugin({
+    baseUrl: "https://pulsealarm.dev",
+    projectCode: "PUL",
+    webhookToken: "1b6ab14728893skXd2e4926f16869290c1c44ddz3xb3",
+    defaults: { platform: "web", environment: "production" }
+  })
+);
+```
+
+The plugin also configures `app.config.errorHandler` automatically.
+
+## Express Integration
+
+```js
+import {
+  createExpressPulseRequestMiddleware,
+  createExpressPulseErrorMiddleware
+} from "pulse-event-sdk/express";
+
+app.use(createExpressPulseRequestMiddleware(pulse));
+app.use(createExpressPulseErrorMiddleware(pulse));
+```
+
+## Fastify Integration
+
+```js
+import { createFastifyPulsePlugin } from "pulse-event-sdk/fastify";
+
+await fastify.register(createFastifyPulsePlugin(pulse));
+```
+
+## Next.js Integration
+
+Pages router API handler:
+
+```js
+import { withPulseApiHandler } from "pulse-event-sdk/next";
+
+export default withPulseApiHandler(async function handler(req, res) {
+  throw new Error("boom");
+}, pulse);
+```
+
+App router route handler:
+
+```js
+import { withPulseRouteHandler } from "pulse-event-sdk/next";
+
+export const POST = withPulseRouteHandler(async function POST(request) {
+  throw new Error("boom");
+}, pulse);
+```
+
+## Nuxt Integration
+
+```js
+import { createNuxtPulsePlugin } from "pulse-event-sdk/nuxt";
+
+export default defineNuxtPlugin((nuxtApp) => {
+  createNuxtPulsePlugin(pulse)(nuxtApp);
+});
+```
+
+## Event Payload Schema
+
+- `title` (required): `string`
+- `description`: `string`
+- `level`: `error | warning | info | fatal | debug`
+- `type`: `exception | event | log`
+- `timestamp`: ISO-8601 `string`
+- `data`: `object`
+- `session_id`: `string`
+- `customer_id`: `string`
+- `ip_address`: `string` 
+- `request_url`: `string`
+- `country`: `string`
+- `country_code`: `string`
+- `tags`: `string[]`
+- `revenue`: `{ currency: string, price: number }`
+- `group`: `boolean`
+- `resolved`: `boolean`
+- `environment`: `production | staging | development | test`
+- `app_version`: `string`
+- `platform`: `web | ios | android | server | desktop`
+
+## CLI Testing
+
+Run all tests:
+
+```bash
+npm test
+```
+
+Run Node quickstart example:
+
+```bash
+node ./examples/node-quickstart.js
+```
+
+Send raw payload to webhook:
+
+```bash
+PROJECT_CODE="PUL"
+WEBHOOK_TOKEN="1b6ab14728893skXd2e4926f16869290c1c44ddz3xb3"
+BASE_URL="https://pulsealarm.dev"
+
+curl -X POST "${BASE_URL}/webhook/${PROJECT_CODE}/${WEBHOOK_TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d '{"title":"CLI test event"}'
+```
+
+## Notes
+
+- `track()` is non-blocking: events go to queue, then flush in background. 1000 events per minute.
+- Browser attempts best-effort flush via `sendBeacon` on page exit/hidden state.
+- In Node.js, call `pulse.close()` before shutdown for cleaner flush behavior. 

package/examples/browser-quickstart.js

@@ -0,0 +1,49 @@
+import { createPulseClient } from "../src/index.js";
+
+const pulse = createPulseClient({
+  baseUrl: "https://pulsealarm.dev",
+  projectCode: "PUL",
+  webhookToken: "1b6ab14728893skXd2e4926f16869290c1c44ddz3xb3",
+  defaults: {
+    environment: "production",
+    app_version: "2.3.1",
+    platform: "web"
+  }
+});
+
+pulse.installGlobalHandlers();
+
+pulse.track({
+  title: "Payment failed for order #1234",
+  description: "Stripe returned card_declined error during checkout",
+  level: "error",
+  type: "exception",
+  data: {
+    stack_trace: "Error: card_declined\n  at processPayment (checkout.js:42)",
+    user_agent: navigator.userAgent,
+    any_key: "any_value"
+  },
+  session_id: "sess_abc123",
+  customer_id: "cust_456",
+  request_url: window.location.href,
+  country: "Turkey",
+  country_code: "TR",
+  tags: ["payment", "critical-path"],
+  revenue: {
+    currency: "USD",
+    price: 49.99
+  },
+  group: true,
+  resolved: false
+});
+
+try {
+  throw new Error("Checkout service unavailable");
+} catch (error) {
+  pulse.captureException(error, {
+    tags: ["checkout"],
+    data: {
+      order_id: 1234
+    }
+  });
+}

package/examples/node-quickstart.js

@@ -0,0 +1,37 @@
+import { createPulseClient } from "../src/index.js";
+
+const pulse = createPulseClient({
+  baseUrl: "https://pulsealarm.dev",
+  projectCode: "PUL",
+  webhookToken: "1b6ab14728893skXd2e4926f16869290c1c44ddz3xb3",
+  defaults: {
+    environment: "production",
+    app_version: "2.3.1",
+    platform: "server"
+  },
+  debug: true
+});
+
+pulse.installGlobalHandlers();
+
+pulse.event("worker.started", {
+  level: "info",
+  tags: ["worker"]
+});
+
+try {
+  throw new Error("Background job failed");
+} catch (error) {
+  pulse.captureError(error, {
+    request_url: "/jobs/reconcile",
+    session_id: "sess_worker_1",
+    customer_id: "cust_456",
+    data: {
+      job_name: "reconcile"
+    }
+  });
+}
+
+setTimeout(() => {
+  pulse.close();
+}, 1500);

package/examples/react-usage.jsx

@@ -0,0 +1,33 @@
+import { useEffect } from "react";
+import { usePulse } from "pulse-event-sdk/react";
+
+export default function CheckoutPage() {
+  const pulse = usePulse({
+    baseUrl: "https://pulsealarm.dev",
+    projectCode: "PUL",
+    webhookToken: "1b6ab14728893skXd2e4926f16869290c1c44ddz3xb3",
+    defaults: { platform: "web", environment: "production" }
+  });
+
+  useEffect(() => {
+    pulse.event("checkout.page_opened", { level: "info", tags: ["checkout"] });
+    pulse.installGlobalHandlers();
+    return () => pulse.close();
+  }, [pulse]);
+
+  return (
+    <button
+      onClick={() => {
+        try {
+          throw new Error("Payment form validation failed");
+        } catch (error) {
+          pulse.captureException(error, {
+            tags: ["payment", "validation"]
+          });
+        }
+      }}
+    >
+      Pay
+    </button>
+  );
+}

package/examples/vue-usage.js

@@ -0,0 +1,16 @@
+import { createApp } from "vue";
+import { createPulseVuePlugin } from "pulse-event-sdk/vue";
+import App from "./App.vue";
+
+const app = createApp(App);
+
+app.use(
+  createPulseVuePlugin({
+    baseUrl: "https://pulsealarm.dev",
+    projectCode: "PUL",
+    webhookToken: "1b6ab14728893skXd2e4926f16869290c1c44ddz3xb3",
+    defaults: { platform: "web", environment: "production" }
+  })
+);
+
+app.mount("#app");

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@pulsealarm/pulse-event-sdk",
+  "version": "0.1.0",
+  "description": "Non-blocking event/error SDK for browser and Node.js",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./react": "./src/integrations/react.js",
+    "./vue": "./src/integrations/vue.js",
+    "./express": "./src/integrations/express.js",
+    "./fastify": "./src/integrations/fastify.js",
+    "./next": "./src/integrations/next.js",
+    "./nuxt": "./src/integrations/nuxt.js"
+  },
+  "scripts": {
+    "check": "node ./examples/node-quickstart.js",
+    "test": "node --test"
+  },
+  "keywords": [
+    "event",
+    "monitoring",
+    "sdk",
+    "error-tracking",
+    "javascript"
+  ],
+  "license": "MIT"
+}