@experian-ecs/connected-api-sdk 1.0.1

package/LICENSE.md

@@ -0,0 +1,12 @@
+/** 
+ * Copyright © 2025 EXPERIAN. All rights reserved.
+ *
+ * This code is provided for inclusion in a website and is intended solely for execution by end
+ * users in web browsers or on an application server. Unauthorized modification, redistribution, or any other use is prohibited. This
+ * notice should be included with any use of this code.
+ *
+ * THIS CODE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
+ * BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
+ * IN NO EVENT SHALL CSIDENTITY CORPORATION OR ITS AFFILIATES BE LIABLE FOR ANY CLAIM, DAMAGES, OR
+ * OTHER LIABILITY ARISING FROM OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS CODE.
+ */

package/LICENSE.txt

@@ -0,0 +1,12 @@
+/** 
+ * Copyright © 2025 EXPERIAN. All rights reserved.
+ *
+ * This code is provided for inclusion in a website and is intended solely for execution by end
+ * users in web browsers or on an application server. Unauthorized modification, redistribution, or any other use is prohibited. This
+ * notice should be included with any use of this code.
+ *
+ * THIS CODE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
+ * BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
+ * IN NO EVENT SHALL CSIDENTITY CORPORATION OR ITS AFFILIATES BE LIABLE FOR ANY CLAIM, DAMAGES, OR
+ * OTHER LIABILITY ARISING FROM OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS CODE.
+ */

package/README.md

