@explorins/pers-signer 1.0.5

package/README.md

@@ -0,0 +1,124 @@
+# @explorins/pers-signer SDK
+
+A lightweight SDK for blockchain transaction signing with PERS integration. Uses existing services and environment-based configuration.
+
+## Installation
+
+```bash
+npm install @explorins/pers-signer
+```
+
+## Quick Start
+
+The SDK uses environment variables for configuration, so no complex setup is needed:
+
+```typescript
+import { PersSignerSDK } from '@explorins/pers-signer';
+
+// Simple initialization - uses environment config
+const sdk = new PersSignerSDK();
+
+// Authenticate user
+const user = await sdk.authenticateUser('user@example.com');
+
+// Sign PERS transaction
+const result = await sdk.signPersTransaction(user, 'transaction-123');
+
+if (result.success) {
+  console.log('Transaction hash:', result.transactionHash);
+}
+```
+
+## Environment Variables
+
+The SDK automatically uses these environment variables from your `.env` file:
+
+- `VITE_EXPRESS_API_URL` - Signer backend API URL
+- `VITE_PERS_API_URL` - PERS API URL  
+- `VITE_PASSKEY_RELYING_PARTY_*` - WebAuthn configuration
+- `VITE_ETHERS_PROVIDER` - Blockchain provider URL
+
+## Configuration
+
+Optional configuration can be provided:
+
+```typescript
+import { PersSignerSDK, PersSignerConfig } from '@explorins/pers-signer';
+
+const config: PersSignerConfig = {
+  tenantId: 'my-tenant',                    // Multi-tenant identifier
+  ethersProviderUrl: 'https://my-rpc.com'  // Custom blockchain provider
+};
+
+const sdk = new PersSignerSDK(config);
+```
+
+## API Reference
+
+### High-Level Methods
+
+#### `authenticateUser(identifier: string): Promise<SignerUser>`
+
+Complete user onboarding flow - handles registration or login automatically.
+
+#### `signPersTransaction(user: SignerUser, transactionId: string): Promise<SigningResult>`
+
+Complete PERS transaction signing flow - same as the web project.
+
+### Granular Methods (For Custom Integrations)
+
+#### `registerUser(identifier: string): Promise<{authToken: string}>`
+#### `loginUser(identifier: string): Promise<string>`
+#### `addWalletToPersUser(signerAuthToken: string): Promise<string>`
+#### `retrieveTransactionData(transactionId: string, persAccessToken: string): Promise<any>`
+#### `signTransactionData(signerAuthToken: string, transactionData: any): Promise<string>`
+#### `submitTransaction(transactionId: string, signature: string, persAccessToken: string): Promise<{transactionHash?: string; success: boolean}>`
+
+### Utility Methods
+
+#### `checkUserExists(identifier: string): Promise<boolean>`
+#### `getUserWallets(signerAuthToken: string): Promise<any>`
+#### `getTransactionStatus(transactionId: string, persAccessToken: string): Promise<{status: string; transactionHash?: string}>`
+
+## Examples
+
+See `/examples/basic-usage.ts` for comprehensive examples including:
+
+- Gaming platform integration
+- E-commerce loyalty transactions
+- Batch operations
+- Custom blockchain providers
+- Environment-based configuration
+
+## Types
+
+```typescript
+interface PersSignerConfig {
+  tenantId?: string;
+  ethersProviderUrl?: string;
+}
+
+interface SignerUser {
+  identifier: string;
+  signerAuthToken?: string;
+  persAccessToken?: string;
+}
+
+interface SigningResult {
+  success: boolean;
+  transactionHash?: string;
+  error?: string;
+}
+```
+
+## Architecture
+
+This SDK is a simple orchestrator that uses existing services:
+
+- **AuthenticationService** - WebAuthn authentication
+- **WalletService** - Wallet management  
+- **SigningService** - Transaction signing
+- **PersService** - PERS integration
+- **TransactionSigningService** - High-level transaction flow
+
+No complex initialization or platform providers needed - everything is pre-configured.