Neatly Packaged Magic

    @essium-llc/lib-xenqu-nodejs
    TypeScript icon, indicating that this package has built-in type declarations

    1.2.7 • Public • Published

    NodeJS Library for the Xenqu API

    NodeJS Implementation of the Xenqu API (with types) Based off of these API Docs

    Getting Started: Install:

    npm install @essium-llc/lib-xenqu-nodejs 

    Usage

    There are 4 ways to initialize your API instance:

    1. Create an API Instance using a Private Key:
    import XenquAPI from "lib-xenqu-nodejs";  
      
    const API = new XenquAPI("client_id", "client_secret", "private_key", "subscriber", 'https://xenqu.com/api');  
    await API.init(); // Connects to API using OAuth 2.0 to get OAuth 1.0 credentials 

    OR

    1. Create an API Instance using a Username/Password Authentication, along with embedding the Xenqu login portal
    import XenquAPI from "lib-xenqu-nodejs";
    
    const boot = await XenquAPIBoot('https://xenqu.com/api', 'your-app-id', 'your-site-profile')  
    const API = new XenquAPI(boot._m, boot._s, null, null, 'https://stage.xenqu.com/api', true);  
    const tempToken = await API.startWebAuth('your-callback-url');  
    // Use the tempToken to embed `https://xenqu.com/login.html?oauth_token=${tempToken}`  
    // login.html will load username and password field. Once UN/PW are accepted  
    // Xenqu will automatically call your callback url with encoded form data.  
    // You will need to decode the returned string and pass the oauth_verifier  
    // data to the following function  
    const tokensToSave = await API.finishWebAuth(oauth_verifier); // Save these tokens (securely) if you'd like to attempt reauthoriztion later!  

    OR

    1. Create an API Instance using a Username/Password Authentication
    import XenquAPI from "lib-xenqu-nodejs";
    
    const boot = await XenquAPIBoot('https://xenqu.com/api', 'your-app-id', 'your-site-profile')  
    const API = new XenquAPI(boot._m, boot._s, null, null, 'https://stage.xenqu.com/api', true); 
     
    // Typically, the client ID and client secret are different for the middle requests in
    // our oauth process. These will be provided if this is the case. Otherwise, 
    // you may proceed by setting these to the same as above
    const loginClient = 'your-login-client-id'; // boot._m
    const loginSecret = 'your-login-client-secret'; // boot._s
    // A registered callback must be used here. Although the responses from the callbacks aren't
    // ever used, the oauth requests still require a registered callback url to be sent
    const callback = 'your-registered-callback';
    // Authenticator is the method of authentication that you want to use.
    // 'default' is for Username/Password authentication
    // 'openid' is used for SSO applications
    const authenticator = 'default'; // 'openid'
    // Additional parameters includes the parameters that are used in the authentication request.
    // If your authenticator is 'default' you'll need to include 'user_name' and 'user_pass'
    // If your authenticator is 'openid' you'll need to include 'provider' and any other fields
    // that that SSO provider requires to be sent.
    const extraParams = { user_name: 'username', user_pass: 'password' };
    // These are example parameters for Microsoft SSO
    const extraParams = { provider: 'microsoft', id_token: 'microsoft-id-token' }
    // Attempt the full xenqu oauth authentication flow in one fell swoop
    const tokensToSave await API.attemptAuthWithUNandPWorSSO(loginClient, loginSecret, callback, authenticator, extraParams); // Save these tokens (securely) if you'd like to attempt reauthoriztion later!  

    If you are having issues trying to use the whole auth flow at once, you can debug each part by breaking apart the requests:

    import XenquAPI from "lib-xenqu-nodejs";
    
    const boot = await XenquAPIBoot('https://xenqu.com/api', 'your-app-id', 'your-site-profile')  
    const API = new XenquAPI(boot._m, boot._s, null, null, 'https://stage.xenqu.com/api', true); 
    
    // See above example for explination of these variables and what they all mean
    const loginClient = 'your-login-client-id'; // boot._m
    const loginSecret = 'your-login-client-secret'; // boot._s
    const callback = 'your-registered-callback';
    const authenticator = 'default'; // 'openid'
    const extraParams = { user_name: 'username', user_pass: 'password' };
    
    await API.startWebAuth('your-callback-url'); 
    await API.authenticate(loginClient , loginSecret , callback, authenticator, extraParams);  
    const verifierWhole = await API.authorize(loginClient, loginSecret, callback); 
    const verifierSplit = verifierWhole.split('&')[1].split('=')[1]; // Split form-data response to get verifier
    const tokensToSave = await API.finishWebAuth(verifierSplit); // Save these tokens (securely) if you'd like to attempt reauthoriztion later!  

    OR

    1. Create an API Instance using old OAuth1.0 credentials.
    • This is useful if you have a user logged in on the web, and they close and re-open their browsing window. If you cached the credentials, you can reload the user without having them re-enter their login information again.
    • This isn't as useful in a private-key authenticated API instance, as you can always renew your keys by calling API.init()
    import XenquAPI from "lib-xenqu-nodejs";    
    
    const oldCreds = new new OAuth1Credentials({    
    	consumer_key: 'your-consumer-key',    
        consumer_secret: 'your-consumer-secret',    
        token: 'your-token',    
        token_secret: 'your-secret', 
    })  
    
    const API = new XenquAPI(oldCreds.consumerKey, oldCreds.consumerSecret, "private_key", "subscriber", 'https://xenqu.com/api');  
    // OR, If you're using Web-Style authentication  
    const API = new XenquAPI(oldCreds.consumerKey, oldCreds.consumerSecret, null, null, 'https://xenqu.com/api', true);  
    
    // Set the second parameter to true to attempt to renew the keys  
    const renewedCreds = await API.tryOldCredentials(oldCreds, false);  

    Once initialized, you can call any API route available on these API Docs. If you find a missing route, please create an issue.

    Access API Routes:

    API.account  // Account Routes 
    API.contact  // Contact Routes 
    API.tracking // Tracking Routes 
    API.forms    // Form Routes
    API.reports  // Report Routes 
    API.files    // File Routes
    API.search   // Search Routes  

    Other Implementations

    Ruby

    .NET

    Our .NET implementation can access reports. We've used this in RPA projects using Automation Anywhere. It should also be possible to get it to work with UiPath, or can used stand-alone to build utility apps.

    Python

    Install

    npm i @essium-llc/lib-xenqu-nodejs

    DownloadsWeekly Downloads

    1

    Version

    1.2.7

    License

    GPL-3.0

    Unpacked Size

    351 kB

    Total Files

    108

    Last publish

    Collaborators

    • techno11