cozy-harvest-lib

    9.25.0 • Public • Published

    Cozy-Harvest-Lib

    Goal

    Cozy-Harvest-Lib is responsible for the logic and components used in Cozy applications dealing with konnector accounts configuration.

    With Harvest components, an app is able to:

    • configure konnectors
    • setup authentification informations
    • check for synchronized data
    • ..and much more in the future

    Current version

    The current version exposes base components to

    • create and edit accounts
    • check status of the synchronization

    Those components are used for now in Cozy-Home.

    Installation

    Just run

    yarn add cozy-harvest-lib
    

    Importing

    Components imported from cozy-harvest-lib must be imported from the root of the package, and not from specific files:

    // imported from the root of the package 👍
    import { TriggerManager } from 'cozy-harvest-lib'
    
    // imported from another file or folder 👎
    import TriggerManager from 'cozy-harvest-lib/TriggerManager'
    

    This is because all harvest components come with their own translation context. If you really do need to import a component straight from the shipped file, there is a withLocales HOC that is available, so something like this would work as a fallback:

    import TriggerManager from 'cozy-harvest-lib/TriggerManager'
    import { withLocales } from 'cozy-harvest-lib'
    
    const MyTriggerManager = withLocales(TriggerManager)
    

    Tracking

    Harvest components come with tracking calls (that would be effective only if the user has consented to tracking). Your app must provide the correct tracking context via the TrackingContext component.

    Here, we pass a tracker to harvest that prefixes the page names sent by harvest with "app-harvest:".

    import { useMemo } from 'react'
    import { KonnectorModal, TrackingContext } from 'cozy-harvest-lib'
    
    export default () => {
      const appTracker = useTracker() // tracker from the app
      const trackerForHarvest = useMemo(() => {
        const trackPage = pageName => tracker.trackPage(`app-harvest:${pageName}`)
        const trackEvent = event => tracker.trackEvent(event)
        return { trackPage, trackEvent }
      }, [appTracker])
      return <TrackingContext.Provider value={trackerForHarvest}>
        <KonnectorModal />
      </TrackingContext.Provider>
    }
    

    If the app does not provide a tracking context, tracking calls will do nothing.

    Data cards

    ⚠️ This is still in progress, things may change abruptly.

    It is possible to display, in the data tab of Harvest, cards showing the data that has been collected by the connector for the current io.cozy.accounts.

    It is up to the application to tell Harvest which datacard should be used. It is done by passing the datacardOptions prop to the Routes component of Harvest.

    Here, if the konnector displayed has one permission on the "io.cozy.timeseries.geojson" doctype, the GeoDataCard is shown.

    import GeoDataCard from 'cozy-harvest-lib/dist/datacards/GeoDataCard'
    
    const datacardOptions = [{
      match: ({ konnector }) => any(konnector.permissions, permission => permission.type == 'io.cozy.timeseries.geojson'),
      component: GeoDataCard
    }]
    
    <Routes datacardOptions={datacardOptions} ... />

    If an application wants to display all the available datacards, it can import datacard options from Harvest. /!\ At this point, the app must install all the dependencies that are necessary for each datacard to work (Leaflet for GeoDataCard for example).

    import datacardOptions from 'cozy-harvest-lib/dist/datacards/datacardOptions'
    <Routes doctypeToDataCard={doctypeToDataCard} ... />
    
    • Since the application imports the datacards component, an application not using this functionality is not bloated by the dependencies of the data card.

    • An application can implement a custom datacard for a particular doctype.

    Datacard components receive as props:

    • accountId: the accountId of the currently displayed io.cozy.accounts
    • konnector: the konnector currently displayed
    • trigger: the trigger linking the account to the konnector

    Getting Started

    For now it is possible to instanciate a <TriggerManager /> which will allow to edit an account and launch the trigger.

    As this component uses CozyClient, it must be wrapped at some point into a <CozyProvider />.

    import CozyClient, { CozyProvider, Q } from 'cozy-client'
    import { TriggerManager } from 'cozy-harvest-lib'
    
    const client = new CozyClient({
      /*...*/
    })
    
    ReactDOM.render(
      <CozyProvider client={client}>
        <Query query={()=> Q('io.cozy.apps').getById('my-konnector-id')}>
          {({ data: konnector }) => (
            <TriggerManager
              konnector={konnector}
              onSuccessLogin={() => alert('logged in')}
            />
          )}
        </Query>
        // other stuff
      </CozyProvider>,
      document.getElementById('main')
    )

    API

    See the Styleguidist.

    Doc and example about manifests

    https://docs.cozy.io/en/tutorials/konnector/#the-manifest

    Keywords

    none

    Install

    npm i cozy-harvest-lib

    DownloadsWeekly Downloads

    481

    Version

    9.25.0

    License

    MIT

    Unpacked Size

    2.48 MB

    Total Files

    525

    Last publish

    Collaborators

    • mycozycloud