postman-collection - npm Package Compare versions

Comparing version 0.1.1 to 0.1.2

lib/collection/cookie.js

@@ -24,2 +24,48 @@ var _ = require('../util').lodash,
 
+/**
+ * The following is the object structure accepted as constructor parameter while calling `new Cookie(...)`. It is
+ * also the structure exported when {@link Property#toJSON} or {@link Property#toObjectResolved} is called on a
+ * Cookie instance.
+ * @typedef Cookie~definition
+ *
+ * @property {String=} [name] The name of the cookie. Some call it the "key".
+ * @property {String=} [expires] Expires sets an expiry date for when a cookie gets deleted. It should either be a
+ * date object or timestamp string of date.
+ * @property {Number=} [maxAge] Max-age sets the time in seconds for when a cookie will be deleted.
+ * @property {String=} [domain] Indicates the domain(s) for which the cookie should be sent.
+ * @property {String=} [path] Limits the scope of the cookie to a specified path, e.g: "/accounts"
+ * @property {Boolean=} [secure] A secure cookie will only be sent to the server when a request is made using SSL and
+ * the HTTPS protocol.
+ * The idea that the contents of the cookie are of high value and could be potentially damaging to transmit
+ * as clear text.
+ * @property {Boolean=} [httpOnly] The idea behind HTTP-only cookies is to instruct a browser that a cookie should never
+ * be accessible via JavaScript through the document.cookie property. This feature was designed as a security measure
+ * to help prevent cross-site scripting (XSS) attacks perpetrated by stealing cookies via JavaScript.
+ * @property {Boolean=} [hostOnly] Indicates that this cookie is only valid for the given domain (and not its parent or
+ * child domains.)
+ * @property {Boolean=} [session] Indicates whether this is a Session Cookie. (A transient cookie, which is deleted at
+ * the end of an HTTP session.)
+ * @property {String=} [value] The value stored in the Cookie
+ * @property {Array=} [extensions] Any extra attributes that are extensions to the original Cookie specification can be
+ * specified here.
+ * @property {String} [extensions[].key] Name of the extension.
+ * @property {String} [extensions[].value] Value of the extension
+ *
+ * @example <caption>JSON definition of an example collection</caption>
+ * {
+ *     name: 'my-cookie-name',
+ *     expires: '1464769543832', // UNIX timestamp, in *milliseconds*
+ *     maxAge: '300'  // In seconds. In this case, the Cookie is valid for 5 minutes
+ *     domain: 'something.example.com',
+ *     path: '/',
+ *     secure: false,
+ *     httpOnly: true,
+ *     session: false,
+ *     value: 'my-cookie-value',
+ *     extensions: [{
+ *         key: 'Priority',
+ *         value: 'HIGH'
+ *     }]
+ * }
+ */
 _.inherit((
@@ -31,3 +77,27 @@ /**
      *
-     * @param {Object} options Pass the initial definition of the Cookie.
+     * @param {Cookie~definition} [options] Pass the initial definition of the Cookie.
+     * @example <caption>Create a new Cookie</caption>
+     * var Cookie = require('postman-collection').Cookie,
+     *     myCookie = new Cookie({
+     *          name: 'my-cookie-name',
+     *          expires: '1464769543832', // UNIX timestamp, in *milliseconds*
+     *          maxAge: '300'  // In seconds. In this case, the Cookie is valid for 5 minutes
+     *          domain: 'something.example.com',
+     *          path: '/',
+     *          secure: false,
+     *          httpOnly: true,
+     *          session: false,
+     *          value: 'my-cookie-value',
+     *          extensions: [{
+     *              key: 'Priority',
+     *              value: 'HIGH'
+     *          }]
+     *     });
+     *
+     * @example <caption>Parse a Cookie Header</caption>
+     * var Cookie = require('postman-collection').Cookie,
+     *     rawHeader = 'myCookie=myValue;Path=/;Expires=Sun, 04-Feb-2018 14:18:27 GMT;Secure;HttpOnly;Priority=HIGH'
+     *     myCookie = new Cookie(rawHeader);
+     *
+     * console.log(myCookie.toJSON());
      */
@@ -34,0 +104,0 @@ Cookie = function PostmanCookie (options) {

lib/collection/event.js

@@ -9,4 +9,13 @@ var _ = require('../util').lodash,
  * @typedef Event~definition
- * @property {String} listen
- * @property {Script} script
+ * @property {String} listen The event-name that this script will be called for. Usually either "test" or "prerequest"
+ * @property {Script|String} script A {@link Script} instance that will be executed on this event. In case of a
+ * string, a new {@link Script} is created.
+ * @example <caption>Constructing an event</caption>
+ * var Event = require('postman-collection').Event,
+ *     rawEvent = {
+ *         listen: 'test',
+ *         script: 'tests["response code is 401"] = responseCode.code === 401'
+ *     },
+ *     myEvent;
+ * myEvent = new Event(rawEvent);
  */
@@ -20,4 +29,3 @@ _.inherit((
      *
-     * @param {Event~definition} definition Pass the initial definition of the event (name, id, listener name, etc) as
-     * the options parameter.
+     * @param {Event~definition} definition Pass the initial definition of the event as the options parameter.
      */
@@ -34,3 +42,3 @@ Event = function PostmanEvent (definition) {
      * Update an event
-     * @param {Event~definition} options
+     * @param {Event~definition} definition
      */
@@ -37,0 +45,0 @@ update: function (definition) {

lib/collection/form-param.js

@@ -6,2 +6,7 @@ var _ = require('../util').lodash,
 
+/**
+ * @typedef FormParam~definition
+ * @property {String} key The name ("key") of the form data parameter.
+ * @property {String} value The value of the parameter.
+ */
 _.inherit((
@@ -12,4 +17,3 @@ /**
      *
-     * @param {Object|String} options Pass the initial definition of the form data parameter (key, value) as the
-     *                        options parameter.
+     * @param {FormParam~definition} options Pass the initial definition of the form data parameter.
      */
@@ -43,9 +47,7 @@ FormParam = function PostmanFormParam (options) {
      * Parse a form data string into an array of objects, where each object contains a key and a value.
-     *
-     * @param query {String}
+     * @todo implement this, not implemented yet.
+     * @param formdata {String}
      * @returns {Array}
      */
-    parse: function (/* query */) {
-        throw new Error('Not implemented.');
-    }
+    parse: function (/* formdata */) {}
 });
@@ -52,0 +54,0 @@

lib/collection/header.js

@@ -6,3 +6,16 @@ var _ = require('../util').lodash,
     Header;
-
+/**
+ * @typedef Header~definition
+ * @property {String} key The Header name (e.g: 'Content-Type')
+ * @property {String} value The value of the header.
+ *
+ * @example Create a header
+ * var Header = require('postman-collection').Header,
+ *     header = new Header({
+ *         key: 'Content-Type',
+ *         value: 'application/xml'
+ *     });
+ *
+ * console.log(header.toString()) // prints the string representation of the Header.
+ */
 _.inherit((
@@ -14,3 +27,17 @@ /**
      *
-     * @param {Object} options Pass the initial definition of the header (key, value) as the options parameter.
+     * @param {Header~definition|String} options Pass the initial definition of the header (key, value) as the options
+     * parameter. In case a string is given, it is parsed to extract the header key and value.
+     *
+     * @example <caption>Parse a string of headers into an array of Header objects</caption>
+     * var Header = require('postman-collection').Header,
+     *     headerString = 'Content-Type: application/json\nUser-Agent: MyClientLibrary/2.0\n';
+     *
+     * var rawHeaders = Header.parse(headerString);
+     * console.log(rawHeaders); // [{ 'Content-Type': 'application/json', 'User-Agent': 'MyClientLibrary/2.0' }]
+     *
+     * var headers = rawHeaders.map(function (h) {
+     *     return new Header(h);
+     * });
+     *
+     * assert headerString === Header.unparse(headers);
      */
@@ -25,3 +52,11 @@ Header = function PostmanHeader (options) {
 
+        /**
+         * The header Key
+         * @type {String}
+         */
         this.key = _.get(options, 'key') || '';
+        /**
+         * The header value
+         * @type {String}
+         */
         this.value = _.get(options, 'value') || '';
@@ -51,6 +86,6 @@ }), PropertyBase);
     /**
-     * Parses a multi line header string into individual header key-value pairs.
+     * Parses a multi line header string into an array of {@link Header~definition}.
      *
      * @param headerString
-     * @returns {Object}
+     * @returns {Array}
      */
@@ -77,2 +112,7 @@ parse: function (headerString) {
 
+    /**
+     * Parses a single Header.
+     * @param header
+     * @returns {{key: string, value: string}}
+     */
     parseSingle: function (header) {
@@ -87,2 +127,8 @@ var parsed;
 
+    /**
+     * Stringifies an Array or {@link PropertyList} of Headers into a single string.
+     *
+     * @param {Array|PropertyList<Header>} headers
+     * @returns {string}
+     */
     unparse: function (headers) {
@@ -89,0 +135,0 @@ if (!_.isArray(headers) && !PropertyList.isPropertyList(headers)) {

lib/collection/query-param.js

@@ -6,2 +6,7 @@ var _ = require('../util').lodash,
 
+/**
+ * @typedef QueryParam~definition
+ * @property {String} key The name ("key") of the query parameter.
+ * @property {String} value The value of the parameter.
+ */
 _.inherit((
@@ -13,4 +18,4 @@ /**
      *
-     * @param {Object|String} options Pass the initial definition of the query parameter (key, value) as the
-     *                        options parameter.
+     * @param {FormParam~definition|String} options Pass the initial definition of the query parameter. In case of
+     * string, the query parameter is parsed using {@link QueryParam.parseSingle}.
      */
@@ -56,2 +61,8 @@ QueryParam = function PostmanQueryParam (options) {
 
+    /**
+     * Parses a single query parameter.
+     *
+     * @param param
+     * @returns {{key: string, value: string}}
+     */
     parseSingle: function (param) {
@@ -67,3 +78,4 @@ var parsed;
     /**
-     * Create a query string from array of parameters (or object of key-values).
+     * Create a query string from array of parameters (or object of key-values). This function ensures that
+     * the double braces "{{" and "}}" are not URL-encoded on unparsing, which allows for variable-substitution.
      *
@@ -70,0 +82,0 @@ * @param params

lib/collection/request-auth.js

@@ -11,5 +11,6 @@ var _ = require('../util').lodash,
      * @enum {string}
+     * @alias AuthTypes
      * @memberOf RequestAuth
      */
-    authenticationTypes = {
+    authenticationTypes = /** @lends AuthTypes */ {
         /**
@@ -49,2 +50,58 @@ * Handler used for the AWS Signature v4 authentication.
 
+/**
+ * @typedef RequestAuth~definition
+ * @property {String=} type The Auth type to use. Check the names in {@link AuthTypes}
+ * @property {Object=} awsv4 Parameters for the AWS Auth
+ * @property {String=} awsv4.accessKey The AWS Access Key ID
+ * @property {String=} awsv4.secretKey The AWS Secret Access Key
+ * @property {String=} awsv4.region The AWS Region (e.g: us-east-1, eu-west-2, etc)
+ * @property {String=} awsv4.service The AWS service name (also sometimes called AWS Service Namespace).
+ * E.g: 's3', 'execute-api', etc.
+ * More: http://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html#genref-aws-service-namespaces
+ *
+ * @property {Object=} basic Parameters for Basic Auth
+ * @property {String=} basic.username
+ * @property {String=} basic.password
+ *
+ * @property {Object=} digest Parameters for Digest Auth
+ * @property {String=} digest.username
+ * @property {String=} digest.realm
+ * @property {String=} digest.password
+ * @property {String=} digest.nonce
+ * @property {String=} digest.nonceCount
+ * @property {String=} digest.algorithm
+ * @property {String=} digest.qop
+ * @property {String=} digest.clientNonce
+ * @property {String=} digest.opaque
+ *
+ * @property {Object=} hawk Parameters for Hawk Auth
+ * @property {String=} hawk.hawkauthId
+ * @property {String=} hawk.hawkauthKey
+ * @property {String=} hawk.hawkalgorithm
+ * @property {String=} hawk.hawkuser
+ * @property {String=} hawk.hawknonce
+ * @property {String=} hawk.hawkextraData
+ * @property {String=} hawk.hawkappId
+ * @property {String=} hawk.hawkdelegation
+ * @property {String=} hawk.hawktimestamp
+ *
+ * @property {Object=} oauth1 Parameters for OAuth1
+ * @property {String=} oauth1.oauthConsumerKey
+ * @property {String=} oauth1.oauthToken
+ * @property {String=} oauth1.oauthSignatureMethod
+ * @property {String=} oauth1.oauthTimestamp
+ * @property {String=} oauth1.oauthNonce
+ * @property {String=} oauth1.oauthVersion
+ * @property {String=} oauth1.oauthSignature
+ *
+ * @property {Object=} oauth2 Parameters for OAuth2
+ * @property {String=} oauth2.addTokenTo
+ * @property {String=} oauth2.callBackUrl
+ * @property {String=} oauth2.authUrl
+ * @property {String=} oauth2.accessTokenUrl
+ * @property {String=} oauth2.clientId
+ * @property {String=} oauth2.clientSecret
+ * @property {String=} oauth2.scope
+ * @property {String=} oauth2.requestAccessTokenLocally
+ */
 _.inherit((
@@ -57,3 +114,3 @@ /**
      *
-     * @param {Object} options Pass the initial definition of the Auth.
+     * @param {RequestAuth~definition} options Pass the initial definition of the Auth.
      */
@@ -67,3 +124,3 @@ RequestAuth = function PostmanRequestAuth (options) {
             /**
-             * @type {authTypes}
+             * @type {String|undefined}
              */
@@ -70,0 +127,0 @@ type: undefined

lib/collection/request-auth/awsv4.js

@@ -52,3 +52,3 @@ var _ = require('../../util').lodash,
             path: request.url.getPathWithQuery(),
-            service: params.serviceName || 'execute-api', // AWS API Gateway is the default service.
+            service: params.service || params.serviceName || 'execute-api', // AWS API Gateway is the default service.
             region: params.region || 'us-east-1',
@@ -55,0 +55,0 @@ method: request.method,

lib/collection/request-body.js

@@ -7,4 +7,6 @@ var _ = require('../util').lodash,
 
-    RequestBody;
+    RequestBody,
 
+    EMPTY = '';
+
 _.inherit((
@@ -92,13 +94,15 @@ /**
     toString: function () {
-        if (this.mode === RequestBody.MODES.raw) {
-            return this.raw.toString();
+        // Formdata. Goodluck.
+        if (this.mode === RequestBody.MODES.formdata) {
+            // @todo: implement this, check if we need to return undefined or something.
+            return;
         }
-
         if (this.mode === RequestBody.MODES.urlencoded) {
             return PropertyList.isPropertyList(this.urlencoded) ? QueryParam.unparse(this.urlencoded.all()) :
-                this.urlencoded;
+                ((this.urlencoded && _.isFunction(this.urlencoded.toString)) ? this.urlencoded.toString() : EMPTY);
         }
 
-        // Formdata. Goodluck.
-        throw new Error('Form data stringification is not implemented yet.');
+        if (this.mode === RequestBody.MODES.raw) {
+            return (this.raw && _.isFunction(this.raw.toString)) ? this.raw.toString() : EMPTY;
+        }
     }
@@ -105,0 +109,0 @@ });

lib/collection/request.js

@@ -11,2 +11,10 @@ var _ = require('../util').lodash,
 
+/**
+ * @typedef Request~definition
+ * @property {String|Url} url The URL of the request. This can be a {@link Url~definition} or a string.
+ * @property {String} method The request method, e.g: "GET" or "POST".
+ * @property {Array<Header~definition>} header The headers that should be sent as a part of this request.
+ * @property {RequestBody~definition} body The request body definition.
+ * @property {RequestAuth~definition} auth The authentication/signing information for this request.
+ */
 _.inherit((
@@ -93,3 +101,3 @@ /**
      *
-     * @param header {PostmanHeader| {key: String, value: String}} Can be a {PostmanHeader} object,
+     * @param header {Header| {key: String, value: String}} Can be a {Header} object,
      *                      or a raw header object.
@@ -104,3 +112,3 @@ */
      *
-     * @param toRemove {String|PostmanHeader} A header object to remove, or a string containing the header key.
+     * @param toRemove {String|Header} A header object to remove, or a string containing the header key.
      * @param options
@@ -129,3 +137,3 @@ * @param options.ignoreCase {Boolean} If set to true, ignores case while removing the header.
      *
-     * //TODO: Rename this? @shamasis
+     * @todo: Rename this?
      * @param params {Array<QueryParam>|String}
@@ -180,2 +188,8 @@ */
 
+    /**
+     * Creates a copy of this request, with the appropriate auth headers or parameters added.
+     *
+     * @note This function does not take care of resolving variables.
+     * @returns {Request}
+     */
     authorize: function () {
@@ -182,0 +196,0 @@ var clonedReq = this.clone();

lib/collection/response.js

@@ -84,2 +84,3 @@ var _ = require('../util').lodash,
      *
+     * @private
      * @readonly
@@ -86,0 +87,0 @@ * @enum {string}

lib/superstring/index.js

@@ -12,2 +12,3 @@ var _ = require('../util').lodash,
  * @constructor
+ * @private
  * @param {String} value
@@ -72,2 +73,5 @@ */
  * Perform replacement of tokens in a SuperString with values stored in keys of an array of objects.
+ *
+ * @constructor
+ * @private
  * @param {Array} variables
@@ -74,0 +78,0 @@ * @param {Object} defaults

package.json

@@ -5,3 +5,3 @@ {
   "author": "Postman Labs <[e-mail]>",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "keywords": [
@@ -52,3 +52,2 @@ "postman"
     "istanbul": "^0.4.2",
-    "jaguarjs-jsdoc": "git+https://github.com/davidshimjs/jaguarjs-jsdoc.git#f4230547c25a907a8c84b51069dd14b5c9e44e69",
     "js-beautify": "^1.5.10",
@@ -64,2 +63,3 @@ "jscs": "^2.7.0",
     "karma-mocha-reporter": "^1.1.5",
+    "postman-jsdoc-theme": "0.0.1",
     "mocha": "^2.3.4",
@@ -66,0 +66,0 @@ "mustache": "^2.2.1",

README.md

@@ -47,3 +47,3 @@ # Postman Collection SDK
 After loading the collection from file, one can do a lot more using the functions that are available in the SDK. To know
-more about these functions, head over to the 
-[Collection SDK Wiki](https://github.com/postmanlabs/postman-collection/wiki).
+more about these functions, head over to
+[Collection SDK Docs](http://www.postmanlabs.com/postman-collection).

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

256396

increased by3.89%

Lines of code

5904

increased by3.85%

No dependency changes