Understanding the SDK Usage

This page describes how to understand the main code pieces where the SDK is used and how for the Personalized Newsletter app.

This guide explains how the Humanity Protocol Connect SDK is used throughout the newsletter app to handle authentication and user data extraction.

SDK Initialization

The SDK is initialized once and exported as a singleton in src/lib/humanity-sdk.ts:

import { HumanitySDK } from '@humanity-org/connect-sdk'
import { getConfig } from './config'

const config = getConfig()

export const sdk = new HumanitySDK({
  clientId: config.humanity.clientId!,
  redirectUri: config.humanity.redirectUri!,
  environment: config.humanity.environment ?? 'sandbox',
  clientSecret: config.humanity.clientSecret, // Optional for server-side operations
})

Key Configuration Parameters:

• clientId - Your app's OAuth client ID (required, with ! assertion)

• redirectUri - Where users are redirected after authorization (required, with ! assertion)

• environment - Either 'sandbox' or 'production' (defaults to 'sandbox')

• clientSecret - Optional, but required for server-side token exchange

The OAuth Flow

Step 1: Building the Authorization URL

File: src/app/api/auth/login/route.ts

When a user clicks "Sign in with Humanity Protocol", the app calls the /api/auth/login endpoint which builds an authorization URL using the SDK:

import { sdk } from '@/lib/humanity-sdk'
import { saveOAuthSession } from '@/lib/session'

export async function POST() {
  // Build authorization URL with SDK
  const { url, codeVerifier, state, nonce } = sdk.buildAuthUrl({
    scopes: ['openid', 'profile.full', 'data.read', 'identity:read'], // scopes requested 
  })

  // Store PKCE parameters in session cookie
  saveOAuthSession({
    clientId: config.humanity.clientId,
    redirectUri: config.humanity.redirectUri,
    baseUrl: config.humanity.baseUrl,
    scopes: ['openid', 'profile.full', 'data.read', 'identity:read'],
    codeVerifier, // PKCE code verifier - must be stored for later
    state, // CSRF protection
    nonce, // Replay attack protection
    createdAt: Date.now(),
  })

  // Return authorization URL to frontend
  return NextResponse.json({ url })
}

What the SDK Returns:

• url - The full authorization URL to redirect the user to

• codeVerifier - PKCE parameter that must be stored and used during token exchange

• state - Random string for CSRF protection

• nonce - Random string for replay attack prevention

Important: The codeVerifier must be stored securely (in session cookie) because it's required in the next step to exchange the authorization code for tokens.

Step 2: Handling the OAuth Callback

File: src/app/callback/route.ts

After the user authorizes, Humanity Protocol redirects them back to /callback with an authorization code. The app exchanges this code for access tokens:

import { sdk } from '@/lib/humanity-sdk'
import { readOAuthSession, deleteOAuthSession } from '@/lib/session'
import { extractUserDataAndIssueToken } from '@/lib/auth-service'

export async function GET(request: Request) {
  const { searchParams } = new URL(request.url)
  const code = searchParams.get('code')
  const state = searchParams.get('state')

  // Read PKCE parameters from session
  const session = readOAuthSession(request)
  if (!session) {
    throw new Error('No OAuth session found')
  }

  // Verify state matches (CSRF protection)
  if (state !== session.state) {
    throw new Error('State mismatch')
  }

  // Exchange authorization code for tokens
  const tokens = await sdk.exchangeCodeForToken({
    code: code!,
    codeVerifier: session.codeVerifier, // From Step 1
  })

  // Tokens received:
  // - tokens.accessToken: Used to call Humanity Protocol APIs
  // - tokens.refreshToken: Used to get new access tokens
  // - tokens.idToken: Contains user identity claims

  // Extract user data and create app session
  const { appToken, user } = await extractUserDataAndIssueToken(
    tokens.accessToken
  )

  // Clean up OAuth session, create app session
  deleteOAuthSession(response)
  saveAppSession(
    {
      appToken,
      expiresAt: Date.now() + 86400000, // 24 hours
      userId: user.appScopedUserId,
      humanityUserId: user.humanityUserId,
      email: user.email,
      evmAddress: user.evmAddress,
      linkedSocials: user.linkedSocials.map((s) => s.provider),
      presets: user.presets.map((p) => p.name),
    },
    response
  )

  // Redirect to feed
  return NextResponse.redirect(new URL('/feed', request.url))
}

What the SDK Returns:

• accessToken - Bearer token for calling Humanity Protocol APIs (short-lived)

• refreshToken - Token for obtaining new access tokens (long-lived)

• idToken - JWT containing basic identity claims

Step 3: Extracting User Data with the SDK

File: src/lib/auth-service.ts

Once we have an access token, we use the SDK to fetch the user's profile and verify their presets:

import { sdk } from './humanity-sdk'

