@jini-ai/daemon 0.3.8 → 0.5.1

package/dist/http/xai.d.ts

@@ -0,0 +1,90 @@
+import type { Express } from 'express';
+import { PendingAuthCache, startOAuthCallbackListener, type OAuthCallbackListener, type OAuthPkceProviderConfig } from '@jini-ai/agent-runtime';
+import { type AdapterContext } from '@jini-ai/http-kit';
+export interface XaiInternalErrorContext {
+    readonly source: 'oauth-start' | 'oauth-complete' | 'oauth-disconnect' | 'auth-status' | 'search';
+    readonly correlationId: string;
+    readonly error: unknown;
+}
+export interface XaiHttpDeps {
+    /** Directory the xAI OAuth token is persisted under (`<dataDir>/<tokenFileName>`). Defaults to `process.cwd()` — a host with a real dataDir should override this (matching `create-local-node-daemon.ts`'s `memoryRoutesDeps.dataDir` pattern). */
+    readonly dataDir?: string;
+    /** On-disk file name for the stored token, scoped under `dataDir`. Defaults to `xai-oauth-token.json`. */
+    readonly tokenFileName?: string;
+    /** The OAuth+PKCE provider config to drive the dance against. Defaults to `@jini-ai/agent-runtime`'s real `XAI_OAUTH_PROVIDER_CONFIG` preset — override only to point at a different client_id/issuer (e.g. once a non-PoC xAI client_id is provisioned). */
+    readonly providerConfig?: OAuthPkceProviderConfig;
+    /** Loopback callback host `providerConfig.clientId` is registered against. Defaults to `XAI_OAUTH_REDIRECT_HOST` (`127.0.0.1`) — see module doc on why this is fixed for xAI's PoC client_id. */
+    readonly callbackHost?: string;
+    /** Loopback callback port `providerConfig.clientId` is registered against. Defaults to `XAI_OAUTH_REDIRECT_PORT` (`56121`). */
+    readonly callbackPort?: number;
+    /** Loopback callback path `providerConfig.clientId` is registered against. Defaults to `XAI_OAUTH_REDIRECT_PATH` (`/callback`). */
+    readonly callbackPath?: string;
+    /** In-memory pending-authorization cache backing the begin/complete dance. Defaults to a fresh 30-minute `PendingAuthCache`, shared across every request `registerXaiRoutes` mounts — see module doc on why this must be resolved once, not per-call. */
+    readonly pending?: PendingAuthCache;
+    /** Mutable slot holding the in-flight loopback listener, if any (only one OAuth dance can be in flight at a time — the port is a singleton). Shared the same way `pending` is. Defaults to `{ current: null }`. */
+    readonly listenerRef?: {
+        current: OAuthCallbackListener | null;
+    };
+    /** Opens the loopback callback listener. Defaults to `@jini-ai/agent-runtime`'s `startOAuthCallbackListener`. Overridable so tests never bind a real socket. */
+    readonly startCallbackListener?: typeof startOAuthCallbackListener;
+    /** Base URL for xAI's Responses API (`POST {searchBaseUrl}/responses`). Defaults to `https://api.x.ai/v1`. */
+    readonly searchBaseUrl?: string;
+    /** Model id sent to the Responses API when a search request doesn't supply its own. Defaults to xAI's real `grok-4.20-reasoning`. */
+    readonly searchDefaultModel?: string;
+    readonly fetchImpl?: typeof fetch;
+    /** Deadline for one search request *and* its response body, in milliseconds. Defaults to {@link DEFAULT_SEARCH_TIMEOUT_MS}. */
+    readonly searchTimeoutMs?: number;
+    /** Host-owned sink for the real exception behind a generic `INTERNAL_ERROR` response (SEC-005). Defaults to `console.error`. */
+    readonly onInternalError?: (context: XaiInternalErrorContext) => void;
+}
+export interface XaiOauthStartResponse {
+    readonly authorizeUrl: string;
+    readonly state: string;
+    readonly callback: {
+        readonly host: string;
+        readonly port: number;
+    };
+}
+export declare const xaiOauthStartRoute: import("@jini-ai/http-kit").JsonRouteSpec<void, XaiOauthStartResponse, XaiHttpDeps>;
+export interface XaiOkResponse {
+    readonly ok: true;
+}
+interface XaiOauthCompleteRequest {
+    readonly state: string;
+    readonly code: string;
+}
+export declare const xaiOauthCompleteRoute: import("@jini-ai/http-kit").JsonRouteSpec<XaiOauthCompleteRequest, XaiOkResponse, XaiHttpDeps>;
+export declare const xaiOauthCancelRoute: import("@jini-ai/http-kit").JsonRouteSpec<void, XaiOkResponse, XaiHttpDeps>;
+export interface XaiAuthStatusResponse {
+    readonly connected: boolean;
+    readonly expiresAt: number | null;
+    readonly scope: string | null;
+    readonly savedAt: number | null;
+    readonly listening: boolean;
+}
+export declare const xaiAuthStatusRoute: import("@jini-ai/http-kit").JsonRouteSpec<void, XaiAuthStatusResponse, XaiHttpDeps>;
+export declare const xaiOauthDisconnectRoute: import("@jini-ai/http-kit").JsonRouteSpec<void, XaiOkResponse, XaiHttpDeps>;
+interface XaiSearchRequest {
+    readonly query: string;
+    readonly allowedXHandles?: readonly string[];
+    readonly excludedXHandles?: readonly string[];
+    readonly fromDate?: string;
+    readonly toDate?: string;
+    readonly enableImageUnderstanding?: boolean;
+    readonly enableVideoUnderstanding?: boolean;
+    readonly model?: string;
+}
+export interface XaiSearchResponse {
+    readonly answer: string;
+    readonly citations: readonly string[];
+    readonly model: string;
+}
+export declare const xaiSearchRoute: import("@jini-ai/http-kit").JsonRouteSpec<XaiSearchRequest, XaiSearchResponse, XaiHttpDeps>;
+/** Mounts every xAI route on `app`. A pack's `http(app, services)` calls this directly. */
+export declare function registerXaiRoutes({ app, deps, adapter }: {
+    readonly app: Express;
+    readonly deps: XaiHttpDeps;
+    readonly adapter: AdapterContext;
+}, _optional?: Record<string, never>): void;
+export {};
+//# sourceMappingURL=xai.d.ts.map