@ilivemylife/react-sdk 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,205 @@
+import * as react from 'react';
+
+/** Build the SSO login URL from ssoUrl + optional route/clientId. */
+declare function getSsoLoginUrl(ssoUrl: string, options?: {
+    addTimestamp?: boolean;
+    route?: string;
+    clientId?: string;
+}): string;
+/** Center a popup on screen. */
+declare function popupCenterParams(width: number, height: number): {
+    left: number;
+    top: number;
+};
+/** SECURITY: verify a postMessage event came from the iLML SSO origin. */
+declare function isValidSsoOrigin(event: MessageEvent, ssoUrl: string): boolean;
+
+interface UseIlmlSsoOptions {
+    /** iLML SSO base origin, e.g. "https://ilivemylife.io". */
+    ssoUrl: string;
+    /** Login route under ssoUrl (e.g. "partnerLogin"). */
+    ssoRoute?: string;
+    /** Client id passed to the wallet for per-partner branding (not a security boundary). */
+    clientId?: string;
+    /**
+     * Called with the iLML SSO payload `event.data.data` (`{ accessToken, ...user }`)
+     * on successful login. The consumer app decides what to do (exchange for its own
+     * token, set auth state, etc.). Return value is ignored.
+     */
+    onSsoData: (data: {
+        accessToken?: string;
+        [k: string]: unknown;
+    }) => void | Promise<void>;
+    /** Called on loginError / signupError from the popup. */
+    onError?: (kind: 'loginError' | 'signupError') => void;
+    /** Called when the login popup is closed WITHOUT a successful login — the user canceled it, or the
+     *  browser blocked it. Lets the consumer clear a "signing in…" state deterministically instead of
+     *  guessing via window focus + timers. NOT fired on success (the hook closes the popup itself). */
+    onClose?: () => void;
+    /** Success type sent by iLML (default "loginSuccess"). */
+    responseType?: string;
+    windowName?: string;
+    width?: number;
+    height?: number;
+}
+declare function useIlmlSso(opts: UseIlmlSsoOptions): {
+    openLogin: () => void;
+};
+
+interface IlmlChatProps {
+    /** iLML SSO/app base origin, e.g. "https://ilivemylife.io". */
+    ssoUrl: string;
+    /** The graph node whose chat to embed (resolved by the consuming app). */
+    nodeId: string;
+    /**
+     * iLML wallet access token, used by the embed when Storage Access API isn't
+     * available. Defaults to localStorage "walletAccessToken" (set by useIlmlSso).
+     */
+    token?: string | null;
+    /**
+     * Optional readiness gate. A just-created (or just-granted) node lands in the read model a moment
+     * after the command succeeds; the embed crashes if it queries the node before then. When provided,
+     * the token handshake polls this until it resolves true (bounded ~15s) before handing the token
+     * over, so the embed only initialises once the node is readable. Omit for already-existing nodes.
+     */
+    isNodeReady?: (nodeId: string) => Promise<boolean>;
+    /** Optional style/class for the iframe wrapper. */
+    className?: string;
+    style?: React.CSSProperties;
+}
+/**
+ * Renders the iLML chat for `nodeId` as a sandboxed iframe and performs the
+ * `messengerReady` -> `initMessenger` token handshake. Origin is verified before
+ * any postMessage is sent. Waits for `isNodeReady` (when given) before handing over the token.
+ * Shows a loading overlay until the messenger is ready — covers both the iframe's own load and the
+ * `isNodeReady` wait, so the user sees progress instead of a blank white frame.
+ */
+declare function IlmlChat({ ssoUrl, nodeId, token, isNodeReady, className, style }: IlmlChatProps): react.JSX.Element;
+
+interface IlmlChatWidgetProps {
+    /** iLML SSO/app base origin. */
+    ssoUrl: string;
+    /** The conversation node to embed. */
+    nodeId: string;
+    /** Wallet access token; defaults to localStorage "walletAccessToken". */
+    token?: string | null;
+    /** Header label — usually the counterpart / conversation name. */
+    title?: string;
+    /** Close the widget (the owner removes it from its dock). Omit to hide the control. */
+    onClose?: () => void;
+    /** Minimize (the owner collapses it to a bar). Omit to hide the control. */
+    onMinimize?: () => void;
+    /** Readiness gate forwarded to IlmlChat — see IlmlChatProps.isNodeReady. */
+    isNodeReady?: (nodeId: string) => Promise<boolean>;
+    /** Show the expand-to-fullscreen control. Default true. */
+    allowFullscreen?: boolean;
+    /** Show the "full height" control — stretches the docked box to fill the viewport height at the SAME
+     *  width (unlike fullscreen, which fills width too). Default true. */
+    allowTall?: boolean;
+    /** Header background (partner brand colour). Default iLML blue. */
+    accentColor?: string;
+    /** Docked-state box className/style (the owner may resize/position). Ignored when expanded. */
+    className?: string;
+    style?: React.CSSProperties;
+}
+declare function IlmlChatWidget({ ssoUrl, nodeId, token, title, onClose, onMinimize, isNodeReady, allowFullscreen, allowTall, accentColor, className, style, }: IlmlChatWidgetProps): react.JSX.Element;
+
+interface IlmlButtonProps {
+    /** If set, renders an <a> to this href; otherwise a <button>. */
+    href?: string;
+    onClick?: () => void;
+    disabled?: boolean;
+    target?: string;
+    rel?: string;
+    type?: 'button' | 'submit';
+    className?: string;
+    style?: React.CSSProperties;
+    children: React.ReactNode;
+}
+declare function IlmlButton({ href, onClick, disabled, target, rel, type, className, style, children, }: IlmlButtonProps): react.JSX.Element;
+
+interface IlmlProfile {
+    /** User id in the graph. */
+    id?: string;
+    /** Display name (falls back to fullName/email). */
+    name: string;
+    /** Avatar image URL, if the user has one. */
+    avatar?: string;
+    email?: string;
+}
+interface UseIlmlProfileOptions {
+    /** iLML graphql endpoint, e.g. "https://api.ilivemylife.io/graphql/v1" (default). */
+    graphqlUrl?: string;
+}
+/**
+ * Fetch the current user's profile for a wallet access token.
+ * `profile: null` while loading, without a token, or on failure. `invalid: true` marks a DEFINITIVE
+ * bad/expired token so the consumer can clear it (sign out); transient errors leave `invalid: false`.
+ */
+declare function useIlmlProfile(token: string | null | undefined, opts?: UseIlmlProfileOptions): {
+    profile: IlmlProfile | null;
+    loading: boolean;
+    invalid: boolean;
+};
+
+interface UseIlmlSessionOptions {
+    /** iLML SSO/app base origin (login popup + deep links). */
+    ssoUrl: string;
+    /** Login route under ssoUrl (e.g. "partnerLogin"). */
+    ssoRoute?: string;
+    /** Client id for per-partner login branding (not a security boundary). */
+    clientId?: string;
+    /** iLML graphql endpoint — resolves the token into `me`. */
+    graphqlUrl: string;
+    /** App-specific side-effect run once per DISTINCT token (onboarding, analytics). The token is set
+     *  regardless of the result; return a Promise and a REJECTION lets a later navigation retry (the
+     *  token is un-remembered), so a transient onboarding failure isn't permanent for the session. */
+    onNewToken?: (token: string) => void | Promise<void>;
+    /** localStorage key for the wallet token. Defaults to 'walletAccessToken' — the SAME key useIlmlSso
+     *  writes on login, so the store reads exactly what the handshake saved. */
+    tokenKey?: string;
+    /** localStorage key for the cached profile (instant chip paint after reload). */
+    profileKey?: string;
+    /** Called when the login popup closes WITHOUT signing in (cancel / blocked). */
+    onLoginClose?: () => void;
+}
+/** Imperative sign-out for non-React code (a transport layer that saw a dead token). Clears the same
+ *  singleton the hooks read, so the account chip and everything else update. */
+declare function signOutIlmlSession(): void;
+/** The wallet token this browser currently holds (or null) — for non-React callers. */
+declare function getIlmlToken(): string | null;
+/** Read-only view of the shared session (token + profile). */
+interface IlmlSessionState {
+    /** The wallet token, or null when signed out. */
+    token: string | null;
+    isLoggedIn: boolean;
+    /** True once the token has been read from storage — gate UI on this to avoid a sign-in flash. */
+    ready: boolean;
+    /** The signed-in user (name/avatar/email), shared across all consumers; null while loading/out. */
+    profile: IlmlProfile | null;
+    profileLoading: boolean;
+    /** True when the token is DEFINITIVELY bad (already cleared) — vs a transient fetch error. */
+    profileInvalid: boolean;
+}
+interface IlmlSession extends IlmlSessionState {
+    /** Open the login popup. */
+    login: () => void;
+    /** Clear the session everywhere. */
+    logout: () => void;
+}
+/**
+ * Read the shared session (token + profile) WITHOUT instantiating the login handshake — for consumers
+ * that only display session state (account chips, gated links, dashboards). A full useIlmlSession()
+ * must be mounted somewhere in the app to supply config and drive login. One `me` fetch is shared
+ * across every useIlmlSessionState + useIlmlSession consumer.
+ */
+declare function useIlmlSessionState(): IlmlSessionState;
+/**
+ * Site-wide iLML session (token + profile) PLUS login/logout, shared across every consumer in the
+ * app. Login/logout from any surface propagates to all of them. Pass config once; later calls reuse
+ * the singleton. Instantiate this where login is driven (e.g. the header); elsewhere prefer the
+ * lighter useIlmlSessionState().
+ */
+declare function useIlmlSession(opts: UseIlmlSessionOptions): IlmlSession;
+
+export { IlmlButton, type IlmlButtonProps, IlmlChat, type IlmlChatProps, IlmlChatWidget, type IlmlChatWidgetProps, type IlmlProfile, type IlmlSession, type IlmlSessionState, type UseIlmlProfileOptions, type UseIlmlSessionOptions, type UseIlmlSsoOptions, getIlmlToken, getSsoLoginUrl, isValidSsoOrigin, popupCenterParams, signOutIlmlSession, useIlmlProfile, useIlmlSession, useIlmlSessionState, useIlmlSso };

