@experian-ecs/connected-api-sdk 1.2.0 → 1.4.0

package/README.md

@@ -102,6 +102,7 @@ If using the sdk in the browser the `auth.getAccessToken` method will throw an e
       at async k.fetchWithAuth (file:/stack/trace/path)
       at async file:/stack/trace/path {
       data: {
+        type: AUTHENTICATION_ERROR,
         dev_url: 'https://experian.com/unity/docs/UNAUTHORIZED',
         code: 'UNAUTHORIZED',
         message: 'User Not Authorized'
@@ -143,21 +144,77 @@ If using the sdk in the browser the `auth.getAccessToken` method will throw an e
 
 ### Credit Attributes
 
+The Credit Attributes API supports both v1 and v2 endpoints with different response formats. Use the `version` parameter to specify which API version to use. Leaving blank defaults to `v1`
+
 * #### Retrieve attribute data for all historical reports
 
   ```tsx
+  // Defaults to V1
   await sdk.creditAttributes.getCreditAttributes();
+  
+    // V1 API - returns array of CreditAttributes objects
+  await sdk.creditAttributes.getCreditAttributes({ version: 'v1' });
+
+  // V2 API - returns CreditAttributes3B object with items array
+  await sdk.creditAttributes.getCreditAttributes({ version: 'v2' });
+  ```
+
+#### Credit Attribute version response validation
+
+  ```tsx
+  import { isV1GetCreditAttributesResponse, isV2GetCreditAttributesResponse } from '@experian-ecs/connected-api-sdk'
+
+  const { data, error } = await sdk.creditAttributes.getCreditAttributes({
+    version: 'v2'
+  });
+
+  if (data) {
+    if (isV2GetCreditAttributesResponse(data)) {
+      // TypeScript now knows data is CreditAttribute3B
+      const { items } = data;
+      items.forEach(item => {
+        console.log(`Attribute ID: ${item.id}`);
+        item.bureau_attributes.forEach(attribute => {
+          console.log(`Bureau: ${attribute.bureau}, Reported At: ${attribute.reported_at}, Categories: ${attribute.categories}, Attributes: ${attribute.attributes}`);
+        });
+      });
+    } else if (isV1GetCreditAttributesResponse(data)) {
+      // TypeScript now knows data is CreditAttribute[]
+      data.forEach(attribute => {
+        console.log(`Bureau: ${attribute.bureau}, Reported At: ${attribute.reported_at}, Categories: ${attribute.categories}, Attributes: ${attribute.attributes}`);
+      });
+    }
+  } else {
+    console.error(error);
+  }
   ```
 
 ### Credit Reports
 
+  The Credit Reports API supports both v1 and v2 endpoints with different response formats. Use the `version` parameter to specify which API version to use. Leaving blank defaults to `v1`
+
 * #### Retrieve all historical reports
 
   ```tsx
+  // Defaults to v1
   await sdk.creditReports.getReports({
     product_config_id: 'procfg_01',
     include_fields: 'report_display',
   })
+
+  // Version specific v1
+  await sdk.creditReports.getReports({
+    version: 'v1',
+    product_config_id: 'procfg_01',
+    include_fields: 'report_display',
+  });
+
+  // Version specific v2
+  await sdk.creditReports.getReports({
+    version: 'v2',
+    product_config_id: 'procfg_01',
+    report_date: '2025-09-01',
+  });
   ```
 
 * #### Retrieve a single report
@@ -167,18 +224,36 @@ If using the sdk in the browser the `auth.getAccessToken` method will throw an e
     id: '',
     include_fields: 'report_display',
   });
+
+  // Version specific v2
+  await sdk.creditReports.getReportById({
+    id: '1234',
+    version: 'v2'
+  });
   ```
 
 * #### Retrieve all historical report summaries
 
   ```tsx
   await sdk.creditReports.getReportMeta();
+
+  // Version specific v2
+  await sdk.creditReports.getReportMeta({
+    version: 'v2',
+    latest_only: true
+  });
   ```
 
 * #### Retrieve a single report summary
 
   ```tsx
   await sdk.creditReports.getReportMetaById({ id: '' });
+
+  // Version specific v2
+  await sdk.creditReports.getReportMetaById({
+    id: '123',
+    version: 'v2'
+  });
   ```
 
 * #### Order a new report
@@ -188,6 +263,12 @@ If using the sdk in the browser the `auth.getAccessToken` method will throw an e
     product_config_id: 'procfg_01',
     include_fields: 'report_display',
   });
+
+  // Version specific v2
+  await sdk.creditReports.orderReport({
+    version: 'v2',
+    product_config_id: 'procfg_01',
+  });
   ```
 
 * #### Mark a report as read
@@ -197,14 +278,30 @@ If using the sdk in the browser the `auth.getAccessToken` method will throw an e
     id: '',
     include_fields: 'report_display',
   });
+
+  // Version specific v2
+  await sdk.creditReports.markReportAsRead({
+    version: 'v2',
+    id: '1234',
+    disposition: { read_status: 'READ' }
+  });
   ```
 
 ### Credit Scores
 
+  The Credit Scores API supports both v1 and v2 endpoints with different response formats. Use the `version` parameter to specify which API version to use. Leaving blank defaults to `v1`
+
 * #### Retrieve all historical scores
 
   ```tsx
+  // Defaults to V1
   await sdk.creditScores.getCreditScores();
+
+  // V1 API - returns array of CreditScore objects
+  await sdk.creditScores.getCreditScores({ version: 'v1' });
+
+  // V2 API - returns CreditScore3B object with items array
+  await sdk.creditScores.getCreditScores({ version: 'v2' });
   ```
 
 * #### Retrieve all historical scores with factors information
@@ -222,9 +319,46 @@ If using the sdk in the browser the `auth.getAccessToken` method will throw an e
 * #### Order a new score
 
   ```tsx
