npm package: @shukashake/ai-sdk
Description: Official SDK for integrating AI assistants with Shuka's brand verification and trust attestation platform
Author: Auron Technologies
Latest version: 2.0.0
Deprecated: Consolidated into @shukashake/agent. Install @shukashake/agent instead.

# Shuka AI SDK

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

## Installation

```bash
npm install @shukashake/ai-sdk
```

Or include via CDN:
```html
<script src="https://cdn.shuka.app/sdk/shuka-ai-sdk.min.js"></script>
```

## Quick Start

```javascript
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

1. Log in at [shuka.app](https://shuka.app)
2. Navigate to **Partner Dashboard** > **SDK**
3. Click **Create API Key**
4. 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

```javascript
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:
```javascript
{
  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.

```javascript
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.

```javascript
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.

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

## Agent-Specific Integrations

### Claude Integration

```javascript
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

```javascript
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

```javascript
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

```javascript
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](https://shuka.app/partner/billing)

## Migration from v1.x

Version 2.0 requires authentication. Update your code:

```javascript
// 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](https://docs.shuka.app/sdk)
- API Status: [status.shuka.app](https://status.shuka.app)
- Email: sdk-support@shuka.app
- Issues: [github.com/auron-tech/shuka-sdk/issues](https://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](https://shuka.app/partner/sdk)