@readme/httpsnippet 3.1.1 → 4.0.0

package/README.md

@@ -1,10 +1,10 @@
 # HTTP Snippet [![version][npm-version]][npm-url] [![License][npm-license]][license-url]
 
-> HTTP Request snippet generator for *many* languages & tools including: `cURL`, `HTTPie`, `Javascript`, `Node`, `C`, `Java`, `PHP`, `Objective-C`, `Swift`, `Python`, `Ruby`, `C#`, `Go`, `OCaml` and [more](https://github.com/kong/httpsnippet/wiki/Targets)!
+> HTTP Request snippet generator for _many_ languages & tools including: `cURL`, `HTTPie`, `Javascript`, `Node`, `C`, `Java`, `PHP`, `Objective-C`, `Swift`, `Python`, `Ruby`, `C#`, `Go`, `OCaml` and [more](https://github.com/Kong/httpsnippet/wiki/Targets)!
 
 Relies on the popular [HAR](http://www.softwareishard.com/blog/har-12-spec/#request) format to import data and describe HTTP calls.
 
-See it in action on companion service: [APIembed](https://apiembed.com/)
+See it in action on [ReadMe](https://docs.readme.com/reference/getopenroles).
 
 [![Build](https://github.com/readmeio/httpsnippet/workflows/CI/badge.svg)](https://github.com/readmeio/httpsnippet)
 
@@ -20,17 +20,16 @@ npm install --save @readme/httpsnippet
 
 #### source
 
-*Required*
-Type: `object`
+_Required_ Type: `object`
 
-Name of [conversion target](https://github.com/kong/httpsnippet/wiki/Targets)
+Name of [conversion target](https://github.com/Kong/httpsnippet/wiki/Targets)
 
-```js
-const HTTPSnippet = require('httpsnippet');
+```ts
+import { HTTPSnippet } from 'httpsnippet';
 
 const snippet = new HTTPSnippet({
   method: 'GET',
-  url: 'https://httpbin.com/anything'
+  url: 'https://httpbin.org/anything',
 });
 ```
 
@@ -46,130 +45,132 @@ Available options:
 
 #### target
 
-*Required*
-Type: `string`
+_Required_ Type: `string`
 
-Name of [conversion target](https://github.com/kong/httpsnippet/wiki/Targets)
+Name of [conversion target](https://github.com/Kong/httpsnippet/wiki/Targets)
 
 #### options
 
 Type: `object`
 
-Target options, *see [wiki](https://github.com/kong/httpsnippet/wiki/Targets) for details*
+Target options, _see [wiki](https://github.com/Kong/httpsnippet/wiki/Targets) for details_
 
-```js
-const HTTPSnippet = require('httpsnippet');
+```ts
+import { HTTPSnippet } from 'httpsnippet';
 
 const snippet = new HTTPSnippet({
   method: 'GET',
-  url: 'https://httpbin.com/anything'
+  url: 'httsp://httpbin.org/anything',
 });
 
 // generate Node.js: Native output
 console.log(snippet.convert('node'));
 
 // generate Node.js: Native output, indent with tabs
-console.log(snippet.convert('node', {
-  indent: '\t'
-}));
+console.log(
+  snippet.convert('node', {
+    indent: '\t',
+  }),
+);
 ```
 
 ### convert(target [, client, options])
 
-#### target
+#### Target
 
-*Required*
-Type: `string`
+_Required_ Type: `string`
 
-Name of [conversion target](https://github.com/kong/httpsnippet/wiki/Targets)
+Name of [conversion target](https://github.com/Kong/httpsnippet/wiki/Targets)
 
-#### client
+#### Client
 
 Type: `string`
 
-Name of conversion target [client library](https://github.com/kong/httpsnippet/wiki/Targets)
+Name of conversion target [client library](https://github.com/Kong/httpsnippet/wiki/Targets)
 
-#### options
+#### Options
 
 Type: `object`
 
-Target options, *see [wiki](https://github.com/kong/httpsnippet/wiki/Targets) for details*
+Target options, _see [wiki](https://github.com/Kong/httpsnippet/wiki/Targets) for details_
 
-```js
-const HTTPSnippet = require('httpsnippet');
+```ts
+import { HTTPSnippet } from 'httpsnippet';
 
 const snippet = new HTTPSnippet({
   method: 'GET',
-  url: 'https://httpbin.com/anything'
+  url: 'https://httpbin.org/anything',
 });
 
 // generate Shell: cURL output
-console.log(snippet.convert('shell', 'curl', {
-  indent: '\t'
-}));
+console.log(
+  snippet.convert('shell', 'curl', {
+    indent: '\t',
+  }),
+);
 
 // generate Node.js: Unirest output
 console.log(snippet.convert('node', 'unirest'));
 ```
 
 ### addTarget(target)
+
 #### target
 
-*Required*
-Type: `object`
+_Required_ Type: `object`
 
 Representation of a [conversion target](https://github.com/Kong/httpsnippet/wiki/Creating-Targets). Can use this to use targets that are not officially supported.
 
-```js
-const customLanguageTarget = require('httpsnippet-for-my-lang');
+```ts
+import { customLanguageTarget } from 'httpsnippet-for-my-lang';
 HTTPSnippet.addTarget(customLanguageTarget);
 ```
 
 ### addTargetClient(target, client)
-### target
 
-*Required*
-Type: `string`
+### Target
 
-Name of [conversion target](https://github.com/kong/httpsnippet/wiki/Targets)
+_Required_ Type: `string`
 
-### client
+Name of [conversion target](https://github.com/Kong/httpsnippet/wiki/Targets)
 
-*Required*
-Type: `object`
+### Client
+
+_Required_ Type: `object`
 
 Representation of a [conversion target client](https://github.com/Kong/httpsnippet/wiki/Creating-Targets). Can use this to use target clients that are not officially supported.
 
-```js
-const customClient = require('httpsnippet-for-my-node-http-client');
+```ts
+import { customClient } from 'httpsnippet-for-my-node-http-client';
 HTTPSnippet.addTargetClient('node', customClient);
 ```
 
 ## Documentation
 
-At the heart of this module is the [HAR Format](http://www.softwareishard.com/blog/har-12-spec/#request) as the HTTP request description format, please review some of the sample JSON HAR Request objects in [test fixtures](/__tests__/__fixtures__/requests), or read the [HAR Docs](http://www.softwareishard.com/blog/har-12-spec/#request) for more details.
+At the heart of this module is the [HAR Format](http://www.softwareishard.com/blog/har-12-spec/#request) as the HTTP request description format, please review some of the sample JSON HAR Request objects in [test fixtures](/test/fixtures/requests), or read the [HAR Docs](http://www.softwareishard.com/blog/har-12-spec/#request) for more details.
 
-For detailed information on each target, please review the [wiki](https://github.com/kong/httpsnippet/wiki).
+For detailed information on each target, please review the [wiki](https://github.com/Kong/httpsnippet/wiki).
 
 ## Differences from `kong/httpsnippet`
 
-The main difference between this library and the upstream [httpsnippet](https://github.com/Kong/httpsnippet) library are:
+There are some major differences between this library and the [httpsnippet](https://github.com/Kong/httpsnippet) upstream:
 
+* Includes a full integration test suite for a handful of clients and targets.
 * Does not ship with a CLI component.
-* The `fetch` target for Node and JS both treat body payloads as an object literal and wrap it within `JSON.stringify()`. We do this to keep those targets looking nicer with those kinds of payloads.
-* Contains a `harIsAlreadyEncoded` option on the core library to disable [escaping](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent) of cookies and query strings in URLs. Helpful if the HAR being supplied already has them escaped.
-* PHP Guzzle snippets come with `require_once('vendor/autoload.php');` at the top of them.
-* A full integration suite for testing out snippets the library creates.
-* This library does not ship a Python client for [http.client](https://docs.python.org/3/library/http.client.html) due to its limitations in supporting file uploads.
-
-### Running the integration suite
-
-```
-docker-compose run integration_node
-docker-compose run integration_php
-docker-compose run integration_python
-docker-compose run integration_shell
-```
+* The main `HTTPSnippet` export contains an `options` argument for an `harIsAlreadyEncoded` option for disabling [escaping](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent) of cookies and query strings in URLs.
+  * We added this because all HARs that we interact with already have this data escaped and this option prevents them from being double encoded, thus corrupting the data.
+* Node
+  * `fetch`
+    * Body payloads are treated as an object literal and wrapped within `JSON.stringify()`. We do this to keep those targets looking nicer with those kinds of payloads. This also applies to the JS `fetch` target as wel.
+  * `request`
+    * Does not provide query string parameters in a `params` argument due to complexities with query encoding.
+* PHP → `guzzle`
+  * Snippets have `require_once('vendor/autoload.php');` prefixed at the top.
+* Python
+  * `python3`
+    * Does not ship this client due to its incompatibility with being able to support file uploads.
+  * `requests`
+    * Does not provide query string parameters in a `params` argument due to complexities with query encoding.
 
 ## License
 

package/package.json

@@ -1,10 +1,11 @@
 {
-  "version": "3.1.1",
+  "version": "4.0.0",
   "name": "@readme/httpsnippet",
   "description": "HTTP Request snippet generator for *most* languages",
   "homepage": "https://github.com/readmeio/httpsnippet",
   "license": "MIT",
-  "main": "src/index.js",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "keywords": [
     "api",
     "clojure",
@@ -36,7 +37,7 @@
     "xmlhttprequest"
   ],
   "engines": {
-    "node": ">=10"
+    "node": ">=14"
   },
   "files": [
     "bin",
@@ -47,35 +48,39 @@
     "url": "https://github.com/readmeio/httpsnippet.git"
   },
   "scripts": {
+    "build": "tsc --build tsconfig.build.json",
+    "clean": "tsc --build tsconfig.build.json --clean",
     "lint": "eslint .",
+    "prebuild": "npm run clean",
     "pretest": "npm run lint",
     "prettier": "prettier --list-different --write \"./**/**.js\"",
     "test": "jest --coverage"
   },
   "devDependencies": {
-    "@readme/eslint-config": "^8.0.2",
-    "eslint": "^8.3.0",
-    "glob": "^7.1.7",
-    "jest": "^27.2.0",
-    "prettier": "^2.5.0",
-    "require-directory": "^2.1.1"
+    "@readme/eslint-config": "^8.8.3",
+    "@types/eslint": "^8.4.1",
+    "@types/event-stream": "^4.0.0",
+    "@types/har-format": "^1.2.8",
+    "@types/jest": "^27.4.1",
+    "@types/node": "^16.11.26",
+    "@types/qs": "^6.9.7",
+    "@types/stringify-object": "^4.0.1",
+    "eslint": "^8.19.0",
+    "glob": "^8.0.1",
+    "jest": "^28.0.3",
+    "prettier": "^2.7.1",
+    "require-directory": "^2.1.1",
+    "ts-jest": "^28.0.5",
+    "type-fest": "^2.12.2",
+    "typescript": "^4.6.3"
   },
   "dependencies": {
+    "ajv": "^6.12.6",
     "event-stream": "4.0.1",
     "form-data": "^4.0.0",
-    "har-validator": "^5.0.0",
+    "har-schema": "^2.0.0",
     "qs": "^6.10.1",
     "stringify-object": "^3.3.0"
   },
-  "prettier": "@readme/eslint-config/prettier",
-  "jest": {
-    "coveragePathIgnorePatterns": [
-      "<rootDir>/__tests__/(.*)/__fixtures__/",
-      "<rootDir>/node_modules"
-    ],
-    "testPathIgnorePatterns": [
-      "<rootDir>/__tests__/__fixtures__/",
-      "<rootDir>/__tests__/targets/"
-    ]
-  }
+  "prettier": "@readme/eslint-config/prettier"
 }

package/src/fixtures/customTarget.ts

@@ -0,0 +1,14 @@
+import type { Target } from '../targets/targets';
+import { request } from '../targets/node/request/client';
+
+export const customTarget = {
+  info: {
+    key: 'js-variant',
+    title: 'JavaScript Variant',
+    extname: '.js',
+    default: 'request',
+  },
+  clientsById: {
+    request,
+  },
+} as unknown as Target;

package/src/fixtures/files/hello.txt

@@ -0,0 +1 @@
+Hello World

package/src/fixtures/mimetypes.ts

@@ -0,0 +1,84 @@
+import type { Request } from '..';
+
+export const mimetypes = {
+  'multipart/mixed': {
+    method: 'POST',
+    url: 'https://httpbin.org/anything',
+    postData: {
+      mimeType: 'multipart/mixed',
+      text: '',
+    },
+  } as Request,
+
+  'multipart/related': {
+    method: 'POST',
+    url: 'https://httpbin.org/anything',
+    postData: {
+      mimeType: 'multipart/related',
+      text: '',
+    },
+  } as Request,
+
+  'multipart/form-data': {
+    method: 'POST',
+    url: 'https://httpbin.org/anything',
+    postData: {
+      mimeType: 'multipart/form-data',
+      text: '',
+    },
+  } as Request,
+
+  'multipart/alternative': {
+    method: 'POST',
+    url: 'https://httpbin.org/anything',
+    postData: {
+      mimeType: 'multipart/alternative',
+      text: '',
+    },
+  } as Request,
+
+  'application/x-www-form-urlencoded': {
+    method: 'POST',
+    url: 'https://httpbin.org/anything',
+    postData: {
+      mimeType: 'application/x-www-form-urlencoded',
+      text: '',
+    },
+  } as Request,
+
+  'text/json': {
+    method: 'POST',
+    url: 'https://httpbin.org/anything',
+    postData: {
+      mimeType: 'text/json',
+      text: '',
+    },
+  } as Request,
+
+  'text/x-json': {
+    method: 'POST',
+    url: 'https://httpbin.org/anything',
+    postData: {
+      mimeType: 'text/x-json',
+      text: '',
+    },
+  } as Request,
+
+  'application/x-json': {
+    method: 'POST',
+    url: 'https://httpbin.org/anything',
+    postData: {
+      mimeType: 'application/x-json',
+      text: '',
+    },
+  } as Request,
+
+  'invalid-json': {
+    method: 'POST',
+    url: 'https://httpbin.org/anything',
+    postData: {
+      mimeType: 'application/json',
+      text: 'foo/bar',
+    },
+  } as Request,
+};

package/src/fixtures/requests/application-form-encoded.js

@@ -0,0 +1,68 @@
+module.exports = {
+  log: {
+    version: '1.2',
+    creator: {
+      name: 'HTTPSnippet',
+      version: '1.0.0',
+    },
+    entries: [
+      {
+        request: {
+          method: 'POST',
+          url: 'https://httpbin.org/anything',
+          headers: [
+            {
+              name: 'content-type',
+              value: 'application/x-www-form-urlencoded',
+            },
+          ],
+          postData: {
+            mimeType: 'application/x-www-form-urlencoded',
+            params: [
+              {
+                name: 'foo',
+                value: 'bar',
+              },
+              {
+                name: 'hello',
+                value: 'world',
+              },
+            ],
+          },
+        },
+        response: {
+          status: 200,
+          statusText: 'OK',
+          httpVersion: 'HTTP/1.1',
+          headers: [
+            {
+              name: 'Content-Type',
+              value: 'application/json',
+            },
+          ],
+          content: {
+            size: -1,
+            mimeType: 'application/json',
+            text: JSON.stringify({
+              args: {},
+              data: '',
+              files: {},
+              form: {
+                foo: 'bar',
+                hello: 'world',
+              },
+              headers: {
+                'Content-Type': 'application/x-www-form-urlencoded',
+              },
+              json: null,
+              method: 'POST',
+              url: 'https://httpbin.org/anything',
+            }),
+          },
+          headersSize: -1,
+          bodySize: -1,
+        },
+      },
+    ],
+  },
+};

package/src/fixtures/requests/application-json.js

@@ -0,0 +1,71 @@
+module.exports = {
+  log: {
+    version: '1.2',
+    creator: {
+      name: 'HTTPSnippet',
+      version: '1.0.0',
+    },
+    entries: [
+      {
+        request: {
+          method: 'POST',
+          url: 'https://httpbin.org/anything',
+          headers: [
+            {
+              name: 'content-type',
+              value: 'application/json',
+            },
+          ],
+          postData: {
+            mimeType: 'application/json',
+            text: '{"number":1,"string":"f\\"oo","arr":[1,2,3],"nested":{"a":"b"},"arr_mix":[1,"a",{"arr_mix_nested":{}}],"boolean":false}',
+          },
+        },
+        response: {
+          status: 200,
+          statusText: 'OK',
+          httpVersion: 'HTTP/1.1',
+          headers: [
+            {
+              name: 'Content-Type',
+              value: 'application/json',
+            },
+          ],
+          content: {
+            size: -1,
+            mimeType: 'application/json',
+            text: JSON.stringify({
+              args: {},
+              data: '{\n  "number": 1,\n  "string": "f\\"oo",\n  "arr": [\n    1,\n    2,\n    3\n  ],\n  "nested": {\n    "a": "b"\n  },\n  "arr_mix": [\n    1,\n    "a",\n    {\n      "arr_mix_nested": {}\n    }\n  ],\n  "boolean": false\n}',
+              files: {},
+              form: {},
+              headers: {
+                'Content-Type': 'application/json',
+              },
+              json: {
+                arr: [1, 2, 3],
+                arr_mix: [
+                  1,
+                  'a',
+                  {
+                    arr_mix_nested: {},
+                  },
+                ],
+                boolean: false,
+                nested: {
+                  a: 'b',
+                },
+                number: 1,
+                string: 'f"oo',
+              },
+              method: 'POST',
+              url: 'https://httpbin.org/anything',
+            }),
+          },
+          headersSize: -1,
+          bodySize: -1,
+        },
+      },
+    ],
+  },
+};

package/src/fixtures/requests/cookies.js

@@ -0,0 +1,50 @@
+module.exports = {
+  log: {
+    version: '1.2',
+    creator: {
+      name: 'HTTPSnippet',
+      version: '1.0.0',
+    },
+    entries: [
+      {
+        request: {
+          method: 'GET',
+          url: 'https://httpbin.org/cookies',
+          cookies: [
+            {
+              name: 'foo',
+              value: 'bar',
+            },
+            {
+              name: 'bar',
+              value: 'baz',
+            },
+          ],
+        },
+        response: {
+          status: 200,
+          statusText: 'OK',
+          httpVersion: 'HTTP/1.1',
+          headers: [
+            {
+              name: 'Content-Type',
+              value: 'application/json',
+            },
+          ],
+          content: {
+            size: -1,
+            mimeType: 'application/json',
+            text: JSON.stringify({
+              cookies: {
+                bar: 'baz',
+                foo: 'bar',
+              },
+            }),
+          },
+          headersSize: -1,
+          bodySize: -1,
+        },
+      },
+    ],
+  },
+};

package/src/fixtures/requests/custom-method.js

@@ -0,0 +1,40 @@
+module.exports = {
+  log: {
+    version: '1.2',
+    creator: {
+      name: 'HTTPSnippet',
+      version: '1.0.0',
+    },
+    entries: [
+      {
+        request: {
+          method: 'PROPFIND',
+          url: 'https://httpbin.org/anything',
+        },
+        response: {
+          status: 405,
+          statusText: 'Method Not Allowed',
+          httpVersion: 'HTTP/1.1',
+          headers: [
+            {
+              name: 'Content-Type',
+              value: 'text/html',
+            },
+          ],
+          content: {
+            size: -1,
+            mimeType: 'text/html',
+            text: [
+              '<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">',
+              '<title>405 Method Not Allowed</title>',
+              '<h1>Method Not Allowed</h1>',
+              '<p>The method is not allowed for the requested URL.</p>',
+            ].join('\n'),
+          },
+          headersSize: -1,
+          bodySize: -1,
+        },
+      },
+    ],
+  },
+};