@nxisai/nxis 2.1.1

package/docs/ssr.md

@@ -0,0 +1,606 @@
+# 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.
+
+## Supported Frameworks
+
+| Framework | Rendering | Method |
+|-----------|-----------|--------|
+| **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` |
+| **Django / Rails / Laravel / Go / Any** | SSR / SSG | `curl` / HTTP API |
+
+## How It Works
+
+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 array 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.
+
+### Sequence Diagram
+
+```mermaid
+sequenceDiagram
+    participant Crawler as Search Engine / LLM / Agent
+    participant App as SSR Application
+    participant Nxis as NxisClient
+    participant Auth as OAuth Token Endpoint
+    participant Proxy as Nxis AI Proxy
+    participant Service as Structured Data Service
+
+    Crawler->>App: Request Page
+    App->>Nxis: getStructuredData with uri, userAgent
+    alt Token cached & valid
+        Note over Nxis: Use cached token
+    else Token expired or missing
+        Nxis->>Auth: POST /v1/oauth/token (client_credentials)
+        Auth-->>Nxis: access_token + expires_in
+    end
+    Nxis->>Proxy: GET /v1/nxis:ssr with Bearer token and User-Agent
+    Proxy->>Service: Authorize & Fetch Data
+    alt Valid Access & Data Found
+        Service-->>Proxy: Returns JSON-LD
+        Proxy-->>Nxis: 200 OK (JSON-LD Data)
+        Nxis-->>App: Returns object array
+        App->>App: Embed JSON-LD in HTML
+        App-->>Crawler: Full HTML with structured data
+    else Invalid or No Data
+        Service-->>Proxy: Error / Empty
+        Proxy-->>Nxis: Error
+        Nxis-->>App: Throws Error
+        App-->>Crawler: HTML without structured data
+    end
+```
+
+---
+
+## Getting Started
+
+### 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_TOKEN_URL=https://authorization.nxis.ai/v1/oauth/token  # Optional, this is the default
+```
+
+### 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: object[] = 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<object[]>` — the JSON-LD data array ready to be serialized into a `<script type="application/ld+json">` tag.
+
+### Token Lifecycle
+
+The SSR client uses **OAuth 2.0 client credentials** for authentication. 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.
+
+---
+
+## Framework Examples
+
+### 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: object[] }) {
+  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);
+```
+
+---
+
+## cURL / HTTP API (Django, Rails, Laravel, Go, etc.)
+
+If you're using a non-JavaScript/TypeScript framework, you can call the Nxis SSR API directly over HTTP. The flow mirrors what `NxisClient` does internally:
+
+1. **Obtain an access token** via the OAuth 2.0 client credentials grant.
+2. **Fetch structured data** from the `/v1/nxis:ssr` endpoint using the Bearer token.
+
+### Step 1 — Get an access token
+
+```bash
+curl -s -X POST https://authorization.nxis.ai/v1/oauth/token \
+  -H "Content-Type: application/x-www-form-urlencoded" \
+  -d "grant_type=client_credentials" \
+  -d "client_id=${NXIS_CLIENT_ID}" \
+  -d "client_secret=${NXIS_CLIENT_SECRET}" \
+  -d "scope=jsonld:read"
+```
+
+Response:
+
+```json
+{
+  "access_token": "eyJhbGciOi...",
+  "token_type": "Bearer",
+  "expires_in": 3600,
+  "scope": "jsonld:read"
+}
+```
+
+> **Token caching:** Access tokens are valid for `expires_in` seconds. Cache the token and reuse it across requests — refresh it when it nears expiration.
+
+### Step 2 — Fetch structured data
+
+```bash
+curl -s "https://api.nxis.ai/v1/nxis:ssr?uri=https://yoursite.com/page&site_id=${NXIS_SITE_ID}" \
+  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
+  -H "User-Agent: Googlebot/2.1"
+```
+
+Response:
+
+```json
+{
+  "data": [
+    {
+      "@context": "https://schema.org",
+      "@type": "WebPage",
+      "name": "Example Page",
+      "url": "https://yoursite.com/page"
+    }
+  ]
+}
+```
+
+### Combined one-liner
+
+Fetch a token and retrieve structured data in a single pipeline:
+
+```bash
+ACCESS_TOKEN=$(curl -s -X POST https://authorization.nxis.ai/v1/oauth/token \
+  -H "Content-Type: application/x-www-form-urlencoded" \
+  -d "grant_type=client_credentials" \
+  -d "client_id=${NXIS_CLIENT_ID}" \
+  -d "client_secret=${NXIS_CLIENT_SECRET}" \
+  -d "scope=jsonld:read" | jq -r '.access_token') && \
+curl -s "https://api.nxis.ai/v1/nxis:ssr?uri=https://yoursite.com/page&site_id=${NXIS_SITE_ID}" \
+  -H "Authorization: Bearer ${ACCESS_TOKEN}" | jq '.data'
+```
+
+### Language Examples
+
+<details>
+<summary><strong>Python (Django, Flask, FastAPI)</strong></summary>
+
+```python
+import requests
+
+# Step 1: Get access token (cache this — valid for `expires_in` seconds)
+token_resp = requests.post(
+    "https://authorization.nxis.ai/v1/oauth/token",
+    data={
+        "grant_type": "client_credentials",
+        "client_id": NXIS_CLIENT_ID,
+        "client_secret": NXIS_CLIENT_SECRET,
+        "scope": "jsonld:read",
+    },
+)
+access_token = token_resp.json()["access_token"]
+
+# Step 2: Fetch structured data
+ssr_resp = requests.get(
+    "https://api.nxis.ai/v1/nxis:ssr",
+    params={"uri": page_url, "site_id": NXIS_SITE_ID},
+    headers={
+        "Authorization": f"Bearer {access_token}",
+        "User-Agent": request.META.get("HTTP_USER_AGENT", ""),
+    },
+)
+json_ld = ssr_resp.json()["data"]
+
+# Inject into your template as:
+# <script type="application/ld+json">{{ json_ld|tojson }}</script>
+```
+
+</details>
+
+<details>
+<summary><strong>Ruby (Rails, Sinatra)</strong></summary>
+
+```ruby
+require 'net/http'
+require 'json'
+
+# Step 1: Get access token
+token_uri = URI("https://authorization.nxis.ai/v1/oauth/token")
+token_resp = Net::HTTP.post_form(token_uri, {
+  grant_type: "client_credentials",
+  client_id: ENV["NXIS_CLIENT_ID"],
+  client_secret: ENV["NXIS_CLIENT_SECRET"],
+  scope: "jsonld:read"
+})
+access_token = JSON.parse(token_resp.body)["access_token"]
+
+# Step 2: Fetch structured data
+ssr_uri = URI("https://api.nxis.ai/v1/nxis:ssr")
+ssr_uri.query = URI.encode_www_form(uri: page_url, site_id: ENV["NXIS_SITE_ID"])
+ssr_req = Net::HTTP::Get.new(ssr_uri)
+ssr_req["Authorization"] = "Bearer #{access_token}"
+ssr_req["User-Agent"] = request.user_agent
+
+ssr_resp = Net::HTTP.start(ssr_uri.hostname, ssr_uri.port, use_ssl: true) { |http| http.request(ssr_req) }
+json_ld = JSON.parse(ssr_resp.body)["data"]
+
+# In your ERB template:
+# <script type="application/ld+json"><%= json_ld.to_json %></script>
+```
+
+</details>
+
+<details>
+<summary><strong>Go</strong></summary>
+
+```go
+package main
+
+import (
+    "encoding/json"
+    "fmt"
+    "net/http"
+    "net/url"
+    "strings"
+)
+
+func getAccessToken(clientID, clientSecret string) (string, error) {
+    data := url.Values{
+        "grant_type":    {"client_credentials"},
+        "client_id":     {clientID},
+        "client_secret": {clientSecret},
+        "scope":         {"jsonld:read"},
+    }
+    resp, err := http.Post(
+        "https://authorization.nxis.ai/v1/oauth/token",
+        "application/x-www-form-urlencoded",
+        strings.NewReader(data.Encode()),
+    )
+    if err != nil {
+        return "", err
+    }
+    defer resp.Body.Close()
+
+    var result struct {
+        AccessToken string `json:"access_token"`
+    }
+    json.NewDecoder(resp.Body).Decode(&result)
+    return result.AccessToken, nil
+}
+
+func getStructuredData(token, pageURL, siteID, userAgent string) ([]interface{}, error) {
+    endpoint := fmt.Sprintf(
+        "https://api.nxis.ai/v1/nxis:ssr?uri=%s&site_id=%s",
+        url.QueryEscape(pageURL), url.QueryEscape(siteID),
+    )
+    req, _ := http.NewRequest("GET", endpoint, nil)
+    req.Header.Set("Authorization", "Bearer "+token)
+    if userAgent != "" {
+        req.Header.Set("User-Agent", userAgent)
+    }
+
+    resp, err := http.DefaultClient.Do(req)
+    if err != nil {
+        return nil, err
+    }
+    defer resp.Body.Close()
+
+    var result struct {
+        Data []interface{} `json:"data"`
+    }
+    json.NewDecoder(resp.Body).Decode(&result)
+    return result.Data, nil
+}
+```
+
+</details>
+
+---
+
+## 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: object[] = 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/nxisbucket.json

@@ -0,0 +1,16 @@
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Sid": "AddPerm",
+      "Effect": "Allow",
+      "Principal": "*",
+      "Action": [
+        "s3:GetObject"
+      ],
+      "Resource": [
+        "arn:aws:s3:::nxis-static/*"
+      ]
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@nxisai/nxis",
+  "version": "2.1.1",
+  "description": "Javascript client for Nxis AI",
+  "main": "build/index.cjs.js",
+  "module": "build/index.esm.js",
+  "browser": "build/nxis.js",
+  "types": "build/index.d.ts",
+  "exports": {
+    ".": {
+      "browser": "./build/nxis.js",
+      "import": "./build/index.esm.js",
+      "require": "./build/index.cjs.js",
+      "types": "./build/index.d.ts"
+    },
+    "./ssr": {
+      "import": "./build/index.esm.js",
+      "require": "./build/index.cjs.js",
+      "types": "./build/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build:types": "tsc --declaration --emitDeclarationOnly --outDir build --target es2018 --skipLibCheck --moduleResolution node --esModuleInterop src/index.ts src/server.ts src/core.ts src/api.ts src/auth.ts",
+    "build": "source .env && npx rollup --config rollup.config.js --environment NXIS_API_HOST:$NXIS_API_HOST && npm run build:types",
+    "build:dev": "source .env && npx rollup --config rollup.config.js --environment NXIS_API_HOST:$NXIS_API_HOST && npm run build:types",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:nxisai/nxis-js.git"
+  },
+  "author": "Reggie McCray",
+  "license": "ISC",
+  "devDependencies": {
+    "@rollup/plugin-node-resolve": "^13.0.6",
+    "@rollup/plugin-terser": "^0.4.4",
+    "@rollup/plugin-typescript": "^8.2.5",
+    "@types/google.analytics": "0.0.42",
+    "@types/uuid": "^8.3.4",
+    "rollup": "^2.58.0",
+    "rollup-plugin-inject-process-env": "^1.3.1",
+    "rollup-plugin-uglify": "^4.0.0"
+  },
+  "dependencies": {
+    "tslib": "^2.3.1",
+    "typescript": "^4.4.3",
+    "uuid": "^14.0.0",
+    "web-vitals": "^2.1.2"
+  },
+  "overrides": {
+    "serialize-javascript": "^7.0.5"
+  }
+}