SDK Examples

Real-world examples demonstrating common NIL Taxonomy SDK usage patterns.

Interactive Builder

Try building licenses with different presets:

Choose a Preset

import { createCommercialLicense } from '@nil-taxonomy/sdk';

const license = createCommercialLicense()
  .setTerritoryCountries(['US', 'CA'])
  .setTerm('2024-01-01', '2025-12-31')
  .addRestrictedCategory('alcohol')
  .addRestrictedCategory('tobacco')
  .build();

Standard brand campaigns and endorsements. Full commercial rights, non-exclusive.

Complete Examples

Example 1: Social Media Endorsement

An athlete partners with a beverage brand for Instagram posts:

import { createCommercialLicense, validateLicense } from '@nil-taxonomy/sdk';
 
// Build the license
const socialEndorsement = createCommercialLicense()
  .setTerritoryCountries(['US', 'CA'])
  .setTerm('2024-01-01', '2024-12-31')
  .addRestrictedCategory('alcohol') // Athlete is under 21
  .addRestrictedCategory('tobacco')
  .addRestrictedCategory('sports_betting')
  .setDerivativeRights('limited')
  .build();
 
// Validate
const validation = validateLicense(socialEndorsement);
if (!validation.valid) {
  throw new Error('Invalid license configuration');
}
 
// Save to database
await db.contracts.create({
  data: {
    athlete_id: 'athlete-123',
    brand_id: 'brand-456',
    license_config: socialEndorsement,
    compensation: { amount: 50000, currency: 'USD' },
    status: 'active'
  }
});

Example 2: Documentary Film

A documentary filmmaker wants to feature an athlete:

import { createEducationalLicense } from '@nil-taxonomy/sdk';
 
const documentaryLicense = createEducationalLicense()
  .setTerritoryGlobal() // Worldwide distribution
  .setTerm('2024-01-01', '2029-12-31') // 5-year film distribution
  .build();
 
console.log(documentaryLicense);
// {
//   subject_scope: ['name', 'image', 'likeness'],
//   use_type: ['editorial', 'educational'],
//   commercial_scope: 'non_commercial',
//   ...
// }

Example 3: Meme Campaign

A brand runs a UGC contest where fans create memes:

import { createUGCLicense } from '@nil-taxonomy/sdk';
 
const memeC ampaign = createUGCLicense()
  .setTerritoryGlobal()
  .setTerm('2024-06-01', '2024-08-31') // Summer campaign
  .setSublicensing('network_allowed') // Allow social sharing
  .setContentSafety({
    restricted_categories: ['adult', 'tobacco', 'alcohol', 'weapons', 'politics'],
    morals_clause: 'enhanced' // Strict moderation
  })
  .build();

⚠️

UGC campaigns require robust content moderation to protect the athlete's reputation. Enhanced morals clauses provide stronger protection.

Example 4: Category Exclusive Deal

An athlete signs as official brand ambassador for an athletic apparel company:

import { createExclusiveLicense } from '@nil-taxonomy/sdk';
 
const ambassadorDeal = createExclusiveLicense(['athletic_apparel'])
  .setTerritoryCountries(['US', 'CA', 'MX'])
  .setTerm('2024-01-01', '2027-12-31', true, 'annual') // 3yr, auto-renew
  .setDataUseLevel('identified_analytics_only', true) // Performance data
  .addCompetitorExclusion('Nike')
  .addCompetitorExclusion('Adidas')
  .addCompetitorExclusion('Under Armour')
  .setAISyntheticUse('synthetic_allowed_with_approval') // Digital avatar
  .build();

Example 5: Multi-Platform Campaign

Brand wants rights across all platforms:

import { createCommercialLicense } from '@nil-taxonomy/sdk';
 
const multiPlatform = createCommercialLicense()
  .setTerritoryGlobal()
  .setTerm('2024-01-01', '2025-12-31')
  .addRestrictedCategory('tobacco')
  .addRestrictedCategory('weapons')
  .setSublicensing('approved_partners') // Agencies, retailers
  .build();

Building from API Data

Fetch a base license and customize it:

import { NILTaxonomyClient, NILLicenseBuilder } from '@nil-taxonomy/sdk';
 
// Initialize client
const client = new NILTaxonomyClient({
  baseUrl: process.env.NIL_TAXONOMY_API_URL!,
  apiKey: process.env.NIL_TAXONOMY_API_KEY!,
});
 
