@nxisai/nxis 2.1.1

package/src/core.ts

@@ -0,0 +1,124 @@
+import { StructuredDataRequest, NxisWarning, StructuredDataResponse, NxisErrorResponse, ProxyError } from './api';
+
+/**
+ * Serializes a {@link StructuredDataRequest} into URL query parameters for
+ * the client-side `/v1/nxis:inject` endpoint.
+ *
+ * @param request - The structured data request containing org, site, URI,
+ *   referrer, and session info.
+ * @returns A `URLSearchParams` instance ready to be appended to the request URL.
+ *
+ * @internal
+ */
+export function buildParams(request: StructuredDataRequest): URLSearchParams {
+  const output = new URLSearchParams();
+  if (request.organization_id?.value) output.append("organization_id", request.organization_id.value);
+  if (request.site_id?.value) output.append("site_id", request.site_id.value);
+  output.append("uri", request.uri.href);
+  if (request.referrer) output.append("referrer", request.referrer);
+  if (request.session) output.append("session", request.session);
+  return output;
+}
+
+/**
+ * Attempts to parse the response body as a {@link NxisErrorResponse}.
+ *
+ * @param response - The `fetch` Response object to parse.
+ * @returns The parsed error body, or `null` if the body is not valid JSON.
+ *
+ * @internal
+ */
+async function parseErrorBody(response: Response): Promise<NxisErrorResponse | null> {
+  try {
+    return await response.json() as NxisErrorResponse;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Processes an HTTP response from the Nxis API and returns the structured
+ * data payload, or throws an appropriate error.
+ *
+ * @remarks
+ * - On a `200` response with data, returns the {@link StructuredDataResponse}.
+ * - On a `200` response with an empty `data` object, throws {@link NxisWarning}.
+ * - On error responses, attempts to parse a structured {@link NxisErrorResponse}
+ *   and throws a {@link ProxyError}. Falls back to generic status-based errors
+ *   if the body cannot be parsed.
+ *
+ * @param response - The raw `fetch` Response from the proxy.
+ * @param pageUrl - The page URL for use in error messages. Defaults to `"unknown"`.
+ * @returns The parsed structured data response.
+ *
+ * @throws {@link NxisWarning}
+ * Thrown when the proxy returns 200 but the data object is empty.
+ *
+ * @throws {@link ProxyError}
+ * Thrown when the proxy returns a non-200 status code.
+ */
+export async function responseHandler(response: Response, pageUrl?: string): Promise<StructuredDataResponse> {
+  const url = pageUrl ?? 'unknown';
+
+  if (response.status === 200) {
+    const json: StructuredDataResponse = await response.json();
+    if (json?.data && Object.keys(json.data).length > 0) return json;
+    throw new NxisWarning(JSON.stringify({ message: `No Nxis resource found for ${url}` }));
+  }
+
+  // Attempt to parse a structured error response from the proxy
+  const errorBody = await parseErrorBody(response);
+  if (errorBody?.code !== undefined && errorBody?.message) {
+    throw ProxyError.fromResponse(response.status, errorBody);
+  }
+
+  // Fallback for non-structured error responses
+  switch (response.status) {
+    case 500: throw new ProxyError(13, 500, "An internal server error occurred, please contact technical support.");
+    case 502: throw new ProxyError(13, 502, "An internal server error occurred, please contact technical support.");
+    case 503: throw new ProxyError(8, 503, "Service is temporarily unavailable, please try again later.");
+    default: throw new ProxyError(13, response.status, `Unexpected response status: ${response.status}`);
+  }
+}
+
+/**
+ * Fetches structured data from the Nxis AI Proxy's SSR endpoint (`/v1/nxis:ssr`).
+ *
+ * @remarks
+ * This is the low-level fetch function used by {@link NxisClient}. It sends
+ * the request with a `Bearer` access token obtained from the OAuth token manager.
+ *
+ * @param uri - The full URI of the page being rendered.
+ * @param accessToken - A valid OAuth Bearer access token.
+ * @param apiHost - The Nxis API host URL.
+ * @param userAgent - Optional User-Agent string for bot detection.
+ * @returns The full {@link StructuredDataResponse} from the proxy.
+ *
+ * @throws {@link ProxyError}
+ * Thrown if the proxy returns a non-200 response.
+ *
+ * @throws {@link NxisWarning}
+ * Thrown if the proxy returns 200 but no data is available for the page.
+ *
+ * @internal
+ */
+export async function fetchStructuredData(
+  uri: string,
+  accessToken: string,
+  apiHost: string,
+  userAgent?: string,
+  siteId?: string,
+): Promise<StructuredDataResponse> {
+  const endpoint = new URL(`${apiHost}/v1/nxis:ssr`);
+  endpoint.searchParams.append("uri", uri);
+  if (siteId) endpoint.searchParams.append("site_id", siteId);
+
+  const hdrs: Record<string, string> = {
+    "Content-Type": "application/json",
+    "Authorization": `Bearer ${accessToken}`,
+  };
+  if (userAgent) hdrs["User-Agent"] = userAgent;
+  const response = await fetch(endpoint.toString(), { headers: hdrs });
+  return responseHandler(response, uri);
+}
+

package/src/index.ts

@@ -0,0 +1,33 @@
+/**
+ * @packageDocumentation
+ *
+ * Nxis.js — a lightweight client for the Nxis AI structured data platform.
+ *
+ * @remarks
+ * This package provides two integration paths:
+ *
+ * - **Client-side (browser):** Load `nxis.js` via a `<script>` tag from the
+ *   Nxis CDN. The script auto-injects JSON-LD into the page.
+ *
+ * - **Server-side (SSR):** Import {@link NxisClient} from
+ *   `@nxisai/nxis/ssr` and initialize it with your OAuth client
+ *   credentials. The client manages access tokens automatically and
+ *   fetches JSON-LD at render time to embed in the initial HTML response.
+ *
+ * @example
+ * ```typescript
+ * import { NxisClient } from '@nxisai/nxis/ssr';
+ *
+ * const nxis = new NxisClient({
+ *   clientId: process.env.NXIS_CLIENT_ID!,
+ *   clientSecret: process.env.NXIS_CLIENT_SECRET!,
+ * });
+ *
+ * const jsonLd = await nxis.getStructuredData({
+ *   uri: 'https://example.com/page',
+ * });
+ * ```
+ */
+export { NxisClient } from './server';
+export { ProxyError, ErrorCode, errorCodeToHttp } from './api';
+export type { NxisClientConfig, NxisSSRRequest, StructuredDataResponse, NxisErrorResponse } from './api';

package/src/server.ts

@@ -0,0 +1,106 @@
+import { NxisClientConfig, NxisSSRRequest } from './api';
+import { OAuthTokenManager } from './auth';
+import { fetchStructuredData } from './core';
+
+/**
+ * A client for fetching JSON-LD structured data from the Nxis AI platform.
+ *
+ * @remarks
+ * `NxisClient` encapsulates OAuth authentication and token lifecycle
+ * management. Initialize once with your client credentials, then call
+ * {@link NxisClient.getStructuredData} for each page render.
+ *
+ * Tokens are cached in memory and refreshed automatically before
+ * expiration — no manual token handling is needed.
+ *
+ * @example
+ * ```tsx
+ * // Next.js App Router
+ * 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 jsonLd = await nxis.getStructuredData({
+ *     uri: `${proto}://${host}/`,
+ *     userAgent: headersList.get('user-agent') ?? undefined,
+ *   });
+ *
+ *   return (
+ *     <script
+ *       type="application/ld+json"
+ *       dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+export class NxisClient {
+  private readonly tokenManager: OAuthTokenManager;
+  private readonly apiHost: string;
+
+  /**
+   * Creates a new Nxis client.
+   *
+   * @param config - Client configuration including OAuth credentials and
+   *   optional host/token URL overrides.
+   *
+   * @throws {@link Error}
+   * Thrown if `NXIS_API_HOST` is not set and no `apiHost` override is provided.
+   */
+  constructor(config: NxisClientConfig) {
+    this.apiHost = config.apiHost ?? process.env.NXIS_API_HOST ?? '';
+    if (!this.apiHost) {
+      throw new Error(
+        'NXIS_API_HOST is not set. Pass apiHost in the config or set the NXIS_API_HOST environment variable.',
+      );
+    }
+
+    this.tokenManager = new OAuthTokenManager({
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+      tokenUrl: config.tokenUrl,
+      scope: config.scope,
+    });
+  }
+
+  /**
+   * Fetches JSON-LD structured data for a given page URL.
+   *
+   * @remarks
+   * Returns a JSON-LD object ready to be serialized into a
+   * `<script type="application/ld+json">` tag in your server-rendered HTML.
+   *
+   * The client automatically obtains a valid OAuth access token before
+   * making the request. Tokens are cached and refreshed transparently.
+   *
+   * @param req - Request-specific parameters (page URI and optional User-Agent).
+   * @returns A JSON-LD object to embed in the page.
+   *
+   * @throws {@link ProxyError}
+   * Thrown when the proxy returns a non-200 response (auth failures, rate
+   * limits, server errors, etc.).
+   *
+   * @throws {@link NxisWarning}
+   * Thrown when the proxy returns 200 but no structured data exists for the page.
+   */
+  async getStructuredData(req: NxisSSRRequest): Promise<Record<string, unknown>> {
+    const accessToken = await this.tokenManager.getAccessToken();
+    const response = await fetchStructuredData(
+      req.uri,
+      accessToken,
+      this.apiHost,
+      req.userAgent,
+      req.siteId,
+    );
+    return response.data;
+  }
+}

package/tsconfig.json

@@ -0,0 +1,66 @@
+{
+  "compilerOptions": {
+    /* Basic Options */
+    // "incremental": true,                   /* Enable incremental compilation */
+    "target": "es2018",
+    "module": "esnext",
+    "moduleResolution": "node",
+    // "lib": [],                             /* Specify library files to be included in the compilation. */
+    // "allowJs": true,                       /* Allow javascript files to be compiled. */
+    // "checkJs": true,                       /* Report errors in .js files. */
+    // "jsx": "preserve",                     /* Specify JSX code generation: 'preserve', 'react-native', or 'react'. */
+    "declaration": true,                      /* Generates corresponding '.d.ts' file. */
+    // "declarationMap": true,                /* Generates a sourcemap for each corresponding '.d.ts' file. */
+    // "sourceMap": true,                     /* Generates corresponding '.map' file. */
+    // "outFile": "./",                       /* Concatenate and emit output to single file. */
+    // "outDir": "./",                        /* Redirect output structure to the directory. */
+    // "rootDir": "./",                       /* Specify the root directory of input files. Use to control the output directory structure with --outDir. */
+    // "composite": true,                     /* Enable project compilation */
+    // "tsBuildInfoFile": "./",               /* Specify file to store incremental compilation information */
+    // "removeComments": true,                /* Do not emit comments to output. */
+    // "noEmit": true,                        /* Do not emit outputs. */
+    // "importHelpers": true,                 /* Import emit helpers from 'tslib'. */
+    // "downlevelIteration": true,            /* Provide full support for iterables in 'for-of', spread, and destructuring when targeting 'ES5' or 'ES3'. */
+    // "isolatedModules": true,               /* Transpile each file as a separate module (similar to 'ts.transpileModule'). */
+
+    /* Strict Type-Checking Options */
+    "strict": true,                           /* Enable all strict type-checking options. */
+    // "noImplicitAny": true,                 /* Raise error on expressions and declarations with an implied 'any' type. */
+    // "strictNullChecks": true,              /* Enable strict null checks. */
+    // "strictFunctionTypes": true,           /* Enable strict checking of function types. */
+    // "strictBindCallApply": true,           /* Enable strict 'bind', 'call', and 'apply' methods on functions. */
+    // "strictPropertyInitialization": true,  /* Enable strict checking of property initialization in classes. */
+    // "noImplicitThis": true,                /* Raise error on 'this' expressions with an implied 'any' type. */
+    // "alwaysStrict": true,                  /* Parse in strict mode and emit "use strict" for each source file. */
+
+    /* Additional Checks */
+    // "noUnusedLocals": true,                /* Report errors on unused locals. */
+    // "noUnusedParameters": true,            /* Report errors on unused parameters. */
+    // "noImplicitReturns": true,             /* Report error when not all code paths in function return a value. */
+    // "noFallthroughCasesInSwitch": true,    /* Report errors for fallthrough cases in switch statement. */
+
+    /* Module Resolution Options */
+    // "moduleResolution": "node",            /* Specify module resolution strategy: 'node' (Node.js) or 'classic' (TypeScript pre-1.6). */
+    // "baseUrl": "./",                       /* Base directory to resolve non-absolute module names. */
+    // "paths": {},                           /* A series of entries which re-map imports to lookup locations relative to the 'baseUrl'. */
+    // "rootDirs": [],                        /* List of root folders whose combined content represents the structure of the project at runtime. */
+    // "typeRoots": [],                       /* List of folders to include type definitions from. */
+    // "types": [],                           /* Type declaration files to be included in compilation. */
+    // "allowSyntheticDefaultImports": true,  /* Allow default imports from modules with no default export. This does not affect code emit, just typechecking. */
+    "esModuleInterop": true                   /* Enables emit interoperability between CommonJS and ES Modules via creation of namespace objects for all imports. Implies 'allowSyntheticDefaultImports'. */
+    // "preserveSymlinks": true,              /* Do not resolve the real path of symlinks. */
+    // "allowUmdGlobalAccess": true,          /* Allow accessing UMD globals from modules. */
+
+    /* Source Map Options */
+    // "sourceRoot": "",                      /* Specify the location where debugger should locate TypeScript files instead of source locations. */
+    // "mapRoot": "",                         /* Specify the location where debugger should locate map files instead of generated locations. */
+    // "inlineSourceMap": true,               /* Emit a single file with source maps instead of having a separate file. */
+    // "inlineSources": true,                 /* Emit the source alongside the sourcemaps within a single file; requires '--inlineSourceMap' or '--sourceMap' to be set. */
+
+    /* Experimental Options */
+    // "experimentalDecorators": true,        /* Enables experimental support for ES7 decorators. */
+    // "emitDecoratorMetadata": true,         /* Enables experimental support for emitting type metadata for decorators. */
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "build", "examples"]
+}