equalweb-sdk 1.0.0

package/README.md

@@ -0,0 +1,227 @@
+# equalweb-api
+
+Official SDK for the EqualWeb V2 API - Document accessibility auditing and PDF remediation.
+
+## Requirements
+
+- Node.js >= 18.0.0
+- TypeScript 5.x (for TypeScript projects)
+
+## Installation
+
+```bash
+npm install equalweb-api
+```
+
+## Quick Start
+
+```typescript
+import { EqualWeb } from "equalweb-api";
+
+const client = new EqualWeb({ apiKey: "your-api-key" });
+
+// Check your credit balance
+const balance = await client.info.getBalance();
+console.log(`Credits remaining: ${balance}`);
+
+// Upload a document
+const file = new File([buffer], "document.pdf", { type: "application/pdf" });
+const upload = await client.documents.upload(file);
+console.log(`Uploaded: ${upload.id}`);
+
+// Start an accessibility audit
+await client.audit.audit([upload.id]);
+
+// Check status (audit is async)
+const status = await client.documents.getStatus(upload.id);
+console.log(`Status: ${status}`);
+
+// Download the audited file when done
+if (status === "done") {
+  const blob = await client.downloads.audited(upload.id);
+}
+```
+
+## API Reference
+
+### Configuration
+
+```typescript
+const client = new EqualWeb({
+  apiKey: "your-api-key", // Required
+  baseUrl: "https://login.equalweb.com/api/v2", // Optional
+  timeout: 30000, // Optional, in milliseconds
+});
+```
+
+### Info
+
+```typescript
+// Get credit balance
+const balance = await client.info.getBalance();
+```
+
+### Documents
+
+```typescript
+// Get all documents
+const docs = await client.documents.getAll();
+
+// Get documents with filters
+const filtered = await client.documents.getAll({
+  groupID: "123",
+  archived: false,
+  type: "pdf",
+});
+
+// Get document status
+const status = await client.documents.getStatus("reportID");
+
+// Upload a document (supports PDF, XLSX, DOCX, PPTX)
+const upload = await client.documents.upload(file);
+
+// Delete documents
+const result = await client.documents.delete(["id1", "id2"]);
+
+// Archive documents
+await client.documents.archive(["id1", "id2"]);
+
+// Restore archived documents
+await client.documents.restore(["id1", "id2"]);
+```
+
+### Groups
+
+```typescript
+// Get all groups
+const groups = await client.groups.getAll();
+
+// Create a new group with documents
+await client.groups.createGroup(["doc1", "doc2"], "My Group");
+
+// Add documents to existing group
+await client.groups.addToGroup(["doc3"], "groupID");
+
+// Rename a group
+await client.groups.rename("groupID", "New Name");
+```
+
+### Audit
+
+```typescript
+// Full audit (accessibility remediation)
+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");
+```
+
+### Reports
+
+```typescript
+// Get audited report (default)
+const report = await client.reports.get("reportID");
+
+// Get original report
+const original = await client.reports.getOriginal("reportID");
+
+// Get both reports
+const both = await client.reports.getBoth("reportID");
+
+// Get browser-viewable URL (no auth required)
+const url = client.reports.getBrowserUrl("reportID");
+```
+
+### Downloads
+
+```typescript
+// Download audited file
+const audited = await client.downloads.audited("reportID");
+
+// Download original file
+const original = await client.downloads.original("reportID");
+
+// Download with options (file type and original flag)
+const file = await client.downloads.file("reportID", {
+  original: false,
+  type: "pdf",
+});
+
+// Download as XLSX
+const xlsx = await client.downloads.audited("reportID", "xlsx");
+
+// Download multiple as ZIP
+const zip = await client.downloads.zipped(["id1", "id2", "id3"]);
+```
+
+## Error Handling
+
+```typescript
+import { EqualWeb, EqualWebError, RateLimitError, AuthenticationError } from "equalweb-api";
+
+try {
+  await client.documents.getAll();
+} catch (error) {
+  if (error instanceof AuthenticationError) {
+    console.error("Invalid API key");
+  } else if (error instanceof RateLimitError) {
+    console.error(`Rate limited. Retry after: ${error.retryAfter}s`);
+  } else if (error instanceof EqualWebError) {
+    console.error(`API error ${error.statusCode}: ${error.message}`);
+  }
+}
+```
+
+## TypeScript Support
+
+Full TypeScript support with exported types:
+
+```typescript
+import type {
+  Document,
+  DocumentGroup,
+  ReportResponse,
+  UploadResponse,
+  EqualWebConfig,
+} from "equalweb-api";
+```
+
+## Supported File Formats
+
+The SDK supports uploading and processing the following document formats:
+
+- **PDF** - Portable Document Format
+- **XLSX** - Microsoft Excel
+- **DOCX** - Microsoft Word
+- **PPTX** - Microsoft PowerPoint
+
+All documents are processed for accessibility compliance according to WCAG and ADA standards.
+
+## Rate Limiting
+
+The API has a rate limit of 100 requests per minute per API key. The SDK throws a `RateLimitError` when the limit is exceeded. Implement retry logic with exponential backoff:
+
+```typescript
+async function withRetry<T>(fn: () => Promise<T>, maxRetries = 3): Promise<T> {
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      return await fn();
+    } catch (error) {
+      if (error instanceof RateLimitError && i < maxRetries - 1) {
+        const delay = (error.retryAfter ?? 60) * 1000;
+        await new Promise((r) => setTimeout(r, delay));
+        continue;
+      }
+      throw error;
+    }
+  }
+  throw new Error("Max retries exceeded");
+}
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,381 @@
+interface EqualWebConfig {
+    apiKey: string;
+    baseUrl?: string;
+    timeout?: number;
+}
+type DocumentStatus = "done" | "pending" | "processing" | string;
+type AuditType = "audit" | "check";
+type ReportType = "audited" | "original" | "both";
+type DownloadFileType = "pdf" | "xlsx";
+interface BalanceResponse {
+    results: number;
+}
+interface Document {
+    numberOfPages: number;
+    createdAt: string;
+    group: number | null;
+    archived: boolean;
+    reportID: string;
+    status: DocumentStatus;
+}
+interface GetDocumentsParams {
+    groupID?: string;
+    archived?: boolean;
+    type?: string;
+}
+interface DocumentStatusResponse {
+    status: DocumentStatus;
+}
+interface UploadResponse {
+    id: string;
+    createdAt: string;
+    numberOfPages: number;
+}
+interface DeleteDocumentsParams {
+    files: string[];
+}
+interface DeleteDocumentsResponse {
+    results: Record<string, boolean | {
+        error: string;
+    }>;
+}
+interface ArchiveDocumentsParams {
+    files: string[];
+    archive?: boolean;
+}
+interface ArchiveDocumentsResponse {
+    results: "ok";
+}
+interface DocumentGroup {
+    id: number;
+    name: string;
+    createdAt: string;
+}
+interface GroupDocumentsParams {
+    files: string[];
+    newGroup?: string;
+    selectedGroup?: string;
+}
+interface GroupDocumentsResponse {
+    results: "ok";
+}
+interface RenameGroupParams {
+    groupID: string;
+    groupName: string;
+}
+interface RenameGroupResponse {
+    results: "ok";
+}
+interface AuditDocumentsParams {
+    files: string[];
+    type?: AuditType;
+}
+interface AuditDocumentsResponse {
+    results: "ok";
+}
+interface ReportRule {
+    Rule: string;
+    Status: "Passed" | "Failed" | "Needs manual check" | string;
+    Description: string;
+}
+interface ReportSummary {
+    "Passed"?: number;
+    "Failed"?: number;
+    "Needs manual check"?: number;
+    Description?: string;
+}
+interface DetailedReport {
+    Document?: ReportRule[];
+    "Page Content"?: ReportRule[];
+    Forms?: ReportRule[];
+    "Alternate Text"?: ReportRule[];
+    Tables?: ReportRule[];
+    Lists?: ReportRule[];
+    Headings?: ReportRule[];
+}
+interface ReportCustomData {
+    fileName?: string;
+    fileSize?: number;
+    numberOfPages?: number;
+    tags?: Record<string, number>;
+    [key: string]: unknown;
+}
+interface AuditedReport {
+    Summary?: ReportSummary;
+    "Detailed Report"?: DetailedReport;
+    customData?: ReportCustomData;
+}
+interface OriginalReport {
+    Summary?: ReportSummary;
+    "Detailed Report"?: DetailedReport;
+    customData?: ReportCustomData;
+}
+interface GetReportParams {
+    type?: ReportType;
+}
+interface ReportResponse {
+    original?: OriginalReport;
+    audited?: AuditedReport;
+}
+interface DownloadFileParams {
+    original?: boolean;
+    type?: DownloadFileType;
+}
+interface DownloadZippedParams {
+    files: string[];
+}
+interface EqualWebErrorResponse {
+    error?: string;
+    message?: string;
+    statusCode?: number;
+}
+declare class EqualWebError extends Error {
+    readonly statusCode: number;
+    readonly response?: EqualWebErrorResponse;
+    constructor(message: string, statusCode: number, response?: EqualWebErrorResponse);
+}
+declare class RateLimitError extends EqualWebError {
+    readonly retryAfter?: number;
+    constructor(message: string, retryAfter?: number);
+}
+declare class AuthenticationError extends EqualWebError {
+    constructor(message?: string);
+}
+
+interface RequestOptions {
+    method: "GET" | "POST" | "PUT" | "DELETE";
+    path: string;
+    query?: Record<string, string | boolean | undefined>;
+    body?: unknown;
+    isFormData?: boolean;
+    responseType?: "json" | "blob";
+}
+declare class HttpClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    constructor(config: EqualWebConfig);
+    request<T>(options: RequestOptions): Promise<T>;
+    private handleErrorResponse;
+    get<T>(path: string, query?: Record<string, string | boolean | undefined>): Promise<T>;
+    post<T>(path: string, body?: unknown): Promise<T>;
+    put<T>(path: string, body?: unknown, isFormData?: boolean): Promise<T>;
+    delete<T>(path: string, body?: unknown): Promise<T>;
+    getBlob(path: string, query?: Record<string, string | boolean | undefined>): Promise<Blob>;
+    postBlob(path: string, body?: unknown): Promise<Blob>;
+}
+
+declare class InfoApi {
+    private readonly client;
+    constructor(client: HttpClient);
+    /**
+     * Get the current credit balance for your account
+     * @returns The current credit balance
+     */
+    getBalance(): Promise<number>;
+}
+
+declare class DocumentsApi {
+    private readonly client;
+    constructor(client: HttpClient);
+    /**
+     * Get all documents
+     * @param params - Optional filters for groupID, archived status, and document type
+     * @returns Array of documents
+     */
+    getAll(params?: GetDocumentsParams): Promise<Document[]>;
+    /**
+     * Get the status of a specific document
+     * @param reportID - The report ID of the document
+     * @returns The document status
+     */
+    getStatus(reportID: string): Promise<string>;
+    /**
+     * Upload a document for processing
+     * 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)
+     * @returns Upload response with document ID and metadata
+     */
+    upload(file: File | Blob | ArrayBuffer | Uint8Array, filename?: string): Promise<UploadResponse>;
+    /**
+     * Delete multiple documents
+     * @param files - Array of document IDs to delete
+     * @returns Results indicating success/failure for each document
+     */
+    delete(files: string[]): Promise<DeleteDocumentsResponse>;
+    /**
+     * Archive documents
+     * @param files - Array of document IDs to archive
+     * @returns Result of the operation
+     */
+    archive(files: string[]): Promise<ArchiveDocumentsResponse>;
+    /**
+     * Restore archived documents
+     * @param files - Array of document IDs to restore
+     * @returns Result of the operation
+     */
+    restore(files: string[]): Promise<ArchiveDocumentsResponse>;
+}
+
+declare class GroupsApi {
+    private readonly client;
+    constructor(client: HttpClient);
+    /**
+     * Get all document groups
+     * @returns Array of document groups
+     */
+    getAll(): Promise<DocumentGroup[]>;
+    /**
+     * Add documents to a new group
+     * @param files - Array of document IDs to group
+     * @param groupName - Name of the new group to create
+     * @returns Result of the operation
+     */
+    createGroup(files: string[], groupName: string): Promise<GroupDocumentsResponse>;
+    /**
+     * Add documents to an existing group
+     * @param files - Array of document IDs to group
+     * @param groupID - ID of the existing group
+     * @returns Result of the operation
+     */
+    addToGroup(files: string[], groupID: string): Promise<GroupDocumentsResponse>;
+    /**
+     * Rename a document group
+     * @param groupID - ID of the group to rename
+     * @param groupName - New name for the group
+     * @returns Result of the operation
+     */
+    rename(groupID: string, groupName: string): Promise<RenameGroupResponse>;
+}
+
+declare class AuditApi {
+    private readonly client;
+    constructor(client: HttpClient);
+    /**
+     * Start a full audit on documents
+     * This performs accessibility remediation and generates detailed reports
+     * @param files - Array of document IDs to audit
+     * @returns Result of the operation (202 Accepted - processing is async)
+     */
+    audit(files: string[]): Promise<AuditDocumentsResponse>;
+    /**
+     * Perform a quick check on documents without full remediation
+     * @param files - Array of document IDs to check
+     * @returns Result of the operation (202 Accepted - processing is async)
+     */
+    check(files: string[]): 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
+     * @returns Result of the operation (202 Accepted - processing is async)
+     */
+    process(files: string[], type: AuditType): Promise<AuditDocumentsResponse>;
+}
+
+declare class ReportsApi {
+    private readonly client;
+    constructor(client: HttpClient);
+    /**
+     * Get the JSON report for a document
+     * @param reportID - The report ID
+     * @param type - Which report to retrieve: "audited", "original", or "both"
+     * @returns The report data
+     */
+    get(reportID: string, type?: ReportType): Promise<ReportResponse>;
+    /**
+     * Get the audited report for a document
+     * @param reportID - The report ID
+     * @returns The audited report data
+     */
+    getAudited(reportID: string): Promise<ReportResponse>;
+    /**
+     * Get the original report for a document
+     * @param reportID - The report ID
+     * @returns The original report data
+     */
+    getOriginal(reportID: string): Promise<ReportResponse>;
+    /**
+     * Get both audited and original reports for a document
+     * @param reportID - The report ID
+     * @returns Both report data
+     */
+    getBoth(reportID: string): Promise<ReportResponse>;
+    /**
+     * Get the URL to view the report in a browser
+     * Note: This URL does not require authentication
+     * @param reportID - The report ID
+     * @returns The browser-viewable URL
+     */
+    getBrowserUrl(reportID: string): string;
+}
+
+declare class DownloadsApi {
+    private readonly client;
+    constructor(client: HttpClient);
+    /**
+     * Download a single document file
+     * @param reportID - The report ID of the document
+     * @param options - Download options (original file, file type)
+     * @returns The file as a Blob
+     */
+    file(reportID: string, options?: DownloadFileParams): Promise<Blob>;
+    /**
+     * Download the audited/processed version of a document
+     * @param reportID - The report ID of the document
+     * @param type - File type to download (pdf or xlsx)
+     * @returns The processed file as a Blob
+     */
+    audited(reportID: string, type?: DownloadFileType): Promise<Blob>;
+    /**
+     * Download the original version of a document
+     * @param reportID - The report ID of the document
+     * @param type - File type to download (pdf or xlsx)
+     * @returns The original file as a Blob
+     */
+    original(reportID: string, type?: DownloadFileType): Promise<Blob>;
+    /**
+     * Download multiple documents as a ZIP file
+     * @param files - Array of document IDs to include in the ZIP
+     * @returns The ZIP file as a Blob
+     */
+    zipped(files: string[]): Promise<Blob>;
+}
+
+declare class EqualWeb {
+    private readonly client;
+    readonly info: InfoApi;
+    readonly documents: DocumentsApi;
+    readonly groups: GroupsApi;
+    readonly audit: AuditApi;
+    readonly reports: ReportsApi;
+    readonly downloads: DownloadsApi;
+    /**
+     * Create a new EqualWeb API client
+     * @param config - Configuration object with API key and optional settings
+     * @example
+     * ```typescript
+     * const client = new EqualWeb({ apiKey: 'your-api-key' });
+     *
+     * // Get credit balance
+     * const balance = await client.info.getBalance();
+     *
+     * // Upload a document
+     * const file = new File([...], 'document.pdf');
+     * const upload = await client.documents.upload(file);
+     *
+     * // Start an audit
+     * await client.audit.audit([upload.id]);
+     *
+     * // Check status
+     * const status = await client.documents.getStatus(upload.id);
+     *
+     * // Download the audited file
+     * const blob = await client.downloads.audited(upload.id);
+     * ```
+     */
+    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 };