/*
 * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
 */

import { invoicesAttemptInvoicePayment } from "../funcs/invoices-attempt-invoice-payment.js";
import { invoicesCreateInvoice } from "../funcs/invoices-create-invoice.js";
import { invoicesFinalizeInvoice } from "../funcs/invoices-finalize-invoice.js";
import { invoicesGetCustomerInvoiceSummary } from "../funcs/invoices-get-customer-invoice-summary.js";
import { invoicesGetInvoicePdf } from "../funcs/invoices-get-invoice-pdf.js";
import { invoicesGetInvoicePreview } from "../funcs/invoices-get-invoice-preview.js";
import { invoicesGetInvoice } from "../funcs/invoices-get-invoice.js";
import { invoicesQueryInvoice } from "../funcs/invoices-query-invoice.js";
import { invoicesRecalculateInvoiceV2 } from "../funcs/invoices-recalculate-invoice-v2.js";
import { invoicesRecalculateInvoice } from "../funcs/invoices-recalculate-invoice.js";
import { invoicesTriggerInvoiceCommsWebhook } from "../funcs/invoices-trigger-invoice-comms-webhook.js";
import { invoicesUpdateInvoicePaymentStatus } from "../funcs/invoices-update-invoice-payment-status.js";
import { invoicesUpdateInvoice } from "../funcs/invoices-update-invoice.js";
import { invoicesVoidInvoice } from "../funcs/invoices-void-invoice.js";
import { ClientSDK, RequestOptions } from "../lib/sdks.js";
import { unwrapAsync } from "../types/fp.js";
import * as models from "./models/index.js";

export class Invoices extends ClientSDK {
  /**
   * Get customer invoice summary
   *
   * @remarks
   * Use when showing a customer's invoice overview (e.g. billing portal or balance summary). Includes totals and multi-currency breakdown.
   */
  async getCustomerInvoiceSummary(
    id: string,
    options?: RequestOptions,
  ): Promise<models.CustomerMultiCurrencyInvoiceSummary> {
    return unwrapAsync(invoicesGetCustomerInvoiceSummary(
      this,
      id,
      options,
    ));
  }

  /**
   * Create one-off invoice
   *
   * @remarks
   * Use when creating a manual or one-off invoice (e.g. custom charge or non-recurring billing). Invoice is created in draft; finalize when ready.
   */
  async createInvoice(
    request: models.CreateInvoiceRequest,
    options?: RequestOptions,
  ): Promise<models.InvoiceResponse> {
    return unwrapAsync(invoicesCreateInvoice(
      this,
      request,
      options,
    ));
  }

  /**
   * Get invoice preview
   *
   * @remarks
   * Use when showing a customer what they will be charged (e.g. preview before checkout or plan change). No invoice is created.
   */
  async getInvoicePreview(
    request: models.GetPreviewInvoiceRequest,
    options?: RequestOptions,
  ): Promise<models.InvoiceResponse> {
    return unwrapAsync(invoicesGetInvoicePreview(
      this,
      request,
      options,
    ));
  }

  /**
   * Query invoices
   *
   * @remarks
   * Use when listing or searching invoices (e.g. admin view or customer history). Returns a paginated list; supports filtering by customer, status, date range.
   */
  async queryInvoice(
    request: models.InvoiceFilter,
    options?: RequestOptions,
  ): Promise<models.ListInvoicesResponse> {
    return unwrapAsync(invoicesQueryInvoice(
      this,
      request,
      options,
    ));
  }

  /**
   * Get invoice
   *
   * @remarks
   * Use when loading an invoice for display or editing (e.g. portal or reconciliation). Supports group_by for usage breakdown and force_runtime_recalculation.
   */
  async getInvoice(
    id: string,
    expandBySource?: boolean | undefined,
    groupBy?: Array<string> | undefined,
    expand?: string | undefined,
    options?: RequestOptions,
  ): Promise<models.InvoiceResponse> {
    return unwrapAsync(invoicesGetInvoice(
      this,
      id,
      expandBySource,
      groupBy,
      expand,
      options,
    ));
  }

