Skip to main content

Nvisy

The client class. All services are exposed as lazily-constructed properties.
The constructor takes a single NvisyOptions object.

NvisyOptions

apiToken and session are mutually exclusive in the type. DEFAULTS and VERSION are exported for reference.

Instance members

withApiToken returns a new instance and leaves the original untouched; all other configuration is preserved.

Services

Most methods take workspaceId as their first argument. Workspaces are the top-level tenancy boundary.

NvisyGuest

The pre-auth client, for the endpoints that work without a token: sign-in, the deployment’s auth capabilities, and health checks.
It takes NvisyGuestOptions — the same transport options as NvisyOptions minus the two authentication fields — and exposes three services:
loginAccount and signupAccount set HttpOnly session and CSRF cookies and return no body. Construct new Nvisy({ session: true }) afterwards to use the authenticated surface with that session.

Workspaces

A Workspace carries id, handle, displayName, memberRole, settings, createdBy, and timestamps. CreateWorkspace requires displayName; handle, description, and settings are optional.

Documents

uploadDocuments accepts a single Blob or an array, and sends them as multipart/form-data. downloadDocument returns the raw Response so you can stream the body.
object
ListWorkspaceDocuments filters by search (case-insensitive partial name), formats, modality, and hash — the last lets you check whether identical content already exists before uploading it. deleteDocuments is idempotent: it returns deleted for the ids that were removed and skipped for ids that were unknown, already deleted, in another workspace, or held by an in-progress detection.

Pipelines

CreateWorkspacePipeline requires displayName; definition, description, retention, and status are optional. A PipelineStatus is draft, enabled, or disabled.

Policies

CreateWorkspacePolicy is a tagged union on source: seed from a built-in template, or supply an inline definition. displayName and description override the body’s own values. WorkspacePoliciesQuery filters by kind.

Detections

A detection is one analysis pass of a document. It produces findings for review; applying them is a separate, repeatable step that creates a redaction.
createDetection starts analysis over a single document:
string
required
The document to analyze.
DocumentContext
Per-document languages, jurisdictions, and document labels. Overrides the pipeline’s defaultScope when present.
createAdhocDetection names policies directly instead of going through a pipeline; it requires documentId and a non-empty policyIds array, and also accepts scope and retentionOverride.

Detection status

A WorkspaceDetection carries id, inputDocumentId, inputDocumentName, pipelineId (absent for an ad-hoc detection), status, triggerType, triggeredBy, metadata, startedAt, completedAt, and error (present only when status is failed).
Redaction does not change a detection’s status. Each createRedaction call produces a new WorkspaceRedactionResult, whose outputDocumentId points at the redacted document.

Streaming status

streamEvents parses the server-sent event stream into typed DetectionStatusEvent values ({ detectionId, status }). It yields the current status immediately, then each transition, and ends once the detection settles. Break out of the loop to close the stream early.
events returns the raw Response if you would rather handle the text/event-stream body yourself.

Audit and intermediates

getAnalysis returns the Audit — report, context, codec, usage, and an optional recognition. downloadAudit returns it as a file: csv by default (a zip of entities.csv, provenance.csv, and reviews.csv), or json with { format: "json" }. getIntermediates returns an ArtifactSet of modality-tagged parts — an image’s OCR layout, an audio clip’s transcript, or tokenized text. A detection whose analysis ran no enricher has none and responds 404.

Redactions

Returns the redaction’s review audit — what was redacted and why — independent of the detection it came from.

Reviews

A review is a human review thread opened on a document, with assignees, comments, and a lifecycle.
A WorkspaceReview carries id, documentId, displayName, author, assignees, reviewStatus, and timestamps. reviewStatus is needs_review, in_review, or resolved. CreateWorkspaceReview takes displayName; CreateWorkspaceComment takes body. WorkspaceReviewsQuery filters by documentId, author, assignee, and reviewStatus. assignReviewer, linkDetection, and linkRedaction are idempotent. getTimeline interleaves comments with lifecycle events; getEvents returns the lifecycle events alone.

