@textrp/briij-js-sdk 42.0.0 → 43.1.0

package/src/client.ts

@@ -170,7 +170,19 @@ import {
     type IStateEventWithRoomId,
     SearchOrderBy,
 } from "./@types/search.ts";
-import { type ISynapseAdminDeactivateResponse, type ISynapseAdminWhoisResponse } from "./@types/synapse.ts";
+import {
+    type IBriijAdminCreatePremiumFeatureRequest,
+    type IBriijAdminPremiumFeaturesResponse,
+    type IBriijAdminUpdatePremiumFeatureRequest,
+    type IBriijLegacyEnabledFeaturesResponse,
+    type IBriijLegacyMyAddressResponse,
+    type IBriijMcreditsBalanceResponse,
+    type IBriijMcreditsFeaturesResponse,
+    type IBriijMcreditsSpendResponse,
+    type IBriijPremiumFeature,
+    type ISynapseAdminDeactivateResponse,
+    type ISynapseAdminWhoisResponse,
+} from "./@types/synapse.ts";
 import { type IHierarchyRoom } from "./@types/spaces.ts";
 import {
     type IPusher,
@@ -198,7 +210,14 @@ import {
     type LoginResponse,
     type LoginTokenPostResponse,
     type SSOAction,
+    WALLET_E2EE_RECOVERY_ACCOUNT_DATA_TYPE,
+    WALLET_IDENTITY_ACCOUNT_DATA_TYPE,
     XRPL_WALLET_LOGIN_TYPE,
+    type WalletE2eeRecoveryEnvelope,
+    type WalletIdentityAccountData,
+    type XrplAuthChallengeRequest,
+    type XrplAuthChallengeResponse,
+    type XrplAuthCompleteRequest,
     type XrplWalletChallengePayload,
 } from "./@types/auth.ts";
 import { TypedEventEmitter } from "./models/typed-event-emitter.ts";
@@ -248,13 +267,14 @@ import {
     type OidcClientConfig,
     validateAuthMetadataAndKeys,
 } from "./oidc/index.ts";
-import { configureXrplIdentityMinting, mintSoulboundIdentityNFT } from "./xrpl/identity.ts";
 import {
-    XRPL_VERIFIED_EVENT,
-    XRPL_VERIFY_ACCEPT_EVENT,
-    XRPL_VERIFY_REQUEST_EVENT,
-} from "./xrpl/verification.ts";
-import { configureXrplTrust } from "./xrpl/trust.ts";
+    getConfiguredXrplIdentityMintingConfig,
+    mintSoulboundIdentityNFT,
+    type XamanWalletAdapter,
+    type XrplIdentityMintingConfig,
+} from "./xrpl/identity.ts";
+import { XRPL_VERIFIED_EVENT, XRPL_VERIFY_ACCEPT_EVENT, XRPL_VERIFY_REQUEST_EVENT } from "./xrpl/verification.ts";
+import { type XrplTrustConfig } from "./xrpl/trust.ts";
 import { type EmptyObject } from "./@types/common.ts";
 import { UnsupportedDelayedEventsEndpointError, UnsupportedStickyEventsEndpointError } from "./errors.ts";
 import { type Transport } from "./matrixrtc/index.ts";
