{"_id":"@apexstream/client","_rev":"3-f7e71677092d9c53f6649195cc77a595","name":"@apexstream/client","dist-tags":{"latest":"1.0.8"},"versions":{"1.0.6":{"name":"@apexstream/client","version":"1.0.6","keywords":["apexstream","websocket","realtime","pubsub","ws","wss","typescript","browser","nodejs"],"author":{"url":"https://github.com/apexstream","name":"ApexStream"},"license":"MIT","_id":"@apexstream/client@1.0.6","maintainers":[{"name":"apexstreamowner","email":"dmitry.shetko@gmail.com"}],"homepage":"https://github.com/apexstream/client#readme","bugs":{"url":"https://github.com/apexstream/client/issues"},"dist":{"shasum":"673d56d2830fa7bf29be1bfcbea32d2b1a9666fa","tarball":"https://registry.npmjs.org/@apexstream/client/-/client-1.0.6.tgz","fileCount":9,"integrity":"sha512-rnxb6MokNiBqL8APwwfYbxdzXpkxthDEX4gDTofZkCA3Tam7SiaTm0u8qK+goWmFV0fub+pJ6vsy0KvOlMHVXA==","signatures":[{"sig":"MEYCIQCODbJFFXpUXbeOugAija600qHVWTc+JZ4PAHoInd3svAIhAPT5Ei9Hug9lnXspKrV+nXIogqC8G0ekhZCVB2+E0zrj","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":70535},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"gitHead":"4b76620a3e35a5aacf5006dc7f412e934377a699","scripts":{"build":"tsup","test:sdk":"node ../../scripts/sdk-integration-test.mjs","prepublishOnly":"npm run build"},"_npmUser":{"name":"apexstreamowner","email":"dmitry.shetko@gmail.com"},"repository":{"url":"git+https://github.com/apexstream/client.git","type":"git"},"_npmVersion":"10.2.3","description":"Official ApexStream JS/TS SDK — WebSocket client for the realtime gateway (subscribe, publish, channel messages). Uses api_key on the WS URL; browsers & Node 18+.","directories":{},"sideEffects":false,"_nodeVersion":"22.14.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.4.0","typescript":"^5.8.3"},"_npmOperationalInternal":{"tmp":"tmp/client_1.0.6_1776932613058_0.8117883324951383","host":"s3://npm-registry-packages-npm-production"}},"1.0.7":{"name":"@apexstream/client","version":"1.0.7","keywords":["apexstream","websocket","realtime","pubsub","ws","wss","typescript","browser","nodejs"],"author":{"url":"https://github.com/apexstream","name":"ApexStream"},"license":"MIT","_id":"@apexstream/client@1.0.7","maintainers":[{"name":"apexstreamowner","email":"dmitry.shetko@gmail.com"}],"homepage":"https://github.com/apexstream/client#readme","bugs":{"url":"https://github.com/apexstream/client/issues"},"dist":{"shasum":"2fe3626ff6d0f9b0793b74b6345141c9d9bfdf3b","tarball":"https://registry.npmjs.org/@apexstream/client/-/client-1.0.7.tgz","fileCount":7,"integrity":"sha512-KwuBfIJbx7031vFtI+yu0Y9s6UEtkcw/daOYph5jBYHC73EXgAZyV1vZF9/gJxAnbtom0pD+67zGB2lHw7q9+g==","signatures":[{"sig":"MEUCIQD6mGZDpMEc/LtnV+2V1J3cWLN+i61Sa30kpDwGGRqjggIgNSZUNqSkp6IeuG3JCk2MIlf1wloULffWufWWqu/ITmE=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":65570},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"gitHead":"6af7597b25044e64102c6649a23db154fa0924dd","scripts":{"build":"tsup","test:sdk":"node ../../scripts/sdk-integration-test.mjs","prepublishOnly":"npm run build"},"_npmUser":{"name":"apexstreamowner","email":"dmitry.shetko@gmail.com"},"repository":{"url":"git+https://github.com/apexstream/client.git","type":"git"},"_npmVersion":"10.2.3","description":"Official ApexStream JS/TS SDK — WebSocket client for the realtime gateway (subscribe, publish, channel messages). Uses api_key on the WS URL; browsers & Node 18+.","directories":{},"sideEffects":false,"_nodeVersion":"22.14.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.4.0","typescript":"^5.8.3"},"_npmOperationalInternal":{"tmp":"tmp/client_1.0.7_1779342989048_0.4537808765422122","host":"s3://npm-registry-packages-npm-production"}},"1.0.8":{"name":"@apexstream/client","version":"1.0.8","description":"Official ApexStream JS/TS SDK — WebSocket client for the realtime gateway (subscribe, publish, channel messages). Uses api_key on the WS URL; browsers & Node 18+.","keywords":["apexstream","websocket","realtime","pubsub","ws","wss","typescript","browser","nodejs"],"homepage":"https://github.com/apexstream/client#readme","bugs":{"url":"https://github.com/apexstream/client/issues"},"repository":{"type":"git","url":"git+https://github.com/apexstream/client.git"},"author":{"name":"ApexStream","url":"https://github.com/apexstream"},"license":"MIT","type":"module","publishConfig":{"access":"public"},"main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"sideEffects":false,"scripts":{"build":"tsup","prepublishOnly":"npm run build","test:sdk":"node ../../scripts/sdk-integration-test.mjs"},"devDependencies":{"tsup":"^8.4.0","typescript":"^5.8.3"},"engines":{"node":">=18"},"_id":"@apexstream/client@1.0.8","gitHead":"6af7597b25044e64102c6649a23db154fa0924dd","_nodeVersion":"22.14.0","_npmVersion":"10.2.3","dist":{"integrity":"sha512-CAVnnWDM+9S3oqVNWUOkNzaTfbtgCGpm+19hNYVpN/YYkp2p+9iELM8E2pPWPCVo4Fhuf1kP16DcR/RRR3HQzA==","shasum":"ace4df81dbc8dc55bedb2f52ae30be5fc57996f1","tarball":"https://registry.npmjs.org/@apexstream/client/-/client-1.0.8.tgz","fileCount":7,"unpackedSize":65650,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIHa/wJd4lquL2WVnHAYYX9AsCjUIDCt8KmZiCxVLQEovAiBoa1AN57NdYALvyvsC3Lkt6TO2WrEGOWpt/7mPqxTgBw=="}]},"_npmUser":{"name":"apexstreamowner","email":"dmitry.shetko@gmail.com"},"directories":{},"maintainers":[{"name":"apexstreamowner","email":"dmitry.shetko@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/client_1.0.8_1779345215917_0.45752317392558073"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-23T08:23:32.933Z","modified":"2026-05-21T06:33:36.253Z","1.0.6":"2026-04-23T08:23:33.203Z","1.0.7":"2026-05-21T05:56:29.181Z","1.0.8":"2026-05-21T06:33:36.048Z"},"bugs":{"url":"https://github.com/apexstream/client/issues"},"author":{"name":"ApexStream","url":"https://github.com/apexstream"},"license":"MIT","homepage":"https://github.com/apexstream/client#readme","keywords":["apexstream","websocket","realtime","pubsub","ws","wss","typescript","browser","nodejs"],"repository":{"type":"git","url":"git+https://github.com/apexstream/client.git"},"description":"Official ApexStream JS/TS SDK — WebSocket client for the realtime gateway (subscribe, publish, channel messages). Uses api_key on the WS URL; browsers & Node 18+.","maintainers":[{"name":"apexstreamowner","email":"dmitry.shetko@gmail.com"}],"readme":"# @apexstream/client\n\nOfficial **JavaScript / TypeScript** SDK for **[ApexStream](https://github.com/apexstream)** — connect your app to the realtime **WebSocket gateway**, subscribe to named channels, and publish JSON payloads. Designed for browser apps and **Node.js 18+** (uses the native `WebSocket` API).\n\nPublished on npm as **`@apexstream/client`** (scoped package).\n\n| | |\n|---|---|\n| **Repository** | [`github.com/apexstream/client`](https://github.com/apexstream/client) |\n| **Issues** | [github.com/apexstream/client/issues](https://github.com/apexstream/client/issues) |\n| **Examples** | **[github.com/apexstream/examples](https://github.com/apexstream/examples)** — standalone Vite demos (chat, dashboard, webhooks, presence, admin, AI bus); copy a folder and run `npm install` in `client/`. |\n\n## Description\n\n**ApexStream** is a WebSocket-centric platform: a control-plane API issues app keys, and a **gateway** exposes `GET /v1/ws` for authenticated clients. This package implements a small **`ApexStreamClient`** that:\n\n- opens a **WebSocket** to your gateway URL (typically `wss://…/v1/ws` in production);\n- sends **subscribe** / **unsubscribe** / **publish** messages as JSON text frames;\n- delivers **message** events to your handlers per channel.\n\nYou bring your own **gateway URL** and **API key** (from the ApexStream dashboard for that deployment). The SDK does **not** read `.env` files; wire values from `import.meta.env` (Vite), `process.env` (Node), or your host’s secret store.\n\n**Keys:** use the **publishable** key (`pk_live_…`) in browser code. The **secret** key (`sk_live_…`) also works for the WebSocket, but the string is added to the URL as `api_key=…` — treat it as sensitive and avoid shipping it in public frontends.\n\n**MIT licensed.**\n\n## Features\n\n- **Subscribe / publish** on named channels with per-channel callbacks  \n- **Connection lifecycle** hooks: `open`, `close`, `error`, `message`  \n- **Secure by default** for non-localhost hosts: requires `wss://` outside localhost  \n- **ESM + CJS** builds and TypeScript typings included  \n\n## Examples\n\nRunnable **product demos** that use this SDK live in **[apexstream/examples](https://github.com/apexstream/examples)** (separate repo so you can clone or zip a single demo without the full platform tree). Each demo has its own `README` and `client/.env.example`.\n\n## Install\n\n```bash\nnpm install @apexstream/client\n```\n\n## Configuration\n\nYou must pass:\n\n- **`url`** — WebSocket URL of the gateway, ending with **`/v1/ws`** (single slash before `v1`), **without** query string — e.g. `wss://gateway.example.com/v1/ws` or `ws://192.168.1.10:30081/v1/ws`. The client appends **`api_key=…`** for the browser `WebSocket` handshake.\n- **`apiKey`** — dashboard **publishable** (`pk_live_…`) or **secret** (`sk_live_…`) for that app/environment.\n- **`allowInsecureTransport`** (optional) — set **`true`** when using **`ws://`** to anything other than **localhost / 127.0.0.1** (typical LAN or k8s NodePort). In local dev (HTTP page + **`ws://`** gateway) use **`wsUrl.startsWith(\"ws://\")`** and/or set **`VITE_APEXSTREAM_ALLOW_INSECURE=1`** so the SDK does not reject plain WebSocket (see Vite snippet below). Omit or **`false`** when using **`wss://`** in production.\n\nThe SDK **does not** load `.env` by itself. Exposed names depend on your bundler (**`VITE_`** = Vite only; **`REACT_APP_`** = CRA; **`NEXT_PUBLIC_`** = Next.js client; plain **`process.env`** in Node). See **`.env.example`** in this package for commented variable names.\n\nTypical mapping from env → constructor:\n\n| Env (example names) | Constructor option | Why |\n|---|---|---|\n| **`VITE_APEXSTREAM_WS_URL`** / **`APEXSTREAM_WS_URL`** | `url` | Gateway WebSocket endpoint (`…/v1/ws`). |\n| **`VITE_APEXSTREAM_API_KEY`** / **`APEXSTREAM_API_KEY`** | `apiKey` | Dashboard publishable (`pk_live_…`) or secret (`sk_live_…`). |\n| **`VITE_APEXSTREAM_ALLOW_INSECURE`** / **`APEXSTREAM_ALLOW_INSECURE_TRANSPORT`** | `allowInsecureTransport` | Set **`1`** / **`true`** for **explicit** local/LAN dev (page on `http://`, gateway on **`ws://`** to a non-localhost host). Combine with URL: **`wsUrl.startsWith(\"ws://\")`** **or** this env (see Vite snippet). Node publishers: **`url.startsWith(\"ws://\")`** from `APEXSTREAM_WS_URL`, or set **`APEXSTREAM_ALLOW_INSECURE_TRANSPORT`**. |\n\n### Browser `Origin` and the gateway\n\nThe browser sends an **`Origin`** header (e.g. `http://localhost:5173`) that must be allowed by your **gateway** deployment. Self‑hosted gateways support **`APEXSTREAM_GATEWAY_ALLOW_ORIGINS`** (comma‑separated full origins, or `*` for debugging only). If the SPA runs at **`http://localhost:5173`** but the WebSocket host is a **LAN IP** or NodePort, those origins differ — configure the gateway accordingly (see your ApexStream / k8s docs).\n\n### DevTools noise\n\nAfter **reconnect** or **React Strict Mode**, Chrome may still print a red **“WebSocket … failed”** line for an **old** socket while the **current** connection succeeds — check **Network → WS** for status **101** and incoming frames.\n\n## Usage\n\n### Production-style (`wss://`)\n\n```ts\nimport { ApexStreamClient } from \"@apexstream/client\";\n\nconst client = new ApexStreamClient({\n  url: \"wss://your-gateway.example.com/v1/ws\",\n  apiKey: \"<publishable key from dashboard>\",\n});\n\nclient.on(\"open\", () => {\n  console.log(\"connected\");\n  // publish only after the socket is OPEN (connect() is asynchronous)\n  client.publish(\"orders\", { kind: \"placed\", id: \"ord_123\" });\n});\nclient.on(\"close\", (ev) => console.log(\"closed\", ev.code, ev.reason));\nclient.on(\"error\", (ev) => console.error(\"socket error\", ev));\nclient.on(\"message\", (data) => console.log(\"raw frame\", data));\n\nconst unsubscribe = client.subscribe(\"orders\", (payload) => {\n  console.log(\"orders event\", payload);\n});\n\nclient.connect();\n\n// Later:\nunsubscribe();\nclient.disconnect();\n```\n\n### Vite: local `http://` + `ws://`, or LAN NodePort (same pattern as repo `examples/*/client`)\n\n```ts\nimport { ApexStreamClient } from \"@apexstream/client\";\n\nconst wsUrl = import.meta.env.VITE_APEXSTREAM_WS_URL!;\nconst apiKey = import.meta.env.VITE_APEXSTREAM_API_KEY!;\nconst allowInsecureTransport =\n  wsUrl.startsWith(\"ws://\") ||\n  import.meta.env.VITE_APEXSTREAM_ALLOW_INSECURE === \"1\" ||\n  import.meta.env.VITE_APEXSTREAM_ALLOW_INSECURE === \"true\";\n\nconst client = new ApexStreamClient({\n  url: wsUrl,\n  apiKey,\n  allowInsecureTransport,\n});\n\nclient.subscribe(\"metrics\", (payload, meta) => {\n  console.log(payload, meta?.reliableMessageId); // meta when extended realtime + reliable messaging\n});\n\nclient.connect();\n```\n\n**Variables:**\n\n- **`VITE_APEXSTREAM_WS_URL`** — gateway WebSocket URL (same rules as **`url`** above).\n- **`VITE_APEXSTREAM_API_KEY`** — dashboard key for that app.\n- **`VITE_APEXSTREAM_ALLOW_INSECURE`** — optional **`1`** / **`true`**: explicit “dev / no HTTPS” switch so **`allowInsecureTransport`** is true even if you prefer to set it manually; **`ws://`** in the URL already implies insecure transport for the SDK, but the flag documents local mode and helps when people copy `.env.example` first.\n\nProduction should use **`wss://`**; then both **`wsUrl.startsWith(\"ws://\")`** and the env flag should be unset / false.\n\n### Extended realtime (optional)\n\nWhen the deployment has **extended realtime** enabled on API + gateway, you can **replay** persisted channel history and **ack reliable** deliveries:\n\n```ts\nclient.subscribe(\"orders\", (_payload, meta) => {\n  if (meta?.reliableMessageId) {\n    client.reliableAck(meta.reliableMessageId);\n  }\n});\n\nclient.connect();\n\nclient.on(\"open\", () => {\n  client.replay(\"orders\", {\n    limit: 100,\n    fromTimestamp: new Date(Date.now() - 3600_000).toISOString(),\n  });\n});\n```\n\n`replay` must run **after** the socket is open. Requires server-side retention / extended features; see your ApexStream runbook.\n\n## Wire format (draft)\n\nMessages are JSON text frames.\n\n**Client → server**\n\n- Subscribe: `{ \"type\": \"subscribe\", \"channel\": \"orders\" }`\n- Unsubscribe: `{ \"type\": \"unsubscribe\", \"channel\": \"orders\" }`\n- Publish: `{ \"type\": \"publish\", \"channel\": \"orders\", \"payload\": { ... } }`\n- Replay (extended): `{ \"type\": \"replay\", \"channel\": \"orders\", \"payload\": { ... } }`\n- Reliable ack (extended): `{ \"type\": \"reliable_ack\", \"payload\": { \"message_id\": \"...\" } }`\n\n**Server → client**\n\n- Delivery: `{ \"type\": \"message\", \"channel\": \"orders\", \"payload\": { ... } }` (optional **`reliable_message_id`** on extended realtime)\n\nThe gateway authenticates the socket using **`api_key` on the WebSocket URL** (see **Configuration** above). Do not log the full URL after connect in production; use **`wss://`** outside localhost.\n\n## Build from source\n\nIn **[apexstream/client](https://github.com/apexstream/client)** (this package at the repo root):\n\n```bash\nnpm install\nnpm run build\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md"}