sharetribe-flex-sdk 1.14.0

package/docs/keep-alive.md

@@ -0,0 +1,48 @@
+# Keep-Alive
+
+*Node.js only*
+
+By default, Node.js `http.Agent` and `https.Agent` create a new
+connection for each request. After the request is completed, the
+connection is closed. By keeping the connection open and reusing it
+for subsequent requests, the request time can be reduced. This is
+escpecially true for HTTPS connections, where the SSL handshake adds
+extra overhead for each request.
+
+The SDK can be configured to use custom `httpAgent` and `httpsAgent`,
+where the `keepAlive` can be set to `true`.
+
+Using persistent Keep-Alive connections is **recommended**.
+
+**Example:**
+
+``` js
+const express = require('express');
+const http = require('http');
+const https = require('https');
+const sharetribeSdk = require('sharetribe-flex-sdk');
+
+const app = express();
+
+// Instantiate HTTP(S) Agents with keepAlive set to true.
+// This will reduce the request time for consecutive requests by
+// reusing the existing TCP connection, thus eliminating the time used
+// for setting up new TCP connections.
+const httpAgent = new http.Agent({ keepAlive: true });
+const httpsAgent = new https.Agent({ keepAlive: true });
+
+app.get('/', (req, res) => {
+  // Initialize the SDK instance
+  const sdk = sharetribeSdk.createInstance({
+    clientId: "<your Client ID>",
+    baseUrl: "<your Base URL>",
+    httpAgent: httpAgent,
+    httpsAgent: httpsAgent
+  });
+
+  // Call the SDK to preload listings
+  sdk.listings.search({ ... }).then((listingsResult) => {
+    // do rendering etc.
+  });
+});
+```

package/docs/object-query-parameters.md

@@ -0,0 +1,36 @@
+# Object query parameters
+
+Some endpoints in the Flex Marketplace API require a specific syntax that allows
+passing one or more key-value pairs as the value of a single query parameter.
+The keys and values are colon-separated whereas the pairs are separated by
+semicolons. For example, when requesting custom image variants:
+
+``` js
+sdk.listings.show({
+  id: listingId,
+  include: ["images"],
+  "fields.image": ["variants.my-variant"],
+  "imageVariant.my-variant": "w:640;h:1280;fit:scale"
+}).then(res => {
+  // res.data contains the response data
+});
+```
+
+To simplify building requests like these, the SDK provides a utility method:
+`sharetribeSdk.util.objectQueryString`. It serializes an object into the correct
+string syntax. Using this method, the request above can be written as follows:
+
+``` js
+sdk.listings.show({
+  id: listingId,
+  include: ["images"],
+  "fields.image": ["variants.my-variant"],
+  "imageVariant.my-variant": sharetribeSdk.util.objectQueryString({
+    w: 640,
+    h: 1280,
+    fit: 'scale'
+  })
+}).then(res => {
+  // res.data contains the response data
+});
+```

package/docs/scripts.js

@@ -0,0 +1,41 @@
+(function() {
+
+  function anchorLink(id) {
+    var div = document.createElement('div');
+    div.className = 'heading-anchor';
+
+    if (id) {
+      // SVG Icon from: https://octicons.github.com/icon/link/
+      div.innerHTML = '<a href="#' + id + '"><svg width="16" height="16" viewBox="0 0 16 16" xmlns="http://www.w3.org/2000/svg"><title>link</title><path d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z" fill="#000" fill-rule="evenodd"/></svg></a>'
+    }
+    return div;
+  }
+
+  function renderAnchors() {
+    ["h1", "h2", "h3", "h4", "h5"].forEach(function(tagName) {
+      Array.from(document.getElementsByTagName(tagName)).forEach(function(headerElem) {
+        headerElem.prepend(anchorLink(headerElem.id));
+      });
+    });
+  }
+
+  function printWelcomeMessage() {
+    console.log("");
+    console.log("✨ Try the SDK in browser! ✨");
+    console.log("");
+    console.log("The SDK is loaded in window.sharetribeSdk global variable.");
+    console.log("");
+  }
+
+  document.addEventListener('DOMContentLoaded', function() {
+    // Render anchors when page is loaded
+    renderAnchors();
+    printWelcomeMessage();
+  }, false);
+
+  document.addEventListener('pjax:success', function() {
+    // Render anchors when page is changed
+    renderAnchors();
+  });
+
+})();

package/docs/serializing-types-to-json.md

