@sudoplatform/sudo-privacy-interaction 2.0.0 → 2.1.0

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 (100) hide show
  1. package/cjs/gen/graphqlTypes.js +1727 -772
  2. package/cjs/private/data/analysis-result/transformer/privacyScoreTransformer.js +8 -0
  3. package/cjs/private/data/common/apiClient.js +23 -0
  4. package/cjs/private/data/data-holder/defaultDataHolderService.js +12 -0
  5. package/cjs/private/data/data-holder/transformer/dataHolderScanSummaryTransformer.js +56 -0
  6. package/cjs/private/data/organization-analysis/defaultOrganizationAnalysisService.js +31 -0
  7. package/cjs/private/data/organization-analysis/transformer/organizationAnalysisModeTransformer.js +29 -0
  8. package/cjs/private/data/organization-analysis/transformer/organizationAnalysisTransformer.js +45 -0
  9. package/cjs/private/data/virtual-presence/transformer/virtualPresenceTransformer.js +2 -0
  10. package/cjs/private/domain/entities/organization-analysis/organizationAnalysisEntity.js +24 -0
  11. package/cjs/private/domain/entities/organization-analysis/organizationAnalysisService.js +7 -0
  12. package/cjs/private/domain/use-cases/data-holder/listDataHolderScanSummariesUseCase.js +29 -0
  13. package/cjs/private/domain/use-cases/organization-analysis/getOrganizationAnalysisUseCase.js +25 -0
  14. package/cjs/public/defaultSudoPrivacyInteractionClient.js +75 -6
  15. package/cjs/public/inputs/index.js +1 -0
  16. package/cjs/public/inputs/organizationAnalysis.js +7 -0
  17. package/cjs/public/typings/index.js +1 -0
  18. package/cjs/public/typings/organizationAnalysis.js +24 -0
  19. package/docs/assets/hierarchy.js +1 -1
  20. package/docs/assets/navigation.js +1 -1
  21. package/docs/assets/search.js +1 -1
  22. package/docs/classes/DefaultSudoPrivacyInteractionClient.html +69 -20
  23. package/docs/enums/DataCategory.html +18 -18
  24. package/docs/enums/DataHolderProtectionState.html +5 -5
  25. package/docs/enums/OrganizationAnalysisMode.html +70 -0
  26. package/docs/enums/OrganizationCategory.html +30 -30
  27. package/docs/enums/ProviderType.html +3 -3
  28. package/docs/enums/RetentionStyle.html +5 -5
  29. package/docs/enums/ShareStyle.html +6 -6
  30. package/docs/enums/SignalValue.html +4 -4
  31. package/docs/enums/VirtualPresenceState.html +7 -7
  32. package/docs/hierarchy.html +6 -5
  33. package/docs/interfaces/CapabilitySignals.html +9 -9
  34. package/docs/interfaces/CategorySignals.html +11 -11
  35. package/docs/interfaces/DataHolder.html +24 -14
  36. package/docs/interfaces/DataHolderScanSummary.html +158 -0
  37. package/docs/interfaces/GetDataHolderOptions.html +63 -0
  38. package/docs/interfaces/GetOrganizationAnalysisInput.html +70 -0
  39. package/docs/interfaces/ListAnalysisResultsInput.html +1 -1
  40. package/docs/interfaces/ListDataHolderScanSummariesInput.html +85 -0
  41. package/docs/interfaces/ListDataHoldersInput.html +1 -1
  42. package/docs/interfaces/ListVirtualPresencesInput.html +1 -1
  43. package/docs/interfaces/OrganizationAnalysis.html +131 -0
  44. package/docs/interfaces/OrganizationIdentity.html +5 -5
  45. package/docs/interfaces/Pagination.html +2 -1
  46. package/docs/interfaces/PrivacyScore.html +13 -5
  47. package/docs/interfaces/PrivacySummary.html +4 -4
  48. package/docs/interfaces/RetentionInfo.html +4 -4
  49. package/docs/interfaces/RiskIndicators.html +8 -8
  50. package/docs/interfaces/ScoreContribution.html +3 -3
  51. package/docs/interfaces/ScoreCoverage.html +70 -0
  52. package/docs/interfaces/SudoPrivacyInteractionClient.html +67 -20
  53. package/docs/interfaces/VirtualPresence.html +21 -12
  54. package/docs/modules.html +4 -4
  55. package/docs/types/SudoPrivacyInteractionClientOptions.html +2 -2
  56. package/lib/gen/graphqlTypes.js +1726 -771
  57. package/lib/private/data/analysis-result/transformer/privacyScoreTransformer.js +8 -0
  58. package/lib/private/data/common/apiClient.js +24 -1
  59. package/lib/private/data/data-holder/defaultDataHolderService.js +12 -0
  60. package/lib/private/data/data-holder/transformer/dataHolderScanSummaryTransformer.js +52 -0
  61. package/lib/private/data/organization-analysis/defaultOrganizationAnalysisService.js +27 -0
  62. package/lib/private/data/organization-analysis/transformer/organizationAnalysisModeTransformer.js +25 -0
  63. package/lib/private/data/organization-analysis/transformer/organizationAnalysisTransformer.js +41 -0
  64. package/lib/private/data/virtual-presence/transformer/virtualPresenceTransformer.js +2 -0
  65. package/lib/private/domain/entities/organization-analysis/organizationAnalysisEntity.js +21 -0
  66. package/lib/private/domain/entities/organization-analysis/organizationAnalysisService.js +6 -0
  67. package/lib/private/domain/use-cases/data-holder/listDataHolderScanSummariesUseCase.js +25 -0
  68. package/lib/private/domain/use-cases/organization-analysis/getOrganizationAnalysisUseCase.js +21 -0
  69. package/lib/public/defaultSudoPrivacyInteractionClient.js +75 -6
  70. package/lib/public/inputs/index.js +1 -0
  71. package/lib/public/inputs/organizationAnalysis.js +6 -0
  72. package/lib/public/typings/index.js +1 -0
  73. package/lib/public/typings/organizationAnalysis.js +21 -0
  74. package/package.json +4 -2
  75. package/types/gen/graphqlTypes.d.ts +324 -0
  76. package/types/private/data/common/apiClient.d.ts +10 -1
  77. package/types/private/data/common/baseSubscriptionManager.d.ts +5 -0
  78. package/types/private/data/data-holder/defaultDataHolderService.d.ts +3 -1
  79. package/types/private/data/data-holder/transformer/dataHolderScanSummaryTransformer.d.ts +18 -0
  80. package/types/private/data/organization-analysis/defaultOrganizationAnalysisService.d.ts +15 -0
  81. package/types/private/data/organization-analysis/transformer/organizationAnalysisModeTransformer.d.ts +12 -0
  82. package/types/private/data/organization-analysis/transformer/organizationAnalysisTransformer.d.ts +14 -0
  83. package/types/private/domain/entities/analysis-result/analysisResultEntity.d.ts +14 -0
  84. package/types/private/domain/entities/data-holder/dataHolderEntity.d.ts +34 -0
  85. package/types/private/domain/entities/data-holder/dataHolderService.d.ts +35 -1
  86. package/types/private/domain/entities/organization-analysis/organizationAnalysisEntity.d.ts +53 -0
  87. package/types/private/domain/entities/organization-analysis/organizationAnalysisService.d.ts +35 -0
  88. package/types/private/domain/entities/virtual-presence/virtualPresenceEntity.d.ts +3 -0
  89. package/types/private/domain/use-cases/data-holder/listDataHolderScanSummariesUseCase.d.ts +36 -0
  90. package/types/private/domain/use-cases/organization-analysis/getOrganizationAnalysisUseCase.d.ts +16 -0
  91. package/types/public/defaultSudoPrivacyInteractionClient.d.ts +9 -3
  92. package/types/public/inputs/dataHolder.d.ts +22 -0
  93. package/types/public/inputs/index.d.ts +1 -0
  94. package/types/public/inputs/organizationAnalysis.d.ts +18 -0
  95. package/types/public/sudoPrivacyInteractionClient.d.ts +25 -3
  96. package/types/public/typings/analysisResult.d.ts +14 -0
  97. package/types/public/typings/dataHolder.d.ts +38 -0
  98. package/types/public/typings/index.d.ts +1 -0
  99. package/types/public/typings/organizationAnalysis.d.ts +53 -0
  100. package/types/public/typings/virtualPresence.d.ts +3 -0
