@mapcreator/api 3.3.1 → 5.0.0-alpha.13

package/manual/examples.authentication.md

@@ -1,205 +0,0 @@
-# Authentication
-Authentication is done through [OAuth]. This library provides multiple [OAuth flow]
-implementations for authentication. A client id can be obtained through a support
-ticket but this is planned to change in the near future. The client will first
-check if any tokens can be found in the cache before requiring authentication.
-If one can be found the `api.authenticate()` method will instantly resolve without
-any side-effects. The variable `api.authenticated` will be set to true if a token
-has been found and is still valid.
-
-Tokens are stored in HTTPS cookies if possible and using `localStorage` when the
-browser is not using a HTTPS connection. [Nodejs] uses a file named `.m4n_token` to store the token.
-
-## Web
-Multiple flows are supported for web browsers. All the web examples assume the web
-build of the library has been included in the target page.
-
-### Implicit Flow
-A client id is required to use the implicit flow. The redirect url *must* be the
-same as the one linked to the client id. The callback url is automatically
-guessed if none is provided.
-
-```js
-// Obtained client id
-var clientId = 1;
-
-// Callback url is set to the current url by default
-var auth = new ImplicitFlow(clientId);
-var api = new Mapcreator(auth);
-
-// This will hijack the page if no authentication cache can
-// be found. Smartest thing to do is to just let it happen
-// and initialize any other code afterwards.
-api.authenticate().then(function() {
-  // Save the token
-  api.saveToken();
-
-  // Get the current user and dump the result to the console.
-  api.users.get('me').then(console.dir);
-});
-```
-
-### Implicit flow pop-up
-Just like the Implicit Flow a client id is required.
-
-```js
-// Obtained client id
-var clientId = 1;
-
-// Callback url is set to the current url by default. The
-// script is smart enough close the page if it detects that
-// it's a child after authentication. This means that either
-// the current page can be set as the callback (default) or
-// a custom page that just contains `api.authenticate()`
-// that uses ImplicitFlowPopup as the auth parameter.
-var auth = new ImplicitFlowPopup(clientId);
-var api = new Mapcreator(auth);
-
-// This will create a pop-up window containing the log in
-// page. Once the pop-up redirects back to the callback it
-// will resolve the promise. The callback page should contain
-api.authenticate().then(function() {
-  // Save the token
-  api.saveToken();
-
-  // Get the current user and dump the result to the console.
-  api.users.get('me').then(console.dir);
-});
-```
-
-### Implicit flow pop-up (advanced)
-Due to the nature of the implicit flow pop-up (referred to as IFP from now on)
-method the callback page can be set to a blank page that just grabs the token
-and then closes. This can be done in the following way.
-
-**index.html:**
-
-```js
-var clientId = 1;
-var callbackUrl = 'https://example.com/callback.html';
-
-var auth = new ImplicitFlowPopup(clientId);
-var api = new Mapcreator(auth);
-
-// This will resolve once the callback page has been loaded
-api.authenticate().then(function() {
-  // Save the token
-  api.saveToken();
-
-  // Get the current user and dump the result to the console.
-  api.users.get('me').then(console.dir);
-});
-```
-
-**callback.html:**
-
-```js
-var clientId = 1;
-
-// This will instantly detect the token and close the page
-new ImplicitFlowPopup(clientId);
-```
-
-### Password flow (dangerous)
-The password flow is **NOT** intended to be used in the browser. If you do
-decide to use the password flow then it is recommended to make sure that
-the site is **NOT** public facing and using HTTPS. Leaking the [secret] is
-a very bad idea.
-
-```js
-var clientId = 1; // client id
-var secret = ''; // secret
-var username = 'user@example.com'; // email is used for authentication
-var password = 'Password1!'; // password
-
-// Secret will be leaked if this is used on a webpage. Please only use
-// this for non-web applications.
-var auth = new PasswordFlow(clientId, secret, username, password);
-var api = new Mapcreator(auth);
-
-// This will resolve once the authentication has completed
-api.authenticate().then(function() {
-  // Get the current user and dump the result to the console.
-  api.users.get('me').then(console.dir);
-});
-```
-
-### Dummy flow
-The dummy flow can be used when a token *should* be present in the cache.
-
-```js
-var auth = new DummyFlow();
-var api = new Mapcreator(auth);
-
-// Manually check if we're logged in
-if (api.authenticated) {
-    console.log('Found authentication token in cache!');
-}
-
-api.authenticate().then(function() {
-    // Will only resolve if a token was found
-    console.log("We're authenticated");
-}).catch(function(err) {
-    // This will be called if `api.authenticated` is false
-    console.log(err.toString());
-});
-```
-
-## Nodejs
-The library currently only supports the password flow and the dummy flow
-for [nodejs]. Other flows might be added in the future.
-
-### Password Flow
-Make sure to store your [secret] somewhere safe and to only store the token
-and **never** the unencrypted user password.
-
-```js
-var clientId = 1; // client id
-var secret = ''; // secret
-var username = 'user@example.com'; // email is used for authentication
-var password = 'Password1!'; // password
-
-var auth = new PasswordFlow(clientId, secret, username, password);
-var api = new Mapcreator(auth);
-
-// This will resolve once the authentication has completed
-api.authenticate().then(function() {
-  // Get the current user and dump the result to the console.
-  api.users.get('me').then(console.dir);
-});
-```
-
-### Dummy flow
-The dummy flow can also be used when a token is known.
-
-```js
-var auth = new DummyFlow();
-var api = new Mapcreator(auth);
-
-var token = {
-  token: "eyJ0eXAiOiJKV1...",
-  type: "Bearer",
-  expires: "Thu, 18 May 2017 14:14:38 GMT"
-};
-
-// Set the token
-api.auth.token = OAuthToken.fromResponseObject(token);
-
-// Manually check if we're logged in
-if (api.authenticated) {
-    console.log('Found authentication token in cache!');
-}
-
-api.authenticate().then(function() {
-    // Will only resolve if a token was found
-    console.log("We're authenticated");
-}).catch(function(err) {
-    // This will be called if `api.authenticated` is false
-    console.log(err.toString());
-});
-```
-
-[OAuth flow]: https://aaronparecki.com/oauth-2-simplified/#authorization
-[OAuth]: https://oauth.org
-[nodejs]: https://nodejs.org
-[secret]: https://www.youtube.com/watch?v=zwZISypgA9M

