206 lines
4.4 KiB
Markdown
206 lines
4.4 KiB
Markdown
# SDK Signer Client
|
|
|
|
A TypeScript client library for connecting to the SDK Signer WebSocket API. This package provides a clean, type-safe interface for communicating with the SDK Signer server.
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
npm install sdk-signer-client
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
```typescript
|
|
import { SDKSignerClient, MessageType } from 'sdk-signer-client';
|
|
|
|
// Create client instance
|
|
const client = new SDKSignerClient({
|
|
url: 'ws://localhost:9090',
|
|
apiKey: 'your-api-key'
|
|
});
|
|
|
|
// Connect to server
|
|
await client.connect();
|
|
|
|
// Wait for server to send LISTENING message
|
|
const response = await client.waitForListening();
|
|
console.log('Server response:', response);
|
|
|
|
// Disconnect when done
|
|
client.disconnect();
|
|
```
|
|
|
|
## Configuration
|
|
|
|
```typescript
|
|
import { ClientConfig } from 'sdk-signer-client';
|
|
|
|
const config: ClientConfig = {
|
|
url: 'ws://localhost:9090', // WebSocket server URL
|
|
apiKey: 'your-api-key', // API key for authentication
|
|
timeout: 5000, // Connection timeout (ms)
|
|
reconnectInterval: 3000, // Reconnection delay (ms)
|
|
maxReconnectAttempts: 5 // Max reconnection attempts
|
|
};
|
|
```
|
|
|
|
## API Reference
|
|
|
|
### Constructor
|
|
|
|
```typescript
|
|
new SDKSignerClient(config: ClientConfig)
|
|
```
|
|
|
|
Creates a new client instance with the specified configuration.
|
|
|
|
### Connection Methods
|
|
|
|
#### `connect(options?: ConnectionOptions): Promise<void>`
|
|
|
|
Establishes a WebSocket connection to the server.
|
|
|
|
```typescript
|
|
await client.connect({
|
|
timeout: 10000,
|
|
headers: { 'Custom-Header': 'value' }
|
|
});
|
|
```
|
|
|
|
#### `disconnect(): void`
|
|
|
|
Closes the WebSocket connection and stops reconnection attempts.
|
|
|
|
#### `isConnectedToServer(): boolean`
|
|
|
|
Returns `true` if the client is connected to the server.
|
|
|
|
### Message Methods
|
|
|
|
#### `send(message: ClientMessage): void`
|
|
|
|
Sends a message to the server.
|
|
|
|
```typescript
|
|
client.send({
|
|
type: MessageType.LISTENING,
|
|
messageId: 'unique-id'
|
|
});
|
|
```
|
|
|
|
#### `sendAndWait(message: ClientMessage, expectedType: MessageType, timeout?: number): Promise<ServerResponse>`
|
|
|
|
Sends a message and waits for a specific response type.
|
|
|
|
```typescript
|
|
const response = await client.sendAndWait(
|
|
{ type: MessageType.NOTIFY_UPDATE, processId: '123', stateId: '456' },
|
|
MessageType.UPDATE_NOTIFIED,
|
|
10000
|
|
);
|
|
```
|
|
|
|
### Convenience Methods
|
|
|
|
#### `listen(): Promise<ServerResponse>`
|
|
|
|
Sends a listening message to establish connection.
|
|
|
|
#### `notifyUpdate(processId: string, stateId: string): Promise<ServerResponse>`
|
|
|
|
Notifies an update for a process.
|
|
|
|
#### `validateState(processId: string, stateId: string): Promise<ServerResponse>`
|
|
|
|
Validates a state.
|
|
|
|
#### `updateProcess(processId: string, stateId: string, data: any): Promise<ServerResponse>`
|
|
|
|
Updates a process with additional data.
|
|
|
|
### Event Handling
|
|
|
|
```typescript
|
|
// Connection events
|
|
client.on('open', () => console.log('Connected!'));
|
|
client.on('close', () => console.log('Disconnected!'));
|
|
client.on('error', (error) => console.error('Error:', error));
|
|
client.on('reconnect', () => console.log('Reconnected!'));
|
|
|
|
// Message events
|
|
client.on('message', (response) => console.log('Received:', response));
|
|
|
|
// Remove event handlers
|
|
client.off('open');
|
|
```
|
|
|
|
## Message Types
|
|
|
|
The client supports all message types defined by the server:
|
|
|
|
- `LISTENING` - Establish connection
|
|
- `NOTIFY_UPDATE` - Notify process update
|
|
- `VALIDATE_STATE` - Validate process state
|
|
- `UPDATE_PROCESS` - Update process data
|
|
- `ERROR` - Error responses
|
|
- And many more...
|
|
|
|
## Error Handling
|
|
|
|
```typescript
|
|
try {
|
|
await client.connect();
|
|
const response = await client.notifyUpdate('process-123', 'state-456');
|
|
console.log('Success:', response);
|
|
} catch (error) {
|
|
console.error('Error:', error.message);
|
|
}
|
|
|
|
// Or use event handlers
|
|
client.on('error', (error) => {
|
|
console.error('Connection error:', error);
|
|
});
|
|
```
|
|
|
|
## Reconnection
|
|
|
|
The client automatically attempts to reconnect when the connection is lost:
|
|
|
|
- Exponential backoff with configurable intervals
|
|
- Configurable maximum reconnection attempts
|
|
- Automatic cleanup on manual disconnect
|
|
|
|
## Testing
|
|
|
|
```bash
|
|
# Run tests
|
|
npm test
|
|
|
|
# Run tests in watch mode
|
|
npm run test:watch
|
|
|
|
# Build the package
|
|
npm run build
|
|
```
|
|
|
|
## Development
|
|
|
|
```bash
|
|
# Install dependencies
|
|
npm install
|
|
|
|
# Start development mode
|
|
npm run dev
|
|
|
|
# Clean build artifacts
|
|
npm run clean
|
|
```
|
|
|
|
## TypeScript Support
|
|
|
|
This package is written in TypeScript and includes full type definitions. All interfaces and types are exported for use in your own TypeScript projects.
|
|
|
|
## License
|
|
|
|
MIT
|