@@ -4,7 +4,7 @@
4
4
  * SPDX-License-Identifier: Apache-2.0
5
5
  */
6
6
  import { DataHolderSubscriber } from '../../../../public/typings/subscription';
7
- import { DataHolderEntity } from './dataHolderEntity';
7
+ import { DataHolderEntity, DataHolderScanSummaryEntity } from './dataHolderEntity';
8
8
  /**
9
9
  * Input for `DataHolderService.list` method.
10
10
  *
@@ -30,6 +30,32 @@ export interface ListDataHoldersOutput {
30
30
  dataHolders: DataHolderEntity[];
31
31
  nextToken?: string;
32
32
  }
33
+ /**
34
+ * Input for `DataHolderService.listScanSummaries` method.
35
+ *
36
+ * @interface ListDataHolderScanSummariesInput
37
+ * @property {string} dataHolderId The data holder to list scan summaries for.
38
+ * @property {number} limit Number of records to return.
39
+ * @property {string} nextToken A token generated by a previous call to
40
+ * `DataHolderService.listScanSummaries`. This allows for pagination.
41
+ */
42
+ export interface ListDataHolderScanSummariesInput {
43
+ dataHolderId: string;
44
+ limit?: number;
45
+ nextToken?: string;
46
+ }
47
+ /**
48
+ * Output for `DataHolderService.listScanSummaries` method.
49
+ *
50
+ * @interface ListDataHolderScanSummariesOutput
51
+ * @property {DataHolderScanSummaryEntity[]} scanSummaries The list of scan summaries
52
+ * retrieved in this query.
53
+ * @property {string} nextToken A token generated by a previous call. This allows for pagination.
54
+ */
55
+ export interface ListDataHolderScanSummariesOutput {
56
+ scanSummaries: DataHolderScanSummaryEntity[];
57
+ nextToken?: string;
58
+ }
33
59
  /**
34
60
  * Input for `DataHolderService.subscribe` method.
35
61
  *
@@ -65,6 +91,14 @@ export interface DataHolderService {
65
91
  * Can be empty if no data holders found.
66
92
  */