package/manual/examples.md

@@ -1,153 +0,0 @@
-# Basics
-These examples assume that an instance of the api exists and is authenticated.
-See the node and web authentication examples for more information on authenticating.
-
-### Getting a resource
-Resources are bound to the base api class by default. Resources can be fetched in
-two ways; by selecting them (`.select`) or by fetching them (`.get`). Selecting them will only set the
-object's id to it's properties. Fetching a resource
-
-Fetch resource and all it's properties:
-
-```js
-api.colors.get(1).then(function(color) {
-    console.log(color.id + " " + color.name + ": " + color.hex);
-})
-```
-
-Select the current user to quickly obtain related mapstyle sets:
-
-```js
-api.users.select('me').mapstyleSets().then(function(sets) {
-    for(var i = 0; i < sets.data.length; i++) {
-        console.log(sets.data[i].name);
-    }
-});
-```
-
-Selection is only usefull as a stepping stone to related resources that can be easily obtained
-using the id of the parent. Please refer to the [api documentation] for further reference.
-
-### Create a new resource
-Create a new color and dump the new resource to the console after saving
-
-```js
-var data = {name: 'Smurf', hex: '88CCFF'};
-api.colors.new(data).save().then(console.dir);
-```
-
-### Modify a resource
-Change profession of the current user and save it.
-
-```js
-api.users.get('me').then(me => {
-  me.profession = 'Developer';
-  me.save(); // Optional chaining to get the updated resource
-});
-```
-
-### Clone a resource
-Setting the id to null forces the creation of a new object upon saving.
-
-```js
-api.colors.get(1).then(color => {
-  color.id = null;
-  color.save();
-});
-```
-
-### Pagination
-Listing resources with pagination. First page with 5 items per page
-
-```js
-api.colors.list(1, 5).then(page => {
-  console.log('Got resources:');
-
-  for (var i = 0; i < page.data.length; i++) {
-    console.log(page.data[i].toString());
-  }
-});
-```
-
-Loop over every page and print the result to the console.
-
-```js
-function parsePages(page) {
-  for (var i = 0; i < page.data.length; i++) {
-    console.log(page.data[i].toString());
-  }
-
-  if (page.hasNext) {
-    console.log('Grabbing page ' + (page.page + 1));
-    page.next().then(parsePage);
-  }
-}
-
-api.colors
-   .list(1, 50)
-   .then(parsePages);
-```
-
-Loop over all pages and return the data in a promise
-
-```js
-function parsePages(page) {
-  var data = [];
-
-  function parse(page) {
-      data = data.concat(page.data);
-
-      if(page.hasNext) {
-          return page.next().then(parse);
-      } else {
-          return data;
-      }
-  }
-
-  return parse(page);
-}
-
-api.colors
-   .list(1, 50)
-   .then(parsePages)
-   .then(d => console.log('Total rows: ' + d.length));
-```
-
-
-Select current user but do not fetch any info to make fetching resources easier.
-
-```js
-api.users.select('me').colors.list().then(page => {
-  console.dir(page.data);
-});
-```
-
-### Searching
-Resource lists can be queried to search for specific records as follows:
-
-```js
-var query = {
-  name: '^:test',
-  scale_min: ['>:1', '<:10'],
-}
-api.layers.search(query).then(console.dir);
-```
-
-The `search` method is an extension of `list`. This means that `.search({})` is the same as
-`list()`. More information about search query formatting can be found in the [api documentation].
-
-### Canceling a requests
-Most methods that return a promise will have a method called `cancel`. This method can be called
-to cancel the request. If the request is running or about to be ran the promise will throw an error
-once canceled. If the request has been completed before the promise has been canceled it will not
-throw an error and instead complete successfully.
-
-```js
-// Fetch a preview
-const promise = api.jobs.select(123456).downloadPreview();
-
-// Turns out we don't need it anyways
-promise.cancel();
-```
-
-[api documentation]: https://docs.mapcreator.io/

