documents-client

Zero-dependency REST client for the documents API (compatible with @documents/adapter-express).

Installation

npm install documents-client

Configuration

import { DocumentsClient } from 'documents-client';

const client = new DocumentsClient({
  baseUrl: 'https://api.example.com',
  rootPath: '/documents', // default
  getAuthToken: async () => localStorage.getItem('token'),
  timeout: 30000, // default
  headers: { 'X-Custom': 'value' },
});

| Option | Description | | -------------- | --------------------------------------------------------- | | baseUrl | API base URL (required) | | rootPath | Document API prefix (default /documents) | | getAuthToken | Async callback returning Bearer token (required for auth) | | timeout | Request timeout in ms (default 30000) | | headers | Extra headers for all requests |

API Reference

Health

const health = await client.health();
// { status: string, details?: Record<string, unknown> }

List Folder

const result = await client.listFolder('/finance/2024/', {
  recursive: true,
  page: 1,
  size: 50,
  query: 'budget',
  includeContent: false,
  metadata: { semanticType: 'document', tags: ['urgent', '-draft'] }, // - prefix = exclude
});
// PaginatedResult<DocumentDraft | DocumentVersion>

Read Document

const doc = await client.readDocument('/finance/2024/budget', {
  branch: 'main',
  version: 'abc123', // or branch for draft
  accept: 'application/vnd.metadata-and-content+json',
});
// DocumentDraft | DocumentVersion

Version History

const history = await client.readVersionHistory('/finance/2024/budget', 'main');
// DocumentVersion[]

List Branches

const branches = await client.listBranches('/finance/2024/budget');
// BranchSummary[]

Put Document

const draft = await client.writeDocument(
  '/finance/2024/new-doc',
  { content: { blocks: [] }, metadata: { mimeType: 'application/json' } },
  {
    branch: 'main',
    ifMatch: 'previous-hash',
    accept: 'application/vnd.metadata-and-content+json',
  }
);
// DocumentDraft | void

Delete Document / Branch

await client.deleteDocument('/finance/2024/old-doc'); // Delete document and all branches
await client.deleteBranch('/finance/2024/old-doc', 'feature-x'); // Delete branch only

Document Actions

// Commit draft to version
const version = await client.commit('/doc', {
  branch: 'main',
  commitMessage: 'Initial',
});

// Stash branch
const { stashedBranch, draft } = await client.stash('/doc', 'main');

// Revert to head
const draft = await client.revert('/doc', 'main');

// Create branch from branch or version (options.branch = source branch, options.version = source version)
const draft = await client.branch('/doc', 'feature', { branch: 'main' });
const draft2 = await client.branch('/doc', 'snapshot', {
  version: 'abc123',
});

// Generate from template (options match other methods)
await client.generateFromTemplate(
  '/templates/tenant',
  { tenantId: 't1', userId: 'u1' },
  { branch: 'main' }
);

Content Negotiation

• Accept (read): application/vnd.metadata-and-content+json (default), application/vnd.metadata-only+json
• Content-Type (put): application/vnd.metadata-and-content+json, application/vnd.metadata-only+json, text/markdown
• Version history: Accept: application/vnd.document-versions+json
• Branches: Accept: application/vnd.document-branches+json

Error Handling

import {
  DocumentsClientError,
  PreconditionFailedError,
  PreconditionRequiredError,
  AuthenticationRequiredError,
} from 'documents-client';

try {
  await client.writeDocument('/doc', body, { ifMatch: oldHash });
} catch (err) {
  if (err instanceof PreconditionFailedError) {
    // 412 - optimistic lock conflict
  }
  if (err instanceof PreconditionRequiredError) {
    // 428 - If-Match required
  }
  if (err instanceof DocumentsClientError) {
    console.log(err.status, err.code, err.isNotFound);
  }
}

Example

import { DocumentsClient } from 'documents-client';

const client = new DocumentsClient({
  baseUrl: 'https://api.example.com',
  getAuthToken: () => sessionStorage.getItem('token'),
});

// List root folder
const { items } = await client.listFolder('/');

// Read a document
const doc = await client.readDocument('/projects/readme');
console.log(doc.metadata, doc.content);

// Update and commit
await client.writeDocument(
  '/projects/readme',
  {
    content: doc.content,
    metadata: doc.metadata,
  },
  { ifMatch: doc.hash }
);
await client.commit('/projects/readme', { commitMessage: 'Updated' });

TypeScript

All types are exported from the main package:

import type {
  DocumentDraft,
  DocumentVersion,
  DocumentMetadata,
  PaginatedResult,
  BranchSummary,
} from 'documents-client';

Or import only types:

import type { DocumentDraft } from 'documents-client/types';