Subtopia-js-sdk NPM

🌟 About

Subtopia JS SDK is a JavaScript library for interacting with the Subtopia Platform. It provides a simple interface for creating and managing Products (Contracts that are responsible for subscription management).

For detailed documentation, refer to sdk.subtopia.io.

⚡ Examples

subtopia-js-examples - A separate repository with examples of using the Subtopia JS SDK in React, Svelte, Vue and NextJS.

📦 Installation

Install the package:

# with npm
npm install subtopia-js-sdk

# or with yarn
yarn add subtopia-js-sdk

Import the package:

import { SubtopiaClient, SubtopiaRegistryClient } from "subtopia-js-sdk";

🛠️ Usage

Example snippets of using the Subtopia JS SDK.

Subscriptions

Purchasing a subscription:

// ... your code

const subtopiaClient = await SubtopiaClient.init({
  algodClient: PUT_ALGOD_INSTANCE_HERE,
  productID: PUT_PRODUCT_ID_HERE,
  creator: { addr: PUT_WALLET_ADDRESS, signer: PUT_WALLET_SIGNER },
});

const response = await subtopiaClient.createSubscription(
  { addr: PUT_WALLET_ADDRESS, signer: PUT_WALLET_SIGNER },
  PUT_DURATION_HERE // pick duration from Duration enum. If there is a discount available for this duration, it will be auto applied.
);

console.log(response.txID); // response is of type string

// ... rest of your code

Subscription lookup:

// ... your code
const subscriptionRecord = await subtopiaClient.getSubscription({
  subscriberAddress: PUT_SUBSCRIBER_ADDRESS,
});

// SubscriptionRecord (throws Error if not subscribed)
console.log(subscriptionRecord);
// ... rest of your code

Unsubscribing:

// ... your code
const deleteResult = await subtopiaClient.unsubscribe({
  subscriber: {
    addr: PUT_SUBSCRIBER_ADDRESS,
    signer: PUT_SUBSCRIBER_SIGNER,
  },
});

// Transaction ID of the unsubscribe transaction
console.log(deleteResult.txID);
// ... your code

Transfering subscription:

// ... your code
const transferResult = await subtopiaClient.transferSubscription({
  oldSubscriber: {
    addr: PUT_OLD_SUBSCRIBER_ADDRESS,
    signer: PUT_OLD_SUBSCRIBER_SIGNER,
  },
  newSubscriberAddress: PUT_NEW_SUBSCRIBER_ADDRESS,
  subscriptionID: PUT_SUBSCRIPTION_ID,
});

// Transaction ID of the transfer transaction
console.log(transferResult.txID);
// ... your code

Discounts

Creating a discount:

// ... your code

const subtopiaRegistryClient = await SubtopiaRegistryClient.init({
  algodClient: PUT_ALGOD_INSTANCE_HERE,
  creator: { addr: PUT_WALLET_ADDRESS, signer: PUT_WALLET_SIGNER },
  chainType: PUT_CHAIN_TYPE_HERE,
});

const discount = await subtopiaRegistryClient.createDiscount({
  productID: PUT_PRODUCT_ID_HERE, // number - the ID of the Product instance you want to create a discount for
  duration: PUT_DURATION_HERE, // number - the type of duration to apply. Also serves as static id for the discount.
  discountType: PUT_DISCOUNT_TYPE_HERE, // number - the type of discount to apply. FIXED or PERCENTAGE
  discountValue: PUT_DISCOUNT_VALUE_HERE, // number - the discount to be deducted from the subscription price
  expiresIn: PUT_EXPIRATION_TIME_HERE, // (Optional) Set 0 for discount to never expire. Else set number of seconds to append to unix timestamp at time of creation.
});

console.log(discount.txID); // response is of type string

// ... rest of your code

Discount lookup:

// ... your code

const discount = await subtopiaRegistryClient.getDiscount(
  productID: PUT_PRODUCT_ID_HERE,
  duration: PUT_DURATION_HERE,
);

// DiscountRecord (throws Error if not found)
console.log(discount);
// ... rest of your code

Deleting a discount:

// ... your code

const deleteResult = await subtopiaRegistryClient.deleteDiscount({
  productID: PUT_PRODUCT_ID,
  duration: PUT_DURATION_HERE,
});

// Transaction ID of the delete discount transaction
console.log(deleteResult.txID);
// ... your code