package/manual/installation.md

@@ -1,33 +0,0 @@
-# Installation
-Installation can be done through either [npm] or [yarn].
-
-```sh
-// Using npm
-npm install --save @mapcreator/api
-
-// Using yarn
-yarn add @mapcreator/api
-```
-
-After installation the package can be imported as follows:
-
-```js
-var m4n = require('@mapcreator/api');
-
-// Do stuff
-var auth = new m4n.ImplicitFlow(1);
-var api = new m4n.Mapcreator(auth);
-```
-
-or using ES6 import statements:
-
-```js
-import {Mapcreator, DummyFlow} from '@mapcreator/api';
-
-// Do stuff
-var auth = new DummyFlow();
-var api = new Mapcreator(auth);
-```
-
-[npm]: https://npmjs.com
-[yarn]: https://yarnpkg.com

package/manual/js/sandbox.js

@@ -1,26 +0,0 @@
-(function() {
-  if (window.name) {
-    new window.mapcrator.ImplicitFlowPopup(1);
-  }
-})();
-
-
-function easyAuth() {
-  var mc = window.mapcreator;
-
-  var clientId = 3;
-  var docsUrl = 'https://docs.mapcreator.io/wrapper/';
-  var auth = new mc.ImplicitFlowPopup(clientId, docsUrl);
-  var api = new mc.Mapcreator(auth);
-
-  api.host = 'https://api.beta.mapcreator.io/';
-
-  return api.authenticate();
-}
-
-console.log('You can play around with the api in here, the library is bound to window.mapcreator. Authentication ');
-console.log('can easily be done by running the command easyAuth(). See the docs for more information here: ');
-console.log('https://docs.mapcreator.io/wrapper/manual/examples.authentication.html');
-console.log('Example: easyAuth().then(api => window.api = api);');
-console.log('window.mapcreator =', window.mapcreator);
-

