bitsnap-react 1.6.1 → 1.7.1

package/dist/returns.d.mts

@@ -1,8 +1,8 @@
-import * as _tanstack_react_query from '@tanstack/react-query';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { CSSProperties, ReactNode } from 'react';
+import { S as SlotAppearance, A as AppearanceElements } from './appearance-core-Dt2grZdl.mjs';
 import { Timestamp } from '@bufbuild/protobuf/wkt';
 import { Message } from '@bufbuild/protobuf';
-import * as react_jsx_runtime from 'react/jsx-runtime';
-import React from 'react';
 
 /**
  * @generated from enum common.v1.Environment
@@ -18,6 +18,323 @@ declare enum Environment {
     TEST = 1
 }
 
+/**
+ * Returns appearance API.
+ *
+ * It mirrors `CheckoutAppearance` (theme, tokens, elements) so a shop can reuse
+ * one brand object for both. The resolver is pure: it turns the caller input
+ * into a theme name, the tokens in effect, the slot overrides and the inline
+ * style for the theme boundary.
+ */
+type ReturnsTheme = "light" | "dark";
+type ReturnsAppearanceTokens = {
+    /** Font family of the returns views. The library never loads fonts. */
+    fontFamily?: string;
+    /** Base font size. */
+    fontSize?: string;
+    /** Page background. */
+    background?: string;
+    /** Raised surfaces: cards, skeletons, summaries. */
+    surface?: string;
+    /** Main text color. */
+    foreground?: string;
+    /** Secondary text: descriptions, dates, hints. */
+    mutedForeground?: string;
+    /** Borders of cards, inputs and separators. */
+    border?: string;
+    /** Primary button background. */
+    buttonBackground?: string;
+    /** Primary button text. */
+    buttonForeground?: string;
+    /** Primary button background on hover. */
+    buttonHoverBackground?: string;
+    /** Hover surface of secondary buttons and selectable cards. */
+    hoverSurface?: string;
+    /** Focus ring color. Also applied to shared UI primitives through `--ring`. */
+    focusRing?: string;
+    /** Error color. */
+    error?: string;
+    /** Success color: result screen, completed and refunded statuses. */
+    success?: string;
+    /** Warning color: statuses that need attention. */
+    warning?: string;
+    /** Status badge background. */
+    badgeBackground?: string;
+    /** Status badge text. */
+    badgeForeground?: string;
+    /** Background of text inputs and the note field. */
+    inputBackground?: string;
+    /** Corner radius, applied through `--radius`. */
+    radius?: string;
+};
+/**
+ * Stable slot names. They are exposed as `data-bitsnap-returns-slot`
+ * attributes so they can also be targeted from plain CSS.
+ */
+declare const RETURNS_SLOT_NAMES: readonly ["root", "header", "title", "description", "backButton", "stepIndicator", "error", "emptyState", "skeleton", "emailForm", "emailInput", "codeForm", "codeInput", "resendButton", "logoutButton", "orderList", "orderCard", "orderReference", "orderDate", "orderTotal", "pagination", "lineList", "line", "lineName", "linePrice", "lineQuantityControl", "quantityButton", "quantityInput", "lineIneligibleReason", "noteInput", "summary", "submitButton", "secondaryButton", "successState", "returnReference", "returnInstructions", "returnList", "returnCard", "statusBadge", "history", "historyEntry"];
+type ReturnsSlotName = (typeof RETURNS_SLOT_NAMES)[number];
+type ReturnsSlotAppearance = SlotAppearance;
+type ReturnsAppearanceElements = AppearanceElements<ReturnsSlotName>;
+type ReturnsAppearance = {
+    /** `"light"` or `"dark"`. Omitted means `"light"`. */
+    theme?: ReturnsTheme;
+    /** Partial overrides applied over the theme preset. */
+    tokens?: ReturnsAppearanceTokens;
+    /** Per element `className`/`style` overrides. */
+    elements?: ReturnsAppearanceElements;
+};
+type ResolvedReturnsAppearance = {
+    theme: ReturnsTheme;
+    /** Tokens that are in effect (the theme preset plus caller overrides). */
+    tokens: ReturnsAppearanceTokens;
+    elements: ReturnsAppearanceElements;
+    /** Theme marker class for the theme boundary. */
+    boundaryClassName: string;
+    /** Inline custom properties applied to the returns root. */
+    boundaryStyle: CSSProperties;
+};
+
+/**
+ * Every string the returns views render. Pass a partial object through the
+ * `texts` prop of `BitsnapReturns`/`ReturnsProvider` to override any of them,
+ * whatever the locale. Strings with `{name}` placeholders keep them in
+ * overrides; unknown placeholders are left untouched.
+ */
+type ReturnsTexts = {
+    /** Label of the back buttons. */
+    back: string;
+    /** Step indicator, placeholders `{current}` and `{total}`. */
+    stepIndicator: string;
+    /** Skeleton accessible label. */
+    loading: string;
+    /** Button that opens the list of previous returns. */
+    myReturnsLink: string;
+    emailStepTitle: string;
+    emailStepDescription: string;
+    emailLabel: string;
+    emailPlaceholder: string;
+    emailSubmit: string;
+    codeStepTitle: string;
+    /** Placeholder `{email}`. */
+    codeStepDescription: string;
+    codeLabel: string;
+    codeSubmit: string;
+    resend: string;
+    /** Placeholder `{seconds}`. */
+    resendIn: string;
+    logout: string;
+    ordersTitle: string;
+    ordersDescription: string;
+    ordersEmpty: string;
+    /** Placeholder `{reference}`. */
+    orderTitle: string;
+    /** Placeholder `{count}`. */
+    orderReturnableLines: string;
+    orderSelect: string;
+    paginationPrevious: string;
+    paginationNext: string;
+    /** Placeholders `{page}` and `{total}` (number of orders). */
+    paginationInfo: string;
+    /** Placeholder `{reference}`. */
+    orderDetailTitle: string;
+    orderDetailDescription: string;
+    /** Placeholder `{name}`. */
+    quantityLabel: string;
+    /** Placeholder `{name}`. */
+    quantityDecrease: string;
+    /** Placeholder `{name}`. */
+    quantityIncrease: string;
+    /** Placeholder `{available}`. */
+    quantityOfAvailable: string;
+    /** Shown for an ineligible line without a reason from the backend. */
+    lineIneligibleFallback: string;
+    noteLabel: string;
+    notePlaceholder: string;
+    selectionContinue: string;
+    selectionEmpty: string;
+    previousReturnsTitle: string;
+    confirmationTitle: string;
+    confirmationDescription: string;
+    confirmationSummary: string;
+    /** Placeholder `{quantity}`. */
+    confirmationQuantity: string;
+    confirmationNote: string;
+    confirmationSubmit: string;
+    successTitle: string;
+    successDescription: string;
+    successReference: string;
+    successInstructions: string;
+    successDone: string;
+    myReturnsTitle: string;
+    myReturnsDescription: string;
+    myReturnsEmpty: string;
+    myReturnOpen: string;
+    myReturnDetailTitle: string;
+    /** Placeholder `{reference}`. */
+    myReturnTitle: string;
+    myReturnCreatedAt: string;
+    myReturnRefund: string;
+    myReturnLines: string;
+    /** Placeholders `{requested}`, `{approved}`, `{received}`. */
+    myReturnLineQuantities: string;
+    myReturnNote: string;
+    myReturnHistory: string;
+    statusSubmitted: string;
+    statusApproved: string;
+    statusRejected: string;
+    statusAwaitingReceipt: string;
+    statusReceived: string;
+    statusCompleted: string;
+    statusCancelled: string;
+    statusRefunded: string;
+    /** Any status the backend adds later. */
+    statusFallback: string;
+    refundStatusNotStarted: string;
+    refundStatusPending: string;
+    refundStatusSucceeded: string;
+    refundStatusFailed: string;
+    refundStatusFallback: string;
+    errorGeneric: string;
+    errorInvalidEmail: string;
+    errorInvalidCode: string;
+    errorSessionExpired: string;
+    errorOrderNotFound: string;
+    errorReturnNotFound: string;
+    errorQuantityUnavailable: string;
+    errorItemNotReturnable: string;
+    errorReturnsDisabled: string;
+    errorRateLimited: string;
+    errorIdempotencyConflict: string;
+    errorDeliveryFailed: string;
+    errorRetry: string;
+};
+type ReturnsTextKey = keyof ReturnsTexts;
+
+/**
+ * Compatibility layer for the `bitsnap-react` 1.6.0 returns widget. Everything
+ * here is pure; the components and hooks apply it at their boundary.
+ */
+/** Environment as a string or as the proto enum used by 1.6.0. */
+type ReturnsEnvironmentInput = "production" | "test" | Environment;
+/** Text keys of the 1.6.0 widget. */
+type LegacyReturnsTexts = Partial<{
+    title: string;
+    email: string;
+    sendCode: string;
+    code: string;
+    verify: string;
+    orders: string;
+    submit: string;
+    note: string;
+    loading: string;
+    history: string;
+}>;
+/** Our text keys plus the 1.6.0 ones. Our keys win when both are given. */
+type ReturnsTextsInput = Partial<ReturnsTexts> & LegacyReturnsTexts;
+/** 1.6.0 `theme` prop. */
+type LegacyReturnsTheme = {
+    brandColor?: string;
+};
+
+/**
+ * Backend environment the returns calls run against. The library has no other
+ * environment switch for public API calls, so this defaults to `"production"`.
+ */
+type ReturnsEnvironment = "production" | "test";
+type ReturnsSessionStatus = 
+/** Server render and first client render: storage has not been read yet. */
+"hydrating"
+/** A `panelAccessToken` is being exchanged for a returns session. */
+ | "exchanging" | "anonymous" | "authenticated";
+/** A pending email verification. */
+type ReturnsChallenge = {
+    challengeId: string;
+    email: string;
+    /** Unix milliseconds when the next code may be requested. */
+    resendAvailableAt: number;
+};
+type ReturnsProviderProps = {
+    /** Bitsnap project ID. */
+    projectID: string;
+    /**
+     * API host. Defaults to the host set with `setCustomHost`/`setHost`, then to
+     * `https://bitsnap.pl`. Each provider keeps its own transport.
+     */
+    host?: string;
+    /**
+     * Backend environment, `"production"` unless set to `"test"`. The proto
+     * `Environment` enum is accepted too.
+     */
+    environment?: ReturnsEnvironmentInput;
+    /** Theme, tokens and per-element overrides. */
+    appearance?: ReturnsAppearance;
+    /**
+     * Text overrides, applied whatever the locale. The keys of `bitsnap-react`
+     * 1.6.0 (`title`, `email`, `sendCode`, ...) are accepted too; our own keys
+     * win when both are given.
+     */
+    texts?: ReturnsTextsInput;
+    /** `bitsnap-react` 1.6.0 brand color. Explicit `appearance.tokens` win. */
+    theme?: LegacyReturnsTheme;
+    /** Locale of texts, dates and money. Defaults to the library locale. */
+    locale?: string;
+    /**
+     * Customer panel access token. When set, it is exchanged for a returns
+     * session on mount, so the customer needs no second verification code.
+     * Changing or removing it drops the session.
+     */
+    panelAccessToken?: string;
+    /** Class of the themed root element. */
+    className?: string;
+    children?: ReactNode;
+};
+/**
+ * Holds everything the returns views share: the per-instance transport, the
+ * query client (when the app has none), appearance, texts and the returns
+ * session. It renders the themed root element, so step components composed
+ * under it are themed without extra markup.
+ *
+ * ```tsx
+ * <ReturnsProvider projectID="…" appearance={brand}>
+ *   <ReturnsOrderList onSelectOrder={setOrderId} />
+ * </ReturnsProvider>
+ * ```
+ */
+declare function ReturnsProvider({ projectID, host, environment, appearance, texts, theme, locale, panelAccessToken, className, children, }: ReturnsProviderProps): react_jsx_runtime.JSX.Element;
+/** Name of {@link ReturnsProvider} in `bitsnap-react` 1.6.0. */
+declare const BitsnapReturnsProvider: typeof ReturnsProvider;
+type BitsnapReturnsProviderProps = ReturnsProviderProps;
+
+type BitsnapReturnsProps = Omit<ReturnsProviderProps, "children">;
+/**
+ * Customer return flow: email, code, orders, line selection, confirmation and
+ * result, plus the list of earlier returns. It is `ReturnsProvider` with the
+ * default step router; compose your own page from the step components to
+ * change the layout.
+ *
+ * ```tsx
+ * <BitsnapReturns projectID="…" appearance={brand} texts={{ emailStepTitle: "Return a product" }} />
+ * ```
+ */
+declare function BitsnapReturns(props: BitsnapReturnsProps): react_jsx_runtime.JSX.Element;
+
+type ReturnsEmailStepProps = {
+    /** Called after the verification code was sent, with the trimmed email. */
+    onSubmitted?: (email: string) => void;
+    className?: string;
+};
+/** First step: asks for the email the order was placed with. */
+declare function ReturnsEmailStep({ onSubmitted, className, }: ReturnsEmailStepProps): react_jsx_runtime.JSX.Element;
+type ReturnsCodeStepProps = {
+    /** Called once the code was accepted and the session exists. */
+    onVerified?: () => void;
+    /** Shows a back button, for example to change the email. */
+    onBack?: () => void;
+    className?: string;
+};
+/** Second step: asks for the code that was emailed to the customer. */
+declare function ReturnsCodeStep({ onVerified, onBack, className, }: ReturnsCodeStepProps): react_jsx_runtime.JSX.Element;
+
 /**
  * @generated from message public.v1.StartReturnSessionResponse
  */
