@partylayer/sdk 0.2.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 CantonConnect
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,282 @@
+# @partylayer/sdk
+
+<div align="center">
+
+**The official SDK for connecting dApps to Canton Network wallets**
+
+[![npm version](https://img.shields.io/npm/v/@partylayer/sdk.svg?style=flat-square)](https://www.npmjs.com/package/@partylayer/sdk)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg?style=flat-square)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+
+</div>
+
+---
+
+## Overview
+
+`@partylayer/sdk` provides a unified interface for connecting your decentralized application (dApp) to multiple Canton Network wallets. Similar to WalletConnect, it abstracts wallet-specific implementations behind a simple, type-safe API.
+
+### Features
+
+- **Multi-Wallet Support**: Console, 5N Loop, Cantor8, and Bron wallets
+- **Zero Configuration**: Works out of the box with sensible defaults
+- **Type-Safe**: Full TypeScript support with strict mode
+- **Secure**: Encrypted session storage with origin binding
+- **Event-Driven**: Subscribe to connection, transaction, and error events
+
+---
+
+## Installation
+
+```bash
+npm install @partylayer/sdk
+```
+
+For React applications, also install the React integration:
+
+```bash
+npm install @partylayer/sdk @partylayer/react
+```
+
+---
+
+## Quick Start
+
+### 1. Create a Client
+
+```typescript
+import { createPartyLayer } from '@partylayer/sdk';
+
+const client = createPartyLayer({
+  network: 'devnet',
+  app: { name: 'My dApp' },
+});
+```
+
+### 2. Connect to a Wallet
+
+```typescript
+// List available wallets
+const wallets = await client.listWallets();
+console.log('Available wallets:', wallets.map(w => w.name));
+
+// Connect to a specific wallet
+const session = await client.connect({ walletId: 'console' });
+console.log('Connected! Party ID:', session.partyId);
+```
+
+### 3. Sign Messages & Transactions
+
+```typescript
+// Sign a message
+const { signature } = await client.signMessage({
+  message: 'Authorize login to My dApp',
+});
+
+// Sign a transaction
+const { signedTx, transactionHash } = await client.signTransaction({
+  tx: myTransaction,
+});
+
+// Submit a transaction
+const receipt = await client.submitTransaction({
+  signedTx,
+});
+```
+
+### 4. Listen to Events
+
+```typescript
+// Connection events
+client.on('session:connected', (event) => {
+  console.log('Connected:', event.session.partyId);
+});
+
+client.on('session:disconnected', () => {
+  console.log('Disconnected');
+});
+
+// Transaction events
+client.on('tx:status', (event) => {
+  console.log('Transaction status:', event.status);
+});
+
+// Error events
+client.on('error', (event) => {
+  console.error('Error:', event.error.message);
+});
+```
+
+### 5. Disconnect
+
+```typescript
+await client.disconnect();
+```
+
+---
+
+## Supported Wallets
+
+| Wallet | ID | Type | Auto-Registered |
+|--------|-----|------|-----------------|
+| Console Wallet | `console` | Browser Extension | ✅ Yes |
+| 5N Loop | `loop` | Mobile / Web | ✅ Yes |
+| Cantor8 | `cantor8` | Browser Extension | ✅ Yes |
+| Bron | `bron` | Enterprise (OAuth) | ⚙️ Requires config |
+
+---
+
+## Configuration
+
+```typescript
+const client = createPartyLayer({
+  // Required
+  network: 'devnet', // 'devnet' | 'testnet' | 'mainnet'
+  app: {
+    name: 'My dApp',
+    origin: 'https://mydapp.com', // Optional, defaults to window.location.origin
+  },
+
+  // Optional
+  registryUrl: 'https://registry.cantonconnect.xyz/v1/wallets.json', // Default
+  channel: 'stable', // 'stable' | 'beta'
+  
+  // Advanced: Custom adapters
+  adapters: [
+    ...getBuiltinAdapters(),
+    new BronAdapter({ auth: {...}, api: {...} }),
+  ],
+});
+```
+
+---
+
+## API Reference
+
+### `createPartyLayer(config)`
+
+Creates a new PartyLayer client instance.
+
+### Client Methods
+
+| Method | Description | Returns |
+|--------|-------------|---------|
+| `listWallets(filter?)` | List available wallets | `Promise<WalletInfo[]>` |
+| `connect(options?)` | Connect to a wallet | `Promise<Session>` |
+| `disconnect()` | Disconnect current session | `Promise<void>` |
+| `getActiveSession()` | Get active session | `Promise<Session \| null>` |
+| `signMessage(params)` | Sign an arbitrary message | `Promise<SignedMessage>` |
+| `signTransaction(params)` | Sign a transaction | `Promise<SignedTransaction>` |
+| `submitTransaction(params)` | Submit signed transaction | `Promise<TxReceipt>` |
+| `on(event, handler)` | Subscribe to events | `() => void` (unsubscribe) |
+| `off(event, handler)` | Unsubscribe from events | `void` |
+| `destroy()` | Cleanup client resources | `void` |
+
+### Events
+
+| Event | Description |
+|-------|-------------|
+| `session:connected` | Wallet connected successfully |
+| `session:disconnected` | Wallet disconnected |
+| `session:expired` | Session has expired |
+| `tx:status` | Transaction status update |
+| `registry:status` | Registry status change |
+| `error` | Error occurred |
+
+---
+
+## Error Handling
+
+```typescript
+import {
+  WalletNotFoundError,
+  WalletNotInstalledError,
+  UserRejectedError,
+  SessionExpiredError,
+  TimeoutError,
+} from '@partylayer/sdk';
+
+try {
+  await client.connect({ walletId: 'console' });
+} catch (error) {
+  if (error instanceof WalletNotInstalledError) {
+    console.log('Please install the wallet extension');
+  } else if (error instanceof UserRejectedError) {
+    console.log('User rejected the connection request');
+  } else if (error instanceof TimeoutError) {
+    console.log('Connection timed out');
+  }
+}
+```
+
+---
+
+## Using Bron (Enterprise Wallet)
+
+Bron requires OAuth2 configuration:
+
+```typescript
+import { createPartyLayer, BronAdapter, getBuiltinAdapters } from '@partylayer/sdk';
+
+const client = createPartyLayer({
+  network: 'devnet',
+  app: { name: 'My dApp' },
+  adapters: [
+    ...getBuiltinAdapters(),
+    new BronAdapter({
+      auth: {
+        clientId: 'your-client-id',
+        redirectUri: 'https://your-app.com/auth/callback',
+        authorizationUrl: 'https://auth.bron.example/authorize',
+        tokenUrl: 'https://auth.bron.example/token',
+      },
+      api: {
+        baseUrl: 'https://api.bron.example',
+        getAccessToken: async () => getStoredAccessToken(),
+      },
+    }),
+  ],
+});
+```
+
+---
+
+## TypeScript
+
+This package is written in TypeScript and includes type definitions. All types are exported:
+
+```typescript
+import type {
+  Session,
+  WalletInfo,
+  SignedMessage,
+  SignedTransaction,
+  TxReceipt,
+  PartyLayerConfig,
+  ConnectOptions,
+} from '@partylayer/sdk';
+```
+
+---
+
+## Related Packages
+
+| Package | Description |
+|---------|-------------|
+| [@partylayer/react](https://www.npmjs.com/package/@partylayer/react) | React hooks and components |
+| [@partylayer/core](https://www.npmjs.com/package/@partylayer/core) | Core types and abstractions |
+
+---
+
+## Links
+
+- [GitHub Repository](https://github.com/cayvox/PartyLayer)
+- [Documentation](https://github.com/cayvox/PartyLayer#readme)
+- [Report Issues](https://github.com/cayvox/PartyLayer/issues)
+- [Canton Network](https://www.canton.network/)
+
+---
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,343 @@
+import { WalletAdapter, NetworkId, StorageAdapter, CryptoAdapter, TelemetryAdapter, LoggerAdapter, WalletId, Session, SessionId, TransactionHash, TransactionStatus, WalletInfo, SignMessageParams, SignedMessage, SignTransactionParams, SignedTransaction, SubmitTransactionParams, TxReceipt } from '@partylayer/core';
+export { AdapterConnectResult, AdapterContext, AdapterDetectResult, PartyLayerError as CantonConnectError, CapabilityKey, CapabilityNotSupportedError, ErrorCode, InternalError, NetworkId, OriginNotAllowedError, PartyId, PartyLayerError, RegistryFetchFailedError, RegistrySchemaInvalidError, RegistryVerificationFailedError, Session, SessionExpiredError, SessionId, SignMessageParams, SignTransactionParams, SignedMessage, SignedTransaction, SubmitTransactionParams, TimeoutError, TransactionStatus, TransportError, TxReceipt, UserRejectedError, WalletAdapter, WalletId, WalletInfo, WalletNotFoundError, WalletNotInstalledError } from '@partylayer/core';
+import { RegistryClient, RegistryStatus } from '@partylayer/registry-client';
+export { RegistryStatus } from '@partylayer/registry-client';
+export { BronAdapter, BronAdapterConfig, BronApiConfig, BronAuthConfig } from '@partylayer/adapter-bron';
+export { Cantor8Adapter } from '@partylayer/adapter-cantor8';
+export { ConsoleAdapter } from '@partylayer/adapter-console';
+export { LoopAdapter } from '@partylayer/adapter-loop';
+
+/**
+ * Configuration types for PartyLayer SDK
+ */
+
+/**
+ * Default registry URL for PartyLayer
+ * This points to the official registry endpoint.
+ */
+declare const DEFAULT_REGISTRY_URL = "https://registry.partylayer.xyz";
+/**
+ * Adapter class type (for instantiation)
+ */
+type AdapterClass = new () => WalletAdapter;
+/**
+ * PartyLayer configuration
+ */
+interface PartyLayerConfig {
+    /**
+     * Registry URL (optional)
+     * @default 'https://registry.partylayer.xyz/v1/wallets.json'
+     */
+    registryUrl?: string;
+    /** Registry channel */
+    channel?: 'stable' | 'beta';
+    /** Default network */
+    network: NetworkId;
+    /**
+     * Wallet adapters to register (OPTIONAL)
+     *
+     * By default, ALL built-in adapters are automatically registered:
+     * - ConsoleAdapter (Console Wallet - browser extension)
+     * - LoopAdapter (5N Loop - QR code / popup)
+     * - Cantor8Adapter (Cantor8 - deep link transport)
+     *
+     * Note: BronAdapter requires OAuth config and is NOT included by default.
+     *
+     * Only provide this if you want to customize which adapters to use.
+     *
+     * @example
+     * ```typescript
+     * // Default: all adapters (recommended)
+     * const client = createCantonConnect({
+     *   network: 'devnet',
+     *   app: { name: 'My dApp' },
+     *   // adapters not specified = all built-in adapters (Console, Loop, Cantor8)
+     * });
+     *
+     * // Custom: only specific adapters
+     * import { ConsoleAdapter } from '@partylayer/sdk';
+     * const client = createPartyLayer({
+     *   adapters: [new ConsoleAdapter()], // Only Console Wallet
+     *   // ...
+     * });
+     *
+     * // With Bron (enterprise wallet with OAuth)
+     * import { BronAdapter, getBuiltinAdapters } from '@partylayer/sdk';
+     * const client = createCantonConnect({
+     *   adapters: [
+     *     ...getBuiltinAdapters(),
+     *     new BronAdapter({ auth: {...}, api: {...} }),
+     *   ],
+     *   // ...
+     * });
+     * ```
+     */
+    adapters?: (WalletAdapter | AdapterClass)[];
+    /** Storage adapter (default: browser localStorage-based encrypted) */
+    storage?: StorageAdapter;
+    /** Crypto adapter (default: WebCrypto) */
+    crypto?: CryptoAdapter;
+    /** Registry public keys for signature verification (ed25519) */
+    registryPublicKeys?: string[];
+    /** Telemetry adapter (optional) */
+    telemetry?: TelemetryAdapter;
+    /** Logger adapter (optional) */
+    logger?: LoggerAdapter;
+    /** Application metadata */
+    app: {
+        /** Application name */
+        name: string;
+        /** Origin (for origin binding checks, defaults to window.location.origin) */
+        origin?: string;
+    };
+}
+/**
+ * Connect options
+ */
+interface ConnectOptions {
+    /** Specific wallet ID to connect to */
+    walletId?: WalletId;
+    /** Prefer installed wallets */
+    preferInstalled?: boolean;
+    /** Allow only specific wallets */
+    allowWallets?: WalletId[];
+    /** Required capabilities */
+    requiredCapabilities?: string[];
+    /** Timeout in milliseconds */
+    timeoutMs?: number;
+}
+/**
+ * Wallet filter options
+ */
+interface WalletFilter {
+    /** Required capabilities */
+    requiredCapabilities?: string[];
+    /** Include experimental wallets */
+    includeExperimental?: boolean;
+}
+
+/**
+ * Event types for PartyLayer SDK
+ */
+
+/**
+ * Registry updated event
+ */
+interface RegistryUpdatedEvent {
+    type: 'registry:updated';
+    channel: 'stable' | 'beta';
+    version: string;
+}
+/**
+ * Registry status event
+ */
+interface RegistryStatusEvent {
+    type: 'registry:status';
+    status: {
+        source: 'network' | 'cache';
+        verified: boolean;
+        channel: 'stable' | 'beta';
+        sequence: number;
+        stale: boolean;
+        fetchedAt: number;
+        etag?: string;
+        error?: Error;
+    };
+}
+/**
+ * Session connected event
+ */
+interface SessionConnectedEvent {
+    type: 'session:connected';
+    session: Session;
+}
+/**
+ * Session disconnected event
+ */
+interface SessionDisconnectedEvent {
+    type: 'session:disconnected';
+    sessionId: SessionId;
+    reason?: string;
+}
+/**
+ * Session expired event
+ */
+interface SessionExpiredEvent {
+    type: 'session:expired';
+    sessionId: SessionId;
+}
+/**
+ * Transaction status event
+ */
+interface TxStatusEvent {
+    type: 'tx:status';
+    sessionId: SessionId;
+    txId: TransactionHash;
+    status: TransactionStatus;
+    raw?: unknown;
+}
+/**
+ * Error event
+ */
+interface ErrorEvent {
+    type: 'error';
+    error: Error;
+}
+/**
+ * All event types
+ */
+type PartyLayerEvent = RegistryUpdatedEvent | RegistryStatusEvent | SessionConnectedEvent | SessionDisconnectedEvent | SessionExpiredEvent | TxStatusEvent | ErrorEvent;
+/**
+ * Event handler type
+ */
+type EventHandler<T extends PartyLayerEvent = PartyLayerEvent> = (event: T) => void | Promise<void>;
+
+/**
+ * PartyLayer Client - Public API Implementation
+ *
+ * This is the main public API for PartyLayer SDK.
+ * All dApps should use this API exclusively.
+ *
+ * References:
+ * - Wallet Integration Guide: https://docs.digitalasset.com/integrate/devnet/index.html
+ * - Signing transactions from dApps: https://docs.digitalasset.com/integrate/devnet/signing-transactions-from-dapps/index.html
+ * - OpenRPC dApp API spec: https://github.com/hyperledger-labs/splice-wallet-kernel/blob/main/api-specs/openrpc-dapp-api.json
+ */
+
+/**
+ * PartyLayer Client
+ *
+ * Main client interface for dApps to interact with Canton wallets.
+ */
+declare class PartyLayerClient {
+    private config;
+    private adapters;
+    private eventHandlers;
+    private activeSession;
+    readonly registryClient: RegistryClient;
+    private logger;
+    private crypto;
+    private storage;
+    private telemetry?;
+    private origin;
+    constructor(config: PartyLayerConfig);
+    /**
+     * Register a wallet adapter
+     *
+     * @internal
+     * This is used internally by the SDK to register adapters.
+     * In production, adapters would be auto-registered via registry.
+     */
+    registerAdapter(adapter: WalletAdapter): void;
+    /**
+     * List available wallets
+     */
+    listWallets(filter?: WalletFilter): Promise<WalletInfo[]>;
+    /**
+     * Connect to a wallet
+     */
+    connect(options?: ConnectOptions): Promise<Session>;
+    /**
+     * Disconnect from wallet
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Get active session
+     */
+    getActiveSession(): Promise<Session | null>;
+    /**
+     * Sign a message
+     */
+    signMessage(params: SignMessageParams): Promise<SignedMessage>;
+    /**
+     * Sign a transaction
+     */
+    signTransaction(params: SignTransactionParams): Promise<SignedTransaction>;
+    /**
+     * Submit a transaction
+     */
+    submitTransaction(params: SubmitTransactionParams): Promise<TxReceipt>;
+    /**
+     * Subscribe to events
+     */
+    on<T extends PartyLayerEvent>(event: T['type'], handler: EventHandler<T>): () => void;
+    /**
+     * Unsubscribe from events
+     */
+    off<T extends PartyLayerEvent>(event: T['type'], handler: EventHandler<T>): void;
+    /**
+     * Destroy client and cleanup
+     */
+    destroy(): void;
+    /**
+     * Create adapter context
+     */
+    private createAdapterContext;
+    /**
+     * Persist session to storage
+     */
+    private persistSession;
+    /**
+     * Remove session from storage
+     */
+    private removeSession;
+    /**
+     * Restore session from storage
+     */
+    private restoreSession;
+    /**
+     * Update registry status and emit event
+     */
+    private updateRegistryStatus;
+    /**
+     * Get registry status
+     */
+    getRegistryStatus(): RegistryStatus | null;
+    /**
+     * Emit event to handlers
+     */
+    private emit;
+}
+/**
+ * Create CantonConnect client
+ *
+ * This is the main entry point for dApps.
+ *
+ * @example
+ * ```typescript
+ * const client = createPartyLayer({
+ *   registryUrl: 'https://registry.partylayer.xyz',
+ *   channel: 'stable',
+ *   network: 'devnet',
+ *   app: { name: 'My dApp' }
+ * });
+ *
+ * const session = await client.connect();
+ * ```
+ */
+declare function createPartyLayer(config: PartyLayerConfig): PartyLayerClient;
+
+/**
+ * Built-in wallet adapters
+ *
+ * These adapters are automatically registered when creating a PartyLayer client.
+ * dApp developers don't need to install or configure these separately.
+ */
+
+/**
+ * Get all built-in adapters
+ *
+ * This function returns instances of all supported wallet adapters.
+ * Called automatically by createPartyLayer() unless custom adapters are provided.
+ *
+ * Included adapters:
+ * - ConsoleAdapter: Console Wallet browser extension
+ * - LoopAdapter: 5N Loop mobile/web wallet
+ * - Cantor8Adapter: Cantor8 wallet with deep link transport
+ *
+ * Note: BronAdapter is NOT included by default because it requires OAuth configuration.
+ * To use Bron, install @partylayer/adapter-bron and register it manually.
+ */
+declare function getBuiltinAdapters(): WalletAdapter[];
+
+export { type AdapterClass, PartyLayerClient as CantonConnectClient, type PartyLayerConfig as CantonConnectConfig, type PartyLayerEvent as CantonConnectEvent, type ConnectOptions, DEFAULT_REGISTRY_URL, type ErrorEvent, type EventHandler, PartyLayerClient, type PartyLayerConfig, type PartyLayerEvent, type RegistryUpdatedEvent, type SessionConnectedEvent, type SessionDisconnectedEvent, type SessionExpiredEvent, type TxStatusEvent, type WalletFilter, PartyLayerClient as _PartyLayerClientInternal, createPartyLayer as createCantonConnect, createPartyLayer, getBuiltinAdapters };