@nxisai/nxis 2.2.1 → 2.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +143 -68
  2. package/package.json +4 -2
package/README.md CHANGED
@@ -6,13 +6,79 @@
6
6
 
7
7
  # Nxis.js
8
8
 
9
+ Structured data for the AI era — inject JSON-LD so search engines, LLMs, and AI agents can understand your pages, and use WebMCP to make those pages actionable by agents.
9
10
 
10
- ## Overview
11
- Nxis.js is a lightweight JavaScript client designed to integrate with the Nxis AI platform. It dynamically injects JSON-LD structured data into web pages to enhance visibility for search engines, AI agents, and large language models (LLMs). By embedding this structured data, Nxis.js helps transform standard web content into semantic data that is easily discoverable and consumable across the modern search and AI ecosystem.
11
+ [![npm version](https://img.shields.io/npm/v/@nxisai/nxis.svg?color=blue)](https://www.npmjs.com/package/@nxisai/nxis) [![npm downloads](https://img.shields.io/npm/dm/@nxisai/nxis.svg)](https://www.npmjs.com/package/@nxisai/nxis) [![license](https://img.shields.io/npm/l/@nxisai/nxis.svg)](https://github.com/nxisai/nxis-js/blob/main/LICENSE)
12
12
 
13
- Nxis.js supports **both client-side (browser)** and **server-side rendering (SSR)** environments, making it compatible with modern web frameworks.
13
+ Nxis.js is a lightweight JavaScript client for the [Nxis AI](https://nxis.ai) platform. It fetches AI-optimized JSON-LD structured data and injects it into your pages, turning ordinary web content into semantic data that's discoverable across the modern search and AI ecosystem. It also makes your pages **actionable by AI agents** — via [WebMCP](#webmcp--ai-agent-tool-registration), Nxis turns your existing forms into tools that agents can discover and invoke directly in the browser. It runs in both **browser** and **server-side rendering (SSR)** environments.
14
14
 
15
- > **Getting Started:** Create an account at [www.nxis.ai](https://www.nxis.ai) to get your API credentials and start integrating structured data into your site.
15
+ > **Getting started:** Create an account at [www.nxis.ai](https://www.nxis.ai) to get your API credentials.
16
+
17
+ ## Features
18
+
19
+ - 🌐 **Browser & SSR** — drop-in CDN `<script>` tag or a typed `NxisClient` for server-rendered apps
20
+ - 🔍 **AI-ready structured data** — JSON-LD visible to search engines, LLMs, and AI agents
21
+ - 🔑 **Automatic OAuth** — access tokens are fetched, cached, and refreshed for you
22
+ - 🤖 **WebMCP tools** — optionally expose your forms as tools AI agents can call (Chrome 138+)
23
+ - 📦 **Zero-config CDN** — static sites need no build step or local JavaScript
24
+ - 🧩 **Framework guides** — Next.js, Nuxt, Remix, Astro, SvelteKit, Express, and more
25
+
26
+ ## Table of Contents
27
+
28
+ - [Installation](#installation)
29
+ - [Basic Usage](#basic-usage)
30
+ - [How It Works](#how-it-works)
31
+ - [Server-Side Rendering (SSR)](#server-side-rendering-ssr)
32
+ - [Framework Guides](#framework-guides)
33
+ - [WebMCP — AI Agent Tool Registration](#webmcp--ai-agent-tool-registration)
34
+
35
+ ## Installation
36
+
37
+ **Browser (CDN)** — no install required. Add the script to your `<head>` (replace `${TOKEN}` with your Nxis JWT token):
38
+
39
+ ```html
40
+ <script
41
+ type="text/javascript"
42
+ async
43
+ src="https://cdn.nxis.ai/nxis.js?token=${TOKEN}"
44
+ crossorigin="anonymous">
45
+ </script>
46
+ ```
47
+
48
+ **Server / SSR (npm):**
49
+
50
+ ```bash
51
+ npm install @nxisai/nxis
52
+ ```
53
+
54
+ ## Basic Usage
55
+
56
+ ### Browser
57
+
58
+ The CDN script is all you need. The JWT token carries your organization and site configuration, so the script automatically fetches your page's JSON-LD and injects it as a `<script type="application/ld+json">` tag — no data attributes, no extra code. Works with static HTML, WordPress, Shopify, Squarespace, or any client-rendered SPA.
59
+
60
+ ### Server-Side Rendering
61
+
62
+ Create a `NxisClient` once, then fetch JSON-LD at render time and embed it in your HTML:
63
+
64
+ ```typescript
65
+ import { NxisClient } from '@nxisai/nxis/ssr';
66
+
67
+ const nxis = new NxisClient({
68
+ clientId: process.env.NXIS_CLIENT_ID!,
69
+ clientSecret: process.env.NXIS_CLIENT_SECRET!,
70
+ });
71
+
72
+ const jsonLd = await nxis.getStructuredData({
73
+ uri: 'https://yoursite.com/',
74
+ siteId: process.env.NXIS_SITE_ID!,
75
+ });
76
+
77
+ // Serialize into your server-rendered HTML:
78
+ // <script type="application/ld+json">${JSON.stringify(jsonLd)}</script>
79
+ ```
80
+
81
+ Tokens are managed automatically — cached in memory and refreshed before expiration. See [Server-Side Rendering (SSR)](#server-side-rendering-ssr) for the full API and [Framework Guides](#framework-guides) for copy-paste setups.
16
82
 
17
83
  ## Supported Frameworks
18
84
 
@@ -30,14 +96,14 @@ Nxis.js supports **both client-side (browser)** and **server-side rendering (SSR
30
96
 
31
97
  Nxis.js supports two integration paths — **client-side (browser)** and **server-side rendering (SSR)**.
32
98
 
33
- ### Client-Side (Browser)
99
+ ### In the Browser
34
100
 
35
101
  1. **Script Loading**: Your page loads `nxis.js` via a `<script>` tag from the Nxis CDN with a signed Nxis JWT token as a query parameter.
36
102
  2. **Request**: On execution, the script sends a request to the Nxis AI Proxy (`/v1/nxis:inject`) with the current page URI and referrer.
37
103
  3. **Validation & Retrieval**: The Proxy validates the JWT token, and retrieves JSON-LD structured data from the Structured Data Service.
38
104
  4. **Injection**: On success, `nxis.js` creates a `<script type="application/ld+json">` element and appends it to the document `<head>`.
39
105
 
40
- ### Server-Side Rendering (SSR)
106
+ ### On the Server (SSR)
41
107
 
42
108
  1. **Initialize**: Your application creates a `NxisClient` with OAuth client credentials. Tokens are managed automatically.
43
109
  2. **Request**: At render time, the client calls the Nxis AI Proxy (`/v1/nxis:ssr`) with the page URI and a Bearer access token.
@@ -46,25 +112,6 @@ Nxis.js supports two integration paths — **client-side (browser)** and **serve
46
112
 
47
113
  ---
48
114
 
49
- ## Client-Side Installation (Browser)
50
-
51
- Add the script tag to the head of your HTML document. Replace `${TOKEN}` with your Nxis JWT token.
52
-
53
- ```html
54
- <script
55
- type="text/javascript"
56
- async
57
- src="https://cdn.nxis.ai/nxis.js?token=${TOKEN}"
58
- crossorigin="anonymous">
59
- </script>
60
- ```
61
-
62
- The JWT token contains your organization and site configuration. No additional data attributes are needed — the CDN extracts everything from the token claims and injects it into the script automatically.
63
-
64
- This works with any static HTML page, CMS (WordPress, Shopify, Squarespace), or client-rendered SPA.
65
-
66
- ---
67
-
68
115
  ## Server-Side Rendering (SSR)
69
116
 
70
117
  For SSR frameworks, Nxis.js provides a `NxisClient` class that fetches JSON-LD at render time so structured data is present in the initial HTML response — no client-side JavaScript required.
@@ -123,6 +170,10 @@ Access tokens are managed automatically by `NxisClient`:
123
170
 
124
171
  ---
125
172
 
173
+ ## Framework Guides
174
+
175
+ Copy-paste setups for popular SSR/SSG frameworks. Each fetches JSON-LD at render time and embeds it in the initial HTML response.
176
+
126
177
  ### Next.js (App Router)
127
178
 
128
179
  ```tsx
@@ -365,6 +416,47 @@ app.get('*', async (req, res) => {
365
416
  app.listen(3000);
366
417
  ```
367
418
 
419
+ ### Adding Nxis SSR with Claude Code
420
+
421
+ You can use [Claude Code](https://docs.anthropic.com/en/docs/claude-code) to automatically add Nxis SSR to an existing Next.js project. Paste the following prompt into Claude Code from your project's root directory:
422
+
423
+ ```
424
+ Install the @nxisai/nxis package and add server-side structured data injection to my
425
+ Next.js App Router project. Here's what I need:
426
+
427
+ 1. Install the @nxisai/nxis npm package
428
+ 2. Add NXIS_API_HOST, NXIS_CLIENT_ID, and NXIS_CLIENT_SECRET to my .env.local
429
+ 3. Create a shared NxisClient instance using `NxisClient` from `@nxisai/nxis/ssr`
430
+ initialized with the OAuth client credentials from environment variables
431
+ 4. Update my root layout (or individual pages) to:
432
+ - Import `headers` from `next/headers`
433
+ - Derive the page URI from the incoming request's `host` and
434
+ `x-forwarded-proto` headers
435
+ - Pass the `user-agent` header for bot detection
436
+ - Inject the returned JSON-LD as a <script type="application/ld+json"> tag
437
+
438
+ Here's the API reference:
439
+
440
+ import { NxisClient } from '@nxisai/nxis/ssr';
441
+
442
+ const nxis = new NxisClient({
443
+ clientId: process.env.NXIS_CLIENT_ID!,
444
+ clientSecret: process.env.NXIS_CLIENT_SECRET!,
445
+ });
446
+
447
+ const jsonLd: Record<string, unknown> = await nxis.getStructuredData({
448
+ uri: pageUri,
449
+ siteId: process.env.NXIS_SITE_ID!,
450
+ userAgent: headersList.get('user-agent') ?? undefined,
451
+ });
452
+
453
+ Tokens are managed automatically — no manual token handling needed.
454
+ Make sure JSON-LD is present in the initial HTML response so it's visible
455
+ to search engines, LLMs, and AI agents that don't render JavaScript.
456
+ ```
457
+
458
+ This will guide Claude Code to install the package, configure environment variables, and wire up SSR structured data injection across your pages.
459
+
368
460
  ---
369
461
 
370
462
  ## WebMCP — AI Agent Tool Registration
@@ -479,6 +571,32 @@ const cleanup = registerActions();
479
571
  const cleanup = registerActions({ observe: false });
480
572
  ```
481
573
 
574
+ ### Using WebMCP with SSR Frameworks
575
+
576
+ WebMCP is a **browser-only** feature — it depends on the live DOM and `document.modelContext`. It cannot run during the server render: in SSR/SSG environments (`getServerSideProps`, server components, loaders, the Nuxt/SvelteKit server pass) `registerActions()` detects there is no `document` and safely no-ops.
577
+
578
+ That's by design and composes with SSR: your server render injects the JSON-LD (via `NxisClient.getStructuredData`), and `registerActions()` then reads those same `<script type="application/ld+json">` tags **in the browser after hydration**. So you can absolutely use WebMCP in an SSR framework — you just call it from a client-only lifecycle hook.
579
+
580
+ **Next.js (App Router)** — a client component:
581
+
582
+ ```tsx
583
+ 'use client';
584
+ import { useEffect } from 'react';
585
+ import { registerActions } from '@nxisai/nxis/webmcp';
586
+
587
+ export function NxisWebMCP() {
588
+ useEffect(() => {
589
+ const cleanup = registerActions(); // runs only in the browser
590
+ return cleanup; // unregister on unmount
591
+ }, []);
592
+ return null;
593
+ }
594
+ ```
595
+
596
+ Render `<NxisWebMCP />` once in your layout. Equivalent hooks for other frameworks: **Nuxt** `onMounted()` (or wrap in `<ClientOnly>`), **Remix** `useEffect`, **SvelteKit** `onMount`.
597
+
598
+ > **Note:** The `@nxisai/nxis/webmcp` subpath ships as an ES module that is safe to import on the server (it no-ops without a DOM). A CommonJS `require()` of this subpath is not supported — import it with ESM `import` syntax.
599
+
482
600
  ### Supported Action Types
483
601
 
484
602
  The backend classifier maps forms to schema.org Action subtypes:
@@ -549,46 +667,3 @@ import type {
549
667
  } from '@nxisai/nxis/webmcp';
550
668
  ```
551
669
 
552
- ---
553
-
554
- ## Adding Nxis SSR with Claude Code
555
-
556
- You can use [Claude Code](https://docs.anthropic.com/en/docs/claude-code) to automatically add Nxis SSR to an existing Next.js project. Paste the following prompt into Claude Code from your project's root directory:
557
-
558
- ```
559
- Install the @nxisai/nxis package and add server-side structured data injection to my
560
- Next.js App Router project. Here's what I need:
561
-
562
- 1. Install the @nxisai/nxis npm package
563
- 2. Add NXIS_API_HOST, NXIS_CLIENT_ID, and NXIS_CLIENT_SECRET to my .env.local
564
- 3. Create a shared NxisClient instance using `NxisClient` from `@nxisai/nxis/ssr`
565
- initialized with the OAuth client credentials from environment variables
566
- 4. Update my root layout (or individual pages) to:
567
- - Import `headers` from `next/headers`
568
- - Derive the page URI from the incoming request's `host` and
569
- `x-forwarded-proto` headers
570
- - Pass the `user-agent` header for bot detection
571
- - Inject the returned JSON-LD as a <script type="application/ld+json"> tag
572
-
573
- Here's the API reference:
574
-
575
- import { NxisClient } from '@nxisai/nxis/ssr';
576
-
577
- const nxis = new NxisClient({
578
- clientId: process.env.NXIS_CLIENT_ID!,
579
- clientSecret: process.env.NXIS_CLIENT_SECRET!,
580
- });
581
-
582
- const jsonLd: Record<string, unknown> = await nxis.getStructuredData({
583
- uri: pageUri,
584
- siteId: process.env.NXIS_SITE_ID!,
585
- userAgent: headersList.get('user-agent') ?? undefined,
586
- });
587
-
588
- Tokens are managed automatically — no manual token handling needed.
589
- Make sure JSON-LD is present in the initial HTML response so it's visible
590
- to search engines, LLMs, and AI agents that don't render JavaScript.
591
- ```
592
-
593
- This will guide Claude Code to install the package, configure environment variables, and wire up SSR structured data injection across your pages.
594
-
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nxisai/nxis",
3
- "version": "2.2.1",
3
+ "version": "2.2.2",
4
4
  "description": "Javascript client for Nxis AI",
5
5
  "main": "build/index.cjs.js",
6
6
  "module": "build/index.esm.js",
@@ -19,8 +19,10 @@
19
19
  "types": "./build/index.d.ts"
20
20
  },
21
21
  "./webmcp": {
22
+ "types": "./build/webmcp.d.ts",
22
23
  "browser": "./build/webmcp.js",
23
- "types": "./build/webmcp.d.ts"
24
+ "import": "./build/webmcp.js",
25
+ "default": "./build/webmcp.js"
24
26
  }
25
27
  },
26
28
  "scripts": {