@rainbird/sdk-react

    1.3.0 • Public • Published

    @rainbird/sdk-react

    pipeline status coverage status

    A package full of React components, hooks, and decorators to ease your way into Rainbird.

    Installation

        yarn add @rainbird/sdk-react
        npm i @rainbird/sdk-react

    Usage

    context | hooks | components | decorators | helpers

    Name Type Description Example/Help
    baseURL String The url to be targeted without any params 'https://api.rainbird.ai'
    apiKey String The api key that allows access to the api This can be found in the 'account' section of the Rainbird Studio
    kmID String The ID of the specific knowledge map that you will query This can be found in the map view of the Rainbird Studio
    factID String The id of the resulting answer from Rainbird This can be found in from the response endpoint from a RESULT type
    evidenceKey String A key to gain access to secured evidence This can be found in the map view of the Rainbird Studio
    options Object (optional) Options provided to Rainbird, currently used to interact with different versions of the engine { engine: 'v2.0' }

    Context

    RainbirdProvider | InteractionProvider | RainbirdContext | InteractionContext

    In order to use any of the hooks, components or decorators in this package they need to be a descendent of a RainbirdContext. Some of the hooks/components/decorators concerning the back-and-forth questioning of Rainbird also need to be a descendent of an InteractionContext as explained below. To make this easier, you can use a RainbirdProvider and InteractionProvider rather than setting the context directly.

    RainbirdProvider

    The RainbirdProvider wraps the RainbirdContext which stores API config info. It's used by the start hook to store the sessionID for later requests. Click here to learn more about the Rainbird API.

    import { RainbirdProvider } from '@rainbird/sdk-react';
    
    export default () => (
        <RainbirdProvider
            baseURL="https://api.rainbird.ai"
            apiKey="myApiKey"
            kmID="myKmId"
            options={{ engine: 'v2.0' }}
        >
            <p>Hello!</p>
        </RainbirdProvider>
    )
    InteractionProvider

    The InteractionProvider wraps the InteractionContext and sends the contents of a query or response call to Rainbird to its direct child, as well as a loading and error state. The InteractionProvider can be instantiated anywhere in the tree, so long as it's a descendent of the RainbirdProvider. For more info on the shape of the data returned from a query or response, click here

    import { RainbirdProvider, InteractionProvider } from '@rainbird/sdk-react';
    
    export default () => (
        <RainbirdProvider
            baseURL="https://api.rainbird.ai"
            apiKey="myApiKey"
            kmID="myKmId"
            options={{ engine: 'v2.0' }}
        >
            <InteractionProvider >
                {({data, loading, error}) => (
                    // ...
                )}
            </InteractionProvider>
        </RainbirdProvider>
    )
    RainbirdContext

    The RainbirdContext can be accessed directly using React.useContext if you need to extract any information about the sessionID, kmID, baseURL or apiKey

    import React, { useContext } from 'react'
    import { RainbirdContext } from '@rainbird/sdk-react';
    
    export default () => {
        const { apiKey, baseURL, kmID, sessionID } = useContext(RainbirdContext)
    
        return (
            // ...
        )
    }
    InteractionContext

    The InteractionContext can be accessed directly using React.useContext if you need to extract any information about the current interaction. However, there is a hook and a decorator available to make this easier.

    import React, { useContext } from 'react'
    import { InteractionContext } from '@rainbird/sdk-react';
    
    export default () => {
        const { data, loading, error } = useContext(InteractionContext)
    
        return (
            // ...
        )
    }

    Hooks

    useStart | useQuery | useInject | useResponse | useUndo | useEvidence | useInteraction

    useStart

    Invoked immediately on mount and responds to changing arguments. Returns data, loading and error state.

    import React from 'react'
    import { RainbirdProvider, useStart } from '@rainbird/sdk-react';
    
    const Start = ({ children }) => {
        const { data, loading, error } = useStart();
    
        return (
            <div>
                {loading && <Loading />}
                {error && <Error />}
                {data && children}
            </div>
        )
    }
    
    export const App = (props) => (
        <RainbirdProvider {...props}>
            <Start>
                <p>Session started!</p>
            </Start>
        </RainbirdProvider>
    )
    useQuery

    Invoked immediately on mount. Returns data, loading and error state. Needs to be a descendent of an InteractionProvider.

    import React from 'react'
    import { RainbirdProvider, InteractionProvider, useQuery } from '@rainbird/sdk-react';
    
    const Query = ({ children }) => {
        const { data, loading, error } = useQuery();
    
        return (
            <div>
                {loading && <Loading />}
                {error && <Error />}
                {data && children}
            </div>
        )
    }
    
    export const App = (props) => (
        <RainbirdProvider {...props}>
            <InteractionProvider>
                <Start>
                    <Query>
                        <p>Query started!</p>
                    </Query>
                </Start>
            </InteractionProvider>
        </RainbirdProvider>
    )
    useInject

    Returns the state of the inject api call as well as a function to send facts.

    import React from 'react'
    import { RainbirdProvider, useInject } from '@rainbird/sdk-react';
    
    const Inject = () => {
        const [inject, sendInject] = useInject();
    
        return (
            <div>
                {inject.loading && <Loading />}
                {inject.error && <Error />}
                {inject.data && inject.data.ok && <p>Success!</p>}
                <button onClick={() => sendInject([{ subject: 'Bob', relationship: 'speaks', object: 'French', cf: 100}])}>
            </div>
        )
    }
    
    export const App = (props) => (
        <RainbirdProvider {...props}>
             <Inject />
        </RainbirdProvider>
    )
    useResponse

    Returns a function to send a response to Rainbird. Needs to be a descendent of an InteractionProvider which will return the data, loading and error state of the interaction (useInteraction is used here to access the InteractionContext).

    import React from 'react'
    import { RainbirdProvider, InteractionProvider, useResponse, useInteraction } from '@rainbird/sdk-react';
    
    const Respond = () => {
        const { data, loading, error } = useInteraction()
        const sendResponse = useResponse();
    
        return (
            <div>
                {loading && <Loading />}
                {error && <Error />}
                {data && data.ok && <p>Success!</p>}
                <button onClick={() => sendResponse([{ subject: 'Bob', relationship: 'speaks', object: 'French', cf: 100}])}>Respond</button>
            </div>
        )
    }
    
    export const App = (props) => (
        <RainbirdProvider {...props}>
            <Start>
                <InteractionProvider>
                    <Query>
                        <Respond />
                    </Query>
                </InteractionProvider>
            </Start>
        </RainbirdProvider>
    )
    useUndo

    Returns a function to undo a response sent to Rainbird. Needs to be a descendent of an InteractionProvider which will return the data, loading and error state of the interaction.

    import React from 'react'
    import { RainbirdProvider, useResponse, useInteraction, useUndo } from '@rainbird/sdk-react';
    
    const RespondAndUndo = () => {
        const { data, loading, error } = useInteraction()
        const sendResponse = useResponse();
        const undo = useUndo()
    
        return (
            <div>
                {loading && <Loading />}
                {error && <Error />}
                {data && data.ok && <p>Success!</p>}
                <button onClick={undo}>Undo</button>
                <button onClick={() => sendResponse([{ subject: 'Bob', relationship: 'speaks', object: 'French', cf: 100}])}>Respond</button>
            </div>
        )
    }
    
    export const App = (props) => (
        <RainbirdProvider {...props}>
            <Start>
                <Query>
                    <RespondAndUndo />
                </Query>
            </Start>
        </RainbirdProvider>
    )
    useEvidence

    Returns the state of the api call as well as a function to call the evidence endpoint.

    import React from 'react'
    import { RainbirdProvider, useEvidence } from '@rainbird/sdk-react';
    
    const Evidence = () => {
        const [evidence, getEvidence] = useEvidence()
    
        return (
            <div>
                {evidence.loading && <Loading />}
                {evidence.error && <Error />}
                {evidence.data && <p>Success!</p>}
                <button onClick={() => getEvidence(factID, evidenceKey?)}>Evidence</button>
            </div>
        )
    }
    
    export const App = (props) => (
        <RainbirdProvider {...props}>
            <Start>
                <Query>
                    <Evidence />
                </Query>
            </Start>
        </RainbirdProvider>
    )
    useInteraction

    Returns the current state of the interaction anywhere in the tree. Must be a descendent of an InteractionProvider.

    import React from 'react'
    import { RainbirdProvider, InteractionProvider, useInteraction } from '@rainbird/sdk-react';
    
    const Interaction = () => {
        const { data, loading, error } = useInteraction()
    
        return (
            <div>
                {loading && <Loading />}
                {error && <Error />}
                {data && <p>Success!</p>}
            </div>
        )
    }
    
    export const App = (props) => (
        <RainbirdProvider {...props}>
            <Start>
                <InteractionProvider>
                    <Interaction />
                </InteractionProvider>
            </Start>
        </RainbirdProvider>
    )

    Decorators

    withStart | withQuery | withInject | withResponse | withUndo | withEvidence | withInteraction

    All the decorators follow the same pattern as the hooks, however they are initialised differently. Rather than instantiating the hooks within the component, the state/functions that are returned from the hooks are injected. This may make testing easier as it's easier to mock the prop in the component.

    withStart
    import React from 'react'
    import { RainbirdProvider, withStart } from '@rainbird/sdk-react';
    
    const Interaction = withStart(({ start }) =>  (
        <div>
            {start.loading && <Loading />}
            {start.error && <Error />}
            {start.data && <p>Success!</p>}
        </div>
    ))
    
    
    export const App = (props) => (
        <RainbirdProvider {...props}>
            <Start/>
        </RainbirdProvider>
    )
    withQuery
    import React from 'react'
    import { RainbirdProvider, InteractionProvider, withQuery } from '@rainbird/sdk-react';
    
    const Query = withQuery(({ query }) =>  (
        <div>
            {query.loading && <Loading />}
            {query.error && <Error />}
            {query.data && <p>Success!</p>}
        </div>
    ))
    
    export const App = (props) => (
        <RainbirdProvider {...props}>
            <InteractionProvider>
                <Start>
                    <Query/>
                </Start>
            </InteractionProvider>
        </RainbirdProvider>
    )
    withInject
    import React from 'react'
    import { RainbirdProvider, InteractionProvider, withInject } from '@rainbird/sdk-react';
    
    const Inject = withInject(({ inject, sendInject }) =>  (
        <div>
            {inject.loading && <Loading />}
            {inject.error && <Error />}
            {inject.data && <p>Success!</p>}
            <button onClick={() => sendInject([{ subject: 'Bob', relationship: 'speaks', object: 'English' }])}>Inject</button>
        </div>
    ))
    
    export const App = (props) => (
        <RainbirdProvider {...props}>
            <InteractionProvider>
                <Start>
                    <Inject>
                </Start>
            </InteractionProvider>
        </RainbirdProvider>
    )
    withResponse
    import React from 'react'
    import { RainbirdProvider, InteractionProvider, withResponse } from '@rainbird/sdk-react';
    
    const Respond = withResponse(({ sendResponse }) =>  (
        <div>
            <button onClick={() => sendResponnse([{ subject: 'Bob', relationship: 'speaks', object: 'English' }])}>Inject</button>
        </div>
    ))
    
    export const App = (props) => (
        <RainbirdProvider {...props}>
            <InteractionProvider>
                <Start>
                    <Query>
                        <Respond />
                    </Query>
                </Start>
            </InteractionProvider>
        </RainbirdProvider>
    )
    withUndo
    import React from 'react'
    import { RainbirdProvider, InteractionProvider, withUndo } from '@rainbird/sdk-react';
    
    const Undo = withUndo(({ undo }) =>  (
        <div>
            <button onClick={undo}>Inject</button>
        </div>
    ))
    
    export const App = (props) => (
        <RainbirdProvider {...props}>
            <InteractionProvider>
                <Start>
                    <Query>
                        <Undo />
                    </Query>
                </Start>
            </InteractionProvider>
        </RainbirdProvider>
    )
    withEvidence
    import React from 'react'
    import { RainbirdProvider, InteractionProvider, withEvidence } from '@rainbird/sdk-react';
    
    const Evidence = withEvidence(({ evidence, getEvidence, factID = '100sdXX0302' }) =>  (
        <div>
            {evidence.loading && <Loading />}
            {evidence.error && <Error />}
            {evidence.data && <Success data={evidence.data} />}
            <button onClick={() => getEvidence(factID, evidenceKey?)}>Inject</button>
        </div>
    ))
    
    export const App = (props) => (
        <RainbirdProvider {...props}>
            <Start>
                <Evidence />
            </Start>
        </RainbirdProvider>
    )
    withInteraction
    import React from 'react'
    import { RainbirdProvider, InteractionProvider, withInteraction } from '@rainbird/sdk-react';
    
    const Interaction = withInteraction(({ interaction }) =>  (
        <div>
            {interaction.loading && <Loading />}
            {interaction.error && <Error />}
            {interaction.data && <Success data={interaction.data} />}
        </div>
    ))
    
    export const App = (props) => (
        <RainbirdProvider {...props}>
            <InteractionProvider>
                <Start>
                    <Interaction />
                </Start>
            </InteractionProvider>
        </RainbirdProvider>
    )

    Components

    Start | Query | Inject | Response | Undo | Evidence | Interaction | FormControl | Rainbird

    The components that follow the naming convention of the api (start, query, inject, response, undo and evidence) follow the same pattern as the hooks and decorators in what they return. They are initialised as follows:

    Start
    import React from 'react'
    import { RainbirdProvider, Start } from '@rainbird/sdk-react';
    
    export const App = (props) => (
        <RainbirdProvider {...props}>
            <Start>
                {({loading, error, data}) => (
                    // ...
                )}
            </Start>
        </RainbirdProvider>
    )
    Query
    import React from 'react'
    import { RainbirdProvider, Start, Query } from '@rainbird/sdk-react';
    
    export const App = (props) => (
        <RainbirdProvider {...props}>
            <InteractionProvider>
                {({data, loading, error}) => (
                    <Start>
                        {(start) => (
                            <Query>
                                {() => {
                                    if (loading) return <Loading>
                                    // ...
                                }}
                            </Query>
                        )}
                    </Start>
                )}
            </InteractionProvider>
        </RainbirdProvider>
    )
    Inject
    import React from 'react'
    import { RainbirdProvider, Start, Inject } from '@rainbird/sdk-react';
    
    export const App = (props) => (
        <RainbirdProvider {...props}>
            <InteractionProvider>
                {(interaction) => (
                    <Start>
                        {(start) => (
                            <Inject>
                                {({data, loading, error, request}) => {
                                    if (loading) return <Loading />
                                    if (error) return <Error />
                                    if (data) return <Success />
                                    return <button onClick={
                                        () => request(
                                            [{
                                                subject: 'Bob',
                                                relationship: 'speaks',
                                                object: 'French',
                                                cf: 100
                                            }]
                                        )}>
                                        inject
                                    </button>
                                }}
                            </Inject>
                        )}
                    </Start>
                )}
            </InteractionProvider>
        </RainbirdProvider>
    )
    Response
    import React from 'react'
    import { RainbirdProvider, Start, Query, Response } from '@rainbird/sdk-react';
    
    export const App = (props) => (
        <RainbirdProvider {...props}>
            <InteractionProvider>
                {({ data, loading, error }) => (
                    <Start>
                        {(start) => (
                            <Query>
                                {() => (
                                    <Response>
                                        {response => (
                                            <button onClick={
                                                () => request([{
                                                        subject: 'Bob',
                                                        relationship: 'speaks',
                                                        object: 'French',
                                                        cf: 100 }]
                                                  )}>response</button>
                                        )}
                                    </Response>
                                )}
                            </Query>
                        )}
                    </Start>
                )}
            </InteractionProvider>
        </RainbirdProvider>
    )
    Undo
    import React from 'react'
    import { RainbirdProvider, Start, Query, Undo } from '@rainbird/sdk-react';
    
    export const App = (props) => (
        <RainbirdProvider {...props}>
            <InteractionProvider>
                {({ data, loading, error }) => (
                    <Start>
                        {(start) => (
                            <Query>
                                {() => (
                                    <Undo>
                                        {undo => <button onClick={undo}>Undo</button>}
                                    </Undo>
                                )}
                            </Query>
                        )}
                    </Start>
                )}
            </InteractionProvider>
        </RainbirdProvider>
    )
    Evidence
    import React from 'react'
    import { RainbirdProvider, Start, Evidence } from '@rainbird/sdk-react';
    
    export const App = (props) => (
        <RainbirdProvider {...props}>
            <InteractionProvider>
                {(interaction) => (
                    <Start>
                        {(start) => (
                            <Evidence>
                                {({data, loading, error, request}) => {
                                    if (loading) return <Loading />
                                    if (error) return <Error />
                                    if (data) return <Success />
                                    return (
                                        <button onClick={() => request(factID, evidenceKey?)}>
                                            Evidence
                                        </button>
                                    )}}
                            </Evidence>
                        )}
                    </Start>
                )}
            </InteractionProvider>
        </RainbirdProvider>
    )
    Interaction
    import React from 'react'
    import { RainbirdProvider, Start, Interaction } from '@rainbird/sdk-react';
    
    export const App = (props) => (
        <RainbirdProvider {...props}>
            <InteractionProvider>
                {(interaction) => (
                    <Start>
                        {(start) => (
                            <Interaction>
                                {({ data, loading, error }) => {
                                    if (loading) return <Loading />
                                    if (error) return <Error />
                                    if (data) return <Success />
                            </Interaction>
                        )}
                    </Start>
                )}
            </InteractionProvider>
        </RainbirdProvider>
    )
    FormControl

    Deciding the correct form input to present can be difficult with the response data. The following component accepts the data from a response to determine which control to present to the user. If this is too rigid, there is a helper method which this is based on that is more flexible.

    Prop Explanation
    multiString The user can select multiple strings from a predetermined list. For example, the user can select 'French', 'English' and 'German'
    multiStringAdd The user can select multiple strings and add their own. For example, the user can select 'French', 'English', 'German' but the user can also add 'Afrikaans'
    singleString The user can only select one string from a predetermined list.
    singleStringAdd The user can only select one string from a predetermined list, but can also add their own.
    singleDate The user can select one date
    singleNumber The user can select one number
    singleTruth The user can make one boolean choice
    certaintySelect The user can choose a number from 1-100 to represent the certainty of their decision. Only appears when allowCF: true is returned on the response.
    import React from 'react';
    import { FormControl } from '@rainbird/sdk-react';
    
    export const Form = ({ data }) => {
        const [value, setValue] = React.useState('')
    
        const handleChange = e => setValue(e.target.value)
    
        return (
            <FormControl
                data={data}
                multiString={<Input onChange={handleChange} value={value} />}
                multiStringAdd={<Input onChange={handleChange} value={value} />}
                singleString={<Input onChange={handleChange} value={value} />}
                singleStringAdd={<Input onChange={handleChange} value={value} />}
                singleDate={<Input type="date" onChange={handleChange} value={value} />}
                singleNumber={<Input type="number" onChange={handleChange} value={value} />}
                singleTruth={<Input onChange={handleChange} value={value} />}
                certaintySelect={<Slider onChange={handleChange} value={value} />}
            />
        )
    }
    Rainbird

    Starting an interaction can be cumbersome and time-consuming, so Rainbird is a component that combines the RainbirdProvider, InteractionProvider, Start and Query to make it quicker to get started.

    import React from 'react'
    import {Rainbird} from '@rainbird/sdk-react';
    
    export const App = () => (
        <Rainbird
            apiKey="myApiKey"
            baseURL="https://api.rainbird.ai"
            options={{}}
            kmID="myKmID"
            subject="Bob"
            relationship="speaks"
            object=""
            onError={e => <Error>{e.message}</Error>}
            onLoad={<Loading />}
        >
            {({ data }) => ( // this is a response from the /query endpoint
                // ...rest of the app
            )}
        </Rainbird>
    )

    Helpers

    Designed to be flexible but take away some of the pain of interacting with the API

    getFormInputType

    A function that takes a question and returns an array of the different input types that a user might expect to see given the shape of the response

    Currently an array to support multiple questions in the future.

    import { getInputTypes } from '@rainbird/sdk-react';
    
    const data = {
        question: {
            plural: true,
            dataType: 'string',
            canAdd: true,
            allowCF: true,
            subject: 'Bob',
            relationship: 'speaks',
            type: 'Second Form Object',
            knownAnswers: []
        }
    }
    
    const inputTypes = getInputTypes(data)
    // [{ control: 'multi-string-add', certainty: true }]

    Keywords

    none

    Install

    npm i @rainbird/sdk-react

    DownloadsWeekly Downloads

    1

    Version

    1.3.0

    License

    MIT

    Unpacked Size

    190 kB

    Total Files

    91

    Last publish

    Collaborators

    • christneet
    • davidrampling