@corto-ai/dexter-integrations 0.0.0-stage → 0.1.1-dev.0

package/README.md

@@ -1,3 +1,64 @@
-# Temporary Holding Version
+# @corto-ai/dexter-integrations
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Allows connecting a table editor to Dexter. Dexter supplies matter values and lookups and controls saving.
+Your app edits field values, sends all edits to dexter, receives live matter updates and displays errors.
+
+## Install
+
+```sh
+npm install @corto-ai/dexter-integrations
+```
+
+## Use
+
+```typescript
+import { createTableAppClient } from '@corto-ai/dexter-integrations';
+
+const client = createTableAppClient();
+
+client.handleMatterUpdate((update) => {
+  // Initialise your editor from update.table and update.tableLookups.
+  // Later updates are external changes: your app decides how to handle them.
+  // update also includes matter, lookups and tableId.
+});
+
+client.handleSaveSuccess(() => {
+  // Persistence succeeded. This callback has no payload.
+  // Updated data arrives separately through handleMatterUpdate.
+});
+
+client.handleSaveError((error) => {
+  // Display error.message in your app.
+});
+
+// After EVERY edit, send the complete current set of field values:
+client.sendChanges({
+  values: { 'your-field-id': 'New value' },
+  isValid: true
+});
+
+// For an invalid edit, you do not need to send values:
+client.sendChanges({ isValid: false });
+```
+
+The connection starts automatically when you call createTableAppClient(). The initial handshake keeps retrying until Dexter is ready.
+
+If any messages are sent in either direction before the connection establishes, the latest payloads will be sent on connection.
+
+Re-registering a handler will replace previous registrations of that handler.
+
+The handleMatterUpdate callback receives `{ matter, lookups, tableId, table, tableLookups }`, using Dexter API DTOs.
+
+## Editing
+
+Only use field IDs permitted by `tableLookups.fields`. You can populate an allowed field that is not yet present in the table. An empty string clears a value; omitted values also count as empty, so always send the complete draft.
+
+Send only `{ isValid: false }` for invalid edits. The SDK discards draft values and blocks Save; invalid edits still count as unsaved for navigation blocking.
+
+Dexter independently validates changes, tracks unsaved values and enables Save when appropriate. Your app may continue editing during a save.
+
+All matter updates (provided through handleMatterUpdate) do not merge or replace your draft. If your app adopts updated values, call `sendChanges` again. Reloading the iframe discards the draft.
+
+`handleSaveError` also reports invalid changes and connection failures. After 10 seconds it reports a one-time waiting warning and continues trying. The SDK never automatically retries saves.
+
+Callback errors are reported through `handleSaveError` without disconnecting. Errors thrown by the error handler itself are logged to the browser console to avoid recursive reporting.

package/index.d.ts