67
93
  list(input: ListDataHoldersInput): Promise<ListDataHoldersOutput>;
94
+ /**
95
+ * Retrieve a list of scan summaries for a data holder (most recent first).
96
+ *
97
+ * @param {ListDataHolderScanSummariesInput} input Parameters used to list scan summaries.
98
+ * @returns {ListDataHolderScanSummariesOutput} A list of scan summaries matching the
99
+ * search criteria. Can be empty if no scan summaries found.
100
+ */
101
+ listScanSummaries(input: ListDataHolderScanSummariesInput): Promise<ListDataHolderScanSummariesOutput>;
68
102
  /**
69
103
  * Subscribe to data holder state events.
70
104
  *
@@ -0,0 +1,53 @@
1
+ /**
2
+ * Copyright © 2026 Anonyome Labs, Inc. All rights reserved.
3
+ *
4
+ * SPDX-License-Identifier: Apache-2.0
5
+ */
6
+ import { AnalysisResultDataEntity, AnalysisResultStatusEntity } from '../analysis-result/analysisResultEntity';
7
+ /**
8
+ * Core entity representation of a shared, domain-keyed privacy analysis of an
9
+ * organization.
10
+ *
11
+ * The same underlying analysis is returned to every caller asking about the same
12
+ * domain; it carries only organization-generic signals. `id` equals the analyzed
13
+ * domain and `owner` is the requesting caller.
14
+ *
15
+ * @interface OrganizationAnalysisEntity
16
+ * @property {string} id Identifies the shared analysis. Equal to the analyzed domain.
17
+ * @property {string} domain The analyzed domain (equal to id).
18
+ * @property {AnalysisResultStatusEntity} status Aggregate status. PENDING while an asynchronous
19
+ * source is still resolving; re-query for the terminal result.
20
+ * @property {Date} lastAnalyzedAt When the aggregate was last derived.
21
+ * @property {AnalysisResultDataEntity} data Structured analysis payload. Populated when status
22
+ * is COMPLETE or PARTIAL.
23
+ * @property {string} owner The caller who requested this view. The underlying analysis is shared.
24
+ * @property {number} version Version of this entity. Increments on update.
25
+ * @property {Date} createdAt Date for when the analysis was created.
26
+ * @property {Date} updatedAt Date for when the analysis was last updated.
27
+ */
28
+ export interface OrganizationAnalysisEntity {
29
+ id: string;
30
+ domain: string;
31
+ status: AnalysisResultStatusEntity;
32
+ lastAnalyzedAt: Date;
33
+ data?: AnalysisResultDataEntity;
34
+ owner: string;
35
+ version: number;
36
+ createdAt: Date;
37
+ updatedAt: Date;
38
+ }
39
+ /**
40
+ * Controls how `getOrganizationAnalysis` obtains source results when the stored
41
+ * analysis is stale or absent.
42
+ *
43
+ * @property ANALYZE Read-through: request analysis from the sources, which may compute and
44
+ * leave the result PENDING until asynchronous work completes.
45
+ * @property FETCH Pull only the sources' existing values; never request new work. A stale
46
+ * domain with no existing source value is not moved to PENDING.
47
+ *
48
+ * @enum
49
+ */
50
+ export declare enum OrganizationAnalysisModeEntity {
51
+ Analyze = "ANALYZE",
52
+ Fetch = "FETCH"
53
+ }
@@ -0,0 +1,35 @@
1
+ /**
2
+ * Copyright © 2026 Anonyome Labs, Inc. All rights reserved.
3
+ *
4
+ * SPDX-License-Identifier: Apache-2.0
5
+ */
6
+ import { OrganizationAnalysisEntity, OrganizationAnalysisModeEntity } from './organizationAnalysisEntity';
7
+ /**
8
+ * Input for `OrganizationAnalysisService.getOrganizationAnalysis` method.
9
+ *
10
+ * @interface GetOrganizationAnalysisInput
11
+ * @property {string} domain The domain to analyze.
12
+ * @property {OrganizationAnalysisModeEntity} mode How to obtain source results. When omitted,
13
+ * the backend behaves as ANALYZE.
14
+ */
15
+ export interface GetOrganizationAnalysisInput {
16
+ domain: string;
17
+ mode?: OrganizationAnalysisModeEntity;
18
+ }
19
+ /**
20
+ * Core entity representation of an organization analysis service used in business logic.
21
+ *
22
+ * @interface OrganizationAnalysisService
23
+ */
24
+ export interface OrganizationAnalysisService {
25
+ /**
26
+ * Analyze (read-through) and return the shared, organization-generic analysis for a domain.
27
+ * Returns a result with PENDING status when an asynchronous source is still resolving;
28
+ * re-query for the terminal result.
29
+ *
30
+ * @param {GetOrganizationAnalysisInput} input Parameters used to obtain the analysis.
31
+ * @returns {OrganizationAnalysisEntity | undefined} The organization analysis, or undefined
32
+ * if not found.
33
+ */
34
+ getOrganizationAnalysis(input: GetOrganizationAnalysisInput): Promise<OrganizationAnalysisEntity | undefined>;
35
+ }
@@ -16,6 +16,8 @@
16
16
  * @property {string} identifier The presence identifier (e.g. email address).
