Update CBS Mobile App codebase

src/services/api/cbsErrors.test.ts

@@ -0,0 +1,167 @@
+import {
+  CBS_ERROR_CODES,
+  CbsApiError,
+  describeError,
+  isCbsApiError,
+  isCbsErrorCode,
+  isClientErrorCode,
+  isRetryableError,
+} from './cbsErrors';
+
+describe('error code catalogue', () => {
+  it('covers all 45 documented codes, with no duplicates', () => {
+    expect(CBS_ERROR_CODES).toHaveLength(45);
+    expect(new Set(CBS_ERROR_CODES).size).toBe(45);
+  });
+
+  it('knows the cheque book codes', () => {
+    expect(isCbsErrorCode('CHEQUE_BOOK_NOT_AVAILABLE')).toBe(true);
+    expect(isCbsErrorCode('CHEQUE_BOOK_REQUEST_DECLINED')).toBe(true);
+  });
+
+  it('does not invite a retry on either cheque book refusal', () => {
+    // Neither is transient. The account cannot take a cheque book at all, or
+    // the bank understood the request and refused it — an identical retry gets
+    // an identical answer, and on a paid product that is worse than useless.
+    expect(isRetryableError('CHEQUE_BOOK_NOT_AVAILABLE')).toBe(false);
+    expect(isRetryableError('CHEQUE_BOOK_REQUEST_DECLINED')).toBe(false);
+  });
+
+  it('knows the statement codes', () => {
+    expect(isCbsErrorCode('INVALID_DATE_RANGE')).toBe(true);
+    expect(isCbsErrorCode('STATEMENT_VIEW_NOT_AVAILABLE')).toBe(true);
+  });
+
+  it('does not invite a retry on either statement refusal', () => {
+    // Both are the request's fault, not the bank's: one range is unusable and
+    // the other view does not exist. Repeating the identical call gets the
+    // identical answer, so the screen must offer a different range — or
+    // nothing — rather than a retry.
+    expect(isRetryableError('INVALID_DATE_RANGE')).toBe(false);
+    expect(isRetryableError('STATEMENT_VIEW_NOT_AVAILABLE')).toBe(false);
+  });
+
+  it('knows the payee-validate codes, which come from IMPS and not from CBS', () => {
+    expect(isCbsErrorCode('IMPS_UNAVAILABLE')).toBe(true);
+    expect(isCbsErrorCode('IMPS_INVALID_RESPONSE')).toBe(true);
+    expect(isCbsErrorCode('IMPS_CONFIGURATION_ERROR')).toBe(true);
+  });
+
+  it('invites a retry when the switch was unreachable, but not when it is misconfigured', () => {
+    // Validate saves nothing, so a failed call is safe to repeat — unlike the
+    // Positive Pay write below. A configuration fault is not the user's to fix.
+    expect(isRetryableError('IMPS_UNAVAILABLE')).toBe(true);
+    expect(isRetryableError('IMPS_INVALID_RESPONSE')).toBe(true);
+    expect(isRetryableError('IMPS_CONFIGURATION_ERROR')).toBe(false);
+  });
+
+  it('knows the Positive Pay codes', () => {
+    expect(isCbsErrorCode('POSITIVE_PAY_NOT_AVAILABLE')).toBe(true);
+    expect(isCbsErrorCode('CHEQUE_ALREADY_REGISTERED')).toBe(true);
+    expect(isCbsErrorCode('POSITIVE_PAY_DECLINED')).toBe(true);
+  });
+
+  it('knows the stop-payment codes', () => {
+    expect(isCbsErrorCode('CHEQUE_NOT_FOUND')).toBe(true);
+    expect(isCbsErrorCode('STOP_PAYMENT_NOT_AVAILABLE')).toBe(true);
+    expect(isCbsErrorCode('CHEQUE_ALREADY_STOPPED')).toBe(true);
+    expect(isCbsErrorCode('STOP_PAYMENT_DECLINED')).toBe(true);
+  });
+
+  it('does not invite a retry on a stop-payment refusal either', () => {
+    // Same reasoning as Positive Pay: stopping a cheque is a write. A second
+    // attempt after a refusal changes nothing, and after a success it returns
+    // CHEQUE_ALREADY_STOPPED — which reads like the customer's mistake.
+    expect(isRetryableError('CHEQUE_NOT_FOUND')).toBe(false);
+    expect(isRetryableError('CHEQUE_ALREADY_STOPPED')).toBe(false);
+    expect(isRetryableError('STOP_PAYMENT_DECLINED')).toBe(false);
+    expect(isRetryableError('STOP_PAYMENT_NOT_AVAILABLE')).toBe(false);
+  });
+
+  it('does not invite a retry on a Positive Pay refusal', () => {
+    // Registering a cheque is a write. A refusal is final, and offering "try
+    // again" would only produce CHEQUE_ALREADY_REGISTERED or a duplicate.
+    expect(isRetryableError('CHEQUE_ALREADY_REGISTERED')).toBe(false);
+    expect(isRetryableError('POSITIVE_PAY_DECLINED')).toBe(false);
+    expect(isRetryableError('POSITIVE_PAY_NOT_AVAILABLE')).toBe(false);
+  });
+
+  it('has copy for every code, so no failure renders as a blank toast', () => {
+    for (const code of CBS_ERROR_CODES) {
+      const copy = describeError(code);
+
+      expect(copy.title.length).toBeGreaterThan(0);
+      expect(copy.description.length).toBeGreaterThan(0);
+    }
+  });
+
+  it('recognises documented codes and rejects invented ones', () => {
+    expect(isCbsErrorCode('MPIN_LOCKED')).toBe(true);
+    expect(isCbsErrorCode('MPIN_UNLOCKED')).toBe(false);
+    expect(isCbsErrorCode(undefined)).toBe(false);
+  });
+
+  it('falls back to generic copy for an unknown or missing code', () => {
+    expect(describeError('SOMETHING_NEW').title).toBe(describeError(undefined).title);
+  });
+});
+
+describe('isRetryableError', () => {
+  // Retrying these has a real chance of working: the bank was unreachable or a
+  // breaker was open.
+  it('marks upstream and transport failures retryable', () => {
+    expect(isRetryableError('CBS_UNAVAILABLE')).toBe(true);
+    expect(isRetryableError('CONNECTOR_UNAVAILABLE')).toBe(true);
+    expect(isRetryableError('NETWORK_ERROR')).toBe(true);
+  });
+
+  // Retrying these can only waste an attempt, and against MPIN_LOCKED there is
+  // nothing to retry at all — the customer must visit a branch.
+  it('does not mark user-input or policy failures retryable', () => {
+    expect(isRetryableError('OTP_INVALID')).toBe(false);
+    expect(isRetryableError('INVALID_CREDENTIALS')).toBe(false);
+    expect(isRetryableError('MPIN_LOCKED')).toBe(false);
+    expect(isRetryableError('VALIDATION_ERROR')).toBe(false);
+  });
+});
+
+describe('CbsApiError', () => {
+  it('carries the code and the validation field map', () => {
+    const error = new CbsApiError({
+      status: 400,
+      code: 'VALIDATION_ERROR',
+      message: 'Request validation failed',
+      fieldErrors: { mobileNumber: 'must be exactly 10 digits' },
+    });
+
+    expect(isCbsApiError(error)).toBe(true);
+    expect(error.code).toBe('VALIDATION_ERROR');
+    expect(error.fieldErrors?.mobileNumber).toBe('must be exactly 10 digits');
+    expect(error.describe().title).toBe(describeError('VALIDATION_ERROR').title);
+  });
+
+  it('is a real Error, so it survives being thrown and caught', () => {
+    expect(() => {
+      throw new CbsApiError({ status: 0, code: 'NETWORK_ERROR', message: 'offline' });
+    }).toThrow('offline');
+  });
+
+  it('does not mistake a plain object for one', () => {
+    expect(isCbsApiError({ status: 400, code: 'OTP_INVALID', message: 'nope' })).toBe(false);
+  });
+});
+
+describe('isClientErrorCode', () => {
+  // These carry a transport detail, not a message anyone wrote for a customer.
+  it('is true for the codes the client synthesises', () => {
+    expect(isClientErrorCode('NETWORK_ERROR')).toBe(true);
+    expect(isClientErrorCode('REQUEST_TIMEOUT')).toBe(true);
+    expect(isClientErrorCode('UNKNOWN_ERROR')).toBe(true);
+  });
+
+  it('is false for codes the backend names, whose message is worth showing', () => {
+    expect(isClientErrorCode('OTP_INVALID')).toBe(false);
+    expect(isClientErrorCode('VALIDATION_ERROR')).toBe(false);
+    expect(isClientErrorCode(undefined)).toBe(false);
+  });
+});