@pelygo/janus 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,1037 @@
+/**
+ * @pelygo/janus
+ *
+ * TypeScript API client for JANUS endpoints with full type safety.
+ *
+ * @packageDocumentation
+ */
+
+import { AuthApi } from '@pelygo/auth/core';
+
+/**
+ * Data for adding a return reason to a client
+ */
+export declare interface AddClientReturnReasonRequest {
+    /** Client object with ID */
+    client: {
+        id: number;
+    };
+    /** Return reason object with ID */
+    return_reason: {
+        id: number;
+    };
+}
+
+/**
+ * Data for adding a comment to a return
+ */
+export declare interface AddReturnCommentRequest {
+    /** Comment text */
+    comment: string;
+}
+
+/**
+ * Data for adding a status to a return
+ */
+export declare interface AddReturnStatusRequest {
+    /** Return object with ID */
+    return: {
+        id: number;
+    };
+    /** Return status object with ID */
+    return_status: {
+        id: number;
+    };
+    /** Created by user object with ID */
+    created_by?: {
+        id: number;
+    };
+}
+
+/**
+ * Approval status for returns
+ */
+export declare type ApprovalStatus = 'pending' | 'approved' | 'rejected';
+
+/**
+ * Base Entity Interface
+ *
+ * All JANUS entities extend from this base type.
+ */
+export declare interface BaseEntity {
+    /** Unique identifier */
+    id: number;
+    /** User ID who created this record */
+    created_by?: number;
+    /** User ID who last updated this record */
+    updated_by?: number;
+    /** Creation timestamp */
+    created_ts?: string;
+    /** Last update timestamp */
+    updated_ts?: string;
+    /** Partition ID for multi-tenancy */
+    partition_id?: number;
+}
+
+/**
+ * Filter Types for API Queries
+ * @module types/filters
+ */
+/**
+ * Base filter options common to most queries
+ */
+export declare interface BaseFilters {
+    /** Page number for pagination */
+    page?: number;
+    /** Page size for pagination */
+    pageSize?: number;
+}
+
+/**
+ * Build a query string from a filter object.
+ *
+ * Handles undefined/null values by omitting them.
+ * Properly encodes special characters.
+ *
+ * @param filters - Object containing filter key-value pairs
+ * @returns Query string (without leading '?')
+ *
+ * @example
+ * ```typescript
+ * const query = buildQueryString({ clientId: 5, status: 'active' });
+ * // Returns: "clientId=5&status=active"
+ * ```
+ */
+export declare function buildQueryString(filters: FilterObject): string;
+
+/**
+ * Build a full URL with query parameters.
+ *
+ * @param baseUrl - Base URL (may already include query params)
+ * @param filters - Filter object to append
+ * @returns Full URL with query parameters
+ *
+ * @example
+ * ```typescript
+ * const url = buildUrl('/returns', { clientId: 5 });
+ * // Returns: "/returns?clientId=5"
+ * ```
+ */
+export declare function buildUrl(baseUrl: string, filters?: FilterObject): string;
+
+/**
+ * Client Entity
+ *
+ * Represents a customer/client in the JANUS system.
+ */
+export declare interface Client extends BaseEntity {
+    /** Client name */
+    name: string;
+    /** Short name / code */
+    short_name?: string;
+    /** Contact email */
+    email?: string;
+    /** Contact phone */
+    phone?: string;
+    /** Operational status */
+    operational_status?: ClientOperationalStatus;
+    /** Client-specific settings */
+    settings?: ClientSettings;
+    /** Whether returns require approval */
+    requires_approval?: boolean;
+    /** Default courier service ID */
+    default_courier_service_id?: number;
+    /** Whether client is active */
+    active?: boolean;
+}
+
+/**
+ * Client Courier Service
+ *
+ * Represents a courier service configured for a specific client.
+ */
+export declare interface ClientCourierService extends BaseEntity {
+    /** Client ID */
+    client_id?: number;
+    /** Courier service ID */
+    courier_service_id?: number;
+    /** Courier service */
+    courier_service?: CourierService;
+    /** Whether this is the default service */
+    is_default?: boolean;
+    /** Client-specific price override */
+    price?: number;
+    /** Whether service is active for this client */
+    active?: boolean;
+}
+
+/**
+ * Operational status for a client
+ */
+export declare type ClientOperationalStatus = 'active' | 'inactive' | 'onboarding' | 'offboarding';
+
+/**
+ * Client settings structure
+ */
+export declare interface ClientSettings {
+    /** Logo URL */
+    logo_url?: string;
+    /** Primary brand color */
+    primary_color?: string;
+    /** Secondary brand color */
+    secondary_color?: string;
+    /** Support email address */
+    support_email?: string;
+    /** Support phone number */
+    support_phone?: string;
+    /** Custom CSS for portal */
+    custom_css?: string;
+    /** Additional settings as key-value pairs */
+    [key: string]: unknown;
+}
+
+/**
+ * Client settings public response (no auth required)
+ */
+export declare interface ClientSettingsPublicResponse {
+    /** Client ID */
+    id: number;
+    /** Client name */
+    name: string;
+    /** Settings */
+    settings?: Record<string, unknown>;
+}
+
+/**
+ * Clients resource interface
+ */
+export declare interface ClientsResource {
+    /** Get all clients accessible to the current user */
+    getAll(): Promise<Client[]>;
+    /** Get a client by ID */
+    getById(id: number): Promise<Client>;
+    /** Update a client */
+    update(id: number, data: UpdateClientRequest): Promise<Client>;
+    /** Get courier services for a client */
+    getCourierServices(clientId: number): Promise<ClientCourierService[]>;
+    /** Get a specific courier service for a client */
+    getCourierServiceById(clientId: number, serviceId: number): Promise<ClientCourierService>;
+    /** Update a courier service for a client */
+    updateCourierService(clientId: number, service: Partial<ClientCourierService>): Promise<ClientCourierService>;
+    /** Get order by reference for a client */
+    getOrderByRef(clientId: number, orderRef: string): Promise<unknown>;
+    /** Add a return reason to a client */
+    addReturnReason(clientId: number, returnReasonId: number): Promise<unknown>;
+    /** Remove a return reason from a client */
+    removeReturnReason(clientId: number, returnReasonId: number): Promise<void>;
+    /** Upload a file for a client */
+    uploadFile(clientId: number, filename: string, data: UploadFileRequest): Promise<UploadFileResponse>;
+}
+
+/**
+ * Courier Entity
+ *
+ * Represents a courier/carrier company.
+ */
+export declare interface Courier extends BaseEntity {
+    /** Courier name */
+    name: string;
+    /** Courier code */
+    code?: string;
+    /** Whether courier is active */
+    active?: boolean;
+}
+
+/**
+ * Courier Service Entity
+ *
+ * Represents a specific service offered by a courier.
+ */
+export declare interface CourierService extends BaseEntity {
+    /** Service name */
+    name: string;
+    /** Service code */
+    code?: string;
+    /** Parent courier ID */
+    courier_id?: number;
+    /** Parent courier */
+    courier?: Courier;
+    /** Whether service is active */
+    active?: boolean;
+    /** Service cost */
+    cost?: number;
+    /** Client-specific price */
+    price?: number;
+}
+
+/**
+ * Create a JANUS API client.
+ *
+ * The client automatically handles authentication using @pelygo/auth
+ * and provides typed methods for all JANUS endpoints.
+ *
+ * @param options - Configuration options
+ * @returns JanusApi instance
+ *
+ * @example
+ * ```typescript
+ * import { createJanusApi } from '@pelygo/janus';
+ *
+ * // Create client with defaults (uses localStorage token)
+ * const janus = createJanusApi();
+ *
+ * // Fetch all clients
+ * const clients = await janus.clients.getAll();
+ *
+ * // Query returns with filters
+ * const returns = await janus.returns.query({
+ *   clientId: 5,
+ *   created_at: '2024-01-01',
+ * });
+ *
+ * // Get public client settings (no auth required)
+ * const settings = await janus.helpers.getClientSettingsByName('acme');
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With custom configuration
+ * const janus = createJanusApi({
+ *   baseUrl: 'https://api.janus.dev.pelygo.com',
+ *   onUnauthorized: () => {
+ *     // Redirect to login
+ *     window.location.href = '/login';
+ *   },
+ * });
+ * ```
+ */
+export declare function createJanusApi(options?: JanusApiOptions): JanusApi;
+
+/**
+ * Data for a return item in create request
+ */
+export declare interface CreateReturnItemRequest {
+    /** Product SKU */
+    sku: string;
+    /** Product name */
+    name?: string;
+    /** Quantity */
+    qty: number;
+    /** Return reason ID */
+    reason_id?: number;
+    /** Customer note */
+    note?: string;
+    /** Price paid */
+    price_paid?: number;
+}
+
+/**
+ * Request Types for API Operations
+ * @module types/requests
+ */
+/**
+ * Data for creating a new return
+ */
+export declare interface CreateReturnRequest {
+    /** Client ID */
+    client_id: number;
+    /** Order reference */
+    order_ref?: string;
+    /** Customer forename */
+    forename?: string;
+    /** Customer surname */
+    surname?: string;
+    /** Customer email */
+    email?: string;
+    /** Company name */
+    company?: string;
+    /** Address line 1 */
+    line_1?: string;
+    /** Address line 2 */
+    line_2?: string;
+    /** Address line 3 */
+    line_3?: string;
+    /** City */
+    city?: string;
+    /** County/State */
+    county?: string;
+    /** Country */
+    country?: string;
+    /** Country code */
+    country_code?: string;
+    /** Postcode */
+    postcode?: string;
+    /** Courier service ID */
+    courier_service_id?: number;
+    /** Return items */
+    items?: CreateReturnItemRequest[];
+}
+
+/**
+ * Customer login response
+ */
+export declare interface CustomerLoginResponse {
+    /** Whether login was successful */
+    success: boolean;
+    /** Order data if found */
+    order?: {
+        id: number;
+        order_ref: string;
+        [key: string]: unknown;
+    };
+    /** Error message if failed */
+    error?: string;
+}
+
+/**
+ * Date range filter
+ */
+export declare interface DateRangeFilter {
+    /** Start date (ISO string) */
+    from?: string;
+    /** End date (ISO string) */
+    to?: string;
+}
+
+/**
+ * Default JANUS API base URL
+ */
+export declare const DEFAULT_JANUS_URL = "https://api.janus.pelygo.com";
+
+/**
+ * Generic filter object type
+ */
+declare type FilterObject = Record<string, FilterValue>;
+
+/**
+ * Order filter options response
+ */
+export declare interface FilterOptionsResponse {
+    /** Available statuses */
+    statuses?: Array<{
+        id: number;
+        name: string;
+    }>;
+    /** Available reasons */
+    reasons?: Array<{
+        id: number;
+        name: string;
+    }>;
+    /** Available courier services */
+    courier_services?: Array<{
+        id: number;
+        name: string;
+    }>;
+    [key: string]: unknown;
+}
+
+/**
+ * Query Parameter Builder Utility
+ *
+ * Builds URL query strings from filter objects.
+ * @module utils/query-builder
+ */
+/**
+ * Filter value types that can be converted to query params
+ */
+declare type FilterValue = string | number | boolean | undefined | null;
+
+/**
+ * Error thrown when access is forbidden (403)
+ */
+export declare class ForbiddenError extends JanusApiError {
+    constructor(message?: string, response?: unknown);
+}
+
+/**
+ * Helpers resource interface (no auth required)
+ */
+export declare interface HelpersResource {
+    /** Get public client settings by client name (for return portal branding) */
+    getClientSettingsByName(name: string): Promise<ClientSettingsPublicResponse>;
+    /** Get notification settings by client name */
+    getNotificationSettings(name: string): Promise<NotificationSettingsResponse>;
+    /** Customer login for return portal */
+    customerLogin(clientId: number, orderRef: string, postcode: string): Promise<CustomerLoginResponse>;
+}
+
+/**
+ * Check if an error is a JanusApiError
+ */
+export declare function isJanusApiError(error: unknown): error is JanusApiError;
+
+/**
+ * Check if an error is an UnauthorizedError
+ */
+export declare function isUnauthorizedError(error: unknown): error is UnauthorizedError;
+
+/**
+ * JANUS API Client Interface
+ *
+ * Provides typed access to all JANUS API resources.
+ */
+export declare interface JanusApi {
+    /** Clients resource - manage client accounts */
+    clients: ClientsResource;
+    /** Returns resource - manage customer returns */
+    returns: ReturnsResource;
+    /** Reports resource - generate reports */
+    reports: ReportsResource;
+    /** Helpers resource - public endpoints (no auth required) */
+    helpers: HelpersResource;
+    /** Underlying AuthApi instance for raw requests */
+    auth: AuthApi;
+}
+
+/**
+ * Error Utilities
+ *
+ * Custom error types and error handling utilities.
+ * @module utils/errors
+ */
+/**
+ * Base class for JANUS API errors
+ */
+export declare class JanusApiError extends Error {
+    /** HTTP status code */
+    readonly status: number;
+    /** Original error response */
+    readonly response?: unknown;
+    constructor(message: string, status: number, response?: unknown);
+}
+
+/**
+ * Options for creating a JANUS API client
+ */
+export declare interface JanusApiOptions {
+    /** Base URL for JANUS API (defaults to production) */
+    baseUrl?: string;
+    /** Base URL for auth API (if different from JANUS) */
+    authUrl?: string;
+    /** Called on 401 unauthorized response */
+    onUnauthorized?: () => void;
+    /** Called on successful login */
+    onLoginSuccess?: (token: string) => void;
+    /** Called on login failure */
+    onLoginError?: (error: Error) => void;
+}
+
+/**
+ * Error thrown when resource is not found (404)
+ */
+export declare class NotFoundError extends JanusApiError {
+    constructor(message?: string, response?: unknown);
+}
+
+/**
+ * Notification settings response
+ */
+declare interface NotificationSettingsResponse {
+    /** Client ID */
+    id: number;
+    /** Client name */
+    name: string;
+    /** Client short name */
+    short_name: string;
+    /** Notification settings */
+    settings?: Record<string, unknown>;
+}
+
+/**
+ * Response Types for API Operations
+ * @module types/responses
+ */
+/**
+ * Paginated response wrapper
+ */
+export declare interface PaginatedResponse<T> {
+    /** Data items */
+    data: T[];
+    /** Total count */
+    total?: number;
+    /** Current page */
+    page?: number;
+    /** Page size */
+    pageSize?: number;
+}
+
+/**
+ * Reports resource interface
+ */
+export declare interface ReportsResource {
+    /** Get returns summary report */
+    returnsSummary(filters?: ReturnsSummaryFilters): Promise<ReturnsSummaryResponse>;
+    /** Get returns summary as CSV */
+    returnsSummaryCsv(filters?: ReturnsSummaryFilters): Promise<string>;
+    /** Get returns by reason report */
+    returnsReasons(filters?: ReturnsReasonsFilters): Promise<unknown>;
+    /** Get returns by reason as CSV */
+    returnsReasonsCsv(filters?: ReturnsReasonsFilters): Promise<string>;
+    /** Get returns overview report */
+    returnsOverview(filters?: ReturnsOverviewFilters): Promise<unknown>;
+    /** Get returns overview as CSV */
+    returnsOverviewCsv(filters?: ReturnsOverviewFilters): Promise<string>;
+    /** Get returns statistics for a client */
+    returnsStats(clientId: number): Promise<ReturnsStatsResponse>;
+}
+
+/**
+ * Return Entity
+ *
+ * Represents a customer return in the JANUS system.
+ */
+export declare interface Return extends BaseEntity {
+    /** Unique return reference */
+    return_reference?: string;
+    /** Associated WMS order reference */
+    wms_order_ref?: string;
+    /** Client ID */
+    client_id?: number;
+    /** Current status ID */
+    status_id?: number;
+    /** Return reason ID */
+    reason_id?: number;
+    /** Customer name */
+    customername?: string;
+    /** Customer forename */
+    forename?: string;
+    /** Customer surname */
+    surname?: string;
+    /** Customer email */
+    email?: string;
+    /** Tracking number */
+    tracking_number?: string;
+    /** Tracking URL */
+    tracking_url?: string;
+    /** Approval status */
+    approval_status?: ApprovalStatus;
+    /** Whether return is approved */
+    approved?: boolean;
+    /** Approval timestamp */
+    approved_ts?: string;
+    /** Address line 1 */
+    line_1?: string;
+    /** Address line 2 */
+    line_2?: string;
+    /** Address line 3 */
+    line_3?: string;
+    /** City */
+    city?: string;
+    /** County/State */
+    county?: string;
+    /** Country */
+    country?: string;
+    /** Country code */
+    country_code?: string;
+    /** Postcode */
+    postcode?: string;
+    /** Company name */
+    company?: string;
+    /** WMS service cost */
+    wms_service_cost?: number;
+    /** Courier service cost */
+    courier_service_cost?: number;
+    /** Courier service ID */
+    courier_service_id?: number;
+    /** Return items */
+    items?: ReturnItem[];
+    /** Return statuses history */
+    statuses?: ReturnStatusHistory[];
+    /** Return comments */
+    comments?: ReturnComment[];
+    /** Latest status */
+    latestStatus?: ReturnStatusHistory;
+}
+
+/**
+ * Return Category Entity
+ *
+ * Groups return reasons into categories.
+ */
+export declare interface ReturnCategory extends BaseEntity {
+    /** Category name */
+    name: string;
+    /** Whether category is active */
+    active?: boolean;
+}
+
+/**
+ * Return Comment Entity
+ *
+ * Represents a comment on a return.
+ */
+export declare interface ReturnComment extends BaseEntity {
+    /** Return ID */
+    return_id?: number;
+    /** Comment text */
+    comment?: string;
+    /** User who created the comment */
+    created_by_user?: {
+        id: number;
+        firstname?: string;
+        lastname?: string;
+        username?: string;
+    };
+}
+
+/**
+ * Return Item Entity
+ *
+ * Represents an item within a return.
+ */
+export declare interface ReturnItem extends BaseEntity {
+    /** Parent return ID */
+    return_id?: number;
+    /** WMS product SKU */
+    wms_product_sku?: string;
+    /** WMS product name */
+    wms_product_name?: string;
+    /** WMS product description */
+    wms_product_description?: string;
+    /** Quantity returned */
+    qty?: number;
+    /** Quantity restocked */
+    wms_restock_qty?: number;
+    /** Price paid per unit */
+    wms_price_paid?: number;
+    /** Customer note */
+    note?: string;
+    /** Return reason ID */
+    return_reason_id?: number;
+    /** Return reason */
+    return_reason?: ReturnReason;
+    /** WMS reason for non-restock */
+    wms_reason?: string;
+    /** WMS notes */
+    wms_notes?: string;
+}
+
+/**
+ * Return Reason Entity
+ *
+ * Defines a reason for returning items.
+ */
+export declare interface ReturnReason extends BaseEntity {
+    /** Reason name */
+    name: string;
+    /** Category ID */
+    category_id?: number;
+    /** Category */
+    category?: ReturnCategory;
+    /** Whether reason is active */
+    active?: boolean;
+}
+
+/**
+ * Filters for returns overview report
+ */
+export declare interface ReturnsOverviewFilters extends BaseFilters {
+    /** Filter by creation date from */
+    createdFrom?: string;
+    /** Filter by creation date to */
+    createdTo?: string;
+    /** Filter by client ID */
+    clientId?: number;
+    /** Include archived returns */
+    include_archived?: boolean;
+    /** Only show archived returns */
+    only_archived?: boolean;
+    /** Export as CSV */
+    csv?: boolean;
+}
+
+/**
+ * Filters for querying returns
+ */
+export declare interface ReturnsQueryFilters extends BaseFilters {
+    /** Filter by client ID */
+    clientId?: number;
+    /** Filter by last status IDs (comma-separated) */
+    last_status_ids?: string;
+    /** Include returns with these status IDs (comma-separated) */
+    include_status_ids?: string;
+    /** Exclude returns with these status IDs (comma-separated) */
+    exclude_status_ids?: string;
+    /** Filter by creation date from */
+    created_at?: string;
+    /** Filter by creation date to */
+    created_to?: string;
+    /** Filter by processed date from */
+    processed_at?: string;
+    /** Filter by processed date to */
+    processed_to?: string;
+    /** Minimum restock quantity */
+    min_restock_qty?: number;
+    /** Maximum restock quantity */
+    max_restock_qty?: number;
+    /** Export as CSV */
+    csv?: boolean;
+    /** Columns to include in response */
+    include_columns?: string;
+    /** Associations to include */
+    include_associations?: string;
+    /** Group results by field */
+    group_by?: string;
+}
+
+/**
+ * Filters for returns reasons report
+ */
+export declare interface ReturnsReasonsFilters extends BaseFilters {
+    /** Filter by creation date from */
+    createdFrom?: string;
+    /** Filter by creation date to */
+    createdTo?: string;
+    /** Filter by client ID */
+    clientId?: number;
+    /** Export as CSV */
+    csv?: boolean;
+}
+
+/**
+ * Returns resource interface
+ */
+export declare interface ReturnsResource {
+    /** Query returns with filters */
+    query(filters?: ReturnsQueryFilters): Promise<Return[]>;
+    /** Get a return by ID */
+    getById(id: number, options?: {
+        include_associations?: string;
+    }): Promise<Return>;
+    /** Create a new return (via helpers endpoint for portal access) */
+    create(data: CreateReturnRequest): Promise<Return>;
+    /** Update a return */
+    update(returnId: number, data: Partial<Return>): Promise<Return>;
+    /** Delete a return */
+    delete(returnId: number): Promise<void>;
+    /** Get all statuses for a return */
+    getStatuses(returnId: number): Promise<ReturnStatus[]>;
+    /** Add a status to a return */
+    addStatus(returnId: number, statusId: number): Promise<unknown>;
+    /** Remove a specific status from a return */
+    removeStatus(returnId: number, statusId: number): Promise<void>;
+    /** Get return items for a return */
+    getItems(returnId: number): Promise<ReturnItem[]>;
+    /** Add an item to a return */
+    addItem(returnId: number, item: CreateReturnItemRequest): Promise<ReturnItem>;
+    /** Update a return item */
+    updateItem(returnId: number, itemId: number, data: Partial<ReturnItem>): Promise<ReturnItem>;
+    /** Get comments for a return */
+    getComments(returnId: number): Promise<ReturnComment[]>;
+    /** Add a comment to a return */
+    addComment(returnId: number, comment: string): Promise<ReturnComment>;
+    /** Remove a comment from a return */
+    removeComment(returnId: number, commentId: number): Promise<void>;
+    /** Set approval status for a return */
+    setApproval(returnId: number, approved: boolean): Promise<unknown>;
+    /** Get all return reasons (reference data) */
+    getReasons(): Promise<ReturnReason[]>;
+    /** Get all return statuses (reference data) */
+    getAllStatuses(): Promise<ReturnStatus[]>;
+    /** Get filter options for returns */
+    getFilterOptions(clientId: number): Promise<FilterOptionsResponse>;
+}
+
+/**
+ * Returns stats response
+ */
+export declare interface ReturnsStatsResponse {
+    /** Total returns count */
+    total?: number;
+    /** Returns awaiting processing */
+    awaiting_processing?: number;
+    /** Returns in progress */
+    in_progress?: number;
+    /** Returns completed */
+    completed?: number;
+    /** Returns requiring approval */
+    awaiting_approval?: number;
+    /** Returns approved */
+    approved?: number;
+    /** Returns rejected */
+    rejected?: number;
+    /** Stats by status */
+    by_status?: Record<string, number>;
+    /** Stats by reason */
+    by_reason?: Record<string, number>;
+}
+
+/**
+ * Filters for returns summary report
+ */
+export declare interface ReturnsSummaryFilters extends BaseFilters {
+    /** Filter by creation date from */
+    createdFrom?: string;
+    /** Filter by creation date to */
+    createdTo?: string;
+    /** Filter by approval date from */
+    approvedFrom?: string;
+    /** Filter by approval date to */
+    approvedTo?: string;
+    /** Filter by client ID */
+    clientId?: number;
+    /** Filter by courier service ID */
+    courierServiceId?: number;
+    /** Filter by approval status */
+    approved?: boolean;
+    /** Include approval description */
+    approvedWithDesc?: boolean;
+    /** Generate clients report */
+    isClientsReport?: boolean;
+    /** Export as CSV */
+    csv?: boolean;
+}
+
+/**
+ * Returns summary report response
+ */
+export declare interface ReturnsSummaryResponse {
+    /** Summary data */
+    data: Array<{
+        /** Client ID */
+        client_id?: number;
+        /** Client name */
+        client_name?: string;
+        /** Total returns */
+        total_returns?: number;
+        /** Total items */
+        total_items?: number;
+        /** Total value */
+        total_value?: number;
+        /** Date */
+        date?: string;
+        [key: string]: unknown;
+    }>;
+}
+
+/**
+ * Return Status Entity
+ *
+ * Defines a status that can be applied to returns.
+ */
+export declare interface ReturnStatus extends BaseEntity {
+    /** Status name */
+    name: string;
+    /** Display color */
+    color?: string;
+    /** Sort order */
+    sort_order?: number;
+    /** Whether this is a final status */
+    is_final?: boolean;
+    /** Whether this status requires approval */
+    requires_approval?: boolean;
+}
+
+/**
+ * Return Status History Entry
+ *
+ * Tracks when a status was applied to a return.
+ */
+export declare interface ReturnStatusHistory extends BaseEntity {
+    /** Return ID */
+    return_id?: number;
+    /** Status ID */
+    return_status_id?: number;
+    /** The status */
+    return_status?: ReturnStatus;
+}
+
+/**
+ * Data for setting return approval
+ */
+export declare interface SetReturnApprovalRequest {
+    /** Whether to approve the return */
+    approve: boolean;
+}
+
+/**
+ * Error thrown when authentication fails (401)
+ */
+export declare class UnauthorizedError extends JanusApiError {
+    constructor(message?: string, response?: unknown);
+}
+
+/**
+ * Data for updating a client
+ */
+export declare interface UpdateClientRequest {
+    /** Client name */
+    name?: string;
+    /** Short name */
+    short_name?: string;
+    /** Email */
+    email?: string;
+    /** Phone */
+    phone?: string;
+    /** Operational status */
+    operational_status?: string;
+    /** Settings object */
+    settings?: Record<string, unknown>;
+    /** Whether returns require approval */
+    requires_approval?: boolean;
+    /** Default courier service ID */
+    default_courier_service_id?: number;
+    /** Whether client is active */
+    active?: boolean;
+}
+
+/**
+ * Data for uploading a file
+ */
+export declare interface UploadFileRequest {
+    /** File content type (e.g., 'image/png') */
+    contentType: string;
+    /** File as base64 encoded string (without prefix) */
+    fileBase64: string;
+    /** Source of the upload */
+    from?: string;
+}
+
+/**
+ * File upload response
+ */
+export declare interface UploadFileResponse {
+    /** URL of the uploaded file */
+    url: string;
+}
+
+/**
+ * User Entity
+ *
+ * Represents a user in the JANUS system.
+ */
+export declare interface User extends BaseEntity {
+    /** Username for login */
+    username: string;
+    /** User's first name */
+    firstname?: string;
+    /** User's last name */
+    lastname?: string;
+    /** Whether user is an admin */
+    isAdmin?: boolean;
+    /** API key for programmatic access */
+    api_key?: string;
+    /** Legacy user ID for migration */
+    legacy_user_id?: number;
+}
+
+/**
+ * Client access entry for a user
+ */
+export declare interface UserClientAccess {
+    /** Client ID */
+    id: number;
+    /** Client name */
+    name: string;
+}
+
+/**
+ * Error thrown for validation errors (400)
+ */
+export declare class ValidationError extends JanusApiError {
+    /** Validation error details */
+    readonly errors?: Record<string, string[]>;
+    constructor(message?: string, errors?: Record<string, string[]>, response?: unknown);
+}
+
+export { }