// Fetch base license
const baseLicense = await client.getBaseLicense('NIL-COMM-STD', 'v1');
 
// Customize it
const customLicense = NILLicenseBuilder.fromBase(baseLicense)
  .setTerritoryCountries(['US']) // Override territory
  .addRestrictedCategory('alcohol') // Add restriction
  .setTerm('2024-01-01', '2024-06-30') // Shorter term
  .build();

Validation Examples

Basic Validation

import { validateLicense } from '@nil-taxonomy/sdk';
 
const result = validateLicense(myLicense);
 
if (!result.valid) {
  console.error('Validation failed:');
  result.errors?.forEach(err => {
    console.error(`- ${err.field}: ${err.message}`);
  });
  process.exit(1);
}
 
console.log('✓ License is valid');

Handling Warnings

const result = validateLicense(riskyLicense);
 
if (result.valid) {
  // Check for high-risk warnings
  const highRisk = result.warnings?.filter(w => w.severity === 'high');
  
  if (highRisk && highRisk.length > 0) {
    console.warn('⚠️ HIGH RISK LICENSE:');
    highRisk.forEach(w => console.warn(`- ${w.message}`));
    
    // Require manager approval for high-risk deals
    await requestApproval(myLicense, highRisk);
  }
}

Safe Building

Use tryBuild() instead of build() for graceful error handling:

const result = new NILLicenseBuilder()
  .setSubjectScope(['name', 'image'])
  .setUseType(['brand_marketing'])
  // ... more config
  .tryBuild();
 
if (!result.success) {
  // Handle errors without throwing
  return { success: false, errors: result.errors };
}
 
const license = result.license;

Integration Examples

Next.js API Route

// app/api/contracts/route.ts
import { createCommercialLicense, validateLicense } from '@nil-taxonomy/sdk';
import { NextResponse } from 'next/server';
 
export async function POST(request: Request) {
  const { athleteId, brandId, territory, term } = await request.json();
  
  // Build license
  const license = createCommercialLicense()
    .setTerritoryCountries(territory)
    .setTerm(term.start, term.end)
    .build();
  
  // Validate
  const validation = validateLicense(license);
  if (!validation.valid) {
    return NextResponse.json(
      { error: 'Invalid license', details: validation.errors },
      { status: 400 }
    );
  }
  
  // Save contract
  const contract = await saveContract({
    athleteId,
    brandId,
    license,
  });
  
  return NextResponse.json({ contract });
}

React Component

'use client'
 
import { useState } from 'react';
import { createCommercialLicense, validateLicense } from '@nil-taxonomy/sdk';
 
export function LicenseForm() {
  const [territory, setTerritory] = useState<string[]>(['US']);
  const [errors, setErrors] = useState<string[]>([]);
  
  const handleSubmit = () => {
    const license = createCommercialLicense()
      .setTerritoryCountries(territory)
      .setTerm('2024-01-01', '2025-12-31')
      .build();
    
    const result = validateLicense(license);
    
    if (!result.valid) {
      setErrors(result.errors?.map(e => e.message) || []);
      return;
    }
    
    saveLicense(license);
  };
  
  return (
    <form onSubmit={handleSubmit}>
      {/* Form fields */}
      {errors.length > 0 && (
        <div className="errors">
          {errors.map((err, i) => <p key={i}>{err}</p>)}
        </div>
      )}
    </form>
  );
}

Supabase Integration

import { createClient } from '@supabase/supabase-js';
import { createCommercialLicense } from '@nil-taxonomy/sdk';
 
const supabase = createClient(url, key);
 
// Save license configuration
async function saveLicense(athleteId: string, license: LicenseConfig) {
  const { data, error } = await supabase
    .from('nil_contracts')
    .insert({
      athlete_id: athleteId,
      license_config: license,
      taxonomy_version: 'v1.0',
      created_at: new Date().toISOString()
    })
    .select()
    .single();
  
  if (error) throw error;
  return data;
}
 
// Query by dimension
async function findCommercialContracts() {
  const { data } = await supabase
    .from('nil_contracts')
    .select('*')
    .eq('license_config->>commercial_scope', 'full_commercial');
  
  return data;
}

Next Steps

Authentication Troubleshooting