17
17
  * @property {VirtualPresenceStateEntity} state The current state of the virtual presence.
18
18
  * @property {Date} lastScannedAt Date for when the virtual presence was last scanned.
19
+ * @property {string} lastScanFailureReason Reason the most recent completed scan failed (an error/exception name).
20
+ * Undefined when the most recent completed scan succeeded (or none has completed).
19
21
  * @property {Date} createdAt Date for when the virtual presence was created.
20
22
  * @property {Date} updatedAt Date for when the virtual presence was last updated.
21
23
  */
@@ -27,6 +29,7 @@ export interface VirtualPresenceEntity {
27
29
  identifier: string;
28
30
  state: VirtualPresenceStateEntity;
29
31
  lastScannedAt: Date;
32
+ lastScanFailureReason?: string;
30
33
  createdAt: Date;
31
34
  updatedAt: Date;
32
35
  }
@@ -0,0 +1,36 @@
1
+ /**
2
+ * Copyright © 2026 Anonyome Labs, Inc. All rights reserved.
3
+ *
4
+ * SPDX-License-Identifier: Apache-2.0
5
+ */
6
+ import { DataHolderScanSummaryEntity } from '../../entities/data-holder/dataHolderEntity';
7
+ import { DataHolderService } from '../../entities/data-holder/dataHolderService';
8
+ /**
9
+ * Input for `ListDataHolderScanSummariesUseCase`.
10
+ *
11
+ * @interface ListDataHolderScanSummariesUseCaseInput
12
+ */
13
+ interface ListDataHolderScanSummariesUseCaseInput {
14
+ dataHolderId: string;
15
+ limit?: number | undefined;
16
+ nextToken?: string | undefined;
17
+ }
18
+ /**
19
+ * Output for `ListDataHolderScanSummariesUseCase`.
20
+ *
21
+ * @interface ListDataHolderScanSummariesUseCaseOutput
22
+ */
23
+ interface ListDataHolderScanSummariesUseCaseOutput {
24
+ scanSummaries: DataHolderScanSummaryEntity[];
25
+ nextToken?: string;
26
+ }
27
+ /**
28
+ * Application business logic for listing scan summaries for a data holder.
29
+ */
30
+ export declare class ListDataHolderScanSummariesUseCase {
31
+ private readonly dataHolderService;
32
+ private readonly log;
33
+ constructor(dataHolderService: DataHolderService);
34
+ execute(input: ListDataHolderScanSummariesUseCaseInput): Promise<ListDataHolderScanSummariesUseCaseOutput>;
35
+ }
36
+ export {};
@@ -0,0 +1,16 @@
1
+ /**
2
+ * Copyright © 2026 Anonyome Labs, Inc. All rights reserved.
3
+ *
4
+ * SPDX-License-Identifier: Apache-2.0
5
+ */
6
+ import { OrganizationAnalysisEntity } from '../../entities/organization-analysis/organizationAnalysisEntity';
7
+ import { GetOrganizationAnalysisInput, OrganizationAnalysisService } from '../../entities/organization-analysis/organizationAnalysisService';
8
+ /**
9
+ * Application business logic for obtaining an organization analysis.
10
+ */
11
+ export declare class GetOrganizationAnalysisUseCase {
12
+ private readonly organizationAnalysisService;
13
+ private readonly log;
14
+ constructor(organizationAnalysisService: OrganizationAnalysisService);
15
+ execute(input: GetOrganizationAnalysisInput): Promise<OrganizationAnalysisEntity | undefined>;
16
+ }
@@ -4,9 +4,9 @@
4
4
  * SPDX-License-Identifier: Apache-2.0
