LinkedClaims TypeScript SDK

Official TypeScript SDK for LinkedClaims - create and manage verifiable trust claims.

Installation

npm install @cooperation/linked-claims
# or
yarn add @cooperation/linked-claims

Quick Start

import LinkedClaims from '@cooperation/linked-claims';

// Initialize client (defaults to production API)
const client = new LinkedClaims();

// Authenticate
await client.auth.login('[email protected]', 'password');

// Create a claim
const { claim } = await client.claims.create({
    subject: 'https://github.com/alice',
    claim: 'endorsement',
    statement: 'Alice is an excellent TypeScript developer',
    effectiveDate: '2024-01-15',
    howKnown: 'FIRST_HAND'
});

console.log(`Claim created: ${claim.id}`);

Drop-in Replacement

This SDK is designed as a drop-in replacement for existing LinkedTrust client libraries:

Migrating from trust-claim-client

// Old way
import { trustClaimClient } from './lib/trust-claim-client';
await trustClaimClient.createClaim({...});

// New way
import { linkedClaims } from '@cooperation/linked-claims';
await linkedClaims.createClaim({...}); // Same API!

Migrating from linkedtrust-client

// Old way
import { linkedTrustClient } from './lib/linkedtrust-client';

// New way  
import { linkedClaims } from '@cooperation/linked-claims';
// All the same methods are available

Authentication

Email/Password

const authResponse = await client.auth.login('[email protected]', 'password');
console.log(`Logged in as ${authResponse.user.email}`);

OAuth

// GitHub
const authResponse = await client.auth.githubAuth(code);

// Google
const authResponse = await client.auth.googleAuth(code);

// LinkedIn
const authResponse = await client.auth.linkedinAuth(code);

Creating Claims

Basic Claim

const { claim } = await client.claims.create({
    subject: 'https://example.org/project/123',
    claim: 'impact',
    statement: 'This project provided clean water to 500 families',
    effectiveDate: '2024-01-15',
    howKnown: 'FIRST_HAND'
});

With Evidence

const { claim } = await client.claims.create({
    subject: 'https://example.org/project/123',
    claim: 'impact',
    statement: 'Project impact documented in report',
    effectiveDate: '2024-01-15',
    howKnown: 'WEB_DOCUMENT',
    sourceURI: 'https://example.org/impact-report.pdf',
    confidence: 0.95
});

Rating Claim

const { claim } = await client.claims.create({
    subject: 'https://example.org/product/456',
    claim: 'rating',
    statement: 'Excellent product quality',
    aspect: 'quality',
    stars: 5,        // 1-5 stars
    score: 1.0,      // -1 to 1 normalized
    howKnown: 'FIRST_HAND'
});

Querying Claims

By Subject

const response = await client.claims.getBySubject(
    'https://github.com/alice',
    1,  // page
    50  // limit
);

console.log(`Found ${response.claims.length} claims`);

With Filters

const response = await client.claims.query({
    claim: 'endorsement',
    issuer_id: 'https://example.org/user/123',
    page: 1,
    limit: 20
});

Semantic Helpers

The SDK includes semantic helpers to guide users in creating valid claims:

Field Guidance

// Get help text for fields
const guidance = client.semantic.getFieldGuidance('subject', {
    domain: 'impact',
    claimType: 'impact'
});

console.log(guidance.help);
// "Enter the URL of the project, organization, or initiative that created impact"

Simplified How Known Options

// Get user-friendly options for howKnown field
const options = client.semantic.getSimplifiedHowKnown();
// Returns 3-4 simple options instead of 11 technical values

URI Building

// Build valid URIs
const uri = client.semantic.buildURI(
    'PERSON',
    'alice',
    'https://example.org'
);
// Returns: https://example.org/person/alice

Configuration

Custom API Endpoint

const client = new LinkedClaims({
    baseUrl: 'https://your-api.example.com'
});

Token Storage Options

const client = new LinkedClaims({
    auth: {
        storage: 'memory',  // 'localStorage' | 'memory' | 'none'
        autoRefresh: true
    }
});

Auth Error Handling

const client = new LinkedClaims({
    onAuthError: () => {
        // Redirect to login
        window.location.href = '/login';
    }
});

Environment Variables

The SDK respects these environment variables:

• NEXT_PUBLIC_TRUST_CLAIM_BACKEND_URL - API base URL (Next.js)
• REACT_APP_TRUST_CLAIM_BACKEND_URL - API base URL (Create React App)
• LINKEDTRUST_BASE_URL - API base URL (Node.js)
• NEXT_PUBLIC_GITHUB_CLIENT_ID - GitHub OAuth client ID
• NEXT_PUBLIC_LINKEDIN_CLIENT_ID - LinkedIn OAuth client ID

TypeScript Support

Full TypeScript support with exported types:

import type { 
    Claim, 
    CreateClaimInput,
    HowKnown,
    EntityType 
} from '@cooperation/linked-claims';

License

MIT - See LICENSE file in the repository