Update: Documentation and Package Json (#5380)

martinmckenna · web-flow · commit 747b7193c34f · 2019-08-27T12:18:20.000-04:00
* updates docs and package json

* adds usage docs for SDK

* updates contributing docs

* updates contributing docs

* updates contributing docs

* updates contributing docs

* updates licence

* fixes typo
diff --git a/CLOUD.md b/CLOUD.md
@@ -4,7 +4,7 @@
 
 Please refer to the [`.env.example` file](./packages/manager/.env.example) in this directory. This will get you started in creating your own `.env` file so you can run the Manager.
 
-Your `.env` file should be located in the `packages/manager` directory before your local development server is started.
+:rotating_light: Your `.env` file should be located in the `packages/manager` directory before your local development server is started.
 
 Here are a list of all the required and optional environment variables the Manager uses:
 
@@ -58,7 +58,7 @@ These are environment variables that can be used for automated testing processes
 
 Once you have a working `.env` file, you can run the following in the root of the project:
 
-`yarn && npx lerna bootstrap --scope linode-manager && npx lerna run start --stream --scope linode-manager`
+`yarn up` or `yarn up:manager`
 
 alternatively, with Docker
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -17,7 +17,7 @@ The following buzzwords are involved in this project, so please familiarize your
 In order to contribute to Linode UI, we recommend the following minimum version numbers:
 
 1. Git v2.19.1
-2. Node v8.11.2
+2. Node v10.16.0
 3. Yarn 1.16.0
 
 You must also have [Lerna](https://lerna.js.org/) installed globally, so please run the following to install the package to your local machine:
diff --git a/GETTING_STARTED.md b/GETTING_STARTED.md
@@ -18,8 +18,7 @@ To start all projects:
 While in the root...
 1. Run `yarn` to install all root dependencies.
 2. Run `npx lerna bootstrap` to install all package dependencies.
-3. Run `npx lerna run start` to start a development server for all projects
-   * additionally, you can add a `--stream` flag to this command to see the output of the development server.
+3. Run `npx lerna run start --parallel` to start a development server for all projects
 
 Alternatively, you can run `yarn up` which runs all previous commands.
 
@@ -29,9 +28,8 @@ Starting a single project is similar to the previous instructions with the excep
 
 1. Run `yarn` to install all root dependencies.
 2. Run `npx lerna bootstrap` to install all package dependencies.
-3. Run `npx lerna run start --scope linode-manager` to start a development server for all projects
-   * additionally, you can add a `--stream` flag to this command to see the output of the development server.
-   * `linode-manager` is the name located in `packages/manager/package.json`
+3. Run `npx lerna run start --scope linode-js-sdk` to start a development server for the JavaScript SDK
+   * `linode-js-sdk` is the name located in `packages/linode-js-sdk/package.json`
 
 ## Helper Scripts
 
diff --git a/LICENSE b/LICENSE
@@ -1,39 +1,13 @@
-The following license only applies to source code, defined as any text file
-in this repository, not including vector graphics:
+Copyright 2019 Linode LLC.
 
-    Copyright (c) 2016, Linode, LLC
-    All rights reserved.
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
 
-    Redistribution and use in source and binary forms, with or without
-    modification, are permitted provided that the following conditions are met:
+    http://www.apache.org/licenses/LICENSE-2.0
 
-    1. Redistributions of source code must retain the above copyright notice, this
-    list of conditions and the following disclaimer.
-
-    2. 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.
-
-    3. 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.
-
-Other assets (files containing raster and vector graphics) are the proprietary
-property of Linode, LLC, and may not be used outside of the context of this
-project for any purpose without prior written approval from Linode, LLC.
-
-Some files or assets in this repository are not the intellectual property of
-Linode and are included under the terms of the licenses of the owners of that
-content. In such cases, such content is accompanied by a LICENSE file in the
-same directory explaining the license terms of that content.
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
diff --git a/README.md b/README.md
@@ -20,7 +20,13 @@ To get started running Linode UI projects locally, please [see the _Getting Star
 
 If you already have your development environment set up, please read the [contributing guidelines](CONTRIBUTING.md) to get help in making your first PR.
 
-Additionally, you can read our [code conventions](./CODE_CONVENTIONS.md) and [Cloud Manager testing conventions](./TESTING.md) docs for instructions on how write code inline with what we expect.
+### I want to contribute to Cloud Manager :heart_eyes:
+
+Along with the contributing guidelines, you can read our [code conventions](./CODE_CONVENTIONS.md) and [Cloud Manager testing conventions](./TESTING.md) docs for instructions on how write code inline with what we expect.
+
+### I want to contribute to the JavaScript SDK :sunglasses:
+
+Amazing! Please check out the documentation in the [SDK directory](./packages/linode-js-sdk/README.md)
 
 ## Reaching Out
 
@@ -34,7 +40,5 @@ action upon feedback.
 
 ## License
 
-All code located in this repository is distributed under the terms of the [BSD 3-clause
-license](LICENSE). The assets are
-not licensed for any purpose without prior written approval from Linode, unless
-otherwise noted.
+All code located in this repository is distributed under the terms of the [APLv2
+license](LICENSE).
diff --git a/packages/linode-js-sdk/README.md b/packages/linode-js-sdk/README.md
@@ -0,0 +1,107 @@
+# Linode JavaScript SDK
+
+This directory contains all the code for the client-side wrapper around Linode's APIv4, written in JavaScript
+
+## Installation
+
+To install the project to your app, run
+
+```
+$ npm install linode-js-sdk
+```
+
+or with yarn
+
+```
+$ yarn add linode-js-sdk
+```
+
+or with a CDN
+
+```js
+<script src="https://unpkg.com/linode-js-sdk/index.js"></script>
+```
+
+## Using the SDK
+
+The first step in using the SDK is to authenticate your requests, either with an OAuth Token or Personal Access Token (PAT). Please [see the Linode API docs](https://developers-linode.netlify.com/api/v4/#access-and-authentication) in order to either get an OAuth Token or PAT so that you can authenticate your requests.
+
+Once you have your token, authenticating involves adding headers to each request. This library is built on top of [the Axios HTTP Client](https://github.com/axios/axios), so most features that are built into Axios are fair game here. Here's an example of how to authenticate all of your requests.
+
+```js
+/** request.js */
+
+import { baseRequest } from 'linode-js-sdk/lib/request'
+
+/** 
+ * intercepts every request with the following config
+ * see https://github.com/axios/axios#interceptors for more documentation.
+ */
+baseRequest.interceptors.request.use(config => {
+  const myToken = '1234'
+
+  return {
+    ...config,
+    headers: {
+      ...config.headers,
+      Authorization: `Bearer ${myToken}`
+    }
+  };
+});
+```
+
+```js
+/** index.js */
+
+import 'request.js'
+import { getAccount } from 'linode-js-sdk/lib/account'
+
+getAccount()
+  .then(response => {
+    document.getElementById('root').innerHTML = `<div>${response.data.email}</div>`
+  })
+  .catch(e => {
+    console.error(e)
+  })
+```
+
+## Contributing (To Be Revised for the Public)
+
+The main goal right now is to abstract out all interactions with the API from Cloud Manager and move them into this package. This library will act as a single source for both Cloud Manager and the general public.
+
+Migrating service functions over from Cloud Manager to the JavaScript SDK is relatively straightforward, and involves a few steps.
+
+1. Find a service function you want to move. All of these are located in `/packages/manager/src/services`. For example:
+
+```js
+/** packages/manager/src/services/account/account.ts */
+
+/**
+ * updateAccountInfo
+ *
+ * Update your contact or billing information.
+ *
+ */
+export const updateAccountInfo = (data: Partial<Linode.Account>) =>
+  Request<Linode.Account>(
+    setURL(`${API_ROOT}/account`),
+    setMethod('PUT'),
+    setData(data, updateAccountSchema)
+  ).then(response => response.data);
+```
+
+2. Since this is an account function, we need to move it to `packages/linode-js-sdk/src/account/account.ts`
+
+3. We also need to make sure that both the Yup Schema and the Type Interfaces are moved over as well.
+   * The type definition `Linode.Account` will need to be moved to `packages/linode-js-sdk/src/account/types.ts`
+   * The Yup Schema will need to move to `packages/linode-js-sdk/src/account/account.schema.ts`
+  
+4. The final step is removing all this code from Cloud Manager.
+   * Most of the interfaces for the Linode namespace are located in the `types` directory. In this case, `Linode.Account` is located at `packages/manager/src/types/Account.ts`.
+   * The schema should be located in the same directory as the service directory for the function you are moving.
+
+After these steps are completed, you'll want to start both the Cloud Manager and Linode JS SDK projects and make sure there are no type errors and that everything is compiling correctly.
+
+## TypeScript
+
+This library comes with TypeScript definitions so no need to write your own or find them elsewhere online. Just import the functions as normal and they should play nicely with TypeScript!
diff --git a/packages/linode-js-sdk/package.json b/packages/linode-js-sdk/package.json
@@ -1,6 +1,18 @@
 {
   "name": "linode-js-sdk",
   "version": "0.2.0",
+  "homepage": "https://github.com/linode/manager/tree/develop/packages/linode-js-sdk",
+  "bugs": {
+    "url": "https://github.com/linode/manager/issues",
+    "email": "feedback@linode.com"
+  },
+  "repository": {
+    "type": "git",
+    "directory": "https://github.com/linode/manager/tree/develop/packages/linode-js-sdk"
+  },
+  "engines": {
+    "node": ">= 10.16.0"
+  },
   "description": "JavaScript wrapper around the Linode APIv4",
   "author": "Linode",
   "license": "MIT",
@@ -27,7 +39,8 @@
     "index.js",
     "index.d.ts",
     "lib/*",
-    "package.json"
+    "package.json",
+    "README.md"
   ],
   "devDependencies": {
     "@babel/cli": "^7.5.5",