5
5
  */
6
6
  import { ListOutput } from '@sudoplatform/sudo-common';
7
- import { ConnectVirtualPresenceWithAuthCodeInput, ConnectVirtualPresenceWithRefreshTokenInput, ListAnalysisResultsInput, ListDataHoldersInput, ListVirtualPresencesInput, RescanVirtualPresenceInput } from './inputs';
7
+ import { ConnectVirtualPresenceWithAuthCodeInput, ConnectVirtualPresenceWithRefreshTokenInput, GetDataHolderOptions, GetOrganizationAnalysisInput, ListAnalysisResultsInput, ListDataHolderScanSummariesInput, ListDataHoldersInput, ListVirtualPresencesInput, RescanVirtualPresenceInput } from './inputs';
8
8
  import { SudoPrivacyInteractionClient, SudoPrivacyInteractionClientOptions } from './sudoPrivacyInteractionClient';
9
- import { AnalysisResult, AnalysisResultSubscriber, DataHolder, DataHolderSubscriber, ProviderConfiguration, VirtualPresence, VirtualPresenceSubscriber } from './typings';
9
+ import { AnalysisResult, AnalysisResultSubscriber, DataHolder, DataHolderScanSummary, DataHolderSubscriber, OrganizationAnalysis, ProviderConfiguration, VirtualPresence, VirtualPresenceSubscriber } from './typings';
10
10
  export declare class DefaultSudoPrivacyInteractionClient implements SudoPrivacyInteractionClient {
11
11
  private readonly apiClient;
12
12
  private readonly userClient;
@@ -14,11 +14,15 @@ export declare class DefaultSudoPrivacyInteractionClient implements SudoPrivacyI
14
14
  private readonly virtualPresenceService;
15
15
  private readonly dataHolderService;
16
16
  private readonly analysisResultService;
17
+ private readonly organizationAnalysisService;
17
18
  private readonly providerConfigurationTransformer;
18
19
  private readonly virtualPresenceTransformer;
19
20
  private readonly relationshipProviderTransformer;
20
21
  private readonly dataHolderTransformer;
22
+ private readonly dataHolderScanSummaryTransformer;
21
23
  private readonly analysisResultTransformer;
24
+ private readonly organizationAnalysisTransformer;
25
+ private readonly organizationAnalysisModeTransformer;
22
26
  private readonly log;
23
27
  constructor(opts: SudoPrivacyInteractionClientOptions);
24
28
  getProviderConfiguration(): Promise<ProviderConfiguration[]>;
@@ -29,12 +33,14 @@ export declare class DefaultSudoPrivacyInteractionClient implements SudoPrivacyI
29
33
  listVirtualPresences(input: ListVirtualPresencesInput): Promise<ListOutput<VirtualPresence>>;
30
34
  subscribeToVirtualPresence(subscriptionId: string, subscriber: VirtualPresenceSubscriber): Promise<void>;
31
35
  unsubscribeFromVirtualPresence(subscriptionId: string): void;
32
- getDataHolder(id: string): Promise<DataHolder | undefined>;
36
+ getDataHolder(id: string, options?: GetDataHolderOptions): Promise<DataHolder | undefined>;
33
37
  listDataHolders(input: ListDataHoldersInput): Promise<ListOutput<DataHolder>>;
38
+ listDataHolderScanSummaries(input: ListDataHolderScanSummariesInput): Promise<ListOutput<DataHolderScanSummary>>;
34
39
  subscribeToDataHolders(subscriptionId: string, subscriber: DataHolderSubscriber): Promise<void>;
35
40
  unsubscribeFromDataHolders(subscriptionId: string): void;
36
41
  getAnalysisResult(id: string): Promise<AnalysisResult | undefined>;
37
42
  listAnalysisResults(input: ListAnalysisResultsInput): Promise<ListOutput<AnalysisResult>>;
38
43
  subscribeToAnalysisResult(subscriptionId: string, subscriber: AnalysisResultSubscriber): Promise<void>;
39
44
  unsubscribeFromAnalysisResult(subscriptionId: string): void;
45
+ getOrganizationAnalysis(input: GetOrganizationAnalysisInput): Promise<OrganizationAnalysis | undefined>;
40
46
  }
