@squidcloud/client 1.0.500 → 1.0.502
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.
- package/dist/cjs/index.js +1 -1
- package/dist/esm/index.js +1 -1
- package/dist/internal-common/src/public-types/ai-agent.public-types.d.ts +3 -3
- package/dist/internal-common/src/public-types/ai-knowledge-base.public-types.d.ts +14 -0
- package/dist/internal-common/src/public-types/connector.public-types.d.ts +45 -0
- package/dist/internal-common/src/types/ai-knowledge-base.types.d.ts +159 -0
- package/dist/internal-common/src/utils/connector-path-status.d.ts +27 -0
- package/dist/typescript-client/src/admin-client.d.ts +1 -0
- package/dist/typescript-client/src/integration-client.d.ts +138 -1
- package/dist/typescript-client/src/version.d.ts +1 -1
- package/package.json +1 -1
|
@@ -1144,11 +1144,11 @@ export interface UpsertContextStatusSuccess extends BaseUpsertContextStatus {
|
|
|
1144
1144
|
}
|
|
1145
1145
|
/**
|
|
1146
1146
|
* Names an upsert failure; `DUPLICATE_CONTENT` identifies existing content when contextId is omitted.
|
|
1147
|
-
* `EMBEDDING_FAILED`, `EXTRACTION_TIMED_OUT`, `PROVIDER_ACCESS_DENIED`, and
|
|
1148
|
-
* succeed on retry. Document faults carry `retryable: false` because the same bytes fail again.
|
|
1147
|
+
* `CONTENT_IN_FLIGHT`, `EMBEDDING_FAILED`, `EXTRACTION_TIMED_OUT`, `PROVIDER_ACCESS_DENIED`, and
|
|
1148
|
+
* `SOURCE_UNREACHABLE` may succeed on retry. Document faults carry `retryable: false` because the same bytes fail again.
|
|
1149
1149
|
* @category AI
|
|
1150
1150
|
*/
|
|
1151
|
-
export type UpsertContextErrorCode = 'CONTENT_TOO_LARGE' | 'DUPLICATE_CONTENT' | 'EMBEDDING_FAILED' | 'ENCRYPTED_DOCUMENT' | 'EXTRACTION_TIMED_OUT' | 'IMAGE_OVER_PROVIDER_LIMIT' | 'NO_EMBEDDABLE_CONTENT' | 'PROVIDER_ACCESS_DENIED' | 'SOURCE_OVER_PROVIDER_LIMIT' | 'SOURCE_UNREACHABLE' | 'UNREADABLE_DOCUMENT' | 'UNREADABLE_WORKBOOK' | 'UNSUPPORTED_FILE_TYPE';
|
|
1151
|
+
export type UpsertContextErrorCode = 'CONTENT_IN_FLIGHT' | 'CONTENT_TOO_LARGE' | 'DUPLICATE_CONTENT' | 'EMBEDDING_FAILED' | 'ENCRYPTED_DOCUMENT' | 'EXTRACTION_TIMED_OUT' | 'IMAGE_OVER_PROVIDER_LIMIT' | 'NO_EMBEDDABLE_CONTENT' | 'PROVIDER_ACCESS_DENIED' | 'SOURCE_OVER_PROVIDER_LIMIT' | 'SOURCE_UNREACHABLE' | 'UNREADABLE_DOCUMENT' | 'UNREADABLE_WORKBOOK' | 'UNSUPPORTED_FILE_TYPE';
|
|
1152
1152
|
/**
|
|
1153
1153
|
* The existing context a `DUPLICATE_CONTENT` rejection points at — where the byte-identical original
|
|
1154
1154
|
* already lives.
|
|
@@ -399,6 +399,12 @@ export interface AiKnowledgeBaseChatOptions {
|
|
|
399
399
|
* Composes with every `searchMode` and with `contextMetadataFilter`. Requires `graphRag.enabled`.
|
|
400
400
|
*/
|
|
401
401
|
graphFilter?: AiKnowledgeBaseGraphFilter;
|
|
402
|
+
/**
|
|
403
|
+
* Returns superseded versions of a document (older drafts a source marked as replaced by a newer version)
|
|
404
|
+
* too, instead of only the final version. For questions pinned to a point in time ("the original model",
|
|
405
|
+
* "as of 2019"). Access control still applies.
|
|
406
|
+
*/
|
|
407
|
+
includeSupersededVersions?: boolean;
|
|
402
408
|
}
|
|
403
409
|
/**
|
|
404
410
|
* Graph scope for a knowledge-base search: restricts results to the documents under one concept.
|
|
@@ -760,6 +766,12 @@ export interface AiKnowledgeBaseSearchOptions {
|
|
|
760
766
|
* Composes with every `searchMode` and with `contextMetadataFilter`. Requires `graphRag.enabled`.
|
|
761
767
|
*/
|
|
762
768
|
graphFilter?: AiKnowledgeBaseGraphFilter;
|
|
769
|
+
/**
|
|
770
|
+
* Returns superseded versions of a document (older drafts a source marked as replaced by a newer version)
|
|
771
|
+
* too, instead of only the final version. For questions pinned to a point in time ("the original model",
|
|
772
|
+
* "as of 2019"). Access control still applies.
|
|
773
|
+
*/
|
|
774
|
+
includeSupersededVersions?: boolean;
|
|
763
775
|
}
|
|
764
776
|
/**
|
|
765
777
|
* A single chunk of data returned from an AI search operation.
|
|
@@ -877,6 +889,8 @@ export interface GrepKnowledgeBaseOptions {
|
|
|
877
889
|
* and is clamped to {@link GREP_KNOWLEDGE_BASE_MAX_MATCHES}.
|
|
878
890
|
*/
|
|
879
891
|
maxMatches?: number;
|
|
892
|
+
/** Scans the text of superseded versions too; by default only the final version of a document is scanned. */
|
|
893
|
+
includeSupersededVersions?: boolean;
|
|
880
894
|
}
|
|
881
895
|
/**
|
|
882
896
|
* Request structure for a literal scan over a knowledge base's raw extracted text.
|
|
@@ -10,3 +10,48 @@ export declare const CONNECTOR_IDS: readonly ["bitbucket", "confluence", "connec
|
|
|
10
10
|
* @category Platform
|
|
11
11
|
*/
|
|
12
12
|
export type ConnectorId = (typeof CONNECTOR_IDS)[number];
|
|
13
|
+
/** Where one file/folder sits in a connector's own tracking, independent of the KB ledger. */
|
|
14
|
+
export type ConnectorPathStatusClassification = 'indexed' | 'staged' | 'failed' | 'skipped' | 'folder_tracked';
|
|
15
|
+
/** The durable ingestion status of one file in the knowledge base ledger, as {@link ConnectorPathStatusEntry.kbStatus}. */
|
|
16
|
+
export interface ConnectorKbFileStatus {
|
|
17
|
+
/** The file's current durable status in the knowledge base ledger. */
|
|
18
|
+
status: 'no_record' | 'in_progress' | 'completed' | 'failed';
|
|
19
|
+
/** Present only when `status` is `'failed'`. */
|
|
20
|
+
errorMessage?: string;
|
|
21
|
+
/** Present only when `status` is `'failed'`, when known. */
|
|
22
|
+
errorCode?: string;
|
|
23
|
+
/** When this status was last recorded; absent when `status` is `'no_record'`. */
|
|
24
|
+
updatedAt?: Date;
|
|
25
|
+
}
|
|
26
|
+
/** One file or folder a connector knows about at or under a searched path. */
|
|
27
|
+
export interface ConnectorPathStatusEntry {
|
|
28
|
+
/** The connector-specific id of the document. */
|
|
29
|
+
documentId: string;
|
|
30
|
+
/** The document's name. */
|
|
31
|
+
name: string;
|
|
32
|
+
/** Whether this document is a file or a folder. */
|
|
33
|
+
type: 'file' | 'folder';
|
|
34
|
+
/** Folder path, when this document was indexed through a folder. With `name`, forms the KB ledger's lookup path. */
|
|
35
|
+
folderPath?: string;
|
|
36
|
+
/** Where this document sits in the connector's own tracking. */
|
|
37
|
+
classification: ConnectorPathStatusClassification;
|
|
38
|
+
/** Message describing the most recent failure, when `classification` is `'failed'` or `'skipped'`. */
|
|
39
|
+
errorMessage?: string;
|
|
40
|
+
/** Last successful ingestion, when the document has one. */
|
|
41
|
+
lastIndexedDate?: Date;
|
|
42
|
+
/** The knowledge-base context ID this document maps to, when it has one. */
|
|
43
|
+
contextId?: string;
|
|
44
|
+
/** The KB ledger's own status for this file, when the connector resolved one. */
|
|
45
|
+
kbStatus?: ConnectorKbFileStatus;
|
|
46
|
+
}
|
|
47
|
+
/** A connector's own record of files/folders matching a searched path, from `Squid.getConnectorPathStatus`. */
|
|
48
|
+
export interface ConnectorPathStatusResult {
|
|
49
|
+
/** False when the integration's type doesn't expose path-status search (most types). */
|
|
50
|
+
supported: boolean;
|
|
51
|
+
/** The knowledge base this integration indexes into, when resolvable. */
|
|
52
|
+
knowledgeBaseId?: string;
|
|
53
|
+
/** The matching files/folders, absent when `supported` is false. */
|
|
54
|
+
entries?: Array<ConnectorPathStatusEntry>;
|
|
55
|
+
/** True when more matches exist than `entries` returns. */
|
|
56
|
+
truncated?: boolean;
|
|
57
|
+
}
|
|
@@ -122,6 +122,65 @@ export interface SetAiKnowledgeBaseContextScopesResponse {
|
|
|
122
122
|
/** How many chunks of the context had their scopes rewritten. */
|
|
123
123
|
updatedChunkCount: number;
|
|
124
124
|
}
|
|
125
|
+
/**
|
|
126
|
+
* Where a context stands in its version family, as computed by the source that owns the family rules.
|
|
127
|
+
* @category AI
|
|
128
|
+
*/
|
|
129
|
+
export interface AiKnowledgeBaseContextVersionState {
|
|
130
|
+
/** Stable id of the family, namespaced by the source (integration + site/drive). */
|
|
131
|
+
familyId: string;
|
|
132
|
+
/** Sortable rank key within the family: larger is more final. */
|
|
133
|
+
versionKey: string;
|
|
134
|
+
/** Revision of the rule set that produced this state. */
|
|
135
|
+
rulesRevision: string;
|
|
136
|
+
/** Whether a newer version of the same document makes this one superseded. */
|
|
137
|
+
superseded: boolean;
|
|
138
|
+
/** The context that supersedes this one; present when `superseded`. */
|
|
139
|
+
winnerContextId?: string;
|
|
140
|
+
/** Why the winner ranks above this context (`final-marker`, `higher-version`, ...). */
|
|
141
|
+
reason?: string;
|
|
142
|
+
}
|
|
143
|
+
/** Most contexts one {@link SetAiKnowledgeBaseContextVersionStatesRequest} may carry. */
|
|
144
|
+
export declare const MAX_AI_KNOWLEDGE_BASE_VERSION_STATE_BATCH = 250;
|
|
145
|
+
/**
|
|
146
|
+
* One context and its new version state.
|
|
147
|
+
* @category AI
|
|
148
|
+
*/
|
|
149
|
+
export interface AiKnowledgeBaseContextVersionStateItem {
|
|
150
|
+
/** The id of the AiKnowledgeBaseContext whose version state is replaced */
|
|
151
|
+
contextId: string;
|
|
152
|
+
/** The new version state; absent clears it, which makes the context a regular, never-superseded one. */
|
|
153
|
+
versionState?: AiKnowledgeBaseContextVersionState;
|
|
154
|
+
}
|
|
155
|
+
/**
|
|
156
|
+
* Request structure for replacing the version state of a batch of AiKnowledgeBaseContexts.
|
|
157
|
+
* @category AI
|
|
158
|
+
*/
|
|
159
|
+
export interface SetAiKnowledgeBaseContextVersionStatesRequest {
|
|
160
|
+
/** The id of the AiKnowledgeBase */
|
|
161
|
+
knowledgeBaseId: string;
|
|
162
|
+
/** At most {@link MAX_AI_KNOWLEDGE_BASE_VERSION_STATE_BATCH} items, each context at most once. */
|
|
163
|
+
items: Array<AiKnowledgeBaseContextVersionStateItem>;
|
|
164
|
+
}
|
|
165
|
+
/**
|
|
166
|
+
* The outcome for one context of a {@link SetAiKnowledgeBaseContextVersionStatesRequest}.
|
|
167
|
+
* @category AI
|
|
168
|
+
*/
|
|
169
|
+
export interface AiKnowledgeBaseContextVersionStateResult {
|
|
170
|
+
contextId: string;
|
|
171
|
+
/** False when no record exists for the context (not ingested yet, or deleted); nothing was written then. */
|
|
172
|
+
applied: boolean;
|
|
173
|
+
/** Whether the context's content is now hidden from search candidates. */
|
|
174
|
+
hidden: boolean;
|
|
175
|
+
}
|
|
176
|
+
/**
|
|
177
|
+
* Response structure for replacing the version state of a batch of AiKnowledgeBaseContexts.
|
|
178
|
+
* @category AI
|
|
179
|
+
*/
|
|
180
|
+
export interface SetAiKnowledgeBaseContextVersionStatesResponse {
|
|
181
|
+
/** One result per request item, in request order. */
|
|
182
|
+
results: Array<AiKnowledgeBaseContextVersionStateResult>;
|
|
183
|
+
}
|
|
125
184
|
/**
|
|
126
185
|
* Request structure for getting an AiKnowledgeBaseContext
|
|
127
186
|
* @category AI
|
|
@@ -396,6 +455,106 @@ export interface AiKnowledgeBaseGetGraphWriteLockStateResponse {
|
|
|
396
455
|
/** Writers queued for an exclusive hold. */
|
|
397
456
|
exclusiveWaiters: number;
|
|
398
457
|
}
|
|
458
|
+
/** Turns content dedup (ENG-2930) on or off for new ingests of one knowledge base. */
|
|
459
|
+
export interface AiKnowledgeBaseSetContentDedupRequest {
|
|
460
|
+
/** The ID of the App */
|
|
461
|
+
appId: AppId;
|
|
462
|
+
/** The ID of the AIKnowledgeBase */
|
|
463
|
+
knowledgeBaseId: AiKnowledgeBaseId;
|
|
464
|
+
/** Whether new ingests share stored content; false keeps reads of already shared content working. */
|
|
465
|
+
enabled: boolean;
|
|
466
|
+
}
|
|
467
|
+
/** Runs the duplicates migration (ENG-2930) over one knowledge base. */
|
|
468
|
+
export interface AiKnowledgeBaseMigrateContentDuplicatesRequest {
|
|
469
|
+
/** The ID of the App */
|
|
470
|
+
appId: AppId;
|
|
471
|
+
/** The ID of the AIKnowledgeBase */
|
|
472
|
+
knowledgeBaseId: AiKnowledgeBaseId;
|
|
473
|
+
/** `dryRun` counts only; `apply` converts copies and hides their storage; `purge` deletes what was hidden. */
|
|
474
|
+
mode: 'dryRun' | 'apply' | 'purge';
|
|
475
|
+
/** Upper bound on the groups this run changes; omitted = all. */
|
|
476
|
+
maxGroups?: number;
|
|
477
|
+
}
|
|
478
|
+
/** What one duplicates-migration run found and did. */
|
|
479
|
+
export interface AiKnowledgeBaseMigrateContentDuplicatesResponse {
|
|
480
|
+
/** Groups of identical contexts not yet stored once. */
|
|
481
|
+
groups: number;
|
|
482
|
+
/** Redundant copies across those groups. */
|
|
483
|
+
copies: number;
|
|
484
|
+
/** Groups this run changed. */
|
|
485
|
+
processedGroups: number;
|
|
486
|
+
/** Chunks this run hid. */
|
|
487
|
+
chunksHidden: number;
|
|
488
|
+
/** Hidden chunks this run deleted. */
|
|
489
|
+
chunksDeleted: number;
|
|
490
|
+
}
|
|
491
|
+
/** Drops the chunk search indexes superseded by `vector_idx_v4` and `bm25_idx_v2` (ENG-2917). */
|
|
492
|
+
export interface AiKnowledgeBaseDropSupersededSearchIndexesRequest {
|
|
493
|
+
/** One `kb_chunks_<dim>` collection; omitted = every chunk collection. */
|
|
494
|
+
embeddingDimensions?: number;
|
|
495
|
+
/** Reports what would be dropped, and why or why not, without dropping anything. */
|
|
496
|
+
dryRun: boolean;
|
|
497
|
+
/** Required to drop: every pod of the deployment runs with version suppression on (one pod cannot check). */
|
|
498
|
+
allPodsSuppressionEnabled?: boolean;
|
|
499
|
+
}
|
|
500
|
+
/** Per chunk collection, the superseded search indexes found and dropped. */
|
|
501
|
+
export interface AiKnowledgeBaseDropSupersededSearchIndexesResponse {
|
|
502
|
+
collections: Array<{
|
|
503
|
+
/** The chunk collection. */
|
|
504
|
+
collection: string;
|
|
505
|
+
/** The superseded indexes present that may go. */
|
|
506
|
+
droppable: Array<string>;
|
|
507
|
+
/** The indexes dropped; empty on a dry run. */
|
|
508
|
+
dropped: Array<string>;
|
|
509
|
+
/** Why they may or may not go. */
|
|
510
|
+
reason: string;
|
|
511
|
+
}>;
|
|
512
|
+
}
|
|
513
|
+
/** Test only: makes index-state probes of one chunk collection treat the named search indexes as not READY. */
|
|
514
|
+
export interface AiKnowledgeBaseHoldChunkSearchIndexesRequest {
|
|
515
|
+
/** The `kb_chunks_<dim>` collection. */
|
|
516
|
+
embeddingDimensions: number;
|
|
517
|
+
/** The indexes to hold; an empty list releases the collection. */
|
|
518
|
+
indexNames: Array<string>;
|
|
519
|
+
}
|
|
520
|
+
/** The collection's read targets, probed right after the hold changed. */
|
|
521
|
+
export interface AiKnowledgeBaseHoldChunkSearchIndexesResponse {
|
|
522
|
+
vectorIndexName: string;
|
|
523
|
+
bm25IndexName: string;
|
|
524
|
+
/** Whether reads apply the `hidden` predicate. */
|
|
525
|
+
hiddenFilterReady: boolean;
|
|
526
|
+
}
|
|
527
|
+
/** Test only: parks the next same-content re-ingest of a context between its read and its reservation. */
|
|
528
|
+
export interface AiKnowledgeBaseParkSameKeyReingestRequest {
|
|
529
|
+
/** The ID of the App */
|
|
530
|
+
appId: AppId;
|
|
531
|
+
/** The ID of the AIKnowledgeBase */
|
|
532
|
+
knowledgeBaseId: AiKnowledgeBaseId;
|
|
533
|
+
/** `arm` parks the next re-ingest of `contextId`, `release` lets it go, `status` only reports. */
|
|
534
|
+
action: 'arm' | 'release' | 'status';
|
|
535
|
+
/** The re-ingested context; required to arm. */
|
|
536
|
+
contextId?: AiContextId;
|
|
537
|
+
}
|
|
538
|
+
/** Whether a re-ingest is parked now. */
|
|
539
|
+
export interface AiKnowledgeBaseParkSameKeyReingestResponse {
|
|
540
|
+
parked: boolean;
|
|
541
|
+
}
|
|
542
|
+
/** Checks the content model (ENG-2930) of one knowledge base. */
|
|
543
|
+
export interface AiKnowledgeBaseCheckContentDedupRequest {
|
|
544
|
+
/** The ID of the App */
|
|
545
|
+
appId: AppId;
|
|
546
|
+
/** The ID of the AIKnowledgeBase */
|
|
547
|
+
knowledgeBaseId: AiKnowledgeBaseId;
|
|
548
|
+
}
|
|
549
|
+
/** The invariant-check outcome of one knowledge base's content model. */
|
|
550
|
+
export interface AiKnowledgeBaseCheckContentDedupResponse {
|
|
551
|
+
/** Live contents. */
|
|
552
|
+
contents: number;
|
|
553
|
+
/** Placements of live contents. */
|
|
554
|
+
placements: number;
|
|
555
|
+
/** Every broken invariant found; empty when the model is consistent. */
|
|
556
|
+
violations: Array<string>;
|
|
557
|
+
}
|
|
399
558
|
/**
|
|
400
559
|
* Request structure for the internal test-only route that sets a knowledge base's graph schema version.
|
|
401
560
|
* A migration test needs a KB on the older schema, which the creation path never produces.
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The registry of connectors that support path-status search, plus the shared dispatch logic that
|
|
3
|
+
* calls the right one by integration type. `ExecuteFunctionLike` duck-types the subset of
|
|
4
|
+
* `@squidcloud/client`'s `Squid` this needs; see `SquidServiceLike` in `./squid-service.utils` for
|
|
5
|
+
* the same pattern.
|
|
6
|
+
*/
|
|
7
|
+
import { IntegrationId } from '../public-types/communication.public-types';
|
|
8
|
+
import { ConnectorPathStatusResult } from '../public-types/connector.public-types';
|
|
9
|
+
import { IntegrationType } from '../public-types/integration.public-types';
|
|
10
|
+
/** How to call one connector's `get<X>PathStatus` executable: its name and its calling convention. */
|
|
11
|
+
export interface PathStatusExecutable {
|
|
12
|
+
functionName: string;
|
|
13
|
+
buildArgs: (integrationId: IntegrationId, path: string) => Array<unknown>;
|
|
14
|
+
}
|
|
15
|
+
/** Absent for a type ⇒ that connector doesn't track file/folder hierarchy beyond the KB ledger. */
|
|
16
|
+
export declare const PATH_STATUS_EXECUTABLE_BY_TYPE: Partial<Record<IntegrationType, PathStatusExecutable>>;
|
|
17
|
+
/** The subset of `Squid` (`@squidcloud/client`) this dispatch needs. */
|
|
18
|
+
export interface ExecuteFunctionLike {
|
|
19
|
+
executeFunction<T>(functionName: string, ...args: Array<unknown>): Promise<T>;
|
|
20
|
+
}
|
|
21
|
+
/**
|
|
22
|
+
* Searches a connector's own record of files/folders at a path, for connectors registered in
|
|
23
|
+
* {@link PATH_STATUS_EXECUTABLE_BY_TYPE}. Returns `{ supported: false }` when `integrationType` isn't
|
|
24
|
+
* registered — most integration types don't support this, and that's not an error. The caller (e.g.
|
|
25
|
+
* `IntegrationClient.getPathStatus`) already has the integration, so this doesn't re-fetch it.
|
|
26
|
+
*/
|
|
27
|
+
export declare function getConnectorPathStatus(executor: ExecuteFunctionLike, integrationType: IntegrationType, integrationId: IntegrationId, path: string): Promise<ConnectorPathStatusResult>;
|
|
@@ -11,6 +11,7 @@ export declare class AdminClient {
|
|
|
11
11
|
private readonly region;
|
|
12
12
|
private readonly appId;
|
|
13
13
|
private readonly consoleRegion;
|
|
14
|
+
private readonly backendFunctionManager;
|
|
14
15
|
private readonly integrationClient;
|
|
15
16
|
private readonly connectorClient;
|
|
16
17
|
private readonly secretClient;
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { DiscoverSourceRepositoriesResponse, IntegrationId, IntegrationInfo, IntegrationType } from './public-types';
|
|
1
|
+
import { ConnectorPathStatusResult, DiscoverSourceRepositoriesResponse, IntegrationId, IntegrationInfo, IntegrationType, JobId } from './public-types';
|
|
2
2
|
/**
|
|
3
3
|
* IntegrationClient manages integrations within an application,
|
|
4
4
|
* providing methods for listing, retrieving, updating, and deleting integrations.
|
|
@@ -6,6 +6,7 @@ import { DiscoverSourceRepositoriesResponse, IntegrationId, IntegrationInfo, Int
|
|
|
6
6
|
*/
|
|
7
7
|
export declare class IntegrationClient {
|
|
8
8
|
private readonly rpcManager;
|
|
9
|
+
private readonly backendFunctionManager;
|
|
9
10
|
private readonly iacBaseUrl;
|
|
10
11
|
/**
|
|
11
12
|
* Lists all enabled integrations for the current application.
|
|
@@ -23,6 +24,18 @@ export declare class IntegrationClient {
|
|
|
23
24
|
* @returns A promise that resolves with the integration info, or `undefined` if not found.
|
|
24
25
|
*/
|
|
25
26
|
get<ConfigurationType = Record<string, any>>(integrationId: IntegrationId): Promise<IntegrationInfo<ConfigurationType> | undefined>;
|
|
27
|
+
/**
|
|
28
|
+
* Searches a connector's own record of files/folders at a path — for connectors (SharePoint, and
|
|
29
|
+
* any future file/folder-hierarchy connector) that track more than the AI knowledge base ledger
|
|
30
|
+
* does. Returns `{ supported: false }` when the integration's type doesn't support this. The
|
|
31
|
+
* connector's own executable requires an API key, so this call fails unless the `Squid` instance
|
|
32
|
+
* is authenticated with one.
|
|
33
|
+
*
|
|
34
|
+
* @param integrationId - The ID of the integration to search.
|
|
35
|
+
* @param path - The path, folder, or filename to search for.
|
|
36
|
+
* @returns A promise that resolves to the connector's path-status result.
|
|
37
|
+
*/
|
|
38
|
+
getPathStatus(integrationId: IntegrationId, path: string): Promise<ConnectorPathStatusResult>;
|
|
26
39
|
/**
|
|
27
40
|
* Enables a disabled integration. The integration becomes available again for runtime access and sync jobs.
|
|
28
41
|
*
|
|
@@ -123,6 +136,32 @@ export declare class IntegrationClient {
|
|
|
123
136
|
* @returns A promise that resolves with the discovered schema and collection readiness information.
|
|
124
137
|
*/
|
|
125
138
|
discoverDataConnectionSchema<SchemaType = Record<string, any>>(integrationId: IntegrationId): Promise<DiscoverDataConnectionSchemaResponse<SchemaType>>;
|
|
139
|
+
/**
|
|
140
|
+
* Starts inferring relationships from the data of a database integration, in the background, over its
|
|
141
|
+
* stored schema. It finds relationships no foreign key declares, discriminator columns, and columns that
|
|
142
|
+
* depend on each other, and writes the findings at the minimum confidence or above into the stored schema.
|
|
143
|
+
* Fails while another run of the integration is active.
|
|
144
|
+
*
|
|
145
|
+
* @param integrationId - The ID of the database integration.
|
|
146
|
+
* @param options - (Optional) What to look for and how much to spend on it.
|
|
147
|
+
* @returns A promise that resolves with the run's job ID, for `squid.jobs().awaitJob(jobId)`.
|
|
148
|
+
*/
|
|
149
|
+
startRelationshipInference(integrationId: IntegrationId, options?: RelationshipInferenceOptions): Promise<JobId>;
|
|
150
|
+
/**
|
|
151
|
+
* Returns the latest relationship-inference run of a database integration, with its progress and findings.
|
|
152
|
+
*
|
|
153
|
+
* @param integrationId - The ID of the database integration.
|
|
154
|
+
* @returns A promise that resolves with the run, or `undefined` when the integration never had one.
|
|
155
|
+
*/
|
|
156
|
+
getRelationshipInference<ItemType = Record<string, any>>(integrationId: IntegrationId): Promise<RelationshipInferenceRun<ItemType> | undefined>;
|
|
157
|
+
/**
|
|
158
|
+
* Stops the active relationship-inference run of a database integration. The run still writes what it
|
|
159
|
+
* found so far, and ends as 'cancelled'.
|
|
160
|
+
*
|
|
161
|
+
* @param integrationId - The ID of the database integration.
|
|
162
|
+
* @returns A promise that resolves when the run is asked to stop.
|
|
163
|
+
*/
|
|
164
|
+
cancelRelationshipInference(integrationId: IntegrationId): Promise<void>;
|
|
126
165
|
/**
|
|
127
166
|
* Tests a data connection (database) to verify it is working.
|
|
128
167
|
* Attempts to connect to the database and perform a basic operation to validate connectivity.
|
|
@@ -279,6 +318,104 @@ export interface DiscoverDataConnectionSchemaResponse<SchemaType = Record<string
|
|
|
279
318
|
* Information about collection readiness for CRUD operations and replication.
|
|
280
319
|
*/
|
|
281
320
|
collectionReadiness: Record<string, CollectionReadiness>;
|
|
321
|
+
/**
|
|
322
|
+
* What discovery could not read, such as the declared foreign keys, and kept as it was.
|
|
323
|
+
*/
|
|
324
|
+
warnings?: string[];
|
|
325
|
+
}
|
|
326
|
+
/**
|
|
327
|
+
* Options for a relationship-inference run.
|
|
328
|
+
* @category Platform
|
|
329
|
+
*/
|
|
330
|
+
export interface RelationshipInferenceOptions {
|
|
331
|
+
/** What to look for. Defaults to all three. */
|
|
332
|
+
kinds?: Array<'relationships' | 'dependencies' | 'discriminators'>;
|
|
333
|
+
/** Collections to examine, on both sides. Defaults to every collection in the schema. */
|
|
334
|
+
collections?: string[];
|
|
335
|
+
/** Instructions about the data, for the AI; given, they turn `useAi` on. */
|
|
336
|
+
instructions?: string;
|
|
337
|
+
/** Lets the AI propose relationships that names miss, settle close calls, and describe the associations it adds. Off by default. */
|
|
338
|
+
useAi?: boolean;
|
|
339
|
+
/** The lowest confidence written to the schema. Defaults to 'medium'. */
|
|
340
|
+
minConfidence?: 'high' | 'medium' | 'low';
|
|
341
|
+
/** Rows sampled per collection; every finding is judged on them. Defaults to 1,000. */
|
|
342
|
+
sampleSize?: number;
|
|
343
|
+
/** Also checks every finding on all rows, at one more query each. Off by default. */
|
|
344
|
+
verifyOnAllRows?: boolean;
|
|
345
|
+
/** When the run stops and keeps what it has: 60 minutes by default, or 240 with `verifyOnAllRows`; at most 1,440. */
|
|
346
|
+
maxDurationMinutes?: number;
|
|
347
|
+
/** Queries in flight at once. Defaults to 2; at most 8 and the integration's pool size. */
|
|
348
|
+
concurrency?: number;
|
|
349
|
+
}
|
|
350
|
+
/**
|
|
351
|
+
* A relationship-inference run of a database integration.
|
|
352
|
+
* @category Platform
|
|
353
|
+
*/
|
|
354
|
+
export interface RelationshipInferenceRun<ItemType = Record<string, any>> {
|
|
355
|
+
/** The ID of the database integration. */
|
|
356
|
+
integrationId: IntegrationId;
|
|
357
|
+
/** Whether the run is still going, and how it ended. */
|
|
358
|
+
status: 'running' | 'completed' | 'cancelled' | 'failed';
|
|
359
|
+
/** What the run does now, or 'done'. */
|
|
360
|
+
phase: 'profiling' | 'matching' | 'in-table' | 'verifying' | 'describing' | 'applying' | 'done';
|
|
361
|
+
/** The options the run was started with. */
|
|
362
|
+
options: RelationshipInferenceOptions;
|
|
363
|
+
/** How far the run got. */
|
|
364
|
+
progress: RelationshipInferenceProgress;
|
|
365
|
+
/** When the run started, in milliseconds since the epoch. */
|
|
366
|
+
startedAt: number;
|
|
367
|
+
/** When the run ended, in milliseconds since the epoch. */
|
|
368
|
+
endedAt?: number;
|
|
369
|
+
/** True when the time budget or a cancel ended the run before it judged every candidate. */
|
|
370
|
+
partial: boolean;
|
|
371
|
+
/** Why the run failed. */
|
|
372
|
+
error?: string;
|
|
373
|
+
/** Everything the run found, whether or not it went into the schema. Empty until the run ends. */
|
|
374
|
+
findings: Array<RelationshipInferenceFinding<ItemType>>;
|
|
375
|
+
/** Signatures of earlier inferred items this complete run did not find again, which it removed from the stored schema. */
|
|
376
|
+
removed?: Array<string>;
|
|
377
|
+
}
|
|
378
|
+
/**
|
|
379
|
+
* How far a relationship-inference run got.
|
|
380
|
+
* @category Platform
|
|
381
|
+
*/
|
|
382
|
+
export interface RelationshipInferenceProgress {
|
|
383
|
+
/** Collections to sample. */
|
|
384
|
+
collections: number;
|
|
385
|
+
/** Collections sampled so far. */
|
|
386
|
+
collectionsProfiled: number;
|
|
387
|
+
/** Key columns to check referencing columns against. */
|
|
388
|
+
keys: number;
|
|
389
|
+
/** Key columns checked so far. */
|
|
390
|
+
keysProbed: number;
|
|
391
|
+
/** Findings to check on all rows, with `verifyOnAllRows`. */
|
|
392
|
+
findingsToVerify: number;
|
|
393
|
+
/** Findings checked on all rows so far. */
|
|
394
|
+
findingsVerified: number;
|
|
395
|
+
/** Queries sent to the database so far. */
|
|
396
|
+
queries: number;
|
|
397
|
+
}
|
|
398
|
+
/**
|
|
399
|
+
* One thing a relationship-inference run found.
|
|
400
|
+
* @category Platform
|
|
401
|
+
*/
|
|
402
|
+
export interface RelationshipInferenceFinding<ItemType = Record<string, any>> {
|
|
403
|
+
/** Identifies the finding; without its kind prefix, it is the item's key in the schema. */
|
|
404
|
+
signature: string;
|
|
405
|
+
/** Which of `association`, `discriminator` and `dependency` holds the finding. */
|
|
406
|
+
kind: 'association' | 'discriminator' | 'dependency';
|
|
407
|
+
/** Whether the finding passed every check at the minimum confidence or above. */
|
|
408
|
+
eligible?: boolean;
|
|
409
|
+
/** Whether the finding went into the stored schema. */
|
|
410
|
+
applied: boolean;
|
|
411
|
+
/** Why the finding did not go into the stored schema. */
|
|
412
|
+
notAppliedReason?: string;
|
|
413
|
+
/** A relationship between two collections, as the schema's `associations` hold it. */
|
|
414
|
+
association?: ItemType;
|
|
415
|
+
/** A column whose value decides what the rest of its row means, as the schema's `discriminators` hold it. */
|
|
416
|
+
discriminator?: ItemType;
|
|
417
|
+
/** Two columns of a row that fix each other, as the schema's `columnDependencies` hold it. */
|
|
418
|
+
dependency?: ItemType;
|
|
282
419
|
}
|
|
283
420
|
/**
|
|
284
421
|
* Response from testing a data connection.
|