@dossier-wiki/os-sdk 1.8.1-staging.863 → 1.8.2-staging.868

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +83 -0
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -415,6 +415,43 @@ Migration:
415
415
  - Use `status` for the initial customer lifecycle state. New records default to
416
416
  `ONBOARDING`; `monitoringStatus` and `riskRating` are not create inputs.
417
417
 
418
+ ## Merging duplicate customers
419
+
420
+ Every id below takes the internal id or `ext:<externalId>`.
421
+
422
+ ```ts
423
+ // Who might be the same party, strongest evidence first
424
+ const { data } = await os.customers.potentialDuplicates(customerId);
425
+
426
+ // Not a duplicate: the pair stops being suggested from either side
427
+ await os.customers.dismissPotentialDuplicate(customerId, {
428
+ duplicateCustomerId: 'ext:CUST-1042',
429
+ reason: 'Spouses sharing a phone number.',
430
+ });
431
+
432
+ // What would move, and the rating, status and KYC tier the survivor ends up with
433
+ const preview = await os.customers.mergePreview(customerId, 'ext:CUST-1042');
434
+
435
+ // customerId survives; the duplicate is archived. This can't be undone.
436
+ const result = await os.customers.merge(customerId, {
437
+ sourceId: 'ext:CUST-1042',
438
+ useSourceValueFor: ['DATE_OF_BIRTH'],
439
+ reason: 'Same passport, onboarded twice.',
440
+ });
441
+ result.moved; // { transactions: 12, identificationDocuments: 1 }
442
+ ```
443
+
444
+ - `merge` and `mergePreview` need a key whose creator is an owner or admin.
445
+ - The survivor keeps the higher risk rating and KYC tier, and a suspended or
446
+ rejected status carries over. It is then re-screened and re-rated.
447
+ - The duplicate's internal id and `ext:<externalId>` keep working on
448
+ transactions, transaction attempts and customer events, and reach the survivor.
449
+ - Creating a customer with the duplicate's `externalId` rejects with
450
+ `CUSTOMER_EXTERNAL_ID_MERGED`; `details.survivingCustomerId` names the
451
+ customer to use.
452
+ - Looking up the old external ID with `isExternal=true` returns the survivor
453
+ with `merged: true` and `mergedFrom`.
454
+
418
455
  ## Profile templates & risk matrix
419
456
 
420
457
  A **Profile Template** is to a customer what a **Product** is to an account:
@@ -595,6 +632,52 @@ How it behaves:
595
632
  - Profile fields are **not** readable by rules. Promote a value to a
596
633
  `$customer.*` constant if a rule needs it.
597
634
 
635
+ ### Named ratings
636
+
637
+ A template can rate a customer more than once, for example once for each
638
+ service. Each named rating is a further matrix with its own key, condition,
639
+ history and officer override. `overallRatingRule` says what sets the customer's
640
+ overall `riskRating`: `TEMPLATE_MATRIX` (the default), `HIGHEST` (the highest
641
+ named rating that applies) or `NAMED` (the rating in `overallRatingKey`).
642
+
643
+ ```ts
644
+ await os.config.profileTemplates.update(templateId, {
645
+ ratingMatrices: [{
646
+ key: 'LENDING',
647
+ name: 'Lending',
648
+ // Scores the customer only while this holds. Omit it to always apply.
649
+ appliesWhen: { field: 'fields.loanAmount', operator: 'IS_NOT_NULL', value: '' },
650
+ matrix: lendingMatrix, // same shape as riskMatrix
651
+ }],
652
+ overallRatingRule: 'HIGHEST',
653
+ });
654
+
655
+ // The named ratings that apply to the customer, in template order
656
+ const ratings = await os.customers.riskRating.listNamed(customerId);
657
+
658
+ // Set one by hand. The response's ratings are still the overall rating.
659
+ await os.customers.riskRating.update(customerId, {
660
+ ratingKey: 'LENDING',
661
+ riskRating: 'MEDIUM',
662
+ justification: 'Loan secured against verified collateral.',
663
+ });
664
+ await os.customers.riskRating.clearOverride(customerId, { ratingKey: 'LENDING' });
665
+
666
+ // One rating's matrix runs and overrides
667
+ await os.customers.riskAssessments.list(customerId, { ratingKey: 'LENDING' });
668
+ ```
669
+
670
+ - At most 10 per template. `ratingMatrices` replaces the whole list. Changing
671
+ it, or the overall rule, publishes a new version and re-assesses the
672
+ template's customers.
673
+ - Without `ratingKey`, `riskAssessments.list` returns only entries not tied to
674
+ a named rating.
675
+ - Overriding a rating that doesn't apply, or clearing one with no override,
676
+ rejects with `409 CONFLICT`. An unknown key rejects with `422 UNPROCESSABLE`.
677
+ - `previewRiskMatrix` and `riskMatrixImpact` take `ratingKey` and `appliesWhen`
678
+ to dry-run one named rating.
679
+ - Changes arrive as the `customer.named_risk_changed` webhook.
680
+
598
681
  ### Derived inputs
599
682
 
600
683
  A factor can read a value the platform derives itself instead of a profile
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@dossier-wiki/os-sdk",
3
- "version": "1.8.1-staging.863",
3
+ "version": "1.8.2-staging.868",
4
4
  "description": "TypeScript SDK for the Dossiers OS API — customers, accounts, transactions, rules, screening, and configuration.",
5
5
  "license": "MIT",
6
6
  "type": "module",