Merge pull request #109 from sharetribe/from-repl-to-playground

From REPL to Playground

CHANGELOG.md

@@ -8,6 +8,16 @@ adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased] - xxxx-xx-xx
 
+## [v1.10.0] - 2020-02-28
+
+### Changed
+
+- The JS SDK Repl environment replaced with a new API Playground
+  [109](https://github.com/sharetribe/flex-sdk-js/pull/109)
+  - Support starting in an initialized and authenticated modes
+  - Support running scripts
+  - Add helpers and support all API value types
+
 ## [v1.9.1] - 2020-02-18
 
 ### Fixed

docs/README.md

@@ -3,7 +3,7 @@
 * [Sharetribe Flex SDK for JavaScript](../README.md)
 * [Features](./features.md)
 * [Try it in browser!](./try-it-in-browser.md)
-* [Try it in command-line!](./try-it-in-command-line.md)
+* [Try it in the API Playground!](./try-it-in-the-playground.md)
 * Getting started
   * [Authentication](./authentication.md)
   * [Calling the API](./calling-the-api.md)

docs/try-it-in-the-playground.md

@@ -0,0 +1,153 @@
+# Try it in the API Playground!
+
+The SDK ships with a command-line based API Playground. You can use
+the Playground to try out the SDK with real API access to learn and
+test things. It also supports executing scripts against the API.
+
+To start the Playground, go to the directory where you cloned the SDK
+Git repository and type:
+
+```
+$ yarn run playground --clientid <CLIENT-ID>
+```
+
+or use the shorthand:
+```
+$ yarn run pg -c <CLIENT-ID>
+```
+
+This will start the playground using your Marketplace API Client ID to
+connect to to your marketplace. You can create a new or find your
+existing Client ID in Flex Console at
+https://flex-console.sharetribe.com/applications.
+
+## Making API Requests
+
+You can make API requests to the Marketplace API and print the results
+using the built-in response printer:
+
+```js
+sdk.listings.query({per_page: 5}).then(printResponse);
+```
+
+Alternatively you can use the pr() helper function:
+```js
+sdk.listings.query({per_page: 5});
+pr();
+```
+
+You can also do custom processing of responses:
+
+```js
+sdk.listings.query({per_page: 10}).then(response => {
+  console.log("Fetched " + response.data.data.length + " listings.");
+  response.data.data.forEach(listing => {
+    console.log(listing.attributes.title);
+  });
+});
+```
+
+## Authenticated access
+
+To start the Playground in a user authenticated mode you can pass in
+the user info you want to log in with:
+
+```
+$ yarn run pg -c <CLIENT-ID> -u [email protected] -s user-secret-password
+```
+
+In the Playground you can now make requests authenticated as the user:
+
+```js
+sdk.currentUser.show().then(printResponse);
+```
+
+## Viewing Marketplace API reference documentation
+
+The Playground has a command for opening the Marketplace API reference
+documentation in browser:
+
+```
+$ yarn run pg --apidocs
+```
+
+You can also do this in a playground session using the built-in
+apiDocs function:
+
+```js
+apiDocs();
+```
+
+## Scripting support
+
+The Playground also supports reading commands from a script file. The
+commands from the given file are read as if they were lines entered
+into an interactive Playground.
+
+Let's say you have a script file create-listing.js for creating a new
+listing for the logged in user:
+
+```js
+sdk.ownListings.query().then(res => {
+  console.log(`You have ${res.data.data.length} listings.`);
+}).then(_ => {
+  console.log('Creating a new listings');
+  return sdk.ownListings.create({
+    title: "My new listings",
+    description: "A shiny new listing",
+    geolocation: new LatLng(40.64542, -74.08508),
+    price: new Money(1590, "USD"),
+    publicData: {
+      category: 'Electric',
+      gears: 22
+    }
+  });
+}).then(res => {
+  console.log(`Created a new listings with id ${res.data.data.id.uuid}`);
+  return sdk.ownListings.query();
+}).then(res => {
+  console.log(`You now have ${res.data.data.length} listings.`);
+});
+```
+
+You can execute the script by running:
+
+```
+$ yarn run pg -c <CLIENT-ID> -u [email protected] -s user-secret-password --script create-listing.js
+```
+
+The output will look something like:
+
+```
+Initializing SDK instance with Client ID: <CLIENT-ID>...
+Successfully connected to Saunatime marketplace.
+Logging in user [email protected]...
+Executing script...
+
+> sdk.ownListings.query().then(res => {
+...   console.log(`You have ${res.data.data.length} listings.`);
+... }).then(() => {
+...   console.log('Creating a new listing');
+...   return sdk.ownListings.create({
+.....     title: "My new listings",
+.....     description: "A shiny new listing",
+.....     geolocation: new LatLng(40.64542, -74.08508),
+.....     price: new Money(1590, "USD"),
+.....     publicData: {
+.......       category: 'Electric',
+.......       gears: 22
+.......     }
+.....   });
+... }).then(res => {
+...   console.log(`Created a new listing with id ${res.data.data.id.uuid}`);
+...   return sdk.ownListings.query();
+... }).then(res => {
+...   console.log(`You now have ${res.data.data.length} listings.`);
+... });
+
+> You have 10 listings.
+Creating a new listing
+Created a new listing with id 5e579343-0241-4d73-a50a-d8c5062feb86
+You now have 11 listings.
+```
+

package.json

@@ -1,14 +1,15 @@
 {
   "name": "sharetribe-flex-sdk",
-  "version": "1.9.1",
+  "version": "1.10.0",
   "description": "Sharetribe Flex SDK for JavaScript",
   "main": "build/sharetribe-flex-sdk-node.js",
   "browser": "build/sharetribe-flex-sdk-web.js",
   "scripts": {
     "build": "webpack",
     "lint": "eslint .",
     "test": "jest",
-    "repl": "babel-node repl.js",
+    "playground": "babel-node playground.js",
+    "pg": "babel-node playground.js",
     "format": "prettier --write --print-width 100 --single-quote --trailing-comma es5 'src/**/*.js' 'examples/**/*.js'",
     "serve-docs": "docpress serve",
     "build-docs": "docpress build"
@@ -42,6 +43,9 @@
     "babel-loader": "^8.0.0",
     "babel-plugin-lodash": "^3.3.4",
     "colors": "^1.3.1",
+    "command-line-args": "^5.1.1",
+    "command-line-usage": "^6.0.1",
+    "open": "^7.0.2",
     "docpress": "^0.7.6",
     "eslint": "^5.3.0",
     "eslint-config-airbnb-base": "^13.0.0",
@@ -50,7 +54,6 @@
     "eslint-plugin-jest": "^21.18.0",
     "jest": "^24.8.0",
     "prettier": "^1.14.0",
-    "repl.history": "^0.1.4",
     "webpack": "^3.12.0"
   },
   "dependencies": {