@nxisai/nxis 2.1.1

package/.github/workflows/deploy.yml

@@ -0,0 +1,110 @@
+name: Deploy nxis.js to S3 and GitHub Packages
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build project
+        env:
+          NXIS_API_HOST: ${{ vars.NXIS_API_HOST || secrets.NXIS_API_HOST }}
+        run: npx rollup --config rollup.config.js
+
+      - name: Configure AWS credentials
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
+          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+          aws-region: ${{ vars.AWS_REGION || secrets.AWS_REGION }}
+
+      - name: Deploy to S3
+        run: aws s3 cp build/nxis.js s3://nxis-ai-static/nxis.js
+
+  publish-npm:
+    needs: build-and-deploy
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js for GitHub Packages
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+          registry-url: 'https://npm.pkg.github.com'
+          scope: '@nxisai'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build SSR package
+        env:
+          NXIS_API_HOST: ${{ vars.NXIS_API_HOST || secrets.NXIS_API_HOST }}
+        run: |
+          npx rollup --config rollup.config.js --environment NXIS_API_HOST:$NXIS_API_HOST
+          npm run build:types
+
+      - name: Scope package for GitHub Packages
+        run: npm pkg set name='@nxisai/nxis'
+
+      - name: Publish to GitHub Packages
+        run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  publish-npmjs:
+    needs: publish-npm
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js for npm
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+          registry-url: 'https://registry.npmjs.org'
+          scope: '@nxisai'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build package
+        env:
+          NXIS_API_HOST: ${{ vars.NXIS_API_HOST || secrets.NXIS_API_HOST }}
+        run: |
+          npx rollup --config rollup.config.js --environment NXIS_API_HOST:$NXIS_API_HOST
+          npm run build:types
+
+      - name: Scope package for npm
+        run: npm pkg set name='@nxisai/nxis'
+
+      - name: Publish to npm
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/README.md

