@opensecret/react 0.2.0 → 0.3.1

package/README.md

@@ -64,7 +64,10 @@ The `useOpenSecret` hook provides access to the OpenSecret API. It returns an ob
 
 #### Authentication Methods
 - `signIn(email: string, password: string): Promise<void>`: Signs in a user with the provided email and password.
-- `signUp(name: string, email: string, password: string, inviteCode: string): Promise<void>`: Signs up a new user with the provided name, email, password, and invite code.
+- `signUp(email: string, password: string, inviteCode: string, name?: string): Promise<void>`: Signs up a new user with the provided email, password, invite code, and optional name.
+- `signInGuest(id: string, password: string): Promise<void>`: Signs in a guest user with their ID and password.
+- `signUpGuest(password: string, inviteCode: string): Promise<LoginResponse>`: Creates a new guest account with just a password and invite code. Returns a response containing the guest's ID, access token, and refresh token.
+- `convertGuestToUserAccount(email: string, password: string, name?: string): Promise<void>`: Converts current guest account to a regular account with email authentication. Optionally sets the user's name.
 - `signOut(): Promise<void>`: Signs out the current user.
 
 #### Key-Value Storage Methods
@@ -76,6 +79,7 @@ The `useOpenSecret` hook provides access to the OpenSecret API. It returns an ob
 #### Account Management Methods
 - `refetchUser(): Promise<void>`: Refreshes the user's authentication state.
 - `changePassword(currentPassword: string, newPassword: string): Promise<void>`: Changes the user's password.
+- `generateThirdPartyToken(audience: string): Promise<{ token: string }>`: Generates a JWT token for use with pre-authorized third-party services (e.g. "https://api.devservice.com"). Developers must register this URL in advance (coming soon).
 
 #### Cryptographic Methods
 - `getPrivateKey(): Promise<PrivateKeyResponse>`: Retrieves the user's private key mnemonic phrase. This is used for cryptographic operations and should be kept secure.

package/dist/index.d.ts