package/dist/index.d.ts

@@ -0,0 +1,205 @@
+import * as react from 'react';
+
+/** Build the SSO login URL from ssoUrl + optional route/clientId. */
+declare function getSsoLoginUrl(ssoUrl: string, options?: {
+    addTimestamp?: boolean;
+    route?: string;
+    clientId?: string;
+}): string;
+/** Center a popup on screen. */
+declare function popupCenterParams(width: number, height: number): {
+    left: number;
+    top: number;
+};
+/** SECURITY: verify a postMessage event came from the iLML SSO origin. */
+declare function isValidSsoOrigin(event: MessageEvent, ssoUrl: string): boolean;
+
+interface UseIlmlSsoOptions {
+    /** iLML SSO base origin, e.g. "https://ilivemylife.io". */
+    ssoUrl: string;
+    /** Login route under ssoUrl (e.g. "partnerLogin"). */
+    ssoRoute?: string;
+    /** Client id passed to the wallet for per-partner branding (not a security boundary). */
+    clientId?: string;
+    /**
+     * Called with the iLML SSO payload `event.data.data` (`{ accessToken, ...user }`)
+     * on successful login. The consumer app decides what to do (exchange for its own
+     * token, set auth state, etc.). Return value is ignored.
+     */
+    onSsoData: (data: {
+        accessToken?: string;
+        [k: string]: unknown;
+    }) => void | Promise<void>;
+    /** Called on loginError / signupError from the popup. */
+    onError?: (kind: 'loginError' | 'signupError') => void;
+    /** Called when the login popup is closed WITHOUT a successful login — the user canceled it, or the
+     *  browser blocked it. Lets the consumer clear a "signing in…" state deterministically instead of
+     *  guessing via window focus + timers. NOT fired on success (the hook closes the popup itself). */
+    onClose?: () => void;
+    /** Success type sent by iLML (default "loginSuccess"). */
+    responseType?: string;
+    windowName?: string;
+    width?: number;
+    height?: number;
+}
+declare function useIlmlSso(opts: UseIlmlSsoOptions): {
+    openLogin: () => void;
+};
+
+interface IlmlChatProps {
+    /** iLML SSO/app base origin, e.g. "https://ilivemylife.io". */
+    ssoUrl: string;
+    /** The graph node whose chat to embed (resolved by the consuming app). */
+    nodeId: string;
+    /**
+     * iLML wallet access token, used by the embed when Storage Access API isn't
+     * available. Defaults to localStorage "walletAccessToken" (set by useIlmlSso).
+     */
+    token?: string | null;
+    /**
+     * Optional readiness gate. A just-created (or just-granted) node lands in the read model a moment
+     * after the command succeeds; the embed crashes if it queries the node before then. When provided,
+     * the token handshake polls this until it resolves true (bounded ~15s) before handing the token
+     * over, so the embed only initialises once the node is readable. Omit for already-existing nodes.
+     */
+    isNodeReady?: (nodeId: string) => Promise<boolean>;
+    /** Optional style/class for the iframe wrapper. */
+    className?: string;
+    style?: React.CSSProperties;
+}
+/**
+ * Renders the iLML chat for `nodeId` as a sandboxed iframe and performs the
+ * `messengerReady` -> `initMessenger` token handshake. Origin is verified before
+ * any postMessage is sent. Waits for `isNodeReady` (when given) before handing over the token.
+ * Shows a loading overlay until the messenger is ready — covers both the iframe's own load and the
+ * `isNodeReady` wait, so the user sees progress instead of a blank white frame.
+ */
+declare function IlmlChat({ ssoUrl, nodeId, token, isNodeReady, className, style }: IlmlChatProps): react.JSX.Element;
+
+interface IlmlChatWidgetProps {
+    /** iLML SSO/app base origin. */
+    ssoUrl: string;
+    /** The conversation node to embed. */
+    nodeId: string;
+    /** Wallet access token; defaults to localStorage "walletAccessToken". */
+    token?: string | null;
+    /** Header label — usually the counterpart / conversation name. */
+    title?: string;
+    /** Close the widget (the owner removes it from its dock). Omit to hide the control. */
+    onClose?: () => void;
+    /** Minimize (the owner collapses it to a bar). Omit to hide the control. */
+    onMinimize?: () => void;
+    /** Readiness gate forwarded to IlmlChat — see IlmlChatProps.isNodeReady. */
+    isNodeReady?: (nodeId: string) => Promise<boolean>;
+    /** Show the expand-to-fullscreen control. Default true. */
+    allowFullscreen?: boolean;
+    /** Show the "full height" control — stretches the docked box to fill the viewport height at the SAME
+     *  width (unlike fullscreen, which fills width too). Default true. */
+    allowTall?: boolean;
+    /** Header background (partner brand colour). Default iLML blue. */
+    accentColor?: string;
+    /** Docked-state box className/style (the owner may resize/position). Ignored when expanded. */
+    className?: string;
+    style?: React.CSSProperties;
+}
+declare function IlmlChatWidget({ ssoUrl, nodeId, token, title, onClose, onMinimize, isNodeReady, allowFullscreen, allowTall, accentColor, className, style, }: IlmlChatWidgetProps): react.JSX.Element;
+
+interface IlmlButtonProps {
+    /** If set, renders an <a> to this href; otherwise a <button>. */
+    href?: string;
+    onClick?: () => void;
+    disabled?: boolean;
+    target?: string;
+    rel?: string;
+    type?: 'button' | 'submit';
+    className?: string;
+    style?: React.CSSProperties;
+    children: React.ReactNode;
+}
+declare function IlmlButton({ href, onClick, disabled, target, rel, type, className, style, children, }: IlmlButtonProps): react.JSX.Element;
+
+interface IlmlProfile {
+    /** User id in the graph. */
+    id?: string;
+    /** Display name (falls back to fullName/email). */
+    name: string;
+    /** Avatar image URL, if the user has one. */
+    avatar?: string;
+    email?: string;
+}
+interface UseIlmlProfileOptions {
+    /** iLML graphql endpoint, e.g. "https://api.ilivemylife.io/graphql/v1" (default). */
+    graphqlUrl?: string;
+}
+/**
+ * Fetch the current user's profile for a wallet access token.
+ * `profile: null` while loading, without a token, or on failure. `invalid: true` marks a DEFINITIVE
+ * bad/expired token so the consumer can clear it (sign out); transient errors leave `invalid: false`.
+ */
+declare function useIlmlProfile(token: string | null | undefined, opts?: UseIlmlProfileOptions): {
+    profile: IlmlProfile | null;
+    loading: boolean;
+    invalid: boolean;
+};
+
+interface UseIlmlSessionOptions {
+    /** iLML SSO/app base origin (login popup + deep links). */
+    ssoUrl: string;
+    /** Login route under ssoUrl (e.g. "partnerLogin"). */
+    ssoRoute?: string;
+    /** Client id for per-partner login branding (not a security boundary). */
+    clientId?: string;
+    /** iLML graphql endpoint — resolves the token into `me`. */
+    graphqlUrl: string;
+    /** App-specific side-effect run once per DISTINCT token (onboarding, analytics). The token is set
+     *  regardless of the result; return a Promise and a REJECTION lets a later navigation retry (the
+     *  token is un-remembered), so a transient onboarding failure isn't permanent for the session. */
+    onNewToken?: (token: string) => void | Promise<void>;
+    /** localStorage key for the wallet token. Defaults to 'walletAccessToken' — the SAME key useIlmlSso
+     *  writes on login, so the store reads exactly what the handshake saved. */
+    tokenKey?: string;
+    /** localStorage key for the cached profile (instant chip paint after reload). */
+    profileKey?: string;
+    /** Called when the login popup closes WITHOUT signing in (cancel / blocked). */
+    onLoginClose?: () => void;
+}
+/** Imperative sign-out for non-React code (a transport layer that saw a dead token). Clears the same
+ *  singleton the hooks read, so the account chip and everything else update. */
+declare function signOutIlmlSession(): void;
+/** The wallet token this browser currently holds (or null) — for non-React callers. */
+declare function getIlmlToken(): string | null;
+/** Read-only view of the shared session (token + profile). */
+interface IlmlSessionState {
+    /** The wallet token, or null when signed out. */
+    token: string | null;
+    isLoggedIn: boolean;
+    /** True once the token has been read from storage — gate UI on this to avoid a sign-in flash. */
+    ready: boolean;
+    /** The signed-in user (name/avatar/email), shared across all consumers; null while loading/out. */
+    profile: IlmlProfile | null;
+    profileLoading: boolean;
+    /** True when the token is DEFINITIVELY bad (already cleared) — vs a transient fetch error. */
+    profileInvalid: boolean;
+}
+interface IlmlSession extends IlmlSessionState {
+    /** Open the login popup. */
+    login: () => void;
+    /** Clear the session everywhere. */
+    logout: () => void;
+}
+/**
+ * Read the shared session (token + profile) WITHOUT instantiating the login handshake — for consumers
+ * that only display session state (account chips, gated links, dashboards). A full useIlmlSession()
+ * must be mounted somewhere in the app to supply config and drive login. One `me` fetch is shared
+ * across every useIlmlSessionState + useIlmlSession consumer.
+ */
+declare function useIlmlSessionState(): IlmlSessionState;
+/**
+ * Site-wide iLML session (token + profile) PLUS login/logout, shared across every consumer in the
+ * app. Login/logout from any surface propagates to all of them. Pass config once; later calls reuse
+ * the singleton. Instantiate this where login is driven (e.g. the header); elsewhere prefer the
+ * lighter useIlmlSessionState().
+ */
+declare function useIlmlSession(opts: UseIlmlSessionOptions): IlmlSession;
+
+export { IlmlButton, type IlmlButtonProps, IlmlChat, type IlmlChatProps, IlmlChatWidget, type IlmlChatWidgetProps, type IlmlProfile, type IlmlSession, type IlmlSessionState, type UseIlmlProfileOptions, type UseIlmlSessionOptions, type UseIlmlSsoOptions, getIlmlToken, getSsoLoginUrl, isValidSsoOrigin, popupCenterParams, signOutIlmlSession, useIlmlProfile, useIlmlSession, useIlmlSessionState, useIlmlSso };