@@ -0,0 +1,401 @@
+# Nxis.js
+
+## Overview
+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.
+
+Nxis.js supports **both client-side (browser)** and **server-side rendering (SSR)** environments, making it compatible with modern web frameworks.
+
+## Supported Frameworks
+
+| Framework | Rendering | Method |
+|-----------|-----------|--------|
+| **Static HTML / WordPress / Shopify** | Client-side | `<script>` tag |
+| **Next.js** (App Router & Pages Router) | SSR / SSG | `NxisClient` |
+| **Nuxt 3** | SSR / SSG | `NxisClient` |
+| **Remix** | SSR | `NxisClient` |
+| **Astro** | SSR / SSG | `NxisClient` |
+| **SvelteKit** | SSR / SSG | `NxisClient` |
+| **Express / Node.js** | Server | `NxisClient` |
+
+## How It Works
+
+Nxis.js supports two integration paths — **client-side (browser)** and **server-side rendering (SSR)**.
+
+### Client-Side (Browser)
+
+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.
+2. **Request**: On execution, the script sends a request to the Nxis AI Proxy (`/v1/nxis:inject`) with the current page URI, referrer, and session context.
+3. **Validation & Retrieval**: The Proxy validates the JWT token, and retrieves JSON-LD structured data from the Structured Data Service.
+4. **Injection**: On success, `nxis.js` creates a `<script type="application/ld+json">` element and appends it to the document `<head>`.
+
+### Server-Side Rendering (SSR)
+
+1. **Initialize**: Your application creates a `NxisClient` with OAuth client credentials. Tokens are managed automatically.
+2. **Request**: At render time, the client calls the Nxis AI Proxy (`/v1/nxis:ssr`) with the page URI and a Bearer access token.
+3. **Validation & Retrieval**: The Proxy validates the token, authorizes the requesting domain, and retrieves the structured data.
+4. **Embedding**: The returned JSON-LD object is serialized directly into a `<script type="application/ld+json">` tag in the initial HTML response — visible to search engines, LLMs, and AI agents without requiring JavaScript execution.
+
+---
+
+## Client-Side Installation (Browser)
+
+Add the script tag to the head of your HTML document. Replace `${TOKEN}` with your Nxis JWT token.
+
+```html
+<script
+  type="text/javascript"
+  async
+  src="https://cdn.nxis.ai/nxis.js?token=${TOKEN}"
+  crossorigin="anonymous">
+</script>
+```
+
+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.
+
+This works with any static HTML page, CMS (WordPress, Shopify, Squarespace), or client-rendered SPA.
+
+---
+
+## Server-Side Rendering (SSR)
+
+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.
+
+**Why SSR matters:** While search engines like Google can render JavaScript, large language models and LLM-based agents do not consistently execute JavaScript when crawling web pages. If structured data is only injected client-side (via the browser `<script>` tag), LLMs and AI agents may never see it. SSR ensures that JSON-LD is embedded directly in the initial HTML response, making your structured data immediately visible to every consumer — from traditional search engine crawlers to LLM training pipelines and AI agents browsing on behalf of users.
+
+The SSR client uses **OAuth 2.0 client credentials** for authentication. Access tokens are managed automatically — cached in memory and refreshed before expiration.
+
+### Installation
+
+```bash
+npm install @nxisai/nxis
+```
+
+### Environment Setup
+
+Set these environment variables on your server:
+
+```bash
+NXIS_API_HOST=https://api.nxis.ai
+NXIS_CLIENT_ID=nxis_cid_...       # Your OAuth client ID
+NXIS_CLIENT_SECRET=nxis_sec_...   # Your OAuth client secret
+NXIS_SITE_ID=...                  # Your site identifier
+```
+
+### API Reference
+
+```typescript
+import { NxisClient } from '@nxisai/nxis/ssr';
+
+const nxis = new NxisClient({
+  clientId: string,       // OAuth client ID
+  clientSecret: string,   // OAuth client secret
+  tokenUrl?: string,      // Optional token endpoint URL (defaults to NXIS_TOKEN_URL env var)
+  scope?: string,         // Optional OAuth scope (defaults to "jsonld:read")
+  apiHost?: string,       // Optional API host override (defaults to NXIS_API_HOST env var)
+});
+
+const jsonLd: Record<string, unknown> = await nxis.getStructuredData({
+  uri: string,            // The full URI of the page being rendered
+  siteId: string,         // The site identifier
+  userAgent?: string,     // Optional User-Agent for bot detection
+});
+```
+
+Returns a `Promise<Record<string, unknown>>` — a JSON-LD object ready to be serialized into a `<script type="application/ld+json">` tag.
+
+### Token Lifecycle
+
+Access tokens are managed automatically by `NxisClient`:
+
+- **Lazy initialization**: No token is fetched until the first `getStructuredData` call.
+- **In-memory cache**: Tokens are cached and reused for subsequent requests.
+- **Auto-refresh**: Tokens are refreshed 60 seconds before expiration.
+- **Concurrency-safe**: Multiple concurrent requests during a refresh all await the same token fetch.
+
+---
+
+### Next.js (App Router)
+
+```tsx
+// app/page.tsx
+import { NxisClient } from '@nxisai/nxis/ssr';
+import { headers } from 'next/headers';
+
+const nxis = new NxisClient({
+  clientId: process.env.NXIS_CLIENT_ID!,
+  clientSecret: process.env.NXIS_CLIENT_SECRET!,
+});
+
+export default async function Page() {
+  const headersList = await headers();
+  const host = headersList.get('host') ?? 'localhost:3000';
+  const proto = headersList.get('x-forwarded-proto') ?? 'http';
+  const pageUri = `${proto}://${host}/`;
+
+  const jsonLd = await nxis.getStructuredData({
+    uri: pageUri,
+    siteId: process.env.NXIS_SITE_ID!,
+    userAgent: headersList.get('user-agent') ?? undefined,
+  });
+
+  return (
+    <>
+      <script
+        type="application/ld+json"
+        dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }}
+      />
+      <main>{/* page content */}</main>
+    </>
+  );
+}
+```
+
+### Next.js (Pages Router)
+
+```tsx
+// pages/index.tsx
+import { NxisClient } from '@nxisai/nxis/ssr';
+import Head from 'next/head';
+import { GetServerSideProps } from 'next';
+
+const nxis = new NxisClient({
+  clientId: process.env.NXIS_CLIENT_ID!,
+  clientSecret: process.env.NXIS_CLIENT_SECRET!,
+});
+
+export const getServerSideProps: GetServerSideProps = async (context) => {
+  const jsonLd = await nxis.getStructuredData({
+    uri: `https://yoursite.com${context.resolvedUrl}`,
+    siteId: process.env.NXIS_SITE_ID!,
+  });
+
+  return { props: { jsonLd } };
+};
+
+export default function Page({ jsonLd }: { jsonLd: Record<string, unknown> }) {
+  return (
+    <>
+      <Head>
+        <script
+          type="application/ld+json"
+          dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }}
+        />
+      </Head>
+      <main>{/* page content */}</main>
+    </>
+  );
+}
+```
+
+### Nuxt 3
+
+```html
+<!-- pages/index.vue -->
+<script setup lang="ts">
+import { NxisClient } from '@nxisai/nxis/ssr';
+
+const config = useRuntimeConfig();
+const nxis = new NxisClient({
+  clientId: config.nxisClientId,
+  clientSecret: config.nxisClientSecret,
+});
+
+const { data: jsonLd } = await useAsyncData('nxis-jsonld', () =>
+  nxis.getStructuredData({
+    uri: `https://yoursite.com${useRoute().fullPath}`,
+    siteId: config.nxisSiteId,
+  })
+);
+
+useHead({
+  script: [
+    {
+      type: 'application/ld+json',
+      innerHTML: JSON.stringify(jsonLd.value),
+    },
+  ],
+});
+</script>
+
+<template>
+  <main><!-- page content --></main>
+</template>
+```
+
+### Remix
+
+```tsx
+// app/routes/_index.tsx
+import { json, type LoaderFunctionArgs } from '@remix-run/node';
+import { useLoaderData } from '@remix-run/react';
+import { NxisClient } from '@nxisai/nxis/ssr';
+
+const nxis = new NxisClient({
+  clientId: process.env.NXIS_CLIENT_ID!,
+  clientSecret: process.env.NXIS_CLIENT_SECRET!,
+});
+
+export async function loader({ request }: LoaderFunctionArgs) {
+  const jsonLd = await nxis.getStructuredData({
+    uri: request.url,
+    siteId: process.env.NXIS_SITE_ID!,
+  });
+
+  return json({ jsonLd });
+}
+
+export default function Index() {
+  const { jsonLd } = useLoaderData<typeof loader>();
+
+  return (
+    <>
+      <script
+        type="application/ld+json"
+        dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }}
+      />
+      <main>{/* page content */}</main>
+    </>
+  );
+}
+```
+
+### Astro
+
+```astro
+---
+// src/pages/index.astro
+import { NxisClient } from '@nxisai/nxis/ssr';
+
+const nxis = new NxisClient({
+  clientId: import.meta.env.NXIS_CLIENT_ID,
+  clientSecret: import.meta.env.NXIS_CLIENT_SECRET,
+});
+
+const jsonLd = await nxis.getStructuredData({
+  uri: Astro.url.href,
+  siteId: import.meta.env.NXIS_SITE_ID,
+});
+---
+
+<html>
+  <head>
+    <script type="application/ld+json" set:html={JSON.stringify(jsonLd)} />
+  </head>
+  <body>
+    <!-- page content -->
+  </body>
+</html>
+```
+
+### SvelteKit
+
+```typescript
+// src/routes/+page.server.ts
+import { NxisClient } from '@nxisai/nxis/ssr';
+import { env } from '$env/static/private';
+import type { PageServerLoad } from './$types';
+
+const nxis = new NxisClient({
+  clientId: env.NXIS_CLIENT_ID,
+  clientSecret: env.NXIS_CLIENT_SECRET,
+});
+
+export const load: PageServerLoad = async ({ url }) => {
+  const jsonLd = await nxis.getStructuredData({
+    uri: url.href,
+    siteId: env.NXIS_SITE_ID,
+  });
+
+  return { jsonLd };
+};
+```
+
+```html
+<!-- src/routes/+page.svelte -->
+<script lang="ts">
+  export let data;
+</script>
+
+<svelte:head>
+  {@html `<script type="application/ld+json">${JSON.stringify(data.jsonLd)}</script>`}
+</svelte:head>
+
+<main><!-- page content --></main>
+```
+
+### Express / Node.js
+
+```javascript
+const express = require('express');
+const { NxisClient } = require('@nxisai/nxis');
+
+const nxis = new NxisClient({
+  clientId: process.env.NXIS_CLIENT_ID,
+  clientSecret: process.env.NXIS_CLIENT_SECRET,
+});
+
+const app = express();
+
+app.get('*', async (req, res) => {
+  const jsonLd = await nxis.getStructuredData({
+    uri: `https://yoursite.com${req.originalUrl}`,
+    siteId: process.env.NXIS_SITE_ID,
+  });
+
+  res.send(`
+    <!DOCTYPE html>
+    <html>
+      <head>
+        <script type="application/ld+json">${JSON.stringify(jsonLd)}</script>
+      </head>
+      <body><!-- page content --></body>
+    </html>
+  `);
+});
+
+app.listen(3000);
+```
+
+---
+
+## Adding Nxis SSR with Claude Code
+
+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:
+
+```
+Install the @nxisai/nxis package and add server-side structured data injection to my
+Next.js App Router project. Here's what I need:
+
+1. Install the @nxisai/nxis npm package
+2. Add NXIS_API_HOST, NXIS_CLIENT_ID, and NXIS_CLIENT_SECRET to my .env.local
+3. Create a shared NxisClient instance using `NxisClient` from `@nxisai/nxis/ssr`
+   initialized with the OAuth client credentials from environment variables
+4. Update my root layout (or individual pages) to:
+   - Import `headers` from `next/headers`
+   - Derive the page URI from the incoming request's `host` and
+     `x-forwarded-proto` headers
+   - Pass the `user-agent` header for bot detection
+   - Inject the returned JSON-LD as a <script type="application/ld+json"> tag
+
+Here's the API reference:
+
+import { NxisClient } from '@nxisai/nxis/ssr';
+
+const nxis = new NxisClient({
+  clientId: process.env.NXIS_CLIENT_ID!,
+  clientSecret: process.env.NXIS_CLIENT_SECRET!,
+});
+
+const jsonLd: Record<string, unknown> = await nxis.getStructuredData({
+  uri: pageUri,
+  siteId: process.env.NXIS_SITE_ID!,
+  userAgent: headersList.get('user-agent') ?? undefined,
+});
+
+Tokens are managed automatically — no manual token handling needed.
+Make sure JSON-LD is present in the initial HTML response so it's visible
+to search engines, LLMs, and AI agents that don't render JavaScript.
+```
+
+This will guide Claude Code to install the package, configure environment variables, and wire up SSR structured data injection across your pages.
+

package/bin/deploy.sh

@@ -0,0 +1,2 @@
+#!/usr/bin/env bash
+aws s3 cp build/nxis.js s3://nxis-ai-static/nxis.js