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

package/src/apiServer.d.ts

@@ -0,0 +1,455 @@
+/**
+ * @typedef {import("./types.js").TextEditOp} TextEditOp
+ * @typedef {import("./types.js").TextGap} TextGap
+ * @typedef {import("./types.js").MetadataOp} MetadataOp
+ * @typedef {import("./types.js").LayerConstraint} LayerConstraint
+ * @typedef {import("./types.js").ConstraintWriteOptions} ConstraintWriteOptions
+ * @typedef {import("./types.js").ConstraintViolation} ConstraintViolation
+ * @typedef {import("./types.js").Requester} Requester
+ * @typedef {import("./types.js").BatchRef} BatchRef
+ * @typedef {import("./types.js").ServiceParam} ServiceParam
+ * @typedef {import("./types.js").ServiceInfo} ServiceInfo
+ * @typedef {import("./types.js").DiscoveredService} DiscoveredService
+ * @typedef {import("./types.js").ResponseHelper} ResponseHelper
+ * @typedef {import("./types.js").ServiceRegistration} ServiceRegistration
+ * @typedef {import("./types.js").ServiceStatusEvent} ServiceStatusEvent
+ * @typedef {import("./types.js").OperationGroupsBundle} OperationGroupsBundle
+ * @typedef {import("./types.js").PlaidClientOptions} PlaidClientOptions
+ * @typedef {import("./types.js").OperationKind} OperationKind
+ * @typedef {import("./types.js").KeySeed} KeySeed
+ * @typedef {import("./types.js").PlaidBatch} PlaidBatch
+ * @typedef {import("./types.js").AuditPageOptions} AuditPageOptions
+ * @typedef {import("./types.js").VocabItemRestoreSummary} VocabItemRestoreSummary
+ * @typedef {import("./types.js").UserDataEntry} UserDataEntry
+ * @typedef {import("./types.js").AdminUserDataEntry} AdminUserDataEntry
+ * @typedef {import("./types.js").ActivityTallyRow} ActivityTallyRow
+ * @typedef {import("./types.js").ConstraintRepair} ConstraintRepair
+ * @typedef {import("./types.js").ValueSetRule} ValueSetRule
+ * @typedef {import("./types.js").RefusedValues} RefusedValues
+ * @typedef {import("./types.js").CommentableType} CommentableType
+ * @typedef {import("./types.js").Comment} Comment
+ * @typedef {import("./types.js").Guideline} Guideline
+ * @typedef {import("./types.js").ClientEventType} ClientEventType
+ * @typedef {import("./types.js").ClientEvent} ClientEvent
+ * @typedef {import("./types.js").Invite} Invite
+ * @typedef {import("./types.js").ServerLimits} ServerLimits
+ * @typedef {import("./types.js").ServerHealth} ServerHealth
+ * @typedef {import("./types.js").RateLimitBucket} RateLimitBucket
+ * @typedef {import("./types.js").RateLimitSnapshot} RateLimitSnapshot
+ * @typedef {import("./types.js").BackupStatus} BackupStatus
+ * @typedef {import("./types.js").ServerReport} ServerReport
+ * @typedef {import("./types.js").LiveLog} LiveLog
+ * @typedef {import("./types.js").SSEConnection} SSEConnection
+ * @typedef {import("./types.js").SSEStats} SSEStats
+ * @typedef {import("./types.js").AtomicValue} AtomicValue
+ * @typedef {import("./types.js").Created} Created
+ * @typedef {import("./types.js").Project} Project
+ * @typedef {import("./types.js").ProjectTextLayer} ProjectTextLayer
+ * @typedef {import("./types.js").ProjectTokenLayer} ProjectTokenLayer
+ * @typedef {import("./types.js").ProjectSpanLayer} ProjectSpanLayer
+ * @typedef {import("./types.js").ProjectRelationLayer} ProjectRelationLayer
+ * @typedef {import("./types.js").ProjectVocab} ProjectVocab
+ * @typedef {import("./types.js").PlaidDocument} PlaidDocument
+ * @typedef {import("./types.js").DocumentTextLayer} DocumentTextLayer
+ * @typedef {import("./types.js").DocumentTokenLayer} DocumentTokenLayer
+ * @typedef {import("./types.js").DocumentSpanLayer} DocumentSpanLayer
+ * @typedef {import("./types.js").PlaidText} PlaidText
+ * @typedef {import("./types.js").TextReshape} TextReshape
+ * @typedef {import("./types.js").Token} Token
+ * @typedef {import("./types.js").Span} Span
+ * @typedef {import("./types.js").Relation} Relation
+ * @typedef {import("./types.js").VocabItem} VocabItem
+ * @typedef {import("./types.js").VocabLink} VocabLink
+ * @typedef {import("./types.js").VocabLayer} VocabLayer
+ * @typedef {import("./types.js").TextLayer} TextLayer
+ * @typedef {import("./types.js").TokenLayer} TokenLayer
+ * @typedef {import("./types.js").SpanLayer} SpanLayer
+ * @typedef {import("./types.js").RelationLayer} RelationLayer
+ * @typedef {import("./types.js").MetadataRecords} MetadataRecords
+ * @typedef {import("./types.js").LayerRecords} LayerRecords
+ * @typedef {import("./types.js").User} User
+ * @typedef {import("./types.js").ProjectListEntry} ProjectListEntry
+ * @typedef {import("./types.js").DocumentListEntry} DocumentListEntry
+ * @typedef {import("./types.js").ApiToken} ApiToken
+ * @typedef {import("./types.js").AuditUser} AuditUser
+ * @typedef {import("./types.js").AuditTarget} AuditTarget
+ * @typedef {import("./types.js").AuditOp} AuditOp
+ * @typedef {import("./types.js").AuditEntry} AuditEntry
+ * @typedef {import("./types.js").LockGrant} LockGrant
+ * @typedef {import("./types.js").DocumentRestoreSummary} DocumentRestoreSummary
+ * @typedef {import("./types.js").RestoreCounts} RestoreCounts
+ * @typedef {import("./types.js").OperationGroup} OperationGroup
+ * @typedef {import("./types.js").QueryResult} QueryResult
+ */
+/**
+ * @template [T=any]
+ * @typedef {import("./types.js").Page<T>} Page
+ */
+/** @param {import("./client.js").PlaidClient} client */
+export function serverApi(client: import("./client.js").PlaidClient): {
+    /**
+     * This server's version and the limits it enforces, e.g.
+     * `{ limits: { mediaFileBytes, jsonBodyBytes, batchOperations, … } }`.
+     * Sizes are in bytes. Unauthenticated.
+     * @returns {Promise<{limits: ServerLimits}>}
+     */
+    info: () => Promise<{
+        limits: ServerLimits;
+    }>;
+    /**
+     * Read `GET /info` again and resolve to it. Until it answers, a reader
+     * waits for it. The facts known before are kept when the server does
+     * not answer, and the error is thrown.
+     * @returns {Promise<{limits: ServerLimits}>}
+     */
+    refresh: () => Promise<{
+        limits: ServerLimits;
+    }>;
+    /**
+     * Just the limits, which is what a caller almost always wants.
+     * @returns {Promise<ServerLimits>}
+     */
+    limits: () => Promise<ServerLimits>;
+    /**
+     * Liveness, version and database size. Unauthenticated, and served
+     * outside the REST router at /health, so it answers even while the API
+     * is refusing requests. Never cached — the point is that it is current.
+     * @returns {Promise<ServerHealth>}
+     */
+    health: () => Promise<ServerHealth>;
+};
+/** @param {import("./client.js").PlaidClient} client */
+export function adminApi(client: import("./client.js").PlaidClient): {
+    /**
+     * Everything about the server in one read: version and JVM uptime,
+     * database size and per-table row counts, media directory usage, backup
+     * configuration and the backups on disk, and the settings an operator
+     * gets asked to confirm. Carries no secrets. Runs a count per table and
+     * walks the media directory, so open it, do not poll it. Admin only.
+     * @returns {Promise<ServerReport>}
+     */
+    server: () => Promise<ServerReport>;
+    /**
+     * Take a database backup right now, outside the nightly schedule.
+     * Resolves to the backup block with `ok` reporting whether the snapshot
+     * succeeded. Uses VACUUM INTO, which only reads, so it is safe while
+     * people are working. Admin only.
+     *
+     * The server answers once the backup is written, which takes minutes on
+     * a large database, so this waits up to `BACKUP_TIMEOUT_MS` (30 minutes)
+     * rather than the client's usual timeout. A proxy in front of the server
+     * may still give up first (a 504): the backup goes on, and its file
+     * shows in `server().backup.backups` once it is written.
+     * @returns {Promise<BackupStatus>}
+     *
+     * outOfBand, as every admin action on the server itself is: none of them
+     * writes project data (see the note at the top of http.js).
+     */
+    backup: () => Promise<BackupStatus>;
+    /**
+     * Documents currently held by an editing lock, with who holds each and
+     * when it expires on its own. Admin only.
+     * @returns {Promise<{entries: Array<{documentId: string, userId: string, expiresAt: number}>}>}
+     */
+    locks: () => Promise<{
+        entries: Array<{
+            documentId: string;
+            userId: string;
+            expiresAt: number;
+        }>;
+    }>;
+    /**
+     * Drop the lock on a document whoever holds it. Idempotent. For a client
+     * that went away without releasing one. Admin only.
+     * @param {string} documentId - The document ID
+     * @returns {Promise<{result: string}>}
+     */
+    releaseLock: (documentId: string) => Promise<{
+        result: string;
+    }>;
+    /**
+     * Live login and invite rate-limit buckets: the address, the account
+     * where there is one, failures inside the window, the limit, and whether
+     * it is currently blocking. Admin only.
+     * @returns {Promise<RateLimitSnapshot>}
+     */
+    rateLimits: () => Promise<RateLimitSnapshot>;
+    /**
+     * Forget recorded rate-limit failures. With `ip`, clears that address,
+     * narrowed to one account with `userId`. With neither, clears every
+     * bucket. Only ever unblocks. Admin only.
+     * @param {object} [opts]
+     * @param {string} [opts.ip] - Clear only this address
+     * @param {string} [opts.userId] - Narrow to one account on that address
+     * @returns {Promise<{result: string}>}
+     */
+    clearRateLimits: ({ ip, userId }?: {
+        ip?: string;
+        userId?: string;
+    }) => Promise<{
+        result: string;
+    }>;
+    /**
+     * What the server has logged, structured and filtered, from an in-memory
+     * buffer kept whether or not a log file is configured. `requests` is one
+     * entry per HTTP request (method, path, status, duration, and who made
+     * it), `events` is everything else, with a stack trace where there was
+     * one. They are buffered separately so a burst of requests cannot evict
+     * an error. Both come newest first, `matched` counts what passed the
+     * filters, and request `stats` describe the filtered set. Covers Plaid's
+     * own log stream since the last restart: for library messages and older
+     * history, see `logFile`. Admin only.
+     * @param {object} [opts]
+     * @param {number} [opts.limit] - Max entries per kind (default 200, max 2000)
+     * @param {string} [opts.q] - Substring of any field, case-insensitive
+     * @param {string} [opts.level] - Minimum level for events, e.g. "warn"
+     * @param {string} [opts.status] - "2xx".."5xx", an exact code, or "failures"
+     * @param {string} [opts.user] - Only requests made by this account
+     * @param {string} [opts.method] - Only requests with this HTTP method
+     * @returns {Promise<LiveLog>}
+     */
+    logs: ({ limit, q, level, status, user, method }?: {
+        limit?: number;
+        q?: string;
+        level?: string;
+        status?: string;
+        user?: string;
+        method?: string;
+    }) => Promise<LiveLog>;
+    /**
+     * The tail of the configured log file, as text lines. The only place
+     * third-party library messages and anything from before the last restart
+     * can be read. Resolves with an `error` string instead of lines when no
+     * log file is configured or it does not exist yet. Admin only.
+     * @param {object} [opts]
+     * @param {number} [opts.lines] - How many lines (default 200, max 2000)
+     * @returns {Promise<{file: (string|null), lines: string[], error?: string}>}
+     */
+    logFile: ({ lines }?: {
+        lines?: number;
+    }) => Promise<{
+        file: (string | null);
+        lines: string[];
+        error?: string;
+    }>;
+    /**
+     * Private user-data entries across every account, each carrying its
+     * `userId`. `/users/:userId/data` has always been owner-or-admin; this
+     * is the same reach across accounts at once. Transparently follows
+     * pagination cursors and returns the full flat array. Admin only.
+     *
+     * Narrow with `prefix` (the literal head of a key) and/or `pattern`, a
+     * GLOB over the whole key (`*` any run, `?` one character) — the way to
+     * ask for a key convention identified by a segment in the middle, e.g.
+     * `igt:assistant:*:meta:*`. Values come only with `includeValues`, and
+     * are recased like any other body (see `userData.put`).
+     * @param {object} [opts]
+     * @param {string} [opts.prefix] - Only keys starting with this
+     * @param {string} [opts.pattern] - Only keys matching this GLOB
+     * @param {boolean} [opts.includeValues] - Also return each entry's value
+     * @returns {Promise<AdminUserDataEntry[]>}
+     */
+    userData: ({ prefix, pattern, includeValues }?: {
+        prefix?: string;
+        pattern?: string;
+        includeValues?: boolean;
+    }) => Promise<AdminUserDataEntry[]>;
+    /**
+     * One page of private user-data entries across accounts, ordered by
+     * (user, key). Admin only.
+     * @param {object} [opts]
+     * @param {string} [opts.prefix] - Only keys starting with this
+     * @param {string} [opts.pattern] - Only keys matching this GLOB
+     * @param {boolean} [opts.includeValues] - Also return each entry's value
+     * @param {number} [opts.limit] - Page size (1..1000; server default 100)
+     * @param {string} [opts.cursor] - Opaque cursor from a previous page
+     * @returns {Promise<Page<AdminUserDataEntry>>}
+     */
+    userDataPage: ({ prefix, pattern, includeValues, limit, cursor }?: {
+        prefix?: string;
+        pattern?: string;
+        includeValues?: boolean;
+        limit?: number;
+        cursor?: string;
+    }) => Promise<Page<AdminUserDataEntry>>;
+};
+/** @param {import("./client.js").PlaidClient} client */
+export function auditApi(client: import("./client.js").PlaidClient): {
+    /**
+     * The audit log across every project, oldest first. Same fold, window
+     * and op-type filter as the per-project read, with the entity scope
+     * dropped. Admin only. Transparently follows pagination cursors and
+     * returns the full flat array.
+     * @param {object} [opts]
+     * @param {string} [opts.startTime] - Only operations at or after this instant
+     * @param {string} [opts.endTime] - Only operations at or before this instant
+     * @param {string[]|string} [opts.opTypes] - Only these op types (e.g.
+     *   `['span-layer/create']`). An entry appears when one of its operations
+     *   matches, carrying only the ones that did.
+     * @param {string[]|string} [opts.kinds] - Only the entries of operations
+     *   of these kinds (e.g. `['review']`), each whole
+     * @returns {Promise<AuditEntry[]>}
+     */
+    list: ({ startTime, endTime, opTypes, kinds }?: {
+        startTime?: string;
+        endTime?: string;
+        opTypes?: string[] | string;
+        kinds?: string[] | string;
+    }) => Promise<AuditEntry[]>;
+    /**
+     * Fetch a single page of the instance-wide audit log. Admin only.
+     * @param {object} [opts]
+     * @param {string} [opts.startTime] - Only entries at or after this instant
+     * @param {string} [opts.endTime] - Only entries at or before this instant
+     * @param {string[]|string} [opts.opTypes] - Only these op types
+     * @param {OperationKind[]|string} [opts.kinds] - Only the entries of operations of these kinds, each whole
+     * @param {"asc"|"desc"} [opts.order] - "desc" pages newest-first, which
+     *   is what a feed wants. A cursor belongs to the direction that made it.
+     * @param {number} [opts.limit] - Page size (1..1000; server default 100)
+     * @param {string} [opts.cursor] - Opaque cursor from a previous page
+     * @param {number} [opts.opsLimit] - Keep only each entry's oldest N
+     *   operations in `ops` (1..1000). `opCount` on every entry says how
+     *   many it has
+     * @param {string} [opts.entryId] - Read only this entry, not a page
+     * @returns {Promise<Page<AuditEntry>>}
+     */
+    listPage: ({ startTime, endTime, opTypes, kinds, order, limit, cursor, opsLimit, entryId }?: {
+        startTime?: string;
+        endTime?: string;
+        opTypes?: string[] | string;
+        kinds?: OperationKind[] | string;
+        order?: "asc" | "desc";
+        limit?: number;
+        cursor?: string;
+        opsLimit?: number;
+        entryId?: string;
+    }) => Promise<Page<AuditEntry>>;
+    /**
+     * Async-iterate the instance-wide audit log page by page. Admin only.
+     * @param {object} [opts]
+     * @param {string} [opts.startTime] - Only entries at or after this instant
+     * @param {string} [opts.endTime] - Only entries at or before this instant
+     * @param {string[]|string} [opts.opTypes] - Only these op types
+     * @param {OperationKind[]|string} [opts.kinds] - Only the entries of operations of these kinds, each whole
+     * @param {number} [opts.pageSize] - Per-request page size
+     * @returns {AsyncGenerator<AuditEntry[]>}
+     */
+    iterPages: ({ startTime, endTime, opTypes, kinds, pageSize }?: {
+        startTime?: string;
+        endTime?: string;
+        opTypes?: string[] | string;
+        kinds?: OperationKind[] | string;
+        pageSize?: number;
+    }) => AsyncGenerator<AuditEntry[]>;
+    /**
+     * Per-user activity counts. `changes` is the number of logical actions,
+     * folded the way the audit feed folds them, so one "Confirm word
+     * analysis" counts once however many rows it wrote; `operations` is the
+     * unfolded row count. Only users who did something appear — subtract
+     * from the roster you already hold to find the ones who did not.
+     *
+     * With `projectId`, scoped to that project and open to its maintainers.
+     * Without one, instance-wide and admin only.
+     * @param {object} [opts]
+     * @param {string} [opts.projectId] - Scope to one project
+     * @param {string} [opts.startTime] - Only count at or after this instant
+     * @param {string} [opts.endTime] - Only count at or before this instant
+     * @param {boolean} [opts.daily] - Also return `byDay`, a list of
+     *   `{date, changes}` per user, oldest first, at the cost of a second
+     *   grouped scan
+     * @returns {Promise<ActivityTallyRow[]>}
+     */
+    tally: ({ projectId, startTime, endTime, daily }?: {
+        projectId?: string;
+        startTime?: string;
+        endTime?: string;
+        daily?: boolean;
+    }) => Promise<ActivityTallyRow[]>;
+};
+/**
+ * How long `admin.backup()` waits for the server to finish writing a backup:
+ * minutes on a large database, past the usual per-request timeout.
+ */
+export const BACKUP_TIMEOUT_MS: number;
+export type TextEditOp = import("./types.js").TextEditOp;
+export type TextGap = import("./types.js").TextGap;
+export type MetadataOp = import("./types.js").MetadataOp;
+export type LayerConstraint = import("./types.js").LayerConstraint;
+export type ConstraintWriteOptions = import("./types.js").ConstraintWriteOptions;
+export type ConstraintViolation = import("./types.js").ConstraintViolation;
+export type Requester = import("./types.js").Requester;
+export type BatchRef = import("./types.js").BatchRef;
+export type ServiceParam = import("./types.js").ServiceParam;
+export type ServiceInfo = import("./types.js").ServiceInfo;
+export type DiscoveredService = import("./types.js").DiscoveredService;
+export type ResponseHelper = import("./types.js").ResponseHelper;
+export type ServiceRegistration = import("./types.js").ServiceRegistration;
+export type ServiceStatusEvent = import("./types.js").ServiceStatusEvent;
+export type OperationGroupsBundle = import("./types.js").OperationGroupsBundle;
+export type PlaidClientOptions = import("./types.js").PlaidClientOptions;
+export type OperationKind = import("./types.js").OperationKind;
+export type KeySeed = import("./types.js").KeySeed;
+export type PlaidBatch = import("./types.js").PlaidBatch;
+export type AuditPageOptions = import("./types.js").AuditPageOptions;
+export type VocabItemRestoreSummary = import("./types.js").VocabItemRestoreSummary;
+export type UserDataEntry = import("./types.js").UserDataEntry;
+export type AdminUserDataEntry = import("./types.js").AdminUserDataEntry;
+export type ActivityTallyRow = import("./types.js").ActivityTallyRow;
+export type ConstraintRepair = import("./types.js").ConstraintRepair;
+export type ValueSetRule = import("./types.js").ValueSetRule;
+export type RefusedValues = import("./types.js").RefusedValues;
+export type CommentableType = import("./types.js").CommentableType;
+export type Comment = import("./types.js").Comment;
+export type Guideline = import("./types.js").Guideline;
+export type ClientEventType = import("./types.js").ClientEventType;
+export type ClientEvent = import("./types.js").ClientEvent;
+export type Invite = import("./types.js").Invite;
+export type ServerLimits = import("./types.js").ServerLimits;
+export type ServerHealth = import("./types.js").ServerHealth;
+export type RateLimitBucket = import("./types.js").RateLimitBucket;
+export type RateLimitSnapshot = import("./types.js").RateLimitSnapshot;
+export type BackupStatus = import("./types.js").BackupStatus;
+export type ServerReport = import("./types.js").ServerReport;
+export type LiveLog = import("./types.js").LiveLog;
+export type SSEConnection = import("./types.js").SSEConnection;
+export type SSEStats = import("./types.js").SSEStats;
+export type AtomicValue = import("./types.js").AtomicValue;
+export type Created = import("./types.js").Created;
+export type Project = import("./types.js").Project;
+export type ProjectTextLayer = import("./types.js").ProjectTextLayer;
+export type ProjectTokenLayer = import("./types.js").ProjectTokenLayer;
+export type ProjectSpanLayer = import("./types.js").ProjectSpanLayer;
+export type ProjectRelationLayer = import("./types.js").ProjectRelationLayer;
+export type ProjectVocab = import("./types.js").ProjectVocab;
+export type PlaidDocument = import("./types.js").PlaidDocument;
+export type DocumentTextLayer = import("./types.js").DocumentTextLayer;
+export type DocumentTokenLayer = import("./types.js").DocumentTokenLayer;
+export type DocumentSpanLayer = import("./types.js").DocumentSpanLayer;
+export type PlaidText = import("./types.js").PlaidText;
+export type TextReshape = import("./types.js").TextReshape;
+export type Token = import("./types.js").Token;
+export type Span = import("./types.js").Span;
+export type Relation = import("./types.js").Relation;
+export type VocabItem = import("./types.js").VocabItem;
+export type VocabLink = import("./types.js").VocabLink;
+export type VocabLayer = import("./types.js").VocabLayer;
+export type TextLayer = import("./types.js").TextLayer;
+export type TokenLayer = import("./types.js").TokenLayer;
+export type SpanLayer = import("./types.js").SpanLayer;
+export type RelationLayer = import("./types.js").RelationLayer;
+export type MetadataRecords = import("./types.js").MetadataRecords;
+export type LayerRecords = import("./types.js").LayerRecords;
+export type User = import("./types.js").User;
+export type ProjectListEntry = import("./types.js").ProjectListEntry;
+export type DocumentListEntry = import("./types.js").DocumentListEntry;
+export type ApiToken = import("./types.js").ApiToken;
+export type AuditUser = import("./types.js").AuditUser;
+export type AuditTarget = import("./types.js").AuditTarget;
+export type AuditOp = import("./types.js").AuditOp;
+export type AuditEntry = import("./types.js").AuditEntry;
+export type LockGrant = import("./types.js").LockGrant;
+export type DocumentRestoreSummary = import("./types.js").DocumentRestoreSummary;
+export type RestoreCounts = import("./types.js").RestoreCounts;
+export type OperationGroup = import("./types.js").OperationGroup;
+export type QueryResult = import("./types.js").QueryResult;
+export type Page<T = any> = import("./types.js").Page<T>;