@heymantle/core-api-client 0.1.3 → 0.1.5

package/dist/index.d.mts

@@ -1,3 +1,89 @@
+/**
+ * Middleware types for the Mantle Core API Client
+ */
+/**
+ * HTTP methods supported by the client
+ */
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE';
+/**
+ * Request information passed through the middleware chain
+ */
+interface MiddlewareRequest {
+    /** Full URL (baseURL + endpoint) */
+    url: string;
+    /** HTTP method */
+    method: HttpMethod;
+    /** Request headers */
+    headers: Record<string, string>;
+    /** Request body (for POST/PUT) */
+    body?: string;
+    /** Original endpoint (before baseURL prepend) */
+    endpoint: string;
+}
+/**
+ * Response information returned through the middleware chain
+ */
+interface MiddlewareResponse<T = unknown> {
+    /** Parsed response data */
+    data: T;
+    /** HTTP status code */
+    status: number;
+    /** Response headers */
+    headers: Headers;
+}
+/**
+ * Context object passed to middleware functions
+ */
+interface MiddlewareContext<T = unknown> {
+    /** The request being made */
+    request: MiddlewareRequest;
+    /** The response (populated after downstream execution) */
+    response?: MiddlewareResponse<T>;
+    /** Error that occurred (if any) */
+    error?: Error;
+    /** Set to true to retry the request */
+    retry: boolean;
+    /** Number of retry attempts made */
+    retryCount: number;
+    /** Maximum retry attempts allowed (default: 3) */
+    maxRetries: number;
+    /** Update the client's auth credentials */
+    updateAuth: (credentials: {
+        apiKey?: string;
+        accessToken?: string;
+    }) => void;
+}
+/**
+ * Next function to call the next middleware in the chain
+ */
+type NextFunction = () => Promise<void>;
+/**
+ * Middleware function signature (Koa-style)
+ *
+ * @example
+ * ```typescript
+ * const loggingMiddleware: Middleware = async (ctx, next) => {
+ *   console.log('Request:', ctx.request.url)
+ *   await next()
+ *   console.log('Response:', ctx.response?.status)
+ * }
+ * ```
+ */
+type Middleware<T = unknown> = (ctx: MiddlewareContext<T>, next: NextFunction) => Promise<void>;
+/**
+ * Options for registering middleware
+ */
+interface MiddlewareOptions {
+    /** Unique name for debugging/removal */
+    name?: string;
+    /** Priority (lower = earlier execution, default: 100) */
+    priority?: number;
+}
+
+/**
+ * Middleware configuration item
+ */
+type MiddlewareConfig = Middleware | [Middleware, MiddlewareOptions];
 /**
  * Configuration for the MantleCoreClient
  */
@@ -10,6 +96,8 @@ interface MantleCoreClientConfig {
     accessToken?: string;
     /** Request timeout in milliseconds. Defaults to 30000 */
     timeout?: number;
+    /** Middleware to register on instantiation */
+    middleware?: MiddlewareConfig[];
 }
 /**
  * Generic paginated list response
@@ -734,6 +822,54 @@ interface DealListParams extends ListParams {
 interface DealListResponse extends PaginatedResponse {
     deals: Deal[];
 }
+/**
+ * Inline customer data for deal creation/update.
+ * Matches existing customers by domain or shopifyDomain.
+ * If no match found, creates a new customer.
+ */
+interface DealCustomerInput {
+    /** The name of the customer */
+    name?: string;
+    /** The email of the customer */
+    email?: string;
+    /** The domain of the customer (used for matching existing customers) */
+    domain?: string;
+    /** The Shopify domain of the customer (used for matching existing customers) */
+    shopifyDomain?: string;
+    /** The Shopify shop ID */
+    shopifyShopId?: string;
+    /** Tags to associate with the customer */
+    tags?: string[];
+    /** Custom fields for the customer */
+    customFields?: Record<string, unknown>;
+    /** The country code of the customer */
+    countryCode?: string;
+    /** The preferred currency of the customer */
+    preferredCurrency?: string;
+    /** Description of the customer */
+    description?: string;
+}
+/**
+ * Inline contact data for deal creation/update.
+ * Matches existing contacts by email.
+ * Contacts are linked to both the customer and the deal.
+ */
+interface DealContactInput {
+    /** The email of the contact (required, used for matching existing contacts) */
+    email: string;
+    /** The name of the contact */
+    name?: string;
+    /** The phone number of the contact */
+    phone?: string;
+    /** The job title of the contact */
+    jobTitle?: string;
+    /** The label for the contact relationship (e.g., "primary", "technical") */
+    label?: string;
+    /** Notes about the contact */
+    notes?: string;
+    /** Tags for the contact */
+    tags?: string[];
+}
 /**
  * Parameters for creating a deal
  */