package/src/ImageHandler.js

@@ -1,134 +0,0 @@
-/*
- * BSD 3-Clause License
- *
- * Copyright (c) 2020, Mapcreator
- * All rights reserved.
- *
- * Redistribution and use in source and binary forms, with or without
- * modification, are permitted provided that the following conditions are met:
- *
- *  Redistributions of source code must retain the above copyright notice, this
- *   list of conditions and the following disclaimer.
- *
- *  Redistributions in binary form must reproduce the above copyright notice,
- *   this list of conditions and the following disclaimer in the documentation
- *   and/or other materials provided with the distribution.
- *
- *  Neither the name of the copyright holder nor the names of its
- *   contributors may be used to endorse or promote products derived from
- *   this software without specific prior written permission.
- *
- * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
- * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
- * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
- * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
- * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
- * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
- * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
- * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
- * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
- * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
- */
-
-import Mapcreator from './Mapcreator';
-import DownloadedResource from './resources/base/DownloadedResource';
-import ResourceBase from './resources/base/ResourceBase';
-import { isParentOf } from './utils/reflection';
-import { FormData } from './utils/requests';
-import { makeCancelable } from './utils/helpers';
-
-/**
- * Image resource handler
- * @protected
- */
-export default class ImageHandler {
-  /**
-   * @param {Mapcreator} api - Api instance
-   * @param {ResourceBase} target - Instance of target item
-   */
-  constructor (api, target) {
-    if (!isParentOf(Mapcreator, api)) {
-      throw new TypeError('Expected api to be of type Mapcreator');
-    }
-
-    if (!isParentOf(ResourceBase, target)) {
-      throw new TypeError('Expected target to be of type ResourceBase');
-    }
-
-    this._api = api;
-    this._target = target;
-  }
-
-  /**
-   * Get api instance
-   * @returns {Mapcreator} - Api instance
-   */
-  get api () {
-    return this._api;
-  }
-
-  /**
-   * Resource url, can be used in an image tag
-   * @returns {string} - Resource url
-   */
-  get url () {
-    return `${this._target.url}/image`;
-  }
-
-  /**
-   * Delete image
-   * @throws {ApiError} - If the api returns errors
-   * @returns {CancelablePromise}
-   */
-  delete () {
-    // use the makeCancelable helper so we don't return the response object
-    return makeCancelable(async signal => {
-      await this.api.ky.delete(this.url, { signal });
-    });
-  }
-
-  /**
-   * Download the image
-   * @returns {CancelablePromise<DownloadedResource>} - image
-   * @throws {ApiError} - If the api returns errors
-   * @example
-   * // Browser
-   * layer.imageHandler.download().then(image => {
-   *   $('img').src = image.createObjectURL();
-   * });
-   *
-   * // NodeJs
-   * layer.imageHandler.download().then({fileName, data} => {
-   *   fs.writeFileSync(fileName, data);
-   * });
-   */
-  download () {
-    return makeCancelable(async signal => {
-      const response = await this.api.ky.get(this.url, { signal });
-
-      return DownloadedResource.fromResponse(response);
-    });
-  }
-
-  /**
-   * Upload new image
-   * @param {ArrayBuffer|ArrayBufferView|File|Blob|Buffer} image - Image file
-   * @returns {CancelablePromise}
-   * @throws {ApiError} - If the api returns errors
-   */
-  upload (image) {
-    const body = new FormData();
-
-    body.append('image', image, 'image');
-
-    const headers = {};
-
-    if (body.getHeaders) {
-      Object.assign(headers, body.getHeaders());
-    }
-
-    return makeCancelable(async signal => {
-      await this.api.ky.post(this.url, { headers, body, signal });
-    });
-  }
-}