From efbe41d81bafaf42844ec46cc41bf123470b74d1 Mon Sep 17 00:00:00 2001 From: "INFRAGISTICS\\PVillarmarzo" Date: Thu, 13 Aug 2026 15:51:57 -0300 Subject: [PATCH 1/2] document AI client request configuration --- docs/ai/install-client-sdk.md | 2 ++ docs/ai/sdk-overview.md | 40 +++++++++++++++++++++++++++++++++++ 2 files changed, 42 insertions(+) diff --git a/docs/ai/install-client-sdk.md b/docs/ai/install-client-sdk.md index 120d88ec..906b6af8 100644 --- a/docs/ai/install-client-sdk.md +++ b/docs/ai/install-client-sdk.md @@ -45,6 +45,8 @@ The AI Client SDK is written in TypeScript and includes complete type definition ## Framework-Specific Setup +For `RevealSdkClient.initialize()` configuration options, including dynamic bearer-token authentication and custom request headers, see [Using the SDK](./sdk-overview.md#initialization). + ### Vanilla JavaScript #### Using ES Modules diff --git a/docs/ai/sdk-overview.md b/docs/ai/sdk-overview.md index 46396ae7..1cf2d6d4 100644 --- a/docs/ai/sdk-overview.md +++ b/docs/ai/sdk-overview.md @@ -33,6 +33,44 @@ The client SDK requires the [AI Server SDK](/ai/install-server-sdk) to be instal ::: +## Request Configuration + +Configure requests only when your application needs authentication or additional request headers. + +### Bearer-Token Authentication + +Use `getBearerToken` when your AI server requires bearer-token authentication. The callback supports synchronous or asynchronous token providers. It is called before each HTTP request, so your authentication provider can return or refresh the current token before the request is sent. The client adds the returned value as an `Authorization: Bearer ` header. + +```typescript +RevealSdkClient.initialize({ + hostUrl: 'https://your-server.com', + getBearerToken: async () => { + return await authService.getValidAccessToken(); + } +}); +``` + +`getBearerToken` is also applied to streaming requests. + +### Custom Request Headers + +Use `onRequest` when you need to add or modify headers other than the bearer token. The interceptor can be asynchronous and is called before each HTTP request. + +```typescript +RevealSdkClient.initialize({ + hostUrl: 'https://your-server.com', + onRequest: async (request) => ({ + ...request, + headers: { + ...request.headers, + 'X-Tenant-Id': await tenantService.getCurrentTenantId() + } + }) +}); +``` + +Use `getBearerToken` for standard bearer-token authentication. Use `onRequest` for other dynamic headers, or when you need to customize the outgoing request. + ## Getting the Client Instance Once initialized, get the shared client instance anywhere in your application: @@ -98,4 +136,6 @@ stream.on('text', (content) => { const result = await stream.finalResponse(); ``` +When bearer-token authentication is configured with `getBearerToken`, the token provider is called when the Server-Sent Events (SSE) HTTP connection is opened, not for each streamed event. + Learn more in [Streaming Responses](./sdk-streaming.md). From 897feb3b461c52d3ac35baf1d5fb016a7dc16c48 Mon Sep 17 00:00:00 2001 From: "INFRAGISTICS\\PVillarmarzo" Date: Tue, 1 Sep 2026 17:29:46 -0300 Subject: [PATCH 2/2] move AI client request configuration into a preview topic Address review feedback on the request configuration docs. - Move the content out of the SDK overview into a dedicated ai/sdk-request-configuration topic marked with sidebar_custom_props.status: preview, matching how the Metadata Storage Provider topic is published, plus an in-page preview note so the API shape is not presented as final. - Document the static bearerToken option and setBearerToken(), and advise choosing one token strategy rather than describing how the two resolve against each other, which is not part of the stated API contract. - Scope onResponse and onError explicitly, limited to what the public config types state. - Keep the request-timing and SSE wording, and link the topic from the SDK overview and the client install page. Co-Authored-By: Claude Opus 5 --- docs/ai/install-client-sdk.md | 2 +- docs/ai/sdk-overview.md | 40 +--------------- docs/ai/sdk-request-configuration.md | 72 ++++++++++++++++++++++++++++ sidebars.ts | 1 + 4 files changed, 75 insertions(+), 40 deletions(-) create mode 100644 docs/ai/sdk-request-configuration.md diff --git a/docs/ai/install-client-sdk.md b/docs/ai/install-client-sdk.md index 906b6af8..0301d8d7 100644 --- a/docs/ai/install-client-sdk.md +++ b/docs/ai/install-client-sdk.md @@ -45,7 +45,7 @@ The AI Client SDK is written in TypeScript and includes complete type definition ## Framework-Specific Setup -For `RevealSdkClient.initialize()` configuration options, including dynamic bearer-token authentication and custom request headers, see [Using the SDK](./sdk-overview.md#initialization). +For `RevealSdkClient.initialize()` authentication and request header options, see [Request Configuration](/ai/sdk-request-configuration). ### Vanilla JavaScript diff --git a/docs/ai/sdk-overview.md b/docs/ai/sdk-overview.md index 1cf2d6d4..2d24d2ea 100644 --- a/docs/ai/sdk-overview.md +++ b/docs/ai/sdk-overview.md @@ -33,43 +33,7 @@ The client SDK requires the [AI Server SDK](/ai/install-server-sdk) to be instal ::: -## Request Configuration - -Configure requests only when your application needs authentication or additional request headers. - -### Bearer-Token Authentication - -Use `getBearerToken` when your AI server requires bearer-token authentication. The callback supports synchronous or asynchronous token providers. It is called before each HTTP request, so your authentication provider can return or refresh the current token before the request is sent. The client adds the returned value as an `Authorization: Bearer ` header. - -```typescript -RevealSdkClient.initialize({ - hostUrl: 'https://your-server.com', - getBearerToken: async () => { - return await authService.getValidAccessToken(); - } -}); -``` - -`getBearerToken` is also applied to streaming requests. - -### Custom Request Headers - -Use `onRequest` when you need to add or modify headers other than the bearer token. The interceptor can be asynchronous and is called before each HTTP request. - -```typescript -RevealSdkClient.initialize({ - hostUrl: 'https://your-server.com', - onRequest: async (request) => ({ - ...request, - headers: { - ...request.headers, - 'X-Tenant-Id': await tenantService.getCurrentTenantId() - } - }) -}); -``` - -Use `getBearerToken` for standard bearer-token authentication. Use `onRequest` for other dynamic headers, or when you need to customize the outgoing request. +If your AI server requires authentication or additional request headers, see [Request Configuration](/ai/sdk-request-configuration). ## Getting the Client Instance @@ -136,6 +100,4 @@ stream.on('text', (content) => { const result = await stream.finalResponse(); ``` -When bearer-token authentication is configured with `getBearerToken`, the token provider is called when the Server-Sent Events (SSE) HTTP connection is opened, not for each streamed event. - Learn more in [Streaming Responses](./sdk-streaming.md). diff --git a/docs/ai/sdk-request-configuration.md b/docs/ai/sdk-request-configuration.md new file mode 100644 index 00000000..a5df38ef --- /dev/null +++ b/docs/ai/sdk-request-configuration.md @@ -0,0 +1,72 @@ +--- +sidebar_label: Request Configuration +sidebar_custom_props: + status: preview +--- + +# Request Configuration + +:::info Preview + +Request configuration is a preview feature. It works as described below, but the option names and shapes may still change. + +::: + +`RevealSdkClient.initialize()` accepts options that control the HTTP requests the client sends to your AI server. Configure them only when your application needs authentication or additional request headers. + +## Bearer-Token Authentication + +Use `bearerToken` when the token is already available at startup. The client sends it as an `Authorization: Bearer ` header on every request. + +```typescript +RevealSdkClient.initialize({ + hostUrl: 'https://your-server.com', + bearerToken: 'your-token' +}); +``` + +To replace that token later, for example after a refresh, call `setBearerToken()` on the client instance: + +```typescript +RevealSdkClient.getInstance().setBearerToken(newToken); +``` + +Use `getBearerToken` instead when the token must be resolved per request. The callback can be synchronous or asynchronous, and it is called before each request is sent, so your authentication provider can return or refresh the current token. + +```typescript +RevealSdkClient.initialize({ + hostUrl: 'https://your-server.com', + getBearerToken: async () => { + return await authService.getValidAccessToken(); + } +}); +``` + +Use either the static token or the callback, not both. + +## Custom Request Headers + +Use `onRequest` when you need to add or modify headers other than the bearer token. The interceptor receives the outgoing request, can be asynchronous, and is called before each request is sent. + +```typescript +RevealSdkClient.initialize({ + hostUrl: 'https://your-server.com', + onRequest: async (request) => ({ + ...request, + headers: { + ...request.headers, + 'X-Tenant-Id': await tenantService.getCurrentTenantId() + } + }) +}); +``` + +## Streaming Requests + +Bearer tokens and `onRequest` also apply to [streaming](/ai/sdk-streaming) requests. They are resolved once, when the Server-Sent Events (SSE) connection is opened, and not for each streamed event. + +## Response and Error Interceptors + +`initialize()` also accepts an `onResponse` interceptor, called with the raw `Response` of each completed request, and an `onError` interceptor, called with the error of each failed request. Both can be asynchronous, and both return the value the client continues with, so `onError` can enrich an error but cannot suppress it. + +For handling AI errors in application code, see [Error Handling](/ai/sdk-error-handling). diff --git a/sidebars.ts b/sidebars.ts index 77af8cf6..8dd4d545 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -296,6 +296,7 @@ const sidebars: SidebarsConfig = { { type: "doc", label: "Chat", id: "ai/sdk-chat" }, { type: "doc", label: "Streaming Responses", id: "ai/sdk-streaming" }, { type: "doc", label: "Error Handling", id: "ai/sdk-error-handling" }, + { type: "doc", label: "Request Configuration", id: "ai/sdk-request-configuration" }, ] },