@taxora/sdk 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,315 @@
+declare class Token {
+    readonly accessToken: string;
+    readonly tokenType: string;
+    readonly expiresAt: Date;
+    constructor(accessToken: string, tokenType: string, expiresAt: Date);
+    isExpired(bufferSeconds?: number): boolean;
+    static fromArray(data: Record<string, unknown>): Token;
+    toArray(): {
+        access_token: string;
+        token_type: string;
+        expires_at: string;
+    };
+}
+
+declare const LoginIdentifier: {
+    readonly EMAIL: "email";
+    readonly CLIENT_ID: "client_id";
+};
+type LoginIdentifier = (typeof LoginIdentifier)[keyof typeof LoginIdentifier];
+
+interface HttpClientInterface {
+    request(method: string, url: string, options?: RequestInit): Promise<Response>;
+}
+
+interface TokenStorageInterface {
+    get(): Token | null;
+    set(token: Token): void;
+    clear(): void;
+}
+
+declare class AuthEndpoint {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly tokenStorage;
+    private readonly httpClient;
+    constructor(baseUrl: string, apiKey: string, tokenStorage: TokenStorageInterface, httpClient: HttpClientInterface);
+    login(identifier: string, password: string, device?: string, loginIdentifier?: LoginIdentifier): Promise<Token>;
+    loginWithClientId(clientId: string, password: string, device?: string): Promise<Token>;
+    refresh(): Promise<Token>;
+    private parseResponse;
+}
+
+declare class CompanyEndpoint {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly tokenStorage;
+    private readonly httpClient;
+    constructor(baseUrl: string, apiKey: string, tokenStorage: TokenStorageInterface, httpClient: HttpClientInterface);
+    get(): Promise<Record<string, unknown>>;
+}
+
+declare const VatState: {
+    readonly VALID: "valid";
+    readonly INVALID: "invalid";
+    readonly FRAUD: "fraud";
+    readonly UNKNOWN: "unknown";
+};
+type VatState = (typeof VatState)[keyof typeof VatState];
+declare function getFailedVatStates(): VatState[];
+declare function describeVatState(state: VatState): string;
+
+interface CompanyAddressProps {
+    fullAddress?: string | null;
+    name?: string | null;
+    street?: string | null;
+    postalCode?: string | null;
+    city?: string | null;
+    state?: string | null;
+    country?: string | null;
+    raw?: string | null;
+}
+declare class CompanyAddress {
+    readonly fullAddress: string | null;
+    readonly name: string | null;
+    readonly street: string | null;
+    readonly postalCode: string | null;
+    readonly city: string | null;
+    readonly state: string | null;
+    readonly country: string | null;
+    readonly raw: string | null;
+    constructor(props: CompanyAddressProps);
+    private assembleFullAddress;
+    static from(value: unknown): CompanyAddress | null;
+    static fromArray(data: Record<string, unknown>, raw: string | null): CompanyAddress;
+    toArray(): Record<string, string | null>;
+    toString(): string;
+}
+
+declare class ScoreBreakdown {
+    readonly stepName: string;
+    readonly scoreContribution: number;
+    readonly metadata: Record<string, unknown>;
+    constructor(stepName: string, scoreContribution: number, metadata: Record<string, unknown>);
+    static fromArray(data: Record<string, unknown>): ScoreBreakdown;
+    toArray(): {
+        step_name: string;
+        score_contribution: number;
+        metadata: Record<string, unknown>;
+    };
+}
+
+declare class ProviderDocumentLine {
+    readonly id: number | null;
+    readonly vatUid: string | null;
+    readonly rowNumber: number | null;
+    readonly entryIdentifier: string | null;
+    readonly reference: string | null;
+    readonly meta: Record<string, unknown>;
+    constructor(id: number | null, vatUid: string | null, rowNumber: number | null, entryIdentifier: string | null, reference: string | null, meta: Record<string, unknown>);
+    static fromArray(data: unknown): ProviderDocumentLine | null;
+    toArray(): Record<string, unknown>;
+}
+
+declare class ProviderDocument {
+    readonly id: number | null;
+    readonly provider: string | null;
+    readonly documentType: string | null;
+    readonly state: string | null;
+    readonly documentDate: Date | null;
+    readonly mime: string | null;
+    readonly size: number | null;
+    readonly hash: string | null;
+    readonly meta: Record<string, unknown>;
+    readonly line: ProviderDocumentLine | null;
+    constructor(id: number | null, provider: string | null, documentType: string | null, state: string | null, documentDate: Date | null, mime: string | null, size: number | null, hash: string | null, meta: Record<string, unknown>, line: ProviderDocumentLine | null);
+    static fromArray(data: unknown): ProviderDocument | null;
+    toArray(): Record<string, unknown>;
+}
+
+declare class VatResource {
+    readonly uuid: string | undefined;
+    readonly vatUid: string | undefined;
+    readonly state: VatState | undefined;
+    readonly countryCode: string | undefined;
+    readonly companyName: string | undefined;
+    readonly companyAddress: CompanyAddress | undefined;
+    readonly requestedCompanyName: string | undefined;
+    readonly requestedCompanyNameOriginal: string | undefined;
+    readonly requestedInputAddress: Record<string, string | null> | undefined;
+    readonly checkedAt: Date | undefined;
+    readonly score: number | undefined;
+    readonly scoreSource: string | undefined;
+    readonly scoreAttempts: Array<{
+        source?: string;
+        score?: number;
+    }> | undefined;
+    readonly breakdown: ScoreBreakdown[] | undefined;
+    readonly environment: string | undefined;
+    readonly provider: string | undefined;
+    readonly usedProviders: string[] | undefined;
+    readonly providerVatState: string | undefined;
+    readonly providerNote: string | undefined;
+    readonly providerLastCheckedAt: Date | undefined;
+    readonly providerDocument: ProviderDocument | undefined;
+    constructor(uuid: string | undefined, vatUid: string | undefined, state: VatState | undefined, countryCode: string | undefined, companyName: string | undefined, companyAddress: CompanyAddress | undefined, requestedCompanyName: string | undefined, requestedCompanyNameOriginal: string | undefined, requestedInputAddress: Record<string, string | null> | undefined, checkedAt: Date | undefined, score: number | undefined, scoreSource: string | undefined, scoreAttempts: Array<{
+        source?: string;
+        score?: number;
+    }> | undefined, breakdown: ScoreBreakdown[] | undefined, environment: string | undefined, provider: string | undefined, usedProviders: string[] | undefined, providerVatState: string | undefined, providerNote: string | undefined, providerLastCheckedAt: Date | undefined, providerDocument: ProviderDocument | undefined);
+    static fromArray(data: Record<string, unknown>): VatResource;
+    getBackendLink(): string | null;
+    toArray(): Record<string, unknown>;
+}
+
+declare class VatCollection implements Iterable<VatResource> {
+    private readonly items;
+    readonly self: string | undefined;
+    constructor(items: VatResource[], self?: string);
+    static fromResponse(data: unknown): VatCollection;
+    [Symbol.iterator](): Iterator<VatResource>;
+    get length(): number;
+    all(): VatResource[];
+}
+
+declare class VatCertificateExport {
+    readonly exportId: string;
+    readonly message?: string | undefined;
+    constructor(exportId: string, message?: string | undefined);
+    static fromArray(data: Record<string, unknown>): VatCertificateExport;
+    toArray(): {
+        export_id: string;
+        message?: string;
+    };
+}
+
+interface VatValidationAddressInputProps {
+    addressLine1?: string;
+    addressLine2?: string;
+    postalCode?: string;
+    city?: string;
+    countryCode?: string;
+}
+declare class VatValidationAddressInput {
+    readonly addressLine1?: string;
+    readonly addressLine2?: string;
+    readonly postalCode?: string;
+    readonly city?: string;
+    readonly countryCode?: string;
+    constructor(props: VatValidationAddressInputProps);
+    static fromArray(data: Record<string, unknown>): VatValidationAddressInput;
+    toArray(): Record<string, string>;
+}
+
+declare const Language: {
+    readonly ENGLISH: "en";
+    readonly GERMAN: "de";
+};
+type Language = (typeof Language)[keyof typeof Language];
+
+declare class VatEndpoint {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly tokenStorage;
+    private readonly httpClient;
+    constructor(baseUrl: string, apiKey: string, tokenStorage: TokenStorageInterface, httpClient: HttpClientInterface);
+    validate(vatUid: string, companyName?: string, provider?: string, addressInput?: VatValidationAddressInput | Record<string, string>): Promise<VatResource>;
+    private validateWithGatewayRetry;
+    validateMultiple(vatUids: string[], companyNames?: string[], provider?: string): Promise<VatCollection>;
+    validateSchema(vatUid: string): Promise<Record<string, unknown>>;
+    state(vatUid: string): Promise<VatResource>;
+    history(vatUid?: string): Promise<VatCollection>;
+    search(term?: string, perPage?: number): Promise<VatCollection>;
+    certificate(uuid: string, lang?: Language): Promise<Uint8Array>;
+    certificatesBulkExport(fromDate: Date | string, toDate: Date | string, countries?: string[], lang?: Language): Promise<VatCertificateExport>;
+    certificatesListExport(fromDate: Date | string, toDate: Date | string, countries?: string[], lang?: Language): Promise<VatCertificateExport>;
+    private exportRequest;
+    downloadBulkExport(exportId: string): Promise<Uint8Array>;
+    private buildHeaders;
+    private sendRequest;
+    private sendBinaryRequest;
+    private parseJsonResponse;
+    private formatDate;
+}
+
+declare const Environment: {
+    readonly SANDBOX: "sandbox";
+    readonly PRODUCTION: "production";
+};
+type Environment = (typeof Environment)[keyof typeof Environment];
+declare function getBaseUrl(environment: Environment): string;
+
+interface TaxoraClientOptions {
+    apiKey: string;
+    environment?: Environment;
+    tokenStorage?: TokenStorageInterface;
+    httpClient?: HttpClientInterface;
+}
+declare class TaxoraClient {
+    readonly auth: AuthEndpoint;
+    readonly vat: VatEndpoint;
+    readonly company: CompanyEndpoint;
+    readonly baseUrl: string;
+    constructor(options: TaxoraClientOptions);
+}
+
+declare class TaxoraClientFactory {
+    static create(options: TaxoraClientOptions): TaxoraClient;
+}
+
+declare const ApiVersion: {
+    readonly V1: "v1";
+};
+type ApiVersion = (typeof ApiVersion)[keyof typeof ApiVersion];
+
+declare class TaxoraException extends Error {
+    readonly context: Record<string, unknown>;
+    constructor(message: string, context?: Record<string, unknown>);
+}
+
+declare class AuthenticationException extends TaxoraException {
+    readonly statusCode = 401;
+    constructor(message: string, context?: Record<string, unknown>);
+}
+
+declare class HttpException extends TaxoraException {
+    readonly statusCode: number;
+    readonly responseBody: string;
+    constructor(message: string, statusCode: number, responseBody: string, context?: Record<string, unknown>);
+    getStatusCode(): number;
+    getResponseBody(): string;
+}
+
+declare class ValidationException extends TaxoraException {
+    readonly statusCode = 422;
+    private readonly errors;
+    constructor(message: string, errors: Record<string, string[]>, context?: Record<string, unknown>);
+    getErrors(): Record<string, string[]>;
+}
+
+declare class InMemoryTokenStorage implements TokenStorageInterface {
+    private token;
+    get(): Token | null;
+    set(token: Token): void;
+    clear(): void;
+}
+
+declare class FetchHttpClient implements HttpClientInterface {
+    request(method: string, url: string, options?: RequestInit): Promise<Response>;
+}
+
+/**
+ * HTTP client wrapper that handles:
+ * - Preemptive token refresh when the stored token is expired
+ * - Automatic retry with a fresh token on 401 responses
+ * - Passthrough for /auth/ routes (no interception)
+ */
+declare class AuthRetryHttpClient implements HttpClientInterface {
+    private readonly inner;
+    private readonly tokenStorage;
+    private readonly refreshFn;
+    constructor(inner: HttpClientInterface, tokenStorage: TokenStorageInterface, refreshFn: () => Promise<Token>);
+    request(method: string, url: string, options?: RequestInit): Promise<Response>;
+    private injectAuthHeader;
+}
+
+export { ApiVersion, AuthEndpoint, AuthRetryHttpClient, AuthenticationException, CompanyAddress, CompanyEndpoint, Environment, Environment as EnvironmentType, FetchHttpClient, type HttpClientInterface, HttpException, InMemoryTokenStorage, Language, LoginIdentifier, ProviderDocument, ProviderDocumentLine, ScoreBreakdown, TaxoraClient, TaxoraClientFactory, type TaxoraClientOptions, TaxoraException, Token, type TokenStorageInterface, ValidationException, VatCertificateExport, VatCollection, VatEndpoint, VatResource, VatState, VatValidationAddressInput, describeVatState, getBaseUrl, getFailedVatStates };