export async function extractUserDataAndIssueToken(accessToken: string) {
  // 1. Get user profile
  const profile = await sdk.getUserInfo({ accessToken })

  // 2. Verify social connection presets
  const presetsResult = await sdk.verifyPresets({
    accessToken,
    presets: [
      'google_connected',
      'linkedin_connected',
      'twitter_connected',
      'discord_connected',
      'github_connected',
      'telegram_connected',
    ],
  })

  // presetsResult.results is an array of:
  // [
  //   { presetName: 'linkedin_connected', value: true },
  //   { presetName: 'twitter_connected', value: false },
  //   ...
  // ]

  // 3. Check for travel preferences using Query Engine
  const isFrequentTraveler = await checkFrequentTraveler(accessToken)

  // 4. Save user to database
  const user = await upsertUser({
    humanityUserId: profile.sub,
    appScopedUserId: hashUserId(profile.sub),
    email: profile.email,
    evmAddress: profile.evm_address,
    linkedSocials: extractSocialAccounts(presetsResult),
    presets: extractPresets(presetsResult, isFrequentTraveler),
    lastLoginAt: new Date(),
    updatedAt: new Date(),
  })

  return { appToken: issueAppJWT(user), user }
}

SDK Methods Used:

1. sdk.getUserInfo({ accessToken })

   • Returns user profile from Humanity Protocol

   • Contains: sub, email, evm_address, etc.

2. sdk.verifyPresets({ accessToken, presets })

   • Batch verification of multiple presets

   • Returns array of { presetName, value } objects

   • Used to detect which social accounts are connected

Step 4: Using the Query Engine for Complex Conditions

File: src/lib/auth-service.ts

The SDK also provides a Query Engine for complex predicate queries:

async function checkFrequentTraveler(accessToken: string): Promise<boolean> {
  // Check for hotel membership
  const hotelQuery = {
    policy: {
      anyOf: [
        { check: { claim: 'membership.marriott', operator: 'isDefined' } },
        { check: { claim: 'membership.hilton', operator: 'isDefined' } },
        { check: { claim: 'membership.wyndham', operator: 'isDefined' } },
        // ... more hotel chains
      ],
    },
  }

  const hasHotelMembership = await sdk.evaluatePredicateQuery({
    accessToken,
    query: hotelQuery,
  })

  // Check for airline membership
  const airlineQuery = {
    policy: {
      anyOf: [
        { check: { claim: 'membership.delta', operator: 'isDefined' } },
        { check: { claim: 'membership.emirates', operator: 'isDefined' } },
        // ... more airlines
      ],
    },
  }

  const hasAirlineMembership = await sdk.evaluatePredicateQuery({
    accessToken,
    query: airlineQuery,
  })

  // Frequent traveler = has BOTH hotel AND airline memberships
  return hasHotelMembership.passed && hasAirlineMembership.passed
}

SDK Method:

• sdk.evaluatePredicateQuery({ accessToken, query })

  • Evaluates complex conditional logic against user's credentials

  • Returns { passed: boolean } indicating if conditions are met

  • Used for sophisticated eligibility checks

Key Files Where SDK is Used

File	Purpose	SDK Methods Used
src/lib/humanity-sdk.ts	SDK singleton initialization	new HumanitySDK()
src/app/api/auth/login/route.ts	Build authorization URL	sdk.buildAuthUrl()
src/app/callback/route.ts	Exchange code for tokens	sdk.exchangeCodeForToken()
src/lib/auth-service.ts	Extract user data, verify presets	sdk.getUserInfo(), sdk.verifyPresets()
src/lib/auth-service.ts	Check travel preferences	sdk.evaluatePredicateQuery()

Data Flow Summary

User clicks "Sign in"
         ↓
[login/route.ts] sdk.buildAuthUrl()
  → Returns: { url, codeVerifier, state, nonce }
  → Store codeVerifier in session cookie
  → Redirect user to authorization URL
         ↓
User authorizes on Humanity Protocol
         ↓
Humanity redirects to /callback?code=...
         ↓
[callback/route.ts] sdk.exchangeCodeForToken()
  → Input: code, codeVerifier (from session)
  → Returns: { accessToken, refreshToken, idToken }
         ↓
[auth-service.ts] sdk.getUserInfo()
  → Input: accessToken
  → Returns: { sub, email, evm_address, ... }
         ↓
[auth-service.ts] sdk.verifyPresets()
  → Input: accessToken, presets array
  → Returns: { results: [{ presetName, value }, ...] }
         ↓
[auth-service.ts] sdk.evaluatePredicateQuery()
  → Input: accessToken, query object
  → Returns: { passed: boolean }
         ↓
Save user to MongoDB, create app session
         ↓
Redirect to personalized feed

Important Security Notes

1. Never expose clientSecret to the frontend - it's only used in server-side API routes

2. Always store codeVerifier securely - required for PKCE token exchange

3. Validate state parameter - prevents CSRF attacks

4. Use HTTP-only cookies - prevents XSS access to session tokens

5. Verify all tokens - never trust client-provided data