@nxisai/nxis 2.1.1

package/build/index.cjs.js

@@ -0,0 +1,423 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+/**
+ * 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.
+ */
+class NxisWarning extends Error {
+    constructor(msg) {
+        super(msg);
+        // Set the prototype explicitly.
+        Object.setPrototypeOf(this, NxisWarning.prototype);
+    }
+}
+/**
+ * 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.
+ */
+exports.ErrorCode = void 0;
+(function (ErrorCode) {
+    /** The request completed successfully. */
+    ErrorCode[ErrorCode["OK"] = 0] = "OK";
+    /** The request contained an invalid argument (e.g. malformed URI). */
+    ErrorCode[ErrorCode["INVALID_ARGUMENT"] = 3] = "INVALID_ARGUMENT";
+    /** The requested resource was not found. */
+    ErrorCode[ErrorCode["NOT_FOUND"] = 5] = "NOT_FOUND";
+    /** The caller does not have permission to access the requested resource. */
+    ErrorCode[ErrorCode["PERMISSION_DENIED"] = 7] = "PERMISSION_DENIED";
+    /** The caller has exceeded their rate limit or quota. */
+    ErrorCode[ErrorCode["RESOURCE_EXHAUSTED"] = 8] = "RESOURCE_EXHAUSTED";
+    /** An internal server error occurred. */
+    ErrorCode[ErrorCode["INTERNAL"] = 13] = "INTERNAL";
+    /** The request lacks valid authentication credentials. */
+    ErrorCode[ErrorCode["UNAUTHENTICATED"] = 16] = "UNAUTHENTICATED";
+})(exports.ErrorCode || (exports.ErrorCode = {}));
+/**
+ * Maps each {@link ErrorCode} to its conventional HTTP status code.
+ *
+ * @example
+ * ```typescript
+ * const httpStatus = errorCodeToHttp[ErrorCode.NOT_FOUND]; // 404
+ * ```
+ */
+const errorCodeToHttp = {
+    [exports.ErrorCode.OK]: 200,
+    [exports.ErrorCode.INVALID_ARGUMENT]: 400,
+    [exports.ErrorCode.NOT_FOUND]: 404,
+    [exports.ErrorCode.PERMISSION_DENIED]: 403,
+    [exports.ErrorCode.RESOURCE_EXHAUSTED]: 429,
+    [exports.ErrorCode.INTERNAL]: 500,
+    [exports.ErrorCode.UNAUTHENTICATED]: 401,
+};
+/**
+ * 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
+ *   }
+ * }
+ * ```
+ */
+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(code, httpStatus, message) {
+        super(message);
+        this.code = code;
+        this.httpStatus = httpStatus;
+        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() {
+        return this.code === exports.ErrorCode.RESOURCE_EXHAUSTED || this.code === exports.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() {
+        return this.code === exports.ErrorCode.UNAUTHENTICATED || this.code === exports.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, body) {
+        return new ProxyError(body.code, status, body.message);
+    }
+}
+
+/** 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
+ * ```
+ */
+class OAuthTokenManager {
+    constructor(config) {
+        var _a, _b, _c;
+        /** The currently cached access token, or `null` if none. */
+        this.cachedToken = null;
+        /** Unix timestamp (ms) at which the cached token expires. */
+        this.expiresAt = 0;
+        /** In-flight token request for concurrency deduplication. */
+        this.pendingRequest = null;
+        this.clientId = config.clientId;
+        this.clientSecret = config.clientSecret;
+        this.tokenUrl = (_b = (_a = config.tokenUrl) !== null && _a !== void 0 ? _a : process.env.NXIS_TOKEN_URL) !== null && _b !== void 0 ? _b : DEFAULT_TOKEN_URL;
+        this.scope = (_c = config.scope) !== null && _c !== void 0 ? _c : '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() {
+        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
+     */
+    async fetchToken() {
+        var _a, _b, _c;
+        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 = {
+                400: exports.ErrorCode.INVALID_ARGUMENT,
+                401: exports.ErrorCode.UNAUTHENTICATED,
+                403: exports.ErrorCode.PERMISSION_DENIED,
+                429: exports.ErrorCode.RESOURCE_EXHAUSTED,
+            };
+            const code = (_a = statusToCode[response.status]) !== null && _a !== void 0 ? _a : exports.ErrorCode.INTERNAL;
+            let message;
+            try {
+                const errorBody = await response.json();
+                message = (_c = (_b = errorBody.message) !== null && _b !== void 0 ? _b : errorBody.error_description) !== null && _c !== void 0 ? _c : `Token request failed with status ${response.status}`;
+            }
+            catch (_d) {
+                message = `Token request failed with status ${response.status}`;
+            }
+            throw new ProxyError(code, response.status, message);
+        }
+        const data = 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;
+    }
+}
+
+/**
+ * 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) {
+    try {
+        return await response.json();
+    }
+    catch (_a) {
+        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.
+ */
+async function responseHandler(response, pageUrl) {
+    const url = pageUrl !== null && pageUrl !== void 0 ? pageUrl : 'unknown';
+    if (response.status === 200) {
+        const json = await response.json();
+        if ((json === null || json === void 0 ? void 0 : 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 === null || errorBody === void 0 ? void 0 : errorBody.code) !== undefined && (errorBody === null || errorBody === void 0 ? void 0 : 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
+ */
+async function fetchStructuredData(uri, accessToken, apiHost, userAgent, siteId) {
+    const endpoint = new URL(`${apiHost}/v1/nxis:ssr`);
+    endpoint.searchParams.append("uri", uri);
+    if (siteId)
+        endpoint.searchParams.append("site_id", siteId);
+    const hdrs = {
+        "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);
+}
+
+/**
+ * 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) }}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+class NxisClient {
+    /**
+     * 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) {
+        var _a, _b;
+        this.apiHost = (_b = (_a = config.apiHost) !== null && _a !== void 0 ? _a : process.env.NXIS_API_HOST) !== null && _b !== void 0 ? _b : '';
+        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) {
+        const accessToken = await this.tokenManager.getAccessToken();
+        const response = await fetchStructuredData(req.uri, accessToken, this.apiHost, req.userAgent, req.siteId);
+        return response.data;
+    }
+}
+
+exports.NxisClient = NxisClient;
+exports.ProxyError = ProxyError;
+exports.errorCodeToHttp = errorCodeToHttp;

package/build/index.d.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';