@0xmonaco/core 0.7.7 → 0.7.8

package/dist/api/applications/api.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Applications API Implementation
+ *
+ * Handles application configuration operations. All operations go through
+ * the API Gateway and require valid authentication.
+ *
+ * This class provides an interface for retrieving application configuration
+ * on the Monaco protocol.
+ *
+ * @example
+ * ```typescript
+ * const applicationsAPI = new ApplicationsAPIImpl(apiUrl);
+ *
+ * // Get application configuration
+ * const config = await applicationsAPI.getApplicationConfig();
+ * console.log(`App name: ${config.name}`);
+ * console.log(`Allowed origins: ${config.allowedOrigins.join(', ')}`);
+ * ```
+ */
+import type { ApplicationConfigResponse, ApplicationsAPI } from "@0xmonaco/types";
+import { BaseAPI } from "../base";
+export declare class ApplicationsAPIImpl extends BaseAPI implements ApplicationsAPI {
+    /**
+     * Gets the configuration for the authenticated application.
+     *
+     * Returns the application's configuration including allowed origins,
+     * webhook URL, and other settings. Requires valid authentication.
+     *
+     * @returns Promise resolving to the application configuration
+     * @throws {APIError} When the request fails or authentication is invalid
+     *
+     * @example
+     * ```typescript
+     * const config = await applicationsAPI.getApplicationConfig();
+     * console.log(`Application: ${config.name}`);
+     * console.log(`ID: ${config.id}`);
+     * if (config.webhookUrl) {
+     *   console.log(`Webhook: ${config.webhookUrl}`);
+     * }
+     * ```
+     */
+    getApplicationConfig(): Promise<ApplicationConfigResponse>;
+}

package/dist/api/applications/api.js

@@ -0,0 +1,54 @@
+/**
+ * Applications API Implementation
+ *
+ * Handles application configuration operations. All operations go through
+ * the API Gateway and require valid authentication.
+ *
+ * This class provides an interface for retrieving application configuration
+ * on the Monaco protocol.
+ *
+ * @example
+ * ```typescript
+ * const applicationsAPI = new ApplicationsAPIImpl(apiUrl);
+ *
+ * // Get application configuration
+ * const config = await applicationsAPI.getApplicationConfig();
+ * console.log(`App name: ${config.name}`);
+ * console.log(`Allowed origins: ${config.allowedOrigins.join(', ')}`);
+ * ```
+ */
+import { BaseAPI } from "../base";
+export class ApplicationsAPIImpl extends BaseAPI {
+    /**
+     * Gets the configuration for the authenticated application.
+     *
+     * Returns the application's configuration including allowed origins,
+     * webhook URL, and other settings. Requires valid authentication.
+     *
+     * @returns Promise resolving to the application configuration
+     * @throws {APIError} When the request fails or authentication is invalid
+     *
+     * @example
+     * ```typescript
+     * const config = await applicationsAPI.getApplicationConfig();
+     * console.log(`Application: ${config.name}`);
+     * console.log(`ID: ${config.id}`);
+     * if (config.webhookUrl) {
+     *   console.log(`Webhook: ${config.webhookUrl}`);
+     * }
+     * ```
+     */
+    async getApplicationConfig() {
+        const data = await this.makeAuthenticatedRequest("/api/v1/applications/config", {
+            method: "GET",
+        });
+        return {
+            id: data.id,
+            name: data.name,
+            allowedOrigins: data.allowed_origins,
+            webhookUrl: data.webhook_url,
+            vaultContractAddress: data.vault_contract_address,
+            clientId: data.client_id,
+        };
+    }
+}

package/dist/api/applications/index.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Applications API Module
+ */
+export { ApplicationsAPIImpl } from "./api";

package/dist/api/applications/index.js

@@ -0,0 +1,4 @@
+/**
+ * Applications API Module
+ */
+export { ApplicationsAPIImpl } from "./api";

package/dist/api/auth/api.d.ts

