Provider structure

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

Providers are private packages, registered in 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, and should only contain UTF-8 compatible alphabetical characters and dashes -. It must match the name of {provider-name} part of the npm package name.
  • manifest<Object>: the manifest is an object containing the following properties :
    • handlers<[String]>: strings of request_type handled by the provider. All request 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, 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 the nativeBridge.
  • test<Object>: The test object provides the info 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. should be something like {provider-name}://fetchData?type={requestType}&foo=bar
    • requestMocks<[Object]>: (optional, but recommended) the bundle packager uses nock to mock server request 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, with 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, which must start with /
      • httpCode<Number> : the httpCode of the response, default is 200
      • expectedResponse<Object> : the response nock will return for the request. It is not the response expected from the library, but just 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 cause 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.

Tests

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

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

results matching ""

    No results matching ""