Provider Structure

A Provider is structured as an npm package. See the prerequisites section for more information about npm packages.

Providers are private packages registered with Applicaster scope on the npm registry. The name of the package must be zapp-pipes-provider-{provider-name}.

Provider API

The final export of the provider npm package must be an object with the following properties:

  • name<String>: name of the provider. This string will be used as the scheme for making requests inside the app. It should contain only UTF-8 compatible alphabetical characters and dashes -. It must match the name of the {provider-name} part of the npm package name.
  • manifest<Object>: the manifest is an object that contains the following properties:
    • handlers<[String]>: strings of request_type handled by the provider. All requests must contain a type parameter which matches one of the handlers declared here. If a request is made to an unregistered request_type, the Zapp-pipes bundle will throw an error.
    • help<Object>: the help object is supposed to provide help for all supported request_type. Ideally, it should provide a description object and a parameters array which declares all the other parameters required for performing the relevant request_type.
  • handler: (nativeBridge) -> (params) -> providerResult<Promise:Any>: the handler method is a curried function which returns the result of the request. The currying enables the core library to inject the parameters and the utility functions the provider may require. Check here for more details about nativeBridge.
  • test<Object>: the test object provides the information required by the packager to run integration tests while building the bundle
    • testCommand<String>: the test command that will be used in the integration test. It should be something like {provider-name}://fetchData?type={requestType}&foo=bar
    • requestMocks<[Object]>: (optional, but recommended) the bundle packager uses the nock library to mock server requests during the integration test process. The requestMocks object allows to register URLs and responses that need to be mocked during the integration test. For each mocked request, you should provide an object with the following properties:
      • host<String>: the full host name and the protocol used
      • method: the HTTP method to use. If using post, the nock setup will automatically intercept requests regardless of the payload sent in the request body
      • path<String>: the path of the request. It must start with /
      • httpCode<Number>: the httpCode of the response. The default is 200
      • expectedResponse<Object>: the response that nock will return for the request. It is not the response expected from the library, but just the response of the request call.

Here is an example of a provider implementation:

  const provider = {
    name: 'my-provider-name',

    manifest: {
        handlers: ['collection', 'item'],
        help: { 
            collection: {
                description: 'list of items',
                params: { ... }
            ....
            }
       }
    },

    test: {
      testCommand: 'my-provider-name://fetchData?type=allFeeds&id=XXX',
      requestMocks: [{
        host: 'http://api.my-server.com',
        method: 'get',
        path: '/feeds/id/XXX',
        httpCode: 200, // unecessary here because it will default to 200
        expectedResponse: {}, // full expected response from a get request to http://api.my-server.com/feeds/id/XXX
      }, {
        host: 'https://auth.my-server.com',
        method: 'post',
        path: '/token',
        httpCode: 200,
        expectedResponse: { token: 'XXXX' },
      }],
    },

    handler: nativeBridge => params => {

      const { type, url } = params;

      if (!checkParams(params)) {
        return nativeBridge.throwError({ msg: 'invalid params', params });
      }

      if (type === 'collection') {
        return collectionRequest(url)
          .catch(error => nativeBridge.throwError({ error, params }))
          .then(response => nativeBridge.sendResponse(response));
      }
    }
  };

  export default provider;

The nativeBridge object is a toolbelt object which provides several key methods from the native JavaScript bridge

the handler has to explicitly return the response using either the sendResponse() or throwError() method of the nativeBridge. Invoking a callback with a request response will break the flow of the bundle and if the handler doesn't return anything, the bundle might hang or throw an error.

Tests

It is better when the provider has tests but there is no strict enforcement of this. However, integration tests are run. These tests rely on the test property of the provider. Bundling will fail if this property is not correctly set according to the documentation above.

Integration tests don't test the provider's internal work fully. They just verify that the provider returns something - even an error.

results matching ""

    No results matching ""