@@ -0,0 +1,206 @@
+/**
+ * Auth API Implementation
+ *
+ * Handles authentication operations including challenge creation, signature verification,
+ * and backend authentication. All operations go through the API Gateway.
+ *
+ * This class provides a complete interface for authentication on the Monaco protocol,
+ * including frontend wallet authentication and backend service authentication.
+ *
+ * @example
+ * ```typescript
+ * const authAPI = new AuthAPIImpl(walletClient, chain, apiUrl);
+ *
+ * // Complete authentication flow
+ * const authResult = await authAPI.authenticate(clientId);
+ *
+ * // Or step-by-step flow
+ * const challenge = await authAPI.createChallenge(userAddress, clientId);
+ * const signature = await authAPI.signChallenge(challenge.message);
+ * const authResult = await authAPI.verifySignature(
+ *   userAddress,
+ *   signature,
+ *   challenge.nonce,
+ *   clientId
+ * );
+ *
+ * // Authenticate backend service
+ * const backendAuth = await authAPI.authenticateBackend(secretKey);
+ * ```
+ */
+import type { AuthAPI, AuthState, BackendAuthResponse, ChallengeResponse, TokenRefreshResponse } from "@0xmonaco/types";
+import type { Chain, WalletClient } from "viem";
+import { BaseAPI } from "../base";
+export declare class AuthAPIImpl extends BaseAPI implements AuthAPI {
+    private readonly chain;
+    private walletClient;
+    /**
+     * Creates a new AuthAPI instance.
+     *
+     * @param walletClient - The viem wallet client for signing operations (optional)
+     * @param chain - The blockchain network configuration
+     * @param apiUrl - The base URL for the Monaco API Gateway
+     */
+    constructor(walletClient: WalletClient | undefined, chain: Chain, apiUrl: string);
+    /**
+     * Sets the wallet client for signing operations.
+     * Used when the wallet becomes available after SDK initialization.
+     */
+    setWalletClient(walletClient: WalletClient): void;
+    /**
+     * Complete authentication flow for frontend applications.
+     *
+     * This method handles the entire authentication process:
+     * 1. Creates a challenge
+     * 2. Signs the challenge message
+     * 3. Verifies the signature and returns JWT tokens
+     *
+     * @param clientId - Client ID of the application
+     * @returns Promise resolving to the verification response with JWT tokens
+     * @throws {APIError} When authentication fails
+     * @throws {InvalidConfigError} When wallet account is not available
+     *
+     * @example
+     * ```typescript
+     * // Complete authentication in one call
+     * const authResult = await authAPI.authenticate("my-app-client-id");
+     * console.log(`Access token: ${authResult.access_token}`);
+     * console.log(`User ID: ${authResult.user.id}`);
+     * ```
+     */
+    authenticate(clientId: string): Promise<AuthState>;
+    /**
+     * Signs a challenge message using the wallet client.
+     *
+     * Signs the provided message using the wallet's private key.
+     * This is used in the authentication flow to prove ownership of the wallet.
+     *
+     * @param message - The message to sign
+     * @returns Promise resolving to the signature
+     * @throws {InvalidConfigError} When wallet account is not available
+     * @throws {APIError} When signing fails
+     *
+     * @example
+     * ```typescript
+     * const challenge = await authAPI.createChallenge(address, clientId);
+     * const signature = await authAPI.signChallenge(challenge.message);
+     * console.log(`Signature: ${signature}`);
+     * ```
+     */
+    signChallenge(message: string): Promise<string>;
+    /**
+     * Creates a challenge for frontend authentication.
+     *
+     * Generates a unique nonce and message that the user must sign with their wallet.
+     * This is the first step in the authentication flow for frontend applications.
+     *
+     * @param address - Wallet address of the user
+     * @param clientId - Client ID of the application
+     * @returns Promise resolving to the challenge response
+     * @throws {APIError} When challenge creation fails
+     *
+     * @example
+     * ```typescript
+     * const challenge = await authAPI.createChallenge(
+     *   "0x1234...",
+     *   "my-app-client-id"
+     * );
+     * console.log(`Challenge message: ${challenge.message}`);
+     * console.log(`Nonce: ${challenge.nonce}`);
+     * ```
+     */
+    createChallenge(address: string, clientId: string): Promise<ChallengeResponse>;
+    /**
+     * Verifies a signature for frontend authentication.
+     *
+     * Validates the signature against the challenge and returns JWT tokens for
+     * authenticated API access. This is the second step in the authentication flow.
+     *
+     * @param address - Wallet address of the user
+     * @param signature - Signature of the challenge message
+     * @param nonce - Nonce from the challenge response
+     * @param clientId - Client ID of the application
+     * @returns Promise resolving to the verification response with JWT tokens
+     * @throws {APIError} When signature verification fails
+     *
+     * @example
+     * ```typescript
+     * // First create a challenge
+     * const challenge = await authAPI.createChallenge(address, clientId);
+     *
+     * // User signs the challenge message with their wallet
+     * const signature = await wallet.signMessage(challenge.message);
+     *
+     * // Verify the signature and get tokens
+     * const authResult = await authAPI.verifySignature(
+     *   address,
+     *   signature,
+     *   challenge.nonce,
+     *   clientId
+     * );
+     *
+     * console.log(`Access token: ${authResult.accessToken}`);
+     * console.log(`User ID: ${authResult.user.id}`);
+     * ```
+     */
+    verifySignature(address: string, signature: string, nonce: string, clientId: string): Promise<AuthState>;
+    /**
+     * Authenticates a backend service using a secret key.
+     *
+     * Returns JWT tokens for API access. This method is used for backend services
+     * that need to authenticate with the Monaco API Gateway.
+     *
+     * @param secretKey - Secret key of the application
+     * @returns Promise resolving to the backend auth response with JWT tokens
+     * @throws {APIError} When backend authentication fails
+     *
+     * @example
+     * ```typescript
+     * const backendAuth = await authAPI.authenticateBackend("my-secret-key");
+     * console.log(`Backend access token: ${backendAuth.accessToken}`);
+     * console.log(`Application: ${backendAuth.application.name}`);
+     * ```
+     */
+    authenticateBackend(secretKey: string): Promise<BackendAuthResponse>;
+    /**
+     * Refreshes an access token using a refresh token.
+     *
+     * Obtains a new access token using a valid refresh token. This is useful for
+     * maintaining long-term authentication without requiring the user to sign
+     * a new challenge.
+     *
+     * @param refreshToken - The refresh token to use
+     * @returns Promise resolving to new access and refresh tokens
+     * @throws {APIError} When token refresh fails
+     *
+     * @example
+     * ```typescript
+     * const newTokens = await authAPI.refreshToken(refreshToken);
+     * console.log(`New access token: ${newTokens.accessToken}`);
+     * console.log(`Expires at: ${new Date(newTokens.expiresAt * 1000)}`);
+     * ```
+     */
+    refreshToken(refreshToken: string): Promise<TokenRefreshResponse>;
+    /**
+     * Revokes the current session's refresh token.
+     *
+     * Invalidates the refresh token associated with the current access token,
+     * preventing it from being used to obtain new access tokens. This is useful
+     * for logout functionality or when a token has been compromised.
+     *
+     * The server identifies the token to revoke from the access token in the
+     * Authorization header — no request body is needed.
+     *
+     * @returns Promise resolving when the token is revoked
+     * @throws {APIError} When token revocation fails
+     *
+     * @example
+     * ```typescript
+     * // After authentication
+     * const authResult = await authAPI.authenticate(clientId);
+     * await authAPI.revokeToken();
+     * console.log("Token revoked successfully");
+     * ```
+     */
+    revokeToken(): Promise<void>;
+}