@@ -46,7 +363,7 @@ type VerifyReturnSessionResponse = Message<"public.v1.VerifyReturnSessionRespons
     /**
      * @generated from field: google.protobuf.Timestamp expires_at = 2;
      */
-    expiresAt?: Timestamp;
+    expiresAt?: Timestamp | undefined;
 };
 /**
  * @generated from message public.v1.ReturnOrderSummary
@@ -67,7 +384,7 @@ type ReturnOrderSummary = Message<"public.v1.ReturnOrderSummary"> & {
     /**
      * @generated from field: google.protobuf.Timestamp purchased_at = 4;
      */
-    purchasedAt?: Timestamp;
+    purchasedAt?: Timestamp | undefined;
     /**
      * @generated from field: int64 total_minor = 5;
      */
@@ -194,7 +511,7 @@ type ReturnOrderDetail = Message<"public.v1.ReturnOrderDetail"> & {
     /**
      * @generated from field: google.protobuf.Timestamp purchased_at = 4;
      */
-    purchasedAt?: Timestamp;
+    purchasedAt?: Timestamp | undefined;
     /**
      * @generated from field: int64 total_minor = 5;
      */
@@ -227,7 +544,7 @@ type ReturnHistoryEntry = Message<"public.v1.ReturnHistoryEntry"> & {
     /**
      * @generated from field: google.protobuf.Timestamp created_at = 4;
      */
-    createdAt?: Timestamp;
+    createdAt?: Timestamp | undefined;
 };
 /**
  * @generated from message public.v1.ReturnRequestLineView
@@ -305,7 +622,7 @@ type ReturnRequestView = Message<"public.v1.ReturnRequestView"> & {
     /**
      * @generated from field: google.protobuf.Timestamp created_at = 10;
      */
-    createdAt?: Timestamp;
+    createdAt?: Timestamp | undefined;
     /**
      * @generated from field: repeated public.v1.ReturnRequestLineView lines = 11;
      */
@@ -326,7 +643,7 @@ type GetReturnableOrderResponse = Message<"public.v1.GetReturnableOrderResponse"
     /**
      * @generated from field: public.v1.ReturnOrderDetail order = 1;
      */
-    order?: ReturnOrderDetail;
+    order?: ReturnOrderDetail | undefined;
     /**
      * @generated from field: repeated public.v1.ReturnHistoryEntry return_history = 2;
      */
@@ -339,7 +656,7 @@ type CreateReturnRequestResponse = Message<"public.v1.CreateReturnRequestRespons
     /**
      * @generated from field: public.v1.ReturnRequestView request = 1;
      */
-    request?: ReturnRequestView;
+    request?: ReturnRequestView | undefined;
 };
 /**
  * @generated from message public.v1.ListMyReturnsResponse
@@ -359,59 +676,292 @@ type ListMyReturnsResponse = Message<"public.v1.ListMyReturnsResponse"> & {
     total: number;
 };
 
-type BitsnapReturnsProviderProps = {
-    projectID: string;
-    host?: string;
-    environment?: Environment;
-    children: React.ReactNode;
-};
-/** Provider for the returns hooks when building a custom customer flow. */
-declare function BitsnapReturnsProvider({ projectID, host, environment, children, }: BitsnapReturnsProviderProps): react_jsx_runtime.JSX.Element;
-declare function useReturnSession(): {
-    startSession: _tanstack_react_query.UseMutateAsyncFunction<StartReturnSessionResponse, Error, string, unknown>;
-    verifySession: _tanstack_react_query.UseMutateAsyncFunction<VerifyReturnSessionResponse, Error, {
-        challengeId: string;
-        code: string;
-    }, unknown>;
-    logout: () => void;
+/** One line chosen for return. */
+type SelectedReturnLine = {
+    lineId: string;
+    quantity: number;
+};
+
+type ReturnsOrderListProps = {
+    /** Called with the canonical order ID of the chosen order. */
+    onSelectOrder?: (orderId: string) => void;
+    /** Shows a "my returns" button that calls this. */
+    onOpenMyReturns?: () => void;
+    /** Shows the sign out button. Defaults to `true`. */
+    showLogout?: boolean;
+    /** Orders per page. Defaults to 10. */
+    pageSize?: number;
+    className?: string;
+};
+/** Orders of the customer that still have products to return. */
+declare function ReturnsOrderList({ onSelectOrder, onOpenMyReturns, showLogout, pageSize, className, }: ReturnsOrderListProps): react_jsx_runtime.JSX.Element;
+type ReturnsOrderDetailProps = {
+    /** Canonical order ID, as given to `onSelectOrder`. */
+    orderId: string;
+    /** Called with the selected lines and the note when the form is valid. */
+    onContinue?: (selection: {
+        items: SelectedReturnLine[];
+        note: string;
+    }) => void;
+    onBack?: () => void;
+    /** Selection to start with, for example when coming back from the confirmation. */
+    initialItems?: SelectedReturnLine[];
+    initialNote?: string;
+    className?: string;
+};
+/** Line and quantity selection of one order. */
+declare function ReturnsOrderDetail({ orderId, onContinue, onBack, initialItems, initialNote, className, }: ReturnsOrderDetailProps): react_jsx_runtime.JSX.Element;
+type ReturnsConfirmationProps = {
+    /** Canonical order ID. */
+    orderId: string;
+    /** Lines chosen in the order detail step. */
+    items: SelectedReturnLine[];
+    note?: string;
+    /** Called with the new return's ID and the created request. */
+    onSubmitted?: (returnId: string, request: ReturnRequestView) => void;
+    onBack?: () => void;
+    className?: string;
+};
+/** Review of the selected lines and the submit action. */
+declare function ReturnsConfirmation({ orderId, items, note, onSubmitted, onBack, className, }: ReturnsConfirmationProps): react_jsx_runtime.JSX.Element;
+type ReturnsResultProps = {
+    /** ID of the created return, as given to `onSubmitted`. */
+    returnId: string;
+    /** Called by the primary button, normally to go back to the orders. */
+    onContinue?: () => void;
+    /** Shows a "my returns" button that calls this. */
+    onOpenMyReturns?: () => void;
+    className?: string;
+};
+/** Success screen with the reference and the return instructions. */
+declare function ReturnsResult({ returnId, onContinue, onOpenMyReturns, className, }: ReturnsResultProps): react_jsx_runtime.JSX.Element;
+
+type ReturnsMyReturnsListProps = {
+    /** Called with the ID of the chosen return. */
+    onSelectReturn?: (returnId: string) => void;
+    onBack?: () => void;
+    /** Returns per page. Defaults to 10. */
+    pageSize?: number;
+    className?: string;
+};
+/** Return requests the customer has submitted, with their status. */
+declare function ReturnsMyReturnsList({ onSelectReturn, onBack, pageSize, className, }: ReturnsMyReturnsListProps): react_jsx_runtime.JSX.Element;
+type ReturnsMyReturnDetailProps = {
+    /** ID of the return to show. */
+    returnId: string;
+    onBack?: () => void;
+    className?: string;
+};
+/** Status, lines, refund and history of one return request. */
+declare function ReturnsMyReturnDetail({ returnId, onBack, className, }: ReturnsMyReturnDetailProps): react_jsx_runtime.JSX.Element;
+
+/** React Query style status shared by the query and mutation results. */
+type QueryStatus = "pending" | "error" | "success";
+type MutationStatus = "idle" | QueryStatus;
+type UseReturnSessionResult = {
+    status: ReturnsSessionStatus;
     isAuthenticated: boolean;
+    /** Pending email verification, set after `start` succeeded. */
+    challenge: ReturnsChallenge | undefined;
+    isStarting: boolean;
+    isVerifying: boolean;
+    /** Last failure of `start` or `verify`, or of the panel token exchange. */
+    error: Error | null;
+    errorKey: ReturnsTextKey | undefined;
+    /** Same as `isStarting` (`bitsnap-react` 1.6.0 name). */
     starting: boolean;
+    /** Same as `isVerifying` (`bitsnap-react` 1.6.0 name). */
     verifying: boolean;
+    /**
+     * `bitsnap-react` 1.6.0 API: sends a code and resolves with the response
+     * (including `challengeId`). Rejects on failure. Also stores the challenge
+     * like `start`.
+     */
+    startSession: (email: string) => Promise<StartReturnSessionResponse>;
+    /**
+     * `bitsnap-react` 1.6.0 API: verifies a code, stores the session like
+     * `verify` and resolves with the response. Rejects on failure.
+     */
+    verifySession: (input: {
+        challengeId: string;
+        code: string;
+    }) => Promise<VerifyReturnSessionResponse>;
+    /** Sends a code to `email`. Resolves to `true` when the code was sent. */
+    start: (email: string) => Promise<boolean>;
+    /** Verifies the code of the pending challenge. Resolves to `true` on success. */
+    verify: (code: string) => Promise<boolean>;
+    /** Sends a new code to the email of the pending challenge. */
+    resend: () => Promise<boolean>;
+    /** Drops the session and the pending challenge. */
+    logout: () => void;
+};
+/** Email verification and the returns session of the nearest provider. */
+declare function useReturnSession(): UseReturnSessionResult;
+type PagedOptions = {
+    /** Items per page. Defaults to 10. */
+    pageSize?: number;
+};
+type UseReturnOrdersResult = {
+    orders: ReturnOrderSummary[];
+    /** Total number of returnable orders. */
+    total: number;
+    /** Response for the requested page (React Query style). */
+    data: ListReturnOrdersResponse | undefined;
+    isLoading: boolean;
+    isFetching: boolean;
     error: Error | null;
+    errorKey: ReturnsTextKey | undefined;
+    status: QueryStatus;
+    isError: boolean;
+    isSuccess: boolean;
+    /** 1-based number of the current page. */
+    page: number;
+    hasNext: boolean;
+    hasPrevious: boolean;
+    next: () => void;
+    previous: () => void;
+    refetch: () => Promise<unknown>;
 };
-declare function useReturnOrders(pageSize?: number, pageToken?: string): _tanstack_react_query.UseQueryResult<void | ListReturnOrdersResponse, Error>;
-declare function useReturnableOrder(canonicalOrderID?: string): _tanstack_react_query.UseQueryResult<void | GetReturnableOrderResponse, Error>;
-declare function useCreateReturn(): _tanstack_react_query.UseMutationResult<void | CreateReturnRequestResponse, Error, {
+/**
+ * Orders of the signed-in customer that have lines to return, page by page.
+ * Call it with `{ pageSize }` (pages are walked with `next`/`previous`) or, as
+ * in `bitsnap-react` 1.6.0, with `(pageSize, pageToken)`; then the explicit
+ * token is requested and `data.nextPageToken` drives paging.
+ */
+declare function useReturnOrders(options?: PagedOptions): UseReturnOrdersResult;
+declare function useReturnOrders(pageSize?: number, pageToken?: string): UseReturnOrdersResult;
+type UseReturnableOrderResult = {
+    order: ReturnOrderDetail | undefined;
+    /** Earlier return requests for this order. */
+    returnHistory: ReturnHistoryEntry[];
+    /** Response (React Query style): `data.order` is the order. */
+    data: GetReturnableOrderResponse | undefined;
+    isLoading: boolean;
+    error: Error | null;
+    errorKey: ReturnsTextKey | undefined;
+    status: QueryStatus;
+    isError: boolean;
+    isSuccess: boolean;
+    refetch: () => Promise<unknown>;
+};
+/**
+ * One order with the eligibility of each line. Without an `orderId` the query
+ * is disabled.
+ */
+declare function useReturnableOrder(orderId?: string): UseReturnableOrderResult;
+type CreateReturnInput = {
+    orderId: string;
+    items: {
+        lineId: string;
+        quantity: number;
+    }[];
+    note?: string;
+};
+/** Input of the `bitsnap-react` 1.6.0 `mutateAsync`/`mutate`. */
+type LegacyCreateReturnInput = {
     canonicalOrderID: string;
     items: {
         lineId: string;
         quantity: number;
     }[];
     note?: string;
+    /** Used as given. A fresh key is generated per call when omitted. */
     idempotencyKey?: string;
-}, unknown>;
-declare function useMyReturns(pageSize?: number, pageToken?: string): _tanstack_react_query.UseQueryResult<void | ListMyReturnsResponse, Error>;
-type BitsnapReturnsProps = {
-    projectID: string;
-    host?: string;
-    environment?: Environment;
-    texts?: Partial<{
-        title: string;
-        email: string;
-        sendCode: string;
-        code: string;
-        verify: string;
-        orders: string;
-        submit: string;
-        note: string;
-        loading: string;
-        history: string;
-    }>;
-    theme?: {
-        brandColor?: string;
-    };
-    className?: string;
 };
-declare function BitsnapReturns(props: BitsnapReturnsProps): react_jsx_runtime.JSX.Element;
+type UseCreateReturnResult = {
+    /**
+     * Submits the return request. Resolves to the created request, or
+     * `undefined` when it failed (see `error`). Retrying reuses the same
+     * idempotency key, so a retry can never create a second request.
+     */
+    submit: (input: CreateReturnInput) => Promise<ReturnRequestView | undefined>;
+    isPending: boolean;
+    error: Error | null;
+    errorKey: ReturnsTextKey | undefined;
+    /**
+     * `bitsnap-react` 1.6.0 API (React Query mutation semantics): resolves with
+     * the response (`result.request`) and rejects on failure.
+     */
+    mutateAsync: (input: LegacyCreateReturnInput) => Promise<CreateReturnRequestResponse>;
+    /** Fire and forget version of `mutateAsync`; failures land in `error`. */
+    mutate: (input: LegacyCreateReturnInput, options?: {
+        onSuccess?: (response: CreateReturnRequestResponse) => void;
+        onError?: (error: Error) => void;
+    }) => void;
+    /** Response of the last successful request. */
+    data: CreateReturnRequestResponse | undefined;
+    reset: () => void;
+    status: MutationStatus;
+    isError: boolean;
+    isSuccess: boolean;
+};
+/**
+ * Creates a return request. With `submit` the idempotency key is generated
+ * once per hook instance, which is once per confirmation screen, and reused on
+ * retry.
+ */
+declare function useCreateReturn(): UseCreateReturnResult;
+type UseMyReturnsResult = {
+    returns: ReturnRequestView[];
+    total: number;
+    /** Response for the requested page (React Query style). */
+    data: ListMyReturnsResponse | undefined;
+    isLoading: boolean;
+    isFetching: boolean;
+    error: Error | null;
+    errorKey: ReturnsTextKey | undefined;
+    status: QueryStatus;
+    isError: boolean;
+    isSuccess: boolean;
+    page: number;
+    hasNext: boolean;
+    hasPrevious: boolean;
+    next: () => void;
+    previous: () => void;
+    refetch: () => Promise<unknown>;
+};
+/**
+ * Return requests of the signed-in customer, page by page. Accepts
+ * `{ pageSize }` or the `bitsnap-react` 1.6.0 `(pageSize, pageToken)` form,
+ * like `useReturnOrders`.
+ */
+declare function useMyReturns(options?: PagedOptions): UseMyReturnsResult;
+declare function useMyReturns(pageSize?: number, pageToken?: string): UseMyReturnsResult;
+type UseMyReturnResult = {
+    request: ReturnRequestView | undefined;
+    isLoading: boolean;
+    error: unknown;
+    errorKey: ReturnsTextKey | undefined;
+    refetch: () => void;
+};
+/** One return request of the signed-in customer. */
+declare function useMyReturn(returnId: string): UseMyReturnResult;
+
+/**
+ * Returns scoped appearance provider. It only wraps the returns views, so the
+ * configuration never leaks into checkout, the panel or the host page.
+ */
+declare function ReturnsAppearanceProvider({ appearance, children, }: {
+    appearance?: ReturnsAppearance;
+    children: ReactNode;
+}): react_jsx_runtime.JSX.Element;
+declare function useReturnsAppearance(): ResolvedReturnsAppearance;
+/**
+ * Returns the caller overrides for a slot, meant to be merged with the
+ * built-in presentation:
+ *
+ * ```tsx
+ * const slot = useReturnsSlot("title");
+ *
+ * return <h2 className={cn("text-xl font-semibold", slot.className)} style={slot.style} />;
+ * ```
+ */
+declare function useReturnsSlot(slot: ReturnsSlotName): ReturnsSlotAppearance;
+
+/**
+ * Returns a lookup for the returns strings: the caller override when provided,
+ * otherwise the default for the locale. Optional `values` fill `{placeholders}`.
+ */
+declare function useReturnsText(): (key: ReturnsTextKey, values?: Record<string, string | number>) => string;
 
-export { BitsnapReturns, type BitsnapReturnsProps, BitsnapReturnsProvider, type BitsnapReturnsProviderProps, Environment, useCreateReturn, useMyReturns, useReturnOrders, useReturnSession, useReturnableOrder };
+export { BitsnapReturns, type BitsnapReturnsProps, BitsnapReturnsProvider, type BitsnapReturnsProviderProps, type CreateReturnInput, Environment, type LegacyCreateReturnInput, type LegacyReturnsTexts, type LegacyReturnsTheme, RETURNS_SLOT_NAMES, type ReturnsAppearance, type ReturnsAppearanceElements, ReturnsAppearanceProvider, type ReturnsAppearanceTokens, type ReturnsChallenge, ReturnsCodeStep, type ReturnsCodeStepProps, ReturnsConfirmation, type ReturnsConfirmationProps, ReturnsEmailStep, type ReturnsEmailStepProps, type ReturnsEnvironment, type ReturnsEnvironmentInput, ReturnsMyReturnDetail, type ReturnsMyReturnDetailProps, ReturnsMyReturnsList, type ReturnsMyReturnsListProps, ReturnsOrderDetail, type ReturnsOrderDetailProps, ReturnsOrderList, type ReturnsOrderListProps, ReturnsProvider, type ReturnsProviderProps, ReturnsResult, type ReturnsResultProps, type ReturnsSessionStatus, type ReturnsSlotAppearance, type ReturnsSlotName, type ReturnsTextKey, type ReturnsTexts, type ReturnsTextsInput, type ReturnsTheme, type SelectedReturnLine, type UseCreateReturnResult, type UseMyReturnResult, type UseMyReturnsResult, type UseReturnOrdersResult, type UseReturnSessionResult, type UseReturnableOrderResult, useCreateReturn, useMyReturn, useMyReturns, useReturnOrders, useReturnSession, useReturnableOrder, useReturnsAppearance, useReturnsSlot, useReturnsText };