npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

pi-backend

v0.1.3

Published

This is an official Pi Network Node.js npm package you can use to integrate the Pi Network apps platform with a node.js backend application.

Downloads

66

Readme

Pi Network - Node.JS server-side package

This is an official Pi Network Node.js npm package you can use to integrate the Pi Network apps platform with a node.js backend application.

Install

Install this package as a dependency of your app:

# With npm:
npm install --save pi-backend

# With yarn:
yarn add pi-backend

Example

  1. Initialize the SDK
import PiNetwork from 'pi-backend';

// DO NOT expose these values to public
const apiKey = "YOUR_PI_API_KEY"
const walletPrivateSeed = "S_YOUR_WALLET_PRIVATE_SEED" // starts with S
const pi = new PiNetwork(apiKey, walletPrivateSeed);
  1. Create an A2U payment

Make sure to store your payment data in your database. Here's an example of how you could keep track of the data. Consider this a database table example.

| uid | product_id | amount | memo | payment_id | txid | | :---: | :---: | :---: | :---: | :---: | :---: | | userUid | apple-pie-1 | 3.14 | Refund for apple pie | NULL | NULL |

const userUid = "user_uid_of_your_app"
const paymentData = {
  amount: 1,
  memo: "Refund for apple pie", // this is just an example
  metadata: {productId: "apple-pie-1"},
  uid: userUid
}
// It is critical that you store paymentId in your database
// so that you don't double-pay the same user, by keeping track of the payment.
const paymentId = await pi.createPayment(paymentData);
  1. Store the paymentId in your database

After creating the payment, you'll get paymentId, which you should be storing in your database.

| uid | product_id | amount | memo | payment_id | txid | | :---: | :---: | :---: | :---: | :---: | :---: | | userUid | apple-pie-1 | 3.14 | Refund for apple pie | paymentId | NULL |

  1. Submit the payment to the Pi Blockchain
// It is strongly recommended that you store the txid along with the paymentId you stored earlier for your reference.
const txid = await pi.submitPayment(paymentId);
  1. Store the txid in your database

Similarly as you did in step 3, keep the txid along with other data.

| uid | product_id | amount | memo | payment_id | txid | | :---: | :---: | :---: | :---: | :---: | :---: | | userUid | apple-pie-1 | 3.14 | Refund for apple pie | paymentId | txid |

  1. Complete the payment
const completedPayment = await pi.completePayment(paymentId, txid);

Overall flow for A2U (App-to-User) payment

To create an A2U payment using the Pi Node.js SDK, here's an overall flow you need to follow:

  1. Initialize the SDK

You'll be initializing the SDK with the Pi API Key of your app and the Private Seed of your app wallet.

  1. Create an A2U payment

You can create an A2U payment using createPayment method. This method returns a payment identifier (payment id).

  1. Store the payment id in your database

It is critical that you store the payment id, returned by createPayment method, in your database so that you don't double-pay the same user, by keeping track of the payment.

  1. Submit the payment to the Pi Blockchain

You can submit the payment to the Pi Blockchain using submitPayment method. This method builds a payment transaction and submits it to the Pi Blockchain for you. Once submitted, the method returns a transaction identifier (txid).

  1. Store the txid in your database

It is strongly recommended that you store the txid along with the payment id you stored earlier for your reference.

  1. Complete the payment

After checking the transaction with the txid you obtained, you must complete the payment, which you can do with completePayment method. Upon completing, the method returns the payment object. Check the status field to make sure everything looks correct.

SDK Reference

This section shows you a list of available methods.

createPayment

This method creates an A2U payment.

  • Required parameter: PaymentArgs

You need to provide 4 different data and pass them as a single object to this method.

type PaymentArgs = {
  amount: number // the amount of Pi you're paying to your user
  memo: string // a short memo that describes what the payment is about
  metadata: object // an arbitrary object that you can attach to this payment. This is for your own use. You should use this object as a way to link this payment with your internal business logic.
  uid: string // a user uid of your app. You should have access to this value if a user has authenticated on your app.
}
  • Return value: a payment identifier (paymentId: string)

submitPayment

This method creates a payment transaction and submits it to the Pi Blockchain.

  • Required parameter: paymentId
  • Return value: a transaction identifier (txid: string)

completePayment

This method completes the payment in the Pi server.

  • Required parameter: paymentId, txid
  • Return value: a payment object (payment: PaymentDTO)

The method return a payment object with the following fields:

payment: PaymentDTO = {
  // Payment data:
  identifier: string, // payment identifier
  user_uid: string, // user's app-specific ID
  amount: number, // payment amount
  memo: string, // a string provided by the developer, shown to the user
  metadata: object, // an object provided by the developer for their own usage
  from_address: string, // sender address of the blockchain transaction
  to_address: string, // recipient address of the blockchain transaction
  direction: Direction, // direction of the payment ("user_to_app" | "app_to_user")
  created_at: string, // payment's creation timestamp
  network: string, // a network of the payment ("Pi Network" | "Pi Testnet")
  // Status flags representing the current state of this payment
  status: {
    developer_approved: boolean, // Server-Side Approval (automatically approved for A2U payment)
    transaction_verified: boolean, // blockchain transaction verified
    developer_completed: boolean, // Server-Side Completion (handled by the create_payment! method)
    cancelled: boolean, // cancelled by the developer or by Pi Network
    user_cancelled: boolean, // cancelled by the user
  },
  // Blockchain transaction data:
  transaction: null | { // This is null if no transaction has been made yet
    txid: string, // id of the blockchain transaction
    verified: boolean, // true if the transaction matches the payment, false otherwise
    _link: string, // a link to the operation on the Pi Blockchain API
  }
}

getPayment

This method returns a payment object if it exists.

  • Required parameter: paymentId
  • Return value: a payment object (payment: PaymentDTO)

cancelPayment

This method cancels the payment in the Pi server.

  • Required parameter: paymentId
  • Return value: a payment object (payment: PaymentDTO)

getIncompleteServerPayments

This method returns the latest incomplete payment which your app has created, if present. Use this method to troubleshoot the following error: "You need to complete the ongoing payment first to create a new one."

  • Required parameter: none
  • Return value: an array which contains 0 or 1 payment object (payments: Array<PaymentDTO>)

If a payment is returned by this method, you must follow one of the following 3 options:

  1. cancel the payment, if it is not linked with a blockchain transaction and you don't want to submit the transaction anymore

  2. submit the transaction and complete the payment

  3. if a blockchain transaction has been made, complete the payment

If you do not know what this payment maps to in your business logic, you may use its metadata property to retrieve which business logic item it relates to. Remember that metadata is a required argument when creating a payment, and should be used as a way to link this payment to an item of your business logic.

Troubleshooting

Error when creating a payment: "You need to complete the ongoing payment first to create a new one."

See documentation for the getIncompleteServerPayments above.