@shukashake/ai-sdk

Shuka AI SDK

The official SDK for integrating AI assistants with Shuka's brand verification and trust attestation platform.

Installation

npm install @shukashake/ai-sdk

Or include via CDN:

<script src="https://cdn.shuka.app/sdk/shuka-ai-sdk.min.js"></script>

Quick Start

const { ShukaIntegration } = require('@shukashake/ai-sdk');

// Initialize with your API key (REQUIRED)
const shuka = new ShukaIntegration({
  apiKey: 'shk_your_api_key_here'  // Get your key at shuka.app/partner/sdk
});

// Verify brand usage before generating content
const result = await shuka.verifyBrandUsage("Create an ad featuring Nike shoes");

if (result.authorized) {
  console.log("Authorized! Handshake ID:", result.handshakeId);
  // Proceed with content generation
} else {
  console.log("Not authorized:", result.message);
  console.log("Alternatives:", result.alternatives);
}

Authentication

All SDK requests require a valid API key.

Getting an API Key

• Log in at shuka.app
• Navigate to Partner Dashboard > SDK
• Click Create API Key
• Copy your key (starts with shk_)

API Key Best Practices

• Never expose your API key in client-side code for production apps
• Use environment variables: process.env.SHUKA_API_KEY
• Rotate keys if compromised
• Use separate keys for development and production

Configuration Options

const shuka = new ShukaIntegration({
  // REQUIRED
  apiKey: 'shk_your_api_key',

  // OPTIONAL
  apiBase: 'https://api.shuka.app',  // Custom API endpoint
  agentName: 'my-ai-assistant',       // Your agent's name
  timeout: 5000,                      // Request timeout (ms)
  retries: 2                          // Retry attempts
});

API Reference

verifyBrandUsage(prompt, userContext?)

Main verification method. Call before generating brand-related content.

Parameters:

• prompt (string): The user's prompt to analyze
• userContext (object, optional): Additional context
  • shukaFingerprint: User's Shuka fingerprint
  • teamId: Team ID for enterprise users

Returns: Promise resolving to:

{
  status: 'authorized' | 'unauthorized' | 'no_verification_needed' | 'error',
  authorized: boolean,
  message: string,
  handshakeId?: string,       // Unique attestation ID
  proofToken?: string,        // Compact proof token
  trustScore?: number,        // 0-1 trust score
  missingLicenses?: string[], // Brands requiring licenses
  alternatives?: string[],    // Suggested alternatives
  analysis: {
    detectedBrands: string[],
    commercialIntent: boolean,
    riskLevel: 'low' | 'medium' | 'high'
  }
}

analyzePrompt(prompt)

Analyze a prompt for brand mentions without making API calls.

const analysis = shuka.analyzePrompt("Design a Gucci-inspired handbag");
// {
//   detectedBrands: ['Gucci'],
//   commercialIntent: true,
//   styleReferences: ['inspired by'],
//   riskLevel: 'high',
//   requiresVerification: true
// }

getPricing()

Get current SDK pricing information.

const pricing = await shuka.getPricing();
// {
//   operation_costs: {
//     'attestation_create': 0.60,
//     'handshake_initiate': 0.60
//   },
//   free_tier: { monthly_limit: 10 }
// }

getUsageStats()

Get your API usage statistics.

const stats = await shuka.getUsageStats();
// {
//   usage_today: 45,
//   usage_this_month: 1234,
//   remaining_credits: 500.00
// }

Agent-Specific Integrations

Claude Integration

const { ClaudeIntegration } = require('@shukashake/ai-sdk');

const shuka = new ClaudeIntegration({
  apiKey: 'shk_your_api_key'
});

// Optimized for Claude tool calling
const result = await shuka.verifyBrandsForClaude(
  "Create a Marvel superhero",
  userFingerprint
);

// Returns Claude-formatted response:
// {
//   verification_result: 'AUTHORIZED' | 'UNAUTHORIZED',
//   message: string,
//   action: string,
//   handshake_id?: string,
//   proof_token?: string
// }

ChatGPT Integration

const { ChatGPTIntegration } = require('@shukashake/ai-sdk');

const shuka = new ChatGPTIntegration({
  apiKey: 'shk_your_api_key'
});

// Optimized for GPT function calling
const result = await shuka.verifyBrandsForGPT(
  "Design an Apple-style product",
  userFingerprint,
  true  // commercialIntent
);

Middleware Pattern

const { createShukaMiddleware } = require('@shukashake/ai-sdk');

const verifyBrands = createShukaMiddleware({
  apiKey: 'shk_your_api_key'
});

// Use in your AI pipeline
async function processPrompt(prompt) {
  const verification = await verifyBrands(prompt);

  if (!verification.shouldProceed) {
    return {
      error: verification.response,
      alternatives: verification.alternatives
    };
  }

  // Proceed with AI generation
  return generateContent(prompt);
}

Error Handling

const { ShukaSDKError } = require('@shukashake/ai-sdk');

try {
  const result = await shuka.verifyBrandUsage(prompt);
} catch (error) {
  if (error instanceof ShukaSDKError) {
    switch (error.code) {
      case 'MISSING_API_KEY':
        console.error('API key not provided');
        break;
      case 'INVALID_API_KEY':
        console.error('API key is invalid or expired');
        break;
      case 'PAYMENT_REQUIRED':
        console.error('Add credits at shuka.app/partner/billing');
        console.error('Details:', error.details);
        break;
      case 'RATE_LIMITED':
        console.error('Rate limit exceeded, retry after:', error.details.retry_after_seconds);
        break;
    }
  }
}

Error Codes

Code	HTTP Status	Description
MISSING_API_KEY	-	API key not provided in config
INVALID_API_KEY	401	API key is invalid or expired
PAYMENT_REQUIRED	402	Insufficient credits - add more at billing portal
RATE_LIMITED	429	Too many requests - slow down or upgrade
VERIFICATION_FAILED	500	Verification service error

Rate Limits

Authenticated Requests (with API key)

Rate limits depend on your subscription tier:

• Free Tier: 10 handshakes/month
• Partner: 1,000 handshakes/month
• Enterprise: Unlimited

Free/Demo Requests (without API key)

Demo requests from shuka.app are rate-limited:

• 10 requests/minute per IP
• 50 requests/hour per IP
• 200 requests/day per IP

Pricing

Operation	Cost
Attestation/Handshake	$0.60
Verification	$0.10
Proof Token	$0.05

Add credits at shuka.app/partner/billing

Migration from v1.x

Version 2.0 requires authentication. Update your code:

// v1.x (DEPRECATED - no longer works)
const shuka = new ShukaIntegration();

// v2.x (REQUIRED)
const shuka = new ShukaIntegration({
  apiKey: 'shk_your_api_key'  // Required
});

The SDK now sends X-SDK-API-Key header with all requests. Requests without a valid API key will receive a 401 error.

Support

• Documentation: docs.shuka.app/sdk
• API Status: status.shuka.app
• Email: [e-mail]
• Issues: github.com/auron-tech/shuka-sdk/issues

License

MIT License - see LICENSE file for details.

Shuka - The Universal Trust Guardian for the AI Economy

Get your API key at shuka.app/partner/sdk