@nxisai/nxis 2.1.1

package/rollup.config.js

@@ -0,0 +1,50 @@
+import typescript from "@rollup/plugin-typescript";
+import terser from "@rollup/plugin-terser";
+import resolve from "@rollup/plugin-node-resolve";
+import injectProcessEnv from "rollup-plugin-inject-process-env";
+
+// Browser bundle — self-executing IIFE with NXIS_API_HOST baked in
+const browserConfig = {
+  input: "src/client.ts",
+  output: {
+    file: "build/nxis.js",
+    format: "es",
+  },
+  plugins: [
+    resolve({
+      customResolveOptions: {
+        moduleDirectory: "node_modules",
+      },
+    }),
+    typescript({ declaration: false }),
+    injectProcessEnv({ NXIS_API_HOST: process.env.NXIS_API_HOST }),
+    terser(),
+  ],
+};
+
+// SSR bundle — ESM + CJS for Node.js / SSR frameworks
+const ssrConfig = {
+  input: "src/index.ts",
+  output: [
+    {
+      file: "build/index.esm.js",
+      format: "es",
+    },
+    {
+      file: "build/index.cjs.js",
+      format: "cjs",
+    },
+  ],
+  plugins: [
+    typescript({ declaration: false }),
+    resolve({
+      customResolveOptions: {
+        moduleDirectory: "node_modules",
+      },
+    }),
+  ],
+  // Mark uuid as external for the SSR bundle so consumers use their own copy
+  external: ["uuid"],
+};
+
+export default [browserConfig, ssrConfig];

package/src/api.ts

