@ddex-workbench/sdk/dist/index.d.mts

Official SDK for DDEX Workbench - Open-source DDEX validation and processing tools

/**
 * DDEX Workbench SDK Type Definitions
 */
interface DDEXClientConfig {
    /** API base URL */
    baseURL: string;
    /** API key for authentication */
    apiKey?: string;
    /** Request timeout in milliseconds */
    timeout: number;
    /** Environment (production, development, custom) */
    environment: "production" | "development" | "custom";
    /** Maximum number of retries for failed requests */
    maxRetries: number;
    /** Delay between retries in milliseconds */
    retryDelay: number;
}
type ERNVersion = "4.3" | "4.2" | "3.8.2";
type ERNProfile = "AudioAlbum" | "AudioSingle" | "Video" | "Mixed" | "Classical" | "Ringtone" | "DJ" | "ReleaseByRelease";
type DDEXType = "ERN" | "DSR";
interface ValidationOptions {
    /** Type of DDEX document */
    type?: DDEXType;
    /** DDEX version */
    version: ERNVersion;
    /** Profile for validation */
    profile?: ERNProfile;
    /** Validation mode */
    mode?: "full" | "quick" | "xsd" | "business";
    /** Strict mode (treat warnings as errors) */
    strict?: boolean;
}
interface ValidationErrorDetail {
    /** Line number where error occurred */
    line: number;
    /** Column number where error occurred */
    column: number;
    /** Error message */
    message: string;
    /** Error severity */
    severity: "error" | "warning" | "info";
    /** Validation rule that triggered the error */
    rule: string;
    /** Context showing the error location */
    context?: string;
    /** Suggestion for fixing the error */
    suggestion?: string;
}
interface ValidationStep {
    /** Type of validation step */
    type: "XSD" | "BusinessRules" | "Schematron";
    /** Duration in milliseconds */
    duration: number;
    /** Number of errors found */
    errorCount: number;
}
interface ValidationMetadata {
    /** Processing time in milliseconds */
    processingTime: number;
    /** Schema version used */
    schemaVersion: string;
    /** Profile used for validation */
    profile?: string;
    /** Timestamp of validation */
    validatedAt: string;
    /** Total error count */
    errorCount: number;
    /** Total warning count */
    warningCount: number;
    /** Validation steps performed */
    validationSteps: ValidationStep[];
}
interface ValidationResult {
    /** Whether the document is valid */
    valid: boolean;
    /** List of validation errors */
    errors: ValidationErrorDetail[];
    /** List of validation warnings */
    warnings: ValidationErrorDetail[];
    /** Validation metadata */
    metadata: ValidationMetadata;
}
interface SupportedFormats {
    /** Supported DDEX types */
    types: string[];
    /** Supported versions with profiles */
    versions: Array<{
        version: string;
        profiles: string[];
        status: "recommended" | "supported" | "deprecated";
    }>;
}
interface HealthStatus {
    /** Service status */
    status: "healthy" | "degraded" | "unhealthy";
    /** Service version */
    version: string;
    /** Timestamp */
    timestamp: string;
    /** Additional details */
    details?: Record<string, any>;
}
interface ApiKey {
    /** Key ID */
    id: string;
    /** Friendly name */
    name: string;
    /** The actual key (only shown on creation) */
    key?: string;
    /** Creation timestamp */
    created: string;
    /** Last used timestamp */
    lastUsed?: string;
    /** Request count */
    requestCount: number;
    /** Rate limit */
    rateLimit: number;
}

/**
 * High-level validation helper
 */
declare class DDEXValidator {
    private client;
    constructor(client: DDEXClient);
    /**
     * Validate ERN 4.3 content
     */
    validateERN43(content: string, profile?: ERNProfile): Promise<ValidationResult>;
    /**
     * Validate ERN 4.2 content
     */
    validateERN42(content: string, profile?: ERNProfile): Promise<ValidationResult>;
    /**
     * Validate ERN 3.8.2 content
     */
    validateERN382(content: string, profile?: ERNProfile): Promise<ValidationResult>;
    /**
     * Auto-detect ERN version and validate
     */
    validateAuto(content: string): Promise<ValidationResult>;
    /**
     * Batch validate multiple files
     */
    validateBatch(items: Array<{
        content: string;
        options: ValidationOptions;
    }>): Promise<ValidationResult[]>;
    /**
     * Check if content is valid (simplified check)
     */
    isValid(content: string, options: ValidationOptions): Promise<boolean>;
    /**
     * Get only errors (no warnings)
     */
    getErrors(content: string, options: ValidationOptions): Promise<ValidationErrorDetail[]>;
    /**
     * Detect ERN version from XML content
     */
    detectVersion(content: string): ERNVersion | null;
}

