equalweb-sdk 1.0.2 → 1.1.0

package/README.md

@@ -124,8 +124,20 @@ await client.audit.audit(["doc1", "doc2"]);
 // Quick check (no remediation)
 await client.audit.check(["doc1", "doc2"]);
 
-// Custom audit type
-await client.audit.process(["doc1", "doc2"], "audit");
+// Quick check, then delete the stored file (report and score are kept)
+await client.audit.check(["doc1"], { deleteFileAfterCheck: true });
+
+// Full audit with advanced options
+await client.audit.audit(["doc1", "doc2"], {
+  addSignature: true,
+  fixContrast: true,
+  autoRemove: 30,
+});
+
+// Custom audit type with options
+await client.audit.process(["doc1"], "ocr", {
+  deleteAfterAudit: true,
+});
 ```
 
 ### Reports
@@ -166,6 +178,33 @@ const xlsx = await client.downloads.audited("reportID", "xlsx");
 const zip = await client.downloads.zipped(["id1", "id2", "id3"]);
 ```
 
+### Convert
+
+```typescript
+// Convert PDF to HTML
+await client.convert.html(["doc1", "doc2"]);
+
+// With options
+await client.convert.html(["doc1"], { autoConvert: true, auditHtml: true });
+
+// With site key
+await client.convert.html(["doc1"], {}, "my-site-key");
+```
+
+### Manual Remediation
+
+```typescript
+// Cancel manual remediation
+await client.manual.cancel(["doc1", "doc2"]);
+```
+
+### Settings
+
+```typescript
+// Update PDF settings for a site
+await client.settings.update("my-site-key", { autoConvert: true });
+```
+
 ## Error Handling
 
 ```typescript

package/dist/index.d.mts

@@ -4,7 +4,7 @@ interface EqualWebConfig {
     timeout?: number;
 }
 type DocumentStatus = "done" | "pending" | "processing" | string;
-type AuditType = "audit" | "check";
+type AuditType = "audit" | "tag" | "ocr" | "check" | "manual" | "sign";
 type ReportType = "audited" | "original" | "both";
 type DownloadFileType = "pdf" | "xlsx";
 interface BalanceResponse {
@@ -16,6 +16,14 @@ interface Document {
     group: number | null;
     archived: boolean;
     reportID: string;
+    /** Client-system id linked at upload time, null when not set */
+    externalID: string | null;
+    /** Accessibility score of the uploaded document, null until checked */
+    originalScore: number | null;
+    /** Accessibility score of the remediated document, null until audited */
+    auditedScore: number | null;
+    /** Client metadata attached at upload time, null when not set */
+    metadata: Record<string, unknown> | null;
     status: DocumentStatus;
 }
 interface GetDocumentsParams {
@@ -23,13 +31,43 @@ interface GetDocumentsParams {
     archived?: boolean;
     type?: string;
 }
+/** Opt-in pagination: passing page switches the response to an envelope */
+interface GetDocumentsPagedParams extends GetDocumentsParams {
+    page: number;
+    /** 1-200, defaults to 50 */
+    pageSize?: number;
+}
+interface PagedDocumentsResponse {
+    results: Document[];
+    total: number;
+    page: number;
+    pageSize: number;
+    totalPages: number;
+}
 interface DocumentStatusResponse {
     status: DocumentStatus;
+    id?: string;
+    externalID?: string | null;
+    originalScore?: number | null;
+    auditedScore?: number | null;
+    metadata?: Record<string, unknown> | null;
+}
+interface UploadOptions {
+    /**
+     * Your system's id for this document (1-100 chars: letters, digits,
+     * - _ . :). Afterwards every endpoint that takes a reportID also accepts
+     * this externalID. A taken externalID rejects the upload with 409.
+     */
+    externalID?: string;
+    /** Metadata to store on the document (JSON object, max 8KB) */
+    metadata?: Record<string, unknown>;
 }
 interface UploadResponse {
     id: string;
     createdAt: string;
     numberOfPages: number;
+    externalID?: string;
+    metadata?: Record<string, unknown>;
 }
 interface DeleteDocumentsParams {
     files: string[];
@@ -66,7 +104,19 @@ interface RenameGroupParams {
 interface RenameGroupResponse {
     results: "ok";
 }
-interface AuditDocumentsParams {
+interface AuditDocumentsOptions {
+    engine?: string;
+    addSignature?: boolean;
+    fixContrast?: boolean;
+    autoRemove?: number;
+    deleteAfterAudit?: boolean;
+    /**
+     * For `check` runs only: delete the stored file once the check finishes.
+     * The report and score are kept. Per-request only — there is no saved default.
+     */
+    deleteFileAfterCheck?: boolean;
+}
+interface AuditDocumentsParams extends AuditDocumentsOptions {
     files: string[];
     type?: AuditType;
 }
@@ -124,6 +174,26 @@ interface DownloadFileParams {
 interface DownloadZippedParams {
     files: string[];
 }
+interface ConvertHtmlParams {
+    files: string[];
+    autoConvert?: boolean;
+    auditHtml?: boolean;
+}
+interface ConvertHtmlResponse {
+    results: "ok";
+}
+interface CancelManualParams {
+    files: string[];
+}
+interface CancelManualResponse {
+    data: "ok";
+}
+interface PdfSettingsParams {
+    autoConvert: boolean;
+}
+interface PdfSettingsResponse {
+    results: "ok";
+}
 interface EqualWebErrorResponse {
     error?: string;
     message?: string;
@@ -180,13 +250,18 @@ declare class DocumentsApi {
     constructor(client: HttpClient);
     /**
      * Get all documents
-     * @param params - Optional filters for groupID, archived status, and document type
-     * @returns Array of documents
+     * @param params - Optional filters for groupID, archived status, and
+     * document type. Passing `page` (and optionally `pageSize`) opts in to
+     * pagination and switches the return value to a paged envelope; without it
+     * the full array is returned as before.
+     * @returns Array of documents, or a paged envelope when `page` is passed
      */
     getAll(params?: GetDocumentsParams): Promise<Document[]>;
+    getAll(params: GetDocumentsPagedParams): Promise<PagedDocumentsResponse>;
     /**
      * Get the status of a specific document
-     * @param reportID - The report ID of the document
+     * @param reportID - The report ID of the document, or the externalID your
+     * system linked at upload time
      * @returns The document status
      */
     getStatus(reportID: string): Promise<string>;
@@ -195,9 +270,12 @@ declare class DocumentsApi {
      * Supported formats: PDF, XLSX, DOCX, PPTX
      * @param file - The file to upload (File, Blob, ArrayBuffer, or Uint8Array)
      * @param filename - Optional filename (required if file is an ArrayBuffer or Uint8Array)
+     * @param options - Optional externalID (links the doc to your own system;
+     * rejected with 409 if already in use) and metadata (JSON object stored on
+     * the document, max 8KB)
      * @returns Upload response with document ID and metadata
      */
-    upload(file: File | Blob | ArrayBuffer | Uint8Array, filename?: string): Promise<UploadResponse>;
+    upload(file: File | Blob | ArrayBuffer | Uint8Array, filename?: string, options?: UploadOptions): Promise<UploadResponse>;
     /**
      * Delete multiple documents
      * @param files - Array of document IDs to delete
@@ -256,22 +334,26 @@ declare class AuditApi {
      * Start a full audit on documents
      * This performs accessibility remediation and generates detailed reports
      * @param files - Array of document IDs to audit
+     * @param options - Optional audit settings (engine, addSignature, fixContrast, autoRemove, deleteAfterAudit)
      * @returns Result of the operation (202 Accepted - processing is async)
      */
-    audit(files: string[]): Promise<AuditDocumentsResponse>;
+    audit(files: string[], options?: AuditDocumentsOptions): Promise<AuditDocumentsResponse>;
     /**
      * Perform a quick check on documents without full remediation
      * @param files - Array of document IDs to check
+     * @param options - Optional audit settings (engine, addSignature, fixContrast, autoRemove, deleteAfterAudit, deleteFileAfterCheck)
      * @returns Result of the operation (202 Accepted - processing is async)
      */
-    check(files: string[]): Promise<AuditDocumentsResponse>;
+    check(files: string[], options?: AuditDocumentsOptions): Promise<AuditDocumentsResponse>;
     /**
      * Start an audit with custom type
      * @param files - Array of document IDs to process
-     * @param type - Type of audit: "audit" for full audit, "check" for quick check
+     * @param type - Type of audit: "audit", "tag", "ocr", "check", "manual", or "sign"
+     * @param options - Optional audit settings (engine, addSignature, fixContrast, autoRemove, deleteAfterAudit)
      * @returns Result of the operation (202 Accepted - processing is async)
      */
-    process(files: string[], type: AuditType): Promise<AuditDocumentsResponse>;
+    process(files: string[], type: AuditType, options?: AuditDocumentsOptions): Promise<AuditDocumentsResponse>;
+    private validateOptions;
 }
 
 declare class ReportsApi {
@@ -343,6 +425,42 @@ declare class DownloadsApi {
     zipped(files: string[]): Promise<Blob>;
 }
 
+declare class ConvertApi {
+    private readonly client;
+    constructor(client: HttpClient);
+    /**
+     * Convert PDF documents to HTML
+     * @param files - Array of document IDs to convert
+     * @param options - Optional conversion settings
+     * @param sitekey - Optional site key for site-specific conversion
+     * @returns Result of the operation
+     */
+    html(files: string[], options?: Omit<ConvertHtmlParams, "files">, sitekey?: string): Promise<ConvertHtmlResponse>;
+}
+
+declare class ManualApi {
+    private readonly client;
+    constructor(client: HttpClient);
+    /**
+     * Cancel manual remediation for documents
+     * @param files - Array of document IDs to cancel manual remediation for
+     * @returns Result of the operation
+     */
+    cancel(files: string[]): Promise<CancelManualResponse>;
+}
+
+declare class SettingsApi {
+    private readonly client;
+    constructor(client: HttpClient);
+    /**
+     * Update PDF settings for a site
+     * @param siteKey - The site key to update settings for
+     * @param params - Settings to update
+     * @returns Result of the operation
+     */
+    update(siteKey: string, params: PdfSettingsParams): Promise<PdfSettingsResponse>;
+}
+
 declare class EqualWeb {
     private readonly client;
     readonly info: InfoApi;
@@ -351,6 +469,9 @@ declare class EqualWeb {
     readonly audit: AuditApi;
     readonly reports: ReportsApi;
     readonly downloads: DownloadsApi;
+    readonly convert: ConvertApi;
+    readonly manual: ManualApi;
+    readonly settings: SettingsApi;
     /**
      * Create a new EqualWeb API client
      * @param config - Configuration object with API key and optional settings
@@ -378,4 +499,4 @@ declare class EqualWeb {
     constructor(config: EqualWebConfig);
 }
 
-export { type ArchiveDocumentsParams, type ArchiveDocumentsResponse, AuditApi, type AuditDocumentsParams, type AuditDocumentsResponse, type AuditType, type AuditedReport, AuthenticationError, type BalanceResponse, type DeleteDocumentsParams, type DeleteDocumentsResponse, type DetailedReport, type Document, type DocumentGroup, type DocumentStatus, type DocumentStatusResponse, DocumentsApi, type DownloadFileParams, type DownloadFileType, type DownloadZippedParams, DownloadsApi, EqualWeb, type EqualWebConfig, EqualWebError, type EqualWebErrorResponse, type GetDocumentsParams, type GetReportParams, type GroupDocumentsParams, type GroupDocumentsResponse, GroupsApi, InfoApi, type OriginalReport, RateLimitError, type RenameGroupParams, type RenameGroupResponse, type ReportCustomData, type ReportResponse, type ReportRule, type ReportSummary, type ReportType, ReportsApi, type UploadResponse };
+export { type ArchiveDocumentsParams, type ArchiveDocumentsResponse, AuditApi, type AuditDocumentsOptions, type AuditDocumentsParams, type AuditDocumentsResponse, type AuditType, type AuditedReport, AuthenticationError, type BalanceResponse, type CancelManualParams, type CancelManualResponse, ConvertApi, type ConvertHtmlParams, type ConvertHtmlResponse, type DeleteDocumentsParams, type DeleteDocumentsResponse, type DetailedReport, type Document, type DocumentGroup, type DocumentStatus, type DocumentStatusResponse, DocumentsApi, type DownloadFileParams, type DownloadFileType, type DownloadZippedParams, DownloadsApi, EqualWeb, type EqualWebConfig, EqualWebError, type EqualWebErrorResponse, type GetDocumentsParams, type GetReportParams, type GroupDocumentsParams, type GroupDocumentsResponse, GroupsApi, InfoApi, ManualApi, type OriginalReport, type PdfSettingsParams, type PdfSettingsResponse, RateLimitError, type RenameGroupParams, type RenameGroupResponse, type ReportCustomData, type ReportResponse, type ReportRule, type ReportSummary, type ReportType, ReportsApi, SettingsApi, type UploadResponse };

package/dist/index.d.ts

@@ -4,7 +4,7 @@ interface EqualWebConfig {
     timeout?: number;
 }
 type DocumentStatus = "done" | "pending" | "processing" | string;
-type AuditType = "audit" | "check";
+type AuditType = "audit" | "tag" | "ocr" | "check" | "manual" | "sign";
 type ReportType = "audited" | "original" | "both";
 type DownloadFileType = "pdf" | "xlsx";
 interface BalanceResponse {
@@ -16,6 +16,14 @@ interface Document {
     group: number | null;
     archived: boolean;
     reportID: string;
+    /** Client-system id linked at upload time, null when not set */
+    externalID: string | null;
+    /** Accessibility score of the uploaded document, null until checked */
+    originalScore: number | null;
+    /** Accessibility score of the remediated document, null until audited */
+    auditedScore: number | null;
+    /** Client metadata attached at upload time, null when not set */
+    metadata: Record<string, unknown> | null;
     status: DocumentStatus;
 }
 interface GetDocumentsParams {
@@ -23,13 +31,43 @@ interface GetDocumentsParams {
     archived?: boolean;
     type?: string;
 }
+/** Opt-in pagination: passing page switches the response to an envelope */
+interface GetDocumentsPagedParams extends GetDocumentsParams {
+    page: number;
+    /** 1-200, defaults to 50 */
+    pageSize?: number;
+}
+interface PagedDocumentsResponse {
+    results: Document[];
+    total: number;
+    page: number;
+    pageSize: number;
+    totalPages: number;
+}
 interface DocumentStatusResponse {
     status: DocumentStatus;
+    id?: string;
+    externalID?: string | null;
+    originalScore?: number | null;
+    auditedScore?: number | null;
+    metadata?: Record<string, unknown> | null;
+}
+interface UploadOptions {
+    /**
+     * Your system's id for this document (1-100 chars: letters, digits,
+     * - _ . :). Afterwards every endpoint that takes a reportID also accepts
+     * this externalID. A taken externalID rejects the upload with 409.
+     */
+    externalID?: string;
+    /** Metadata to store on the document (JSON object, max 8KB) */
+    metadata?: Record<string, unknown>;
 }
 interface UploadResponse {
     id: string;
     createdAt: string;
     numberOfPages: number;
+    externalID?: string;
+    metadata?: Record<string, unknown>;
 }
 interface DeleteDocumentsParams {
     files: string[];
@@ -66,7 +104,19 @@ interface RenameGroupParams {
 interface RenameGroupResponse {
     results: "ok";
 }
-interface AuditDocumentsParams {
+interface AuditDocumentsOptions {
+    engine?: string;
+    addSignature?: boolean;
+    fixContrast?: boolean;
+    autoRemove?: number;
+    deleteAfterAudit?: boolean;
+    /**
+     * For `check` runs only: delete the stored file once the check finishes.
+     * The report and score are kept. Per-request only — there is no saved default.
+     */
+    deleteFileAfterCheck?: boolean;
+}
+interface AuditDocumentsParams extends AuditDocumentsOptions {
     files: string[];
     type?: AuditType;
 }
@@ -124,6 +174,26 @@ interface DownloadFileParams {
 interface DownloadZippedParams {
     files: string[];
 }
+interface ConvertHtmlParams {
+    files: string[];
+    autoConvert?: boolean;
+    auditHtml?: boolean;
+}
+interface ConvertHtmlResponse {
+    results: "ok";
+}
+interface CancelManualParams {
+    files: string[];
+}
+interface CancelManualResponse {
+    data: "ok";
+}
+interface PdfSettingsParams {
+    autoConvert: boolean;
+}
+interface PdfSettingsResponse {
+    results: "ok";
+}
 interface EqualWebErrorResponse {
     error?: string;
     message?: string;
@@ -180,13 +250,18 @@ declare class DocumentsApi {
     constructor(client: HttpClient);
     /**
      * Get all documents
-     * @param params - Optional filters for groupID, archived status, and document type
-     * @returns Array of documents
+     * @param params - Optional filters for groupID, archived status, and
+     * document type. Passing `page` (and optionally `pageSize`) opts in to
+     * pagination and switches the return value to a paged envelope; without it
+     * the full array is returned as before.
+     * @returns Array of documents, or a paged envelope when `page` is passed
      */
     getAll(params?: GetDocumentsParams): Promise<Document[]>;
+    getAll(params: GetDocumentsPagedParams): Promise<PagedDocumentsResponse>;
     /**
      * Get the status of a specific document
-     * @param reportID - The report ID of the document
+     * @param reportID - The report ID of the document, or the externalID your
+     * system linked at upload time
      * @returns The document status
      */
     getStatus(reportID: string): Promise<string>;
@@ -195,9 +270,12 @@ declare class DocumentsApi {
      * Supported formats: PDF, XLSX, DOCX, PPTX
      * @param file - The file to upload (File, Blob, ArrayBuffer, or Uint8Array)
      * @param filename - Optional filename (required if file is an ArrayBuffer or Uint8Array)
+     * @param options - Optional externalID (links the doc to your own system;
+     * rejected with 409 if already in use) and metadata (JSON object stored on
+     * the document, max 8KB)
      * @returns Upload response with document ID and metadata
      */
-    upload(file: File | Blob | ArrayBuffer | Uint8Array, filename?: string): Promise<UploadResponse>;
+    upload(file: File | Blob | ArrayBuffer | Uint8Array, filename?: string, options?: UploadOptions): Promise<UploadResponse>;
     /**
      * Delete multiple documents
      * @param files - Array of document IDs to delete
@@ -256,22 +334,26 @@ declare class AuditApi {
      * Start a full audit on documents
      * This performs accessibility remediation and generates detailed reports
      * @param files - Array of document IDs to audit
+     * @param options - Optional audit settings (engine, addSignature, fixContrast, autoRemove, deleteAfterAudit)
      * @returns Result of the operation (202 Accepted - processing is async)
      */
-    audit(files: string[]): Promise<AuditDocumentsResponse>;
+    audit(files: string[], options?: AuditDocumentsOptions): Promise<AuditDocumentsResponse>;
     /**
      * Perform a quick check on documents without full remediation
      * @param files - Array of document IDs to check
+     * @param options - Optional audit settings (engine, addSignature, fixContrast, autoRemove, deleteAfterAudit, deleteFileAfterCheck)
      * @returns Result of the operation (202 Accepted - processing is async)
      */
-    check(files: string[]): Promise<AuditDocumentsResponse>;
+    check(files: string[], options?: AuditDocumentsOptions): Promise<AuditDocumentsResponse>;
     /**
      * Start an audit with custom type
      * @param files - Array of document IDs to process
-     * @param type - Type of audit: "audit" for full audit, "check" for quick check
+     * @param type - Type of audit: "audit", "tag", "ocr", "check", "manual", or "sign"
+     * @param options - Optional audit settings (engine, addSignature, fixContrast, autoRemove, deleteAfterAudit)
      * @returns Result of the operation (202 Accepted - processing is async)
      */
-    process(files: string[], type: AuditType): Promise<AuditDocumentsResponse>;
+    process(files: string[], type: AuditType, options?: AuditDocumentsOptions): Promise<AuditDocumentsResponse>;
+    private validateOptions;
 }
 
 declare class ReportsApi {
@@ -343,6 +425,42 @@ declare class DownloadsApi {
     zipped(files: string[]): Promise<Blob>;
 }
 
+declare class ConvertApi {
+    private readonly client;
+    constructor(client: HttpClient);
+    /**
+     * Convert PDF documents to HTML
+     * @param files - Array of document IDs to convert
+     * @param options - Optional conversion settings
+     * @param sitekey - Optional site key for site-specific conversion
+     * @returns Result of the operation
+     */
+    html(files: string[], options?: Omit<ConvertHtmlParams, "files">, sitekey?: string): Promise<ConvertHtmlResponse>;
+}
+
+declare class ManualApi {
+    private readonly client;
+    constructor(client: HttpClient);
+    /**
+     * Cancel manual remediation for documents
+     * @param files - Array of document IDs to cancel manual remediation for
+     * @returns Result of the operation
+     */
+    cancel(files: string[]): Promise<CancelManualResponse>;
+}
+
+declare class SettingsApi {
+    private readonly client;
+    constructor(client: HttpClient);
+    /**
+     * Update PDF settings for a site
+     * @param siteKey - The site key to update settings for
+     * @param params - Settings to update
+     * @returns Result of the operation
+     */
+    update(siteKey: string, params: PdfSettingsParams): Promise<PdfSettingsResponse>;
+}
+
 declare class EqualWeb {
     private readonly client;
     readonly info: InfoApi;
@@ -351,6 +469,9 @@ declare class EqualWeb {
     readonly audit: AuditApi;
     readonly reports: ReportsApi;
     readonly downloads: DownloadsApi;
+    readonly convert: ConvertApi;
+    readonly manual: ManualApi;
+    readonly settings: SettingsApi;
     /**
      * Create a new EqualWeb API client
      * @param config - Configuration object with API key and optional settings
@@ -378,4 +499,4 @@ declare class EqualWeb {
     constructor(config: EqualWebConfig);
 }
 
-export { type ArchiveDocumentsParams, type ArchiveDocumentsResponse, AuditApi, type AuditDocumentsParams, type AuditDocumentsResponse, type AuditType, type AuditedReport, AuthenticationError, type BalanceResponse, type DeleteDocumentsParams, type DeleteDocumentsResponse, type DetailedReport, type Document, type DocumentGroup, type DocumentStatus, type DocumentStatusResponse, DocumentsApi, type DownloadFileParams, type DownloadFileType, type DownloadZippedParams, DownloadsApi, EqualWeb, type EqualWebConfig, EqualWebError, type EqualWebErrorResponse, type GetDocumentsParams, type GetReportParams, type GroupDocumentsParams, type GroupDocumentsResponse, GroupsApi, InfoApi, type OriginalReport, RateLimitError, type RenameGroupParams, type RenameGroupResponse, type ReportCustomData, type ReportResponse, type ReportRule, type ReportSummary, type ReportType, ReportsApi, type UploadResponse };
+export { type ArchiveDocumentsParams, type ArchiveDocumentsResponse, AuditApi, type AuditDocumentsOptions, type AuditDocumentsParams, type AuditDocumentsResponse, type AuditType, type AuditedReport, AuthenticationError, type BalanceResponse, type CancelManualParams, type CancelManualResponse, ConvertApi, type ConvertHtmlParams, type ConvertHtmlResponse, type DeleteDocumentsParams, type DeleteDocumentsResponse, type DetailedReport, type Document, type DocumentGroup, type DocumentStatus, type DocumentStatusResponse, DocumentsApi, type DownloadFileParams, type DownloadFileType, type DownloadZippedParams, DownloadsApi, EqualWeb, type EqualWebConfig, EqualWebError, type EqualWebErrorResponse, type GetDocumentsParams, type GetReportParams, type GroupDocumentsParams, type GroupDocumentsResponse, GroupsApi, InfoApi, ManualApi, type OriginalReport, type PdfSettingsParams, type PdfSettingsResponse, RateLimitError, type RenameGroupParams, type RenameGroupResponse, type ReportCustomData, type ReportResponse, type ReportRule, type ReportSummary, type ReportType, ReportsApi, SettingsApi, type UploadResponse };