@chainvine/sdk

@ChainVine SDK

A light client for interacting with the ChainVine API (note: you will need an active subscription for ChainVine in order to utilise the SDK).

Installation

npm install @chainvine/sdk

Usage

There are two methods of interacting with the ChainVine API, either by providing a Chainvine API Key (available under 'Community Settings' from your admin dashboard) or by omitting the API key and ensuring all requests are sent from a previously whitelisted domains (these can also be managed under 'Community Settings' from your admin dashboard).

It is advised to use the API key method as it is more secure and allows you to use the SDK from any domain, but only if you are operating from a server context (i.e. from an API) as you do not want to expose your API key in a browser.

Should you be using the ChainVine SDK on the browser side you will need to follow the domain whitelisting approach.

Please consult the documentation for usage and integration details: https://docs.chainvine.xyz/developers/sdk

import { ChainvineClient } from '@chainvine/sdk/lib';

// Initialise the client (without an API key or any overriden settings)
const client = new ChainvineClient();

//OR, Initialise the client with an API key and/or supply some config
const client = new ChainvineClient({
  apiKey: '<YOUR API KEY>', //optional, if not provided you will need to whitelist your domain from your admin dashboard
  testMode: true, // optional, defaults to false. When set to true, the SDK will use the test API endpoint
  logToConsole: true, // optional, defaults to false. When set to true, the SDK will log errors and requests/responses to the console (useful for development and debugging)
});

// All user-specific actions require a userClient
const user_wallet = '0x1234567890';
const userClient = await client.syncUser(user_wallet)

Helper functions

We offer some helper functions to make integration with ChainVine easier.

Note: these helper functions rely on browser functionality and must be executed client-side.

Store a Referrer Code for future use

This will create a CV_REF cookie for you (which will expire in 120 days by default) you can either interrogate requests to your API for this if you are using the SDK from your API or call getReferrerId() to fetch when you need it in your browser

import { storeReferrer } from '@chainvine/sdk';

storeReferrer(); //This will fetch the r query parameter from the current URL (if available) and store it in a CV_REF cookie

You may customise the cookie settings as follows:

storeReferrer({
  durationDays: 30, //Override the default cookie duration (120 days)
  ref: 'ABC123', //Should you already have access to the referrer code, and if you do not want it fetched from the URL, you can provide it directly
}); 

Retrieve a previously stored Referrer Code

import { getReferrer } from '@chainvine/sdk';

//Fetches a previously stored referrer code from the CV_REF cookie if available, returns undefined if not
getReferrer(); 

Clear a stored Referrer Code

import { clearReferrer } from '@chainvine/sdk';

//Clear the CV_REF cookie:
clearReferrer();

A browser use-case might then look something like:

import { ChainvineClient } from '@chainvine/sdk/lib';
import { getReferrer, storeReferrer } from '@chainvine/sdk';

const client = new ChainvineClient();

... 

//Fetch and store the referrer_id from the URL on page load:
storeReferrer();

...

//When a user connects their wallet (or at any point once you have access to their wallet address) 
//Note: this could be a completely different page or flow to the one where the referrer was stored
const user = await client.syncUser('0x1234567890')
const referral = await user.referral({campaign}).linkReferrer(getReferrer());