@@ -0,0 +1,40 @@
+# Serializing types to and from JSON
+
+The SDK provides two helper functions to serialize and deserialize the
+data to and from JSON while retaining the type information.
+
+- `types.reviver`: Function to be passed to `JSON.parse`
+- `types.replacer`: Function to be passed to `JSON.stringify`
+
+Serializing the data to JSON may be necessary if you are saving the
+data to
+[LocalStorage](https://developer.mozilla.org/en-US/docs/Web/API/Storage/LocalStorage)
+or if you have a server that fetches the data and you want to pass the
+preloaded state to your [Redux
+store](https://redux.js.org/recipes/server-rendering#inject-initial-component-html-and-state).
+
+**Example:**
+
+```js
+const { reviver, replacer, UUID } = require('sharetribe-flex-sdk').types;
+
+const testData = {
+  id: new UUID('f989541d-7e96-4c8a-b550-dff1eef25815')
+};
+
+const roundtrip = JSON.parse(JSON.stringify(testData, replacer), reviver);
+
+assert(roundtrip.id.constructor.name === 'UUID');
+```
+
+**Please note:** [Your own types](#your-own-types) are not serialized.
+
+**Please note:** When the API call fails, [the error
+response](./calling-the-api.md#error-response) is wrapped in
+[Error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error)
+object. Stringifying Error object may result in unexpected results,
+e.g. in some browsers `JSON.stringify(new Error("error"))` returns an
+empty object. Because of this, it's recommended that you do not
+stringify the whole SDK responses as is, but instead pick the
+`status`, `statusText` and `data` fields from the response, and store
+and stringify those.

package/docs/sharing-session-between-client-and-server.md

@@ -0,0 +1,19 @@
+# Sharing session between client and server
+
+For server side rendering, the server needs to be able to prefetch the
+page data using the same user session than the client is using. For
+example, if the user logs in as "joe", the client needs to pass the
+session information to the server, so that the server is able to make
+requests as "joe". In other words, the client and server need share
+the same session information.
+
+The sharing of the session can be achieved by cookies. When the client
+SDK is configured to use the [Browser cookie
+store](./token-store.md#browser-cookie-store) (default) and the server
+SDK is configured to use the [Express cookie
+store](./token-store.md#express-cookie-store), both client and server
+are reading and writing the session to the same cookie. Thus, the
+session information will be shared between server and client.
+
+Have a look at the [Token store](./token-store.md) examples on how to
+configure the cookie stores.

package/docs/styles.css

@@ -0,0 +1,95 @@
+/**
+ * The fonts included are copyrighted by the vendor listed below.
+ *
+ * Vendor:      Mostardesign
+ * License URL: https://www.fontspring.com/licenses/mostardesign/webfont
+ *
+ */
+
+@font-face {
+    font-family: 'sofiapro';
+    src: url('https://assets-sharetribecom.sharetribe.com/webfonts/sofiapro/sofiapro-extralight-webfont.woff2') format('woff2');
+         url('https://assets-sharetribecom.sharetribe.com/webfonts/sofiapro/sofiapro-extralight-webfont.woff') format('woff');
+    font-weight: 200;
+    font-style: normal;
+}
+@font-face {
+    font-family: 'sofiapro';
+    src: url('https://assets-sharetribecom.sharetribe.com/webfonts/sofiapro/sofiapro-light-webfont.woff2') format('woff2');
+         url('https://assets-sharetribecom.sharetribe.com/webfonts/sofiapro/sofiapro-light-webfont.woff') format('woff');
+    font-weight: 300;
+    font-style: normal;
+}
+@font-face {
+    font-family: 'sofiapro';
+    src: url('https://assets-sharetribecom.sharetribe.com/webfonts/sofiapro/sofiapro-regular-webfont.woff2') format('woff2');
+         url('https://assets-sharetribecom.sharetribe.com/webfonts/sofiapro/sofiapro-regular-webfont.woff') format('woff');
+    font-weight: 400;
+    font-style: normal;
+}
+@font-face {
+    font-family: 'sofiapro';
+    src: url('https://assets-sharetribecom.sharetribe.com/webfonts/sofiapro/sofiapro-medium-webfont.woff2') format('woff2'),
+         url('https://assets-sharetribecom.sharetribe.com/webfonts/sofiapro/sofiapro-medium-webfont.woff') format('woff');
+    font-weight: 500; /* Medium */
+    font-style: normal;
+}
+@font-face {
+    font-family: 'sofiapro';
+    src: url('https://assets-sharetribecom.sharetribe.com/webfonts/sofiapro/sofiapro-semibold-webfont.woff2') format('woff2'),
+         url('https://assets-sharetribecom.sharetribe.com/webfonts/sofiapro/sofiapro-semibold-webfont.woff') format('woff');
+    font-weight: 600; /* SemiBold */
+    font-style: normal;
+}
+@font-face {
+    font-family: 'sofiapro';
+    src: url('https://assets-sharetribecom.sharetribe.com/webfonts/sofiapro/sofiapro-bold-webfont.woff2') format('woff2'),
+         url('https://assets-sharetribecom.sharetribe.com/webfonts/sofiapro/sofiapro-bold-webfont.woff') format('woff');
+    font-weight: 700; /* Bold */
+    font-style: normal;
+}
+
+body {
+    -webkit-font-smoothing: antialiased; /* http://szafranek.net/blog/2009/02/22/font-smoothing-explained/ */
+    -moz-osx-font-smoothing: grayscale; /* http://szafranek.net/blog/2009/02/22/font-smoothing-explained/ */
+    text-rendering: optimizeSpeed;
+}
+
+.markdown-body {
+    font-family: sofiapro, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";
+}
+
+h1, h2, h3, h4, h5 {
+    /* Position relative is needed for the hover anchor element */
+    position: relative;
+}
+
+h1:hover .heading-anchor,
+h2:hover .heading-anchor,
+h3:hover .heading-anchor,
+h4:hover .heading-anchor,
+h5:hover .heading-anchor {
+    display: block;
+}
+
+.heading-anchor {
+    display: none;
+    position: absolute;
+    left: -20px; /* -16px - right padding */
+    padding-right: 4px;
+    cursor: pointer;
+}
+
+.heading-anchor svg {
+    /* Make SVG inline block, so that we can finetune the bottom margin */
+    display: inline-block;
+}
+
+h1 .heading-anchor svg {
+    /* Fine tuning for nicer vertical alignment with the big h1 font size */
+    margin-bottom: 0.1em;
+}
+
+.heading-anchor:hover {
+    display: block;
+}

package/docs/token-store.md

@@ -0,0 +1,114 @@
+# Token store
+
+Token store is a pluggable SDK module, that stores the user's session information.
+
+The SDK ships with three token store implementations. They are:
+
+### Browser cookie store
+
+Reads and stores the session information to HTTP cookie. This token store
+is used by default, if SDK is used in environment where cookie are
+available (i.e. browser).
+
+The constructor takes the following options:
+
+| Key | Descriotion |
+| --- | ----------- |
+| `clientId` | The clientId |
+| `secure` | Boolean. When `true`, the cookie will be transferred only with HTTPS requests |
+
+**Please note:** Some browsers, like Google Chrome, do not set cookies
+when using `file:///` protocol. In this case, you can use [Memory
+store](#memory-store).
+
+### Express cookie store
+
+This token store is meant to be used with
+[Express.js](https://expressjs.com/) server. Read and stores the
+session information to HTTP cookie.
+
+The constructor takes the following options:
+
+| Key | Descriotion |
+| --- | ----------- |
+| `clientId` | The clientId |
+| `req` | Express.js request |
+| `res` | Express.js response |
+| `secure` | Boolean. When `true`, the cookie will be transferred only with HTTPS requests |
+
+**Example:** Create new SDK instance with Express cookie store:
+
+``` js
+const express = require('express');
+const cookieParser = require('cookie-parser');
+const sharetribeSdk = require('sharetribe-flex-sdk');
+
+const app = express();
+
+// The token store expects that cookieParser middleware is in use
+app.use(cookieParser());
+
+app.get('/', (req, res) => {
+  // Initialize the SDK instance
+  const sdk = sharetribeSdk.createInstance({
+    clientId: "<your Client ID>",
+    baseUrl: "<your Base URL>",
+    tokenStore: sharetribeSdk.tokenStore.expressCookieStore({
+      clientId: "<your Client ID>",
+      req,
+      res,
+      secure: true // Set to true, if you are using HTTPS
+    }),
+  });
+
+  // Call the SDK to preload listings
+  sdk.listings.search({ ... }).then((listingsResult) => {
+    // do rendering etc.
+  });
+});
+```
+
+**Serious security note:** Always create a new SDK instance per each request! Do not store and reuse the SDK instance or you may end up mixing user sessions.
+
+**❌ Example:** DON'T DO THIS!
+
+``` js
+// DON'T DO THIS!
+//
+let sdk;
+
+app.get('/', (req, res) => {
+  // Initialize the SDK instance
+  sdk = sharetribeSdk.createInstance({
+    clientId: "<your Client ID>",
+    baseUrl: "<your Base URL>",
+    tokenStore: sharetribeSdk.tokenStore.expressCookieStore({
+      clientId: "<your Client ID>",
+      req,
+      res,
+      secure: true // Set true, if you are using HTTPS
+    }),
+  });
+
+  // Call the SDK to preload listings
+  sdk.listings.search({ ... }).then((listingsResult) => {
+    // do rendering etc.
+  });
+});
+
+app.get('/something_else', (req, res) => {
+  // OOPS! The previous user session is used here!
+  sdk.listings.search({ ... }).then((listingsResult) => {
+    // do rendering etc.
+  });
+});
+
+```
+
+## Memory store
+
+Memory store stores the session information to application memory. The session information is lost when the page is refreshed.
+
+This store is mainly used for testing and development.
+
+In case you are testing locally from `file:///`, you may need to use memory store, because some browsers (e.g. Google Chrome) do not save cookies when using `file:///` making the default [Browser cookie store](#browser-cookie-store) unusable.

package/docs/try-it-in-browser.md

@@ -0,0 +1,32 @@
+# Try it in browser!
+
+The SDK is loaded in **this page!**
+
+To try the SDK, just open the Console in your browser's Developer
+Tools and call `sharetribeSdk.createInstance(...)` to create a new SDK
+instance.
+
+Then copy-paste the following commands to the Console:
+
+Set your clientId:
+
+```js
+const clientId = "<your clientId here>";
+```
+
+Create new SDK instance:
+
+```js
+const sdk = sharetribeSdk.createInstance({clientId});
+```
+
+Fetch 10 listings:
+
+```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);
+  })
+})
+```

package/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 useremail@yourdomain.com -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 useremail@yourdomain.com -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 useremail@yourdomain.com...
+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/docs/types.md

@@ -0,0 +1,27 @@
+# Types
+
+The SDK provides a set of types that complement the data types
+JavaScript supports out-of-the box. When calling the API endpoints,
+the SDK returns data using these types. It also expects these types
+given as parameters for the *queries* and *commands*.
+
+Here's a list of the provided types:
+
+| Name | Description | Constructor | Properties |
+| ---- | ----------- | ----------- | ---------- |
+| `UUID` | [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) | `new UUID(uuid)` | `uuid`<br /> |
+| `Money` | Amount of money in certain currency | `new Money(amount: Number, currency: String)` | `amount` The amount in subunit.<br />`currency`<br /> |
+| `LatLng` | Geolocation | `new LatLng(lat: Number, lng: Number)` | `lat`<br />`lng`<br /> |
+| `LatLngBounds` | Bounding box limited by North-East and South-West corners | `new LatLngBounds(ne: LatLng, sw: LatLng)` | `ne`<br />`sw`<br /> |
+| `BigDecimal` | Arbitrary precision decimal value | `new BigDecimal(value: String)` | `value` |
+
+**Example:**
+
+```js
+const { Money } = require('sharetribe-flex-sdk').types;
+
+const price = new Money(5000, 'USD');
+
+console.log("Amount in subunit (i.e. cents): " + price.amount)
+console.log("Currency: " + price.currency)
+```

package/docs/writing-your-own-token-store.md

@@ -0,0 +1,29 @@
+# Writing your own token store
+
+The SDK ships with three built-in token store implementations: Browser
+cookie store, Express cookie store and memory store. However, in some
+cases you may need to write your own cookie store, for example, if you
+want to save the cookie in some other location, such as
+[LocalStorage](https://developer.mozilla.org/en-US/docs/Web/API/Storage/LocalStorage).
+
+## Interface
+
+The Token store interface has three methods. Any token store
+implementation must implement all of them:
+
+**`setToken(Object) : null | Promise(null)`**
+
+Stores the new token. Returns either `null` or a `Promise`.
+
+**`getToken() : Object | Promise(Object)`**
+
+Reads the token from the store. Returns either a token or a Promise
+holding the token as a value.
+
+**`removeToken : null | Promise(null)`**
+
+Removes the stored token. Returns either `null` or a Promise.
+
+## Examples
+
+See the built-in token store implementations.