@devoxa/paddle-sdk NPM

Installation

yarn add @devoxa/paddle-sdk

Usage

:warning: This package does not implement all available webhook events and API routes. It should have the ones required for 90% of subscription based applications, but if you are missing something feel free to add them via a pull request!

import { PaddleSdk, stringifyMetadata } from '@devoxa/paddle-sdk'

// The metadata you want to attach to subscriptions, to link them to your application entities
type PaddleMetadata = { userId: number }

const paddleSdk = new PaddleSdk<PaddleMetadata>({
  baseUrl: 'https://vendors.paddle.com/api', // (Optional) The base URL of the paddle API (e.g. to use the sandbox)
  publicKey: '...', // Your public key from the paddle dashboard
  vendorId: 123, // Your vendor ID from the paddle dashboard
  vendorAuthCode: 'AAA', // Your vendor auth code from the paddle dashboard
  metadataCodec: stringifyMetadata(), // JSON stringify and parse additional order data
})

Available Methods

verifyWebhookEvent(body: any): boolean
parseWebhookEvent(body: any): PaddleSdkSubscriptionCreatedEvent | PaddleSdkSubscriptionUpdatedEvent | ...
async createProductPayLink(data: PaddleSdkCreateProductPayLinkRequest): Promise<PaddleSdkCreateProductPayLinkResponse>
async listSubscriptions(data: PaddleSdkListSubscriptionsRequest): Promise<PaddleSdkListSubscriptionsResponse>
async updateSubscription(data: PaddleSdkUpdateSubscriptionRequest): Promise<PaddleSdkUpdateSubscriptionResponse>
async cancelSubscription(data: PaddleSdkCancelSubscriptionRequest): Promise<PaddleSdkCancelSubscriptionResponse>
async createSubscriptionModifier(data: PaddleSdkCreateSubscriptionModifierRequest): Promise<PaddleSdkCreateSubscriptionModifierResponse>

A note on parsing webhooks:

If you are using parseWebhookEvent on raw events, only enable the following events in your dashboard to prevent ImplementationMissing errors being thrown.

Passthrough Data

During the checkout stage Paddle allows passing additional data to your webhooks in the passthrough strings via either the client-side JavaScript API or the server-side Pay Link API. See the official documentation for more details. It's your responsibility to properly convert your data structures to/from such a string. This project offers you a few such converters in the form of metadata codecs which stringify/parse metadata values to/from passthrough strings:

ignoreMetadata is a codec which ignores metadata values. It stringifies any value to an empty string, and parses any string to a null value.
passthroughMetadata is a codec which assumes your metadata values are already strings and passes them unmodified.
stringifyMetadata is a codec which JSON stringifies/parses your metadata values to/from passthrough strings.
encryptMetadata is a wrapper which must be used to decorate any of the above codecs. It applies symmetric encryption to the passthrough strings generated by the wrapped codec to prevent users from tampering with your data.