GENUN API Documentation

Appearance

SDK Guide ​

Install with NPM ​

For project that utilize module bundler like Webpack, Rollup, Parcel, Vite, or for applications created with Create React App, Vue CLI, etc., you can install the latest version of @genun/client-sdk using npm or yarn.

To install with npm:

bash
npm install @genun/client-sdk --save

To install with yarn:

bash
yarn add @genun/client-sdk

Peer Dependencies ​

Please note that @genun/client-sdk requires axios as a peer dependency. If you haven't already installed axios in your project, you will need to install it separately:

bash
npm install axios --save

Or if you are using yarn:

bash
yarn add axios

Make sure to install a version of axios that is compatible with the version required by @genun/client-sdk.

Including the SDK in Your Project ​

Depending on your project type and module system, you can choose different ways to include @genun/client-sdk.

Using the UMD Package ​

If you want to include @genun/client-sdk directly in the browser using a <script> tag, use the following CDN link:

html
<!-- Dependencies -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/axios/1.6.2/axios.min.js"></script>
<!-- Include @genun/client-sdk -->
<script src="https://cdn.genunuserdata.online/genun-client-sdk.umd.1.6.0.min.js"></script>

After inclusion, GenunClientSDK will be available as a global object.

Using CommonJS Package ​

If you are in a Node.js environment or a project using a build tool (like Webpack), you can include it like this:

javascript
// Include @genun/client-sdk
const GenunClientSDK = require('@genun/client-sdk');

Using ES Module ​

For modern JavaScript environments that support ES Modules, you can use the import syntax:

javascript
// Include @genun/client-sdk
import GenunClientSDK from '@genun/client-sdk';

Init SDK ​

To initialize the SDK, create a new instance of GENUNClient with your API domain and API key, as well as any additional configurations needed for your setup.

Constructor Parameters:

  • domain (String): The API domain.
  • apiKey (String): Your API key.
  • debug (Boolean): Optional. Enables debug mode, which outputs more error logs. Defaults to false.
  • loginRequiredHook (Function): Optional. A hook that gets triggered when the API returns a loginRequiredErrorCode.
  • ...anyAxiosParams (Any): Optional. Additional Axios configuration parameters, see: Axios request config.

API Method:

javascript
GENUNClient({
    domain,
    apiKey,
    debug,
    loginRequiredHook,
    ...anyAxiosParams,
})

Example:

javascript
const genunClient = new GENUNClient({
    domain: 'API_DOMAIN',
    apiKey: 'YOUR_API_KEY',
    debug: true,
    loginRequiredHook() {
        // Handle the logic when the API returns that user
        // authentication is required to access the API.
        console.log('You need to log in to continue');
    },
    timeout: 10000,
});

Customer Registration and Login With Wallet ​

Allow users to register an account or log in to the platform using an Ethereum wallet. This process involves passing user identity details along with an EIP-712 signature from the wallet.

API Method:

javascript
async genunClient.auth.loginWithWallet({
    id,
    account,
    timestamp,
    signature,
    walletType,
});

Parameters:

  • id (String): A version 4 UUID that must be unique and cannot be reused.
  • account (String): The user's Ethereum account address.
  • timestamp (Number): The current timestamp when the signature was generated.
  • signature (String): The signature conforming to the EIP-712 standard, generated by wallet plugin such as MetaMask.
  • walletType (Number): The type of wallet.

Here are the walletType IDs for each supported wallet:

WALLET_TYPE_IDs = {
    "MetaMask": 2,
    "WalletConnect": 3,
    "Web3Auth": 4,
    "TrustWallet": 5,
    "CoinbaseWallet": 6
}

EIP-712 Signature Generation for Wallet Authentication:

To authenticate using the loginWithWallet method, you must generate a signature that conforms to the EIP-712 standard. This involves creating a structured data object that the user's wallet will sign. The following JSON object defines the data structure required for the signature:

{
    "domain": {
        "name": "GENU.N Authentication",
        "version": "1.0",
        "verifyingContract": "0xCcCCccccCCCCcCCCCCCcCcCccCcCCCcCcccccccC"
    },
    "primaryType": "Request",
    "types": {
        "Request": [
            { "name": "id", "type": "string" },
            { "name": "account", "type": "address" },
            { "name": "timestamp", "type": "uint256" }
        ]
    }
}

Steps for Generating the Signature:

  1. Generate a UUID: Create a version 4 UUID to use as the id. This will serve as a unique identifier for the authentication request.
  2. Get the Wallet Address: Retrieve the currently connected wallet address to use as the account.
  3. Create a Timestamp: Generate the current time as a Unix timestamp to use as the timestamp.
  4. Submit for Signing: Combine the id, account, and timestamp with the above EIP-712 data structure and submit it to the wallet plugin or service to generate the signature.
  5. Call loginWithWallet: Use the signature along with the id, account, and timestamp as parameters to call the loginWithWallet method.

Example:

javascript
const result = await genunClient.auth.loginWithWallet({
    id: 'uuid',
    account: '0xUSER_ACCOUNT_ADDRESS',
    timestamp: CURRENT_UNIX_TIMESTAMP,
    signature: 'SIGNATURE_FROM_WALLET',
    walletType: WALLET_TYPE_ID,
});

