bitcoincash-oauth-client 0.1.1 → 0.2.2

package/dist/index.d.ts

@@ -13,9 +13,9 @@ export interface Keypair {
 }
 
 export interface SecureStorage {
-  getItem(key: string): string | null;
-  setItem(key: string, value: string): void;
-  removeItem(key: string): void;
+  getItem(key: string): string | null | Promise<string | null>;
+  setItem(key: string, value: string): void | Promise<void>;
+  removeItem(key: string): void | Promise<void>;
 }
 
 export interface OAuthClientOptions {
@@ -27,17 +27,29 @@ export interface OAuthClientOptions {
   secureStorage?: SecureStorage;
   /** Custom fetch implementation (optional) */
   fetch?: typeof fetch;
+  /** Key for storing access token (default: "oauth_token") */
+  tokenKey?: string;
+  /** Key for storing refresh token (default: "oauth_refresh_token") */
+  refreshTokenKey?: string;
+  /** Enable automatic token refresh (default: true) */
+  autoRefresh?: boolean;
+  /** Seconds before expiry to trigger refresh (default: 300 = 5 minutes) */
+  refreshThreshold?: number;
+  /** Enable debug logging (default: false) */
+  debug?: boolean;
 }
 
 export interface AuthenticationResult {
   /** JWT access token */
   access_token: string;
   /** Refresh token */
-  refresh_token: string;
+  refresh_token?: string;
   /** Token expiration in seconds */
   expires_in: number;
   /** Token type (e.g., "bearer") */
   token_type: string;
+  /** Granted scopes */
+  scopes?: string[];
 }
 
 export interface RegistrationResult {
@@ -47,7 +59,71 @@ export interface RegistrationResult {
   message?: string;
 }
 
+export interface AuthParams {
+  /** User ID */
+  userId: string;
+  /** Private key in hex format */
+  privateKeyHex: string;
+  /** Public key in hex format */
+  publicKeyHex: string;
+  /** Domain for authentication */
+  domain?: string;
+}
+
+// Error Classes
+
+export class OAuthError extends Error {
+  /** Error code */
+  code: string;
+  /** HTTP status code (if applicable) */
+  statusCode: number | null;
+  
+  constructor(message: string, code: string, statusCode?: number | null);
+}
+
+export class NetworkError extends OAuthError {
+  /** Original error that caused this */
+  originalError: Error | null;
+  
+  constructor(message: string, originalError?: Error | null);
+}
+
+export class AuthenticationError extends OAuthError {
+  constructor(message: string, statusCode: number, code?: string);
+}
+
+export class TokenExpiredError extends AuthenticationError {
+  constructor(message?: string);
+}
+
+export class UserNotFoundError extends AuthenticationError {
+  constructor(message?: string);
+}
+
+export class InvalidTokenError extends AuthenticationError {
+  constructor(message?: string);
+}
+
 export class BitcoinCashOAuthClient {
+  /** OAuth server URL */
+  serverUrl: string;
+  /** Network type */
+  network: string;
+  /** Storage interface for tokens */
+  secureStorage: SecureStorage | null;
+  /** Fetch implementation */
+  fetchImpl: typeof fetch;
+  /** Key for storing access token */
+  tokenKey: string;
+  /** Key for storing refresh token */
+  refreshTokenKey: string;
+  /** Enable automatic token refresh */
+  autoRefresh: boolean;
+  /** Seconds before expiry to trigger refresh */
+  refreshThreshold: number;
+  /** Enable debug logging */
+  debug: boolean;
+  
   constructor(options?: OAuthClientOptions);
   
   /** Initialize the client by instantiating secp256k1 */
@@ -62,37 +138,91 @@ export class BitcoinCashOAuthClient {
   /** Register a new user with the server */
   register(address: string, userId?: string | null): Promise<RegistrationResult>;
   
-  /** Create authentication message (userId,timestamp) */
-  createAuthMessage(userId: string, timestamp?: number | null): string;
+  /** Create authentication message (protocol|domain|userId|timestamp) */
+  createAuthMessage(userId: string, timestamp?: number | null, domain?: string | null): string;
   
   /** Sign authentication message with private key */
   signAuthMessage(message: string, privateKeyHex: string): Promise<string>;
   
-  /** Authenticate with the server */
+  /** 
+   * Authenticate with the server
+   * @param userId - User ID
+   * @param privateKeyHex - Private key in hex format
+   * @param publicKeyHex - Public key in hex format
+   * @param timestamp - Optional Unix timestamp (defaults to now)
+   * @param domain - Optional domain for message binding
+   */
   authenticate(
     userId: string,
     privateKeyHex: string,
     publicKeyHex: string,
-    timestamp?: number | null
+    timestamp?: number | null,
+    domain?: string | null
   ): Promise<AuthenticationResult>;
   
-  /** Get stored token */
+  /** Get stored access token */
   getToken(): string | null;
   
-  /** Make authenticated request */
-  authenticatedRequest(endpoint: string, options?: RequestInit): Promise<Response>;
+  /** Get stored refresh token */
+  getRefreshToken(): string | null;
+  
+  /**
+   * Validate if the current token is still valid
+   * @param serverCheck - If true, validates with the server; if false, only checks local expiry
+   */
+  isTokenValid(serverCheck?: boolean): Promise<boolean>;
+  
+  /**
+   * Make authenticated request with automatic retry on token expiration
+   * @param endpoint - API endpoint (relative to serverUrl)
+   * @param options - Fetch options
+   * @param authParams - Parameters to re-authenticate if token expires (optional)
+   */
+  authenticatedRequest(
+    endpoint: string, 
+    options?: RequestInit, 
+    authParams?: AuthParams | null
+  ): Promise<Response>;
   
-  /** Refresh access token */
+  /**
+   * Refresh access token using refresh token
+   * @param refreshToken - The refresh token
+   */
   refreshToken(refreshToken: string): Promise<AuthenticationResult>;
   
+  /**
+   * Refresh access token with automatic retry on expiration
+   * @param userId - User ID
+   * @param privateKeyHex - Private key in hex format
+   * @param publicKeyHex - Public key in hex format
+   * @param domain - Optional domain for authentication
+   */
+  refreshAccessToken(
+    userId: string,
+    privateKeyHex: string,
+    publicKeyHex: string,
+    domain?: string | null
+  ): Promise<AuthenticationResult>;
+  
   /** Revoke token */
-  revokeToken(token: string): Promise<{ message: string }>;
+  revokeToken(token: string): Promise<{ success: boolean; message?: string }>;
+  
+  /** Clean up resources (clear timers, etc.) */
+  destroy(): void;
   
   // Utility methods
   bytesToHex(bytes: Uint8Array): string;
   hexToBytes(hex: string): Uint8Array;
-  sha256(data: Uint8Array): Promise<Uint8Array>;
-  ripemd160(data: Uint8Array): Promise<Uint8Array>;
 }
 
+// Utility functions
+export function isBrowser(): boolean;
+export function isNode(): boolean;
+export function isCapacitor(): boolean;
+export function isHybridApp(): boolean;
+export function getFetch(userProvidedFetch?: typeof fetch | null): typeof fetch;
+export function getRandomBytes(length: number): Promise<Uint8Array>;
+export function sha256(data: Uint8Array): Promise<Uint8Array>;
+export function ripemd160(data: Uint8Array): Promise<Uint8Array>;
+
 export default BitcoinCashOAuthClient;