npm package: @orzattyholding/account-sdk
Description: TypeScript SDK for OrzattyAccount integration
Author: Orzatty Holdings
Latest version: 1.0.1

# OrzattyAccount TypeScript SDK

A comprehensive TypeScript SDK for integrating with the OrzattyAccount authentication system.

## Installation

```bash
npm install @orzattyholding/account-sdk
```

## Quick Start

```typescript
import { OrzattyAccountClient, OAuthClient } from '@orzattyholding/account-sdk';

// Initialize the client
const client = new OrzattyAccountClient({
  baseUrl: 'https://account.orzatty.com',
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret', // Optional for public clients
});

// Get current user
const user = await client.getCurrentUser();
console.log(user);
```

## OAuth Flow

```typescript
import { OAuthClient } from '@orzattyholding/account-sdk';

const oauth = new OAuthClient({
  baseUrl: 'https://account.orzatty.com',
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
});

// Generate PKCE for security
const pkce = oauth.generatePKCE();

// Get authorization URL
const authUrl = oauth.getAuthorizationUrl({
  clientId: 'your-client-id',
  redirectUri: 'https://yourapp.com/callback',
  scope: ['openid', 'profile', 'email'],
  state: 'random-state',
  codeChallenge: pkce.codeChallenge,
  codeChallengeMethod: pkce.codeChallengeMethod,
});

// Exchange code for tokens
const tokens = await oauth.exchangeCodeForToken({
  code: 'authorization-code',
  redirectUri: 'https://yourapp.com/callback',
  codeVerifier: pkce.codeVerifier,
});

// Set tokens on main client
client.setTokens(tokens);
```

## Webhooks

```typescript
import { WebhookClient } from '@orzattyholding/account-sdk';

const webhooks = new WebhookClient({
  baseUrl: 'https://account.orzatty.com',
  clientId: 'your-client-id',
  apiKey: 'your-api-key',
});

// Register a webhook
const webhook = await webhooks.registerWebhook({
  serviceId: 'your-service-id',
  url: 'https://yourapp.com/webhooks',
  events: ['user.created', 'user.updated'],
  secret: 'webhook-secret',
});

// Verify webhook signature
const isValid = WebhookClient.verifySignature(
  payload,
  signature,
  'webhook-secret'
);
```

## Service Registry

```typescript
import { ServiceRegistryClient } from '@orzattyholding/account-sdk';

const registry = new ServiceRegistryClient({
  baseUrl: 'https://account.orzatty.com',
  clientId: 'your-client-id',
  apiKey: 'your-api-key',
});

// Register your service
const service = await registry.registerService({
  name: 'my-service',
  type: 'web-app',
  version: '1.0.0',
  baseUrl: 'https://myservice.com',
  healthEndpoint: '/health',
  description: 'My awesome service',
});

// Get service health
const health = await registry.getServiceHealth(service.id);
```

## Error Handling

```typescript
import { 
  AuthenticationError, 
  ValidationError, 
  RateLimitError 
} from '@orzattyholding/account-sdk';

try {
  const user = await client.getCurrentUser();
} catch (error) {
  if (error instanceof AuthenticationError) {
    // Handle authentication error
    console.log('Please log in');
  } else if (error instanceof ValidationError) {
    // Handle validation error
    console.log('Invalid data:', error.details);
  } else if (error instanceof RateLimitError) {
    // Handle rate limit
    console.log('Rate limited, retry after:', error.retryAfter);
  }
}
```

## Configuration

```typescript
interface SDKConfig {
  baseUrl: string;
  clientId: string;
  clientSecret?: string; // Required for confidential clients
  apiKey?: string; // Alternative to client secret
  timeout?: number; // Request timeout in milliseconds
  retries?: number; // Number of retry attempts
  userAgent?: string; // Custom user agent
}
```

## API Reference

### OrzattyAccountClient

- `getCurrentUser()` - Get current user profile
- `updateUserProfile(updates)` - Update user profile
- `getUserSessions()` - Get user sessions
- `revokeSession(sessionId)` - Revoke a session
- `getUserOrganizations()` - Get user's organizations
- `getOrganization(id)` - Get organization details
- `createOrganization(data)` - Create new organization
- `updateOrganization(id, updates)` - Update organization
- `getPrivacySettings()` - Get privacy settings
- `updatePrivacySettings(service, settings)` - Update privacy settings
- `enableTwoFactor()` - Enable 2FA
- `verifyTwoFactor(token)` - Verify 2FA setup
- `disableTwoFactor(token)` - Disable 2FA

### OAuthClient

- `generatePKCE()` - Generate PKCE challenge
- `getAuthorizationUrl(request)` - Get authorization URL
- `exchangeCodeForToken(request)` - Exchange code for tokens
- `refreshToken(refreshToken)` - Refresh access token
- `revokeToken(token)` - Revoke token
- `getUserInfo(accessToken)` - Get user info
- `getDiscoveryDocument()` - Get OIDC discovery document
- `getJWKS()` - Get JSON Web Key Set

### WebhookClient

- `registerWebhook(request)` - Register webhook
- `getWebhook(id)` - Get webhook details
- `updateWebhook(id, updates)` - Update webhook
- `deleteWebhook(id)` - Delete webhook
- `publishEvent(event)` - Publish event
- `getDeliveryHistory(webhookId)` - Get delivery history
- `retryDelivery(deliveryId)` - Retry failed delivery
- `testWebhook(webhookId)` - Test webhook endpoint

### ServiceRegistryClient

- `registerService(request)` - Register service
- `getService(id)` - Get service details
- `getAllServices()` - Get all services
- `updateService(id, updates)` - Update service
- `deleteService(id)` - Delete service
- `getServiceHealth(id)` - Get service health
- `triggerHealthCheck(id)` - Trigger health check

## License

MIT