Quick start
Load the browser bundle, mount search, control visibility, and clean up.
Search sends a cached THEO bearer to the API base you pass. Obtain that bearer from your authenticated host before mounting. The browser receives only the THEO response. It must not receive a mint secret or send a Kigo member token as the bearer.
Prerequisites
- Provide an authenticated host token endpoint. The browser never receives a mint secret.
- Build the loyalty IIFE from revision
b7909e4564933080f7dbc92e6c4915147906ab60. - Create the mount element before initialization.
- Pass the API base for the selected environment. Production is
https://api.augeoai.net.
Supported build
Load the self-hosted loyalty build of revision b7909e4564933080f7dbc92e6c4915147906ab60.
That build reports version b7909e45 when no release tag is present.
Confirm window.AugeoSearchSdk.version before member traffic.
CDN latest was not verified for this recovery flow.
Do not treat package 0.2.5 as a CDN release of this flow.
Build output is packages/search-sdk/dist/iife/loyalty/index.js.
Serve that file as a classic script at /vendor/search-sdk/loyalty/index.js.
Call window.AugeoSearchSdk.createAugeoSearch with an existing element.
Pass that HTMLElement as target.
Do not pass a selector or a ShadowRoot.
<div id="search-host"></div>
<script src="/vendor/search-sdk/loyalty/index.js"></script>Self-hosted production pages allow script-src 'self' and connect-src 'self' https://api.augeoai.net.
The host token endpoint stays on 'self'.
A verified CDN script instead allows https://sdks.augeoai.net in script-src.
Use only the script origin you actually load.
Pass https://api.augeoai.net as apiBaseUrl for production.
Named stage and development builds need their own API base.
Pass that base explicitly.
Do not rely on the bundle default.
The widget injects styles inside Shadow DOM.
That style need is separate from script and connect policy.
Kigo session refresh, embed wiring, and logout handoff remain host-owned. This SDK does not mint tokens and does not add an Offers SDK. Fixture commands and the shared broker are recorded in the harness README.
packages/chat-sdk/harness/kigo-auth/README.mdLoad and mount
Mount only after the broker caches a THEO response.
getToken stays asynchronous and reads that cache.
It can return a string or a promise.
Do not mint inside the getter.
Renew from expires_in.
There is no refresh token.
programId on the SDK is a hint, not authorization.
import type { AugeoSearchInstance, CreateAugeoSearchOptions } from './vendor/search-sdk/index';
import type { BrokerSession, TokenBroker } from './vendor/kigo-auth/tokenBroker';
const API_BASE_URL = 'https://api.augeoai.net';
function mountSearch(
broker: TokenBroker,
session: BrokerSession,
scopeKey: string,
): AugeoSearchInstance {
const target = document.getElementById('search-host');
if (!target) throw new Error('Search mount container is missing.');
let search: AugeoSearchInstance;
const options: CreateAugeoSearchOptions = {
target,
apiBaseUrl: API_BASE_URL,
open: false,
auth: {
getToken: () => broker.readToken(),
},
onOpenChange: (open) => {
search.update({ open });
},
capabilities: {
programChat: {
status: 'enabled',
scope: { programId: session.programId, authScopeKey: scopeKey },
},
},
};
search = window.AugeoSearchSdk.createAugeoSearch(options);
return search;
}
async function startSearch(
broker: TokenBroker,
session: BrokerSession,
scopeKey: string,
): Promise<AugeoSearchInstance> {
await broker.acquire(session);
return mountSearch(broker, session, scopeKey);
}hostSession is not a Search SDK global.
The broker above is your shared cache for Chat and Search.
Chat reads that cache with a synchronous getter.
Search reads it with readToken().
broker and status belong to the host page.
<script>
if (!window.AugeoSearchSdk) throw new Error('Search bundle did not load.');
const target = document.getElementById('search-host');
if (!target) throw new Error('Search mount container is missing.');
const status = document.getElementById('search-status');
if (!status) throw new Error('Search status element is missing.');
const search = window.AugeoSearchSdk.createAugeoSearch({
target,
apiBaseUrl: 'https://api.augeoai.net',
open: false,
auth: {
getToken: () => broker.readToken(),
onFailure: (failure) => broker.onFailure(failure),
},
onOpenChange: (open) => {
search.update({ open });
},
onAuthError: () => {
status.textContent = 'Please sign in again.';
},
});
</script>Omitting onSearchSubmit selects panel results.
Follow Host integration to connect chat or a host results page.
Recover a rejected session
A recoverable HTTP 401 awaits optional onFailure, then reads getToken once.
That retry is the only automatic retry for the request.
onAuthError is the final notice, not the renewal callback.
Omit onFailure to keep the previous getter reread.
A rejected, blank, or unchanged replacement stops the cycle.
Only a later user action or a new session starts another cycle.
Show members Please sign in again.
Do not show error codes or provider bodies.
Chat awaits onFailure and does not automatically retry the turn.
The exchange fields and error envelope are in Configuration.
import type {
CreateAugeoSearchOptions,
SearchAuthError,
SearchAuthFailure,
} from './vendor/search-sdk/index';
import type { TokenBroker } from './vendor/kigo-auth/tokenBroker';
const SIGN_IN_TEXT = 'Please sign in again.';
function recoveringAuth(broker: TokenBroker): CreateAugeoSearchOptions['auth'] {
return {
getToken: () => broker.readToken(),
onFailure: (failure: SearchAuthFailure) => broker.onFailure(failure),
};
}
function legacyAuth(broker: TokenBroker): CreateAugeoSearchOptions['auth'] {
return {
getToken: () => broker.readToken(),
};
}
function finalAuthNotice(status: HTMLElement, _error: SearchAuthError): void {
status.textContent = SIGN_IN_TEXT;
}Switch members
Logout or an account or program change clears the cache and destroys Search. A late response from the old session must not restore credentials or results. Same-member renewal keeps the instance mounted. The next request reads the replacement bearer. Failed renewal shows one sign-in action.
import type {
AugeoSearchInstance,
CreateAugeoSearchOptions,
SearchAuthFailure,
} from './vendor/search-sdk/index';
import type { BrokerSession, TokenBroker } from './vendor/kigo-auth/tokenBroker';
const SIGN_IN_TEXT = 'Please sign in again.';
function fencedAuth(
epoch: number,
currentEpoch: () => number,
broker: TokenBroker,
): CreateAugeoSearchOptions['auth'] {
return {
getToken: () => {
if (epoch !== currentEpoch()) return Promise.reject(new Error('authentication required'));
return broker.readToken();
},
onFailure: (failure: SearchAuthFailure) => {
if (epoch !== currentEpoch()) return;
return broker.onFailure(failure);
},
};
}
async function endSession(search: AugeoSearchInstance, broker: TokenBroker): Promise<void> {
await broker.logout();
search.destroy();
}
async function switchMember(
search: AugeoSearchInstance,
broker: TokenBroker,
session: BrokerSession,
scopeKey: string,
): Promise<AugeoSearchInstance> {
search.destroy();
await broker.changeSession(session);
const target = document.getElementById('search-host');
if (!target) throw new Error('Search mount container is missing.');
return window.AugeoSearchSdk.createAugeoSearch({
target,
apiBaseUrl: 'https://api.augeoai.net',
auth: {
getToken: () => broker.readToken(),
},
capabilities: {
programChat: {
status: 'enabled',
scope: { programId: session.programId, authScopeKey: scopeKey },
},
},
});
}
function keepMountedRenewal(broker: TokenBroker): Promise<void> {
broker.noteUserAction();
return broker.signIn();
}
function showFailedRenewal(status: HTMLElement, broker: TokenBroker): void {
const prompt = broker.signInPrompt();
status.textContent = prompt === null ? SIGN_IN_TEXT : prompt.message;
}Apply controlled visibility with update({ open }).
Call destroy() when the route or member session ends.
Repeated destruction is safe.
Only update() and destroy() are public instance methods.
Control visibility
The initial open value defaults to false.
Clicking or focusing the field requests onOpenChange(true).
The host must apply the requested state with search.update({ open }).
A callback that only records the request leaves the panel closed.
Programmatic visibility uses the same method:
search.update({ open: true });
search.update({ open: false });Manage lifecycle
Call search.destroy() when the host removes the route or ends the member session.
It removes the element, unmounts the UI, and cancels outstanding requests.
Repeated destruction is safe; updates after destruction have no effect.
Create a new instance when a different member or program session starts.
Keep the instance when only the THEO bearer rotates.
Related links
- Option details: Configuration
- Product and chat callbacks: Host integration
- Run acceptance checks: Validation
- Diagnose a closed or empty panel: Troubleshooting