@osiris-ai/turnkey-sdk/README.md

Osiris Turnkey SDK

# @osiris-ai/turnkey-sdk

A minimal TypeScript SDK for interacting with the Turnkey API to create, manage, and sign with crypto wallets using API key authentication.

## Features

- 🔐 **Secure API Key Authentication** - Uses Turnkey's API key stamper for request signing
- 🏦 **Wallet Management** - Create wallets, list wallets, and manage wallet accounts
- ✍️ **Transaction Signing** - Sign raw payloads, multiple payloads, and transactions
- 📝 **Full TypeScript Support** - Comprehensive type definitions for all API interactions
- 🚀 **Lightweight** - Minimal dependencies with tree-shakeable exports

## Installation

```bash
npm install @osiris-ai/turnkey-sdk
```

## Quick Start

```typescript
import { TurnkeySDK } from '@osiris-ai/turnkey-sdk';

const sdk = new TurnkeySDK({
  organizationId: 'your-organization-id',
  apiPublicKey: 'your-api-public-key',
  apiPrivateKey: 'your-api-private-key',
  baseUrl: 'https://api.turnkey.com'
});

// List wallets
const wallets = await sdk.listWallets({
  organizationId: 'your-organization-id'
});

// Sign a raw payload
const signature = await sdk.signRawPayload({
  type: 'ACTIVITY_TYPE_SIGN_RAW_PAYLOAD_V2',
  timestampMs: Date.now().toString(),
  organizationId: 'your-organization-id',
  parameters: {
    signWith: 'your-private-key-id',
    payload: 'your-hex-payload',
    encoding: 'PAYLOAD_ENCODING_HEXADECIMAL',
    hashFunction: 'HASH_FUNCTION_KECCAK256'
  }
});
```

## API Reference

### Configuration

```typescript
interface TurnkeyConfig {
  organizationId: string;    // Your Turnkey organization ID
  apiPublicKey: string;      // Your API public key
  apiPrivateKey: string;     // Your API private key
  baseUrl: string;           // Turnkey API base URL
}
```

### Wallet Management

#### `listWallets(request: ListWalletsRequest): Promise<ListWalletsResponse>`

Lists all wallets in an organization.

```typescript
const wallets = await sdk.listWallets({
  organizationId: 'your-organization-id'
});
```

#### `listWalletAccounts(request: ListWalletAccountsRequest): Promise<ListWalletAccountsResponse>`

Lists all accounts in a specific wallet.

```typescript
const accounts = await sdk.listWalletAccounts({
  organizationId: 'your-organization-id',
  walletId: 'your-wallet-id',
  paginationOptions: {
    limit: '10',
    before: '',
    after: ''
  }
});
```

#### `createWallet(request: CreateWalletRequest): Promise<CreateWalletResponse>`

Creates a new wallet (sub-organization) with specified accounts.

```typescript
const wallet = await sdk.createWallet({
  subOrganizationName: 'my-wallet',
  rootUsers: [{
    userName: 'wallet-admin',
    apiKeys: [{
      apiKeyName: 'admin-key',
      publicKey: 'your-public-key',
      curveType: 'API_KEY_CURVE_P256'
    }],
    authenticators: [],
    oauthProviders: []
  }],
  rootQuorumThreshold: 1,
  wallet: {
    walletName: 'my-wallet',
    accounts: [{
      pathFormat: 'PATH_FORMAT_BIP32',
      path: "m/44'/60'/0'/0/0",
      curve: 'CURVE_SECP256K1',
      addressFormat: 'ADDRESS_FORMAT_ETHEREUM'
    }],
    mnemonicLength: 12
  }
});
```

#### `addWalletAccount(request: AddWalletAccountsRequest): Promise<AddWalletAccountsResponse>`

Adds new accounts to an existing wallet.

```typescript
const result = await sdk.addWalletAccount({
  type: 'ACTIVITY_TYPE_CREATE_WALLET_ACCOUNTS',
  timestampMs: Date.now().toString(),
  organizationId: 'your-organization-id',
  parameters: {
    walletId: 'your-wallet-id',
    accounts: [{
      curve: 'CURVE_SECP256K1',
      pathFormat: 'PATH_FORMAT_BIP32',
      path: "m/44'/60'/0'/0/1",
      addressFormat: 'ADDRESS_FORMAT_ETHEREUM'
    }]
  }
});
```

### Signing Operations

#### `signRawPayload(request: SignRawPayloadRequest): Promise<SignRawPayloadResponse>`

Signs a single raw payload.

```typescript
const signature = await sdk.signRawPayload({
  type: 'ACTIVITY_TYPE_SIGN_RAW_PAYLOAD_V2',
  timestampMs: Date.now().toString(),
  organizationId: 'your-organization-id',
  parameters: {
    signWith: 'your-private-key-id',
    payload: '0x1234567890abcdef',
    encoding: 'PAYLOAD_ENCODING_HEXADECIMAL',
    hashFunction: 'HASH_FUNCTION_KECCAK256'
  }
});
```

#### `signRawPayloads(request: SignRawPayloadsRequest): Promise<SignRawPayloadsResponse>`

Signs multiple raw payloads in a single request.

```typescript
const signatures = await sdk.signRawPayloads({
  type: 'ACTIVITY_TYPE_SIGN_RAW_PAYLOADS',
  timestampMs: Date.now().toString(),
  organizationId: 'your-organization-id',
  parameters: {
    signWith: 'your-private-key-id',
    payloads: ['0x1234567890abcdef', '0xfedcba0987654321'],
    encoding: 'PAYLOAD_ENCODING_HEXADECIMAL',
    hashFunction: 'HASH_FUNCTION_KECCAK256'
  }
});
```

#### `signTransaction(request: SignTransactionRequest): Promise<SignTransactionResponse>`

Signs a transaction.

```typescript
const signedTx = await sdk.signTransaction({
  type: 'ACTIVITY_TYPE_SIGN_TRANSACTION_V2',
  timestampMs: Date.now().toString(),
  organizationId: 'your-organization-id',
  parameters: {
    signWith: 'your-private-key-id',
    unsignedTransaction: '0x...',
    type: 'TRANSACTION_TYPE_ETHEREUM'
  }
});
```

## Error Handling

The SDK includes built-in error handling for common scenarios:

```typescript
try {
  const result = await sdk.signRawPayloads(request);
} catch (error) {
  console.error('Signing failed:', error.message);
}
```

## Requirements

- Node.js 18.0.0 or higher
- TypeScript 5.0 or higher (for development)

## Peer Dependencies

- `@noble/curves` ^1.9.2 (optional) - For cryptographic operations
- `viem` ^2.30.1 (optional) - For Ethereum utilities

## License

MIT

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Support

For issues and questions, please open an issue on the GitHub repository.