@@ -471,6 +491,17 @@ export interface ICreateClientOpts {
      * Defaults to the built-in global logger; see {@link DebugLogger} for an alternative.
      */
     logger?: Logger;
+
+    /**
+     * Optional per-client XRPL trust configuration.
+     */
+    xrplTrust?: Partial<XrplTrustConfig>;
+
+    /**
+     * Optional per-client XRPL identity minting configuration.
+     */
+    xrplIdentityMinting?: Partial<Omit<XrplIdentityMintingConfig, "homeserverBaseUrl" | "accessToken">>;
+    xamanWallet?: XamanWalletAdapter;
 }
 
 export interface IBriijClientCreateOpts extends ICreateClientOpts {
@@ -1291,6 +1322,9 @@ export class BriijClient extends TypedEventEmitter<EmittedEvents, ClientEventHan
     protected clientOpts?: IStoredClientOpts;
     protected clientWellKnownIntervalID?: ReturnType<typeof setInterval>;
     protected canResetTimelineCallback?: ResetTimelineCallback;
+    private xrplTrustConfig?: XrplTrustConfig;
+    private xrplIdentityMintingConfig: Partial<Omit<XrplIdentityMintingConfig, "homeserverBaseUrl" | "accessToken">> =
+        {};
 
     public canSupport = new Map<Feature, ServerSupport>();
 
@@ -1351,6 +1385,17 @@ export class BriijClient extends TypedEventEmitter<EmittedEvents, ClientEventHan
 
         const userId = opts.userId || null;
         this.credentials = { userId };
+        if (opts.xrplTrust) {
+            this.xrplTrustConfig = {
+                homeserverBaseUrl: opts.xrplTrust.homeserverBaseUrl ?? this.baseUrl,
+                accessToken: opts.xrplTrust.accessToken ?? opts.accessToken ?? "",
+                trustPath: opts.xrplTrust.trustPath,
+            };
+        }
+        this.xrplIdentityMintingConfig = {
+            ...(opts.xrplIdentityMinting ?? {}),
+            ...(opts.xamanWallet ? { xamanWallet: opts.xamanWallet } : {}),
+        };
 
         this.http = new BriijHttpApi(this as ConstructorParameters<typeof BriijHttpApi>[0], {
             fetchFn: opts.fetchFn,
@@ -6056,6 +6101,41 @@ export class BriijClient extends TypedEventEmitter<EmittedEvents, ClientEventHan
         return this.fallbackICEServerAllowed;
     }
 
+    /**
+     * Some briij deployments mount admin resources under `/_briij/admin` while
+     * Synapse defaults to `/_synapse/admin`. Try both prefixes to stay compatible.
+     */
+    private async authedRequestWithAdminPrefixes<T>(
+        method: Method,
+        adminSubPath: string,
+        queryParams?: QueryDict,
+        body?: Body,
+    ): Promise<T> {
+        const normalizedSubPath = adminSubPath.replace(/^\/+/, "");
+        const adminPrefixes = ["/_synapse/admin", "/_briij/admin"];
+        let lastError: unknown;
+
+        for (const adminPrefix of adminPrefixes) {
+            try {
+                return await this.http.authedRequest<T>(
+                    method,
+                    `${adminPrefix}/${normalizedSubPath}`,
+                    queryParams,
+                    body,
+                    { prefix: "" },
+                );
+            } catch (error) {
+                if (error instanceof BriijError && error.httpStatus === 404) {
+                    lastError = error;
+                    continue;
+                }
+                throw error;
+            }
+        }
+
+        throw lastError ?? new Error("Admin API endpoint not found");
+    }
+
     /**
      * Determines if the current user is an administrator of the Synapse homeserver.
      * Returns false if untrue or the homeserver does not appear to be a Synapse
@@ -6063,11 +6143,20 @@ export class BriijClient extends TypedEventEmitter<EmittedEvents, ClientEventHan
      * as a result.</strong>
      * @returns true if the user appears to be a Synapse administrator.
      */
-    public isSynapseAdministrator(): Promise<boolean> {
-        const path = utils.encodeUri("/_synapse/admin/v1/users/$userId/admin", { $userId: this.getUserId()! });
-        return this.http
-            .authedRequest<{ admin: boolean }>(Method.Get, path, undefined, undefined, { prefix: "" })
-            .then((r) => r.admin); // pull out the specific boolean we want
+    public async isSynapseAdministrator(): Promise<boolean> {
+        const adminSubPath = utils.encodeUri("v1/users/$userId/admin", { $userId: this.getUserId()! });
+        try {
+            const response = await this.authedRequestWithAdminPrefixes<{ admin: boolean }>(Method.Get, adminSubPath);
+            return response.admin;
+        } catch (error) {
+            if (error instanceof BriijError && error.httpStatus === 404) {
+                return false;
+            }
+            if (error instanceof Error && /Admin API endpoint not found/i.test(error.message)) {
+                return false;
+            }
+            throw error;
+        }
     }
 
     /**
@@ -6078,8 +6167,8 @@ export class BriijClient extends TypedEventEmitter<EmittedEvents, ClientEventHan
      * @returns the whois response - see Synapse docs for information.
      */
     public whoisSynapseUser(userId: string): Promise<ISynapseAdminWhoisResponse> {
-        const path = utils.encodeUri("/_synapse/admin/v1/whois/$userId", { $userId: userId });
-        return this.http.authedRequest(Method.Get, path, undefined, undefined, { prefix: "" });
+        const adminSubPath = utils.encodeUri("v1/whois/$userId", { $userId: userId });
+        return this.authedRequestWithAdminPrefixes(Method.Get, adminSubPath);
     }
 
     /**
@@ -6089,8 +6178,117 @@ export class BriijClient extends TypedEventEmitter<EmittedEvents, ClientEventHan
      * @returns the deactivate response - see Synapse docs for information.
      */
     public deactivateSynapseUser(userId: string): Promise<ISynapseAdminDeactivateResponse> {
-        const path = utils.encodeUri("/_synapse/admin/v1/deactivate/$userId", { $userId: userId });
-        return this.http.authedRequest(Method.Post, path, undefined, undefined, { prefix: "" });
+        const adminSubPath = utils.encodeUri("v1/deactivate/$userId", { $userId: userId });
+        return this.authedRequestWithAdminPrefixes(Method.Post, adminSubPath);
+    }
+
+    /**
+     * Lists active mCredits features for the authenticated user.
+     */
+    public getBriijMcreditsFeatures(): Promise<IBriijMcreditsFeaturesResponse> {
+        return this.http.authedRequest(Method.Get, "/mcredits/features", undefined, undefined, {
+            prefix: ClientPrefix.V3,
+        });
+    }
+
+    /**
+     * Retrieves the authenticated user's mCredits balance.
+     */
+    public getBriijMcreditsBalance(): Promise<IBriijMcreditsBalanceResponse> {
+        return this.http.authedRequest(Method.Get, "/mcredits/balance", undefined, undefined, {
+            prefix: ClientPrefix.V3,
+        });
+    }
+
+    /**
+     * Spends mCredits for a premium feature.
+     * @param featureKey - The premium feature identifier to spend against.
+     */
+    public spendBriijMcredits(featureKey: string): Promise<IBriijMcreditsSpendResponse> {
+        return this.http.authedRequest(
+            Method.Post,
+            "/mcredits/spend",
+            undefined,
+            { feature_key: featureKey },
+            {
+                prefix: ClientPrefix.V3,
+            },
+        );
+    }
+
+    /**
+     * Calls Briij's legacy-compatible endpoint to resolve a Matrix user to wallet/mcredit payload.
+     * @param matrixUserId - Matrix user ID used by legacy clients.
+     */
+    public getBriijLegacyMyAddress(matrixUserId: string): Promise<IBriijLegacyMyAddressResponse> {
+        return this.http.authedRequest(
+            Method.Post,
+            "/my-address",
+            undefined,
+            { address: matrixUserId },
+            { prefix: "" },
+        );
+    }
+
+    /**
+     * Calls Briij's legacy-compatible enabled-features endpoint.
+     * @param walletAddress - XRPL wallet address.
+     * @param network - Legacy network segment; defaults to `main`.
+     */
+    public getBriijLegacyEnabledFeatures(
+        walletAddress: string,
+        network = "main",
+    ): Promise<IBriijLegacyEnabledFeaturesResponse> {
+        const path = utils.encodeUri("/my-features/$walletAddress/$network/enabled", {
+            $walletAddress: walletAddress,
+            $network: network,
+        });
+        return this.http.authedRequest(Method.Get, path, undefined, undefined, { prefix: "" });
+    }
+
+    /**
+     * Lists mCredits premium features from Synapse admin APIs.
+     */
+    public async getBriijAdminPremiumFeatures(): Promise<IBriijPremiumFeature[]> {
+        const response = await this.authedRequestWithAdminPrefixes<IBriijAdminPremiumFeaturesResponse>(
+            Method.Get,
+            "v2/briij/premium_features",
+        );
+        return response.premium_features;
+    }
+
+    /**
+     * Creates an mCredits premium feature via Synapse admin APIs.
+     * @param body - Feature fields to create.
+     */
+    public createBriijAdminPremiumFeature(body: IBriijAdminCreatePremiumFeatureRequest): Promise<IBriijPremiumFeature> {
+        return this.authedRequestWithAdminPrefixes(Method.Post, "v2/briij/premium_features", undefined, body);
+    }
+
+    /**
+     * Updates an mCredits premium feature via Synapse admin APIs.
+     * @param featureKey - The premium feature key to update.
+     * @param body - Updatable feature fields.
+     */
+    public updateBriijAdminPremiumFeature(
+        featureKey: string,
+        body: IBriijAdminUpdatePremiumFeatureRequest,
+    ): Promise<IBriijPremiumFeature> {
+        const adminSubPath = utils.encodeUri("v2/briij/premium_features/$featureKey", {
+            $featureKey: featureKey,
+        });
+        return this.authedRequestWithAdminPrefixes(Method.Put, adminSubPath, undefined, body);
+    }
+
+    /**
+     * Soft-deactivates an mCredits premium feature via Synapse admin APIs.
+     * @param featureKey - The premium feature key to deactivate.
+     */
+    public deactivateBriijAdminPremiumFeature(featureKey: string): Promise<IBriijPremiumFeature> {
+        const adminSubPath = utils.encodeUri("v2/briij/premium_features/$featureKey", {
+            $featureKey: featureKey,
+        });
+        return this.authedRequestWithAdminPrefixes(Method.Delete, adminSubPath);
     }
 
     protected async fetchClientWellKnown(): Promise<void> {
@@ -6680,32 +6878,44 @@ export class BriijClient extends TypedEventEmitter<EmittedEvents, ClientEventHan
             type: loginType,
         });
 
-        if (response.access_token && response.user_id) {
-            this.http.opts.accessToken = response.access_token;
-            this.credentials = {
-                userId: response.user_id,
-            };
-            configureXrplTrust({
-                homeserverBaseUrl: this.baseUrl,
-                accessToken: response.access_token,
-            });
+        await this.applyLoginResponse(response, loginType);
+
+        return response;
+    }
+
+    private async applyLoginResponse(response: LoginResponse, loginType?: LoginRequest["type"]): Promise<void> {
+        if (!response.access_token || !response.user_id) {
+            return;
         }
 
+        this.http.opts.accessToken = response.access_token;
+        this.credentials = {
+            userId: response.user_id,
+        };
+        this.deviceId = response.device_id ?? this.deviceId;
+        this.xrplTrustConfig = {
+            homeserverBaseUrl: this.baseUrl,
+            accessToken: response.access_token,
+            trustPath: this.xrplTrustConfig?.trustPath,
+        };
+
         // After Xaman-backed SSO login, mint once and persist identity metadata in account_data.
-        if (loginType === "m.login.token" && response.access_token && response.user_id) {
-            configureXrplIdentityMinting({
-                homeserverBaseUrl: this.baseUrl,
-                accessToken: response.access_token,
-            });
+        if (loginType === "m.login.token") {
+            const fallbackMintingConfig = getConfiguredXrplIdentityMintingConfig();
+            const xamanWallet = this.xrplIdentityMintingConfig.xamanWallet ?? fallbackMintingConfig.xamanWallet;
 
             try {
-                await mintSoulboundIdentityNFT(response.user_id);
+                await mintSoulboundIdentityNFT(response.user_id, {
+                    ...fallbackMintingConfig,
+                    ...this.xrplIdentityMintingConfig,
+                    homeserverBaseUrl: this.baseUrl,
+                    accessToken: response.access_token,
+                    xamanWallet,
+                });
             } catch (error) {
                 logger.warn("XRPL identity NFT minting skipped/failed", error);
             }
         }
-
-        return response;
     }
 
     /**
@@ -6724,32 +6934,120 @@ export class BriijClient extends TypedEventEmitter<EmittedEvents, ClientEventHan
     }
 
     /**
-     * @param user - Matrix user ID localpart or fully qualified MXID.
-     * @param walletAddress - XRPL/Xahau classic wallet address.
-     * @param signature - Hex signature for the challenge message.
-     * @param challenge - Signed challenge payload.
-     * @param network - Ledger network identifier. Defaults to `xrpl`.
+     * Request an XRPL login challenge from the homeserver.
+     *
+     * The briij homeserver responds with HTTP 401 as the successful challenge
+     * response, so this helper normalizes that into a resolved promise.
+     */
+    public async getXrplAuthChallenge(
+        request: Omit<XrplAuthChallengeRequest, "type">,
+    ): Promise<XrplAuthChallengeResponse> {
+        try {
+            const response = (await this.loginRequest({
+                ...request,
+                type: XRPL_WALLET_LOGIN_TYPE,
+            })) as unknown as XrplAuthChallengeResponse;
+            if (typeof response.session === "string" && typeof response.challenge === "string") {
+                return response;
+            }
+        } catch (error) {
+            if (error instanceof BriijError && error.httpStatus === 401) {
+                const session = error.data?.session;
+                const challenge = error.data?.challenge;
+                if (typeof session === "string" && typeof challenge === "string") {
+                    return { session, challenge };
+                }
+            }
+            throw error;
+        }
+
+        throw new Error("XRPL challenge response was not returned by homeserver");
+    }
+
+    /**
+     * Complete XRPL login using the previously issued challenge session.
+     *
      * @returns Promise which resolves to a LoginResponse object.
      * @returns Rejects: with an error response.
      */
-    public loginWithXrplWallet(
+    public completeXrplAuth(request: Omit<XrplAuthCompleteRequest, "type">): Promise<LoginResponse> {
+        return this.loginRequest({
+            ...request,
+            type: XRPL_WALLET_LOGIN_TYPE,
+        });
+    }
+
+    /**
+     * Store a chain-agnostic wallet recovery envelope in account data.
+     *
+     * This uses a stable account-data type and does not affect core E2EE state.
+     *
+     * @param envelope - Wallet recovery envelope payload.
+     */
+    public async setWalletRecoveryEnvelope(envelope: WalletE2eeRecoveryEnvelope): Promise<EmptyObject> {
+        return await this.setAccountData(WALLET_E2EE_RECOVERY_ACCOUNT_DATA_TYPE, envelope);
+    }
+
+    /**
+     * Fetch wallet recovery envelope directly from the homeserver.
+     *
+     * @returns The stored envelope, or null if not found.
+     */
+    public getWalletRecoveryEnvelopeFromServer(): Promise<WalletE2eeRecoveryEnvelope | null> {
+        return this.getAccountDataFromServer(WALLET_E2EE_RECOVERY_ACCOUNT_DATA_TYPE);
+    }
+
+    /**
+     * Fetch canonical wallet identity metadata from the homeserver.
+     *
+     * @returns Wallet identity metadata, or null if not found.
+     */
+    public getWalletIdentityFromServer(): Promise<WalletIdentityAccountData | null> {
+        return this.getAccountDataFromServer(WALLET_IDENTITY_ACCOUNT_DATA_TYPE);
+    }
+
+    /**
+     * @deprecated Use `getXrplAuthChallenge` + `completeXrplAuth` for explicit
+     * two-step XRPL login flow. This wrapper now expects `challenge` to include
+     * the `session` and optional `public_key`.
+     */
+    public async loginWithXrplWallet(
         user: string,
         walletAddress: string,
         signature: string,
         challenge: string | XrplWalletChallengePayload,
         network = "xrpl",
     ): Promise<LoginResponse> {
-        return this.login(XRPL_WALLET_LOGIN_TYPE, {
-            user: user,
+        let parsedChallenge: Partial<XrplWalletChallengePayload> | null = null;
+        if (typeof challenge === "string") {
+            try {
+                parsedChallenge = JSON.parse(challenge) as Partial<XrplWalletChallengePayload>;
+            } catch {
+                throw new Error("XRPL challenge must be JSON with a session field");
+            }
+        } else {
+            parsedChallenge = challenge;
+        }
+
+        const session = parsedChallenge?.session;
+        if (!session) {
+            throw new Error("XRPL challenge payload is missing session; call getXrplAuthChallenge first");
+        }
+
+        const response = await this.completeXrplAuth({
+            user,
             identifier: {
                 type: "m.id.user",
-                user: user,
+                user,
             },
-            wallet_address: walletAddress,
-            signature: signature,
-            challenge: typeof challenge === "string" ? challenge : JSON.stringify(challenge),
-            network: network,
+            session,
+            address: walletAddress,
+            signature,
+            public_key: parsedChallenge?.public_key,
+            network,
         });
+        await this.applyLoginResponse(response, XRPL_WALLET_LOGIN_TYPE);
+        return response;
     }
 
     /**