Update README.md and add CONTRIBUTING.md (thanks Spatie for the templ…

…ate) (#32)

CONTRIBUTING.md

@@ -0,0 +1,55 @@
+# Contributing
+
+Contributions are **welcome** and will be fully **credited**.
+
+Please read and understand the contribution guide before creating an issue or pull request.
+
+## Etiquette
+
+This project is open source, and as such, the maintainers give their free time to build and maintain the source code
+held within. They make the code freely available in the hope that it will be of use to other developers. It would be
+extremely unfair for them to suffer abuse or anger for their hard work.
+
+Please be considerate towards maintainers when raising issues or presenting pull requests. Let's show the
+world that developers are civilized and selfless people.
+
+It's the duty of the maintainer to ensure that all submissions to the project are of sufficient
+quality to benefit the project. Many developers have different skillsets, strengths, and weaknesses. Respect the maintainer's decision, and do not be upset or abusive if your submission is not used.
+
+## Viability
+
+When requesting or submitting new features, first consider whether it might be useful to others. Open
+source projects are used by many developers, who may have entirely different needs to your own. Think about
+whether or not your feature is likely to be used by other users of the project.
+
+## Procedure
+
+Before filing an issue:
+
+- Attempt to replicate the problem, to ensure that it wasn't a coincidental incident.
+- Check to make sure your feature suggestion isn't already present within the project.
+- Check the pull requests tab to ensure that the bug doesn't have a fix in progress.
+- Check the pull requests tab to ensure that the feature isn't already in progress.
+
+Before submitting a pull request:
+
+- Check the codebase to ensure that your feature doesn't already exist.
+- Check the pull requests to ensure that another person hasn't already submitted the feature or fix.
+
+## Requirements
+
+If the project maintainer has any additional requirements, you will find them listed here.
+
+- **[Laravel Pint Coding Standard](https://laravel.com/docs/master/pint)** - most fixes are applied automatically by running `php ./vendor/bin/pint`.
+
+- **Add tests!** - Your patch won't be accepted if it doesn't have tests.
+
+- **Document any change in behaviour** - Make sure the `README.md` and any other relevant documentation are kept up-to-date.
+
+- **Consider our release cycle** - We try to follow [SemVer v2.0.0](http://semver.org/). Randomly breaking public APIs is not an option.
+
+- **One pull request per feature** - If you want to do more than one thing, send multiple pull requests.
+
+- **Send coherent history** - Make sure each individual commit in your pull request is meaningful. If you had to make multiple intermediate commits while developing, please [squash them](http://www.git-scm.com/book/en/v2/Git-Tools-Rewriting-History#Changing-Multiple-Commit-Messages) before submitting.
+
+**Happy coding**!

README.md

@@ -5,15 +5,10 @@
 [![GitHub Code Style Action Status](https://img.shields.io/github/actions/workflow/status/rapkis/laravel-controld/fix-php-code-style-issues.yml?branch=main&label=code%20style&style=flat-square)](https://github.com/rapkis/laravel-controld/actions?query=workflow%3A"Fix+PHP+code+style+issues"+branch%3Amain)
 [![Total Downloads](https://img.shields.io/packagist/dt/rapkis/laravel-controld.svg?style=flat-square)](https://packagist.org/packages/rapkis/laravel-controld)
 
-This is where your description should go. Limit it to a paragraph or two. Consider adding a small example.
+Access the ControlD API in your Laravel application.
 
-## Support us
-
-[<img src="https://github-ads.s3.eu-central-1.amazonaws.com/laravel-controld.jpg?t=1" width="419px" />](https://spatie.be/github-ad-click/laravel-controld)
-
-We invest a lot of resources into creating [best in class open source packages](https://spatie.be/open-source). You can support us by [buying one of our paid products](https://spatie.be/open-source/support-us).
-
-We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on [our contact page](https://spatie.be/about-us). We publish all received postcards on [our virtual postcard wall](https://spatie.be/open-source/postcards).
+This is **not** an official package and is purely a third-party API client.
+Any service-related issues should be directed towards the service provider itself.
 
 ## Installation
 
@@ -23,14 +18,7 @@ You can install the package via composer:
 composer require rapkis/laravel-controld
 ```
 
-You can publish and run the migrations with:
-
-```bash
-php artisan vendor:publish --tag="laravel-controld-migrations"
-php artisan migrate
-```
-
-You can publish the config file with:
+You should publish the config file with:
 
 ```bash
 php artisan vendor:publish --tag="laravel-controld-config"
@@ -40,22 +28,83 @@ This is the contents of the published config file:
 
 ```php
 return [
+    'url' => env('CONTROL_D_API_URL'),
+    'secret' => env('CONTROL_D_API_SECRET'),
+    'middleware' => [
+        'request' => [],
+        'response' => [ControlDErrorHandlerMiddleware::class],
+    ],
 ];
 ```
+Make sure to define the ControlD endpoint and your API token in the .env file.
+You can also set up middleware classes that will be applied to your HTTP requests and responses (see [Middleware](#middleware)).
 
-Optionally, you can publish the views using
+## Usage
 
-```bash
-php artisan vendor:publish --tag="laravel-controld-views"
+To access the ControlD API you first need to have an account created. Visit [controld.com](https://controld.com/).
+Make sure you're familiar with their 
+[documentation](https://docs.controld.com/) and [API reference](https://docs.controld.com/reference).
+The package assumes you understand with how the service and the API work.
+
+## Quick Start
+
+The main class you'll be working with is `\Rapkis\Controld\ControlD`.
+You can access all ControlD endpoints by using its methods. 
+Endpoints are organized according to the documentation for ease of use.
+
+Start by instantiating it:
+```php
+$controlD = app(\Rapkis\Controld\ControlD::class); // or use DI
 ```
 
-## Usage
+`\Rapkis\Controld\ControlD` depends on Laravel's HTTP client, 
+which is configured automatically via `\Rapkis\Controld\ControlDFactory`.
+To make things simple, it is recommended to resolve it via 
+Laravel's [Service Container](https://laravel.com/docs/10.x/container) (a.k.a. `app()`, Dependency Injection, etc.) 
+to instantiate the `\Rapkis\Controld\ControlD` class. 
+It's already pre-configured in `\Rapkis\Controld\ControldServiceProvider`.
+
+Now, you can make API requests
 
 ```php
-$controld = new Rapkis\Controld();
-echo $controld->echoPhrase('Hello, Rapkis!');
+// Lists all profiles of your account: https://docs.controld.com/reference/get_profiles
+$controlD->profiles()->list();
+
+// Create a new profile: https://docs.controld.com/reference/post_profiles
+$profile = $controlD->profiles()->create('My Profile Name'); // returns \Rapkis\Controld\Responses\Profile
+
+// Create a new device that uses your new profile: https://docs.controld.com/reference/post_devices
+$device = $controlD->devices()->create(
+    'Device Name', // the name of your device
+    $profile->pk, // the profile it will use
+    'router', // the icon (type) of your device. Purely visual.
+); // returns \Rapkis\Controld\Responses\Device
 ```
 
+## General structure
+
+In a nutshell, the package is made up of "Resources" and "Responses".
+Resource classes are used to make HTTP requests and then JSON responses are mapped to Response classes. 
+These classes are basic DTOs (data transfer objects) which are easier to work with than basic arrays: 
+you don't have to guess array keys and can immediately understand the response structure.
+
+Each method in the `\Rapkis\Controld\ControlD` class corresponds to the appropriate Resource class (`\Rapkis\Controld\Resources`).
+Resource classes make the requests and map the responses to the response classes. Usually with the help of factory classes.
+
+## Middleware
+
+Just like with the Laravel's HTTP client (or Guzzle), you can add middlware to interact with your requests and responses.
+You can check how they work in the [Laravel documentation](https://laravel.com/docs/10.x/http-client#guzzle-middleware)
+
+For example, this package handles ControlD specific errors with `\Rapkis\Controld\Middleware\ControlDErrorHandlerMiddleware`.
+Instead of parsing the JSON response somewhere in your code, 
+you can parse it in the middleware class and handle your errors **before** returning a response.
+
+Feel free to modify the middleware or add your own! For example, you can have middleware which 
+renders error-specific exceptions instead of the generic one.
+Alternatively, if you're running [an organization](https://docs.controld.com/docs/organizations), 
+you can add the impersonation header (`X-Force-Org-Id: org_id_goes_here`) directly via middleware.
+
 ## Testing
 
 ```bash
@@ -70,14 +119,9 @@ Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed re
 
 Please see [CONTRIBUTING](CONTRIBUTING.md) for details.
 
-## Security Vulnerabilities
-
-Please review [our security policy](../../security/policy) on how to report security vulnerabilities.
-
 ## Credits
 
 - [Rapolas Gruzdys](https://github.com/rapkis)
-- [All Contributors](../../contributors)
 
 ## License