@@ -0,0 +1,281 @@
+/**
+ * A URL object representing an HTTP or HTTPS URI.
+ *
+ * @remarks
+ * Used as the canonical type for page URIs throughout the client-side request path.
+ */
+export type HttpUri = URL
+
+/**
+ * A wrapper around an optional string identifier.
+ *
+ * @remarks
+ * Used to represent entity IDs (organization, site, resource, etc.) that may
+ * or may not be present in a given context.
+ */
+export type Uid = {
+  /** The string identifier value, or `null` if not set. */
+  value: string | null
+}
+
+/**
+ * Makes a type `T` nullable — allowing `null` or `undefined` in addition to `T`.
+ */
+export type Nullable<T> = T | null | undefined;
+
+/**
+ * Configuration injected by the Nxis CDN into the browser script.
+ *
+ * @remarks
+ * The CDN extracts these values from the JWT token's claims and writes them
+ * into `window.__NXIS_CONFIG__` before the client script executes.
+ */
+export type NxisConfig = {
+  /** The organization identifier. */
+  org_id: string
+  /** The site identifier within the organization. */
+  site_id: string
+  /** The subscription identifier used for quota and entitlement checks. */
+  sub_id: string
+}
+
+/**
+ * Parameters for a client-side structured data request sent to the
+ * `/v1/nxis:inject` endpoint.
+ */
+export type StructuredDataRequest = {
+  /** The organization that owns the site. */
+  organization_id: Nullable<Uid>
+  /** The site the page belongs to. */
+  site_id: Nullable<Uid>
+  /** The full URI of the page being enhanced. */
+  uri: HttpUri
+  /** The `document.referrer` value, if available. */
+  referrer?: string
+  /** A client-generated session ID for request correlation. */
+  session?: string
+}
+
+/**
+ * The response body returned by both the `/v1/nxis:inject` and `/v1/nxis:ssr`
+ * endpoints on success.
+ *
+ * @remarks
+ * The `data` field corresponds to a `google.protobuf.Struct` in the proto
+ * definition, which serializes as a flat JSON object over HTTP transcoding.
+ */
+export type StructuredDataResponse = {
+  /** A JSON-LD structured data object ready for injection into the page. */
+  data: Record<string, unknown>
+}
+
+/**
+ * A non-fatal warning indicating no structured data was found for a page.
+ *
+ * @remarks
+ * Thrown when the proxy returns a 200 response with an empty `data` object.
+ * Callers can catch this specifically to distinguish "no data" from actual errors.
+ */
+export class NxisWarning extends Error {
+  constructor(msg: string) {
+    super(msg);
+    // Set the prototype explicitly.
+    Object.setPrototypeOf(this, NxisWarning.prototype);
+  }
+}
+
+
+/**
+ * Configuration for initializing a {@link NxisClient} instance.
+ *
+ * @remarks
+ * Used to create a client that automatically manages OAuth tokens and
+ * fetches structured data from the Nxis AI Proxy.
+ *
+ * @example
+ * ```typescript
+ * const nxis = new NxisClient({
+ *   clientId: process.env.NXIS_CLIENT_ID!,
+ *   clientSecret: process.env.NXIS_CLIENT_SECRET!,
+ * });
+ * ```
+ */
+export type NxisClientConfig = {
+  /** OAuth client ID (format: `nxis_cid_[a-zA-Z0-9]{16}`). */
+  clientId: string;
+  /** OAuth client secret (format: `nxis_sec_[a-zA-Z0-9]{32}`). */
+  clientSecret: string;
+  /**
+   * Override for the OAuth token endpoint URL.
+   *
+   * @defaultValue Falls back to `NXIS_TOKEN_URL` env var, then `"https://authorization.nxis.ai/v1/oauth/token"`.
+   */
+  tokenUrl?: string;
+  /**
+   * OAuth scope to request.
+   *
+   * @defaultValue `"jsonld:read"`
+   */
+  scope?: string;
+  /**
+   * Override for the Nxis API host URL.
+   *
+   * @defaultValue Falls back to the `NXIS_API_HOST` environment variable.
+   */
+  apiHost?: string;
+};
+
+/**
+ * Request parameters for fetching structured data for a specific page.
+ *
+ * @remarks
+ * Passed to {@link NxisClient.getStructuredData}. Contains only
+ * request-specific parameters — credentials and host config are
+ * set once at client initialization.
+ *
+ * @example
+ * ```typescript
+ * const jsonLd = await nxis.getStructuredData({
+ *   uri: 'https://example.com/page',
+ *   userAgent: req.headers['user-agent'],
+ * });
+ * ```
+ */
+export type NxisSSRRequest = {
+  /** The full URI of the page being rendered (e.g. `"https://example.com/about"`). */
+  uri: string;
+  /** The site identifier to scope the request to a specific site. */
+  siteId: string;
+  /**
+   * Optional User-Agent string forwarded to the proxy for bot detection.
+   *
+   * @remarks
+   * When provided, the proxy can distinguish search-engine crawlers and LLM
+   * agents from regular visitors and adjust response behavior accordingly.
+   */
+  userAgent?: string;
+};
+
+/**
+ * gRPC-compatible error codes used by the Nxis AI Proxy.
+ *
+ * @remarks
+ * These codes map directly to gRPC status codes and are included in
+ * structured error responses from the proxy. Use {@link errorCodeToHttp}
+ * to convert to the corresponding HTTP status code.
+ */
+export enum ErrorCode {
+  /** The request completed successfully. */
+  OK = 0,
+  /** The request contained an invalid argument (e.g. malformed URI). */
+  INVALID_ARGUMENT = 3,
+  /** The requested resource was not found. */
+  NOT_FOUND = 5,
+  /** The caller does not have permission to access the requested resource. */
+  PERMISSION_DENIED = 7,
+  /** The caller has exceeded their rate limit or quota. */
+  RESOURCE_EXHAUSTED = 8,
+  /** An internal server error occurred. */
+  INTERNAL = 13,
+  /** The request lacks valid authentication credentials. */
+  UNAUTHENTICATED = 16,
+}
+
+/**
+ * Maps each {@link ErrorCode} to its conventional HTTP status code.
+ *
+ * @example
+ * ```typescript
+ * const httpStatus = errorCodeToHttp[ErrorCode.NOT_FOUND]; // 404
+ * ```
+ */
+export const errorCodeToHttp: Record<ErrorCode, number> = {
+  [ErrorCode.OK]: 200,
+  [ErrorCode.INVALID_ARGUMENT]: 400,
+  [ErrorCode.NOT_FOUND]: 404,
+  [ErrorCode.PERMISSION_DENIED]: 403,
+  [ErrorCode.RESOURCE_EXHAUSTED]: 429,
+  [ErrorCode.INTERNAL]: 500,
+  [ErrorCode.UNAUTHENTICATED]: 401,
+};
+
+/**
+ * The structured JSON body returned by the proxy on error responses.
+ */
+export interface NxisErrorResponse {
+  /** The gRPC-style error code. */
+  code: ErrorCode;
+  /** A human-readable error message. */
+  message: string;
+  /** Optional array of protobuf `Any`-style detail messages. */
+  details?: Array<{ "@type": string; value: string }>;
+}
+
+/**
+ * An error thrown when the Nxis AI Proxy returns a non-200 response.
+ *
+ * @remarks
+ * `ProxyError` carries both the gRPC {@link ErrorCode} and the HTTP status
+ * code so callers can decide how to surface or retry the failure.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const data = await getStructuredData({ token, uri });
+ * } catch (err) {
+ *   if (err instanceof ProxyError && err.isRetryable) {
+ *     // back off and retry
+ *   }
+ * }
+ * ```
+ */
+export class ProxyError extends Error {
+  /**
+   * @param code - The gRPC-style {@link ErrorCode}.
+   * @param httpStatus - The HTTP status code from the proxy response.
+   * @param message - A human-readable description of the error.
+   */
+  constructor(
+    public readonly code: ErrorCode,
+    public readonly httpStatus: number,
+    message: string,
+  ) {
+    super(message);
+    this.name = "ProxyError";
+    Object.setPrototypeOf(this, ProxyError.prototype);
+  }
+
+  /**
+   * Whether this error represents a transient failure that may succeed on retry.
+   *
+   * @remarks
+   * Returns `true` for {@link ErrorCode.RESOURCE_EXHAUSTED} (rate limiting)
+   * and {@link ErrorCode.INTERNAL} (server errors).
+   */
+  get isRetryable(): boolean {
+    return this.code === ErrorCode.RESOURCE_EXHAUSTED || this.code === ErrorCode.INTERNAL;
+  }
+
+  /**
+   * Whether this error indicates an authentication or authorization failure.
+   *
+   * @remarks
+   * Returns `true` for {@link ErrorCode.UNAUTHENTICATED} (missing/invalid token)
+   * and {@link ErrorCode.PERMISSION_DENIED} (valid token, insufficient access).
+   */
+  get isAuthError(): boolean {
+    return this.code === ErrorCode.UNAUTHENTICATED || this.code === ErrorCode.PERMISSION_DENIED;
+  }
+
+  /**
+   * Creates a `ProxyError` from an HTTP status code and a parsed
+   * {@link NxisErrorResponse} body.
+   *
+   * @param status - The HTTP status code of the response.
+   * @param body - The parsed error response body from the proxy.
+   * @returns A new `ProxyError` instance.
+   */
+  static fromResponse(status: number, body: NxisErrorResponse): ProxyError {
+    return new ProxyError(body.code, status, body.message);
+  }
+}