+  // Defaults to V1
   await sdk.creditScores.orderCreditScore({ 
     product_config_id: 'procfg_01' 
   });
+
+  // V2 API
+  await sdk.creditScores.orderCreditScore({ 
+    product_config_id: 'procfg_01',
+    version: 'v2'
+  });
+  ```
+
+* #### Credit Score version response validation
+
+  ```tsx
+  import { isV1GetCreditScoresResponse, isV2GetCreditScoresResponse } from '@experian-ecs/connected-api-sdk'
+
+  const { data, error } = await sdk.creditScores.getCreditScores({
+    version: 'v2'
+  });
+
+  if (data) {
+    if (isV2GetCreditScoresResponse(data)) {
+      // TypeScript now knows data is CreditScore3B
+      const { items } = data;
+      items.forEach(item => {
+        console.log(`Score ID: ${item.id}`);
+        item.bureau_scores.forEach(score => {
+          console.log(`Bureau: ${score.bureau}, Score: ${score.score}`);
+        });
+      });
+    } else if (isV1GetCreditScoresResponse(data)) {
+      // TypeScript now knows data is CreditScore[]
+      data.forEach(score => {
+        console.log(`Score ID: ${score.score_id}, Score: ${score.score}`);
+      });
+    }
+  } else {
+    console.error(error);
+  }
   ```
 
 ### Credit Score Planner
@@ -533,18 +667,41 @@ If using the sdk in the browser the `auth.getAccessToken` method will throw an e
 
 ### Product Configs
 
+  The Product Config API supports both v1 and v2 endpoints with different response formats. Use the `version` parameter to specify which API version to use. Leaving blank defaults to `v1`.
+
+
 * #### Retrieve product configurations for a tenant
 
   ```tsx
+  // Defaults to V1
   await sdk.productConfigs.getProductConfigs();
+
+  // V1 API - returns product configurations
+  await sdk.productConfigs.getProductConfigs({version: 'v1'});
+
+  // V2 API - Includes Score Ranges and Disclosures array
+  await sdk.productConfigs.getProductConfigs({version: 'v2'});
   ```
 
 * #### Retrieve a single product configuration for a tenant
 
   ```tsx
+  // Defaults to V1
   await sdk.productConfigs.getProductConfigById({ 
     product_config_id: 'procfg_01' 
   });
+
+  // V1 API
+  await sdk.productConfigs.getProductConfigById({ 
+    product_config_id: 'procfg_01',
+    version: 'v1'
+  });
+
+  // V2 API - Includes Score Ranges and Disclosures array
+  await sdk.productConfigs.getProductConfigById({ 
+    product_config_id: 'procfg_01',
+    version: 'v2' 
+  });
   ```
 
 ### Registrations
@@ -604,7 +761,7 @@ If using the sdk in the browser the `auth.getAccessToken` method will throw an e
 
 ### Type Guards
 
-For typescript users, helper utility functions are exported in order to aid with type narrowing response types that return variable response models. An example use case can be viewed for [simulating a credit score](#simulate-a-scenario---fico-only)
+For typescript users, helper utility functions are exported in order to aid with type narrowing response types that return variable response models. An example use case can be viewed for [simulating a credit score](#simulate-a-scenario---fico-only) and [validating credit score responses](#credit-score-version-response-validation). 
 
 * Credit Score Planner
 
@@ -628,3 +785,32 @@ For typescript users, helper utility functions are exported in order to aid with
   function isFicoScenarioVariation(variation?: ScenarioVariation): variation is FicoScenarioVariation;
   function isVantageScenarioVariation(variation?: ScenarioVariation): variation is VantageScenarioVariation;
   ```
+
+* Credit Scores
+
+  ```tsx
+  function isValidApiVersion(version: string): version is ApiVersion;
+  function isCreditScore(data: unknown): data is CreditScore;
+  function isCreditScoreV2(data: unknown): data is CreditScore_V2;
+  function isBureauScore(data: unknown): data is BureauScore;
+  function isValidBureau(bureau: unknown): bureau is Bureau;
+  function isCreditScore3B(data: unknown): data is CreditScores_V2;
+  function isCreditScoreArray(data: unknown): data is CreditScore[];
+  function isV1GetCreditScoresResponse(data: unknown): data is GetCreditScoreResponse<'v1'>;
+  function isV2GetCreditScoresResponse(data: unknown): data is GetCreditScoreResponse<'v2'>;
+  function isV1PostCreditScoresResponse(data: unknown): data is PostCreditScoreResponse<'v1'>;
+  function isV2PostCreditScoresResponse(data: unknown): data is PostCreditScoreResponse<'v2'>;
+  ```
+
+* Credit Attributes
+ 
+  ```tsx
+  function isCreditAttribute(data: unknown): data is CreditAttributes;
+  function isCreditAttributeV2(data: unknown): data is CreditAttribute_V2;
+  function isBureauAttribute(data: unknown): data is BureauAttribute;
+  function isValidBureauAttribute(bureau: unknown): bureau is Bureau;
+  function isCreditAttributesV2(data: unknown): data is CreditAttribute_V2;
+  function isCreditAttributeArray(data: unknown): data is CreditAttribute[];
+  function isV1GetCreditAttributesResponse(data: unknown): data is GetCreditAttributeResponse<'v1'>;
+  function isV2GetCreditAttributesResponse(data: unknown): data is GetCreditAttributeResponse<'v2'>;
+  ```