@nxisai/nxis 2.1.1

package/build/api.d.ts

@@ -0,0 +1,244 @@
+/**
+ * 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 declare class NxisWarning extends Error {
+    constructor(msg: string);
+}
+/**
+ * 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 declare 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 declare const errorCodeToHttp: Record<ErrorCode, number>;
+/**
+ * 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 declare class ProxyError extends Error {
+    readonly code: ErrorCode;
+    readonly httpStatus: number;
+    /**
+     * @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: ErrorCode, httpStatus: number, message: string);
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+}

package/build/auth.d.ts

@@ -0,0 +1,91 @@
+/**
+ * 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;
+}
+/**
+ * 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 declare class OAuthTokenManager {
+    private readonly clientId;
+    private readonly clientSecret;
+    private readonly tokenUrl;
+    private readonly scope;
+    /** The currently cached access token, or `null` if none. */
+    private cachedToken;
+    /** Unix timestamp (ms) at which the cached token expires. */
+    private expiresAt;
+    /** In-flight token request for concurrency deduplication. */
+    private pendingRequest;
+    constructor(config: OAuthConfig);
+    /**
+     * 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.
+     */
+    getAccessToken(): Promise<string>;
+    /**
+     * Fetches a new access token from the OAuth endpoint.
+     *
+     * @internal
+     */
+    private fetchToken;
+}

package/build/core.d.ts

@@ -0,0 +1,56 @@
+import { StructuredDataRequest, StructuredDataResponse } 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 declare function buildParams(request: StructuredDataRequest): URLSearchParams;
+/**
+ * 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 declare function responseHandler(response: Response, pageUrl?: string): Promise<StructuredDataResponse>;
+/**
+ * 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 declare function fetchStructuredData(uri: string, accessToken: string, apiHost: string, userAgent?: string, siteId?: string): Promise<StructuredDataResponse>;