package/dist/api/auth/api.js

@@ -0,0 +1,305 @@
+/**
+ * Auth API Implementation
+ *
+ * Handles authentication operations including challenge creation, signature verification,
+ * and backend authentication. All operations go through the API Gateway.
+ *
+ * This class provides a complete interface for authentication on the Monaco protocol,
+ * including frontend wallet authentication and backend service authentication.
+ *
+ * @example
+ * ```typescript
+ * const authAPI = new AuthAPIImpl(walletClient, chain, apiUrl);
+ *
+ * // Complete authentication flow
+ * const authResult = await authAPI.authenticate(clientId);
+ *
+ * // Or step-by-step flow
+ * const challenge = await authAPI.createChallenge(userAddress, clientId);
+ * const signature = await authAPI.signChallenge(challenge.message);
+ * const authResult = await authAPI.verifySignature(
+ *   userAddress,
+ *   signature,
+ *   challenge.nonce,
+ *   clientId
+ * );
+ *
+ * // Authenticate backend service
+ * const backendAuth = await authAPI.authenticateBackend(secretKey);
+ * ```
+ */
+import { InvalidConfigError } from "../../errors";
+import { BaseAPI } from "../base";
+export class AuthAPIImpl extends BaseAPI {
+    chain;
+    walletClient;
+    /**
+     * Creates a new AuthAPI instance.
+     *
+     * @param walletClient - The viem wallet client for signing operations (optional)
+     * @param chain - The blockchain network configuration
+     * @param apiUrl - The base URL for the Monaco API Gateway
+     */
+    constructor(walletClient, chain, apiUrl) {
+        super(apiUrl);
+        this.chain = chain;
+        this.walletClient = walletClient;
+    }
+    /**
+     * Sets the wallet client for signing operations.
+     * Used when the wallet becomes available after SDK initialization.
+     */
+    setWalletClient(walletClient) {
+        this.walletClient = walletClient;
+    }
+    /**
+     * Complete authentication flow for frontend applications.
+     *
+     * This method handles the entire authentication process:
+     * 1. Creates a challenge
+     * 2. Signs the challenge message
+     * 3. Verifies the signature and returns JWT tokens
+     *
+     * @param clientId - Client ID of the application
+     * @returns Promise resolving to the verification response with JWT tokens
+     * @throws {APIError} When authentication fails
+     * @throws {InvalidConfigError} When wallet account is not available
+     *
+     * @example
+     * ```typescript
+     * // Complete authentication in one call
+     * const authResult = await authAPI.authenticate("my-app-client-id");
+     * console.log(`Access token: ${authResult.access_token}`);
+     * console.log(`User ID: ${authResult.user.id}`);
+     * ```
+     */
+    async authenticate(clientId) {
+        if (!this.walletClient) {
+            throw new InvalidConfigError("Wallet client not set. Connect a wallet first.", "walletClient");
+        }
+        const account = this.walletClient.account;
+        if (!account) {
+            throw new InvalidConfigError("No account available in wallet client", "account");
+        }
+        // 1. Create challenge
+        const challenge = await this.createChallenge(account.address, clientId);
+        // 2. Sign the challenge message
+        const signature = await this.signChallenge(challenge.message);
+        // 3. Verify signature and get tokens
+        return await this.verifySignature(account.address, signature, challenge.nonce, clientId);
+    }
+    /**
+     * Signs a challenge message using the wallet client.
+     *
+     * Signs the provided message using the wallet's private key.
+     * This is used in the authentication flow to prove ownership of the wallet.
+     *
+     * @param message - The message to sign
+     * @returns Promise resolving to the signature
+     * @throws {InvalidConfigError} When wallet account is not available
+     * @throws {APIError} When signing fails
+     *
+     * @example
+     * ```typescript
+     * const challenge = await authAPI.createChallenge(address, clientId);
+     * const signature = await authAPI.signChallenge(challenge.message);
+     * console.log(`Signature: ${signature}`);
+     * ```
+     */
+    async signChallenge(message) {
+        if (!this.walletClient) {
+            throw new InvalidConfigError("Wallet client not set. Connect a wallet first.", "walletClient");
+        }
+        const account = this.walletClient.account;
+        if (!account) {
+            throw new InvalidConfigError("No account available in wallet client", "account");
+        }
+        // Sign the message using the wallet client
+        return await this.walletClient.signMessage({
+            account,
+            message,
+        });
+    }
+    /**
+     * Creates a challenge for frontend authentication.
+     *
+     * Generates a unique nonce and message that the user must sign with their wallet.
+     * This is the first step in the authentication flow for frontend applications.
+     *
+     * @param address - Wallet address of the user
+     * @param clientId - Client ID of the application
+     * @returns Promise resolving to the challenge response
+     * @throws {APIError} When challenge creation fails
+     *
+     * @example
+     * ```typescript
+     * const challenge = await authAPI.createChallenge(
+     *   "0x1234...",
+     *   "my-app-client-id"
+     * );
+     * console.log(`Challenge message: ${challenge.message}`);
+     * console.log(`Nonce: ${challenge.nonce}`);
+     * ```
+     */
+    async createChallenge(address, clientId) {
+        const responseBody = await this.makePublicRequest("/api/v1/auth/challenge", {
+            method: "POST",
+            body: JSON.stringify({
+                address,
+                client_id: clientId,
+                chain_id: this.chain.id,
+            }),
+        });
+        return {
+            nonce: responseBody.nonce,
+            message: responseBody.message,
+            expiresAt: responseBody.expires_at,
+        };
+    }
+    /**
+     * Verifies a signature for frontend authentication.
+     *
+     * Validates the signature against the challenge and returns JWT tokens for
+     * authenticated API access. This is the second step in the authentication flow.
+     *
+     * @param address - Wallet address of the user
+     * @param signature - Signature of the challenge message
+     * @param nonce - Nonce from the challenge response
+     * @param clientId - Client ID of the application
+     * @returns Promise resolving to the verification response with JWT tokens
+     * @throws {APIError} When signature verification fails
+     *
+     * @example
+     * ```typescript
+     * // First create a challenge
+     * const challenge = await authAPI.createChallenge(address, clientId);
+     *
+     * // User signs the challenge message with their wallet
+     * const signature = await wallet.signMessage(challenge.message);
+     *
+     * // Verify the signature and get tokens
+     * const authResult = await authAPI.verifySignature(
+     *   address,
+     *   signature,
+     *   challenge.nonce,
+     *   clientId
+     * );
+     *
+     * console.log(`Access token: ${authResult.accessToken}`);
+     * console.log(`User ID: ${authResult.user.id}`);
+     * ```
+     */
+    async verifySignature(address, signature, nonce, clientId) {
+        const responseBody = await this.makePublicRequest("/api/v1/auth/verify", {
+            method: "POST",
+            body: JSON.stringify({
+                address,
+                signature,
+                nonce,
+                client_id: clientId,
+                chain_id: this.chain.id,
+            }),
+        });
+        return {
+            accessToken: responseBody.access_token,
+            refreshToken: responseBody.refresh_token,
+            expiresAt: responseBody.expires_at,
+            user: {
+                id: responseBody.user.id,
+                address: responseBody.user.address,
+                username: responseBody.user.username,
+            },
+        };
+    }
+    /**
+     * Authenticates a backend service using a secret key.
+     *
+     * Returns JWT tokens for API access. This method is used for backend services
+     * that need to authenticate with the Monaco API Gateway.
+     *
+     * @param secretKey - Secret key of the application
+     * @returns Promise resolving to the backend auth response with JWT tokens
+     * @throws {APIError} When backend authentication fails
+     *
+     * @example
+     * ```typescript
+     * const backendAuth = await authAPI.authenticateBackend("my-secret-key");
+     * console.log(`Backend access token: ${backendAuth.accessToken}`);
+     * console.log(`Application: ${backendAuth.application.name}`);
+     * ```
+     */
+    async authenticateBackend(secretKey) {
+        const responseBody = await this.makePublicRequest("/api/v1/auth/backend", {
+            method: "POST",
+            body: JSON.stringify({
+                secret_key: secretKey,
+                chain_id: this.chain.id,
+            }),
+        });
+        return {
+            accessToken: responseBody.access_token,
+            expiresAt: responseBody.expires_at,
+            application: {
+                id: responseBody.application.id,
+                name: responseBody.application.name,
+                clientId: responseBody.application.client_id,
+            },
+        };
+    }
+    /**
+     * Refreshes an access token using a refresh token.
+     *
+     * Obtains a new access token using a valid refresh token. This is useful for
+     * maintaining long-term authentication without requiring the user to sign
+     * a new challenge.
+     *
+     * @param refreshToken - The refresh token to use
+     * @returns Promise resolving to new access and refresh tokens
+     * @throws {APIError} When token refresh fails
+     *
+     * @example
+     * ```typescript
+     * const newTokens = await authAPI.refreshToken(refreshToken);
+     * console.log(`New access token: ${newTokens.accessToken}`);
+     * console.log(`Expires at: ${new Date(newTokens.expiresAt * 1000)}`);
+     * ```
+     */
+    async refreshToken(refreshToken) {
+        const responseBody = await this.makePublicRequest("/api/v1/auth/refresh", {
+            method: "POST",
+            body: JSON.stringify({
+                refresh_token: refreshToken,
+            }),
+        });
+        return {
+            accessToken: responseBody.access_token,
+            expiresAt: responseBody.expires_at,
+        };
+    }
+    /**
+     * Revokes the current session's refresh token.
+     *
+     * Invalidates the refresh token associated with the current access token,
+     * preventing it from being used to obtain new access tokens. This is useful
+     * for logout functionality or when a token has been compromised.
+     *
+     * The server identifies the token to revoke from the access token in the
+     * Authorization header — no request body is needed.
+     *
+     * @returns Promise resolving when the token is revoked
+     * @throws {APIError} When token revocation fails
+     *
+     * @example
+     * ```typescript
+     * // After authentication
+     * const authResult = await authAPI.authenticate(clientId);
+     * await authAPI.revokeToken();
+     * console.log("Token revoked successfully");
+     * ```
+     */
+    async revokeToken() {
+        await this.makeAuthenticatedRequest("/api/v1/auth/revoke", {
+            method: "POST",
+        });
+    }
+}

package/dist/api/auth/index.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Auth API Module
+ */
+export { AuthAPIImpl } from "./api";

package/dist/api/auth/index.js

@@ -0,0 +1,4 @@
+/**
+ * Auth API Module
+ */
+export { AuthAPIImpl } from "./api";