Providers

Inference providers configured per workspace.
CreateWorkspaceProvider requires displayName and a config (ProviderConfig), and accepts isActive. verifyProvider returns { reachable, error? }.

Connections

startFileServiceOAuth returns an authorizeUrl to send the user to; on consent the callback completes the connection. importFiles takes the files the user chose in the provider’s picker and exportFiles writes redacted outputs back — both return a WorkspaceConnectionSync. getPickerToken mints a short-lived provider access token for a browser file picker.

Syncs

startSync runs an object-store connection’s configured direction.

Webhooks

CreateWorkspaceWebhook requires displayName, description, url, and events, and accepts headers and status.
createWebhook returns WorkspaceWebhookCreated, whose secret is the signing secret — returned exactly once. Store it immediately.

Verifying deliveries

The @nvisy/sdk/webhooks entry point verifies an incoming delivery and parses it into a typed event, using Web Crypto so it runs in Node, browsers, edge runtimes, and workers.
For runtimes without a Fetch Request, constructEvent takes the raw body and headers directly; WEBHOOK_HEADERS names the four headers a delivery carries (X-Webhook-Signature, X-Webhook-Timestamp, X-Webhook-Event, X-Webhook-Request-Id). Verification failures throw WebhookSignatureError.
Pass the raw request body, not a re-serialized one — re-encoding JSON changes the bytes the signature was computed over.

Members and Invites

A member’s memberRole is owner, admin, editor, or reviewer. UpdateWorkspaceMember takes role; CreateWorkspaceInvite requires inviteeEmail, invitedRole, and expiresIn.

Account

An Account carries id, username, emailAddress, displayName, avatarUrl, isActivated, isSuspended, and timestamps. listIdentities reports the account’s sign-in methods — its password and any linked OIDC providers. linkIdentity and reauth return the provider authorize URL to redirect the user to.
Removing a password or unlinking a provider is refused when it is the account’s only remaining sign-in method. linkIdentity requires a step-up reauthProof obtained from reauth.

Authentication

Post-login operations live on client.auth; sign-in itself is on NvisyGuest.
mintDesktopToken mints a long-lived native-app token from an active browser session. It takes { redirectUri } and returns { apiToken, redirectUri }.

API Tokens

CreateAccountApiToken requires displayName and expiresIn, one of never, in7Days, in30Days, in90Days, or in1Year.
createApiToken returns AccountApiTokenWithJwt, whose token is the JWT — returned exactly once. Store it immediately; it cannot be retrieved later.

Capabilities

What this deployment supports. Replaces the former catalog endpoints.
listLabels returns the built-in taxonomy as a LabelCatalog — a map of label id to its definition. listRecognizers returns the engine’s registered recognizers grouped into ner and llm. listConnectors returns { fileServices, objectStores, inference } — an OAuth file-service provider is offered only when its app is configured. getAuthCapabilities is also available pre-auth on NvisyGuest.

Analytics and Activities

WorkspaceAnalytics aggregates storage, detections, and usage.
WorkspaceActivityFilterQuery filters by actor and type.

Notifications

streamEvents yields the current unread count immediately, then each change.

Status

Health carries status, a checks array of per-dependency health, and a timestamp. checkLiveness probes no dependencies and has no body, so it returns the raw Response; a non-2xx status throws.

Date Windows

Methods taking a DateWindow accept an inclusive from/to day range as YYYY-MM-DD strings. Both are optional: to defaults to today (UTC), and from defaults to a fixed window back from to.

Pagination

List methods are cursor-paginated and accept CursorPagination: Every page has items, an optional nextCursor, and an optional total.

Errors

NvisyError is the base class, thrown for SDK-level problems such as an invalid API token. NvisyApiError extends it for API responses: Helpers: isClientError() (4xx), isServerError() (5xx), isRetryable() (5xx, 408, or 429), and toJSON().
isRetryable() reports that the error is of a transient kind, not that the operation is safe to repeat. Retry automatically only for reads.