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

package/README.md

@@ -1,3 +1,60 @@
-# 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.
+Connect a table editor to Dexter. Dexter supplies matter context and owns Save; your app edits field values 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, send no values:
+client.sendChanges({ isValid: false });
+
+// On teardown:
+client.disconnect();
+```
+
+Replace the comments with your editor's behaviour. Connection starts automatically; no context request is needed. A late matter-update handler receives the latest context. Registering a handler replaces its previous callback.
+
+The matter-update 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 leave protection. Dexter independently validates changes, tracks unsaved values and enables Save when appropriate. Reverting to persisted values clears the dirty state. Your app may continue editing during a save.
+
+Save success acknowledges persistence without returning data. Dexter forwards its own context updates separately; the SDK does not fetch, merge or reorder them. External updates do not merge or replace a valid submitted draft. If your app adopts updated values, call `sendChanges` again. Reloading the iframe discards the draft.
+
+`handleSaveError` also reports invalid changes and connection failures. The initial handshake keeps retrying until Dexter is ready or the app is torn down. 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,426 @@
+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;
+    disconnect(): void;
+}
+type TableAppClientOptions = TransportOptions;
+declare const createTableAppClient: (options?: TableAppClientOptions) => TableAppClient;
+
+export { createTableAppClient };
+export type { FieldV2Dto, MatterContext, MatterDto, MatterLookupsDto, TableAppChanges, TableAppClient, TableAppClientOptions, TableAppUpdate, TableDto, TableLookupDto };