@ustriveneo/partner-sdk

TypeScript SDK for the UStrive Partner API. Enables partners to integrate UStrive's mentorship platform into their applications.

Installation

npm install @ustriveneo/partner-sdk

Quick Start

import { UStrivePartnerClient } from '@ustriveneo/partner-sdk';

const client = new UStrivePartnerClient({
  apiKey: 'pk_live_xxx',
  secret: 'sk_live_yyy',
});

Usage

Create a Student

const user = await client.users.create({
  firstName: 'Jane',
  lastName: 'Doe',
  email: '[email protected]',
  userType: 'STUDENT',
});

Search Mentors

const { mentors } = await client.mentors.search({
  q: 'college applications',
  limit: 10,
});

Get Mentor Profile

const mentor = await client.mentors.get('mentor-id');

Create a Match

const match = await client.matches.create({
  studentId: 'student-id',
  mentorId: 'mentor-id',
  message: 'Looking forward to working together!',
});

Schedule a Session

const session = await client.sessions.create({
  matchId: 'match-id',
  startTime: '2026-03-01T14:00:00Z',
  endTime: '2026-03-01T15:00:00Z',
  type: 'VIDEO',
  timezone: { value: 'America/New_York', label: 'Eastern Time' },
});

End a Match

await client.matches.end('match-id', {
  satisfactionRating: 5,
  feedback: 'Great experience!',
});

List User's Matches

const { matches } = await client.matches.listByUser('user-id', {
  status: 'ACTIVE',
});

List User's Sessions

const { sessions } = await client.sessions.listByUser('user-id');

External Identity & Cognito Integration

The SDK supports linking external user identities (e.g., Cognito sub) to UStrive users. This is useful when your application manages its own authentication via Cognito or another identity provider.

Sync User (Cognito Post Authentication Trigger)

The sync method is idempotent and designed to be called on every authentication event. It creates a new user if no match is found, or updates the existing linked user.

// In your Cognito Post Authentication Lambda trigger:
import { UStrivePartnerClient } from '@ustriveneo/partner-sdk';

const client = new UStrivePartnerClient({
  apiKey: process.env.USTRIVE_API_KEY!,
  secret: process.env.USTRIVE_SECRET!,
});

export const handler = async (event: any) => {
  const { sub, email, given_name, family_name } = event.request.userAttributes;

  const result = await client.users.sync({
    externalId: sub,
    firstName: given_name,
    lastName: family_name,
    email: email,
    userType: 'STUDENT',
  });

  if (result.created) {
    console.log('New UStrive user created:', result.id);
  } else {
    console.log('Existing UStrive user synced:', result.id);
  }

  return event;
};

Look Up User by External ID

const user = await client.users.getByExternalId('cognito-sub-value');
console.log('UStrive user ID:', user.id);

Create User with External ID

You can also provide an externalId when creating a user directly:

const user = await client.users.create({
  firstName: 'Jane',
  lastName: 'Doe',
  email: '[email protected]',
  userType: 'STUDENT',
  externalId: 'cognito-sub-12345',
});

Messaging

The SDK provides server-side messaging capabilities for match chat channels.

Get Stream Token

Generate a client-side token for a user to connect to real-time chat/video:

const { token, apiKey } = await client.messaging.getStreamToken('user-id');
// Pass token + apiKey to @ustriveneo/partner-realtime on the client

Send a Message

const message = await client.messaging.sendMessage('match-id', {
  userId: 'student-id',
  text: 'Hello mentor!',
});

Get Message History

const { messages } = await client.messaging.getMessages('match-id', {
  limit: 50,
  offset: 0,
});

Calls (Video & Audio)

Create a Call

const call = await client.calls.create('match-id');
// Returns: { callId, type, createdAt }

List Calls

const { calls } = await client.calls.list('match-id');

Error Handling

import { UStriveError, RateLimitError, NotFoundError } from '@ustriveneo/partner-sdk';

try {
  const user = await client.users.get('non-existent-id');
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log('User not found');
  } else if (error instanceof RateLimitError) {
    console.log(`Rate limited. Retry after ${error.retryAfter} seconds`);
  } else if (error instanceof UStriveError) {
    console.log(`API error: ${error.message} (${error.statusCode})`);
  }
}

Configuration

const client = new UStrivePartnerClient({
  apiKey: 'pk_test_xxx',       // Your public API key
  secret: 'sk_test_yyy',       // Your secret key
  baseUrl: 'https://partner-api-dev.ustriveneo.com', // Optional: override for dev/staging
});

Authentication

The SDK handles authentication automatically. On the first request, it exchanges your API key and secret for a JWT token (valid for 1 hour). Tokens are refreshed automatically when they expire.

Webhooks

To receive real-time events (match created, session scheduled, etc.), configure a webhook URL in the Developer Console. Events are delivered as POST requests signed with your webhook secret.

Signature Headers

Each webhook delivery includes two signature headers with identical values:

• X-Webhook-Signature (recommended) - Use this header for new integrations.
• X-UStrive-Signature (deprecated) - Will be removed in a future release. Migrate to X-Webhook-Signature.

Verifying Webhook Signatures

import crypto from 'crypto';

function verifyWebhookSignature(payload: string, signature: string, secret: string): boolean {
  const [tsPart, sigPart] = signature.split(',');
  const timestamp = tsPart.replace('t=', '');
  const expectedSig = sigPart.replace('v1=', '');

  const computed = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${payload}`)
    .digest('hex');

  return crypto.timingSafeEqual(Buffer.from(computed), Buffer.from(expectedSig));
}

// Usage: read from X-Webhook-Signature header (preferred)
const signature = req.headers['x-webhook-signature'];
const isValid = verifyWebhookSignature(req.body, signature, webhookSecret);

Testing Webhooks

Use the Event Simulator in the Developer Console to send realistic test payloads for any event type. You can simulate specific scenarios like match accepted, rejected, or expired. See the Webhooks documentation for details.