@getmandato/sdk 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,486 @@
+/** Configuration options for the Mandato SDK client */
+interface MandatoConfig {
+    /** API key (sk_live_xxx or sk_test_xxx) */
+    apiKey: string;
+    /** Base URL for the API (default: https://api.getmandato.dev) */
+    baseUrl?: string;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Maximum number of retries for 429/5xx errors (default: 3) */
+    maxRetries?: number;
+}
+
+/**
+ * Base HTTP client for the Mandato SDK.
+ * Handles auth, retries, timeouts, idempotency keys, and error mapping.
+ */
+
+/** HTTP client for making requests to the Mandato API */
+declare class MandatoHttpClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    private readonly maxRetries;
+    constructor(config: MandatoConfig);
+    /** Make a GET request */
+    get<T>(path: string, params?: Record<string, string | number | undefined>): Promise<T>;
+    /** Make a POST request */
+    post<T>(path: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
+    /** Make a PATCH request */
+    patch<T>(path: string, body?: unknown): Promise<T>;
+    /** Make a DELETE request */
+    delete<T>(path: string): Promise<T>;
+    /** Build full URL with optional query params */
+    private buildUrl;
+    /** Execute an HTTP request with retries and error mapping */
+    private request;
+    /** Safely parse error response body */
+    private parseErrorBody;
+}
+
+/**
+ * Mandato SDK types — standalone, zero workspace dependencies.
+ * These mirror the API response shapes.
+ */
+/** ISO 3166-1 alpha-2 country code */
+type CountryCode = "RO" | "IT" | "BE" | "PL" | "FR" | "DE";
+/** Invoice type */
+type InvoiceType = "invoice" | "credit_note" | "debit_note";
+/** Invoice lifecycle status */
+type InvoiceStatus = "created" | "validated" | "converting" | "submitting" | "submitted" | "accepted" | "rejected" | "error";
+/** Connection status */
+type ConnectionStatus = "pending_setup" | "active" | "expired" | "error";
+/** API key environment */
+type ApiKeyEnvironment = "test" | "production";
+/** Webhook event types */
+type WebhookEventType = "invoice.created" | "invoice.validated" | "invoice.submitted" | "invoice.accepted" | "invoice.rejected" | "invoice.error" | "connection.active" | "connection.expired";
+/** Address in a party (supplier/customer) */
+interface Address {
+    street?: string;
+    city?: string;
+    postalCode?: string;
+    country: string;
+    stateOrProvince?: string;
+}
+/** Invoice party (supplier or customer) */
+interface Party {
+    vatNumber: string;
+    name: string;
+    address?: Address;
+    email?: string;
+    phone?: string;
+    /** Italy SDI code (7 chars) */
+    sdiCode?: string;
+    /** Peppol participant ID */
+    peppolId?: string;
+    /** France SIRET (14 digits) */
+    siret?: string;
+    /** Germany Leitweg-ID */
+    leitwegId?: string;
+}
+/** Single invoice line item */
+interface InvoiceLine {
+    description: string;
+    quantity?: number;
+    unitPrice: number;
+    vatRate: number;
+    unitCode?: string;
+    discount?: number;
+    itemCode?: string;
+}
+/** Payment details */
+interface PaymentMeans {
+    bankAccount?: string;
+    bic?: string;
+    paymentTerms?: string;
+    dueDate?: string;
+}
+/** File attachment (base64-encoded) */
+interface Attachment {
+    filename: string;
+    content: string;
+    mimeType: string;
+}
+/** Request body for creating an invoice */
+interface CreateInvoiceRequest {
+    country: CountryCode;
+    invoiceType?: InvoiceType;
+    companyId?: string;
+    externalId?: string;
+    supplier: Party;
+    customer: Party;
+    lines: InvoiceLine[];
+    currency?: string;
+    issueDate?: string;
+    dueDate?: string;
+    note?: string;
+    paymentMeans?: PaymentMeans;
+    attachments?: Attachment[];
+}
+/** Request body for validating an invoice (dry-run) */
+type ValidateInvoiceRequest = CreateInvoiceRequest;
+/** Request body for creating a company */
+interface CreateCompanyRequest {
+    name: string;
+    vatNumber: string;
+    country: CountryCode;
+    registrationNumber?: string;
+    address?: Address;
+    currency?: string;
+    contacts?: {
+        email?: string;
+        phone?: string;
+    };
+}
+/** Request body for updating a company */
+interface UpdateCompanyRequest {
+    name?: string;
+    address?: Address;
+    currency?: string;
+    contacts?: {
+        email?: string;
+        phone?: string;
+    };
+}
+/** Request body for creating a connection */
+interface CreateConnectionRequest {
+    companyId: string;
+    countryCode: CountryCode;
+}
+/** Request body for registering a webhook */
+interface CreateWebhookRequest {
+    url: string;
+    events?: WebhookEventType[];
+}
+/** Request body for creating an API key */
+interface CreateApiKeyRequest {
+    name: string;
+    environment?: ApiKeyEnvironment;
+    expiresAt?: string;
+}
+/** Query parameters for listing invoices */
+interface ListInvoicesParams {
+    country?: CountryCode;
+    status?: InvoiceStatus;
+    companyId?: string;
+    search?: string;
+    dateFrom?: string;
+    dateTo?: string;
+    cursor?: string;
+    limit?: number;
+}
+/** Invoice object as returned by the API */
+interface Invoice {
+    id: string;
+    country: string;
+    supplierVat: string;
+    customerVat: string;
+    status: InvoiceStatus;
+    netAmount: string;
+    vatAmount: string;
+    grossAmount: string;
+    currency: string;
+    govId: string | null;
+    externalId: string | null;
+    errorMessage: string | null;
+    errorTranslated: string | null;
+    errorFix: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Invoice event in the timeline */
+interface InvoiceEvent {
+    id: string;
+    event: string;
+    status: string;
+    metadata: Record<string, unknown> | null;
+    createdAt: string;
+}
+/** Company object as returned by the API */
+interface Company {
+    id: string;
+    name: string;
+    vatNumber: string;
+    country: string;
+    currency: string;
+    isActive: boolean;
+    createdAt: string;
+}
+/** Connection object as returned by the API */
+interface Connection {
+    id: string;
+    companyId: string;
+    countryCode: string;
+    status: ConnectionStatus;
+    tokenExpiresAt: string | null;
+    lastErrorMessage: string | null;
+    createdAt: string;
+    /** OAuth URL to redirect user (returned on creation for RO) */
+    authorizationUrl?: string;
+}
+/** API key object as returned by the API (masked) */
+interface ApiKey {
+    id: string;
+    name: string;
+    keyPrefix: string;
+    environment: ApiKeyEnvironment;
+    lastUsedAt: string | null;
+    expiresAt: string | null;
+    revokedAt: string | null;
+    createdAt: string;
+}
+/** API key creation response (full key shown once) */
+interface ApiKeyCreated {
+    id: string;
+    key: string;
+    keyPrefix: string;
+    name: string;
+    environment: ApiKeyEnvironment;
+    expiresAt: string | null;
+    createdAt: string;
+}
+/** Webhook configuration object */
+interface WebhookConfig {
+    url: string | null;
+    secret: string | null;
+    events: WebhookEventType[] | null;
+}
+/** Webhook creation response (secret shown once) */
+interface WebhookCreated {
+    url: string;
+    secret: string;
+    events: WebhookEventType[];
+}
+/** Validation result */
+interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+/** Health check response */
+interface HealthStatus {
+    status: "ok" | "degraded";
+    timestamp: string;
+    checks: {
+        database: string;
+        redis: string;
+    };
+}
+/** Paginated response wrapper */
+interface PaginatedResponse<T> {
+    data: T[];
+    hasMore: boolean;
+    nextCursor: string | null;
+}
+/** Single item response wrapper */
+interface SingleResponse<T> {
+    data: T;
+}
+/** Deletion confirmation */
+interface DeletedResponse {
+    data: {
+        id: string;
+        deleted: boolean;
+    };
+}
+
+/** API key resource operations */
+declare class ApiKeys {
+    private readonly http;
+    constructor(http: MandatoHttpClient);
+    /** List API keys (masked) */
+    list(): Promise<SingleResponse<ApiKey[]>>;
+    /** Create a new API key (full key returned once) */
+    create(data: CreateApiKeyRequest): Promise<SingleResponse<ApiKeyCreated>>;
+    /** Revoke an API key */
+    revoke(id: string): Promise<SingleResponse<{
+        id: string;
+        revoked: boolean;
+    }>>;
+}
+
+/** Company resource operations */
+declare class Companies {
+    private readonly http;
+    constructor(http: MandatoHttpClient);
+    /** Create a company */
+    create(data: CreateCompanyRequest): Promise<SingleResponse<Company>>;
+    /** List all companies */
+    list(): Promise<SingleResponse<Company[]>>;
+    /** Get a single company by ID */
+    get(id: string): Promise<SingleResponse<Company>>;
+    /** Update a company */
+    update(id: string, data: UpdateCompanyRequest): Promise<SingleResponse<Company>>;
+    /** Delete a company */
+    delete(id: string): Promise<DeletedResponse>;
+}
+
+/** Connection resource operations */
+declare class Connections {
+    private readonly http;
+    constructor(http: MandatoHttpClient);
+    /** Initialize a government connection */
+    create(data: CreateConnectionRequest): Promise<SingleResponse<Connection>>;
+    /** List all connections */
+    list(): Promise<SingleResponse<Connection[]>>;
+    /** Get a single connection by ID */
+    get(id: string): Promise<SingleResponse<Connection>>;
+    /** Remove a connection */
+    delete(id: string): Promise<DeletedResponse>;
+}
+
+/** Invoice resource operations */
+declare class Invoices {
+    private readonly http;
+    constructor(http: MandatoHttpClient);
+    /** Create and submit an invoice */
+    create(data: CreateInvoiceRequest, idempotencyKey?: string): Promise<SingleResponse<Invoice>>;
+    /** List invoices with optional filters */
+    list(params?: ListInvoicesParams): Promise<PaginatedResponse<Invoice>>;
+    /** Get a single invoice by ID */
+    get(id: string): Promise<SingleResponse<Invoice>>;
+    /** Dry-run validation without submission */
+    validate(data: ValidateInvoiceRequest): Promise<ValidationResult>;
+    /** Get invoice event timeline */
+    getEvents(id: string): Promise<SingleResponse<InvoiceEvent[]>>;
+}
+
+/** Webhook resource operations */
+declare class Webhooks {
+    private readonly http;
+    constructor(http: MandatoHttpClient);
+    /** Register a webhook URL */
+    create(data: CreateWebhookRequest): Promise<SingleResponse<WebhookCreated>>;
+    /** Get current webhook configuration */
+    get(): Promise<SingleResponse<WebhookConfig>>;
+    /** Remove webhook */
+    delete(): Promise<SingleResponse<{
+        deleted: boolean;
+    }>>;
+}
+
+/**
+ * Main Mandato SDK client.
+ * Composes all resource namespaces for a clean, typed API.
+ */
+
+/**
+ * The Mandato SDK client.
+ *
+ * @example
+ * ```typescript
+ * import { MandatoClient } from "@getmandato/sdk";
+ *
+ * const mandato = new MandatoClient({ apiKey: "sk_live_xxx" });
+ *
+ * const { data: invoice } = await mandato.invoices.create({
+ *   country: "RO",
+ *   supplier: { vatNumber: "RO12345678", name: "Supplier SRL" },
+ *   customer: { vatNumber: "RO87654321", name: "Customer SRL" },
+ *   lines: [{ description: "Consulting", unitPrice: 100, vatRate: 19 }],
+ * });
+ * ```
+ */
+declare class MandatoClient {
+    /** Invoice operations */
+    readonly invoices: Invoices;
+    /** Company operations */
+    readonly companies: Companies;
+    /** Connection operations */
+    readonly connections: Connections;
+    /** Webhook operations */
+    readonly webhooks: Webhooks;
+    /** API key operations */
+    readonly apiKeys: ApiKeys;
+    private readonly http;
+    constructor(config: MandatoConfig);
+    /** Check API health */
+    health(): Promise<HealthStatus>;
+}
+
+/**
+ * Mandato SDK error classes.
+ * Map HTTP status codes to typed errors for developer-friendly handling.
+ */
+/** Base error for all Mandato API errors */
+declare class MandatoError extends Error {
+    /** HTTP status code */
+    readonly status: number;
+    /** Error type from the API response */
+    readonly type: string;
+    /** Request ID for support reference */
+    readonly requestId?: string;
+    constructor(message: string, status: number, type: string, requestId?: string);
+}
+/** 400 — Request validation failed */
+declare class ValidationError extends MandatoError {
+    readonly details: Array<{
+        path: string;
+        message: string;
+    }>;
+    constructor(message: string, details?: Array<{
+        path: string;
+        message: string;
+    }>, requestId?: string);
+}
+/** 401 — Invalid or missing API key */
+declare class AuthenticationError extends MandatoError {
+    constructor(message?: string, requestId?: string);
+}
+/** 403 — Insufficient permissions or plan limit */
+declare class ForbiddenError extends MandatoError {
+    constructor(message?: string, requestId?: string);
+}
+/** 404 — Resource not found */
+declare class NotFoundError extends MandatoError {
+    constructor(message?: string, requestId?: string);
+}
+/** 409 — Idempotency conflict */
+declare class ConflictError extends MandatoError {
+    constructor(message?: string, requestId?: string);
+}
+/** 429 — Rate limit exceeded */
+declare class RateLimitError extends MandatoError {
+    /** Requests per minute allowed */
+    readonly limit?: number;
+    /** Seconds until the rate limit resets */
+    readonly retryAfter?: number;
+    constructor(message: string, limit?: number, retryAfter?: number, requestId?: string);
+}
+/** 500+ — Server-side error */
+declare class ServerError extends MandatoError {
+    constructor(message?: string, status?: number, requestId?: string);
+}
+
+/**
+ * Webhook signature verification and event construction.
+ * Uses HMAC-SHA256 with timing-safe comparison.
+ */
+/** Webhook event payload as delivered by Mandato */
+interface WebhookEvent {
+    id: string;
+    type: string;
+    createdAt: string;
+    data: Record<string, unknown>;
+}
+/**
+ * Verify a webhook signature against the payload.
+ * Uses HMAC-SHA256 with timing-safe comparison to prevent timing attacks.
+ *
+ * @param payload — raw request body string
+ * @param signature — value of the X-Mandato-Signature header
+ * @param secret — webhook signing secret from the dashboard
+ * @returns true if the signature is valid
+ */
+declare function verifyWebhookSignature(payload: string, signature: string, secret: string): boolean;
+/**
+ * Verify the webhook signature and parse the event payload.
+ * Throws if the signature is invalid.
+ *
+ * @param payload — raw request body string
+ * @param signature — value of the X-Mandato-Signature header
+ * @param secret — webhook signing secret from the dashboard
+ * @returns parsed WebhookEvent
+ */
+declare function constructWebhookEvent(payload: string, signature: string, secret: string): WebhookEvent;
+
+export { type Address, type ApiKey, type ApiKeyCreated, type ApiKeyEnvironment, type Attachment, AuthenticationError, type Company, ConflictError, type Connection, type ConnectionStatus, type CountryCode, type CreateApiKeyRequest, type CreateCompanyRequest, type CreateConnectionRequest, type CreateInvoiceRequest, type CreateWebhookRequest, type DeletedResponse, ForbiddenError, type HealthStatus, type Invoice, type InvoiceEvent, type InvoiceLine, type InvoiceStatus, type InvoiceType, type ListInvoicesParams, MandatoClient, type MandatoConfig, MandatoError, MandatoHttpClient, NotFoundError, type PaginatedResponse, type Party, type PaymentMeans, RateLimitError, ServerError, type SingleResponse, type UpdateCompanyRequest, type ValidateInvoiceRequest, ValidationError, type ValidationResult, type WebhookConfig, type WebhookCreated, type WebhookEvent, type WebhookEventType, constructWebhookEvent, verifyWebhookSignature };