@botonic/core
Version:
Runtime and APIs for Botonic bots: actions, context, messaging, and integration hooks used by the **current** framework line.
157 lines (156 loc) • 6.96 kB
TypeScript
import type { BotonicSession, BotonicSessionBot, BotonicSessionHubtypeCase, BotonicSessionUser, BotonicSessionUserContactInfoItem, UserExtraData } from '@botonic/shared';
import { MessagingChannel } from '@botonic/shared';
import { WebchatClientSettings } from '@botonic/shared';
import { BotonicAction } from './botonic-action';
export type { UserExtraData };
export interface BotonicRequestSessionBasicEntity {
id: string;
name: string;
}
export type BotonicRequestSessionOrganization = BotonicRequestSessionBasicEntity;
export type BotonicRequestSessionBot = BotonicRequestSessionBasicEntity;
export interface BotonicRequestSessionUserContactInfoItem {
name: string;
type: string;
value: string;
description?: string;
}
export interface BotonicRequestSessionChannel {
provider: MessagingChannel;
imp_id?: string;
unformatted_phone_number?: string;
}
export interface BotonicRequestSessionUser<TExtraData extends UserExtraData = UserExtraData> {
id: string;
provider_id: string;
name?: string;
override_name?: string;
extra_data?: TExtraData;
contact_info?: BotonicRequestSessionUserContactInfoItem[];
locale: string;
country: string;
system_locale: string;
}
export interface BotonicRequestSession<TExtraData extends UserExtraData = UserExtraData> {
organization: BotonicRequestSessionOrganization;
bot: BotonicRequestSessionBot;
channel: BotonicRequestSessionChannel;
user: BotonicRequestSessionUser<TExtraData>;
is_test_integration: boolean;
is_first_interaction: boolean;
shadowing: boolean;
flow_thread_id?: string;
had_hubtype_handoff: boolean;
hubtype_case?: BotonicSessionHubtypeCase;
custom: Record<string, any>;
external: Record<string, any>;
webviews_custom: Record<string, any>;
webchat_client_settings: WebchatClientSettings;
}
/**
* Hydrated BotonicSession from Lambda `session`.
* Field names match backend `model_dump(mode="json")` (snake_case).
*/
export interface BotonicSessionUpdate<TExtraData extends UserExtraData = UserExtraData> {
shadowing?: boolean | null;
flowThreadId?: string | null;
custom?: Record<string, unknown>;
webviewsCustom?: Record<string, unknown>;
webchatClientSettings?: Record<string, unknown>;
/** Flow Builder capture node id; maps to `capture_user_input_node_id` on `PATCH …/session/`. */
captureUserInputNodeId?: string | null;
/** Stored as `_botonic_action` on session; not sent on v2 session PATCH. */
botonicAction?: string | null;
/** Maps to `is_first_interaction` on session; included in `PATCH …/session/` when set. */
isFirstInteraction?: boolean;
user?: {
overrideName?: string | null;
extraData?: TExtraData;
locale?: string;
country?: string;
systemLocale?: string;
};
}
/**
* Maps camelCase session updates to snake_case PATCH body (v2 only).
*/
export declare function sessionUpdateToPatchBody<TExtraData extends UserExtraData = UserExtraData>(update: BotonicSessionUpdate<TExtraData>): Record<string, unknown>;
/**
* Mutates `session.raw` immediately so the rest of the turn sees updates.
* Handles `capture_user_input_node_id` (mirror of {@link sessionUpdateToPatchBody}) and
* `_botonic_action` (not sent on session PATCH).
* For `isFirstInteraction`, also updates in-memory `is_first_interaction`; the same
* value is emitted by {@link sessionUpdateToPatchBody} for `PATCH …/session/`.
*/
export declare function applyNonPatchSessionUpdateFields<TExtraData extends UserExtraData = UserExtraData>(session: BotonicSession<TExtraData>, updates: BotonicSessionUpdate<TExtraData>): void;
/**
* Maps `BotonicSessionUpdate.user` to `PATCH …/users/<user_id>/` body (ChatUserPatchSerializer keys, snake_case).
* Unknown keys are omitted — only serializer fields are sent.
*/
export declare function userUpdateToChatUserPatchBody<TExtraData extends UserExtraData = UserExtraData>(user: BotonicSessionUpdate<TExtraData>['user'] | undefined): Record<string, unknown>;
export declare class BotonicContextSessionUser<TExtraData extends UserExtraData = UserExtraData> {
private rawUser;
private readonly onUserUpdate?;
constructor(rawUser: BotonicSessionUser<TExtraData>, onUserUpdate?: ((updates: {
extraData?: TExtraData;
}) => void) | undefined);
get raw(): BotonicSessionUser<TExtraData>;
get id(): string;
get username(): string | undefined;
get name(): string | undefined;
get overrideName(): string | undefined;
get providerId(): string;
get locale(): string;
set locale(v: string);
get country(): string;
set country(v: string);
get systemLocale(): string;
set systemLocale(v: string);
get extraData(): TExtraData | undefined;
set extraData(v: TExtraData | undefined);
get contactInfo(): BotonicSessionUserContactInfoItem[] | undefined;
}
export declare class BotonicContextSession<TExtraData extends UserExtraData = UserExtraData> {
private sessionData;
private onUpdate?;
constructor(sessionData: BotonicSession<TExtraData>);
setOnUpdate(cb: (updates: BotonicSessionUpdate<TExtraData>) => void): void;
/** Replace underlying session object (e.g. after GET session from Hubtype). */
replaceSession(next: BotonicSession<TExtraData>): void;
get raw(): BotonicSession<TExtraData>;
get bot(): BotonicSessionBot;
get user(): BotonicContextSessionUser<TExtraData>;
get organizationId(): string;
get organizationName(): string;
get isFirstInteraction(): boolean;
get botonicAction(): string | undefined;
set botonicAction(v: string | undefined);
isBotonicActionRedirect(): boolean;
getBotonicActionPayload(action: BotonicAction): string | undefined;
get isTestIntegration(): boolean;
get flowThreadId(): string | null | undefined;
get shadowing(): boolean | undefined;
set shadowing(v: boolean | undefined);
get hadHubtypeHandoff(): boolean | undefined;
get hubtypeCase(): BotonicSessionHubtypeCase | undefined;
/** Convenience for legacy code paths; prefer {@link hubtypeCase}. */
get hubtypeCaseId(): string | undefined;
get custom(): Record<string, unknown> | undefined;
get external(): Record<string, unknown> | undefined;
get webviewsCustom(): Record<string, unknown> | undefined;
get webchatClientSettings(): WebchatClientSettings;
/** Flow Builder: node id capturing user input (`capture_user_input_node_id` in JSON). */
get captureUserInputNodeId(): string | undefined;
/** Channel provider (e.g. webchat, whatsapp). */
get provider(): string;
get impId(): string;
get unformattedPhoneNumber(): string | undefined;
isDev(): boolean;
isWebchat(): boolean;
isTelegram(): boolean;
isFacebook(): boolean;
isInstagram(): boolean;
isTwitter(): boolean;
isWhatsapp(): boolean;
hasFlowThreadId(): boolean;
}