feat: implement client to abstract bridge calls

This PR implements a client for the bridge service, which will be used
by the master Bitgo Express server to forward certain requests to the
bridge service.

A base HTTP Client has been implemented and the the existing keyProvider
has been refactored to extend it as well.

Tests have been added for the new client and existing tests for the
keyProvider have been updated whereby necessary(error handling changes).

Ticket: WCN-743

Author: pranishnepal

src/__tests__/api/advancedWalletManager/keyProviderClient.test.ts

@@ -93,7 +93,7 @@ describe('postMpcV2Key', () => {
 
     response.status.should.equal(500);
     response.body.should.have.property('error', 'Internal Server Error');
-    response.body.should.have.property('details', 'This is an error message');
+    response.body.details.should.match(/This is an error message/);
   });
 
   it('should handle unexpected key provider errors', async () => {
@@ -106,10 +106,7 @@ describe('postMpcV2Key', () => {
 
     response.status.should.equal(500);
     response.body.should.have.property('error', 'Internal Server Error');
-    response.body.should.have.property(
-      'details',
-      'key provider returned unexpected response. 502: Unexpected error',
-    );
+    response.body.details.should.match(/502.*Unexpected error/);
   });
 });
 
@@ -150,27 +147,17 @@ describe('KeyProviderClient.generateKey', () => {
   });
 
   [
-    {
-      url: endPointPath,
-      statusCode: 400,
-      mockedError: 'bad request',
-      expectedError: 'bad request',
-    },
-    { url: endPointPath, statusCode: 404, mockedError: 'not found', expectedError: 'not found' },
-    { url: endPointPath, statusCode: 409, mockedError: 'conflict', expectedError: 'conflict' },
-    {
-      url: endPointPath,
-      statusCode: 500,
-      mockedError: 'internal error',
-      expectedError: 'internal error',
-    },
-  ].forEach(({ url, statusCode, mockedError, expectedError }) => {
+    { url: endPointPath, statusCode: 400, mockedError: 'bad request' },
+    { url: endPointPath, statusCode: 404, mockedError: 'not found' },
+    { url: endPointPath, statusCode: 409, mockedError: 'conflict' },
+    { url: endPointPath, statusCode: 500, mockedError: 'internal error' },
+  ].forEach(({ url, statusCode, mockedError }) => {
     it(`should bubble up ${statusCode} errors`, async () => {
       const nockMocked = nock(keyProviderUrl)
         .post(url)
         .reply(statusCode, { message: mockedError })
         .persist();
-      await client.generateKey(params).should.be.rejectedWith(expectedError);
+      await client.generateKey(params).should.be.rejectedWith(new RegExp(mockedError));
       nockMocked.done();
     });
   });
@@ -222,17 +209,17 @@ describe('KeyProviderClient.sign', () => {
   });
 
   [
-    { statusCode: 400, mockedError: 'bad request', expectedError: 'bad request' },
-    { statusCode: 404, mockedError: 'not found', expectedError: 'not found' },
-    { statusCode: 409, mockedError: 'conflict', expectedError: 'conflict' },
-    { statusCode: 500, mockedError: 'internal error', expectedError: 'internal error' },
-  ].forEach(({ statusCode, mockedError, expectedError }) => {
+    { statusCode: 400, mockedError: 'bad request' },
+    { statusCode: 404, mockedError: 'not found' },
+    { statusCode: 409, mockedError: 'conflict' },
+    { statusCode: 500, mockedError: 'internal error' },
+  ].forEach(({ statusCode, mockedError }) => {
     it(`should bubble up ${statusCode} errors`, async () => {
       const nockMocked = nock(keyProviderUrl)
         .post(endPointPath)
         .reply(statusCode, { message: mockedError })
         .persist();
-      await client.sign(params).should.be.rejectedWith(expectedError);
+      await client.sign(params).should.be.rejectedWith(new RegExp(mockedError));
       nockMocked.done();
     });
   });

src/__tests__/api/master/bridgeClient.test.ts

@@ -0,0 +1,317 @@
+import nock from 'nock';
+import 'should';
+import { OsoBridgeClient } from '../../../masterBitgoExpress/clients/bridgeClient';
+import { BridgeJobResponse } from '../../../masterBitgoExpress/clients/bridgeClient.types';
+import { KeySource } from '../../../shared/types';
+
+const BASE_URL = 'http://bridge.invalid';
+const TIMEOUT = 60000;
+
+const mockJob: BridgeJobResponse = {
+  jobId: 'job-123',
+  status: 'awaiting_bitgo',
+  version: 1,
+  coin: 'tbtc',
+  operationType: 'multisig_sign',
+  createdAt: '2026-06-09T00:00:00.000Z',
+  updatedAt: '2026-06-09T00:00:00.000Z',
+};
+
+describe('OsoBridgeClient', () => {
+  let client: OsoBridgeClient;
+
+  before(() => {
+    nock.disableNetConnect();
+    client = new OsoBridgeClient(BASE_URL, TIMEOUT);
+  });
+
+  afterEach(() => nock.cleanAll());
+
+  describe('constructor', () => {
+    it('throws when url is empty', () => {
+      (() => new OsoBridgeClient('', TIMEOUT)).should.throw(
+        'OsoBridgeClient: awmAsyncUrl is required',
+      );
+    });
+
+    it('strips trailing slash from url', () => {
+      const c = new OsoBridgeClient(`${BASE_URL}/`, TIMEOUT);
+      nock(BASE_URL).get('/health').reply(200, { status: 'ok' });
+      return c.health().should.be.fulfilled();
+    });
+  });
+
+  describe('submit()', () => {
+    it('sets X-OSO-Source for a single source', async () => {
+      const n = nock(BASE_URL)
+        .post('/api/tbtc/multisig/sign')
+        .matchHeader('x-oso-source', 'user')
+        .reply(202, { jobId: 'job-123' });
+
+      await client.submit({
+        path: '/api/tbtc/multisig/sign',
+        body: { foo: 'bar' },
+        sources: [KeySource.USER],
+        operationType: 'multisig_sign',
+      });
+
+      n.done();
+    });
+
+    it('sets X-OSO-Source as comma-joined for multiple sources', async () => {
+      const n = nock(BASE_URL)
+        .post('/api/tbtc/key/independent')
+        .matchHeader('x-oso-source', 'user,backup')
+        .reply(202, { jobId: 'job-456' });
+
+      await client.submit({
+        path: '/api/tbtc/key/independent',
+        body: { foo: 'bar' },
+        sources: [KeySource.USER, KeySource.BACKUP],
+        operationType: 'multisig_keygen',
+      });
+
+      n.done();
+    });
+
+    it('sets X-OSO-Operation header', async () => {
+      const n = nock(BASE_URL)
+        .post('/api/tbtc/multisig/sign')
+        .matchHeader('x-oso-operation', 'multisig_sign')
+        .reply(202, { jobId: 'job-123' });
+
+      await client.submit({
+        path: '/api/tbtc/multisig/sign',
+        body: { foo: 'bar' },
+        sources: [KeySource.USER],
+        operationType: 'multisig_sign',
+      });
+
+      n.done();
+    });
+
+    it('sets X-Idempotency-Key when provided', async () => {
+      const n = nock(BASE_URL)
+        .post('/api/tbtc/multisig/sign')
+        .matchHeader('x-idempotency-key', 'idem-key-abc')
+        .reply(202, { jobId: 'job-123' });
+
+      await client.submit({
+        path: '/api/tbtc/multisig/sign',
+        body: { foo: 'bar' },
+        sources: [KeySource.USER],
+        operationType: 'multisig_sign',
+        idempotencyKey: 'idem-key-abc',
+      });
+
+      n.done();
+    });
+
+    it('omits X-Idempotency-Key when not provided', async () => {
+      const n = nock(BASE_URL)
+        .post('/api/tbtc/multisig/sign')
+        .matchHeader('x-idempotency-key', (val) => val === undefined)
+        .reply(202, { jobId: 'job-123' });
+
+      await client.submit({
+        path: '/api/tbtc/multisig/sign',
+        body: { foo: 'bar' },
+        sources: [KeySource.USER],
+        operationType: 'multisig_sign',
+      });
+
+      n.done();
+    });
+
+    it('forwards body as-is', async () => {
+      const body = { signablePayload: 'deadbeef', walletId: 'w-123' };
+      const n = nock(BASE_URL)
+        .post('/api/tbtc/multisig/sign', body)
+        .reply(202, { jobId: 'job-123' });
+
+      await client.submit({
+        path: '/api/tbtc/multisig/sign',
+        body,
+        sources: [KeySource.USER],
+        operationType: 'multisig_sign',
+      });
+
+      n.done();
+    });
+
+    it('returns jobId from response', async () => {
+      nock(BASE_URL).post('/api/tbtc/multisig/sign').reply(202, { jobId: 'job-789' });
+
+      const result = await client.submit({
+        path: '/api/tbtc/multisig/sign',
+        body: {},
+        sources: [KeySource.USER],
+        operationType: 'multisig_sign',
+      });
+
+      result.should.have.property('jobId', 'job-789');
+    });
+
+    it('normalizes path without leading slash', async () => {
+      const n = nock(BASE_URL).post('/api/tbtc/multisig/sign').reply(202, { jobId: 'job-123' });
+
+      await client.submit({
+        path: 'api/tbtc/multisig/sign',
+        body: {},
+        sources: [KeySource.USER],
+        operationType: 'multisig_sign',
+      });
+
+      n.done();
+    });
+
+    it('throws on invalid response shape', async () => {
+      nock(BASE_URL).post('/api/tbtc/multisig/sign').reply(202, { notAJobId: true });
+
+      await client
+        .submit({
+          path: '/api/tbtc/multisig/sign',
+          body: {},
+          sources: [KeySource.USER],
+          operationType: 'multisig_sign',
+        })
+        .should.be.rejectedWith(/bridge returned unexpected response for submit/);
+    });
+
+    it('throws on 400', async () => {
+      nock(BASE_URL).post('/api/tbtc/multisig/sign').reply(400, { message: 'bad input' });
+
+      await client
+        .submit({
+          path: '/api/tbtc/multisig/sign',
+          body: {},
+          sources: [KeySource.USER],
+          operationType: 'multisig_sign',
+        })
+        .should.be.rejectedWith('bad input');
+    });
+  });
+
+  describe('getJob()', () => {
+    it('GETs /job/:jobId and returns BridgeJobResponse', async () => {
+      const n = nock(BASE_URL).get('/job/job-123').reply(200, mockJob);
+
+      const result = await client.getJob('job-123');
+
+      result.should.have.property('jobId', 'job-123');
+      result.should.have.property('status', 'awaiting_bitgo');
+      n.done();
+    });
+
+    it('throws on 404', async () => {
+      nock(BASE_URL).get('/job/missing').reply(404, { message: 'job not found' });
+
+      await client.getJob('missing').should.be.rejectedWith('job not found');
+    });
+
+    it('throws on invalid response shape', async () => {
+      nock(BASE_URL).get('/job/job-123').reply(200, { bad: 'shape' });
+
+      await client
+        .getJob('job-123')
+        .should.be.rejectedWith(/bridge returned unexpected response for getJob/);
+    });
+  });
+
+  describe('updateJob()', () => {
+    it('PATCHes /job/:jobId with correct body', async () => {
+      const n = nock(BASE_URL)
+        .patch('/job/job-123', { version: 1, status: 'complete', result: { txid: 'abc' } })
+        .reply(204);
+
+      await client.updateJob({
+        jobId: 'job-123',
+        version: 1,
+        status: 'complete',
+        result: { txid: 'abc' },
+      });
+
+      n.done();
+    });
+
+    it('returns void on 204', async () => {
+      nock(BASE_URL).patch('/job/job-123').reply(204);
+
+      const result = await client.updateJob({
+        jobId: 'job-123',
+        version: 1,
+        status: 'failed',
+        error: 'timeout',
+      });
+
+      (result === undefined).should.be.true();
+    });
+
+    it('throws on 409', async () => {
+      nock(BASE_URL).patch('/job/job-123').reply(409, { message: 'version conflict' });
+
+      await client
+        .updateJob({ jobId: 'job-123', version: 1, status: 'complete' })
+        .should.be.rejectedWith('version conflict');
+    });
+  });
+
+  describe('listJobs()', () => {
+    it('GETs /jobs without query when status omitted', async () => {
+      const n = nock(BASE_URL)
+        .get('/jobs')
+        .reply(200, { jobs: [mockJob] });
+
+      const result = await client.listJobs({});
+
+      result.jobs.should.have.length(1);
+      result.jobs[0].should.have.property('jobId', 'job-123');
+      n.done();
+    });
+
+    it('GETs /jobs?status=awaiting_bitgo when status provided', async () => {
+      const n = nock(BASE_URL)
+        .get('/jobs')
+        .query({ status: 'awaiting_bitgo' })
+        .reply(200, { jobs: [mockJob] });
+
+      const result = await client.listJobs({ status: 'awaiting_bitgo' });
+
+      result.jobs.should.have.length(1);
+      n.done();
+    });
+
+    it('returns empty array when jobs list is empty', async () => {
+      nock(BASE_URL).get('/jobs').reply(200, { jobs: [] });
+
+      const result = await client.listJobs({});
+
+      result.jobs.should.have.length(0);
+    });
+  });
+
+  describe('health()', () => {
+    it('GETs /health and returns body', async () => {
+      const n = nock(BASE_URL).get('/health').reply(200, { status: 'ok' });
+
+      const result = await client.health();
+
+      result.should.have.property('status', 'ok');
+      n.done();
+    });
+  });
+
+  describe('error handling', () => {
+    it('throws on 401', async () => {
+      nock(BASE_URL).get('/job/job-123').reply(401, { message: 'unauthorized' });
+
+      await client.getJob('job-123').should.be.rejectedWith('unauthorized');
+    });
+
+    it('throws with status code on unexpected status', async () => {
+      nock(BASE_URL).get('/job/job-123').reply(503, { message: 'service unavailable' });
+
+      await client.getJob('job-123').should.be.rejectedWith(/503/);
+    });
+  });
+});