@@ -15,3 +15,25 @@ import { Pagination } from './common';
15
15
  export interface ListDataHoldersInput extends Pagination {
16
16
  virtualPresenceId: string;
17
17
  }
18
+ /**
19
+ * Properties required to list scan summaries for a data holder.
20
+ *
21
+ * @interface ListDataHolderScanSummariesInput
22
+ * @property {string} dataHolderId The identifier of the data holder to list scan summaries for.
23
+ * @property {number} limit Number of items to return.
24
+ * @property {string} nextToken A token generated by a previous call.
25
+ */
26
+ export interface ListDataHolderScanSummariesInput extends Pagination {
27
+ dataHolderId: string;
28
+ }
29
+ /**
30
+ * Options to control what `getDataHolder` returns.
31
+ *
32
+ * @interface GetDataHolderOptions
33
+ * @property {boolean} includeScanSummary Whether to also fetch and attach the most recent
34
+ * scan summary to the returned data holder. Defaults to `true`. When `true`, the data holder
35
+ * and its latest scan summary are fetched concurrently.
36
+ */
37
+ export interface GetDataHolderOptions {
38
+ includeScanSummary?: boolean;
39
+ }
@@ -6,4 +6,5 @@
6
6
  export * from './analysisResult';
7
7
  export * from './common';
8
8
  export * from './dataHolder';
9
+ export * from './organizationAnalysis';
9
10
  export * from './virtualPresence';
@@ -0,0 +1,18 @@
1
+ /**
2
+ * Copyright © 2026 Anonyome Labs, Inc. All rights reserved.
3
+ *
4
+ * SPDX-License-Identifier: Apache-2.0
5
+ */
6
+ import { OrganizationAnalysisMode } from '../typings/organizationAnalysis';
7
+ /**
8
+ * Properties required to obtain an organization analysis.
9
+ *
10
+ * @interface GetOrganizationAnalysisInput
11
+ * @property {string} domain The domain to analyze.
12
+ * @property {OrganizationAnalysisMode} mode How to obtain source results. When omitted, the
13
+ * backend behaves as `Analyze` (read-through).
14
+ */
15
+ export interface GetOrganizationAnalysisInput {
16
+ domain: string;
17
+ mode?: OrganizationAnalysisMode;
18
+ }
@@ -5,8 +5,8 @@
5
5
  */
6
6
  import { ListOutput } from '@sudoplatform/sudo-common';
7
7
  import { SudoUserClient } from '@sudoplatform/sudo-user';
8
- import { ConnectVirtualPresenceWithAuthCodeInput, ConnectVirtualPresenceWithRefreshTokenInput, ListAnalysisResultsInput, ListDataHoldersInput, ListVirtualPresencesInput, RescanVirtualPresenceInput } from './inputs';
9
- import { AnalysisResult, AnalysisResultSubscriber, DataHolder, DataHolderSubscriber, ProviderConfiguration, VirtualPresence, VirtualPresenceSubscriber } from './typings';
8
+ import { ConnectVirtualPresenceWithAuthCodeInput, ConnectVirtualPresenceWithRefreshTokenInput, GetDataHolderOptions, GetOrganizationAnalysisInput, ListAnalysisResultsInput, ListDataHolderScanSummariesInput, ListDataHoldersInput, ListVirtualPresencesInput, RescanVirtualPresenceInput } from './inputs';
9
+ import { AnalysisResult, AnalysisResultSubscriber, DataHolder, DataHolderScanSummary, DataHolderSubscriber, OrganizationAnalysis, ProviderConfiguration, VirtualPresence, VirtualPresenceSubscriber } from './typings';
10
10
  export interface SudoPrivacyInteractionClient {
11
11
  /**
12
12
  * Retrieve the provider configurations required by consumers to support
@@ -69,9 +69,12 @@ export interface SudoPrivacyInteractionClient {
69
69
  * Retrieve a single data holder by ID.
70
70
  *
71
71
  * @param {string} id The unique identifier of the data holder.
72
+ * @param {GetDataHolderOptions} options Optional settings controlling what is returned.
73
+ * By default the most recent scan summary is fetched concurrently and attached as
74
+ * `latestScanSummary`.
72
75
  * @returns {DataHolder | undefined} The data holder, or undefined if not found.
73
76
  */
74
- getDataHolder(id: string): Promise<DataHolder | undefined>;
77
+ getDataHolder(id: string, options?: GetDataHolderOptions): Promise<DataHolder | undefined>;
75
78
  /**
76
79
  * List data holders associated with a virtual presence.
77
80
  *
@@ -79,6 +82,15 @@ export interface SudoPrivacyInteractionClient {
79
82
  * @returns {ListOutput<DataHolder>} A list of data holders matching the search criteria.
80
83
  */
81
84
  listDataHolders(input: ListDataHoldersInput): Promise<ListOutput<DataHolder>>;
85
+ /**
86
+ * List scan summaries associated with a data holder, most recent first.
87
+ *
88
+ * @param {ListDataHolderScanSummariesInput} input Parameters used to retrieve a list
89
+ * of scan summaries.
90
+ * @returns {ListOutput<DataHolderScanSummary>} A list of scan summaries matching the
91
+ * search criteria.
92
+ */
93
+ listDataHolderScanSummaries(input: ListDataHolderScanSummariesInput): Promise<ListOutput<DataHolderScanSummary>>;
82
94
  /**
83
95
  * Subscribe to data holder state events. Emitted when data holders are discovered
84
96
  * or updated during scanning.
@@ -123,6 +135,16 @@ export interface SudoPrivacyInteractionClient {
123
135
  * @param {string} subscriptionId The subscription identifier to unsubscribe.
124
136
  */
125
137
  unsubscribeFromAnalysisResult(subscriptionId: string): void;
138
+ /**
139
+ * Analyze (read-through) and return the shared, organization-generic analysis for a domain.
140
+ *
141
+ * Returns a result with a `Pending` status when an asynchronous source is still resolving;
142
+ * re-query for the terminal result. When `mode` is omitted, the backend behaves as `Analyze`.
143
+ *
144
+ * @param {GetOrganizationAnalysisInput} input Parameters used to obtain the analysis.
145
+ * @returns {OrganizationAnalysis | undefined} The organization analysis, or undefined if not found.
146
+ */
147
+ getOrganizationAnalysis(input: GetOrganizationAnalysisInput): Promise<OrganizationAnalysis | undefined>;
126
148
  }