package/src/auth.ts

@@ -0,0 +1,171 @@
+import { ProxyError, ErrorCode } from './api';
+
+/**
+ * Configuration for the OAuth client credentials flow.
+ *
+ * @internal
+ */
+export interface OAuthConfig {
+  /** OAuth client ID (format: `nxis_cid_[a-zA-Z0-9]{16}`). */
+  clientId: string;
+  /** OAuth client secret (format: `nxis_sec_[a-zA-Z0-9]{32}`). */
+  clientSecret: string;
+  /**
+   * The OAuth token endpoint URL.
+   *
+   * @defaultValue Falls back to `NXIS_TOKEN_URL` env var, then `"https://authorization.nxis.ai/v1/oauth/token"`.
+   */
+  tokenUrl?: string;
+  /**
+   * OAuth scope to request.
+   *
+   * @defaultValue `"jsonld:read"`
+   */
+  scope?: string;
+}
+
+/**
+ * Response from the OAuth token endpoint (`POST /v1/oauth/token`).
+ *
+ * @remarks
+ * Matches the `IssueTokenResponse` message in the OAuth service proto.
+ */
+export interface IssueTokenResponse {
+  /** The issued access token. */
+  access_token: string;
+  /** Token type — always `"Bearer"`. */
+  token_type: string;
+  /** Seconds until the token expires. */
+  expires_in: number;
+  /** The granted scope. */
+  scope: string;
+}
+
+/** Default token endpoint URL. */
+const DEFAULT_TOKEN_URL = 'https://authorization.nxis.ai/v1/oauth/token';
+
+/** Refresh the token when it has this many seconds or fewer remaining. */
+const REFRESH_BUFFER_SECONDS = 60;
+
+/**
+ * Manages OAuth 2.0 access tokens using the client credentials grant.
+ *
+ * @remarks
+ * Tokens are cached in memory and automatically refreshed before expiration.
+ * Concurrent calls during a refresh all await the same in-flight request,
+ * preventing redundant token fetches.
+ *
+ * @example
+ * ```typescript
+ * const manager = new OAuthTokenManager({
+ *   clientId: process.env.NXIS_CLIENT_ID!,
+ *   clientSecret: process.env.NXIS_CLIENT_SECRET!,
+ * });
+ *
+ * const token = await manager.getAccessToken();
+ * // Use token in Authorization: Bearer <token> header
+ * ```
+ */
+export class OAuthTokenManager {
+  private readonly clientId: string;
+  private readonly clientSecret: string;
+  private readonly tokenUrl: string;
+  private readonly scope: string;
+
+  /** The currently cached access token, or `null` if none. */
+  private cachedToken: string | null = null;
+
+  /** Unix timestamp (ms) at which the cached token expires. */
+  private expiresAt: number = 0;
+
+  /** In-flight token request for concurrency deduplication. */
+  private pendingRequest: Promise<string> | null = null;
+
+  constructor(config: OAuthConfig) {
+    this.clientId = config.clientId;
+    this.clientSecret = config.clientSecret;
+    this.tokenUrl = config.tokenUrl
+      ?? process.env.NXIS_TOKEN_URL
+      ?? DEFAULT_TOKEN_URL;
+    this.scope = config.scope ?? 'jsonld:read';
+  }
+
+  /**
+   * Returns a valid access token, fetching or refreshing as needed.
+   *
+   * @remarks
+   * If the cached token has more than {@link REFRESH_BUFFER_SECONDS} seconds
+   * remaining, it is returned immediately. Otherwise a new token is requested
+   * from the OAuth endpoint.
+   *
+   * @returns A valid OAuth Bearer access token.
+   *
+   * @throws {@link ProxyError}
+   * Thrown if the token endpoint returns an error response.
+   */
+  async getAccessToken(): Promise<string> {
+    if (this.cachedToken && Date.now() < this.expiresAt) {
+      return this.cachedToken;
+    }
+
+    // Deduplicate concurrent refresh requests
+    if (this.pendingRequest) {
+      return this.pendingRequest;
+    }
+
+    this.pendingRequest = this.fetchToken();
+
+    try {
+      const token = await this.pendingRequest;
+      return token;
+    } finally {
+      this.pendingRequest = null;
+    }
+  }
+
+  /**
+   * Fetches a new access token from the OAuth endpoint.
+   *
+   * @internal
+   */
+  private async fetchToken(): Promise<string> {
+    const body = new URLSearchParams({
+      grant_type: 'client_credentials',
+      client_id: this.clientId,
+      client_secret: this.clientSecret,
+      scope: this.scope,
+    });
+
+    const response = await fetch(this.tokenUrl, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body: body.toString(),
+    });
+
+    if (!response.ok) {
+      const statusToCode: Record<number, ErrorCode> = {
+        400: ErrorCode.INVALID_ARGUMENT,
+        401: ErrorCode.UNAUTHENTICATED,
+        403: ErrorCode.PERMISSION_DENIED,
+        429: ErrorCode.RESOURCE_EXHAUSTED,
+      };
+      const code = statusToCode[response.status] ?? ErrorCode.INTERNAL;
+      let message: string;
+      try {
+        const errorBody = await response.json();
+        message = errorBody.message ?? errorBody.error_description ?? `Token request failed with status ${response.status}`;
+      } catch {
+        message = `Token request failed with status ${response.status}`;
+      }
+      throw new ProxyError(code, response.status, message);
+    }
+
+    const data: IssueTokenResponse = await response.json();
+
+    this.cachedToken = data.access_token;
+    // Subtract buffer so we refresh before actual expiry
+    this.expiresAt = Date.now() + (data.expires_in - REFRESH_BUFFER_SECONDS) * 1000;
+
+    return this.cachedToken;
+  }
+}

