Neopolitan Pizza Maker

    @dudadev/partner-api
    TypeScript icon, indicating that this package has built-in type declarations

    1.5.6 • Public • Published

    @dudadev/partner-api

    The @dudadev/partner-api library provides convenient access to Duda's public APIs from applications written in server-side Javascript.

    1. Requirements
    2. Installation
    3. Usage
    4. Configuration
      1. Initialize with config object
      2. API Environments
      3. Network Retries
    5. Request Overrides
    6. Responses
      1. Success
      2. Errors
    7. Debugging
    8. App Store
      1. Authenticating requests
      2. Handling different api_endpoint values
      3. Utility functions
    9. More Information

    Requirements

    Node v12 or higher.

    Installation

    Install the package with:

    npm install @dudadev/partner-api --save
    # or
    yarn add @dudadev/partner-api

    Usage

    The package needs to be configured with your API credentials:

    const { Duda } = require('@dudadev/partner-api');
    
    const duda = new Duda({
      user: process.env.DUDA_API_USER,
      pass: process.env.DUDA_API_PASS,
      env: Duda.Environments.Direct,
    });
    
    duda.sites.get({ site_name: "a-site-name" })
      .then(({ response: site }) => console.log(site))
      .catch(({ response: error }) => console.error(error));

    Or using ES modules and async/await:

    // async / await
    (async function () {
      try {
        const site = await duda.sites.get({ site_name: "a-site-name" });
        console.log(site);
      } catch ({
        status,
        response
      }) {
        console.log(status, response);
        // handle error
      }
    })();

    Configuration

    Initialize with config object

    The package can be initialized with several options:

    const duda = new Duda({
      user: 'api-user',
      pass: 'api-pass',
      env: Duda.Environments.Sandbox, // also, .direct, .eu
    });

    API Environments

    • Duda.Environments.EU: api.eu.duda.co
    • Duda.Environments.Direct: api.duda.co
    • Duda.Environments.Sandbox: api-sandbox.duda.co

    Network Retries

    Automatic network retries can be enabled with the maxNetworkRetries config option. This will retry requests n times with exponential backoff if they fail due to an intermittent network problem.

    const duda = new Duda({
      ...,
      maxNetworkRetries: 2
    });

    Request Overrides

    You can override the http.RequestOptions of any method on a per-request basis by passing a second object with custom options:

    const { Duda } = require('@dudadev/partner-api');
    
    const duda = new Duda({
      user: process.env.DUDA_API_USER,
      pass: process.env.DUDA_API_PASS,
      env: Duda.Environments.Direct,
    });
    
    duda.sites.get({ site_name: 'a-site-name' }, {
      host: 'api-special.duda.co',
      auth: 'another-username:another-password',
      headers: {
        'X-CUSTOM-HEADER': 'a-value',
      },
    })
      .then(({ response: site }) => console.log(site))
      .catch(({ response: error }) => console.error(error))

    Responses

    interface Response {
      status: number;
      response: DudaResponse | DudaError;
    }

    Debugging

    You can debug requests made by the library by setting the DUDA_API_LOG_LEVEL environment variable to one of the following levels:

    1. error: only shows fatal errors
    2. warning: shows all errors and warnings
    3. info: high-level debugging information
    4. debug: verbose debugging information

    The library will display logs that are >= DUDA_API_LOG_LEVEL. So, for example, setting the log level to warning (2) would log all warnings (2) and errors (1).

    The logger will attempt to redact any sensitive information before it logs using the following regular expressions:

    • /(user(name)?|pass(word)?|auth(orization)?)":"[^"]+/gi
    • /(Bearer|Basic) [^"]+/gi

    Example using debug

    $ DUDA_API_LOG_LEVEL=debug node index.js
    [debug] 8ce2a72d-d6b6-4fe8-bf39-45ebe99f7233 no http agent defined: received=undefined
    [info] 8ce2a72d-d6b6-4fe8-bf39-45ebe99f7233 new request: method=get endpoint=api-sandbox.duda.co/api/sites/multiscreen/374f37ea1eff44e7966b2c685ded251a/pages
    [debug] 8ce2a72d-d6b6-4fe8-bf39-45ebe99f7233 full request details: req={"headers":{},"method":"get","path":"/api/sites/multiscreen/374f37ea1eff44e7966b2c685ded251a/pages","auth": [redacted],"host":"api-sandbox.duda.co"}
    [debug] 8ce2a72d-d6b6-4fe8-bf39-45ebe99f7233 data received: raw={"results":[{"uuid":"683340afe033436caab26cf8a548b1dd","title":"Home","path":"home","seo":{"no_index":false}}]}
    [debug] 8ce2a72d-d6b6-4fe8-bf39-45ebe99f7233 request ended: status=200 time=0.51s

    App Store API

    If you're an app developer, you can access the App Store API under duda.appstore after calling new Duda(opts).

    Authenticating requests

    API Endpoints protected by an X-DUDA-ACCESS-TOKEN expect method calls to include a token property set to the authorization_code without Bearer included.

    duda.appstore.sites.get({
      site_name: 'a-site-name',
      token: 'authorization-code',
    })

    Handling different api_endpoint values

    You can use the request override feature to set the host of a method call to the correct api_endpoint for a particular site.

    function getSite(site: string) {
      const {
        site_name,
        auth,
        api_endpoint
      } = getInstallFromDB(site);
    
      return duda.appstore.sites.get({
        site_name: site_name,
        token: auth.authorization_code,
      }, {
        host: api_endpoint,
      })
    }
    
    getSite('a-site-name')
      .then((site) => console.log(site))
      .catch((err) => console.log(err.status, err.error))

    Utility functions

    Included under Duda.appstore is utils which contains useful methods for validating webhooks & signatures.

    function validateWebook(req: YourRequestObject): boolean {
      // conform request object
      return duda.appstore.utils.validateWebook(process.env.SECRET_KEY, req.headers, req.body);
    }
    
    function validateSSO(req: YourRequestObject): boolean {
      // conform request object
      return duda.appstore.utils.validateSSOLink(process.env.SECRET_KEY, req.query);
    }

    More Information

    Keywords

    none

    Install

    npm i @dudadev/partner-api

    DownloadsWeekly Downloads

    122

    Version

    1.5.6

    License

    MIT

    Unpacked Size

    310 kB

    Total Files

    247

    Last publish

    Collaborators

    • yoavporat
    • liady
    • russjeffery
    • idanen
    • hilakerer
    • sharon_rub
    • talkor
    • dannyr-duda
    • shira.weiss
    • roiekoper-duda
    • everett-duda