From ada5bd8a5597bcca9278a9ed377a4e8512aa9967 Mon Sep 17 00:00:00 2001 From: Brennan Spellacy Date: Wed, 29 Jul 2020 10:35:56 -0700 Subject: [PATCH] update readme --- README.md | 211 +++++++++++++++++++++--------------------------------- 1 file changed, 83 insertions(+), 128 deletions(-) diff --git a/README.md b/README.md index 6881e91..7ca9b87 100644 --- a/README.md +++ b/README.md @@ -1,170 +1,125 @@ -# patch_api_v1 +# Patch Javascript SDK +![Test](https://github.com/patch-technology/patch-node/workflows/Test/badge.svg) +[![Discord](https://img.shields.io/discord/733029448558837792)](https://discord.gg/M23NnGR) -Patch - JavaScript client for patch_api_v1 -The core API used to integrate with Patch's service -This SDK is automatically generated by the [OpenAPI Generator](https://openapi-generator.tech) project: +The official Javascript package for the [Patch API](https://www.usepatch.com) -- API version: v1 -- Package version: v1 -- Build package: org.openapitools.codegen.languages.JavascriptClientCodegen +## Documentation +For a complete API reference, check out [Patch's API Reference.](https://docs.usepatch.com/docs/patch/openapi/v1/swagger.yaml) ## Installation -### For [Node.js](https://nodejs.org/) - -#### npm - -To publish the library as a [npm](https://www.npmjs.com/), please follow the procedure in ["Publishing npm packages"](https://docs.npmjs.com/getting-started/publishing-npm-packages). - -Then install it via: - +### NPM ```shell -npm install patch_api_v1 --save +npm install patch-node --save ``` -Finally, you need to build the module: - +### Yarn ```shell -npm run build +yarn add patch-node ``` -##### Local development +### Requirements +* Node 10 + -To use the library locally without publishing to a remote npm registry, first install the dependencies by changing into the directory containing `package.json` (and this README). Let's call this `JAVASCRIPT_CLIENT_DIR`. Then run: +## Usage -```shell -npm install -``` +### Configuration -Next, [link](https://docs.npmjs.com/cli/link) it globally in npm with the following, also from `JAVASCRIPT_CLIENT_DIR`: +After installing the package, you'll have to configure it with your API key which is available from the API key page in the Patch dashboard: +```javascript +// ES6+ +import Patch from 'patch-node' +const patch = Patch('key_test_1234') -```shell -npm link +// ES5 +var patch = require('patch-node')('key_test_1234') ``` -To use the link you just defined in your project, switch to the directory you want to use your patch_api_v1 from, and run: +### Orders +In Patch, orders represent a purchase of carbon offsets or negative emissions by mass. Place orders directly if you know the amount of carbon dioxide you would like to sequester. If you do not know how much to purchase, use an estimate. -```shell -npm link /path/to/ -``` +[API Reference](https://docs.usepatch.com/docs/patch/openapi/v1/swagger.yaml/paths/~1v1~1orders/get) -Finally, you need to build the module: +#### Examples +```javascript +// Create an order +const mass = 1000000 // Pass in the mass in grams (i.e. 1 metric tonne) +patch.orders.createOrder({ mass_g: mass }) -```shell -npm run build -``` +# Retrieve an order +orderId = 'ord_test_1234' // Pass in the order's id +patch.orders.retrieveOrder(orderId) -#### git +// Place an order +const orderId = 'ord_test_1234' // Pass in the order's id +patch.orders.placeOrder(orderId) -If the library is hosted at a git repository, e.g.https://github.com/GIT_USER_ID/GIT_REPO_ID -then install it via: +// Cancel an order +const orderId = 'ord_test_1234' // Pass in the order's id +patch.orders.cancelOrder(orderId) -```shell - npm install GIT_USER_ID/GIT_REPO_ID --save +// Retrieve a list of orders +const page = 1 // Pass in which page of orders you'd like +patch.orders.retrieveOrders({ page }) ``` -### For browser +### Estimates +Estimates allow API users to get a quote for the cost of compensating a certain amount of CO2. When creating an estimate, an order in the `draft` state will also be created, reserving the allocation of a project for 5 minutes. If you don't place your draft order within those 5 minutes, the order will automatically be cancelled. -The library also works in the browser environment via npm and [browserify](http://browserify.org/). After following -the above steps with Node.js and installing browserify with `npm install -g browserify`, -perform the following (assuming *main.js* is your entry file): +[API Reference](https://docs.usepatch.com/docs/patch/openapi/v1/swagger.yaml/paths/~1v1~1estimates/get) -```shell -browserify main.js > bundle.js -``` - -Then include *bundle.js* in the HTML pages. - -### Webpack Configuration +#### Examples +```javascript +// Create an estimate +const mass = 1000000 // Pass in the mass in grams (i.e. 1 metric tonne) +patch.estimates.createMassEstimate({ mass_g: mass }) -Using Webpack you may encounter the following error: "Module not found: Error: -Cannot resolve module", most certainly you should disable AMD loader. Add/merge -the following section to your webpack config: +// Retrieve an estimate +const estimateId = 'est_test_1234' +patch.estimates.retrieveEstimate(estimate_id) -```javascript -module: { - rules: [ - { - parser: { - amd: false - } - } - ] -} +// Retrieve a list of estimates +const page = 1 // Pass in which page of estimates you'd like +patch.estimates.retrieveEstimates({ page }) ``` -## Getting Started +### Projects +Projects are the ways Patch takes CO2 out of the air. They can represent reforestation, enhanced weathering, direct air carbon capture, etc. When you place an order via Patch, it is allocated to a project. -Please follow the [installation](#installation) instruction and execute the following JS code: +[API Reference](https://docs.usepatch.com/docs/patch/openapi/v1/swagger.yaml/paths/~1v1~1projects/get) +#### Examples ```javascript -var Patch = require('patch_api_v1'); - -var defaultClient = Patch.ApiClient.instance; -// Configure Bearer access token for authorization: bearer_auth -var bearer_auth = defaultClient.authentications['bearer_auth']; -bearer_auth.accessToken = "YOUR ACCESS TOKEN" - -var api = new Patch.EstimatesApi() -var createMassEstimateRequest = new Patch.CreateMassEstimateRequest(); // {CreateMassEstimateRequest} -api.createMassEstimate(createMassEstimateRequest).then(function(data) { - console.log('API called successfully. Returned data: ' + data); -}, function(error) { - console.error(error); -}); - +// Retrieve a project +const project_id = 'pro_test_1234' // Pass in the project's ID +patch.projects.retrieveProject(project_id) +// Retrieve a list of projects +const page = 1 // Pass in which page of projects you'd like +patch.projects.retrieve_projects({ page }) ``` -## Documentation for API Endpoints - -All URIs are relative to *https://api.usepatch.com* - -Class | Method | HTTP request | Description ------------- | ------------- | ------------- | ------------- -*Patch.EstimatesApi* | [**createMassEstimate**](docs/EstimatesApi.md#createMassEstimate) | **POST** /v1/estimates/mass | Create an estimate based on mass of CO2 -*Patch.EstimatesApi* | [**retrieveEstimate**](docs/EstimatesApi.md#retrieveEstimate) | **GET** /v1/estimates/{id} | Retrieves an estimate -*Patch.EstimatesApi* | [**retrieveEstimates**](docs/EstimatesApi.md#retrieveEstimates) | **GET** /v1/estimates | Retrieves a list of estimates -*Patch.OrdersApi* | [**cancelOrder**](docs/OrdersApi.md#cancelOrder) | **PATCH** /v1/orders/{id}/cancel | Cancel an order -*Patch.OrdersApi* | [**createOrder**](docs/OrdersApi.md#createOrder) | **POST** /v1/orders | Creates an order -*Patch.OrdersApi* | [**placeOrder**](docs/OrdersApi.md#placeOrder) | **PATCH** /v1/orders/{id}/place | Place an order -*Patch.OrdersApi* | [**retrieveOrder**](docs/OrdersApi.md#retrieveOrder) | **GET** /v1/orders/{id} | Retrieves an order -*Patch.OrdersApi* | [**retrieveOrders**](docs/OrdersApi.md#retrieveOrders) | **GET** /v1/orders | Retrieves a list of orders -*Patch.PreferencesApi* | [**createPreference**](docs/PreferencesApi.md#createPreference) | **POST** /v1/preferences | creates a project preference -*Patch.PreferencesApi* | [**deletePreference**](docs/PreferencesApi.md#deletePreference) | **DELETE** /v1/preferences/{id} | Deletes an organization's preference for a project -*Patch.PreferencesApi* | [**retrievePreference**](docs/PreferencesApi.md#retrievePreference) | **GET** /v1/preferences/{id} | Retrieve the preference -*Patch.PreferencesApi* | [**retrievePreferences**](docs/PreferencesApi.md#retrievePreferences) | **GET** /v1/preferences | Retrieves a list of preferences -*Patch.ProjectsApi* | [**retrieveProject**](docs/ProjectsApi.md#retrieveProject) | **GET** /v1/projects/{id} | Retrieves a project -*Patch.ProjectsApi* | [**retrieveProjects**](docs/ProjectsApi.md#retrieveProjects) | **GET** /v1/projects | Retrieves a list of projects - - -## Documentation for Models - - - [Patch.Allocation](docs/Allocation.md) - - [Patch.CreateMassEstimateRequest](docs/CreateMassEstimateRequest.md) - - [Patch.CreateOrderRequest](docs/CreateOrderRequest.md) - - [Patch.CreatePreferenceRequest](docs/CreatePreferenceRequest.md) - - [Patch.ErrorResponse](docs/ErrorResponse.md) - - [Patch.Estimate](docs/Estimate.md) - - [Patch.EstimateListResponse](docs/EstimateListResponse.md) - - [Patch.EstimateResponse](docs/EstimateResponse.md) - - [Patch.MetaIndexObject](docs/MetaIndexObject.md) - - [Patch.Order](docs/Order.md) - - [Patch.OrderListResponse](docs/OrderListResponse.md) - - [Patch.OrderResponse](docs/OrderResponse.md) - - [Patch.Preference](docs/Preference.md) - - [Patch.PreferenceListResponse](docs/PreferenceListResponse.md) - - [Patch.PreferenceResponse](docs/PreferenceResponse.md) - - [Patch.Project](docs/Project.md) - - [Patch.ProjectListResponse](docs/ProjectListResponse.md) - - [Patch.ProjectResponse](docs/ProjectResponse.md) - - -## Documentation for Authorization +### Preferences +Preferences are how you route your orders in Patch. If you don't have a preference, Patch will allocate your order to the least expensive option. If you do have a preference, all of your orders will be sent to that project. You can set your preferences via API, or through the [Patch Dashboard](https://dashboard.usepatch.com/projects). +[API Reference](https://docs.usepatch.com/docs/patch/openapi/v1/swagger.yaml/paths/~1v1~1preferences/post) +#### Examples +```javascript +// Create a preference +const projectId = 'pro_test_1234' // Pass in the project_id for your preference +patch.preferences.create_preference(project_id: projectId) -### bearer_auth +// Retrieve a preference +const preferenceId = 'pre_test_1234' // Pass in the preferences's id +patch.preferences.retrieve_preference(preferenceId) -- **Type**: Bearer authentication +// Delete a preference +const preferenceId = 'pre_test_1234' // Pass in the preferences's id +patch.preferences.delete_preference(preferenceId) +// Retrieve a list of preferences +const page = 1 // Pass in which page of preferences you'd like +patch.preferences.retrieve_preferences({ page }) +```