package/src/client.ts

@@ -0,0 +1,104 @@
+import { NxisWarning, NxisConfig, StructuredDataResponse } from './api';
+import { buildParams, responseHandler } from './core';
+import { v4 as uuidv4 } from 'uuid';
+
+declare global {
+  interface Window {
+    /** A unique session ID generated per page load for request correlation. */
+    NXIS_SESSION_ID: string;
+    /**
+     * Configuration injected by the Nxis CDN into the served script.
+     * Contains organization, site, and subscription identifiers extracted
+     * from the JWT token's claims.
+     */
+    __NXIS_CONFIG__: NxisConfig;
+    ga: UniversalAnalytics.ga;
+  }
+}
+
+/**
+ * Injects JSON-LD structured data into the document `<head>`.
+ *
+ * @remarks
+ * Creates a `<script type="application/ld+json">` element containing the
+ * serialized JSON-LD array, wrapped with HTML comments for easy identification
+ * in the DOM (`<!-- Nxis.ai -->` … `<!-- End Nxis.ai -->`).
+ *
+ * Does nothing if the response data array is empty.
+ *
+ * @param response - The structured data response from the proxy.
+ *
+ * @internal
+ */
+function inject(response: StructuredDataResponse): void {
+  if (response.data && Object.keys(response.data).length > 0) {
+    const start = document.createComment("Nxis.ai");
+    const end = document.createComment("End Nxis.ai");
+    const script: Element = document.createElement('script');
+    script.setAttribute('type', 'application/ld+json');
+    script.textContent = JSON.stringify(response.data);
+    document.head.appendChild(script);
+    script.before(start);
+    script.after(end);
+  }
+}
+
+/**
+ * Handles errors from the client-side fetch pipeline.
+ *
+ * @remarks
+ * - {@link NxisWarning} instances are logged as `console.warn` — these
+ *   indicate that no data was found for the current page, which is non-fatal.
+ * - All other errors are logged as `console.error`.
+ *
+ * @param e - The error caught from the fetch/response pipeline.
+ *
+ * @internal
+ */
+function errorHandler(e: Error): void {
+  if (e instanceof NxisWarning) {
+    console.warn(JSON.parse(e.message).message);
+  } else {
+    console.error(`Unable to retrieve structured data for ${window.location.href}`);
+  }
+}
+
+/**
+ * Client-side IIFE — auto-executes on script load.
+ *
+ * @remarks
+ * This is the main entry point for the browser bundle (`build/nxis.js`).
+ * It performs the following steps:
+ *
+ * 1. Generates a unique session ID and stores it on `window.NXIS_SESSION_ID`.
+ * 2. Reads the injected {@link NxisConfig} from `window.__NXIS_CONFIG__`.
+ * 3. Builds the request parameters from the current page URL, referrer,
+ *    and session context.
+ * 4. Calls the `/v1/nxis:inject` proxy endpoint.
+ * 5. On success, injects the returned JSON-LD into the document `<head>`.
+ * 6. On failure, logs a warning or error to the console.
+ */
+(function () {
+  window.NXIS_SESSION_ID = uuidv4();
+  const API = process.env.NXIS_API_HOST;
+  const config: NxisConfig = window.__NXIS_CONFIG__;
+
+  const headers: Headers = new Headers();
+  const NXIS: URL = new URL(`${API}/v1/nxis:inject`);
+
+  NXIS.search = buildParams({
+    organization_id: { value: config?.org_id },
+    site_id: { value: config?.site_id },
+    uri: new URL(window.location.href),
+    referrer: document.referrer,
+    session: window.NXIS_SESSION_ID
+  }).toString();
+  if (config?.sub_id) headers.set("X-NXIS-SUBSCRIPTION", config.sub_id);
+  headers.set("Content-Type", "application/json");
+  headers.set("User-Agent", navigator.userAgent);
+
+  fetch(`${NXIS}`, { headers })
+    .then((res) => responseHandler(res, window.location.href))
+    .then(inject)
+    .catch(errorHandler);
+})();