/**
 * DDEX Workbench API Client
 *
 * @example
 * ```typescript
 * import { DDEXClient } from '@ddex-workbench/sdk';
 *
 * const client = new DDEXClient({
 *   apiKey: 'ddex_your-api-key',
 *   environment: 'production'
 * });
 *
 * const result = await client.validate(xmlContent, {
 *   version: '4.3',
 *   profile: 'AudioAlbum'
 * });
 * ```
 */
declare class DDEXClient {
    private readonly client;
    private readonly config;
    readonly validator: DDEXValidator;
    constructor(config?: Partial<DDEXClientConfig>);
    /**
     * Validate DDEX XML content
     *
     * @param content - XML content as string
     * @param options - Validation options
     * @returns Validation result with errors and metadata
     *
     * @example
     * ```typescript
     * const result = await client.validate(xmlContent, {
     *   version: '4.3',
     *   profile: 'AudioAlbum'
     * });
     *
     * if (!result.valid) {
     *   console.log('Validation errors:', result.errors);
     * }
     * ```
     */
    validate(content: string, options: ValidationOptions): Promise<ValidationResult>;
    /**
     * Validate XML from URL
     *
     * @param url - URL to XML file
     * @param options - Validation options
     * @returns Validation result
     *
     * @example
     * ```typescript
     * const result = await client.validateURL(
     *   'https://example.com/release.xml',
     *   { version: '4.3', profile: 'AudioAlbum' }
     * );
     * ```
     */
    validateURL(url: string, options: ValidationOptions): Promise<ValidationResult>;
    /**
     * Get supported DDEX formats and versions
     *
     * @returns Supported formats, versions, and profiles
     *
     * @example
     * ```typescript
     * const formats = await client.getSupportedFormats();
     * console.log('Supported versions:', formats.versions);
     * ```
     */
    getSupportedFormats(): Promise<SupportedFormats>;
    /**
     * Check API health status
     *
     * @returns Health status of the API
     *
     * @example
     * ```typescript
     * const health = await client.checkHealth();
     * if (health.status === 'healthy') {
     *   console.log('API is operational');
     * }
     * ```
     */
    checkHealth(): Promise<HealthStatus>;
    /**
     * API Key Management (requires authentication)
     */
    /**
     * List API keys for authenticated user
     *
     * @param authToken - Firebase auth token
     * @returns List of API keys
     */
    listApiKeys(authToken: string): Promise<ApiKey[]>;
    /**
     * Create new API key
     *
     * @param name - Friendly name for the key
     * @param authToken - Firebase auth token
     * @returns New API key (only shown once)
     */
    createApiKey(name: string, authToken: string): Promise<ApiKey>;
    /**
     * Revoke API key
     *
     * @param keyId - API key ID to revoke
     * @param authToken - Firebase auth token
     */
    revokeApiKey(keyId: string, authToken: string): Promise<void>;
    /**
     * Update API key for this client instance
     *
     * @param apiKey - New API key
     */
    setApiKey(apiKey: string): void;
    /**
     * Remove API key from this client instance
     */
    clearApiKey(): void;
    /**
     * Private helper methods
     */
    private setupInterceptors;
    private shouldRetry;
    private handleError;
    private getEnvironment;
}

/**
 * Custom error types for DDEX Workbench SDK
 */
/**
 * Base error class for all DDEX SDK errors
 */
declare class DDEXError extends Error {
    readonly code: string;
    readonly statusCode?: number;
    readonly details?: any;
    constructor(message: string, code?: string, statusCode?: number, details?: any);
}
/**
 * Rate limit exceeded error
 */
declare class RateLimitError extends DDEXError {
    readonly retryAfter?: number;
    constructor(message?: string, retryAfter?: number);
    /**
     * Get human-readable retry message
     */
    getRetryMessage(): string;
}

export { type ApiKey, DDEXClient, type DDEXClientConfig, DDEXError, type DDEXType, DDEXValidator, type ERNProfile, type ERNVersion, type HealthStatus, RateLimitError, type SupportedFormats, type ValidationErrorDetail, type ValidationMetadata, type ValidationOptions, type ValidationResult, type ValidationStep };