sharetribe-flex-sdk 1.14.0

package/docs/README.md

@@ -0,0 +1,20 @@
+# Documentation
+
+* [Sharetribe Flex SDK for JavaScript](../README.md)
+* [Features](./features.md)
+* [Try it in browser!](./try-it-in-browser.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)
+  * [Types](./types.md)
+* Advanced
+  * [Configurations](./configurations.md)
+  * [Your own types](./your-own-types.md)
+  * [Serializing types to JSON](./serializing-types-to-json.md)
+  * [Object query parameters](./object-query-parameters.md)
+  * [Token store](./token-store.md)
+  * [Sharing session between client and server](sharing-session-between-client-and-server.md)
+  * [Keep-Alive](./keep-alive.md)
+  * [Writing your own token store](./writing-your-own-token-store.md)
+* [Developing SDK](./developing-sdk.md)

package/docs/authentication.md

@@ -0,0 +1,179 @@
+# Authentication
+
+The SDK provides methods to log the user in and out and determine if
+the user is already logged in or not.
+
+## Login
+
+**`sdk.login({ username: string, password: string }) : Promise`**
+
+Logs in the user and returns a Promise.
+
+The session information will be saved to the SDK instance when the
+Promise is resolved. Subsequent requests will be made as the logged in
+user.
+
+## Logout
+
+**`sdk.logout() : Promise`**
+
+Logs out the user and returns a Promise.
+
+**Trobleshooting:** In case you're testing locally from `file:///`,
+the session information may not be saved after successful login. In
+this case, you should configure the SDK to use [memory-based token
+store](./token-store.md#memory-store).
+
+## Login with IdP
+
+**`sdk.loginWithIdp({ idpId: string, idpClientId: string, idpToken: string }) : Promise`**
+
+Logs in the user with information from an identity provider (e.g. Facebook) and
+returns a Promise. User can be authenticated if the `idpToken` can be verified
+and an identity provider account resolved from the token is associated with a
+Flex account or if an email address resolved from the token matches a verified
+email of a Flex account.
+
+`sdk.loginWithIdp` requires that the SDK instance is initialized with a
+`clientSecret` attribute.
+
+The session information will be saved to the SDK instance when the
+Promise is resolved. Subsequent requests will be made as the logged in
+user.
+
+## Determine if user is logged in
+
+**`sdk.authInfo() : Promise(Object)`**
+
+Returns a Promise with an Object as a value. The object may contain two fields:
+
+- `scopes`: an array containing the scopes associated with the currently stored token
+- `isAnonymous`: a boolean denoting if the currently stored token only allows public read access
+
+To determine if the user is logged in, check if `isAnonymous` equals
+`false`.
+
+**Example:**
+
+```js
+sdk.authInfo().then(authInfo => {
+  if (authInfo && authInfo.isAnonymous === false) {
+    console.log("User is logged in.");
+  } else {
+    console.log("User is NOT logged in.")
+  }
+};
+```
+
+**Please note:** Even thought the `authInfo` method returns a Promise,
+the method does not call the API. The authentication information is
+saved locally in the [token store](./token-store.md).
+
+**Please note:** The token store does not store any other user
+information in addition to the authentication token. If you need, for
+example, to know the name of the logged in user, you need to call
+`sdk.current_user.show()`, which calls the corresponding API endpoint.
+
+## Authentication example
+
+Here's a full example how to log user in and out and determine the
+current authentication status.
+
+**Example:**
+
+```js
+const isLoggedIn = (authInfo) => authInfo && authInfo.isAnonymous === false;
+
+sdk
+  .authInfo()
+  .then((authInfo) => {
+    console.log(`Logged in: ${isLoggedIn(authInfo)}`);
+    // prints: "Logged in: false"
+
+    return sdk.login({
+      username: "test-user@example.com",
+      password: "test-secret",
+    });
+  })
+  .then((loginRes) => {
+    console.log("Login successful!");
+
+    return sdk.authInfo();
+  })
+  .then((authInfo) => {
+    console.log(`Logged in: ${isLoggedIn(authInfo)}`);
+    // prints: "Logged in: true"
+
+    return sdk.currentUser.show();
+  })
+  .then((userRes) => {
+    const profile = userRes.data.data.attributes.profile;
+    console.log(`Current user: ${profile.firstName} ${profile.lastName}`);
+
+    return sdk.logout();
+  })
+  .then((logoutRes) => {
+    console.log("Logged out!");
+
+    return sdk.authInfo();
+  })
+  .then((authInfo) => {
+    console.log(`Logged in: ${isLoggedIn(authInfo)}`);
+    // prints: "Logged in: false"
+  })
+  .catch((res) => {
+    // An error occurred
+    console.log(`Request failed with status: ${res.status} ${res.statusText}`);
+  });
+```
+
+## Exchange token
+
+**`sdk.exchangeToken() : Promise`**
+
+A valid access token can be exchanged to a trusted token when combined with a client
+secret. A trusted token is required by the Flex APIs for certain requests, for
+example, [privileged
+transitions](https://www.sharetribe.com/docs/background/privileged-transitions/).
+
+In order to exchange an access token, a valid access token needs to be stored in
+the SDK's token store. This can be achieved by logging in or by initializing the
+SDK with a token store that holds an access token.
+
+**Example:**
+
+```js
+const sdk = sharetribeSdk.createInstance({
+  clientId: "a client ID",
+  clientSecret: "a client secret",
+  tokenStore: sharetribeSdk.tokenStore.memoryStore(),
+});
+
+sdk.login({ username: "test-user@example.com", password: "test-secret" });
+
+sdk.exchangeToken().then((res) => {
+  console.log("Trusted token: ", res.data);
+});
+```
+
+## Seeing occasional 401 errors?
+
+Are you seeing occasional 401 errors in the browser's Web Console?
+Don't worry! That's part of the normal operations.
+
+Flex API uses two authentication tokens for each session:
+
+- _Access token_ that is used to authenticate the user. Valid only a
+  short amount of time.
+- _Refresh token_ that is used to issue a fresh authentication
+  token. Long lived.
+
+When _access token_ expires, you will see a 401 error in browser's Web
+Console. The SDK will handle this and automatically issue new fresh
+authentication token and retry the request. This all happens under the
+hood and you don't need to worry about it. SDK will do the heavy
+lifting.
+
+See [Authentication API reference
+document](https://www.sharetribe.com/api-reference/authentication.html)
+for more information.

package/docs/calling-the-api.md

@@ -0,0 +1,217 @@
+# Calling the API
+
+## API Endpoints
+
+The SDK provides direct mapping from API endpoints to SDK methods.
+
+For example:
+
+`GET /api/marketplace/show` maps to `sdk.marketplace.show(...)`
+
+`GET /api/listings/query` maps to `sdk.listings.query(...)`
+
+`POST /api/own_listings/create` maps to `sdk.ownListings.create(...)`
+
+## Parameters
+
+You can pass a set of parameters to the SDK method you call. The
+*query* endpoints take one parameter, where as the *command* endpoints
+take three parameters.
+
+**Please note:** The SDK does not validate the parameters. The
+parameter validation is only done in the client side. In case of
+invalid parameters, the request fill fail.
+
+### Query method parameters
+
+The *query* (GET) methods take only one parameter:
+
+* `queryParams`: Object of query parameters
+
+**Example:**
+
+```js
+sdk.listings.query({perPage: 5})
+
+// Calls GET /api/listings/query?perPage=5
+```
+
+The `queryParams` is optional. If the endpoint doesn't require any
+query parameters, you can call the SDK method without any parameters.
+
+### Command method parameters
+
+The *command* (POST) methods take three parameters:
+
+* `bodyParams`: Object of body parameters
+* `queryParams`: Object of query parameters
+* `opts`: Additional options
+
+**Example:**
+
+```js
+sdk.ownListings.create({title: 'New listings', price: new Money(5000, 'USD')}, {expand: true});
+
+// Calls POST /api/own_listings/create?expand=true
+// with title and price serialized in the request body
+```
+
+All parameters are optional. If the endpoint doesn't require any body
+parameters, query parameters or options, you can call the SDK method
+without any parameters.
+
+If you wonder what the `new Money(...)` is, have a look at [Types](./types.md).
+
+### Command method options
+
+The third parameter for *command* methods is `opts`.
+
+Here's a list of available `opts`:
+
+* `onUploadProcess`: Takes a callback function that is called with [ProgressEvent](https://developer.mozilla.org/en-US/docs/Web/API/ProgressEvent).
+
+**Example:**
+
+```js
+const logProgress = (progressEvent) => {
+  const percentCompleted = Math.round((progressEvent.loaded * 100) / progressEvent.total);
+  console.log(percentCompleted + '% completed');
+}
+
+sdk.listings.uploadImage({ image: file }, {}, { onUploadProgress: logProgress })
+```
+
+## Response
+
+Calling any SDK method will always return a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). The value of the Promise differs whether the request was successful or error. In case of successful request the Promise will be *fulfilled* where as in case of error the Promise will be *rejected*.
+
+**Example:**
+
+```js
+const promise = sdk.listings.query();
+
+// Handle success response
+promise.then(response => { console.log(response)} );
+
+// Handle error response
+promise.catch(response => { console.log(response)} );
+```
+
+### Success response
+
+A successful response will have the following format:
+
+```
+{
+  status: 200,
+  statusText: 'OK',
+  data: // The data returned by the API. Object.
+}
+```
+
+The API returns the data always in the following format:
+
+```
+{
+  data: // Either an array of resources or just a single resource
+  meta: {} // Object containing metadata, such as pagination information
+  included: [] // Array of included responses
+}
+```
+
+**Example:** Response from query that returns multiple listings.
+
+```
+{
+  status: 200,
+  statusText: 'OK',
+  data: {
+    data: [
+      {
+        id: '5a8d820f-8cb9-4855-96bf-5a6e1db31362',
+        type: 'listing',
+        attributes: {
+          title: '...'
+          description: '...',
+
+          // other attributes here ...
+        },
+        relationships: {
+          author: {
+            data: {
+              id: '...',
+              type: 'user'
+            }
+          },
+          images: {
+            data: [
+              {
+                id: '...',
+                type: 'image'
+              }
+
+              // other listing images here ...
+            ]
+          }
+        }
+      }
+    ],
+    meta: {
+      totalItems: 210,
+      totalPages: 210,
+      page: 1,
+      perPage: 1
+    },
+    included: [
+      {
+        id: '...',
+        type: 'image',
+        attributes: { ... }
+      },
+      {
+        id: '...' ,
+        type: 'user',
+        attributes: { ... }
+      }
+
+      // other included resources here ...
+    ]
+  }
+}
+```
+
+### Error response
+
+An error response will have the following format:
+
+```
+{
+  status: <HTTP Status code, 4xx or 5xx>,
+  statusText: <HTTP Status text>,
+  data: // The data returned by the API, for example:
+  {
+    errors: [
+      {
+        status: <HTTP Status code, 4xx or 5xx>,
+        code: // error code
+        title: <HTTP Status text>,
+        details: {
+          // Additional details, not part of the public API.
+        }
+      }
+    ]
+  }
+}
+```
+
+The error value is always an `instanceof` [Error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error).
+
+**Please note** that the content of the `details` is not part of the public API. This means that:
+
+- You can use `details` for debugging and error tracking.
+- You SHOULD NOT write production code that depends on the content of `details`.
+- The content of `details` is not well specified and will change in the future.
+
+## API documentation
+
+Please see the [API documentation](https://flex-api-docs-preview.sharetribe.com/), for more information about the available endpoints, parameters and the response format.

package/docs/configurations.md

@@ -0,0 +1,95 @@
+# Configurations
+
+There are a few configuration options that can given to the
+`createInstance` method:
+
+``` js
+const sharetribeSdk = require('sharetribe-flex-sdk');
+
+var sdk = sharetribeSdk.createInstance({
+
+  // An API application client ID (mandatory)
+  clientId: "08ec69f6-d37e-414d-83eb-324e94afddf0",
+
+  // An API application client secret. Only to be used in a server
+  // environment and not to be exposed to a client/browser.
+  clientSecret: "8af2bf99c380b3a303ab90ae4012c8cd8f69d309",
+
+  // Token store
+  //
+  // Token store instance to use. Token store is where the SDK
+  // saves the session information.
+  //
+  // Built-in token stores:
+  //
+  // - sharetribeSdk.tokenStore.browserCookieStore
+  // - sharetribeSdk.tokenStore.expressCookieStore
+  // - sharetribeSdk.tokenStore.memoryStore
+  //
+  // Default: sharetribeSdk.tokenStore.browserCookieStore()
+  //
+  tokenStore: sharetribeSdk.tokenStore.browserCookieStore(),
+
+  // List of custom type handlers
+  typeHandlers: [
+    {
+      sdkType: UUID,
+      // "type" was renamed to "sdkType" on v1.4.0
+      appType: MyUuidType,
+      // "customType" was renamed to "appType" on v1.4.0
+
+      // Writer fn type signature must be:
+      // appType -> sdkType
+      //
+      // E.g.
+      // MyUuidType -> UUID
+      writer: v => new UUID(v.myUuid),
+
+      // Reader fn type signature must be:
+      // sdkType -> appType
+      //
+      // E.g.
+      // UUID -> MyUuidType
+      reader: v => new MyUuidType(v.uuid),
+    }
+  ],
+
+  // Node.js only.
+  // HTTP and HTTPS agents to be used when performing
+  // http and https request. This allows defining non-default
+  // options for agent, such as `{ keepAlive: true }`.
+  //
+  httpAgent: httpAgent,
+  httpsAgent: httpsAgent,
+
+  // If true and default browser token store is used,
+  // the cookie is never transferred without HTTPS connection.
+  // Default: false
+  secure: false,
+
+  // SDK uses Transit format to communicate with the API.
+  // If this configuration is `true` a verbose Transit mode is enabled.
+  // Useful for development.
+  // Default: false
+  transitVerbose: false,
+
+  // The API base URL (optional)
+  // Defaults to Sharetribe production (https://flex-api.sharetribe.com)
+  // Change this if you want to point the SDK to somewhere else (like localhost).
+  // Useful mainly for Sharetribe's internal development
+  baseUrl: "https://the-api-base-url.example.sharetribe.com/",
+
+  // Allow use of Client Secret in browser (optional, defaults to false)
+  //
+  // Privileged Marketplace API calls that use Client Secret are meant to be done
+  // from a secure context, e.g. from a private Node.js server. Using Client Secret
+  // in an open website exposes the it to the public.
+  //
+  // By default, the SDK will display a warning if Client Secret is used in browser
+  // but if you know what you are doing, and you have secured the website properly so
+  // that Client Secret is not leaked, you can suppress the warning by setting this
+  // to `true`.
+  dangerouslyAllowClientSecretInBrowser: false
+
+});
+```

package/docs/developing-sdk.md

@@ -0,0 +1,131 @@
+# Developing SDK
+
+Here are the commands you need when developing the SDK:
+
+#### Install dependencies:
+
+```sh
+$ yarn install
+```
+
+#### Build the package:
+
+```sh
+$ yarn run build
+```
+
+#### Run tests:
+
+```sh
+$ yarn test
+```
+
+#### Run linter:
+
+```sh
+$ yarn run lint
+```
+
+#### Format code (run Prettier):
+
+```sh
+$ yarn run format
+```
+
+#### Move the built files to `/docs` folder
+
+Docpress only looks for files in the project root and `/docs` folder.
+
+```sh
+$ cp build/sharetribe-flex-sdk-web.js docs/sharetribe-flex-sdk-web.js
+```
+
+#### Serve the docpress docs
+
+```sh
+$ yarn run serve-docs
+```
+
+#### Build the docpress docs
+
+```sh
+$ yarn run build-docs
+```
+
+#### Update the Github Pages
+
+```sh
+$ yarn run build
+$ cp build/sharetribe-flex-sdk-web.js docs/sharetribe-flex-sdk-web.js
+$ yarn run build-docs
+$ mv _docpress ../
+$ git checkout gh-pages
+$ cp -r ../_docpress/* ./
+$ rm -r ../_docpress
+$ // git add, commit, push
+```
+
+#### Release a new version to NPM
+
+1. Update version in `package.json`
+
+1. Update CHANGELOG.md
+   - Move everything in Unreleased to the corresponding version section
+
+1. Login as `sharetribe` with `npm login`
+   - check credentials from password manager
+
+1. Publish with `npm publish`
+
+1. Add a new tag
+
+    ```bash
+    git tag -a v1.2.3 -m v1.2.3
+    ```
+
+1.  Update `latest` tag
+
+    ```bash
+    git push origin :refs/tags/latest
+    git tag -f -a latest -m latest
+    ```
+
+1.  Push the tag
+
+    ```bash
+    git push --tags
+    ```
+
+1.  Go to [Github releases and draft a new release](https://github.com/sharetribe/flex-sdk-js/releases/new)
+
+    Use the following content:
+
+    **Tag version:** \<the newly created tag\>
+
+    **Release title:** \<version number\>
+
+    **Describe this release:**
+
+    ```markdown
+    <copy the content from the [CHANGELOG.md](CHANGELOG.md)>
+    ```
+
+    Here's a full example:
+
+    **Tag version:** v1.2.3
+
+    **Release title:** v1.2.3
+
+    **Describe this release:**
+
+    ```markdown
+    ### Added
+
+    - Added many things
+
+    ### Changed
+
+    - Changed this and that
+    ```
+
+1.  Announce the new version in Slack

package/docs/docpress.json

@@ -0,0 +1,14 @@
+{
+  "github": "sharetribe/flex-sdk-js",
+  "scripts": [
+    "scripts.js",
+    "sharetribe-flex-sdk-web.js"
+  ],
+  "css": [
+    "styles.css"
+  ],
+  "googleAnalytics": {
+    "id": "UA-10178914-13",
+    "domain": "sharetribe.github.io"
+  }
+}

package/docs/features.md

@@ -0,0 +1,14 @@
+# Features
+
+The SDK handles **groundwork** such as authentication, renewing
+authentication tokens and serializing and deserializing data to and
+from JavaScript data structures, so that you don't need to worry about
+it.
+
+The main SDK features are:
+
+- [Promise-based](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) asynchronous API.
+- Universal: Runs in any JavaScript environment, including [Node.js](https://nodejs.org/), browser and [React Native](https://facebook.github.io/react-native/) (experimental).
+- Predictable mapping from SDK methods to API endpoints.
+- [Types](./types.md) to represent UUID, money, geolocation, etc. with automatic serialization and deserialization.
+- [Easy authentication](./authentication.md).