@@ -6,7 +6,9 @@ declare namespace api {
     export {
         setApiUrl,
         fetchLogin,
+        fetchGuestLogin,
         fetchSignUp,
+        fetchGuestSignUp,
         refreshToken,
         fetchUser,
         fetchPut,
@@ -28,6 +30,8 @@ declare namespace api {
         fetchPrivateKey,
         signMessage,
         fetchPublicKey,
+        convertGuestToEmailAccount,
+        generateThirdPartyToken,
         LoginResponse,
         UserResponse,
         KVListItem,
@@ -35,7 +39,9 @@ declare namespace api {
         GoogleAuthResponse,
         PrivateKeyResponse,
         SignMessageResponse,
-        PublicKeyResponse
+        PublicKeyResponse,
+        ThirdPartyTokenRequest,
+        ThirdPartyTokenResponse
     }
 }
 
@@ -86,6 +92,8 @@ declare function changePassword(currentPassword: string, newPassword: string): P
 
 declare function confirmPasswordReset(email: string, alphanumericCode: string, plaintextSecret: string, newPassword: string): Promise<void>;
 
+declare function convertGuestToEmailAccount(email: string, password: string, name?: string): Promise<void>;
+
 declare const EXPECTED_ROOT_CERT_HASH = "641a0321a3e244efe456463195d606317ed7cdcc3c1756e09893f3c68f79bb5b";
 
 declare function fetchAttestationDocument(nonce: string): Promise<string>;
@@ -94,6 +102,10 @@ declare function fetchDelete(key: string): Promise<void>;
 
 declare function fetchGet(key: string): Promise<string | undefined>;
 
+declare function fetchGuestLogin(id: string, password: string): Promise<LoginResponse>;
+
+declare function fetchGuestSignUp(password: string, inviteCode: string): Promise<LoginResponse>;
+
 declare function fetchList(): Promise<KVListItem[]>;
 
 declare function fetchLogin(email: string, password: string): Promise<LoginResponse>;
@@ -106,12 +118,14 @@ declare function fetchPublicKey(algorithm: SigningAlgorithm): Promise<PublicKeyR
 
 declare function fetchPut(key: string, value: string): Promise<string>;
 
-declare function fetchSignUp(name: string, email: string, password: string, inviteCode: string): Promise<LoginResponse>;
+declare function fetchSignUp(email: string, password: string, inviteCode: string, name?: string | null): Promise<LoginResponse>;
 
 declare function fetchUser(): Promise<UserResponse>;
 
 export declare function generateSecureSecret(): string;
 
+declare function generateThirdPartyToken(audience: string): Promise<ThirdPartyTokenResponse>;
+
 declare function getAttestation(forceRefresh?: boolean): Promise<Attestation>;
 
 export declare type GithubAuthResponse = {
@@ -147,8 +161,8 @@ export declare type KVListItem = {
 };
 
 export declare type LoginResponse = {
-    id: number;
-    email: string;
+    id: string;
+    email?: string;
     access_token: string;
     refresh_token: string;
 };
@@ -178,10 +192,10 @@ export declare type OpenSecretContextType = {
     signIn: (email: string, password: string) => Promise<void>;
     /**
      * Creates a new user account
-     * @param name - User's full name
      * @param email - User's email address
      * @param password - User's chosen password
      * @param inviteCode - Invitation code for registration
+     * @param name - Optional user's full name
      * @returns A promise that resolves when account creation is complete
      * @throws {Error} If signup fails
      *
@@ -191,7 +205,53 @@ export declare type OpenSecretContextType = {
      * - Updates the auth state with new user information
      * - Throws an error if account creation fails
      */
-    signUp: (name: string, email: string, password: string, inviteCode: string) => Promise<void>;
+    signUp: (email: string, password: string, inviteCode: string, name?: string) => Promise<void>;
+    /**
+     * Authenticates a guest user with user id and password
+     * @param id - User's unique id
+     * @param password - User's password
+     * @returns A promise that resolves when authentication is complete
+     * @throws {Error} If login fails
+     *
+     * @description
+     * - Calls the login API endpoint
+     * - Stores access_token and refresh_token in localStorage
+     * - Updates the auth state with user information
+     * - Throws an error if authentication fails
+     */
+    signInGuest: (id: string, password: string) => Promise<void>;
+    /**
+     * Creates a new guest account, which can be upgraded to a normal account later with email.
+     * @param password - User's chosen password, cannot be changed or recovered without adding email address.
+     * @param inviteCode - Invitation code for registration
+     * @returns A promise that resolves to the login response containing the guest ID
+     * @throws {Error} If signup fails
+     *
+     * @description
+     * - Calls the registration API endpoint
+     * - Stores access_token and refresh_token in localStorage
+     * - Updates the auth state with new user information
+     * - Throws an error if account creation fails
+     */
+    signUpGuest: (password: string, inviteCode: string) => Promise<LoginResponse>;
+    /**
+     * Upgrades a guest account to a user account with email and password authentication.
+     * @param email - User's email address
+     * @param password - User's chosen password
+     * @param name - Optional user's full name
+     * @returns A promise that resolves when account creation is complete
+     * @throws {Error} If:
+     * - The current user is not a guest account
+     * - The email address is already in use
+     * - The user is not authenticated
+     *
+     * @description
+     * - Upgrades the currently signed-in guest account (identified by their UUID) to a full email account
+     * - Requires the user to be currently authenticated as a guest
+     * - Updates the auth state with new user information
+     * - Preserves all existing data associated with the guest account
+     */
+    convertGuestToUserAccount: (email: string, password: string, name?: string) => Promise<void>;
     /**
      * Logs out the current user
      * @returns A promise that resolves when logout is complete
@@ -351,6 +411,22 @@ export declare type OpenSecretContextType = {
      * 3. Parses it for viewing
      */
     getAttestationDocument: () => Promise<ParsedAttestationView>;
+    /**
+     * Generates a JWT token for use with authorized third-party services
+     * @param audience - The URL of the authorized service (e.g. "https://billing.opensecret.cloud")
+     * @returns A promise resolving to the token response
+     * @throws {Error} If:
+     * - The user is not authenticated
+     * - The audience URL is invalid
+     * - The audience URL is not authorized
+     *
+     * @description
+     * - Generates a signed JWT token for use with specific authorized third-party services
+     * - The audience must be an pre-authorized URL registered by the developer (e.g. api.devservice.com)
+     * - Requires an active authentication session
+     * - Token can be used to authenticate with the specified service
+     */
+    generateThirdPartyToken: (audience: string) => Promise<ThirdPartyTokenResponse>;
 };
 
 /**
@@ -442,13 +518,21 @@ declare type SignMessageResponse = {
     message_hash: string;
 };
 
+declare type ThirdPartyTokenRequest = {
+    audience: string;
+};
+
+declare type ThirdPartyTokenResponse = {
+    token: string;
+};
+
 export declare function useOpenSecret(): OpenSecretContextType;
 
 export declare type UserResponse = {
     user: {
         id: string;
         name: string | null;
-        email: string;
+        email?: string;
         email_verified: boolean;
         login_method: string;
         created_at: string;