Skip to content

Commit

Permalink
update readme
Browse files Browse the repository at this point in the history
  • Loading branch information
@bspellacy
bspellacy committed Jul 29, 2020
1 parent 0c88696 commit ada5bd8
Showing 1 changed file with 83 additions and 128 deletions.
211 changes: 83 additions & 128 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -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/<JAVASCRIPT_CLIENT_DIR>
```
[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&#39;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 })
```

0 comments on commit ada5bd8

Please sign in to comment.