Inline 'Creating Targets' wiki page into CONTRIBUTING

This should let us remove wiki references and generally allow us to
start versioning all the documentation alongside the source code.

Author: pimterry

CONTRIBUTING.md

@@ -11,7 +11,7 @@ patches and features.
 ## Using the issue tracker
 
 The [issue tracker](/issues) is the preferred channel for [bug reports](#bug-reports),
-[features requests](#feature-requests) and [submitting pull requests](#pull-requests), 
+[features requests](#feature-requests) and [submitting pull requests](#pull-requests),
 but please respect the following restrictions:
 
 * Please **do not** use the issue tracker for personal support requests (use
@@ -136,4 +136,291 @@ license your work under the same license as that used by the project.
 
 ## Creating New Conversion Targets
 
-For a info on creating new conversion targets, please review this [guideline](https://github.com/Mashape/httpsnippet/wiki/Creating-Targets)
+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)*.
+
+###### Example
+
+```js
+module.exports = function (source, opts) {
+  // optionally process `opts` object for target specific configuration
+  //
+  // process `source` object
+  //
+  // return processed output as string
+};
+
+module.exports.info = {
+  key: 'curl',
+  title: 'cURL',
+  link: 'http://curl.haxx.se/',
+  description: 'curl is a command line tool and library for transferring data with URL syntax',
+  extname: '.sh'
+};
+```
+
+### Conversion Rules
+
+1. Start by reading and 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
+}
+```