@@ -0,0 +1,425 @@
+type CountryCode = 'AU' | 'GB' | 'US' | 'CA' | 'IE' | 'NZ' | 'AD' | 'AE' | 'AF' | 'AG' | 'AI' | 'AL' | 'AM' | 'AO' | 'AQ' | 'AR' | 'AS' | 'AT' | 'AW' | 'AX' | 'AZ' | 'BA' | 'BB' | 'BD' | 'BE' | 'BF' | 'BG' | 'BH' | 'BI' | 'BJ' | 'BL' | 'BM' | 'BN' | 'BO' | 'BQ' | 'BR' | 'BS' | 'BT' | 'BV' | 'BW' | 'BY' | 'BZ' | 'CC' | 'CD' | 'CF' | 'CG' | 'CH' | 'CI' | 'CK' | 'CL' | 'CM' | 'CN' | 'CO' | 'CR' | 'CU' | 'CV' | 'CW' | 'CX' | 'CY' | 'CZ' | 'DE' | 'DJ' | 'DK' | 'DM' | 'DO' | 'DZ' | 'EC' | 'EE' | 'EG' | 'EH' | 'ER' | 'ES' | 'ET' | 'FI' | 'FJ' | 'FK' | 'FM' | 'FO' | 'FR' | 'GA' | 'GD' | 'GE' | 'GF' | 'GG' | 'GH' | 'GI' | 'GL' | 'GM' | 'GN' | 'GP' | 'GQ' | 'GR' | 'GS' | 'GT' | 'GU' | 'GW' | 'GY' | 'HK' | 'HM' | 'HN' | 'HR' | 'HT' | 'HU' | 'ID' | 'IL' | 'IM' | 'IN' | 'IO' | 'IQ' | 'IR' | 'IS' | 'IT' | 'JE' | 'JM' | 'JO' | 'JP' | 'KE' | 'KG' | 'KH' | 'KI' | 'KM' | 'KN' | 'KP' | 'KR' | 'KW' | 'KY' | 'KZ' | 'LA' | 'LB' | 'LC' | 'LI' | 'LK' | 'LR' | 'LS' | 'LT' | 'LU' | 'LV' | 'LY' | 'MA' | 'MC' | 'MD' | 'ME' | 'MF' | 'MG' | 'MH' | 'MK' | 'ML' | 'MM' | 'MN' | 'MO' | 'MP' | 'MQ' | 'MR' | 'MS' | 'MT' | 'MU' | 'MV' | 'MW' | 'MX' | 'MY' | 'MZ' | 'NA' | 'NC' | 'NE' | 'NF' | 'NG' | 'NI' | 'NL' | 'NO' | 'NP' | 'NR' | 'NU' | 'OM' | 'PA' | 'PE' | 'PF' | 'PG' | 'PH' | 'PK' | 'PL' | 'PM' | 'PN' | 'PR' | 'PS' | 'PT' | 'PW' | 'PY' | 'QA' | 'RE' | 'RO' | 'RS' | 'RU' | 'RW' | 'SA' | 'SB' | 'SC' | 'SD' | 'SE' | 'SG' | 'SH' | 'SI' | 'SJ' | 'SK' | 'SL' | 'SM' | 'SN' | 'SO' | 'SR' | 'SS' | 'ST' | 'SV' | 'SX' | 'SY' | 'SZ' | 'TC' | 'TD' | 'TF' | 'TG' | 'TH' | 'TJ' | 'TK' | 'TL' | 'TM' | 'TN' | 'TO' | 'TR' | 'TT' | 'TV' | 'TW' | 'TZ' | 'UA' | 'UG' | 'UM' | 'UY' | 'UZ' | 'VA' | 'VC' | 'VE' | 'VG' | 'VI' | 'VN' | 'VU' | 'WF' | 'WS' | 'YE' | 'YT' | 'ZA' | 'ZM' | 'ZW' | 'Invalid';
+
+type CandidateStatus = 'Pending' | 'Confirmed' | 'Rejected';
+
+interface CandidateReferenceDto {
+    clientDocumentId?: string;
+    documentName?: string;
+    sourceQuote?: string;
+}
+
+interface ValueProvenanceDto {
+    references: Array<CandidateReferenceDto>;
+}
+
+interface DateTimeValueCandidateDto {
+    decidedByUserId?: string;
+    id: string;
+    isBestMatch: boolean;
+    provenance: ValueProvenanceDto;
+    status: CandidateStatus;
+    value: string;
+}
+
+type UpdateSource = 'User' | 'AI' | 'Admin';
+
+interface ValueAttributionDto {
+    source: UpdateSource;
+    updatedAt: string;
+    userId?: string;
+}
+
+interface CriticalDateDto {
+    attribution?: ValueAttributionDto;
+    candidates: Array<DateTimeValueCandidateDto>;
+    date?: string;
+    id: string;
+    name: string;
+}
+
+interface ActorType {
+    id?: string;
+    name?: string;
+}
+
+type EmailAddressType = 'Home' | 'Work';
+
+interface StringValueCandidateDto {
+    decidedByUserId?: string;
+    id: string;
+    isBestMatch: boolean;
+    provenance: ValueProvenanceDto;
+    status: CandidateStatus;
+    value: string;
+}
+
+interface EmailAddressV2Dto {
+    attribution?: ValueAttributionDto;
+    candidates: Array<StringValueCandidateDto>;
+    type: EmailAddressType;
+    value: string;
+}
+
+type OrganisationType = 'Business' | 'Family' | 'Government' | 'Trust';
+
+type PartyNature = 'Person' | 'Organisation';
+
+type PhoneNumberType = 'Home' | 'Work' | 'Mobile';
+
+interface PhoneNumberV2Dto {
+    attribution?: ValueAttributionDto;
+    candidates: Array<StringValueCandidateDto>;
+    type: PhoneNumberType;
+    value: string;
+}
+
+type StreetAddressType = 'Home' | 'Work';
+
+interface StreetAddressValueDto {
+    buildingName?: string;
+    city: string;
+    country: string;
+    number: string;
+    postalCode: string;
+    state: string;
+    street: string;
+    unitFlatShop?: string;
+}
+
+interface StreetAddressValueDtoValueCandidateDto {
+    decidedByUserId?: string;
+    id: string;
+    isBestMatch: boolean;
+    provenance: ValueProvenanceDto;
+    status: CandidateStatus;
+    value: StreetAddressValueDto;
+}
+
+interface StreetAddressV2Dto {
+    attribution?: ValueAttributionDto;
+    buildingName?: string;
+    candidates: Array<StreetAddressValueDtoValueCandidateDto>;
+    city: string;
+    country: string;
+    number: string;
+    postalCode: string;
+    state: string;
+    street: string;
+    type: StreetAddressType;
+    unitFlatShop?: string;
+}
+
+interface ContactDetailsDto {
+    emailAddresses: Array<EmailAddressV2Dto>;
+    fullName: string;
+    id: string;
+    organisationType?: OrganisationType;
+    partyNature?: PartyNature;
+    phoneNumbers: Array<PhoneNumberV2Dto>;
+    streetAddresses: Array<StreetAddressV2Dto>;
+}
+
+interface EmailAddressDto {
+    type: EmailAddressType;
+    value: string;
+}
+
+interface FieldV2Dto {
+    attribution?: ValueAttributionDto;
+    candidates: Array<StringValueCandidateDto>;
+    dataType: string;
+    description: string;
+    groupName: string;
+    id: string;
+    isBaseTableField?: boolean;
+    name: string;
+    sortOrder?: number;
+    value: string;
+}
+
+interface PartyParentDto {
+    attribution?: ValueAttributionDto;
+    id: string;
+    isSuppressed?: boolean;
+    parentPartyId?: string;
+    parentTableId?: string;
+    provenance: ValueProvenanceDto;
+    suppressedAt?: string;
+}
+
+interface BaseRole {
+    id?: string;
+    name?: string;
+}
+
+interface BaseRoleValueCandidateDto {
+    decidedByUserId?: string;
+    id: string;
+    isBestMatch: boolean;
+    provenance: ValueProvenanceDto;
+    status: CandidateStatus;
+    value: BaseRole;
+}
+
+interface PartyBaseRoleV2Dto {
+    attribution?: ValueAttributionDto;
+    candidates: Array<BaseRoleValueCandidateDto>;
+    value?: BaseRole;
+}
+
+interface PartyRoleValueV2Dto {
+    id: string;
+    name: string;
+}
+
+interface PartyRoleValueV2DtoValueCandidateDto {
+    decidedByUserId?: string;
+    id: string;
+    isBestMatch: boolean;
+    provenance: ValueProvenanceDto;
+    status: CandidateStatus;
+    value: PartyRoleValueV2Dto;
+}
+
+interface PartyRoleInfoV2Dto {
+    attribution?: ValueAttributionDto;
+    baseRole: PartyBaseRoleV2Dto;
+    candidates: Array<PartyRoleValueV2DtoValueCandidateDto>;
+    value: PartyRoleValueV2Dto;
+}
+
+interface PhoneNumberDto {
+    type: PhoneNumberType;
+    value: string;
+}
+
+interface StreetAddressDto {
+    buildingName?: string;
+    city: string;
+    country: string;
+    number: string;
+    postalCode: string;
+    state: string;
+    street: string;
+    type: StreetAddressType;
+    unitFlatShop?: string;
+}
+
+interface MatterPartyDto {
+    actorType?: ActorType;
+    contact?: ContactDetailsDto;
+    contactId?: string;
+    /** @deprecated */ emailAddresses: Array<EmailAddressDto>;
+    fields: Array<FieldV2Dto>;
+    /** @deprecated */ fullName: string;
+    id: string;
+    parents: Array<PartyParentDto>;
+    /** @deprecated */ phoneNumbers: Array<PhoneNumberDto>;
+    roleInfo: PartyRoleInfoV2Dto;
+    sortOrder?: number;
+    /** @deprecated */ streetAddresses: Array<StreetAddressDto>;
+}
+
+interface MatterStageDto {
+    id: string;
+    name: string;
+}
+
+type MatterSyncStatus = 'Never' | 'Started' | 'Finished';
+
+interface StaffMemberDto {
+    id: string;
+    name?: string;
+}
+
+interface StaffDto {
+    acting?: StaffMemberDto;
+    assisting?: StaffMemberDto;
+    credit?: StaffMemberDto;
+    responsible?: StaffMemberDto;
+}
+
+interface TableDto$1 {
+    description: string;
+    fields: Array<FieldV2Dto>;
+    id: string;
+    name: string;
+    parentPartyId?: string;
+    parentTableId?: string;
+    sortOrder?: number;
+    templateTableId: string;
+}
+
+interface MatterDto$1 {
+    countryCode: CountryCode;
+    criticalDates: Array<CriticalDateDto>;
+    description: string;
+    firmId: string;
+    id: string;
+    industryCategoryId: string;
+    industryCategoryName: string;
+    isUserManaged: boolean;
+    matterTypeDescription?: string;
+    matterTypeId?: string;
+    matterTypeName?: string;
+    name: string;
+    parties: Array<MatterPartyDto>;
+    staff: StaffDto;
+    state?: string;
+    status?: MatterStageDto;
+    syncStatus: MatterSyncStatus;
+    tables: Array<TableDto$1>;
+}
+
+interface AreaOfLawLookupDto {
+    id: string;
+    name: string;
+}
+
+interface StateLookupDto {
+    code: string;
+    name: string;
+}
+
+interface CountryLookupDto {
+    code: CountryCode;
+    name: string;
+    states?: Array<StateLookupDto>;
+}
+
+interface CriticalDateLookupDto {
+    description: string;
+    id: string;
+    name: string;
+}
+
+interface CurrencyLookupDto {
+    code: string;
+    name: string;
+}
+
+interface IndustryCategoryLookupDto {
+    id: string;
+    name: string;
+}
+
+interface MatterTypeTreeLeafDto {
+    ancestry?: Array<string>;
+    description: string;
+    id: string;
+    name: string;
+}
+
+interface MatterTypeFolderTreeDto {
+    ancestry?: Array<string>;
+    folders?: Array<MatterTypeFolderTreeDto>;
+    id: string;
+    matterTypes?: Array<MatterTypeTreeLeafDto>;
+    name: string;
+    sortOrder?: number;
+}
+
+interface FieldLookupDto {
+    allowableValues: Array<string>;
+    dataType: string;
+    description: string;
+    fieldId: string;
+    groupName: string;
+    name: string;
+    sortOrder?: number;
+    tableId: string;
+}
+
+interface PartyRoleLookupDto {
+    candidateBaseRoles?: Array<BaseRole>;
+    fields?: Array<FieldLookupDto>;
+    id: string;
+    name: string;
+    parentId?: string;
+    sortOrder?: number;
+}
+
+interface RepresentationRoleDto {
+    id: string;
+    name: string;
+}
+
+interface RepresentationRoleLookupDto {
+    actingFor?: Array<RepresentationRoleDto>;
+    opposing?: Array<RepresentationRoleDto>;
+}
+
+interface StaffLookupDto {
+    id: string;
+    name: string;
+}
+
+interface StatusLookupDto {
+    description: string;
+    id: string;
+    name: string;
+}
+
+interface TableLookupDto {
+    description: string;
+    fields?: Array<FieldLookupDto>;
+    id: string;
+    name: string;
+    parentId?: string;
+    sortOrder?: number;
+}
+
+interface MatterLookupsDto {
+    areasOfLaw?: Array<AreaOfLawLookupDto>;
+    countries?: Array<CountryLookupDto>;
+    criticalDates?: Array<CriticalDateLookupDto>;
+    currencies?: Array<CurrencyLookupDto>;
+    industryCategories?: Array<IndustryCategoryLookupDto>;
+    matterTypeTree?: Array<MatterTypeFolderTreeDto>;
+    partyRoles?: Array<PartyRoleLookupDto>;
+    representationRoles?: RepresentationRoleLookupDto;
+    staff?: Array<StaffLookupDto>;
+    statuses?: Array<StatusLookupDto>;
+    tables?: Array<TableLookupDto>;
+}
+
+type TableDto = TableDto$1 & {
+    appUrl?: string;
+};
+type MatterDto = Omit<MatterDto$1, 'tables'> & {
+    tables: TableDto[];
+};
+
+interface MatterContext {
+    matter: MatterDto;
+    lookups: MatterLookupsDto;
+}
+interface TableAppUpdate extends MatterContext {
+    tableId: string;
+    table: TableDto;
+    tableLookups: TableLookupDto;
+}
+type TableAppChanges = {
+    isValid: true;
+    values: Record<string, string>;
+} | {
+    isValid: false;
+    values?: never;
+};
+
+interface TransportOptions {
+    /** Report a slow initial handshake after this delay; keep waiting. Defaults to 10 seconds. */
+    timeoutMs?: number;
+}
+
+interface TableAppClient {
+    handleMatterUpdate(callback: (update: TableAppUpdate) => void): void;
+    sendChanges(changes: TableAppChanges): void;
+    handleSaveSuccess(callback: () => void): void;
+    handleSaveError(callback: (error: Error) => void): void;
+}
+type TableAppClientOptions = TransportOptions;
+declare const createTableAppClient: (options?: TableAppClientOptions) => TableAppClient;
+
+export { createTableAppClient };
+export type { FieldV2Dto, MatterContext, MatterDto, MatterLookupsDto, TableAppChanges, TableAppClient, TableAppClientOptions, TableAppUpdate, TableDto, TableLookupDto };