@zeniai/client-epic-state 5.1.26 → 5.1.27-betaAK0

package/lib/entity/invoicing/invoicingTypes.d.ts

@@ -0,0 +1,766 @@
+/**
+ * Domain payload types for the Invoicing (Accounts Receivable) module.
+ *
+ * These mirror the snake_case shapes returned by the Invoicing backend
+ * microservice (reachable at `apiEndPoints.invoicingMicroServiceBaseUrl`,
+ * keeping the same `/1.0/*` paths and `ZeniAPIResponse` envelope as the rest of
+ * the platform). The Invoicing UI in `@zeniai/web-components` was authored
+ * against these shapes, so we keep them as the canonical domain types rather
+ * than remapping to camelCase, which keeps the ported pages drop-in compatible.
+ *
+ * These were migrated from the standalone Invoicing service's API contract and
+ * are now owned here; nothing references the original standalone frontend.
+ */
+export interface InvoicingBillingAddress {
+    city?: string;
+    company?: string;
+    country?: string;
+    email?: string;
+    first_name?: string;
+    last_name?: string;
+    line1?: string;
+    line2?: string;
+    phone?: string;
+    state_code?: string;
+    validation_status?: 'not_validated' | 'valid' | 'partially_valid' | 'invalid';
+    zip?: string;
+}
+export type InvoicingInvoiceStatus = 'paid' | 'partially_paid' | 'posted' | 'payment_due' | 'not_paid' | 'voided' | 'pending' | 'draft';
+export interface InvoicingLineItem {
+    amount: number;
+    description: string;
+    quantity: number;
+    unit_amount: number;
+    date_from?: string;
+    date_to?: string;
+    discount_amount?: number;
+    entity_description?: string;
+    entity_type?: string;
+    id?: string;
+    is_taxed?: boolean;
+    item_level_discount_amount?: number;
+    subscription_id?: string;
+    tax_amount?: number;
+    tax_exempt_reason?: string;
+    tax_rate?: number;
+    usage_percentage?: number;
+}
+export interface InvoicingLinkedPayment {
+    applied_amount: number;
+    txn_id: string;
+    applied_at?: string;
+    txn_amount?: number;
+    txn_date?: string;
+    txn_status?: string;
+}
+export interface InvoicingIssuedCreditNote {
+    cn_id: string;
+    cn_status: string;
+    cn_total: number;
+}
+export type InvoicingPriceType = 'tax_exclusive' | 'tax_inclusive';
+export interface InvoicingDunningAttempt {
+    attempt: number;
+    created_at?: string;
+    dunning_type?: string;
+    transaction_id?: string;
+}
+export interface InvoicingInvoiceNote {
+    note: string;
+    entity_id?: string;
+    entity_type?: string;
+}
+export interface InvoicingInvoice {
+    customer_id: string;
+    date: string;
+    id: string;
+    status: InvoicingInvoiceStatus;
+    total: number;
+    adjustment_credit_notes?: string[];
+    amount_adjusted?: number;
+    amount_due?: number;
+    amount_paid?: number;
+    amount_to_collect?: number;
+    billing_address?: InvoicingBillingAddress;
+    created_at?: string;
+    credits_applied?: number;
+    currency_code?: string;
+    customer_email?: string;
+    customer_name?: string;
+    due_date?: string;
+    dunning_attempts?: InvoicingDunningAttempt[];
+    dunning_status?: string;
+    first_invoice?: boolean;
+    generated_at?: string;
+    has_advance_charges?: boolean;
+    issued_credit_notes?: InvoicingIssuedCreditNote[];
+    line_items?: InvoicingLineItem[];
+    linked_payments?: InvoicingLinkedPayment[];
+    net_term_days?: number;
+    next_retry_at?: string;
+    notes?: InvoicingInvoiceNote[];
+    paid_at?: string;
+    po_number?: string;
+    price_type?: InvoicingPriceType;
+    recurring?: boolean;
+    round_off_amount?: number;
+    shipping_address?: InvoicingBillingAddress;
+    sub_total?: number;
+    subscription_id?: string;
+    subscription_name?: string;
+    tax?: number;
+    updated_at?: string;
+    write_off_amount?: number;
+}
+export interface InvoicingInvoiceKPIs {
+    due_total: number;
+    paid_total: number;
+    pending_total: number;
+    total_invoiced: number;
+}
+/** Status -> count map for list tab badges; always includes an `all` total. */
+export type InvoicingListCounts = Record<string, number> & {
+    all: number;
+};
+/** Cursor-paginated list envelope returned by Invoicing list endpoints. */
+export interface InvoicingPaginatedList<T> {
+    items: T[];
+    next_cursor: string | null;
+}
+export interface InvoicingCustomer {
+    id: string;
+    allow_direct_debit?: boolean;
+    arr?: number;
+    auto_collection?: 'on' | 'off';
+    billing_address?: InvoicingBillingAddress;
+    card_status?: 'no_card' | 'valid' | 'expiring' | 'expired';
+    company?: string;
+    consolidated_invoicing?: boolean;
+    created_at?: string;
+    customer_type?: 'residential' | 'business';
+    default_payment_method_id?: string;
+    email?: string;
+    excess_payments?: number;
+    first_name?: string;
+    fraud_flag?: 'safe' | 'suspicious' | 'fraudulent';
+    initials?: string;
+    invoice_notes?: string;
+    is_at_risk?: boolean;
+    last_name?: string;
+    lifetime_value?: number;
+    locale?: string;
+    mrr?: number;
+    net_term_days?: number;
+    payment_method?: string;
+    payment_method_last4?: string;
+    payment_method_type?: 'ach' | 'card' | 'none';
+    phone?: string;
+    plan?: string;
+    plan_name?: string;
+    preferred_currency_code?: string;
+    promotional_credits?: number;
+    refundable_credits?: number;
+    status?: string;
+    stripe_customer_id?: string;
+    subscriptions?: InvoicingSubscription[];
+    taxability?: 'taxable' | 'exempt';
+    total_receivable?: number;
+    unbilled_charges?: number;
+    updated_at?: string;
+    vat_number?: string;
+}
+export interface InvoicingCustomerCounts extends InvoicingListCounts {
+    active: number;
+    at_risk: number;
+    churned: number;
+    not_churned: number;
+    total: number;
+    trial: number;
+}
+export type InvoicingSubscriptionStatus = 'active' | 'in_trial' | 'future' | 'non_renewing' | 'paused' | 'cancelled';
+export type InvoicingBillingPeriodUnit = 'day' | 'week' | 'month' | 'year';
+export interface InvoicingSubscriptionItem {
+    amount?: number;
+    billing_cycles?: number;
+    catalog_item_id?: string;
+    item_name?: string;
+    item_price_id?: string;
+    item_type?: string;
+    quantity?: number;
+    unit_price?: number;
+}
+export interface InvoicingSubscriptionCoupon {
+    coupon_id: string;
+    applied_count?: number;
+    apply_till?: string;
+    coupon_code?: string;
+}
+export interface InvoicingContractTerm {
+    id: string;
+    action_at_term_end?: string;
+    auto_renew?: boolean;
+    billing_cycle?: number;
+    cancellation_notice_days?: number;
+    contract_end?: string;
+    contract_start?: string;
+    status?: string;
+    total_contract_value?: number;
+}
+export interface InvoicingSubscription {
+    customer_id: string;
+    id: string;
+    status: InvoicingSubscriptionStatus;
+    activated_at?: string;
+    auto_collection?: 'on' | 'off';
+    auto_collection_count?: number;
+    billing_period?: number;
+    billing_period_unit?: InvoicingBillingPeriodUnit;
+    cancel_reason?: string;
+    cancelled_at?: string;
+    catalog_item_id?: string;
+    contract_term?: InvoicingContractTerm;
+    coupons?: InvoicingSubscriptionCoupon[];
+    created_at?: string;
+    currency_code?: string;
+    current_term_end?: string;
+    current_term_start?: string;
+    customer_name?: string;
+    due_invoices_count?: number;
+    due_since?: string;
+    has_scheduled_changes?: boolean;
+    mrr?: number;
+    next_billing_at?: string;
+    pause_date?: string;
+    plan_amount?: number;
+    plan_id?: string;
+    plan_name?: string;
+    po_number?: string;
+    remaining_billing_cycles?: number;
+    resume_date?: string;
+    setup_fee?: number;
+    shipping_address?: InvoicingBillingAddress;
+    started_at?: string;
+    subscription_items?: InvoicingSubscriptionItem[];
+    total_dues?: number;
+    trial_end?: string;
+    trial_start?: string;
+    updated_at?: string;
+}
+export type InvoicingTransactionType = 'payment' | 'refund' | 'authorization' | 'payment_reversal';
+export type InvoicingTransactionStatus = 'in_progress' | 'success' | 'voided' | 'failure' | 'timeout' | 'needs_attention' | 'late_failure' | 'failed';
+export interface InvoicingLinkedInvoiceRef {
+    applied_amount: number;
+    invoice_id: string;
+    invoice_status?: string;
+}
+export interface InvoicingLinkedRefund {
+    txn_amount: number;
+    txn_id: string;
+    txn_status: string;
+}
+export interface InvoicingLinkedCreditNoteRef {
+    applied_amount: number;
+    cn_id: string;
+}
+export interface InvoicingTransaction {
+    amount: number;
+    id: string;
+    amount_capturable?: number;
+    amount_unused?: number;
+    currency_code?: string;
+    customer?: string;
+    customer_id?: string;
+    customer_name?: string;
+    date?: string;
+    error_code?: string;
+    error_text?: string;
+    fraud_flag?: string;
+    fraud_reason?: string;
+    gateway?: string;
+    gateway_account_id?: string;
+    id_at_gateway?: string;
+    invoice_id?: string;
+    linked_credit_notes?: InvoicingLinkedCreditNoteRef[];
+    linked_invoices?: InvoicingLinkedInvoiceRef[];
+    linked_refunds?: InvoicingLinkedRefund[];
+    masked_card_number?: string;
+    payment_method?: string;
+    payment_source_id?: string;
+    reference_number?: string;
+    refunded_txn_id?: string;
+    settled_at?: string;
+    status?: InvoicingTransactionStatus;
+    subscription_id?: string;
+    three_d_secure?: boolean;
+    type?: InvoicingTransactionType;
+}
+export interface InvoicingPaymentKPIs {
+    net_revenue: number;
+    total_collected: number;
+    total_failed: number;
+    total_refunds: number;
+}
+export type InvoicingCreditNoteStatus = 'adjusted' | 'refunded' | 'refund_due' | 'voided' | 'open' | 'closed' | 'partially_used';
+export type InvoicingCreditNoteType = 'adjustment' | 'refundable' | 'store' | 'referral';
+export interface InvoicingCreditNoteLineItem {
+    amount: number;
+    description: string;
+    quantity: number;
+    unit_amount: number;
+    entity_type?: string;
+    id?: string;
+}
+export interface InvoicingCreditNoteAllocation {
+    allocated_amount: number;
+    invoice_id: string;
+    allocated_at?: string;
+}
+export interface InvoicingCreditNote {
+    id: string;
+    allocations?: InvoicingCreditNoteAllocation[];
+    amount_allocated?: number;
+    amount_available?: number;
+    amount_refunded?: number;
+    create_reason_code?: string;
+    created_at?: string;
+    credit_note_number?: string;
+    currency_code?: string;
+    customer_id?: string;
+    customer_name?: string;
+    date?: string;
+    line_items?: InvoicingCreditNoteLineItem[];
+    linked_refunds?: string[];
+    notes?: string;
+    price_type?: InvoicingPriceType;
+    reason_code?: string;
+    reference_invoice_id?: string;
+    status?: InvoicingCreditNoteStatus;
+    sub_total?: number;
+    subscription_id?: string;
+    total?: number;
+    type?: InvoicingCreditNoteType;
+}
+export interface InvoicingCreditKPIs {
+    total_allocated: number;
+    total_available: number;
+    total_open: number;
+    total_refunded: number;
+}
+export type InvoicingDiscountType = 'percentage' | 'fixed_amount' | 'offer_quantity';
+export type InvoicingCouponDurationType = 'one_time' | 'forever' | 'limited_period';
+export type InvoicingCouponStatus = 'active' | 'expired' | 'archived';
+export interface InvoicingCoupon {
+    id: string;
+    apply_on?: string;
+    coupon_code?: string;
+    created_at?: string;
+    currency_code?: string;
+    discount_amount?: number;
+    discount_percentage?: number;
+    discount_quantity?: number;
+    discount_type?: InvoicingDiscountType;
+    duration_type?: InvoicingCouponDurationType;
+    invoice_name?: string;
+    invoice_notes?: string;
+    item_constraints?: Record<string, unknown>[];
+    max_redemptions?: number;
+    name?: string;
+    period?: number;
+    period_unit?: string;
+    redemptions?: number;
+    restricted_products?: string[];
+    rev_rec_treatment?: string;
+    status?: InvoicingCouponStatus;
+    updated_at?: string;
+    valid_from?: string;
+    valid_till?: string;
+}
+export interface InvoicingCouponCode {
+    code: string;
+    coupon_id?: string;
+    coupon_set_id?: string;
+    status?: string;
+}
+export interface InvoicingCouponSet {
+    id: string;
+    archived_count?: number;
+    codes?: InvoicingCouponCode[];
+    coupon_id?: string;
+    name?: string;
+    redeemed_count?: number;
+    total_count?: number;
+}
+export interface InvoicingDiscountKPIs {
+    total_active: number;
+    total_discounted_amount: number;
+    total_expired: number;
+    total_redemptions: number;
+}
+export type InvoicingDunningStatus = 'Retrying' | 'Scheduled' | 'Manual Review' | 'Resolved' | 'Cancelled' | 'Paused';
+export interface InvoicingDunningCase {
+    id: string;
+    status: InvoicingDunningStatus;
+    amount?: number;
+    attempts?: number;
+    created_at?: string;
+    currency_code?: string;
+    customer?: string;
+    customer_email?: string;
+    customer_id?: string;
+    days_past_due?: number;
+    failure_reason?: string;
+    initials?: string;
+    invoice_id?: string;
+    last_attempt?: string;
+    max_attempts?: number;
+    next_retry?: string;
+    paused_reason?: string;
+    paused_until?: string;
+    subscription_id?: string;
+}
+export interface InvoicingDunningKPIs {
+    active_cases: number;
+    at_risk_amount: number;
+    recovery_rate: number;
+    total_cases: number;
+    avg_days_to_resolve?: number | null;
+}
+export interface InvoicingPlanTier {
+    price: number;
+    starting_unit: number;
+    ending_unit?: number;
+    package_size?: number;
+    pricing_type?: string;
+}
+export interface InvoicingAccountingDetail {
+    accounting_category_1?: string;
+    accounting_category_2?: string;
+    accounting_category_3?: string;
+    accounting_category_4?: string;
+    accounting_code?: string;
+    sku?: string;
+}
+export interface InvoicingPlan {
+    id: string;
+    applicable_items?: string[];
+    archived_at?: string;
+    billing_cycles?: number;
+    created_at?: string;
+    currency_code?: string;
+    description?: string;
+    enabled_for_checkout?: boolean;
+    enabled_in_portal?: boolean;
+    external_name?: string;
+    gift_claim_redirect_url?: string;
+    included_in_mrr?: boolean;
+    is_giftable?: boolean;
+    is_shippable?: boolean;
+    item_applicability?: string;
+    item_family_id?: string;
+    item_type?: string;
+    metadata?: Record<string, unknown>;
+    metered?: boolean;
+    name?: string;
+    period?: number;
+    period_unit?: string;
+    price?: number;
+    prices?: InvoicingProduct[];
+    status?: string;
+    tiers?: InvoicingPlanTier[];
+    trial_period?: number;
+    trial_period_unit?: string;
+    type?: string;
+    unit?: string;
+    updated_at?: string;
+    usage_calculation?: string;
+}
+export interface InvoicingProduct {
+    id: string;
+    accounting_detail?: InvoicingAccountingDetail;
+    applicable_items?: string[];
+    archived_at?: string;
+    billing_cycles?: number;
+    created_at?: string;
+    currency_code?: string;
+    description?: string;
+    enabled?: boolean;
+    enabled_for_checkout?: boolean;
+    enabled_in_portal?: boolean;
+    external_name?: string;
+    free_quantity?: number;
+    gift_claim_redirect_url?: string;
+    included_in_mrr?: boolean;
+    invoice_notes?: string;
+    is_giftable?: boolean;
+    is_shippable?: boolean;
+    is_taxable?: boolean;
+    item_applicability?: string;
+    item_id?: string;
+    item_type?: string;
+    metered?: boolean;
+    name?: string;
+    period?: number;
+    period_unit?: string;
+    price?: number;
+    pricing_model?: string;
+    proration_type?: string;
+    shipping_period?: number;
+    shipping_period_unit?: string;
+    show_description_in_invoices?: boolean;
+    show_description_in_quotes?: boolean;
+    status?: string;
+    tiers?: InvoicingPlanTier[];
+    trial_end_action?: string;
+    trial_period?: number;
+    trial_period_unit?: string;
+    type?: string;
+    unit?: string;
+    updated_at?: string;
+    usage_accumulation_reset_frequency?: string;
+    usage_calculation?: string;
+}
+export interface InvoicingCatalogKPIs {
+    active_plans: number;
+    active_products: number;
+    avg_plan_price: number;
+    total_mrr: number;
+}
+export interface InvoicingSettings {
+    accent_color?: string;
+    address?: string;
+    address_enabled?: boolean;
+    auto_collection?: 'on' | 'off';
+    chargebee_connected?: boolean;
+    chargebee_site?: string;
+    company_name?: string;
+    currency?: string;
+    currency_code?: string;
+    date_format?: string;
+    default_memo?: string;
+    dunning_max_attempts?: number;
+    dunning_retry_interval?: number;
+    email?: string;
+    id?: string;
+    invoice_prefix?: string;
+    logo_url?: string;
+    net_term_days?: number;
+    payment_terms?: string;
+    phone?: string;
+    phone_enabled?: boolean;
+    show_service_periods?: boolean;
+    show_tax_id?: boolean;
+    stripe_connected_account_id?: string;
+    stripe_publishable_key?: string;
+    tax_enabled?: boolean;
+    tax_id?: string;
+    tax_rate?: number;
+    timezone?: string;
+    [key: string]: unknown;
+}
+export interface InvoicingAnalyticsKPIs {
+    active_customers: number;
+    active_subscriptions: number;
+    arr: number;
+    churn_rate: number;
+    mrr: number;
+    ltv?: number;
+    net_revenue_retention?: number;
+}
+export interface InvoicingRevenueDataPoint {
+    month: string;
+    revenue: number;
+    arr?: number;
+}
+export interface InvoicingMRRDataPoint {
+    month: string;
+    mrr: number;
+    churned?: number;
+    expansion?: number;
+    month_num?: number;
+    net?: number;
+    new?: number;
+    start_mrr?: number;
+    year?: number;
+}
+export interface InvoicingChurnDataPoint {
+    month: string;
+    rate: number;
+    churned?: number;
+    subscribers?: number;
+}
+export interface InvoicingPlanRevenuePoint {
+    mrr: number;
+    pct: number;
+    plan: string;
+}
+export interface InvoicingAuditEntry {
+    action: string;
+    target: string;
+    time: string;
+    actor?: string;
+    entity_id?: string;
+    entity_type?: string;
+    id?: string;
+    meta?: string;
+    timestamp?: string;
+}
+export interface InvoicingDashboardSummary {
+    customer_movement: {
+        churned: number;
+        net_change: number;
+        new: number;
+        paused: number;
+        reactivated: number;
+        resumed: number;
+        total_active: number;
+        total_active_value: number;
+    };
+    failed_payments: {
+        amount: number;
+        count: number;
+    };
+    grr: {
+        churn: number;
+        contraction: number;
+        grr: number;
+        retained_arr: number;
+        starting_arr: number;
+    };
+    mrr_movement: {
+        churned: number;
+        expansions: number;
+        net_change: number;
+        new_subscriptions: number;
+    };
+    nrr: {
+        churn: number;
+        contraction: number;
+        ending_arr: number;
+        expansion_arr: number;
+        nrr: number;
+        starting_arr: number;
+    };
+    outstanding: number;
+    past_due_invoices: {
+        amount: number;
+        count: number;
+    };
+    upcoming_invoices: {
+        amount: number;
+        count: number;
+    };
+    /** Period-over-period change in outstanding balance, e.g. -6.7. */
+    outstanding_change_pct?: number;
+}
+export type InvoicingApprovalStatus = 'approved' | 'denied' | 'pending';
+export interface InvoicingApprovalItem {
+    id: string;
+    amount?: number;
+    created_at?: string;
+    notes?: string;
+    requester?: string;
+    status?: InvoicingApprovalStatus;
+    target?: string;
+    type?: string;
+}
+export interface InvoicingAgingBuckets {
+    '90_plus': InvoicingInvoice[];
+    '1_30': InvoicingInvoice[];
+    '31_60': InvoicingInvoice[];
+    '61_90': InvoicingInvoice[];
+    current: InvoicingInvoice[];
+}
+export interface InvoicingAgingReportSummary {
+    '90_plus': number;
+    '1_30': number;
+    '31_60': number;
+    '61_90': number;
+    current: number;
+    total: number;
+}
+export interface InvoicingAgingReport {
+    buckets: InvoicingAgingBuckets;
+    summary: InvoicingAgingReportSummary;
+}
+export interface InvoicingCustomerMovementRow {
+    churned: number;
+    ending: number;
+    month: string;
+    new: number;
+    paused: number;
+    reactivated: number;
+    resumed: number;
+    starting: number;
+}
+export type InvoicingCustomerMovementReport = InvoicingCustomerMovementRow[];
+export interface InvoicingDeferredRevenueScheduleRow {
+    adjustments: string;
+    closing: string;
+    opening: string;
+    period: string;
+    recognized: string;
+}
+export interface InvoicingDeferredRevenueObligationRow {
+    pct: number;
+    product: string;
+    recognized: string;
+    remaining: string;
+    total: string;
+}
+export interface InvoicingDeferredRevenueKPIs {
+    avg_contract_duration: string;
+    recognition_rate: string;
+    recognized_this_month: string;
+    total_deferred: string;
+}
+export interface InvoicingDeferredRevenueReport {
+    kpis: InvoicingDeferredRevenueKPIs;
+    obligations: InvoicingDeferredRevenueObligationRow[];
+    schedule: InvoicingDeferredRevenueScheduleRow[];
+}
+export type InvoicingMigrationStatus = 'scanning' | 'review' | 'importing' | 'done' | 'failed' | 'rolled_back';
+export interface InvoicingMigrationIssue {
+    level: 'error' | 'warning';
+    message: string;
+    count?: number;
+}
+export interface InvoicingMigrationModuleSummary {
+    id: string;
+    imported: number;
+    issues: InvoicingMigrationIssue[];
+    label: string;
+    skipped: number;
+    state: 'pending' | 'scanning' | 'scanned' | 'importing' | 'imported';
+    total: number;
+    warnings: number;
+}
+export interface InvoicingMigrationSummary {
+    imported: number;
+    skipped: number;
+    total_records: number;
+    warnings: number;
+}
+export interface InvoicingMigrationSession {
+    created_at: string;
+    id: string;
+    modules: InvoicingMigrationModuleSummary[];
+    site: string;
+    source: 'chargebee_api' | 'csv_upload';
+    status: InvoicingMigrationStatus;
+    summary: InvoicingMigrationSummary;
+    updated_at: string;
+    catalog_version?: string;
+    /** Present only on the rollback response. */
+    deleted?: number;
+    error?: string | null;
+    rollback_available_until?: string | null;
+}
+export interface InvoicingDataImportStatusRow {
+    id: string;
+    last_imported: string | null;
+    module: string;
+    records: number;
+    source: string;
+    status: 'in_sync' | 'skipped' | 'warnings' | 'error' | 'pending';
+    status_count: number;
+}