  /**
   * Update invoice
   *
   * @remarks
   * Use when updating invoice metadata or due date (e.g. PDF URL, net terms), or when recalculating this draft invoice's discount from its current standing coupon associations via apply_discount:true (idempotent, does not attach a new coupon). Allowed for invoices in draft or finalized status.
   */
  async updateInvoice(
    id: string,
    body: models.UpdateInvoiceRequest,
    options?: RequestOptions,
  ): Promise<models.InvoiceResponse> {
    return unwrapAsync(invoicesUpdateInvoice(
      this,
      id,
      body,
      options,
    ));
  }

  /**
   * Trigger invoice communication webhook
   *
   * @remarks
   * Use when sending an invoice to the customer (e.g. trigger email or Slack). Payload includes full invoice details for your integration.
   */
  async triggerInvoiceCommsWebhook(
    id: string,
    options?: RequestOptions,
  ): Promise<models.SuccessResponse> {
    return unwrapAsync(invoicesTriggerInvoiceCommsWebhook(
      this,
      id,
      options,
    ));
  }

  /**
   * Finalize invoice
   *
   * @remarks
   * Use when locking an invoice for payment (e.g. after review). Once finalized, line items are locked; invoice can be paid or voided.
   */
  async finalizeInvoice(
    id: string,
    options?: RequestOptions,
  ): Promise<models.SuccessResponse> {
    return unwrapAsync(invoicesFinalizeInvoice(
      this,
      id,
      options,
    ));
  }

  /**
   * Update invoice payment status
   *
   * @remarks
   * Use when reconciling payment status from an external gateway or manual entry (e.g. mark paid after bank confirmation).
   */
  async updateInvoicePaymentStatus(
    id: string,
    body: models.UpdatePaymentStatusRequest,
    options?: RequestOptions,
  ): Promise<models.InvoiceResponse> {
    return unwrapAsync(invoicesUpdateInvoicePaymentStatus(
      this,
      id,
      body,
      options,
    ));
  }

  /**
   * Attempt invoice payment
   *
   * @remarks
   * Use when paying an invoice with the customer's wallet balance (e.g. prepaid credits or balance applied at checkout).
   */
  async attemptInvoicePayment(
    id: string,
    options?: RequestOptions,
  ): Promise<models.SuccessResponse> {
    return unwrapAsync(invoicesAttemptInvoicePayment(
      this,
      id,
      options,
    ));
  }

  /**
   * Get invoice PDF
   *
   * @remarks
   * Use when delivering an invoice PDF to the customer (e.g. email attachment or download). Use url=true for a presigned URL instead of binary. Use force_generate=true to regenerate and re-upload the PDF even if one already exists in S3.
   */
  async getInvoicePdf(
    id: string,
    url?: boolean | undefined,
    forceGenerate?: boolean | undefined,
    options?: RequestOptions,
  ): Promise<ReadableStream<Uint8Array>> {
    return unwrapAsync(invoicesGetInvoicePdf(
      this,
      id,
      url,
      forceGenerate,
      options,
    ));
  }

  /**
   * Recalculate invoice (voided invoice)
   *
   * @remarks
   * Starts an async workflow that creates a fresh replacement invoice for a voided SUBSCRIPTION invoice (same billing period). Returns workflow_id and run_id; poll workflow status or GET the new invoice via recalculated_invoice_id after completion.
   */
  async recalculateInvoice(
    id: string,
    options?: RequestOptions,
  ): Promise<models.ModelsTemporalWorkflowResult> {
    return unwrapAsync(invoicesRecalculateInvoice(
      this,
      id,
      options,
    ));
  }

  /**
   * Recalculate draft invoice (v2)
   *
   * @remarks
   * Recalculates a draft SUBSCRIPTION invoice in-place (replaces line items, reapplies credits/coupons/taxes). Use when subscription or usage data changed before finalizing.
   */
  async recalculateInvoiceV2(
    id: string,
    finalize?: boolean | undefined,
    options?: RequestOptions,
  ): Promise<models.InvoiceResponse> {
    return unwrapAsync(invoicesRecalculateInvoiceV2(
      this,
      id,
      finalize,
      options,
    ));
  }

  /**
   * Void invoice
   *
   * @remarks
   * Use when cancelling an invoice (e.g. order cancelled or duplicate). Only unpaid invoices can be voided.
   */
  async voidInvoice(
    id: string,
    options?: RequestOptions,
  ): Promise<models.SuccessResponse> {
    return unwrapAsync(invoicesVoidInvoice(
      this,
      id,
      options,
    ));
  }
}