项目作者: patch-technology

项目描述 :
Patch's Javascript client library - https://www.patch.io
高级语言: JavaScript
项目地址: git://github.com/patch-technology/patch-node.git
创建时间: 2020-07-26T23:18:20Z
项目社区:https://github.com/patch-technology/patch-node

开源协议:

下载


Patch JavaScript SDK

Test
@patch-technology/patch"">npm version
Discord

The official JavaScript package for the Patch API.

Documentation

For a complete API reference, check out Patch’s API Reference.

Installation

NPM

  1. npm install @patch-technology/patch --save

Yarn

  1. yarn add @patch-technology/patch

Requirements

  • Node 10+

Usage

Configuration

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:

  1. // ES6+
  2. import Patch from '@patch-technology/patch';
  3. const patch = Patch('key_test_1234');
  4. // ES5
  5. var patch = require('@patch-technology/patch').default('key_test_1234');

Peer dependencies

For environments that do not include the Node Standard Library, such as React Native, you will need to install the listed peer dependencies in order for the package to work as expected. You can install the peer dependencies by running:

  1. npm install install-peers

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.
You can also create an order with a maximum desired price, and we’ll allocate enough mass to
fulfill the order for you.

API Reference

Examples

  1. // Create an order - you can create an order
  2. // providing either amount (and unit) or total_price (and currency), but not both
  3. // Create order with amount
  4. const amount = 1_000_000; // Pass in the amount in unit specified
  5. const unit = 'g';
  6. patch.orders.createOrder({ amount: amount, unit: unit });
  7. // Create an order with total price
  8. const totalPrice = 500; // Pass in the total price in smallest currency unit (ie cents for USD).
  9. const currency = 'USD';
  10. patch.orders.createOrder({ total_price: totalPrice, currency: currency });
  11. // Create order with the issued_to field (optional)
  12. const amount = 1_000_000; // Pass in the amount in unit specified
  13. const unit = 'g';
  14. const issued_to = { email: 'issuee@companya.com', name: 'Olivia Jones' };
  15. patch.orders.createOrder({ amount: amount, unit: unit, issued_to: issued_to });
  16. // Retrieve an order
  17. orderId = 'ord_test_1234'; // Pass in the order's id
  18. patch.orders.retrieveOrder(orderId);
  19. // Place an order
  20. const orderId = 'ord_test_1234'; // Pass in the order's id
  21. patch.orders.placeOrder(orderId);
  22. // Place an order with the issued_to field (optional)
  23. const orderId = 'ord_test_1234'; // Pass in the order's id
  24. const issued_to = { email: 'issuee@companya.com', name: 'Olivia Jones' };
  25. patch.orders.placeOrder(orderId, { issued_to: issued_to });
  26. // Cancel an order
  27. const orderId = 'ord_test_1234'; // Pass in the order's id
  28. patch.orders.cancelOrder(orderId);
  29. // Retrieve a list of orders
  30. const page = 1; // Pass in which page of orders you'd like
  31. patch.orders.retrieveOrders({ page });

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.

API Reference

Examples

  1. // Create a mass estimate
  2. const mass_g = 1000000; // Pass in the mass in grams (i.e. 1 metric tonne)
  3. patch.estimates.createMassEstimate({ mass_g });
  4. // Create a flight estimate
  5. const distance_m = 9000000; // Pass in the distance traveled in meters
  6. patch.estimates.createFlightEstimate({ distance_m });
  7. // Create an ecommerce estimate
  8. const distance_m = 9000000;
  9. // Pass in the shipping distance in meters, the transportation method, and the package mass
  10. patch.estimates.createEcommerceEstimate({
  11. distance_m,
  12. package_mass_g: 1000,
  13. transportation_method: 'air'
  14. });
  15. // Create a bitcoin estimate
  16. const transaction_value_btc_sats = 1000; // [Optional] Pass in the transaction value in satoshis
  17. patch.estimates.createBitcoinEstimate({
  18. transaction_value_btc_sats
  19. });
  20. // Create a vehicle estimate
  21. const distance_m = 9000000;
  22. // Pass in the driving distance in meters and the model/make/year of the vehicle
  23. patch.estimates.createVehicleEstimate({
  24. distance_m,
  25. make: 'Toyota',
  26. model: 'Corolla',
  27. year: 1995
  28. });
  29. // Retrieve an estimate
  30. const estimateId = 'est_test_1234';
  31. patch.estimates.retrieveEstimate(estimate_id);
  32. // Retrieve a list of estimates
  33. const page = 1; // Pass in which page of estimates you'd like
  34. patch.estimates.retrieveEstimates({ page });

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.

When fetching Projects, you can add filters to the query to narrow the result. Currently supported filters are:

  • country
  • type
  • minimumAvailableMass

You can also set the acceptLanguage option to retrieve projects in a different language.

API Reference

Examples

  1. // Retrieve a project
  2. const projectId = 'pro_test_1234'; // Pass in the project's ID
  3. patch.projects.retrieveProject(projectId);
  4. // Retrieve a list of projects
  5. const page = 1; // Pass in which page of projects you'd like
  6. patch.projects.retrieveProjects({ page });
  7. // Retrieve a filtered list of projects
  8. const country = 'CA'; // Pass in the country you'd like to get projects from
  9. patch.projects.retrieveProjects({ country });
  10. // Retrieve a filtered list of projects
  11. const type = 'biomass'; // Pass in the project type you'd like to filter by
  12. patch.projects.retrieveProjects({ type });
  13. // Retrieve a filtered list of projects
  14. const minimumAvailableMass = 100; // Pass in the minimum available inventory the projects should have
  15. patch.projects.retrieveProjects({ minimumAvailableMass });
  16. // Retrieve a project in another language
  17. // See http://docs.patch.test:3000/#/internationalization for more information and support languages
  18. const projectId = 'pro_test_1234';
  19. patch.projects.retrieveProject(projectId, { acceptLanguage: 'fr' });

Contributing

While we value open-source contributions to this SDK, the core of this library is generated programmatically. Complex additions made directly to the library would have to be moved over to our generation code, otherwise they would be overwritten upon the next generated release. Feel free to open a PR as a proof of concept, but know that we will not be able to merge it as-is. We suggest opening an issue first to discuss with us!

On the other hand, contributions to the README, as well as new test cases are always very welcome!

Build and manually test

To build and test the package locally, run:

  1. $ npm run build

This will generate a dist folder with the compiled code. Next you want to link the package and use it in a different folder.

In the patch-node folder, run:

  1. $ npm link

Navigate to a different, empty folder:

  1. $ cd ..
  2. $ mkdir test-patch-node
  3. $ cd test-patch-node

In that repository, run the following command to use the locally built package:

  1. $ npm link @patch-technology/patch

This will create a node_modules directory in your test repository which will symlink to your locally built package. To test out the package, open a node REPL and import the package and run some queries.

  1. SANDBOX_API_KEY=xxx node
  1. const Patch = require('@patch-technology/patch');
  2. const patch = Patch.default(process.env.SANDBOX_API_KEY);
  3. patch.projects.retrieveProjects().then((response) => console.log(response));

Run the specs

Before running the tests, make sure you set the test API key! Please use test API keys and not production ones, they usually start with key_test_.
Be sure you navigate back to the root patch-node directory to run the tests.

  1. $ export SANDBOX_API_KEY=<PATCH_TEST_API_KEY>

Then you are ready to run the tests:

  1. $ npm run test