export type JurisdictionType = 'state' | 'county' | 'city' | 'district';
export interface Address {
    /** 5-digit ZIP code (US). */
    zip5: string;
    /** Optional 4-digit ZIP+4 extension. */
    zip4?: string | null;
}
export interface LineItem {
    /** Pre-tax amount, non-negative, decimal string. e.g. `"100.00"`. */
    amount: string;
    /**
     * Tax category. One of the engine's six categories (`general`,
     * `clothing`, `groceries`, `prescription_drugs`, `prepared_food`,
     * `digital_goods`) or `""` to use the engine default. Defaults to
     * `"general"` on the wire if omitted client-side.
     */
    category?: string;
}
/**
 * Top-level shipping input on `POST /v1/calculate`. Sent under the
 * `shipping` key (NOT as a line item with `category: "shipping"` —
 * that's the legacy shim that pre-dates the engine's first-class
 * shipping support). Engine v0.59.0+ required; older engines silently
 * ignore the field.
 *
 * The engine applies per-state shipping-taxability rules internally
 * (MN's "tax-if-items-taxable" rule, MO/VA's "separately-stated"
 * rule, MD's shipping-vs-handling distinction, etc.). Connectors
 * just pass the amount and optional flags; the engine decides
 * whether to tax it and at what rate.
 */
export interface ShippingInput {
    /** Pre-tax shipping amount, non-negative, decimal string. e.g. `"12.50"`. */
    amount: string;
    /**
     * Free-form shipping-method label (e.g. `"ups_ground"`, `"usps_priority"`).
     * Sent to the engine for analytics / audit purposes only. Does not
     * affect tax calculation. Defaults to `null` (omitted) if not set.
     */
    method?: string | null;
    /**
     * Whether the shipping charge is shown as a separate line on the
     * invoice (vs. baked into product prices). Relevant in MO and VA
     * where shipping is only taxable if NOT separately stated. Defaults
     * to `true` — the common e-commerce case where carts show a
     * dedicated "Shipping" line.
     */
    separatelyStated?: boolean;
    /**
     * Whether this charge is a handling fee (vs. shipping). Some
     * states (notably MD) distinguish: shipping exempt, handling
     * taxable, "shipping and handling" combined fully taxable.
     * Defaults to `false`.
     */
    isHandlingCharge?: boolean;
}
export interface JurisdictionRate {
    name: string;
    /**
     * Jurisdiction type. Canonical values are `state` / `county` / `city`
     * / `district` (see `JurisdictionType`); the engine reserves the right
     * to emit other strings in future, hence the open `string` type here.
     */
    type: string;
    /** Rate as a percent decimal string. e.g. `"6.87500"` means 6.875%. */
    ratePct: string;
    /** Dollar contribution on /v1/calculate; `null` on /v1/rates. */
    tax: string | null;
}
export interface HealthResponse {
    status: string;
    version: string;
    databaseConnected: boolean;
}
export interface StateCoverage {
    /** USPS abbreviation, e.g. `"MN"`. */
    abbrev: string;
    name: string;
    hasSalesTax: boolean;
    sstMember: boolean;
    /** 0 = unsupported, 1 = fully maintained, 2 = rate-only via SST data. */
    tier: number;
    notes: string;
}
export interface StatesResponse {
    states: StateCoverage[];
    total: number;
}
export interface RateStack {
    input: {
        zip5: string;
        zip4: string | null;
    };
    jurisdictions: JurisdictionRate[];
    /** Combined percent across all jurisdictions, decimal string. */
    combinedRatePct: string;
    disclaimer: string;
}
export interface CapabilityEndpoint {
    path: string;
    version: number;
}
/**
 * Feature flags returned by the engine on `GET /v1/capabilities`.
 *
 * Known flags as of engine v0.59.0:
 *
 * - `coverageWarning` — engine emits a coverage-warning when a calc
 *   request hits a jurisdiction with incomplete rate data.
 * - `shippingFirstClass` — engine accepts the top-level `shipping`
 *   field on `POST /v1/calculate` (vs. the legacy
 *   `category: "shipping"` line-item shim).
 * - `vendorAllocation` — engine accepts per-line `vendor_id` and
 *   returns per-vendor allocation in the response. As of v0.59.0
 *   this is `false`; engine team has indicated it's permanently
 *   out of scope.
 * - `transactionRecordBack` — engine exposes
 *   `POST /v1/transactions` for committed-sale record-back. As of
 *   v0.59.0 this is `false`; engine team has positioned the engine
 *   as calculation-only.
 *
 * Additional flags emitted by future engine versions will appear in
 * `extras` (preserved verbatim) so connectors can flag-gate new
 * functionality without an SDK bump.
 */
