Merge branch 'master' of github.com:ahmadnassri/apiembed

Author: Montana Flynn

CONTRIBUTING.md

@@ -133,3 +133,278 @@ project:
 
 **IMPORTANT**: By submitting a patch, you agree to allow the project owner to
 license your work under the same license as that used by the project.
+
+## Creating New Conversion Targets
+
+Please start by browsing for [available targets](/src/targets) and inspect each implementation.
+
+a target is a simple module with a constructor that accepts two parameters: `source` and `options`, 
+where `source` is the HAR Object to process, and `options` is an optional object with any target 
+specific flags *(used for customizing the output)*.
+
+### Conversion Rules
+
+1. start by reading an understanding the [HAR](http://www.softwareishard.com/blog/har-12-spec/#request) format.
+2. utilize utility properties created for convenience (`source.headersObj`, `source.uriObj` etc ...) *see below for mode details*
+3. follow the guidelines below for best practices and consistency.
+
+### Guidelines
+
+Using the following example of a request object, HTTP Snippet will pre-process data and create some additional properties:
+
+| property                    | description                                                                                                                                       |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `source.fullUrl`            | the full & final url, including all query string values                                                                                           |
+| `source.uriObj`             | the url parsed with `url.parse()`. compatible with `url.format`                                                                                   |
+| `source.queryObj`           | a key => value pair, "normalized" version of `source.queryString`, adds additional query string values from the `source.url`                      |
+| `source.headersObj`         | a key => value pair, "normalized" version of `source.headers`, header names are lowercased                                                        |
+| `source.allHeaders`         | same as `source.headersObj` but with `cookies` header and populated from `source.cookies` array                                                   |
+| `source.postData.jsonObj`   | the parsed value of `source.postData.text`, only for `source.postData.mimeType` = `application/json` *(or equivalent mimeTypes)*                  |  
+| `source.postData.paramsObj` | a key => value pair, "normalized" version of `source.postData.params`, only for `source.postData.mimeType` = `application/x-www-form-urlencoded`  | 
+
+###### Sample Incoming Request Object
+
+```js
+{
+  method: 'POST',
+  url: 'http://mockbin.com/har?key=value',
+  httpVersion: 'HTTP/1.1',
+  queryString: [
+    { name: 'foo', value: 'bar' },
+    { name: 'foo', value: 'baz' },
+    { name: 'baz', value: 'abc' }
+  ],
+  headers: [
+    { name: 'Accept', value: 'application/json' },
+    { name: 'Content-Type', value: 'application/x-www-form-urlencoded' }
+  ],
+
+  cookies:  [
+    { name: 'foo', value: 'bar' },
+    { name: 'bar', value: 'baz' }
+  ],
+
+  postData: {
+    mimeType: 'application/x-www-form-urlencoded',
+    params: [
+      { name: 'foo', value: 'bar' },
+      { name: 'foo', value: 'baz' },
+      { name: 'baz', value: 'abc' }
+    ]
+  }
+}
+```
+
+###### Processed Source Object
+
+```js
+{
+  method: 'POST',
+
+  // the base url value stripped of any the query string
+  url: 'http://mockbin.com/har',
+
+  // the full & final url, including all query string values
+  fullUrl: 'http://mockbin.com/har?foo=bar&foo=baz&baz=abc&key=value',
+
+  // the url parsed with url.parse()
+  // compatible with url.format
+  uriObj: {
+    protocol: 'http:',
+    slashes: true,
+    auth: null,
+    host: 'mockbin.com',
+    port: null,
+    hostname: 'mockbin.com',
+    hash: null,
+    search: 'key=value&baz=abc&foo=bar&foo=baz',
+    query: { key: 'value', baz: 'abc', foo: [Object] },
+    pathname: '/har',
+    path: '/har?key=value&baz=abc&foo=bar&foo=baz',
+    href: 'http://mockbin.com/har'
+  },
+
+  httpVersion: 'HTTP/1.1',
+
+  // added to pass har-validator
+  bodySize: 0,
+
+  // added to pass har-validator
+  headersSize: 0,
+
+  queryString: [
+    { name: 'foo', value: 'bar' },
+    { name: 'foo', value: 'baz' },
+    { name: 'baz', value: 'abc' }
+  ],
+
+  // "normalized" version of `queryString`
+  // adds any additional query string values from the url
+  // compatible with "querystring" node module
+  queryObj: {
+    key: 'value',
+    baz: 'abc',
+    foo: [ 'bar', 'baz' ]
+  },
+
+  headers: [
+    { name: 'Accept', value: 'application/json' },
+    { name: 'Content-Type', value: 'application/x-www-form-urlencoded' }
+  ],
+
+  // normalized headers array into a key => value object pair
+  // header names are lowercased
+  headersObj: {
+    'accept': 'application/json',
+    'content-type': 'application/x-www-form-urlencoded'
+  },
+
+  // same as headersObj but with Cookies added (if any exist in cookies array)
+  allHeaders: {
+    'accept': 'application/json',
+    'content-type': 'application/x-www-form-urlencoded',
+    'cookie': 'foo=bar; bar=baz'
+  },
+
+  cookies:  [
+    { name: 'foo', value: 'bar' },
+    { name: 'bar', value: 'baz' }
+  ],
+
+  // see below for different scenarios
+  postData: [Object]
+}
+```
+
+###### application/x-www-form-urlencoded
+
+```js
+postData: {
+  // added to pass har-validator
+  size: 0,
+
+  // original value
+  mimeType: 'application/x-www-form-urlencoded',
+
+  // original value
+  params: [
+    { name: 'foo', value: 'bar' },
+    { name: 'foo', value: 'baz' },
+    { name: 'baz', value: 'abc' }
+  ],
+
+  // "normalized" version of `params`
+  // compatible with "querystring" node module
+  paramsObj: {
+    key: 'value',
+    baz: 'abc',
+    foo: [ 'bar', 'baz' ]
+  }
+
+  // the raw body in plain text
+  // this value will be always overwritten in this scenario
+  text: 'baz=abc&foo=bar&foo=baz'
+
+  // see below
+  jsonObj: false
+}
+```
+
+###### application/json
+
+- will match when `postData.mimeType` is one of: `application/json`, `text/json`, `text/x-json`, `application/x-json`
+- In case of failure to parse `postData.text` as a JSON object, `postData.mimeType` is set to `text/plain`, `postData.jsonObj` remains as `false`. this is done so that the implementing target, would still attempt to post the raw body as is.
+- This also emphasizes not to rely on `postData.mimeType` for the `Content-Type` header!
+
+```js
+postData: {
+  // added to pass har-validator
+  size: 0,
+
+  // original value
+  mimeType: 'application/json',
+
+  // ignored
+  params: [],
+
+  // default value
+  paramsObj: false
+
+  // the raw body in plain text
+  text: '"{\"foo\": \"bar\"}"'
+
+  // the parsed value of postData.text
+  jsonObj: {
+    foo: 'bar'
+  }
+}
+```
+
+###### multipart/form-data
+
+- will match when `postData.mimeType` is one of: `multipart/mixed` `multipart/related`, `multipart/form-data`, `multipart/alternative`
+- will force `postData.mimeType` to `multipart/form-data`
+- will create/overwrite the `Content-Type` header if it does not exist, with the appropriate boundary flag.
+- when no `params[].value` is present, will default to empty content
+
+```js
+postData: {
+  // added to pass har-validator
+  size: 0,
+
+  // original value
+  mimeType: 'multipart/form-data',
+
+  // parsed into text values
+  params: [
+    {
+      name: 'foo',
+      value: 'bar'
+    }
+  ]
+
+  // ignored
+  paramsObj: false
+
+  // the raw body in plain text
+  // generated based on appropriately parsing the `params` into a multi-boundary content string
+  // this value will be always overwritten in this scenario
+  text: '----------------------------591447866569479977899212\r\nContent-Disposition: form-data; name=\"foo\"\r\n\r\nbar\r\n----------------------------591447866569479977899212--'
+
+  // ignored
+  jsonObj: false
+}
+```
+
+###### multipart/form-data (File Uploads)
+
+```js
+postData: {
+  // added to pass har-validator
+  size: 0,
+
+  // original value
+  mimeType: 'multipart/form-data',
+
+  // parsed into text values
+  params: [
+    {
+      name: 'foo',
+      value: 'Hello World',
+      fileName: 'test/fixtures/files/hello.txt',
+      contentType: 'text/plain'
+    }
+  ]
+
+  // ignored
+  paramsObj: false
+
+  // the raw body in plain text
+  // generated based on appropriately parsing the `params` into a multi-boundary content string
+  // this value will be always overwritten in this scenario
+  text: '----------------------------771333709043252625002993\r\nContent-Disposition: form-data; name=\"foo\"; filename=\"hello.txt\"\r\nContent-Type: text/plain\r\n\r\nHello World\r\n----------------------------771333709043252625002993--'
+
+  // ignored
+  jsonObj: false
+}
+```

README.md

@@ -128,7 +128,6 @@ snippets/
 └── endpoint-3.js
 ```
 
-
 ### Module
 
 ```js

package.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.0.0-beta.10",
+  "version": "1.1.1",
   "name": "httpsnippet",
   "description": "HTTP Request snippet generator for *most* languages",
   "main": "./src/index.js",
@@ -40,6 +40,8 @@
     "chalk": "^1.0.0",
     "commander": "^2.6.0",
     "debug": "^2.1.1",
+    "event-stream": "^3.3.0",
+    "form-data": "^0.2.0",
     "har-validator": "^1.1.2",
     "require-directory": "^2.1.0"
   }