@partylayer/core 0.2.3 → 0.2.4

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 CantonConnect
+Copyright (c) 2024 PartyLayer
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -244,9 +244,9 @@ try {
 
 ## Links
 
-- [GitHub Repository](https://github.com/cayvox/PartyLayer)
-- [Wallet Provider Guide](https://github.com/cayvox/PartyLayer/blob/main/docs/wallet-provider-guide.md)
-- [Report Issues](https://github.com/cayvox/PartyLayer/issues)
+- [GitHub Repository](https://github.com/PartyLayer/PartyLayer)
+- [Wallet Provider Guide](https://github.com/PartyLayer/PartyLayer/blob/main/docs/wallet-provider-guide.md)
+- [Report Issues](https://github.com/PartyLayer/PartyLayer/issues)
 
 ---
 

package/dist/index.d.mts

@@ -34,7 +34,7 @@ type NetworkId = 'devnet' | 'testnet' | 'mainnet' | (string & Record<never, neve
  * Capability keys that wallets can support
  * Based on OpenRPC dApp API capabilities
  */
-type CapabilityKey = 'connect' | 'disconnect' | 'restore' | 'signMessage' | 'signTransaction' | 'submitTransaction' | 'events' | 'deeplink' | 'popup' | 'injected' | 'remoteSigner';
+type CapabilityKey = 'connect' | 'disconnect' | 'restore' | 'signMessage' | 'signTransaction' | 'submitTransaction' | 'ledgerApi' | 'events' | 'deeplink' | 'popup' | 'injected' | 'remoteSigner';
 /**
  * Wallet installation hints for detection
  */
@@ -222,7 +222,7 @@ interface ErrorMappingContext {
     /** Wallet ID (if applicable) */
     walletId?: string;
     /** Operation phase */
-    phase: 'connect' | 'restore' | 'signMessage' | 'signTransaction' | 'submitTransaction';
+    phase: 'connect' | 'restore' | 'signMessage' | 'signTransaction' | 'submitTransaction' | 'ledgerApi';
     /** Transport type */
     transport?: 'injected' | 'popup' | 'deeplink' | 'remote';
     /** Timeout in milliseconds (for timeout errors) */
@@ -389,6 +389,24 @@ interface SubmitTransactionParams {
     /** Signed transaction */
     signedTx: unknown;
 }
+/**
+ * Ledger API proxy parameters (CIP-0103 ledgerApi method)
+ */
+interface LedgerApiParams {
+    /** HTTP method for the JSON Ledger API */
+    requestMethod: 'GET' | 'POST' | 'PUT' | 'DELETE';
+    /** Resource path (e.g., "/v1/state/acs") */
+    resource: string;
+    /** Optional JSON body */
+    body?: string;
+}
+/**
+ * Ledger API proxy result
+ */
+interface LedgerApiResult {
+    /** JSON response from the Ledger API */
+    response: string;
+}
 /**
  * Logger interface
  */
@@ -400,10 +418,40 @@ interface LoggerAdapter {
 }
 /**
  * Telemetry interface
+ *
+ * Extended in 0.3.0 with optional metrics methods.
+ * All new methods are optional to maintain backward compatibility.
  */
 interface TelemetryAdapter {
+    /** Track a named event with optional properties */
     track(event: string, properties?: Record<string, unknown>): void;
+    /** Track an error occurrence */
     error(error: Error, properties?: Record<string, unknown>): void;
+    /**
+     * Increment a metric counter
+     * @param metric - Metric name (e.g., 'wallet_connect_attempts')
+     * @param value - Value to increment by (default: 1)
+     * @since 0.3.0
+     */
+    increment?(metric: string, value?: number): void;
+    /**
+     * Set a gauge metric value
+     * @param metric - Metric name
+     * @param value - Current value
+     * @since 0.3.0
+     */
+    gauge?(metric: string, value: number): void;
+    /**
+     * Flush buffered metrics to backend
+     * @since 0.3.0
+     */
+    flush?(): Promise<void>;
+    /**
+     * Check if telemetry is enabled
+     * @returns true if telemetry should be collected
+     * @since 0.3.0
+     */
+    isEnabled?(): boolean;
 }
 /**
  * Crypto interface
@@ -519,6 +567,13 @@ interface WalletAdapter {
      * @param params Submit transaction parameters
      */
     submitTransaction?(ctx: AdapterContext, session: Session, params: SubmitTransactionParams): Promise<TxReceipt>;
+    /**
+     * Proxy a JSON Ledger API request (optional - only if wallet supports it)
+     * @param ctx Adapter context
+     * @param session Active session
+     * @param params Ledger API request parameters
+     */
+    ledgerApi?(ctx: AdapterContext, session: Session, params: LedgerApiParams): Promise<LedgerApiResult>;
     /**
      * Subscribe to adapter events (optional)
      * @param event Event name
@@ -660,6 +715,287 @@ interface Transport$1 {
     pollJobStatus?(jobId: string, statusUrl: string, options: TransportOptions): Promise<JobStatus>;
 }
 
+/**
+ * Canonical Metrics Constants
+ *
+ * These metric names are the official set for PartyLayer telemetry.
+ * Changing these names would break metrics aggregation and downstream reporting.
+ *
+ * @since 0.3.0
+ */
+/**
+ * Enablement Metrics
+ *
+ * These metrics measure how PartyLayer enables wallet interactions.
+ */
+declare const ENABLEMENT_METRICS: {
+    /** Total wallet connect() calls made */
+    readonly WALLET_CONNECT_ATTEMPTS: "wallet_connect_attempts";
+    /** Successful wallet connections (session:connected events) */
+    readonly WALLET_CONNECT_SUCCESS: "wallet_connect_success";
+    /** New sessions created (not restored) */
+    readonly SESSIONS_CREATED: "sessions_created";
+    /** Sessions successfully restored from storage */
+    readonly SESSIONS_RESTORED: "sessions_restored";
+    /** Total session restore attempts */
+    readonly RESTORE_ATTEMPTS: "restore_attempts";
+};
+/**
+ * Error Metrics
+ *
+ * These metrics track error occurrences by code.
+ */
+declare const ERROR_METRICS: {
+    /** Prefix for error metrics (e.g., error_USER_REJECTED) */
+    readonly ERROR_PREFIX: "error_";
+};
+/**
+ * Registry Metrics
+ *
+ * These metrics track registry client behavior.
+ */
+declare const REGISTRY_METRICS: {
+    /** Registry fetched from network */
+    readonly REGISTRY_FETCH: "registry_fetch";
+    /** Registry served from cache */
+    readonly REGISTRY_CACHE_HIT: "registry_cache_hit";
+    /** Stale registry was used */
+    readonly REGISTRY_STALE: "registry_stale";
+};
+/**
+ * All metrics combined
+ */
+declare const METRICS: {
+    /** Registry fetched from network */
+    readonly REGISTRY_FETCH: "registry_fetch";
+    /** Registry served from cache */
+    readonly REGISTRY_CACHE_HIT: "registry_cache_hit";
+    /** Stale registry was used */
+    readonly REGISTRY_STALE: "registry_stale";
+    /** Prefix for error metrics (e.g., error_USER_REJECTED) */
+    readonly ERROR_PREFIX: "error_";
+    /** Total wallet connect() calls made */
+    readonly WALLET_CONNECT_ATTEMPTS: "wallet_connect_attempts";
+    /** Successful wallet connections (session:connected events) */
+    readonly WALLET_CONNECT_SUCCESS: "wallet_connect_success";
+    /** New sessions created (not restored) */
+    readonly SESSIONS_CREATED: "sessions_created";
+    /** Sessions successfully restored from storage */
+    readonly SESSIONS_RESTORED: "sessions_restored";
+    /** Total session restore attempts */
+    readonly RESTORE_ATTEMPTS: "restore_attempts";
+};
+/**
+ * Type for all metric names
+ */
+type MetricName = typeof METRICS[keyof typeof METRICS];
+/**
+ * Build an error metric name from an error code
+ *
+ * @param errorCode - The error code (e.g., 'USER_REJECTED')
+ * @returns The metric name (e.g., 'error_USER_REJECTED')
+ */
+declare function errorMetricName(errorCode: string): string;
+
+/**
+ * Metrics Payload Types and Privacy Validation
+ *
+ * This module defines the privacy-safe payload format for metrics collection.
+ *
+ * Privacy Guarantees:
+ * - NO wallet addresses
+ * - NO raw party IDs
+ * - NO transaction payloads
+ * - NO signed message content
+ * - NO user identifiers
+ *
+ * @since 0.3.0
+ */
+/**
+ * Privacy-safe metrics payload
+ *
+ * This is the only payload format accepted by the metrics backend.
+ */
+interface MetricsPayload {
+    /** SDK version (e.g., '0.3.0') */
+    sdkVersion: string;
+    /** Network identifier (e.g., 'devnet', 'mainnet') */
+    network: string;
+    /** Unix timestamp in milliseconds */
+    timestamp: number;
+    /** Metric name → value map */
+    metrics: Record<string, number>;
+    /** Hashed app identifier (opt-in, SHA-256) */
+    appIdHash?: string;
+    /** Hashed origin (opt-in, SHA-256) */
+    originHash?: string;
+}
+/**
+ * Validate that a payload is privacy-safe
+ *
+ * @param payload - Unknown payload to validate
+ * @returns true if payload is valid MetricsPayload with no PII
+ * @throws Error if forbidden fields are detected
+ */
+declare function validatePayload(payload: unknown): payload is MetricsPayload;
+/**
+ * Hash a string using SHA-256 (browser-compatible)
+ *
+ * @param value - String to hash
+ * @returns Hex-encoded SHA-256 hash
+ */
+declare function hashForPrivacy(value: string): Promise<string>;
+/**
+ * Create a sanitized metrics payload
+ *
+ * This function ensures the payload is privacy-safe before sending.
+ *
+ * @param data - Raw metrics data
+ * @returns Sanitized MetricsPayload
+ */
+declare function createMetricsPayload(data: {
+    sdkVersion: string;
+    network: string;
+    metrics: Record<string, number>;
+    appIdHash?: string;
+    originHash?: string;
+}): MetricsPayload;
+
+/**
+ * CIP-0103 dApp Standard — Canonical Type Definitions
+ *
+ * These types are the verbatim representation of the CIP-0103 specification.
+ * They live in @partylayer/core so both @partylayer/provider and @partylayer/sdk
+ * can reference them without circular dependencies.
+ *
+ * Reference: https://github.com/canton-foundation/cips/blob/main/cip-0103/cip-0103.md
+ *
+ * IMPORTANT: Do not add PartyLayer-specific fields or aliases.
+ * These types represent the standard exactly.
+ */
+type CIP0103EventListener<T = unknown> = (...args: T[]) => void;
+type CIP0103RequestParams = unknown[] | Record<string, unknown>;
+interface CIP0103RequestPayload {
+    method: string;
+    params?: CIP0103RequestParams;
+}
+interface CIP0103Provider {
+    request<T = unknown>(args: CIP0103RequestPayload): Promise<T>;
+    on<T = unknown>(event: string, listener: CIP0103EventListener<T>): CIP0103Provider;
+    emit<T = unknown>(event: string, ...args: T[]): boolean;
+    removeListener<T = unknown>(event: string, listenerToRemove: CIP0103EventListener<T>): CIP0103Provider;
+}
+interface CIP0103ConnectResult {
+    isConnected: boolean;
+    reason?: string;
+    isNetworkConnected?: boolean;
+    networkReason?: string;
+    /** Async wallet extension: URL for user to complete connection */
+    userUrl?: string;
+}
+interface CIP0103Network {
+    /** CAIP-2 network identifier, e.g. "canton:da-mainnet" */
+    networkId: string;
+    /** JSON Ledger API endpoint (if available) */
+    ledgerApi?: string;
+    /** Access token for Ledger API (if available) */
+    accessToken?: string;
+}
+type CIP0103AccountStatus = 'initializing' | 'allocated';
+interface CIP0103Account {
+    primary: boolean;
+    partyId: string;
+    status: CIP0103AccountStatus;
+    hint: string;
+    publicKey: string;
+    namespace: string;
+    /** CAIP-2 network identifier */
+    networkId: string;
+    signingProviderId: string;
+}
+type CIP0103ProviderType = 'browser' | 'desktop' | 'mobile' | 'remote';
+interface CIP0103ProviderInfo {
+    id: string;
+    /** dApp API version */
+    version: string;
+    providerType: CIP0103ProviderType;
+}
+interface CIP0103StatusEvent {
+    connection: CIP0103ConnectResult;
+    provider: CIP0103ProviderInfo;
+    network?: CIP0103Network;
+    session?: {
+        accessToken: string;
+        userId: string;
+    };
+}
+type CIP0103TxStatus = 'pending' | 'signed' | 'executed' | 'failed';
+interface CIP0103TxPendingPayload {
+    status: 'pending';
+    commandId: string;
+}
+interface CIP0103TxSignedPayload {
+    status: 'signed';
+    commandId: string;
+    payload: {
+        signature: string;
+        signedBy: string;
+        party: string;
+    };
+}
+interface CIP0103TxExecutedPayload {
+    status: 'executed';
+    commandId: string;
+    payload: {
+        updateId: string;
+        completionOffset: number;
+    };
+}
+interface CIP0103TxFailedPayload {
+    status: 'failed';
+    commandId: string;
+}
+type CIP0103TxChangedEvent = CIP0103TxPendingPayload | CIP0103TxSignedPayload | CIP0103TxExecutedPayload | CIP0103TxFailedPayload;
+interface CIP0103LedgerApiRequest {
+    requestMethod: 'GET' | 'POST' | 'PUT' | 'DELETE';
+    resource: string;
+    body?: string;
+}
+interface CIP0103LedgerApiResponse {
+    response: string;
+}
+interface CIP0103SignMessageRequest {
+    message: string;
+}
+interface CIP0103ProviderRpcError {
+    code: number;
+    message: string;
+    data?: unknown;
+}
+declare const CIP0103_METHODS: {
+    readonly CONNECT: "connect";
+    readonly DISCONNECT: "disconnect";
+    readonly IS_CONNECTED: "isConnected";
+    readonly STATUS: "status";
+    readonly GET_ACTIVE_NETWORK: "getActiveNetwork";
+    readonly LIST_ACCOUNTS: "listAccounts";
+    readonly GET_PRIMARY_ACCOUNT: "getPrimaryAccount";
+    readonly SIGN_MESSAGE: "signMessage";
+    readonly PREPARE_EXECUTE: "prepareExecute";
+    readonly LEDGER_API: "ledgerApi";
+};
+type CIP0103Method = (typeof CIP0103_METHODS)[keyof typeof CIP0103_METHODS];
+/** All mandatory method names as an array (useful for conformance testing) */
+declare const CIP0103_MANDATORY_METHODS: readonly CIP0103Method[];
+declare const CIP0103_EVENTS: {
+    readonly STATUS_CHANGED: "statusChanged";
+    readonly ACCOUNTS_CHANGED: "accountsChanged";
+    readonly TX_CHANGED: "txChanged";
+    /** Emitted when async connect completes */
+    readonly CONNECTED: "connected";
+};
+type CIP0103Event = (typeof CIP0103_EVENTS)[keyof typeof CIP0103_EVENTS];
+
 /**
  * Deep Link Transport
  *
@@ -882,4 +1218,4 @@ interface Transport {
     disconnect(): Promise<void>;
 }
 
-export { type AdapterConnectResult, type AdapterContext, type AdapterDetectResult, type AdapterEventName, type AdapterMetadata, type CapabilityKey, CapabilityNotSupportedError, type ConnectRequest, type ConnectResponse, type CryptoAdapter, DeepLinkTransport, type ErrorCode, type ErrorMappingContext, type InstallHints, InternalError, type JobStatus, type LoggerAdapter, MockTransport, type NetworkId, OriginNotAllowedError, type PartyId, PartyLayerError, type PersistedSession, PopupTransport, PostMessageTransport, type RegistryClientAdapter, RegistryFetchFailedError, RegistrySchemaInvalidError, RegistryVerificationFailedError, type Session, SessionExpiredError, type SessionId, type SignMessageParams, type SignRequest, type SignResponse, type SignTransactionParams, type Signature, type SignedMessage, type SignedTransaction, type StorageAdapter, type SubmitTransactionParams, type TelemetryAdapter, TimeoutError, type TransactionHash, type TransactionStatus, type Transport, TransportError, type TransportOptions, type TransportType, type TxReceipt, type TxStatusUpdate, UserRejectedError, type WalletAdapter, type WalletId, type WalletInfo, WalletNotFoundError, WalletNotInstalledError, capabilityGuard, createSession, generateSessionId, installGuard, isSessionExpired, mapUnknownErrorToPartyLayerError, toPartyId, toSessionId, toSignature, toTransactionHash, toWalletId, validateSession };
+export { type AdapterConnectResult, type AdapterContext, type AdapterDetectResult, type AdapterEventName, type AdapterMetadata, type CIP0103Account, type CIP0103AccountStatus, type CIP0103ConnectResult, type CIP0103Event, type CIP0103EventListener, type CIP0103LedgerApiRequest, type CIP0103LedgerApiResponse, type CIP0103Method, type CIP0103Network, type CIP0103Provider, type CIP0103ProviderInfo, type CIP0103ProviderRpcError, type CIP0103ProviderType, type CIP0103RequestParams, type CIP0103RequestPayload, type CIP0103SignMessageRequest, type CIP0103StatusEvent, type CIP0103TxChangedEvent, type CIP0103TxExecutedPayload, type CIP0103TxFailedPayload, type CIP0103TxPendingPayload, type CIP0103TxSignedPayload, type CIP0103TxStatus, CIP0103_EVENTS, CIP0103_MANDATORY_METHODS, CIP0103_METHODS, type CapabilityKey, CapabilityNotSupportedError, type ConnectRequest, type ConnectResponse, type CryptoAdapter, DeepLinkTransport, ENABLEMENT_METRICS, ERROR_METRICS, type ErrorCode, type ErrorMappingContext, type InstallHints, InternalError, type JobStatus, type LedgerApiParams, type LedgerApiResult, type LoggerAdapter, METRICS, type MetricName, type MetricsPayload, MockTransport, type NetworkId, OriginNotAllowedError, type PartyId, PartyLayerError, type PersistedSession, PopupTransport, PostMessageTransport, REGISTRY_METRICS, type RegistryClientAdapter, RegistryFetchFailedError, RegistrySchemaInvalidError, RegistryVerificationFailedError, type Session, SessionExpiredError, type SessionId, type SignMessageParams, type SignRequest, type SignResponse, type SignTransactionParams, type Signature, type SignedMessage, type SignedTransaction, type StorageAdapter, type SubmitTransactionParams, type TelemetryAdapter, TimeoutError, type TransactionHash, type TransactionStatus, type Transport, TransportError, type TransportOptions, type TransportType, type TxReceipt, type TxStatusUpdate, UserRejectedError, type WalletAdapter, type WalletId, type WalletInfo, WalletNotFoundError, WalletNotInstalledError, capabilityGuard, createMetricsPayload, createSession, errorMetricName, generateSessionId, hashForPrivacy, installGuard, isSessionExpired, mapUnknownErrorToPartyLayerError, toPartyId, toSessionId, toSignature, toTransactionHash, toWalletId, validatePayload, validateSession };