@@ -0,0 +1,606 @@
+# Connected Solutions Experience API SDK
+
+1. [Authentication](#authentication)
+    1. [NodeJS](#nodejs)
+    2. [Browser](#browser)
+2. [Usage](#usage)
+    1. [Response format](#response-format)
+    2. [Alerts](#alerts)
+    3. [Credit Reports](#credit-reports)
+    4. [Credit Attributes](#credit-attributes)
+    5. [Credit Scores](#credit-scores)
+    6. [Credit Score Planner](#credit-score-planner)
+    7. [Credit Score Simulator](#credit-score-simulator)
+    8. [Customer Auth](#customer-auth)
+    9. [Customers](#customers)
+    10. [Entitlements](#entitlements)
+    11. [Product Configs](#product-configs)
+    12. [Registrations](#registrations)
+3. [Utilities](#utilities)
+    1. [Type Guards](#type-guards)
+
+## Authentication
+
+### NodeJs
+
+* #### Instantiate the sdk
+
+  ```tsx
+  import { createSDK } from '@experian-ecs/connected-api-sdk'
+
+  // environment can either be 'PRODUCTION' or 'SANDBOX'
+  const sdk = createSDK({ environment: 'PRODUCTION' })
+  ```
+
+* #### Retrieve an access token
+
+  ```tsx
+  const tokenRequest = await sdk.auth.getAccessToken({
+    grantType: 'trusted_partner',
+    clientId: process.env.SDK_CLIENT_ID!,
+    clientSecret: process.env.SDK_CLIENT_SECRET!,
+    customerId: 'cus_01'
+  });
+  ```
+
+* #### Set the authentication token on the sdk instance
+
+  ```tsx
+  sdk.setConfig({
+    token: tokenRequest.data?.access_token
+  });
+  ```
+
+### Browser
+
+If using the sdk in the browser the `auth.getAccessToken` method will throw an error to prevent the user from exposing their client id and client secret in the public browser environment. Because of this, the user will need to retrieve a valid oauth token outside of the sdk and provide it to the configuration object passed to `createSDK`.
+
+* #### Instantiate the sdk with a token
+
+  ```tsx
+  import { createSDK } from '@experian-ecs/connected-api-sdk'
+
+  // environment can either be 'PRODUCTION' or 'SANDBOX'
+  const sdk = createSDK({ 
+    environment: 'PRODUCTION',
+    token: 'your-oauth-token'
+  })
+  ```
+
+## Usage
+
+### Response format
+
+* All calls to sdk methods return a single object with `data`, `error`, `meta` keys.
+
+  ```tsx
+  const { data, error, meta } = await sdk.creditScores.getCreditScores();
+  ```
+
+* Success example
+
+  ```tsx
+  { 
+    data: [ {...}, {...} ],
+    error: undefined,
+    meta: {
+      status: 200,
+      statusText: 'OK'
+    }
+  }
+  ```
+
+* Error example
+
+  ```tsx
+  {
+    data: undefined,
+    error: [ConnectedSolutionsClientAuthError]: User Not Authorized
+      at ft.St [as generateError] (file:/stack/trace/path)
+      at k.fetchRequest (file:/stack/trace/path)
+      at process.processTicksAndRejections (node:internal/process/task_queues:105:5)
+      at async k.fetchWithAuth (file:/stack/trace/path)
+      at async file:/stack/trace/path {
+      data: {
+        dev_url: 'https://experian.com/unity/docs/UNAUTHORIZED',
+        code: 'UNAUTHORIZED',
+        message: 'User Not Authorized'
+      },
+      status: 401
+    },
+    meta: { 
+      status: 401, 
+      statusText: 'User Not Authorized' 
+    }
+  }
+  ```
+
+### Alerts
+
+* #### Retrieve all alerts
+
+  ```tsx
+  await sdk.alerts.getAlerts();
+  ```
+
+* #### Retrieve a single alert
+
+  ```tsx
+  await sdk.alerts.getAlertById({ id: 'alr_01' });
+  ```
+
+* #### Retrieve counts for all alerts
+
+  ```tsx
+  await sdk.alerts.getAlertCounts();
+  ```
+
+* #### Mark an alert as read
+
+  ```tsx
+  await sdk.alerts.markAlertAsRead({ id: 'alr_01' });
+  ```
+
+### Credit Attributes
+
+* #### Retrieve attribute data for all historical reports
+
+  ```tsx
+  await sdk.creditAttributes.getCreditAttributes();
+  ```
+
+### Credit Reports
+
+* #### Retrieve all historical reports
+
+  ```tsx
+  await sdk.creditReports.getReports({
+    product_config_id: 'procfg_01',
+    include_fields: 'report_display',
+  })
+  ```
+
+* #### Retrieve a single report
+
+  ```tsx
+  await sdk.creditReports.getReportById({
+    id: '',
+    include_fields: 'report_display',
+  });
+  ```
+
+* #### Retrieve all historical report summaries
+
+  ```tsx
+  await sdk.creditReports.getReportMeta();
+  ```
+
+* #### Retrieve a single report summary
+
+  ```tsx
+  await sdk.creditReports.getReportMetaById({ id: '' });
+  ```
+
+* #### Order a new report
+
+  ```tsx
+  await sdk.creditReports.orderReport({
+    product_config_id: 'procfg_01',
+    include_fields: 'report_display',
+  });
+  ```
+
+* #### Mark a report as read
+
+  ```tsx
+  await sdk.creditReports.markReportAsRead({
+    id: '',
+    include_fields: 'report_display',
+  });
+  ```
+
+### Credit Scores
+
+* #### Retrieve all historical scores
+
+  ```tsx
+  await sdk.creditScores.getCreditScores();
+  ```
+
+* #### Retrieve all historical scores with factors information
+
+  ```tsx
+  await sdk.creditScores.getCreditScores({ include_factors: true });
+  ```
+
+* #### Retrieve all historical scores with ingredients information - FICO Only
+
+  ```tsx
+  await sdk.creditScores.getCreditScores({ include_ingredients: true });
+  ```
+
+* #### Order a new score
+
+  ```tsx
+  await sdk.creditScores.orderCreditScore({ 
+    product_config_id: 'procfg_01' 
+  });
+  ```
+
+### Credit Score Planner
+
+* #### Get current plan
+
+  ```tsx
+  await sdk.creditScorePlanner.getCreditScorePlan({ 
+    product_config_id: 'procfg_01' 
+  });
+  ```
+
+* #### Get timeline options for creating a plan
+
+  ```tsx
+  // FICO
+  await sdk.creditScorePlanner.getCreditScorePlanRevisions({ 
+    product_config_id: 'procfg_01',
+    target_score: 800
+  });
+
+  // VANTAGE
+  await sdk.creditScorePlanner.getCreditScorePlanRevisions({ 
+    product_config_id: 'procfg_01',
+    max_actions_per_plan: 5
+  });
+  ```
+
+* #### Create a new plan
+
+  ```tsx
+  const { data, error } = await sdk.creditScorePlanner.getCreditScorePlanRevisions({
+    product_config_id: 'procfg_01',
+    target_score: 800,
+  })
+
+  if(data) {
+    const [ selectedRevision, ...revisions ] = data;
+
+    await sdk.creditScorePlanner.createCreditScorePlan({
+      product_config_id: 'procfg_01',
+      ...selectedRevision
+    });  
+
+  } else {
+    console.error(error)
+  }
+  ```
+
+* #### Delete your current plan
+
+  ```tsx
+  await sdk.creditScorePlanner.deleteCreditScorePlan({ 
+    product_config_id: 'procfg_01' 
+  });
+  ```
+
+### Credit Score Simulator
+
+* #### Get all scenarios available for simulation
+
+  Vantage will return both the simulations and their simulated results from this method.
+
+  FICO will return only the possible simulations, and will require an additional call to `simulateScenario` to get the results of the selected simulation. Example below.
+
+  ```tsx
+  await sdk.creditScoreSimulator.getSimulations({ 
+    product_config_id: 'procfg_01' 
+  });
+  ```
+
+* #### Simulate a scenario - FICO Only
+
+  ```tsx
+  import { isFicoScenario } from '@experian-ecs/connected-api-sdk'
+
+  const { data, error } = await sdk.creditScoreSimulator.getSimulations({
+    product_config_id: 'procfg_01'
+  })
+
+  if(data){
+    const {
+      simulations: [ selectedScenario, ...simulations ]
+    } = data;
+
+    if(isFicoScenario(selectedScenario)){
+      const { scenario, variations } = selectedScenario;
+
+      const simulationResult = await sdk.creditScoreSimulator.simulateScenario({
+        product_config_id: 'procfg_01',
+        scenario,
+        variations
+      })
+    }
+  } else {
+    console.error(error)
+  }
+  ```
+
+### Customer Auth
+
+* #### Retrieve knowledge based authentication questions
+
+  ```tsx
+  const questionsRequest = await sdk.customerAuth.getAuthQuestions();
+  ```
+
+* #### Submit answers to knowledge based authentication questions
+
+  ```tsx
+  await sdk.customerAuth.submitAuthAnswers({
+    answers: [
+      {
+        answer_order: 1,
+        choice_id: '1',
+      },
+      {
+        answer_order: 2,
+        choice_id: '2',
+
+      },
+    ],
+    authentication_id: questionsRequest.authentication_id,
+    authentication_session_id: questionsRequest.authentication_session_id
+  })
+  ```
+
+### Customers
+
+* #### Retrieve a customer
+
+  ```tsx
+  await sdk.customers.getCustomerById({ customer_id: 'cus_01' });
+  ```
+
+* #### Update a customer
+
+  ```tsx
+  await sdk.customers.updateCustomer({
+    customer_id: 'cus_01',
+    first_name: '';
+    // any other customer fields
+  });
+  ```
+
+* #### Delete a customer
+
+  ```tsx
+  await sdk.customers.deleteCustomer({ customer_id: 'cus_01' });
+  ```
+
+* #### Search customers by fields
+
+  ```tsx
+  await sdk.customers.searchCustomers({
+    count: 10,
+    name: { first_name: 'John' },
+  });
+  ```
+
+* #### Create a new customer
+
+  ```tsx
+  await sdk.customers.createCustomer({
+    people_id: '',
+    reference_id: '',
+    first_name: '',
+    middle_initial: '',
+    last_name: '',
+    suffix: '',
+    addresses: [
+      {
+        address_type: 'CURRENT_RESIDENTIAL',
+        address1: '',
+        address2: '',
+        city: '',
+        state: '',
+        zip: '',
+        country_code: 'US',
+      },
+    ],
+    phones: [
+      {
+        phone_type: 'HOME',
+        phone_country_code: '001',
+        phone_number: '123-494-3566',
+      },
+    ],
+    emails: [
+      {
+        email_type: 'PERSONAL',
+        email_address: 'test@experian.com',
+      },
+    ],
+    social_security_number: '',
+    date_of_birth: 'yyy-mm-dd',
+    outside_auth: false,
+    disclosure: {
+      accepted_at: 'yyy-mm-ddT00:00:00.000+00:00',
+    },
+  });
+  ```
+
+### Entitlements
+
+* #### Retrieve all entitlements for a customer
+
+  ```tsx
+  await sdk.entitlements.getEntitlements({ customer_id: 'cus_01' })
+  ```
+
+* #### Retrieve an entitlement by id
+
+  ```tsx
+  await sdk.entitlements.getEntitlementById({ entitlement_id: 'ent_01' })
+  ```
+
+* #### Create a new entitlement for a customer with one or more products
+
+  ```tsx
+  await sdk.entitlements.createEntitlement({
+    name: '',
+    description: '',
+    product_config_ids: [
+      'procfg_01'
+    ];
+    customer_id: 'cus_01';
+  })
+  ```
+
+* #### Update an existing entitlement for a customer
+
+  ```tsx
+  await sdk.entitlements.updateEntitlement({
+    entitlement_id: 'ent_01',
+    product_config_ids: [
+      'procfg_01'
+    ];
+    customer_id: 'cus_01';
+  });
+  ```
+
+* #### Delete an entitlement
+
+  ```tsx
+  await sdk.entitlements.deleteEntitlement({ entitlement_id: '' });
+  ```
+
+* #### Activate an exisiting entitlement
+
+  ```tsx
+  await sdk.entitlements.activateEntitlement({ entitlement_id: '' });
+  ```
+
+* #### Entitle customer to a new product
+
+  ```tsx
+  await sdk.entitlements.entitleCustomerToNewProduct({
+    entitlement_id: 'ent_01',
+    product_config_id: 'procfg_01',
+    customer_id: 'cus_01'
+  });
+  ```
+
+* #### Activate a product already entitled to a customer
+
+  ```tsx
+  await sdk.entitlements.activateProduct({
+    product_config_id: 'procfg_01',
+    entitlement_id: 'ent_01'
+  });
+  ```
+
+* #### Get the eligibility status for an existing product entitled to a customer
+
+  ```tsx
+  await sdk.entitlements.getProductEligibility({
+    product_config_id: 'procfg_01',
+    customer_id: 'cus_01'
+  });
+  ```
+
+### Product Configs
+
+* #### Retrieve product configurations for a tenant
+
+  ```tsx
+  await sdk.productConfigs.getProductConfigs();
+  ```
+
+* #### Retrieve a single product configuration for a tenant
+
+  ```tsx
+  await sdk.productConfigs.getProductConfigById({ 
+    product_config_id: 'procfg_01' 
+  });
+  ```
+
+### Registrations
+
+* #### Create a customer, create an entitlement, and activate product(s) in a single request
+
+  ```tsx
+  await sdk.registrations.createRegistration({
+    customer: {
+      phones: [
+        {
+          phone_type: 'HOME',
+          phone_country_code: '',
+          phone_number: '',
+        },
+      ],
+      date_of_birth: '',
+      last_name: '',
+      suffix: '',
+      social_security_number: '',
+      disclosure: {
+        accepted_at: 'yyyy-mm-ddT00:00:00.000+00:00',
+      },
+      emails: [
+        {
+          email_type: '',
+          email_address: '',
+        },
+      ],
+      outside_auth: boolean,
+      middle_initial: '',
+      people_id: '',
+      addresses: [
+        {
+          address_type: '',
+          address1: '',
+          address2: '',
+          city: '',
+          state: '',
+          zip: '',
+          country_code: '',
+        },
+      ],
+      reference_id: '',
+      first_name: '',
+    },
+    entitlement: {
+      name: '',
+      description: '',
+      available_at: 'yyyy-mm-ddT00:00:00.000+00:00',
+      product_config_ids: ['procfg_01'],
+    },
+  });
+  ```
+
+## Utilities
+
+### 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)
+
+* Credit Score Planner
+
+  ```tsx
+  function isPlanCompleted(plan: CreditScorePlan): plan is FicoCreditScorePlanCompleted | VantageCreditScorePlanCompleted;
+  function isPlanSet(plan: CreditScorePlan): plan is FicoCreditScorePlanCompleted | FicoCreditScorePlanSet | VantageCreditScorePlanCompleted | VantageCreditScorePlanSet;
+  function isVantagePlan(plan: CreditScorePlan): plan is VantageCreditScorePlan;
+  function isFicoPlan(plan: CreditScorePlan): plan is FicoCreditScorePlan;
+  function isFicoRevisionsRequest(request: ScorePlanRevisionsRequest): request is FicoScorePlanRevisionsRequest;
+  function isVantageRevisionsRequest(request: ScorePlanRevisionsRequest): request is VantageScorePlanRevisionsRequest;
+  function isFicoRevision(revision: ScorePlanRevision): revision is FicoScorePlanRevision;
+  function isVantageRevision(revision: ScorePlanRevision): revision is VantageScorePlanRevision;
+  ```
+
+* Credit Score Simulator
+
+  ```tsx
+  function isFicoSimulator(data?: CreditScoreSimulator): data is FicoScoreSimulator;
+  function isVantageScenario(scenario?: Scenario): scenario is VantageScenario;
+  function isFicoScenario(scenario: Scenario): scenario is FicoScenario;
+  function isFicoScenarioVariation(variation?: ScenarioVariation): variation is FicoScenarioVariation;
+  function isVantageScenarioVariation(variation?: ScenarioVariation): variation is VantageScenarioVariation;
+  ```