@@ -748,14 +884,26 @@ interface DealCreateParams {
     closedAt?: string;
     dealFlowId?: string;
     dealStageId?: string;
+    /** The ID of an existing customer (alternative to customer object) */
     customerId?: string;
+    /**
+     * Create or update a customer inline (alternative to customerId).
+     * Matches existing customers by domain or shopifyDomain.
+     */
+    customer?: DealCustomerInput;
     domain?: string;
     shopifyDomain?: string;
     companyId?: string;
     appId?: string;
     planId?: string;
     ownerIds?: string[];
+    /** Array of existing contact IDs (alternative to contacts array) */
     contactIds?: string[];
+    /**
+     * Create or update contacts inline (alternative to contactIds).
+     * Matches existing contacts by email. Contacts are linked to both the customer and the deal.
+     */
+    contacts?: DealContactInput[];
     notes?: string;
     affiliateId?: string;
     partnershipId?: string;
@@ -2850,9 +2998,10 @@ declare class EntitiesResource extends BaseResource {
  */
 declare class MantleCoreClient {
     private readonly baseURL;
-    private readonly apiKey?;
-    private readonly accessToken?;
+    private apiKey?;
+    private accessToken?;
     private readonly timeout;
+    private readonly middlewareManager;
     readonly customers: CustomersResource;
     readonly contacts: ContactsResource;
     readonly subscriptions: SubscriptionsResource;
@@ -2883,6 +3032,40 @@ declare class MantleCoreClient {
     readonly docs: DocsResource;
     readonly entities: EntitiesResource;
     constructor(config: MantleCoreClientConfig);
+    /**
+     * Register a middleware function
+     *
+     * @param middleware - The middleware function to register
+     * @param options - Optional configuration (name, priority)
+     * @returns this for chaining
+     *
+     * @example
+     * ```typescript
+     * client.use(async (ctx, next) => {
+     *   console.log('Request:', ctx.request.url);
+     *   await next();
+     *   console.log('Response:', ctx.response?.status);
+     * });
+     * ```
+     */
+    use(middleware: Middleware, options?: MiddlewareOptions): this;
+    /**
+     * Remove a middleware by name
+     *
+     * @param name - The name of the middleware to remove
+     * @returns true if removed, false if not found
+     */
+    removeMiddleware(name: string): boolean;
+    /**
+     * Update authentication credentials
+     * Useful for middleware that needs to refresh tokens
+     *
+     * @param credentials - New credentials to set
+     */
+    updateAuth(credentials: {
+        apiKey?: string;
+        accessToken?: string;
+    }): void;
     /**
      * Performs a GET request to the API
      */
@@ -2903,6 +3086,14 @@ declare class MantleCoreClient {
      * Makes an HTTP request to the API
      */
     private makeRequest;
+    /**
+     * Execute request through middleware chain
+     */
+    private makeRequestWithMiddleware;
+    /**
+     * Direct request execution (no middleware)
+     */
+    private executeRequest;
     /**
      * Gets the authorization header value
      */
@@ -2957,4 +3148,92 @@ declare class MantleRateLimitError extends MantleAPIError {
     constructor(message?: string, retryAfter?: number);
 }
 
-export { type AccountOwner, type AccountOwnersListResponse, type Affiliate, type AffiliateCommission, type AffiliateCommissionListParams, type AffiliateCommissionListResponse, AffiliateCommissionsResource, type AffiliateListParams, type AffiliateListResponse, type AffiliatePayout, type AffiliatePayoutListParams, type AffiliatePayoutListResponse, AffiliatePayoutsResource, type AffiliateProgram, type AffiliateProgramCreateParams, type AffiliateProgramUpdateParams, AffiliateProgramsResource, type AffiliateReferral, type AffiliateReferralListParams, type AffiliateReferralListResponse, AffiliateReferralsResource, type AffiliateUpdateParams, AffiliatesResource, type Agent, type AgentListResponse, AgentsResource, type App, type AppEvent, type AppEventListParams, type AppEventListResponse, type AppInstallation, type AppInstallationParams, type AppListParams, AppsResource, BaseResource, type Channel, type ChannelCreateParams, type ChannelListParams, ChannelsResource, type Charge, type ChargeListParams, type ChargeListResponse, ChargesResource, CompaniesResource, type Company, type CompanyCreateParams, type CompanyListParams, type CompanyListResponse, type CompanyUpdateParams, type Contact, type ContactCreateParams, type ContactEntity, type ContactListParams, type ContactListResponse, type ContactUpdateParams, ContactsResource, type CustomField, type CustomFieldCreateParams, type CustomFieldUpdateParams, type Customer, type CustomerCreateParams, type CustomerEntity, type CustomerListParams, type CustomerListResponse, type CustomerRetrieveParams, type CustomerSegment, type CustomerSegmentListParams, type CustomerSegmentListResponse, CustomerSegmentsResource, type CustomerUpdateParams, CustomersResource, type DateRangeType, type Deal, DealActivitiesResource, type DealActivity, type DealActivityCreateParams, type DealActivityUpdateParams, type DealCreateParams, type DealFlow, type DealFlowCreateParams, type DealFlowUpdateParams, DealFlowsResource, type DealListParams, type DealListResponse, type DealStage, type DealUpdateParams, DealsResource, type DeleteResponse, type DocCollection, type DocCollectionCreateParams, type DocCollectionUpdateParams, type DocGroup, type DocGroupCreateParams, type DocGroupUpdateParams, type DocPage, type DocPageCreateParams, type DocPageListParams, type DocPageListResponse, type DocPageStatus, type DocPageUpdateParams, type DocTreeNode, type DocTreeResponse, DocsResource, EntitiesResource, type EntitiesSearchParams, type EntitiesSearchResponse, type Entity, type EntityType, type Feature, type FeatureCreateParams, type FeatureUpdateParams, type Flow, type FlowCreateParams, type FlowListParams, type FlowListResponse, type FlowStatus, type FlowUpdateParams, FlowsResource, type ListParams, MantleAPIError, MantleAuthenticationError, MantleCoreClient, type MantleCoreClientConfig, MantleNotFoundError, MantlePermissionError, MantleRateLimitError, MantleValidationError, MeResource, type MeResponse, type MessageAttachment, type MetricDataPoint, type MetricType, type MetricsBaseParams, type MetricsGetParams, MetricsResource, type MetricsResponse, type Organization, OrganizationResource, type PaginatedResponse, type Plan, type PlanCreateParams, type PlanFeature, type PlanListParams, type PlanListResponse, type PlanUpdateParams, type PlanUsageCharge, type RequestOptions, type Review, type ReviewCreateParams, type ReviewUpdateParams, type SocialProfile, type SocialProfileType, type Subscription, type SubscriptionListParams, type SubscriptionListResponse, SubscriptionsResource, type Task, type TaskCreateParams, type TaskListParams, type TaskListResponse, type TaskPriority, type TaskStatus, type TaskUpdateParams, TasksResource, type Ticket, type TicketContactData, type TicketCreateParams, type TicketListParams, type TicketListResponse, type TicketMessage, type TicketMessageCreateParams, type TicketMessageUpdateParams, type TicketUpdateParams, TicketsResource, type TimelineEvent, type TimelineListParams, type TimelineListResponse, type Transaction, type TransactionListParams, type TransactionListResponse, TransactionsResource, type UsageEvent, type UsageEventCreateData, type UsageEventCreateParams, type UsageEventCreateResponse, type UsageEventListParams, type UsageEventListResponse, type UsageEventMetricsParams, UsageEventsResource, type UsageMetric, type UsageMetricCreateParams, type UsageMetricParams, type UsageMetricUpdateParams, type User, type UserListParams, type UserListResponse, UsersResource, type Webhook, type WebhookCreateParams, type WebhookFilter, type WebhookListResponse, type WebhookTopic, type WebhookUpdateParams, WebhooksResource };
+/**
+ * Manages middleware registration and execution
+ */
+declare class MiddlewareManager {
+    private middlewares;
+    /**
+     * Register a middleware function
+     *
+     * @param middleware - The middleware function to register
+     * @param options - Optional configuration
+     * @returns this for chaining
+     */
+    use(middleware: Middleware, options?: MiddlewareOptions): this;
+    /**
+     * Remove a middleware by name
+     *
+     * @param name - The name of the middleware to remove
+     * @returns true if removed, false if not found
+     */
+    remove(name: string): boolean;
+    /**
+     * Get all registered middleware names
+     */
+    list(): string[];
+    /**
+     * Check if any middleware is registered
+     */
+    hasMiddleware(): boolean;
+    /**
+     * Execute the middleware chain with retry support
+     *
+     * @param ctx - The middleware context
+     * @param coreHandler - The core request handler to call at the end of the chain
+     * @returns The response from the core handler
+     */
+    execute<T>(ctx: MiddlewareContext<T>, coreHandler: () => Promise<MiddlewareResponse<T>>): Promise<MiddlewareResponse<T>>;
+    /**
+     * Run the middleware chain (onion model)
+     */
+    private runChain;
+}
+
+/**
+ * Options for the auth refresh middleware
+ */
+interface AuthRefreshOptions {
+    /**
+     * Function to refresh the access token
+     * Should return the new access token
+     */
+    refreshToken: () => Promise<string>;
+    /**
+     * Optional callback when refresh succeeds
+     */
+    onRefreshSuccess?: (newToken: string) => void;
+    /**
+     * Optional callback when refresh fails
+     */
+    onRefreshFailed?: (error: Error) => void;
+    /**
+     * Maximum refresh attempts per request (default: 1)
+     */
+    maxRefreshAttempts?: number;
+}
+/**
+ * Creates a middleware that automatically refreshes access tokens on 401 errors
+ *
+ * @example
+ * ```typescript
+ * const client = new MantleCoreClient({
+ *   accessToken: 'initial-token',
+ * });
+ *
+ * client.use(createAuthRefreshMiddleware({
+ *   refreshToken: async () => {
+ *     const response = await fetch('/refresh', { method: 'POST' });
+ *     const data = await response.json();
+ *     return data.accessToken;
+ *   },
+ *   onRefreshSuccess: (newToken) => {
+ *     // Persist the new token
+ *     localStorage.setItem('accessToken', newToken);
+ *   },
+ * }), { name: 'auth-refresh' });
+ * ```
+ */
+declare function createAuthRefreshMiddleware(options: AuthRefreshOptions): Middleware;
+
+export { type AccountOwner, type AccountOwnersListResponse, type Affiliate, type AffiliateCommission, type AffiliateCommissionListParams, type AffiliateCommissionListResponse, AffiliateCommissionsResource, type AffiliateListParams, type AffiliateListResponse, type AffiliatePayout, type AffiliatePayoutListParams, type AffiliatePayoutListResponse, AffiliatePayoutsResource, type AffiliateProgram, type AffiliateProgramCreateParams, type AffiliateProgramUpdateParams, AffiliateProgramsResource, type AffiliateReferral, type AffiliateReferralListParams, type AffiliateReferralListResponse, AffiliateReferralsResource, type AffiliateUpdateParams, AffiliatesResource, type Agent, type AgentListResponse, AgentsResource, type App, type AppEvent, type AppEventListParams, type AppEventListResponse, type AppInstallation, type AppInstallationParams, type AppListParams, AppsResource, type AuthRefreshOptions, BaseResource, type Channel, type ChannelCreateParams, type ChannelListParams, ChannelsResource, type Charge, type ChargeListParams, type ChargeListResponse, ChargesResource, CompaniesResource, type Company, type CompanyCreateParams, type CompanyListParams, type CompanyListResponse, type CompanyUpdateParams, type Contact, type ContactCreateParams, type ContactEntity, type ContactListParams, type ContactListResponse, type ContactUpdateParams, ContactsResource, type CustomField, type CustomFieldCreateParams, type CustomFieldUpdateParams, type Customer, type CustomerCreateParams, type CustomerEntity, type CustomerListParams, type CustomerListResponse, type CustomerRetrieveParams, type CustomerSegment, type CustomerSegmentListParams, type CustomerSegmentListResponse, CustomerSegmentsResource, type CustomerUpdateParams, CustomersResource, type DateRangeType, type Deal, DealActivitiesResource, type DealActivity, type DealActivityCreateParams, type DealActivityUpdateParams, type DealContactInput, type DealCreateParams, type DealCustomerInput, type DealFlow, type DealFlowCreateParams, type DealFlowUpdateParams, DealFlowsResource, type DealListParams, type DealListResponse, type DealStage, type DealUpdateParams, DealsResource, type DeleteResponse, type DocCollection, type DocCollectionCreateParams, type DocCollectionUpdateParams, type DocGroup, type DocGroupCreateParams, type DocGroupUpdateParams, type DocPage, type DocPageCreateParams, type DocPageListParams, type DocPageListResponse, type DocPageStatus, type DocPageUpdateParams, type DocTreeNode, type DocTreeResponse, DocsResource, EntitiesResource, type EntitiesSearchParams, type EntitiesSearchResponse, type Entity, type EntityType, type Feature, type FeatureCreateParams, type FeatureUpdateParams, type Flow, type FlowCreateParams, type FlowListParams, type FlowListResponse, type FlowStatus, type FlowUpdateParams, FlowsResource, type HttpMethod, type ListParams, MantleAPIError, MantleAuthenticationError, MantleCoreClient, type MantleCoreClientConfig, MantleNotFoundError, MantlePermissionError, MantleRateLimitError, MantleValidationError, MeResource, type MeResponse, type MessageAttachment, type MetricDataPoint, type MetricType, type MetricsBaseParams, type MetricsGetParams, MetricsResource, type MetricsResponse, type Middleware, type MiddlewareContext, MiddlewareManager, type MiddlewareOptions, type MiddlewareRequest, type MiddlewareResponse, type NextFunction, type Organization, OrganizationResource, type PaginatedResponse, type Plan, type PlanCreateParams, type PlanFeature, type PlanListParams, type PlanListResponse, type PlanUpdateParams, type PlanUsageCharge, type RequestOptions, type Review, type ReviewCreateParams, type ReviewUpdateParams, type SocialProfile, type SocialProfileType, type Subscription, type SubscriptionListParams, type SubscriptionListResponse, SubscriptionsResource, type Task, type TaskCreateParams, type TaskListParams, type TaskListResponse, type TaskPriority, type TaskStatus, type TaskUpdateParams, TasksResource, type Ticket, type TicketContactData, type TicketCreateParams, type TicketListParams, type TicketListResponse, type TicketMessage, type TicketMessageCreateParams, type TicketMessageUpdateParams, type TicketUpdateParams, TicketsResource, type TimelineEvent, type TimelineListParams, type TimelineListResponse, type Transaction, type TransactionListParams, type TransactionListResponse, TransactionsResource, type UsageEvent, type UsageEventCreateData, type UsageEventCreateParams, type UsageEventCreateResponse, type UsageEventListParams, type UsageEventListResponse, type UsageEventMetricsParams, UsageEventsResource, type UsageMetric, type UsageMetricCreateParams, type UsageMetricParams, type UsageMetricUpdateParams, type User, type UserListParams, type UserListResponse, UsersResource, type Webhook, type WebhookCreateParams, type WebhookFilter, type WebhookListResponse, type WebhookTopic, type WebhookUpdateParams, WebhooksResource, createAuthRefreshMiddleware };

package/dist/index.d.ts

@@ -1,3 +1,89 @@
+/**
+ * Middleware types for the Mantle Core API Client
+ */
+/**
+ * HTTP methods supported by the client
+ */
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE';
+/**
+ * Request information passed through the middleware chain
+ */
+interface MiddlewareRequest {
+    /** Full URL (baseURL + endpoint) */
+    url: string;
+    /** HTTP method */
+    method: HttpMethod;
+    /** Request headers */
+    headers: Record<string, string>;
+    /** Request body (for POST/PUT) */
+    body?: string;
+    /** Original endpoint (before baseURL prepend) */
+    endpoint: string;
+}
+/**
+ * Response information returned through the middleware chain
+ */
+interface MiddlewareResponse<T = unknown> {
+    /** Parsed response data */
+    data: T;
+    /** HTTP status code */
+    status: number;
+    /** Response headers */
+    headers: Headers;
+}
+/**
+ * Context object passed to middleware functions
+ */
+interface MiddlewareContext<T = unknown> {
+    /** The request being made */
+    request: MiddlewareRequest;
+    /** The response (populated after downstream execution) */
+    response?: MiddlewareResponse<T>;
+    /** Error that occurred (if any) */
+    error?: Error;
+    /** Set to true to retry the request */
+    retry: boolean;
+    /** Number of retry attempts made */
+    retryCount: number;
+    /** Maximum retry attempts allowed (default: 3) */
+    maxRetries: number;
+    /** Update the client's auth credentials */
+    updateAuth: (credentials: {
+        apiKey?: string;
+        accessToken?: string;
+    }) => void;
+}
+/**
+ * Next function to call the next middleware in the chain
+ */
+type NextFunction = () => Promise<void>;
+/**
+ * Middleware function signature (Koa-style)
+ *
+ * @example
+ * ```typescript
+ * const loggingMiddleware: Middleware = async (ctx, next) => {
+ *   console.log('Request:', ctx.request.url)
+ *   await next()
+ *   console.log('Response:', ctx.response?.status)
+ * }
+ * ```
+ */
+type Middleware<T = unknown> = (ctx: MiddlewareContext<T>, next: NextFunction) => Promise<void>;
+/**
+ * Options for registering middleware
+ */
+interface MiddlewareOptions {
+    /** Unique name for debugging/removal */
+    name?: string;
+    /** Priority (lower = earlier execution, default: 100) */
+    priority?: number;
+}
+
+/**
+ * Middleware configuration item
+ */
+type MiddlewareConfig = Middleware | [Middleware, MiddlewareOptions];
 /**
  * Configuration for the MantleCoreClient
  */
@@ -10,6 +96,8 @@ interface MantleCoreClientConfig {
     accessToken?: string;
     /** Request timeout in milliseconds. Defaults to 30000 */
     timeout?: number;
+    /** Middleware to register on instantiation */
+    middleware?: MiddlewareConfig[];
 }
 /**
  * Generic paginated list response
@@ -734,6 +822,54 @@ interface DealListParams extends ListParams {
 interface DealListResponse extends PaginatedResponse {
     deals: Deal[];
 }
+/**
+ * Inline customer data for deal creation/update.
+ * Matches existing customers by domain or shopifyDomain.
+ * If no match found, creates a new customer.
+ */
+interface DealCustomerInput {
+    /** The name of the customer */
+    name?: string;
+    /** The email of the customer */
+    email?: string;
+    /** The domain of the customer (used for matching existing customers) */
+    domain?: string;
+    /** The Shopify domain of the customer (used for matching existing customers) */
+    shopifyDomain?: string;
+    /** The Shopify shop ID */
+    shopifyShopId?: string;
+    /** Tags to associate with the customer */
+    tags?: string[];
+    /** Custom fields for the customer */
+    customFields?: Record<string, unknown>;
+    /** The country code of the customer */
+    countryCode?: string;
+    /** The preferred currency of the customer */
+    preferredCurrency?: string;
+    /** Description of the customer */
+    description?: string;
+}
+/**
+ * Inline contact data for deal creation/update.
+ * Matches existing contacts by email.
+ * Contacts are linked to both the customer and the deal.
+ */
+interface DealContactInput {
+    /** The email of the contact (required, used for matching existing contacts) */
+    email: string;
+    /** The name of the contact */
+    name?: string;
+    /** The phone number of the contact */
+    phone?: string;
+    /** The job title of the contact */
+    jobTitle?: string;
+    /** The label for the contact relationship (e.g., "primary", "technical") */
+    label?: string;
+    /** Notes about the contact */
+    notes?: string;
+    /** Tags for the contact */
+    tags?: string[];
+}
 /**
  * Parameters for creating a deal
  */
@@ -748,14 +884,26 @@ interface DealCreateParams {
     closedAt?: string;
     dealFlowId?: string;
     dealStageId?: string;
+    /** The ID of an existing customer (alternative to customer object) */
     customerId?: string;
+    /**
+     * Create or update a customer inline (alternative to customerId).
+     * Matches existing customers by domain or shopifyDomain.
+     */
+    customer?: DealCustomerInput;
     domain?: string;
     shopifyDomain?: string;
     companyId?: string;
     appId?: string;
     planId?: string;
     ownerIds?: string[];
+    /** Array of existing contact IDs (alternative to contacts array) */
     contactIds?: string[];
+    /**
+     * Create or update contacts inline (alternative to contactIds).
+     * Matches existing contacts by email. Contacts are linked to both the customer and the deal.
+     */
+    contacts?: DealContactInput[];
     notes?: string;
     affiliateId?: string;
     partnershipId?: string;
@@ -2850,9 +2998,10 @@ declare class EntitiesResource extends BaseResource {
  */
 declare class MantleCoreClient {
     private readonly baseURL;
-    private readonly apiKey?;
-    private readonly accessToken?;
+    private apiKey?;
+    private accessToken?;
     private readonly timeout;
+    private readonly middlewareManager;
     readonly customers: CustomersResource;
     readonly contacts: ContactsResource;
     readonly subscriptions: SubscriptionsResource;
@@ -2883,6 +3032,40 @@ declare class MantleCoreClient {
     readonly docs: DocsResource;
     readonly entities: EntitiesResource;
     constructor(config: MantleCoreClientConfig);
+    /**
+     * Register a middleware function
+     *
+     * @param middleware - The middleware function to register
+     * @param options - Optional configuration (name, priority)
+     * @returns this for chaining
+     *
+     * @example
+     * ```typescript
+     * client.use(async (ctx, next) => {
+     *   console.log('Request:', ctx.request.url);
+     *   await next();
+     *   console.log('Response:', ctx.response?.status);
+     * });
+     * ```
+     */
+    use(middleware: Middleware, options?: MiddlewareOptions): this;
+    /**
+     * Remove a middleware by name
+     *
+     * @param name - The name of the middleware to remove
+     * @returns true if removed, false if not found
+     */
+    removeMiddleware(name: string): boolean;
+    /**
+     * Update authentication credentials
+     * Useful for middleware that needs to refresh tokens
+     *
+     * @param credentials - New credentials to set
+     */
+    updateAuth(credentials: {
+        apiKey?: string;
+        accessToken?: string;
+    }): void;
     /**
      * Performs a GET request to the API
      */
@@ -2903,6 +3086,14 @@ declare class MantleCoreClient {
      * Makes an HTTP request to the API
      */
     private makeRequest;
+    /**
+     * Execute request through middleware chain
+     */
+    private makeRequestWithMiddleware;
+    /**
+     * Direct request execution (no middleware)
+     */
+    private executeRequest;
     /**
      * Gets the authorization header value
      */
@@ -2957,4 +3148,92 @@ declare class MantleRateLimitError extends MantleAPIError {
     constructor(message?: string, retryAfter?: number);
 }
 
-export { type AccountOwner, type AccountOwnersListResponse, type Affiliate, type AffiliateCommission, type AffiliateCommissionListParams, type AffiliateCommissionListResponse, AffiliateCommissionsResource, type AffiliateListParams, type AffiliateListResponse, type AffiliatePayout, type AffiliatePayoutListParams, type AffiliatePayoutListResponse, AffiliatePayoutsResource, type AffiliateProgram, type AffiliateProgramCreateParams, type AffiliateProgramUpdateParams, AffiliateProgramsResource, type AffiliateReferral, type AffiliateReferralListParams, type AffiliateReferralListResponse, AffiliateReferralsResource, type AffiliateUpdateParams, AffiliatesResource, type Agent, type AgentListResponse, AgentsResource, type App, type AppEvent, type AppEventListParams, type AppEventListResponse, type AppInstallation, type AppInstallationParams, type AppListParams, AppsResource, BaseResource, type Channel, type ChannelCreateParams, type ChannelListParams, ChannelsResource, type Charge, type ChargeListParams, type ChargeListResponse, ChargesResource, CompaniesResource, type Company, type CompanyCreateParams, type CompanyListParams, type CompanyListResponse, type CompanyUpdateParams, type Contact, type ContactCreateParams, type ContactEntity, type ContactListParams, type ContactListResponse, type ContactUpdateParams, ContactsResource, type CustomField, type CustomFieldCreateParams, type CustomFieldUpdateParams, type Customer, type CustomerCreateParams, type CustomerEntity, type CustomerListParams, type CustomerListResponse, type CustomerRetrieveParams, type CustomerSegment, type CustomerSegmentListParams, type CustomerSegmentListResponse, CustomerSegmentsResource, type CustomerUpdateParams, CustomersResource, type DateRangeType, type Deal, DealActivitiesResource, type DealActivity, type DealActivityCreateParams, type DealActivityUpdateParams, type DealCreateParams, type DealFlow, type DealFlowCreateParams, type DealFlowUpdateParams, DealFlowsResource, type DealListParams, type DealListResponse, type DealStage, type DealUpdateParams, DealsResource, type DeleteResponse, type DocCollection, type DocCollectionCreateParams, type DocCollectionUpdateParams, type DocGroup, type DocGroupCreateParams, type DocGroupUpdateParams, type DocPage, type DocPageCreateParams, type DocPageListParams, type DocPageListResponse, type DocPageStatus, type DocPageUpdateParams, type DocTreeNode, type DocTreeResponse, DocsResource, EntitiesResource, type EntitiesSearchParams, type EntitiesSearchResponse, type Entity, type EntityType, type Feature, type FeatureCreateParams, type FeatureUpdateParams, type Flow, type FlowCreateParams, type FlowListParams, type FlowListResponse, type FlowStatus, type FlowUpdateParams, FlowsResource, type ListParams, MantleAPIError, MantleAuthenticationError, MantleCoreClient, type MantleCoreClientConfig, MantleNotFoundError, MantlePermissionError, MantleRateLimitError, MantleValidationError, MeResource, type MeResponse, type MessageAttachment, type MetricDataPoint, type MetricType, type MetricsBaseParams, type MetricsGetParams, MetricsResource, type MetricsResponse, type Organization, OrganizationResource, type PaginatedResponse, type Plan, type PlanCreateParams, type PlanFeature, type PlanListParams, type PlanListResponse, type PlanUpdateParams, type PlanUsageCharge, type RequestOptions, type Review, type ReviewCreateParams, type ReviewUpdateParams, type SocialProfile, type SocialProfileType, type Subscription, type SubscriptionListParams, type SubscriptionListResponse, SubscriptionsResource, type Task, type TaskCreateParams, type TaskListParams, type TaskListResponse, type TaskPriority, type TaskStatus, type TaskUpdateParams, TasksResource, type Ticket, type TicketContactData, type TicketCreateParams, type TicketListParams, type TicketListResponse, type TicketMessage, type TicketMessageCreateParams, type TicketMessageUpdateParams, type TicketUpdateParams, TicketsResource, type TimelineEvent, type TimelineListParams, type TimelineListResponse, type Transaction, type TransactionListParams, type TransactionListResponse, TransactionsResource, type UsageEvent, type UsageEventCreateData, type UsageEventCreateParams, type UsageEventCreateResponse, type UsageEventListParams, type UsageEventListResponse, type UsageEventMetricsParams, UsageEventsResource, type UsageMetric, type UsageMetricCreateParams, type UsageMetricParams, type UsageMetricUpdateParams, type User, type UserListParams, type UserListResponse, UsersResource, type Webhook, type WebhookCreateParams, type WebhookFilter, type WebhookListResponse, type WebhookTopic, type WebhookUpdateParams, WebhooksResource };
+/**
+ * Manages middleware registration and execution
+ */
+declare class MiddlewareManager {
+    private middlewares;
+    /**
+     * Register a middleware function
+     *
+     * @param middleware - The middleware function to register
+     * @param options - Optional configuration
+     * @returns this for chaining
+     */
+    use(middleware: Middleware, options?: MiddlewareOptions): this;
+    /**
+     * Remove a middleware by name
+     *
+     * @param name - The name of the middleware to remove
+     * @returns true if removed, false if not found
+     */
+    remove(name: string): boolean;
+    /**
+     * Get all registered middleware names
+     */
+    list(): string[];
+    /**
+     * Check if any middleware is registered
+     */
+    hasMiddleware(): boolean;
+    /**
+     * Execute the middleware chain with retry support
+     *
+     * @param ctx - The middleware context
+     * @param coreHandler - The core request handler to call at the end of the chain
+     * @returns The response from the core handler
+     */
+    execute<T>(ctx: MiddlewareContext<T>, coreHandler: () => Promise<MiddlewareResponse<T>>): Promise<MiddlewareResponse<T>>;
+    /**
+     * Run the middleware chain (onion model)
+     */
+    private runChain;
+}
+
+/**
+ * Options for the auth refresh middleware
+ */
+interface AuthRefreshOptions {
+    /**
+     * Function to refresh the access token
+     * Should return the new access token
+     */
+    refreshToken: () => Promise<string>;
+    /**
+     * Optional callback when refresh succeeds
+     */
+    onRefreshSuccess?: (newToken: string) => void;
+    /**
+     * Optional callback when refresh fails
+     */
+    onRefreshFailed?: (error: Error) => void;
+    /**
+     * Maximum refresh attempts per request (default: 1)
+     */
+    maxRefreshAttempts?: number;
+}
+/**
+ * Creates a middleware that automatically refreshes access tokens on 401 errors
+ *
+ * @example
+ * ```typescript
+ * const client = new MantleCoreClient({
+ *   accessToken: 'initial-token',
+ * });
+ *
+ * client.use(createAuthRefreshMiddleware({
+ *   refreshToken: async () => {
+ *     const response = await fetch('/refresh', { method: 'POST' });
+ *     const data = await response.json();
+ *     return data.accessToken;
+ *   },
+ *   onRefreshSuccess: (newToken) => {
+ *     // Persist the new token
+ *     localStorage.setItem('accessToken', newToken);
+ *   },
+ * }), { name: 'auth-refresh' });
+ * ```
+ */
+declare function createAuthRefreshMiddleware(options: AuthRefreshOptions): Middleware;
+
+export { type AccountOwner, type AccountOwnersListResponse, type Affiliate, type AffiliateCommission, type AffiliateCommissionListParams, type AffiliateCommissionListResponse, AffiliateCommissionsResource, type AffiliateListParams, type AffiliateListResponse, type AffiliatePayout, type AffiliatePayoutListParams, type AffiliatePayoutListResponse, AffiliatePayoutsResource, type AffiliateProgram, type AffiliateProgramCreateParams, type AffiliateProgramUpdateParams, AffiliateProgramsResource, type AffiliateReferral, type AffiliateReferralListParams, type AffiliateReferralListResponse, AffiliateReferralsResource, type AffiliateUpdateParams, AffiliatesResource, type Agent, type AgentListResponse, AgentsResource, type App, type AppEvent, type AppEventListParams, type AppEventListResponse, type AppInstallation, type AppInstallationParams, type AppListParams, AppsResource, type AuthRefreshOptions, BaseResource, type Channel, type ChannelCreateParams, type ChannelListParams, ChannelsResource, type Charge, type ChargeListParams, type ChargeListResponse, ChargesResource, CompaniesResource, type Company, type CompanyCreateParams, type CompanyListParams, type CompanyListResponse, type CompanyUpdateParams, type Contact, type ContactCreateParams, type ContactEntity, type ContactListParams, type ContactListResponse, type ContactUpdateParams, ContactsResource, type CustomField, type CustomFieldCreateParams, type CustomFieldUpdateParams, type Customer, type CustomerCreateParams, type CustomerEntity, type CustomerListParams, type CustomerListResponse, type CustomerRetrieveParams, type CustomerSegment, type CustomerSegmentListParams, type CustomerSegmentListResponse, CustomerSegmentsResource, type CustomerUpdateParams, CustomersResource, type DateRangeType, type Deal, DealActivitiesResource, type DealActivity, type DealActivityCreateParams, type DealActivityUpdateParams, type DealContactInput, type DealCreateParams, type DealCustomerInput, type DealFlow, type DealFlowCreateParams, type DealFlowUpdateParams, DealFlowsResource, type DealListParams, type DealListResponse, type DealStage, type DealUpdateParams, DealsResource, type DeleteResponse, type DocCollection, type DocCollectionCreateParams, type DocCollectionUpdateParams, type DocGroup, type DocGroupCreateParams, type DocGroupUpdateParams, type DocPage, type DocPageCreateParams, type DocPageListParams, type DocPageListResponse, type DocPageStatus, type DocPageUpdateParams, type DocTreeNode, type DocTreeResponse, DocsResource, EntitiesResource, type EntitiesSearchParams, type EntitiesSearchResponse, type Entity, type EntityType, type Feature, type FeatureCreateParams, type FeatureUpdateParams, type Flow, type FlowCreateParams, type FlowListParams, type FlowListResponse, type FlowStatus, type FlowUpdateParams, FlowsResource, type HttpMethod, type ListParams, MantleAPIError, MantleAuthenticationError, MantleCoreClient, type MantleCoreClientConfig, MantleNotFoundError, MantlePermissionError, MantleRateLimitError, MantleValidationError, MeResource, type MeResponse, type MessageAttachment, type MetricDataPoint, type MetricType, type MetricsBaseParams, type MetricsGetParams, MetricsResource, type MetricsResponse, type Middleware, type MiddlewareContext, MiddlewareManager, type MiddlewareOptions, type MiddlewareRequest, type MiddlewareResponse, type NextFunction, type Organization, OrganizationResource, type PaginatedResponse, type Plan, type PlanCreateParams, type PlanFeature, type PlanListParams, type PlanListResponse, type PlanUpdateParams, type PlanUsageCharge, type RequestOptions, type Review, type ReviewCreateParams, type ReviewUpdateParams, type SocialProfile, type SocialProfileType, type Subscription, type SubscriptionListParams, type SubscriptionListResponse, SubscriptionsResource, type Task, type TaskCreateParams, type TaskListParams, type TaskListResponse, type TaskPriority, type TaskStatus, type TaskUpdateParams, TasksResource, type Ticket, type TicketContactData, type TicketCreateParams, type TicketListParams, type TicketListResponse, type TicketMessage, type TicketMessageCreateParams, type TicketMessageUpdateParams, type TicketUpdateParams, TicketsResource, type TimelineEvent, type TimelineListParams, type TimelineListResponse, type Transaction, type TransactionListParams, type TransactionListResponse, TransactionsResource, type UsageEvent, type UsageEventCreateData, type UsageEventCreateParams, type UsageEventCreateResponse, type UsageEventListParams, type UsageEventListResponse, type UsageEventMetricsParams, UsageEventsResource, type UsageMetric, type UsageMetricCreateParams, type UsageMetricParams, type UsageMetricUpdateParams, type User, type UserListParams, type UserListResponse, UsersResource, type Webhook, type WebhookCreateParams, type WebhookFilter, type WebhookListResponse, type WebhookTopic, type WebhookUpdateParams, WebhooksResource, createAuthRefreshMiddleware };

package/dist/index.js

@@ -49,6 +49,7 @@ __export(index_exports, {
   MantleValidationError: () => MantleValidationError,
   MeResource: () => MeResource,
   MetricsResource: () => MetricsResource,
+  MiddlewareManager: () => MiddlewareManager,
   OrganizationResource: () => OrganizationResource,
   SubscriptionsResource: () => SubscriptionsResource,
   TasksResource: () => TasksResource,
@@ -56,10 +57,114 @@ __export(index_exports, {
   TransactionsResource: () => TransactionsResource,
   UsageEventsResource: () => UsageEventsResource,
   UsersResource: () => UsersResource,
-  WebhooksResource: () => WebhooksResource
+  WebhooksResource: () => WebhooksResource,
+  createAuthRefreshMiddleware: () => createAuthRefreshMiddleware
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/middleware/manager.ts
+var MiddlewareManager = class {
+  constructor() {
+    this.middlewares = [];
+  }
+  /**
+   * Register a middleware function
+   *
+   * @param middleware - The middleware function to register
+   * @param options - Optional configuration
+   * @returns this for chaining
+   */
+  use(middleware, options = {}) {
+    const registered = {
+      fn: middleware,
+      name: options.name ?? `middleware_${Date.now()}_${Math.random().toString(36).slice(2)}`,
+      priority: options.priority ?? 100
+    };
+    this.middlewares.push(registered);
+    this.middlewares.sort((a, b) => a.priority - b.priority);
+    return this;
+  }
+  /**
+   * Remove a middleware by name
+   *
+   * @param name - The name of the middleware to remove
+   * @returns true if removed, false if not found
+   */
+  remove(name) {
+    const index = this.middlewares.findIndex((m) => m.name === name);
+    if (index !== -1) {
+      this.middlewares.splice(index, 1);
+      return true;
+    }
+    return false;
+  }
+  /**
+   * Get all registered middleware names
+   */
+  list() {
+    return this.middlewares.map((m) => m.name);
+  }
+  /**
+   * Check if any middleware is registered
+   */
+  hasMiddleware() {
+    return this.middlewares.length > 0;
+  }
+  /**
+   * Execute the middleware chain with retry support
+   *
+   * @param ctx - The middleware context
+   * @param coreHandler - The core request handler to call at the end of the chain
+   * @returns The response from the core handler
+   */
+  async execute(ctx, coreHandler) {
+    const maxAttempts = ctx.maxRetries + 1;
+    let attempts = 0;
+    while (attempts < maxAttempts) {
+      ctx.retryCount = attempts;
+      ctx.retry = false;
+      ctx.error = void 0;
+      try {
+        await this.runChain(ctx, coreHandler);
+        if (!ctx.retry) {
+          return ctx.response;
+        }
+        attempts++;
+      } catch (error) {
+        if (!ctx.retry || attempts >= maxAttempts - 1) {
+          throw error;
+        }
+        attempts++;
+      }
+    }
+    throw ctx.error ?? new Error("Max retries exceeded");
+  }
+  /**
+   * Run the middleware chain (onion model)
+   */
+  async runChain(ctx, coreHandler) {
+    let index = -1;
+    const dispatch = async (i) => {
+      if (i <= index) {
+        throw new Error("next() called multiple times");
+      }
+      index = i;
+      if (i < this.middlewares.length) {
+        const middleware = this.middlewares[i];
+        await middleware.fn(ctx, () => dispatch(i + 1));
+      } else {
+        try {
+          ctx.response = await coreHandler();
+        } catch (error) {
+          ctx.error = error;
+          throw error;
+        }
+      }
+    };
+    await dispatch(0);
+  }
+};
+
 // src/utils/sanitize.ts
 function sanitizeObject(obj) {
   if (!obj || typeof obj !== "object") {
@@ -1667,6 +1772,16 @@ var MantleCoreClient = class {
     this.apiKey = config.apiKey;
     this.accessToken = config.accessToken;
     this.timeout = config.timeout || 3e4;
+    this.middlewareManager = new MiddlewareManager();
+    if (config.middleware) {
+      for (const mw of config.middleware) {
+        if (Array.isArray(mw)) {
+          this.middlewareManager.use(mw[0], mw[1]);
+        } else {
+          this.middlewareManager.use(mw);
+        }
+      }
+    }
     this.customers = new CustomersResource(this);
     this.contacts = new ContactsResource(this);
     this.subscriptions = new SubscriptionsResource(this);
@@ -1697,6 +1812,49 @@ var MantleCoreClient = class {
     this.docs = new DocsResource(this);
     this.entities = new EntitiesResource(this);
   }
+  /**
+   * Register a middleware function
+   *
+   * @param middleware - The middleware function to register
+   * @param options - Optional configuration (name, priority)
+   * @returns this for chaining
+   *
+   * @example
+   * ```typescript
+   * client.use(async (ctx, next) => {
+   *   console.log('Request:', ctx.request.url);
+   *   await next();
+   *   console.log('Response:', ctx.response?.status);
+   * });
+   * ```
+   */
+  use(middleware, options) {
+    this.middlewareManager.use(middleware, options);
+    return this;
+  }
+  /**
+   * Remove a middleware by name
+   *
+   * @param name - The name of the middleware to remove
+   * @returns true if removed, false if not found
+   */
+  removeMiddleware(name) {
+    return this.middlewareManager.remove(name);
+  }
+  /**
+   * Update authentication credentials
+   * Useful for middleware that needs to refresh tokens
+   *
+   * @param credentials - New credentials to set
+   */
+  updateAuth(credentials) {
+    if (credentials.apiKey !== void 0) {
+      this.apiKey = credentials.apiKey;
+    }
+    if (credentials.accessToken !== void 0) {
+      this.accessToken = credentials.accessToken;
+    }
+  }
   /**
    * Performs a GET request to the API
    */
@@ -1736,6 +1894,75 @@ var MantleCoreClient = class {
    * Makes an HTTP request to the API
    */
   async makeRequest(endpoint, options) {
+    if (this.middlewareManager.hasMiddleware()) {
+      return this.makeRequestWithMiddleware(endpoint, options);
+    }
+    return this.executeRequest(endpoint, options);
+  }
+  /**
+   * Execute request through middleware chain
+   */
+  async makeRequestWithMiddleware(endpoint, options) {
+    const request = {
+      url: `${this.baseURL}${endpoint}`,
+      method: options.method,
+      headers: {
+        Authorization: this.getAuthHeader(),
+        "Content-Type": "application/json",
+        ...options.headers
+      },
+      body: options.body,
+      endpoint
+    };
+    const ctx = {
+      request,
+      retry: false,
+      retryCount: 0,
+      maxRetries: 3,
+      updateAuth: (credentials) => this.updateAuth(credentials)
+    };
+    const coreHandler = async () => {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+      try {
+        const response2 = await fetch(ctx.request.url, {
+          method: ctx.request.method,
+          body: ctx.request.body,
+          headers: ctx.request.headers,
+          signal: controller.signal
+        });
+        clearTimeout(timeoutId);
+        if (!response2.ok) {
+          await this.handleErrorResponse(response2);
+        }
+        const text = await response2.text();
+        const data = text ? JSON.parse(text) : {};
+        return {
+          data,
+          status: response2.status,
+          headers: response2.headers
+        };
+      } catch (error) {
+        clearTimeout(timeoutId);
+        if (error instanceof MantleAPIError) {
+          throw error;
+        }
+        if (error instanceof Error && error.name === "AbortError") {
+          throw new MantleAPIError("Request timeout", 408);
+        }
+        throw new MantleAPIError(
+          error instanceof Error ? error.message : "Unknown error occurred",
+          500
+        );
+      }
+    };
+    const response = await this.middlewareManager.execute(ctx, coreHandler);
+    return response.data;
+  }
+  /**
+   * Direct request execution (no middleware)
+   */
+  async executeRequest(endpoint, options) {
     const authHeader = this.getAuthHeader();
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeout);
@@ -1821,6 +2048,45 @@ var MantleCoreClient = class {
     }
   }
 };
+
+// src/middleware/auth-refresh.ts
+function createAuthRefreshMiddleware(options) {
+  const {
+    refreshToken,
+    onRefreshSuccess,
+    onRefreshFailed,
+    maxRefreshAttempts = 1
+  } = options;
+  let refreshAttempts = 0;
+  return async (ctx, next) => {
+    try {
+      await next();
+    } catch (error) {
+      if (!(error instanceof MantleAuthenticationError)) {
+        throw error;
+      }
+      if (refreshAttempts >= maxRefreshAttempts) {
+        refreshAttempts = 0;
+        throw error;
+      }
+      refreshAttempts++;
+      try {
+        const newToken = await refreshToken();
+        ctx.updateAuth({ accessToken: newToken });
+        ctx.request.headers.Authorization = `Bearer ${newToken}`;
+        onRefreshSuccess?.(newToken);
+        ctx.retry = true;
+        refreshAttempts = 0;
+      } catch (refreshError) {
+        refreshAttempts = 0;
+        onRefreshFailed?.(refreshError);
+        throw new MantleAuthenticationError(
+          "Authentication failed. Please re-authenticate."
+        );
+      }
+    }
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AffiliateCommissionsResource,
@@ -1852,6 +2118,7 @@ var MantleCoreClient = class {
   MantleValidationError,
   MeResource,
   MetricsResource,
+  MiddlewareManager,
   OrganizationResource,
   SubscriptionsResource,
   TasksResource,
@@ -1859,5 +2126,6 @@ var MantleCoreClient = class {
   TransactionsResource,
   UsageEventsResource,
   UsersResource,
-  WebhooksResource
+  WebhooksResource,
+  createAuthRefreshMiddleware
 });

package/dist/index.mjs

@@ -1,3 +1,106 @@
+// src/middleware/manager.ts
+var MiddlewareManager = class {
+  constructor() {
+    this.middlewares = [];
+  }
+  /**
+   * Register a middleware function
+   *
+   * @param middleware - The middleware function to register
+   * @param options - Optional configuration
+   * @returns this for chaining
+   */
+  use(middleware, options = {}) {
+    const registered = {
+      fn: middleware,
+      name: options.name ?? `middleware_${Date.now()}_${Math.random().toString(36).slice(2)}`,
+      priority: options.priority ?? 100
+    };
+    this.middlewares.push(registered);
+    this.middlewares.sort((a, b) => a.priority - b.priority);
+    return this;
+  }
+  /**
+   * Remove a middleware by name
+   *
+   * @param name - The name of the middleware to remove
+   * @returns true if removed, false if not found
+   */
+  remove(name) {
+    const index = this.middlewares.findIndex((m) => m.name === name);
+    if (index !== -1) {
+      this.middlewares.splice(index, 1);
+      return true;
+    }
+    return false;
+  }
+  /**
+   * Get all registered middleware names
+   */
+  list() {
+    return this.middlewares.map((m) => m.name);
+  }
+  /**
+   * Check if any middleware is registered
+   */
+  hasMiddleware() {
+    return this.middlewares.length > 0;
+  }
+  /**
+   * Execute the middleware chain with retry support
+   *
+   * @param ctx - The middleware context
+   * @param coreHandler - The core request handler to call at the end of the chain
+   * @returns The response from the core handler
+   */
+  async execute(ctx, coreHandler) {
+    const maxAttempts = ctx.maxRetries + 1;
+    let attempts = 0;
+    while (attempts < maxAttempts) {
+      ctx.retryCount = attempts;
+      ctx.retry = false;
+      ctx.error = void 0;
+      try {
+        await this.runChain(ctx, coreHandler);
+        if (!ctx.retry) {
+          return ctx.response;
+        }
+        attempts++;
+      } catch (error) {
+        if (!ctx.retry || attempts >= maxAttempts - 1) {
+          throw error;
+        }
+        attempts++;
+      }
+    }
+    throw ctx.error ?? new Error("Max retries exceeded");
+  }
+  /**
+   * Run the middleware chain (onion model)
+   */
+  async runChain(ctx, coreHandler) {
+    let index = -1;
+    const dispatch = async (i) => {
+      if (i <= index) {
+        throw new Error("next() called multiple times");
+      }
+      index = i;
+      if (i < this.middlewares.length) {
+        const middleware = this.middlewares[i];
+        await middleware.fn(ctx, () => dispatch(i + 1));
+      } else {
+        try {
+          ctx.response = await coreHandler();
+        } catch (error) {
+          ctx.error = error;
+          throw error;
+        }
+      }
+    };
+    await dispatch(0);
+  }
+};
+
 // src/utils/sanitize.ts
 function sanitizeObject(obj) {
   if (!obj || typeof obj !== "object") {
@@ -1605,6 +1708,16 @@ var MantleCoreClient = class {
     this.apiKey = config.apiKey;
     this.accessToken = config.accessToken;
     this.timeout = config.timeout || 3e4;
+    this.middlewareManager = new MiddlewareManager();
+    if (config.middleware) {
+      for (const mw of config.middleware) {
+        if (Array.isArray(mw)) {
+          this.middlewareManager.use(mw[0], mw[1]);
+        } else {
+          this.middlewareManager.use(mw);
+        }
+      }
+    }
     this.customers = new CustomersResource(this);
     this.contacts = new ContactsResource(this);
     this.subscriptions = new SubscriptionsResource(this);
@@ -1635,6 +1748,49 @@ var MantleCoreClient = class {
     this.docs = new DocsResource(this);
     this.entities = new EntitiesResource(this);
   }
+  /**
+   * Register a middleware function
+   *
+   * @param middleware - The middleware function to register
+   * @param options - Optional configuration (name, priority)
+   * @returns this for chaining
+   *
+   * @example
+   * ```typescript
+   * client.use(async (ctx, next) => {
+   *   console.log('Request:', ctx.request.url);
+   *   await next();
+   *   console.log('Response:', ctx.response?.status);
+   * });
+   * ```
+   */
+  use(middleware, options) {
+    this.middlewareManager.use(middleware, options);
+    return this;
+  }
+  /**
+   * Remove a middleware by name
+   *
+   * @param name - The name of the middleware to remove
+   * @returns true if removed, false if not found
+   */
+  removeMiddleware(name) {
+    return this.middlewareManager.remove(name);
+  }
+  /**
+   * Update authentication credentials
+   * Useful for middleware that needs to refresh tokens
+   *
+   * @param credentials - New credentials to set
+   */
+  updateAuth(credentials) {
+    if (credentials.apiKey !== void 0) {
+      this.apiKey = credentials.apiKey;
+    }
+    if (credentials.accessToken !== void 0) {
+      this.accessToken = credentials.accessToken;
+    }
+  }
   /**
    * Performs a GET request to the API
    */
@@ -1674,6 +1830,75 @@ var MantleCoreClient = class {
    * Makes an HTTP request to the API
    */
   async makeRequest(endpoint, options) {
+    if (this.middlewareManager.hasMiddleware()) {
+      return this.makeRequestWithMiddleware(endpoint, options);
+    }
+    return this.executeRequest(endpoint, options);
+  }
+  /**
+   * Execute request through middleware chain
+   */
+  async makeRequestWithMiddleware(endpoint, options) {
+    const request = {
+      url: `${this.baseURL}${endpoint}`,
+      method: options.method,
+      headers: {
+        Authorization: this.getAuthHeader(),
+        "Content-Type": "application/json",
+        ...options.headers
+      },
+      body: options.body,
+      endpoint
+    };
+    const ctx = {
+      request,
+      retry: false,
+      retryCount: 0,
+      maxRetries: 3,
+      updateAuth: (credentials) => this.updateAuth(credentials)
+    };
+    const coreHandler = async () => {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+      try {
+        const response2 = await fetch(ctx.request.url, {
+          method: ctx.request.method,
+          body: ctx.request.body,
+          headers: ctx.request.headers,
+          signal: controller.signal
+        });
+        clearTimeout(timeoutId);
+        if (!response2.ok) {
+          await this.handleErrorResponse(response2);
+        }
+        const text = await response2.text();
+        const data = text ? JSON.parse(text) : {};
+        return {
+          data,
+          status: response2.status,
+          headers: response2.headers
+        };
+      } catch (error) {
+        clearTimeout(timeoutId);
+        if (error instanceof MantleAPIError) {
+          throw error;
+        }
+        if (error instanceof Error && error.name === "AbortError") {
+          throw new MantleAPIError("Request timeout", 408);
+        }
+        throw new MantleAPIError(
+          error instanceof Error ? error.message : "Unknown error occurred",
+          500
+        );
+      }
+    };
+    const response = await this.middlewareManager.execute(ctx, coreHandler);
+    return response.data;
+  }
+  /**
+   * Direct request execution (no middleware)
+   */
+  async executeRequest(endpoint, options) {
     const authHeader = this.getAuthHeader();
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeout);
@@ -1759,6 +1984,45 @@ var MantleCoreClient = class {
     }
   }
 };
+
+// src/middleware/auth-refresh.ts
+function createAuthRefreshMiddleware(options) {
+  const {
+    refreshToken,
+    onRefreshSuccess,
+    onRefreshFailed,
+    maxRefreshAttempts = 1
+  } = options;
+  let refreshAttempts = 0;
+  return async (ctx, next) => {
+    try {
+      await next();
+    } catch (error) {
+      if (!(error instanceof MantleAuthenticationError)) {
+        throw error;
+      }
+      if (refreshAttempts >= maxRefreshAttempts) {
+        refreshAttempts = 0;
+        throw error;
+      }
+      refreshAttempts++;
+      try {
+        const newToken = await refreshToken();
+        ctx.updateAuth({ accessToken: newToken });
+        ctx.request.headers.Authorization = `Bearer ${newToken}`;
+        onRefreshSuccess?.(newToken);
+        ctx.retry = true;
+        refreshAttempts = 0;
+      } catch (refreshError) {
+        refreshAttempts = 0;
+        onRefreshFailed?.(refreshError);
+        throw new MantleAuthenticationError(
+          "Authentication failed. Please re-authenticate."
+        );
+      }
+    }
+  };
+}
 export {
   AffiliateCommissionsResource,
   AffiliatePayoutsResource,
@@ -1789,6 +2053,7 @@ export {
   MantleValidationError,
   MeResource,
   MetricsResource,
+  MiddlewareManager,
   OrganizationResource,
   SubscriptionsResource,
   TasksResource,
@@ -1796,5 +2061,6 @@ export {
   TransactionsResource,
   UsageEventsResource,
   UsersResource,
-  WebhooksResource
+  WebhooksResource,
+  createAuthRefreshMiddleware
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heymantle/core-api-client",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "TypeScript SDK for the Mantle Core API",
   "main": "dist/index.js",
   "module": "dist/index.mjs",