Returns:

json
{
    "token": "JWT_TOKEN"
}

List All Products ​

Retrieves a list of all products with pagination support. This includes details such as contract status, inventory quantity.

API Method:

javascript
async genunClient.product.list({
    limit,
    page,
});

Parameters:

  • limit (Number): The number of products per page.
  • page (Number): The page number to retrieve.

Example:

javascript
const result = await genunClient.product.list({
    limit: 10,
    page: 1,
});

Returns:

json
{
    "data": [
        {
            "id": "PRODUCT_ID",
            "name": "PRODUCT_NAME",
            // Additional product details...
        },
        // More products...
    ],
    "limit": 10,
    "page": 1,
    "total": TOTAL_NUMBER_OF_PRODUCTS
}

Get Product Details ​

Fetches detailed information about a specific product, including authentication type, certification contract details, and inventory statistics.

API Method:

javascript
async genunClient.product.detail(productId);

Parameters:

  • productId (String): The unique identifier of the product.

Example:

javascript
const result = await genunClient.product.detail('productId');

Returns:

json
{
    "id": "PRODUCT_ID",
    "name": "PRODUCT_NAME",
    // Additional product details...
}

Get Product Item Details ​

Fetches detailed information about a specific product item identified by its item ID, including certification details, claiming status, and associated product information.

API Method:

javascript
async genunClient.product.itemDetail({
    productItemId,
})

Parameters:

  • productItemId (required): The unique identifier for the product item.

Example:

javascript
const result = await genunClient.product.itemDetail('productItemId');

Returns:

json
{
  "authenticator": {},
  "certificationContract": {
    // ...contract details
  },
  // ...other fields
  "product": {
    "content": "...",
    "cover": "662802786546614272",
    "id": "662804743130710016",
    // ...other product details
  },
  "productAttributes": [
    {
      "name": "Color",
      "value": "White",
      // ...other attribute details
    }
  ],
  "productItem": {
    "SN": "P001",
    "statusText": "Claimable",
    // ...other item details
  },
  "walletTypesSupportedForClaiming": [1, 2, 4]
}

Item Authentication ​

Authenticates an identity asset (Ntag or QR Code) to verify if the tag has not been tampered with and retrieves the associated product item ID.

API Method:

javascript
async genunClient.identityAsset.authenticate(secureCode);

Parameters:

  • secureCode (String): The secure code extracted from the QR code or Ntag.

Example:

javascript
const secureCode = 'SECURE_CODE_FROM_QR';
const result = await genunClient.identityAsset.authenticate(secureCode);

Returns:

json
{
    "productItemId": "ITEM_ID"
}

Item and NFT Claiming ​

Allows users to claim a product item, transferring ownership to their account. This process returns the updated product item details.

API Method:

javascript
async genunClient.product.claimItem({
    productItemId,
});

Parameters:

  • productItemId (String): The unique identifier of the product item to claim.

Example:

javascript
const claimResponse = await genunClient.product.claimItem({
    productItemId: 'productItemId',
});

Returns:

  • The same structure as the product detail response.

List Customer Claimed Items ​

Lists items associated with a specified user or the current user if no user ID is provided. This includes product details and item information.

API Method:

javascript
async genunClient.user.items({
    userId,
    limit,
    page,
});

Parameters:

  • userId (String, optional): The unique identifier of the user, default is the id of current logged-in user.
  • limit (Number): The number of items per page.
  • page (Number): The page number to retrieve.

Example:

javascript
const result = await genunClient.user.items({
    limit: 10,
    page: 1,
});

Returns:

json
{
    "data": [
        {
            "productItem": {
                "id": "ITEM_ID",
                "SN": "SERIAL_NUMBER",
                // Additional item details...
            },
            // More items...
        }
    ],
    "limit": 10,
    "page": 1,
    "total": TOTAL_NUMBER_OF_ITEMS
}

List Customer Claimed NFTs ​

Compiles a list of NFTs owned by a specified user or the current user if no user ID is provided. Details include blockchain network, NFT metadata, and contract information.

API Method:

javascript
async genunClient.user.nfts({
    userId,
    limit,
    page,
});

Parameters:

  • userId (String, optional): The unique identifier of the user, default is the id of current logged-in user.
  • limit (Number): The number of NFTs per page.
  • page (Number): The page number to retrieve.

Example:

javascript
const result = await genunClient.user.nfts({
    limit: 10,
    page: 1,
});

Returns:

json
{
    "data": [
        {
            "bcNft": {
                "tokenId": "NFT_TOKEN_ID",
                "contractAddress": "CONTRACT_ADDRESS",
                // Additional NFT details...
            },
            // More NFTs...
        }
    ],
    "limit": 10,
    "page": 1,
    "total": TOTAL_NUMBER_OF_NFTS
}

NFT Token Gating ​

Verifies whether the currently logged-in user has the necessary NFTs to access exclusive content, returning a boolean indicating access permission.

API Method:

javascript
async genunClient.gating.verify();

Returns:

json
{
    "accessGranted": Boolean
}

Example:

javascript
const result = await genunClient.gating.verify();