export interface CapabilityFeatures {
    coverageWarning: boolean;
    shippingFirstClass: boolean;
    vendorAllocation: boolean;
    transactionRecordBack: boolean;
    /** Any feature flags not in the typed set above; preserved verbatim from the engine response. */
    extras: Record<string, boolean>;
}
export interface CapabilitiesResponse {
    /** Engine version string, e.g. `"0.59.0"`. */
    version: string;
    /** Map of logical endpoint name -> path + version metadata. */
    endpoints: Record<string, CapabilityEndpoint>;
    /** Feature flags; see {@link CapabilityFeatures}. */
    features: CapabilityFeatures;
}
export interface CalculatedLine {
    amount: string;
    category: string;
    tax: string;
    ratePct: string;
    jurisdictions: JurisdictionRate[];
    note: string | null;
}
/**
 * Calculated shipping segment in the `POST /v1/calculate` response.
 * Present when the request included a top-level `shipping` field
 * AND the engine supports first-class shipping (v0.59.0+).
 *
 * The engine returns this even when shipping ended up non-taxable
 * — `taxAmount` is `"0.00"` and `taxableReason` explains why
 * (e.g., "TX does not tax shipping when separately stated").
 */
export interface CalculatedShipping {
    /** Echoed shipping amount, decimal string. */
    amount: string;
    /** Tax due on shipping, decimal string. `"0.00"` when exempt. */
    taxAmount: string;
    /** Effective shipping tax rate (combined across jurisdictions), decimal string. */
    ratePct: string;
    /**
     * Engine's explanation of why shipping was / wasn't taxed in this
     * jurisdiction (e.g., "MN taxes shipping when items are taxable").
     * Useful for connector debug logs and merchant support. `null`
     * when engine omitted the field.
     */
    taxableReason?: string | null;
}
export interface CalculationResult {
    subtotal: string;
    taxTotal: string;
    lines: CalculatedLine[];
    disclaimer: string;
    /**
     * Calculated shipping. `null` when the request omitted the
     * top-level `shipping` field OR when the engine is older than
     * v0.59.0 and ignored it.
     */
    shipping: CalculatedShipping | null;
    /**
     * Coverage warning text emitted by engine v0.59.0+ when a calc
     * request hits a jurisdiction with incomplete rate data. `null`
     * when no warning was emitted.
     */
    coverageWarning?: string | null;
}
export declare function parseHealthResponse(raw: unknown): HealthResponse;
export declare function parseStatesResponse(raw: unknown): StatesResponse;
export declare function parseCapabilitiesResponse(raw: unknown): CapabilitiesResponse;
export declare function parseRateStack(raw: unknown): RateStack;
export declare function parseCalculationResult(raw: unknown): CalculationResult;
interface WireShippingBody {
    amount: string;
    method?: string;
    separately_stated?: boolean;
    is_handling_charge?: boolean;
}
interface WireCalculateBody {
    address: {
        zip5: string;
        zip4?: string;
    };
    line_items: {
        amount: string;
        category: string;
    }[];
    shipping?: WireShippingBody;
}
/**
 * Build the wire-format body for `POST /v1/calculate`. Translates the
 * camelCase consumer-facing types into the snake_case keys the engine
 * expects. When `shipping` is omitted the field is left out of the
 * body entirely (preserves backward compatibility with engine versions
 * <0.59.0 that don't know about the field).
 */
export declare function buildCalculateBody(address: Address, lineItems: LineItem[], shipping?: ShippingInput | null): WireCalculateBody;
export {};
//# sourceMappingURL=models.d.ts.map