127
149
  export type SudoPrivacyInteractionClientOptions = {
128
150
  /** Sudo User client to use. No default */
@@ -101,10 +101,24 @@ export interface AnalysisResultData {
101
101
  * @interface PrivacyScore
102
102
  * @property {number} score Numeric score (0-100). Higher is better.
103
103
  * @property {ScoreContribution[]} breakdown Breakdown of how each aspect contributed to the score.
104
+ * @property {ScoreCoverage} coverage How much of the scoring-relevant input had a known value.
104
105
  */
105
106
  export interface PrivacyScore {
106
107
  score: number;
107
108
  breakdown: ScoreContribution[];
109
+ coverage: ScoreCoverage;
110
+ }
111
+ /**
112
+ * How much of the scoring-relevant input had a known value. A low ratio means the
113
+ * score rests on few known signals and should be treated as lower-confidence.
114
+ *
115
+ * @interface ScoreCoverage
116
+ * @property {number} evaluated Scoring aspects with a known value.
117
+ * @property {number} total Total scoring aspects the calculator considers.
118
+ */
119
+ export interface ScoreCoverage {
120
+ evaluated: number;
121
+ total: number;
108
122
  }
109
123
  /**
110
124
  * A single scoring aspect and its contribution to the overall score.
@@ -20,6 +20,9 @@
20
20
  * @property {number} version Version of this entity. Increments on update.
21
21
  * @property {Date} createdAt Date for when the data holder was created.
22
22
  * @property {Date} updatedAt Date for when the data holder was last updated.
23
+ * @property {DataHolderScanSummary} latestScanSummary The most recent scan summary for this
24
+ * data holder, when requested via `getDataHolder`. Undefined when not requested or when the
25
+ * data holder has no scan summaries.
23
26
  */
24
27
  export interface DataHolder {
25
28
  id: string;
@@ -33,6 +36,7 @@ export interface DataHolder {
33
36
  version: number;
34
37
  createdAt: Date;
35
38
  updatedAt: Date;
39
+ latestScanSummary?: DataHolderScanSummary;
36
40
  }
37
41
  /**
38
42
  * The protection state of a data holder.
@@ -49,3 +53,37 @@ export declare enum DataHolderProtectionState {
49
53
  Resolved = "RESOLVED",
50
54
  Unknown = "UNKNOWN"
51
55
  }
56
+ /**
57
+ * The Sudo Platform SDK representation of email interaction metrics captured
58
+ * during a single scan for a specific data holder.
59
+ *
60
+ * @interface DataHolderScanSummary
61
+ * @property {string} dataHolderId The data holder these metrics apply to.
62
+ * @property {string} owner Unique identifier of the user.
63
+ * @property {Date} scannedAt Date for when the scan was performed.
64
+ * @property {Date} scanRangeFrom Start of the scanned time range.
65
+ * @property {Date} scanRangeTo End of the scanned time range.
66
+ * @property {number} emailCount Total number of emails observed in the scan range.
67
+ * @property {number} readCount Number of emails that were read.
68
+ * @property {number} readRate Ratio of read emails to total emails.
69
+ * @property {number} marketingEmailCount Number of marketing emails observed.
70
+ * @property {number} marketingEmailOpened Number of marketing emails that were opened.
71
+ * @property {number} marketingOpenRate Ratio of opened marketing emails to marketing emails.
72
+ * @property {Record<string, number>} categoryBreakdown Count of emails per category.
73
+ * @property {number} uncategorizedCount Number of emails that could not be categorized.
74
+ */
75
+ export interface DataHolderScanSummary {
76
+ dataHolderId: string;
77
+ owner: string;
78
+ scannedAt: Date;
79
+ scanRangeFrom: Date;
80
+ scanRangeTo: Date;
81
+ emailCount: number;
82
+ readCount: number;
83
+ readRate: number;
84
+ marketingEmailCount: number;
85
+ marketingEmailOpened: number;
86
+ marketingOpenRate: number;
87
+ categoryBreakdown: Record<string, number>;
88
+ uncategorizedCount: number;
89
+ }
@@ -5,6 +5,7 @@
5
5
  */
6
6
  export * from './analysisResult';
7
7
  export * from './dataHolder';
8
+ export * from './organizationAnalysis';
8
9
  export * from './providerConfiguration';
9
10
  export * from './subscription';
10
11
  export * from './virtualPresence';
@@ -0,0 +1,53 @@
1
+ /**
2
+ * Copyright © 2026 Anonyome Labs, Inc. All rights reserved.
3
+ *
4
+ * SPDX-License-Identifier: Apache-2.0
5
+ */
6
+ import { AnalysisResultData, AnalysisResultStatus } from './analysisResult';
7
+ /**
8
+ * The Sudo Platform SDK representation of a shared, domain-keyed privacy analysis
9
+ * of an organization.
10
+ *
11
+ * The same underlying analysis is returned to every caller asking about the same
12
+ * domain; it carries only organization-generic signals. `id` equals the analyzed
13
+ * domain and `owner` is the requesting caller.
14
+ *
15
+ * @interface OrganizationAnalysis
16
+ * @property {string} id Identifies the shared analysis. Equal to the analyzed domain.
17
+ * @property {string} domain The analyzed domain (equal to id).
18
+ * @property {AnalysisResultStatus} status Aggregate status. Pending while an asynchronous
19
+ * source is still resolving; re-query for the terminal result.
20
+ * @property {Date} lastAnalyzedAt When the aggregate was last derived.
21
+ * @property {AnalysisResultData} data Structured analysis payload. Populated when status is
22
+ * Complete or Partial.
23
+ * @property {string} owner The caller who requested this view. The underlying analysis is shared.
24
+ * @property {number} version Version of this entity. Increments on update.
25
+ * @property {Date} createdAt Date for when the analysis was created.
26
+ * @property {Date} updatedAt Date for when the analysis was last updated.
27
+ */
28
+ export interface OrganizationAnalysis {
29
+ id: string;
30
+ domain: string;
31
+ status: AnalysisResultStatus;
32
+ lastAnalyzedAt: Date;
33
+ data?: AnalysisResultData;
34
+ owner: string;
35
+ version: number;
36
+ createdAt: Date;
37
+ updatedAt: Date;
38
+ }
39
+ /**
40
+ * Controls how `getOrganizationAnalysis` obtains source results when the stored
41
+ * analysis is stale or absent.
42
+ *
43
+ * @property Analyze Read-through: request analysis from the sources, which may compute and
44
+ * leave the result pending until asynchronous work completes.
45
+ * @property Fetch Pull only the sources' existing values; never request new work. A stale
46
+ * domain with no existing source value is not moved to pending.
47
+ *
48
+ * @enum
49
+ */
50
+ export declare enum OrganizationAnalysisMode {
51
+ Analyze = "ANALYZE",
52
+ Fetch = "FETCH"
53
+ }
@@ -16,6 +16,8 @@
16
16
  * @property {string} identifier The presence identifier (e.g. email address).
17
17
  * @property {VirtualPresenceState} state The current state of the virtual presence.
18
18
  * @property {Date} lastScannedAt Date for when the virtual presence was last scanned.
19
+ * @property {string} lastScanFailureReason Reason the most recent completed scan failed (an error/exception name).
20
+ * Undefined when the most recent completed scan succeeded (or none has completed).
19
21
  * @property {Date} createdAt Date for when the virtual presence was created.
20
22
  * @property {Date} updatedAt Date for when the virtual presence was last updated.
21
23
  */
@@ -27,6 +29,7 @@ export interface VirtualPresence {
27
29
  identifier: string;
28
30
  state: VirtualPresenceState;
29
31
  lastScannedAt: Date;
32
+ lastScanFailureReason?: string;
30
33
  createdAt: Date;
31
34
  updatedAt: Date;
32
35
  }