@larc-iu/plaid-client 0.2.0-alpha.3 → 0.2.0-alpha.30

package/src/types.d.ts

@@ -0,0 +1,867 @@
+export type TextEditOp = import("./textEdits.js").TextEditOp;
+export type TextGap = import("./textEdits.js").TextGap;
+export type MetadataOp = import("./metadataOps.js").MetadataOp;
+export type LayerConstraint = import("./constraints.js").LayerConstraint;
+export type ConstraintWriteOptions = import("./constraints.js").ConstraintWriteOptions;
+export type ConstraintViolation = import("./constraints.js").ConstraintViolation;
+export type Requester = import("./requester.js").Requester;
+export type BatchRef = import("./batchRef.js").BatchRef;
+export type ServiceParam = import("./serviceSchema.js").ServiceParam;
+export type ServiceInfo = import("./serviceSchema.js").ServiceInfo;
+export type DiscoveredService = import("./serviceSchema.js").DiscoveredService;
+export type ResponseHelper = import("./services.js").ResponseHelper;
+export type ServiceRegistration = import("./services.js").ServiceRegistration;
+export type ServiceStatusEvent = import("./services.js").ServiceStatusEvent;
+export type OperationGroupsBundle = import("./client.js").PlaidClient["operationGroups"];
+/**
+ * A single page of a cursor-paginated collection.
+ */
+export type Page<T = any> = {
+    entries: T[];
+    nextCursor: string | null;
+};
+/**
+ * Client options.
+ */
+export type PlaidClientOptions = {
+    /**
+     * Per-request timeout in ms (default
+     * 30000, 0 or null disables it).
+     */
+    timeout?: number | null;
+    /**
+     * Timeout for batch submissions in
+     * ms (default 180000, 0 or null disables it). Aborting a batch does NOT
+     * stop the server, which keeps running the transaction and holding the
+     * write lock. Defaults to `timeout` when that is given and this is not.
+     */
+    batchTimeout?: number | null;
+    /**
+     * Delays in ms before sending a keyed
+     * write again when its answer was lost (no response, 502 or 504). Default
+     * [1000, 3000, 9000].
+     */
+    retryDelaysMs?: number[];
+    /**
+     * Fired once when
+     * a request returns HTTP 401 (missing, expired or invalid token). 403 does
+     * NOT trigger it.
+     */
+    onAuthError?: ((error: Error) => void) | null;
+};
+/**
+ * What kind of operation a logical-operation group is (`?group-kind=`).
+ */
+export type OperationKind = "assistant-plan" | "service-run" | "import" | "bulk-edit" | "guess-adoption" | "repair" | "review";
+/**
+ * Idempotency-Key seed for an operation run more than once (`client.keySeed()`).
+ */
+export type KeySeed = {
+    seed: string;
+    stamps: Map<number, number | null>;
+};
+/**
+ * A batch: the client's bundles, on which every write of project data queues
+ * until `submit()`. See `PlaidClient.batch()`. `submit()` resolves to one
+ * result per operation, in order. `ref(opIndex, index)` stands for the id a
+ * queued operation will create, in the body of a later write on this batch.
+ */
+export type PlaidBatch = import("./client.js").PlaidClient & {
+    readonly client: import("./client.js").PlaidClient;
+    readonly operations: Array<{
+        path: string;
+        method: string;
+        body?: any;
+    }>;
+    submit(): Promise<any[]>;
+    abort(): void;
+    ref(opIndex?: number, index?: number): BatchRef;
+};
+/**
+ * Options for a single page of any audit log. `kinds` keeps only the entries
+ * of operations of these kinds, each whole. `order: "desc"` pages newest
+ * first, and a cursor belongs to the direction that made it. `opsLimit` keeps
+ * only each entry's oldest N operations in `ops` (1..1000), and every entry
+ * has `opCount`. `entryId` reads only that entry rather than a page.
+ */
+export type AuditPageOptions = {
+    startTime?: string;
+    endTime?: string;
+    opTypes?: string[] | string;
+    kinds?: OperationKind[] | string;
+    order?: "asc" | "desc";
+    limit?: number;
+    cursor?: string;
+    opsLimit?: number;
+    entryId?: string;
+};
+/**
+ * What `vocabLayers.restoreItem` did, or with `dryRun` would do.
+ */
+export type VocabItemRestoreSummary = {
+    /**
+     * The entry was gone and came back under its old id.
+     */
+    inserted: boolean;
+    /**
+     * A living entry's form was set back.
+     */
+    form: boolean;
+    /**
+     * A living entry's fields were set back.
+     */
+    metadata: boolean;
+    /**
+     * 0 when nothing changes.
+     */
+    total: number;
+};
+/**
+ * One private data entry. `version` is raised by one on every write of the
+ * entry, and a new entry is 1.
+ */
+export type UserDataEntry = {
+    key: string;
+    updatedAt: string;
+    version: number;
+    value?: any;
+};
+export type AdminUserDataEntry = UserDataEntry & {
+    userId: string;
+};
+/**
+ * One user's activity over a scope and window (`audit.tally`).
+ */
+export type ActivityTallyRow = {
+    user: {
+        id: string;
+        displayName?: string;
+    };
+    operations: number;
+    changes: number;
+    documents: number;
+    firstTs: string;
+    lastTs: string;
+    byDay?: Array<{
+        date: string;
+        changes: number;
+    }>;
+};
+/**
+ * What a constraint repair did in one document.
+ */
+export type ConstraintRepair = {
+    document: string;
+    constraint: string;
+    deleted: number;
+    joined: number;
+};
+/**
+ * A value-set rule as `refusedValues` takes it: the list, the characters a
+ * value is split on, and whether every part (`"all"`, the default) or only
+ * the first must be listed.
+ */
+export type ValueSetRule = {
+    values: string[];
+    delimiters?: string;
+    parts?: "all" | "first";
+};
+/**
+ * What a value-set rule would refuse in a layer's stored values: how many,
+ * how many distinct, and the most frequent with the parts not listed.
+ */
+export type RefusedValues = {
+    count: number;
+    valueCount: number;
+    values: Array<{
+        value: any;
+        parts: string[];
+        count: number;
+    }>;
+};
+/**
+ * Entities that can carry a comment.
+ */
+export type CommentableType = "document" | "text" | "token" | "span" | "relation" | "vocab-item";
+/**
+ * One comment. `projectId` and `documentId` are null for a comment on a
+ * vocabulary entry, and `vocabLayerId` is set only for one. `anchorLabel` is
+ * what the comment is about, in words, captured when it was posted: a
+ * comment outlives its anchor. `edited` is true once the body has been
+ * rewritten since it was posted.
+ */
+export type Comment = {
+    id: string;
+    projectId: string | null;
+    documentId: string | null;
+    vocabLayerId: string | null;
+    entityType: CommentableType;
+    entityId: string;
+    anchorLabel: string | null;
+    authorId: string;
+    body: string;
+    createdAt: string;
+    updatedAt: string;
+    edited: boolean;
+};
+/**
+ * One entry in a project's annotation manual. `body` is present on a single
+ * read and on a list made with `includeBodies`, `bodyChars` on a list made
+ * without. `pinned`: the assistant is given this one in full on every turn.
+ */
+export type Guideline = {
+    id: string;
+    projectId: string;
+    title: string;
+    body?: string;
+    bodyChars?: number;
+    pinned: boolean;
+    createdAt: string;
+    updatedAt: string;
+};
+/**
+ * A research-telemetry event type.
+ */
+export type ClientEventType = "suggestion.shown" | "suggestion.adopted" | "suggestion.dismissed" | "plan.opened";
+/**
+ * One research-telemetry event as the server stores it.
+ */
+export type ClientEvent = {
+    id: number;
+    projectId: string;
+    documentId: string | null;
+    userId: string;
+    type: ClientEventType;
+    targetId: string | null;
+    data: Record<string, any> | null;
+    clientTs: string | null;
+    ts: string;
+};
+/**
+ * An invite. `kind` is "signup" or "password-reset", `status` "active",
+ * "used", "expired", "revoked" or "inactive".
+ */
+export type Invite = {
+    id: string;
+    kind: string;
+    status: string;
+    createdBy: string;
+    createdAt: string;
+    expiresAt: string;
+    maxUses: number;
+    uses: number;
+    revokedAt: string | null;
+    note: string | null;
+    targetUserId: string | null;
+    grantAdmin: boolean;
+    projectId: string | null;
+    projectRole: string | null;
+};
+/**
+ * Server limits, as reported by /api/v1/info. An unset limit is absent.
+ * `passwordMinLength` is the shortest password the server accepts on any
+ * path, `lockExpirationMs` how long a document lock is held before it lapses.
+ * `queryBranches` is the most branches a query's `or` and `seq` may expand
+ * to, `queryClauseDepth` the deepest its clauses may nest.
+ */
+export type ServerLimits = {
+    mediaFileBytes?: number;
+    jsonBodyBytes?: number;
+    batchOperations?: number;
+    metadataDepth?: number;
+    metadataKeyCount?: number;
+    metadataStringLength?: number;
+    metadataTotalBytes?: number;
+    userDataValueBytes?: number;
+    guidelineTitleLength?: number;
+    guidelineBodyLength?: number;
+    commentBodyLength?: number;
+    passwordMinLength?: number;
+    lockExpirationMs?: number;
+    queryBranches?: number;
+    queryClauseDepth?: number;
+};
+export type ServerHealth = {
+    ok: boolean;
+    version: string;
+    uptimeMs: number;
+    audit: {
+        dbSizeMb?: number;
+        auditRows?: number;
+        error?: string;
+    };
+};
+export type RateLimitBucket = {
+    ip: string;
+    userId?: string;
+    failures: number;
+    limit: number;
+    blocked: boolean;
+};
+export type RateLimitSnapshot = {
+    windowMs: number;
+    logins: RateLimitBucket[];
+    ips: RateLimitBucket[];
+    invites: RateLimitBucket[];
+};
+export type BackupStatus = {
+    enabled: boolean;
+    directory: string;
+    retention: number;
+    time: string;
+    backups: Array<{
+        name: string;
+        bytes: number;
+        modified: string;
+    }>;
+    ok?: boolean;
+};
+export type ServerReport = {
+    version: string;
+    jvm: {
+        uptimeMs: number;
+        startedAt: string;
+        java: string;
+        heapUsed: number;
+        heapMax: number;
+    };
+    database: {
+        path: string | null;
+        bytes: number | null;
+        walBytes: number | null;
+        slowQueryThresholdMs?: number;
+        journalMode?: string;
+        maxPoolSize?: number;
+        tables: Record<string, number | null>;
+    };
+    media: {
+        directory: string;
+        files: number;
+        bytes: number;
+        orphans: number;
+        orphanBytes: number;
+    };
+    backup: BackupStatus;
+    settings: Record<string, any>;
+};
+/**
+ * The live log. Requests and events are buffered separately, so a burst of
+ * requests cannot evict an error. In each, `matched` is how many passed the
+ * filters (which may exceed what `entries` holds) and `held` how many are
+ * buffered in total. `file` is the configured log file's absolute path, or
+ * null when logging to stdout.
+ */
+export type LiveLog = {
+    requests: {
+        entries: object[];
+        matched: number;
+        held: number;
+        capacity: number;
+        stats: Record<string, number | null>;
+    };
+    events: {
+        entries: object[];
+        matched: number;
+        held: number;
+        capacity: number;
+        byLevel: Record<string, number>;
+    };
+    file: string | null;
+};
+/**
+ * An open server-sent-events stream. Once CLOSED, `error` says why: null when
+ * this side closed it. A refused stream's error carries the HTTP `status`,
+ * and one the server ended is named "StreamClosed".
+ */
+export type SSEConnection = {
+    close: () => void;
+    getStats: () => SSEStats;
+    readyState: number;
+    error: (Error & {
+        status?: number;
+    }) | null;
+};
+/**
+ * How an SSE connection has fared so far. `events` counts what arrived by
+ * event type ("audit-log", "message", "heartbeat", "connected", "other").
+ */
+export type SSEStats = {
+    durationSeconds: number;
+    isConnected: boolean;
+    isClosed: boolean;
+    clientId: string | null;
+    events: Record<string, number>;
+    readyState: number;
+};
+/**
+ * A value a span or relation holds: a JSON scalar.
+ */
+export type AtomicValue = string | number | boolean | null;
+/**
+ * What a create answers: the new record's id.
+ */
+export type Created = {
+    id: string;
+};
+/**
+ * A project. `textLayers` nests its layers in their display order, each
+ * with the layers built on it, and `vocabs` lists the vocabularies linked to
+ * it.
+ */
+export type Project = {
+    id: string;
+    name: string;
+    config: Record<string, any>;
+    readers: string[];
+    writers: string[];
+    maintainers: string[];
+    textLayers: ProjectTextLayer[];
+    vocabs: ProjectVocab[];
+};
+export type ProjectTextLayer = {
+    id: string;
+    name: string;
+    config: Record<string, any>;
+    tokenLayers: ProjectTokenLayer[];
+};
+export type ProjectTokenLayer = {
+    id: string;
+    name: string;
+    config: Record<string, any>;
+    constraints: Record<string, LayerConstraint[]>;
+    spanLayers: ProjectSpanLayer[];
+};
+export type ProjectSpanLayer = {
+    id: string;
+    name: string;
+    config: Record<string, any>;
+    constraints: Record<string, LayerConstraint[]>;
+    relationLayers: ProjectRelationLayer[];
+};
+export type ProjectRelationLayer = {
+    id: string;
+    name: string;
+    config: Record<string, any>;
+    constraints: Record<string, LayerConstraint[]>;
+};
+export type ProjectVocab = {
+    id: string;
+    name: string;
+    maintainers: string[];
+    config: Record<string, any>;
+};
+/**
+ * A document. `version` rises by one on every write to it or its layers.
+ * A read with `includeBody` also carries `textLayers`, the document's
+ * annotation nested under each layer.
+ */
+export type PlaidDocument = {
+    id: string;
+    name: string;
+    project: string;
+    version: number;
+    timeCreated: string;
+    timeModified: string;
+    metadata?: Record<string, any>;
+    textLayers?: DocumentTextLayer[];
+};
+/**
+ * A text layer as a document read nests it: `text` is null where the
+ * document has no text in this layer.
+ */
+export type DocumentTextLayer = {
+    id: string;
+    name: string;
+    config: Record<string, any>;
+    text: {
+        id: string;
+        document: string;
+        body: string;
+        digest: string;
+        metadata?: Record<string, any>;
+    } | null;
+    tokenLayers: DocumentTokenLayer[];
+};
+export type DocumentTokenLayer = {
+    id: string;
+    name: string;
+    config: Record<string, any>;
+    constraints: Record<string, LayerConstraint[]>;
+    overlapMode: string;
+    parentTokenLayer: string | null;
+    tokens: Array<{
+        id: string;
+        begin: number;
+        end: number;
+        precedence: number | null;
+        metadata?: Record<string, any>;
+    }>;
+    spanLayers: DocumentSpanLayer[];
+    vocabs: Array<ProjectVocab & {
+        vocabLinks: Array<{
+            id: string;
+            vocabItem: VocabItem;
+            tokens: string[];
+            metadata?: Record<string, any>;
+        }>;
+    }>;
+};
+export type DocumentSpanLayer = {
+    id: string;
+    name: string;
+    config: Record<string, any>;
+    constraints: Record<string, LayerConstraint[]>;
+    spans: Array<{
+        id: string;
+        value: AtomicValue;
+        tokens: string[];
+        metadata?: Record<string, any>;
+    }>;
+    relationLayers: Array<ProjectRelationLayer & {
+        relations: Array<{
+            id: string;
+            source: string;
+            target: string;
+            value: AtomicValue;
+            metadata?: Record<string, any>;
+        }>;
+    }>;
+};
+/**
+ * A text: one document's body in one text layer. `digest` names the body,
+ * as an edit's `base`.
+ */
+export type PlaidText = {
+    id: string;
+    body: string;
+    document: string;
+    layer: string;
+    digest: string;
+    metadata?: Record<string, any>;
+};
+/**
+ * What a text write changed besides the body: the tokens whose extent
+ * moved (with `layer` and `text` on one the write made), the spans and
+ * vocabulary links whose tokens or value changed, and the ids of what it
+ * deleted.
+ */
+export type TextReshape = {
+    tokens: Array<{
+        id: string;
+        begin: number;
+        end: number;
+        layer?: string;
+        text?: string;
+    }>;
+    spans: Array<{
+        id: string;
+        tokens?: string[];
+        value?: AtomicValue;
+    }>;
+    vocabLinks: Array<{
+        id: string;
+        tokens: string[];
+    }>;
+    deleted: {
+        tokens: string[];
+        spans: string[];
+        relations: string[];
+        vocabLinks: string[];
+    };
+};
+/**
+ * A token. `value` is the text it covers.
+ */
+export type Token = {
+    id: string;
+    text: string;
+    begin: number;
+    end: number;
+    layer: string;
+    document: string;
+    precedence: number | null;
+    value: string;
+    metadata?: Record<string, any>;
+};
+export type Span = {
+    id: string;
+    layer: string;
+    document: string;
+    value: AtomicValue;
+    tokens: string[];
+    metadata?: Record<string, any>;
+};
+/**
+ * A relation, from the span `source` to the span `target`.
+ */
+export type Relation = {
+    id: string;
+    layer: string;
+    document: string;
+    source: string;
+    target: string;
+    value: AtomicValue;
+    metadata?: Record<string, any>;
+};
+export type VocabItem = {
+    id: string;
+    layer: string;
+    form: string;
+    metadata?: Record<string, any>;
+};
+/**
+ * A link from a vocabulary entry to the tokens of one occurrence.
+ */
+export type VocabLink = {
+    id: string;
+    vocabItem: string;
+    document: string;
+    tokens: string[];
+    metadata?: Record<string, any>;
+};
+/**
+ * A vocabulary. `items` is there on a read made with `includeItems`.
+ */
+export type VocabLayer = {
+    id: string;
+    name: string;
+    timeCreated: string;
+    timeModified: string;
+    config: Record<string, any>;
+    maintainers: string[];
+    items?: VocabItem[];
+};
+export type TextLayer = {
+    id: string;
+    name: string;
+    project: string;
+    config: Record<string, any>;
+};
+export type TokenLayer = {
+    id: string;
+    name: string;
+    textLayer: string;
+    project: string;
+    overlapMode: string;
+    parentTokenLayer: string | null;
+    config: Record<string, any>;
+    constraints: Record<string, LayerConstraint[]>;
+};
+export type SpanLayer = {
+    id: string;
+    name: string;
+    tokenLayer: string;
+    project: string;
+    config: Record<string, any>;
+    constraints: Record<string, LayerConstraint[]>;
+};
+export type RelationLayer = {
+    id: string;
+    name: string;
+    spanLayer: string;
+    project: string;
+    config: Record<string, any>;
+    constraints: Record<string, LayerConstraint[]>;
+};
+/**
+ * The records with metadata, by the path segment of their routes.
+ */
+export type MetadataRecords = {
+    documents: PlaidDocument;
+    texts: PlaidText;
+    tokens: Token;
+    spans: Span;
+    relations: Relation;
+    "vocab-items": VocabItem;
+    "vocab-links": VocabLink;
+};
+/**
+ * The four layer kinds, by the path segment of their routes.
+ */
+export type LayerRecords = {
+    "text-layers": TextLayer;
+    "token-layers": TokenLayer;
+    "span-layers": SpanLayer;
+    "relation-layers": RelationLayer;
+};
+export type User = {
+    id: string;
+    displayName: string;
+    isAdmin: boolean;
+    deactivatedAt: string | null;
+    avatarHash: string | null;
+};
+/**
+ * A project as the project list gives it: the project, with how many
+ * documents it has and when the newest of them last changed.
+ */
+export type ProjectListEntry = Project & {
+    documentCount: number;
+    lastModified: string | null;
+};
+/**
+ * A document as a project's document list gives it.
+ */
+export type DocumentListEntry = {
+    id: string;
+    name: string;
+    version: number;
+    timeCreated: string;
+    timeModified: string;
+};
+/**
+ * A named API token, without the signed token itself, which only `create`
+ * returns.
+ */
+export type ApiToken = {
+    id: string;
+    userId: string;
+    name: string;
+    createdAt: string;
+    lastUsedAt: string | null;
+    revokedAt: string | null;
+};
+/**
+ * Who made an operation, as the audit log names them.
+ */
+export type AuditUser = {
+    id: string;
+    displayName: string;
+    avatarHash: string | null;
+};
+/**
+ * A project or a document an audit entry names, while it exists.
+ */
+export type AuditTarget = {
+    id: string;
+    name: string;
+};
+/**
+ * One operation of an audit entry.
+ */
+export type AuditOp = {
+    id: string;
+    /**
+     * The kind of write, such as "document/update".
+     */
+    type: string;
+    description: string;
+    time: string;
+    /**
+     * The time to read at to see the operation done.
+     */
+    endTime: string;
+    user: AuditUser | null;
+    credential?: string;
+    project?: AuditTarget;
+    document?: AuditTarget;
+    batchId?: string;
+};
+/**
+ * One entry of an audit log: a logical operation, an atomic batch or a lone
+ * write, with its operations oldest first (`ops`, cut to `opsLimit` when one
+ * was asked for, while `opCount` counts them all).
+ */
+export type AuditEntry = {
+    id: string;
+    time: string;
+    endTime: string;
+    user: AuditUser | null;
+    projects: AuditTarget[];
+    documents: AuditTarget[];
+    ops: AuditOp[];
+    opCount: number;
+    groupId?: string;
+    message?: string;
+    kind?: OperationKind;
+    ref?: string;
+    batchId?: string;
+    apiToken?: {
+        id: string;
+        name: string;
+    };
+    credential?: string;
+};
+/**
+ * A document lock as its holder sees it. `expiresAt` is in epoch
+ * milliseconds.
+ */
+export type LockGrant = {
+    lockId: string;
+    userId: string;
+    expiresAt: number;
+};
+/**
+ * What `documents.restore` did, or with `dryRun` would do: per kind of
+ * record, how many come back, are set back and are removed (per layer for
+ * the layered kinds), and what could not come back, with why.
+ */
+export type DocumentRestoreSummary = {
+    name: boolean;
+    documentMetadata: boolean;
+    texts: RestoreCounts;
+    tokens: RestoreCounts & {
+        byLayer: Array<RestoreCounts & {
+            layerId: string;
+        }>;
+    };
+    spans: RestoreCounts & {
+        byLayer: Array<RestoreCounts & {
+            layerId: string;
+        }>;
+    };
+    relations: RestoreCounts & {
+        byLayer: Array<RestoreCounts & {
+            layerId: string;
+        }>;
+    };
+    vocabLinks: RestoreCounts;
+    skipped: Array<{
+        kind: string;
+        count: number;
+        reason: string;
+    }>;
+    /**
+     * When the name the
+     * document had then belongs to another document now: the name it keeps,
+     * and that other document's name.
+     */
+    nameKept?: {
+        name: string;
+        taken: string;
+    };
+    /**
+     * 0 when nothing changes.
+     */
+    total: number;
+};
+export type RestoreCounts = {
+    inserted: number;
+    updated: number;
+    deleted: number;
+};
+/**
+ * A logical-operation group: its label, who made it and when, and the kind
+ * and reference of the operation when it has them.
+ */
+export type OperationGroup = {
+    id: string;
+    message: string | null;
+    user: string;
+    createdAt: string;
+    kind?: string;
+    ref?: string;
+};
+/**
+ * A query's answer. For "ids" and "entities", one row of `results` per
+ * match, a cell per `columns` entry: an id, or the entity as its GET
+ * answers it. For "count", only the count. `truncated`: the rows or the
+ * count stopped at the server's cap.
+ */
+export type QueryResult = {
+    return: string;
+    count: number;
+    truncated: boolean;
+    columns?: string[];
+    results?: any[][];
+};