domain

type Account struct {
	ID                       string
	Name                     string           `audit:"name"`
	DefaultBillingAddressID  *string          `audit:"default_billing_address_id"`
	DefaultShippingAddressID *string          `audit:"default_shipping_address_id"`
	Branding                 *AccountBranding `audit:"branding"`
	Portal                   *AccountPortal   `audit:"portal"`
	CreatedAt                time.Time
	UpdatedAt                time.Time
}

type AccountAffiliation struct {
	AccountID   string
	AccountName string
	RoleID      string
	RoleName    string
	RoleType    string
	LastUsedAt  *time.Time
}

type AccountBranding struct {
	ID              string
	SupportEmail    *string `audit:"support_email"`
	PhoneNumber     *string `audit:"phone_number"`
	LogoURL         *string `audit:"logo_url"`
	FaviconURL      *string `audit:"favicon_url"`
	FacebookHandle  *string `audit:"facebook_handle"`
	InstagramHandle *string `audit:"instagram_handle"`
	LinkedInHandle  *string `audit:"linkedin_handle"`
	TwitterHandle   *string `audit:"twitter_handle"`
	WebsiteURL      *string `audit:"website_url"`
	CreatedAt       time.Time
	UpdatedAt       time.Time
}

type AccountContext struct {
	AccountID                    string
	IsSandbox                    bool
	OwnerAccountID               *string
	AccountMode                  constants.AccountMode
	SubscriptionStatus           *string
	PlanCode                     string
	AgentMonthlySpendingCapCents *int64
}

type AccountGroup struct {
	ID                   string
	OwnerAccountID       string  `audit:"account_id"`
	Name                 string  `audit:"name"`
	Description          *string `audit:"description"`
	CommissionPolicyCode string  `audit:"commission_policy_code"`
	FreightPolicyCode    string  `audit:"freight_policy_code"`
	AccountGroupTypeCode string  `audit:"account_group_type_code"`
	// DefaultLeadTimeDays is inherited by every customer in the group that has not set its own. Nil falls through to the account default.
	DefaultLeadTimeDays *int32 `audit:"default_lead_time_days"`
	RegistrationFlowID  *string
	CreatedAt           time.Time
	UpdatedAt           time.Time
}

type AccountGroupProductLineAccess struct {
	AccountGroupID   string
	AccountGroupName string            `audit:"account_group_name"`
	ProductLines     []ProductLineInfo `audit:"product_lines"`
	CreatedAt        time.Time
	UpdatedAt        time.Time
}

type AccountGroupProductLineAccessRepo interface {
	List(ctx context.Context, params ListAccountGroupProductLineAccessParams) (*ListAccountGroupProductLineAccessResult, *apierror.APIError)
	Get(ctx context.Context, accountID, accountGroupID string) (*AccountGroupProductLineAccess, *apierror.APIError)
	Create(ctx context.Context, params CreateAccountGroupProductLineAccessParams) (*AccountGroupProductLineAccess, *apierror.APIError)
	Update(ctx context.Context, params UpdateAccountGroupProductLineAccessParams) (*AccountGroupProductLineAccess, *apierror.APIError)
	Delete(ctx context.Context, accountID, accountGroupID string) *apierror.APIError
	ExistsByAccountGroupID(ctx context.Context, accountGroupID string) (bool, *apierror.APIError)
}

type AccountGroupProductLineAccessSvc interface {
	// ListAccountGroupProductLineAccess returns a paginated list of product line access records grouped by account group.
	ListAccountGroupProductLineAccess(ctx context.Context, params ListAccountGroupProductLineAccessParams) (*ListAccountGroupProductLineAccessResult, *apierror.APIError)

	// GetAccountGroupProductLineAccess returns the product line access for a single account group.
	GetAccountGroupProductLineAccess(ctx context.Context, accountGroupID string) (*AccountGroupProductLineAccess, *apierror.APIError)

	// CreateAccountGroupProductLineAccess creates a new product line access record for an account group.
	CreateAccountGroupProductLineAccess(ctx context.Context, params CreateAccountGroupProductLineAccessParams) (*AccountGroupProductLineAccess, *apierror.APIError)

	// UpdateAccountGroupProductLineAccess replaces all product lines for an account group.
	UpdateAccountGroupProductLineAccess(ctx context.Context, params UpdateAccountGroupProductLineAccessParams) (*AccountGroupProductLineAccess, *apierror.APIError)

	// DeleteAccountGroupProductLineAccess removes all product line access for an account group.
	DeleteAccountGroupProductLineAccess(ctx context.Context, accountGroupID string) *apierror.APIError

	// BatchGetAccountGroupProductLineAccessByIDs returns access records for the given account_group_ids. Used by the api-gateway resourcekit resolver.
	BatchGetAccountGroupProductLineAccessByIDs(ctx context.Context, accountGroupIDs []string) ([]*AccountGroupProductLineAccess, *apierror.APIError)
}

type AccountGroupRepo interface {
	List(ctx context.Context, params ListAccountGroupsParams) (*ListAccountGroupsResult, *apierror.APIError)
	Get(ctx context.Context, accountID, id string) (*AccountGroup, *apierror.APIError)
	GetByIDs(ctx context.Context, accountID string, ids []string) ([]*AccountGroup, *apierror.APIError)
	Create(ctx context.Context, id string, params CreateAccountGroupParams) (*AccountGroup, *apierror.APIError)
	Update(ctx context.Context, params UpdateAccountGroupParams) (*AccountGroup, *apierror.APIError)
	Delete(ctx context.Context, params DeleteAccountGroupParams) *apierror.APIError
	CheckAccountGroupNotInUse(ctx context.Context, accountGroup *AccountGroup) *apierror.APIError
	DeleteAccountRelationPriceGroupsByAccountGroupID(ctx context.Context, accountGroupID string) *apierror.APIError
	ExistsByName(ctx context.Context, accountID, name string, excludeID *string) (bool, *apierror.APIError)
}

type AccountGroupSvc interface {
	// ListAccountGroups returns a paginated list of account groups for the caller's account.
	ListAccountGroups(ctx context.Context, params ListAccountGroupsParams) (*ListAccountGroupsResult, *apierror.APIError)

	// GetAccountGroup returns a single account group by ID.
	GetAccountGroup(ctx context.Context, accountGroupID string) (*AccountGroup, *apierror.APIError)

	// CreateAccountGroup creates a new account group.
	CreateAccountGroup(ctx context.Context, params CreateAccountGroupParams) (*AccountGroup, *apierror.APIError)

	// UpdateAccountGroup partially updates an account group.
	UpdateAccountGroup(ctx context.Context, params UpdateAccountGroupParams) (*AccountGroup, *apierror.APIError)

	// DeleteAccountGroup deletes an account group.
	DeleteAccountGroup(ctx context.Context, accountGroupID string) *apierror.APIError

	// BatchGetAccountGroupsByIDs returns account groups matching the input IDs that the caller's account is authorized to read. Used by the api-gateway resourcekit include resolver.
	BatchGetAccountGroupsByIDs(ctx context.Context, ids []string) ([]*AccountGroup, *apierror.APIError)
}

type AccountIntegration struct {
	ID              string
	AccountID       string
	IntegrationCode constants.IntegrationCode `audit:"integration_code"`
	Name            string                    `audit:"name"`
	IsActive        bool                      `audit:"is_active"`
	CreatedAt       time.Time
	UpdatedAt       time.Time
}

type AccountIntegrationRepo interface {
	List(ctx context.Context, params ListAccountIntegrationsParams) (*ListAccountIntegrationsResult, *apierror.APIError)
	Get(ctx context.Context, accountID, id string) (*AccountIntegration, *apierror.APIError)
	GetByIDs(ctx context.Context, accountID string, ids []string) ([]*AccountIntegration, *apierror.APIError)
	FindByCode(ctx context.Context, accountID string, code constants.IntegrationCode) (*AccountIntegration, *apierror.APIError)
	Create(ctx context.Context, id string, params CreateAccountIntegrationParams, encryptedCredentials string) (*AccountIntegration, *apierror.APIError)
	UpdateCredentials(ctx context.Context, accountID, id, name, encryptedCredentials string) (*AccountIntegration, *apierror.APIError)
	Update(ctx context.Context, params UpdateAccountIntegrationParams) (*AccountIntegration, *apierror.APIError)
	Delete(ctx context.Context, params DeleteAccountIntegrationParams) (*AccountIntegration, *apierror.APIError)
	GetEncryptedCredentials(ctx context.Context, accountID string, code constants.IntegrationCode) (credentials string, isActive bool, err *apierror.APIError)
	HasIntegration(ctx context.Context, accountID string, code constants.IntegrationCode) (bool, *apierror.APIError)
}

type AccountIntegrationSvc interface {
	// ListAccountIntegrations returns a paginated list of integrations for the caller's account.
	ListAccountIntegrations(ctx context.Context, params ListAccountIntegrationsParams) (*ListAccountIntegrationsResult, *apierror.APIError)

	// CreateAccountIntegration creates or upserts an integration. If one with the same code exists, it updates name and credentials instead of inserting.
	CreateAccountIntegration(ctx context.Context, params CreateAccountIntegrationParams) (*AccountIntegration, *apierror.APIError)

	// UpdateAccountIntegration updates name and/or is_active on an integration.
	UpdateAccountIntegration(ctx context.Context, params UpdateAccountIntegrationParams) (*AccountIntegration, *apierror.APIError)

	// DeleteAccountIntegration deletes an integration and returns the deleted resource.
	DeleteAccountIntegration(ctx context.Context, params DeleteAccountIntegrationParams) (*AccountIntegration, *apierror.APIError)

	// GetStripePublishableKey returns the Stripe publishable key for the account.
	GetStripePublishableKey(ctx context.Context) (string, *apierror.APIError)

	// HasStripeIntegration returns whether the account has a Stripe integration.
	HasStripeIntegration(ctx context.Context) (bool, *apierror.APIError)

	// BatchGetAccountIntegrationsByIDs returns account integrations matching the input IDs that the caller's account is authorized to read. Used by the api-gateway resourcekit include resolver.
	BatchGetAccountIntegrationsByIDs(ctx context.Context, ids []string) ([]*AccountIntegration, *apierror.APIError)
}

type AccountPortal struct {
	ID        string
	Slug      string `audit:"slug"`
	CreatedAt time.Time
	UpdatedAt time.Time
}

type AccountPrice struct {
	ID                               string
	OwnerAccountID                   string
	RecipientAccountID               string `audit:"recipient_account_id"`
	RecipientAccountName             string `audit:"recipient_account_name"`
	RecipientAccountNumber           string
	RecipientAccountStatus           string
	RecipientAccountIsEdiEnabled     bool
	RecipientAccountCommissionPolicy string
	RecipientAccountRelationshipType string
	RecipientAccountCreatedAt        time.Time
	RecipientAccountUpdatedAt        time.Time
	ProductLineID                    string `audit:"product_line_id"`
	ProductLineName                  string `audit:"product_line_name"`
	ProductLineIsCommissionExempt    bool
	ProductLineIsFreightExempt       bool
	ProductLineCreatedAt             time.Time
	ProductLineUpdatedAt             time.Time
	RateID                           string
	RateValue                        string `audit:"rate_value"`
	RateCreatedAt                    time.Time
	RateUpdatedAt                    time.Time
	NumeratorUnitID                  string `audit:"numerator_unit_id"`
	NumeratorUnitName                string `audit:"numerator_unit_name"`
	NumeratorUnitAbbr                string `audit:"numerator_unit_abbr"`
	NumeratorUnitType                string `audit:"numerator_unit_type"`
	NumeratorUnitRatioNumerator      string
	NumeratorUnitRatioDenominator    string
	NumeratorUnitOffsetNumerator     string
	NumeratorUnitOffsetDenominator   string
	NumeratorUnitCreatedAt           time.Time
	NumeratorUnitUpdatedAt           time.Time
	DenominatorUnitID                string `audit:"denominator_unit_id"`
	DenominatorUnitName              string `audit:"denominator_unit_name"`
	DenominatorUnitAbbr              string `audit:"denominator_unit_abbr"`
	DenominatorUnitType              string `audit:"denominator_unit_type"`
	DenominatorUnitRatioNumerator    string
	DenominatorUnitRatioDenominator  string
	DenominatorUnitOffsetNumerator   string
	DenominatorUnitOffsetDenominator string
	DenominatorUnitCreatedAt         time.Time
	DenominatorUnitUpdatedAt         time.Time
	Categories                       []AccountPriceCategory  `audit:"categories"`
	Attributes                       []AccountPriceAttribute `audit:"attributes"`
	CreatedAt                        time.Time
	UpdatedAt                        time.Time
}

type AccountPriceAttribute struct {
	ID        string
	Value     string
	ColorCode string
	CreatedAt time.Time
	UpdatedAt time.Time
}

type AccountPriceCategory struct {
	ID        string
	Name      string
	Type      string
	CreatedAt time.Time
	UpdatedAt time.Time
}

type AccountPriceRepo interface {
	List(ctx context.Context, params ListAccountPricesParams) (*ListAccountPricesResult, *apierror.APIError)
	// ResolveRecipientAccountIDs returns the customer plus its parent account, if it has one.
	ResolveRecipientAccountIDs(ctx context.Context, ownerAccountID, customerAccountID string) ([]string, *apierror.APIError)
	Get(ctx context.Context, accountID, accountPriceID string) (*AccountPrice, *apierror.APIError)
	Create(ctx context.Context, accountPriceID, rateID string, params CreateAccountPriceParams) (*AccountPrice, *apierror.APIError)
	Update(ctx context.Context, params UpdateAccountPriceParams) (*AccountPrice, *apierror.APIError)
	Delete(ctx context.Context, accountID, accountPriceID string) *apierror.APIError
}

type AccountPriceSvc interface {
	// ExportPriceList accepts a price-list export for one customer and returns the job tracking it. Pricing a whole catalog is far too slow to hold a request open for, so the document is rendered by the export worker.
	ExportPriceList(ctx context.Context, params ExportPriceListParams) (*Job, *apierror.APIError)

	// BuildExportPriceList renders the PDF an accepted price-list export recorded.
	BuildExportPriceList(ctx context.Context, accountID string, filters json.RawMessage) (*Export, *apierror.APIError)

	// ListAccountPrices returns a paginated list of account prices for the caller's account. Customer actors can only see prices where they are the recipient.
	ListAccountPrices(ctx context.Context, params ListAccountPricesParams) (*ListAccountPricesResult, *apierror.APIError)

	// GetAccountPrice returns a single account price by ID.
	GetAccountPrice(ctx context.Context, accountPriceID string) (*AccountPrice, *apierror.APIError)

	// CreateAccountPrice creates a new account price with rate, category, and attribute associations.
	CreateAccountPrice(ctx context.Context, params CreateAccountPriceParams) (*AccountPrice, *apierror.APIError)

	// UpdateAccountPrice partially updates an account price. If categories or attributes are provided, they are replaced entirely (delete-all-then-recreate).
	UpdateAccountPrice(ctx context.Context, params UpdateAccountPriceParams) (*AccountPrice, *apierror.APIError)

	// DeleteAccountPrice deletes an account price and cascades to associations and rate.
	DeleteAccountPrice(ctx context.Context, accountPriceID string) *apierror.APIError
}

type AccountRelation struct {
	ID                    string
	OwnerAccountID        string
	CounterpartyAccountID string
	RoleCode              string
	// IsOwnerSide is true when the caller's account is the owner of the relation (i.e. the API key belongs to the merchant targeting a customer/supplier account).
	IsOwnerSide bool
}

type AccountRelationRepo interface {
	FindByOwnerAccountAndUserID(ctx context.Context, ownerAccountID, userID string) (*AccountRelation, *apierror.APIError)
	FindByOwnerAccountAndAPIKeyID(ctx context.Context, ownerAccountID string, apiKeyID int64) (*AccountRelation, *apierror.APIError)
	FindByCounterpartyAccountAndUserID(ctx context.Context, counterpartyAccountID, ownerAccountID, userID string) (*AccountRelation, *apierror.APIError)
	FindByCounterpartyAccountAndAPIKeyID(ctx context.Context, counterpartyAccountID string, apiKeyID int64) (*AccountRelation, *apierror.APIError)
	FindCustomerByEmail(ctx context.Context, ownerAccountID, email string) (*CustomerByEmail, *apierror.APIError)
	FindContactsByEmail(ctx context.Context, ownerAccountID, email string) ([]ContactMatch, *apierror.APIError)
	HasRelation(ctx context.Context, ownerAccountID, counterpartyAccountID string) (bool, *apierror.APIError)
	CountOtherOwnerRelations(ctx context.Context, counterpartyAccountID, excludeOwnerAccountID string) (int64, *apierror.APIError)
	FindRelationByOwnerAndCounterparty(ctx context.Context, ownerAccountID, counterpartyAccountID string) (string, *apierror.APIError)
	CreateNotificationPreference(ctx context.Context, id, accountRelationID, recipientAccountUserID string, notificationTypeCode string) *apierror.APIError
	ListNotificationPreferences(ctx context.Context, accountRelationID, recipientAccountUserID string) ([]NotificationPreference, *apierror.APIError)
	ListNotificationRecipients(ctx context.Context, accountRelationID string) ([]NotificationRecipientRef, *apierror.APIError)
	DeleteNotificationPreference(ctx context.Context, accountRelationID, recipientAccountUserID, notificationTypeCode string) *apierror.APIError
	DeleteNotificationPreferencesByTypes(ctx context.Context, accountRelationID string, notificationTypeCodes []string) *apierror.APIError
	ListChildAccounts(ctx context.Context, params ListChildAccountsParams) (*ListChildAccountsResult, *apierror.APIError)
	GetChildAccountDetail(ctx context.Context, ownerAccountID, counterpartyAccountID string) (*ChildAccount, *apierror.APIError)
	GetChildAccountsByRelationIDs(ctx context.Context, ownerAccountID string, relationIDs []string) ([]*ChildAccount, *apierror.APIError)
	SetParentRelation(ctx context.Context, ownerAccountID, childRelationID, parentRelationID string) *apierror.APIError
	ClearParentRelation(ctx context.Context, ownerAccountID, childRelationID, parentRelationID string) *apierror.APIError
	GetParentRelationID(ctx context.Context, relationID string) (*string, *apierror.APIError)
	FindCustomerAccountsByVendorAndUser(ctx context.Context, vendorAccountID, userID string) ([]CustomerAccountSummary, *apierror.APIError)
}

type AccountRepo interface {
	Create(ctx context.Context, id, name string, accountTypeCode AccountType, planCode constants.PlanCode) *apierror.APIError
	GetPlanCode(ctx context.Context, id string) (constants.PlanCode, *apierror.APIError)
	GetAccountContext(ctx context.Context, accountID string) (*AccountContext, *apierror.APIError)
	// GetPlanIDAndPeriodEnd returns the account's active plan id (for limit lookups) and current subscription period end (for deriving billing-period start).
	GetPlanIDAndPeriodEnd(ctx context.Context, accountID string) (planID *string, periodEnd *time.Time, apiErr *apierror.APIError)
	Delete(ctx context.Context, id string) *apierror.APIError
	GetPlanTypeIDByCode(ctx context.Context, planCode string) (string, *apierror.APIError)
	UpdateSubscription(ctx context.Context, accountID string, status *string, planCode string, accountPlanID *string, stripeSubID *string, periodEnd *time.Time, stripeCustomerID *string, billingProfileID *string, billingCadenceID *string, pricingPlanSubscriptionID *string, servicingStatus *string, collectionStatus *string) *apierror.APIError
	ClearStripeCustomer(ctx context.Context, accountID string) *apierror.APIError
	ClearPricingPlanSubscription(ctx context.Context, accountID string) *apierror.APIError
	GetByStripeCustomerID(ctx context.Context, stripeCustomerID string) (accountID string, planCode string, err *apierror.APIError)
	GetSandboxLimit(ctx context.Context, accountID string) (*int32, *apierror.APIError)
	GetSeatLimitByPlanCode(ctx context.Context, planCode string) (*int32, *apierror.APIError)
	CountNonSandboxByPlanCode(ctx context.Context, planCode string) (int64, *apierror.APIError)
	UpdateAgentSpendingCap(ctx context.Context, accountID string, capCents *int64) *apierror.APIError
	GetAgentSpendingCap(ctx context.Context, accountID string) (*int64, *apierror.APIError)
	HasActiveBillingPlan(ctx context.Context, accountID string) (bool, *apierror.APIError)
	GetName(ctx context.Context, accountID string) (string, *apierror.APIError)
	GetPortalSlug(ctx context.Context, accountID string) (*string, *apierror.APIError)
	GetByID(ctx context.Context, accountID string) (*Account, *apierror.APIError)
	// GetByIDs returns accounts matching the given IDs. Caller authorization is enforced at the service layer.
	GetByIDs(ctx context.Context, ids []string) ([]*Account, *apierror.APIError)
	GetBySlug(ctx context.Context, slug string) (*PublicAccountBySlug, *apierror.APIError)
	UpdateName(ctx context.Context, accountID, name string) *apierror.APIError
	UpdateBranding(ctx context.Context, accountID string, params UpdateAccountParams) *apierror.APIError
	UpdatePortalSlug(ctx context.Context, accountID, slug string) *apierror.APIError
	ExistsPortalSlug(ctx context.Context, slug, excludeAccountID string) (bool, *apierror.APIError)
	UpdateBrandingLogoURL(ctx context.Context, accountID, logoURL string) *apierror.APIError
	GetBrandingLogoKey(ctx context.Context, accountID string) (*string, *apierror.APIError)
	UpdateBrandingFaviconURL(ctx context.Context, accountID, faviconURL string) *apierror.APIError
	GetBrandingFaviconKey(ctx context.Context, accountID string) (*string, *apierror.APIError)
	ListPlanLimits(ctx context.Context, accountPlanID string) (map[string]*int32, *apierror.APIError)
	ListPlanFeatures(ctx context.Context, accountPlanID string) (map[string]bool, *apierror.APIError)
}

type AccountStatus struct {
	ID        string
	Code      string
	Name      string
	CreatedAt time.Time
	UpdatedAt time.Time
}

type AccountStatusRepo interface {
	List(ctx context.Context, params ListAccountStatusesParams) (*ListAccountStatusesResult, *apierror.APIError)
	Get(ctx context.Context, identifier string) (*AccountStatus, *apierror.APIError)
	GetByIDs(ctx context.Context, ids []string) ([]*AccountStatus, *apierror.APIError)
}

type AccountStatusSvc interface {
	// ListAccountStatuses returns a paginated list of account statuses.
	ListAccountStatuses(ctx context.Context, params ListAccountStatusesParams) (*ListAccountStatusesResult, *apierror.APIError)

	// GetAccountStatus returns a single account status by ID or code.
	GetAccountStatus(ctx context.Context, identifier string) (*AccountStatus, *apierror.APIError)

	// BatchGetAccountStatusesByIDs returns account statuses by ID for the api-gateway include resolver.
	BatchGetAccountStatusesByIDs(ctx context.Context, ids []string) ([]*AccountStatus, *apierror.APIError)
}

type AccountSvc interface {
	// GetAccountContext returns contextual information for an account (including whether it is a sandbox).
	GetAccountContext(ctx context.Context, accountID string) (*AccountContext, *apierror.APIError)

	// GetUserAccountAccess returns the user's access to an account, including role and permissions.
	//
	// If the user has no relationship to the account, returns (nil, false, nil).
	GetUserAccountAccess(ctx context.Context, userID, accountID string) (*AccountUserAccess, bool, *apierror.APIError)

	// GetRolePermissions returns the permission map for the given role ID.
	GetRolePermissions(ctx context.Context, roleID string) (map[string]bool, *apierror.APIError)

	// GetRoleInfo returns a role's name and type code.
	GetRoleInfo(ctx context.Context, roleID string) (*RoleInfo, *apierror.APIError)

	// GetAccountRelationByUserID returns the relationship between the target account and the account implied by the user. actorAccountID is required for owner-side matches (the relation's owner_account_id must equal it); pass "" to skip the owner-side fallback entirely.
	GetAccountRelationByUserID(ctx context.Context, targetAccountID, actorAccountID, userID string) (*AccountRelation, *apierror.APIError)

	// GetAccountRelationByAPIKeyID returns the relationship between the owner account and the account implied by the API key.
	GetAccountRelationByAPIKeyID(ctx context.Context, ownerAccountID string, apiKeyID int64) (*AccountRelation, *apierror.APIError)

	// MarkAccountUserUsed records that the account user was recently used.
	MarkAccountUserUsed(ctx context.Context, accountUserID string) *apierror.APIError

	// ListUserAccountAffiliations returns the accounts the user is affiliated with.
	//
	// Also returns, if available, the user's last used account ID.
	ListUserAccountAffiliations(ctx context.Context, userID string) ([]AccountAffiliation, *string, *apierror.APIError)

	// GetAdminRole returns the role ID used for administrative access.
	GetAdminRole(ctx context.Context) (string, *apierror.APIError)

	// UpdateAccountSubscription updates subscription fields on an account, resolving the account_plan_id from the plan_code.
	UpdateAccountSubscription(ctx context.Context, accountID string, status *string, planCode string, stripeSubID *string, periodEnd *time.Time, stripeCustomerID *string, billingProfileID *string, billingCadenceID *string, pricingPlanSubscriptionID *string, servicingStatus *string, collectionStatus *string) *apierror.APIError

	// ClearAccountStripeCustomer removes all Stripe-related fields from an account.
	ClearAccountStripeCustomer(ctx context.Context, accountID string) *apierror.APIError

	// GetAccountByStripeCustomerID resolves an account from a Stripe customer ID.
	GetAccountByStripeCustomerID(ctx context.Context, stripeCustomerID string) (accountID string, planCode string, err *apierror.APIError)

	// CompleteRegistration creates the production account, sandbox, owner roles, account-user records, business address, and portal for a newly registered user. Returns the new account ID and sandbox account ID.
	CompleteRegistration(ctx context.Context, input CompleteRegistrationInput) (*CompleteRegistrationOutput, *apierror.APIError)

	// UpdateAgentSpendingCap sets or removes the monthly agent LLM spending cap for the caller's account. Pass nil to remove the cap.
	UpdateAgentSpendingCap(ctx context.Context, capCents *int64) (*int64, *apierror.APIError)

	// GetAccount returns the full account with optional branding and portal sub-resources.
	GetAccount(ctx context.Context, accountID string) (*Account, *apierror.APIError)

	// BatchGetAccountsByIDs returns accounts matching the given IDs that the caller is authorized to read. Used by the api-gateway include resolver for owner.account expansion across many parent resources.
	BatchGetAccountsByIDs(ctx context.Context, ids []string) ([]*Account, *apierror.APIError)

	// GetAccountBySlug returns a minimal public account by portal slug (unauthenticated).
	GetAccountBySlug(ctx context.Context, slug string) (*PublicAccountBySlug, *apierror.APIError)
	GetPortalProfileBySlug(ctx context.Context, slug string) (*PortalProfile, *apierror.APIError)

	// UpdateAccount partially updates an account's name, branding, and/or portal slug.
	UpdateAccount(ctx context.Context, params UpdateAccountParams) (*Account, *apierror.APIError)

	// UploadAccountPhoto uploads an account logo to S3 and updates the branding record.
	UploadAccountPhoto(ctx context.Context, accountID string, file []byte, contentType string) *apierror.APIError

	// GetAccountLogoURL returns a presigned S3 URL for the account's logo, or nil if none.
	GetAccountLogoURL(ctx context.Context, accountID string) (*string, *apierror.APIError)

	// UploadAccountFavicon uploads a customer-portal favicon to S3 and updates the branding record.
	UploadAccountFavicon(ctx context.Context, accountID string, file []byte, contentType string) *apierror.APIError

	// GetAccountFaviconURL returns a presigned S3 URL for the account's customer-portal favicon, or nil if none.
	GetAccountFaviconURL(ctx context.Context, accountID string) (*string, *apierror.APIError)
}

type AccountType string

type AccountUser struct {
	ID           string
	UserID       string
	DepartmentID *string
	RoleID       *string
	RoleType     *string
	RoleName     *string
	AccountID    string
	LastUsedAt   *time.Time
	CreatedAt    time.Time
	UpdatedAt    time.Time
}

type AccountUserAccess struct {
	AccountUserID string
	AccountID     string
	RoleID        *string
	RoleType      *string
	RoleName      *string
	Permissions   map[string]bool
	LastUsedAt    *time.Time
}

type AccountUserDetail struct {
	ID                   string
	UserID               string
	Name                 *string `audit:"name"`
	Email                *string `audit:"email"`
	Username             *string `audit:"username"`
	ImageURL             *string `audit:"image_url"`
	EmailVerified        bool    `audit:"email_verified"`
	RoleID               *string `audit:"role_id"`
	RoleName             *string `audit:"role_name"`
	RoleType             *string `audit:"role_type_code"`
	DepartmentID         *string `audit:"department_id"`
	DepartmentName       *string `audit:"department_name"`
	DepartmentCreatedAt  *time.Time
	DepartmentUpdatedAt  *time.Time
	StatusCode           constants.AccountUserStatus `audit:"status_code"`
	IsCommissionEligible bool                        `audit:"is_commission_eligible"`
	LastUsedAt           *time.Time
	CreatedAt            time.Time
	UpdatedAt            time.Time
}

type AccountUserRef struct {
	ID     string
	UserID string
}

type AccountUserRepo interface {
	FindByAccountAndUserID(ctx context.Context, userID, accountID string) (*AccountUser, *apierror.APIError)
	// ResolveAccountUserID resolves either an account_user id or a user id to the account_user id within the given account.
	ResolveAccountUserID(ctx context.Context, accountID, userOrAccountUserID string) (string, *apierror.APIError)
	FindAffiliationsByUserID(ctx context.Context, userID string) ([]AccountAffiliation, *apierror.APIError)
	FindLastUsedAccountID(ctx context.Context, userID string) (string, *apierror.APIError)
	UpdateLastUsedAt(ctx context.Context, accountUserID string, lastUsedAt time.Time) *apierror.APIError
	GetAdminRoleID(ctx context.Context) (string, *apierror.APIError)
	DeactivateExcept(ctx context.Context, accountID, keepUserID string, limit int32) (int64, *apierror.APIError)
	EnsureActive(ctx context.Context, accountID, userID string) *apierror.APIError
	CountActive(ctx context.Context, accountID string) (int64, *apierror.APIError)
	ReactivateUsers(ctx context.Context, accountID string, limit int32) (int64, *apierror.APIError)
	List(ctx context.Context, params ListAccountUsersParams) (*ListAccountUsersResult, *apierror.APIError)
	GetDetail(ctx context.Context, accountID, userID string, includes []string) (*AccountUserDetail, *apierror.APIError)
	GetDetailByAccountAndID(ctx context.Context, accountID, accountUserID string, includes []string) (*AccountUserDetail, *apierror.APIError)
	Create(ctx context.Context, id, accountID, userID string, roleID, departmentID *string, isCommissionEligible bool) *apierror.APIError
	Update(ctx context.Context, accountUserID string, roleID, departmentID *string, isCommissionEligible bool) *apierror.APIError
	// ReactivateRemovedAccountUser reactivates a previously soft-removed link for (accountID, userID), setting its role/department, and returns the reactivated account_user id. Returns resource_not_found when no removed link exists.
	ReactivateRemovedAccountUser(ctx context.Context, accountID, userID string, roleID, departmentID *string, isCommissionEligible bool) (string, *apierror.APIError)
	SoftDelete(ctx context.Context, accountUserID string) *apierror.APIError
	UpdateStatus(ctx context.Context, accountUserID string, status constants.AccountUserStatus) *apierror.APIError
	CountByRoleID(ctx context.Context, accountID, roleID string) (int64, *apierror.APIError)
	RevokeRefreshTokensByUserID(ctx context.Context, userID string) *apierror.APIError
	FindFirstAccountIDByUserID(ctx context.Context, userID string) (string, *apierror.APIError)
	FindTenancyAccountsByUserID(ctx context.Context, userID string) ([]TenancyAccount, *apierror.APIError)
	MarkUsedByAccountAndUser(ctx context.Context, accountID, userID string) *apierror.APIError
	GetByIDs(ctx context.Context, accountID string, ids []string) ([]*AccountUserDetail, *apierror.APIError)
}

type AccountUserSvc interface {
	// ListAccountUsers returns a paginated list of account users.
	ListAccountUsers(ctx context.Context, params ListAccountUsersParams) (*ListAccountUsersResult, *apierror.APIError)

	// GetAccountUser returns a single account user by account_user ID.
	GetAccountUser(ctx context.Context, accountUserID string, includes []string) (*AccountUserDetail, *apierror.APIError)

	// CreateAccountUser creates a new account user.
	CreateAccountUser(ctx context.Context, params CreateAccountUserParams) (*AccountUserDetail, *apierror.APIError)

	// UpdateAccountUser partially updates an account user, optionally including notification preferences.
	UpdateAccountUser(ctx context.Context, params UpdateAccountUserParams, includes []string) (*AccountUserDetail, *apierror.APIError)

	// UpdateAccountUserStatus transitions an account user to the given target status.
	UpdateAccountUserStatus(ctx context.Context, accountUserID string, targetStatus constants.AccountUserStatus) *apierror.APIError

	// UpdateAccountUserPassword updates the password for a scanner-role account user.
	UpdateAccountUserPassword(ctx context.Context, accountUserID, requesterPassword, newPassword string) *apierror.APIError

	// BatchGetAccountUsersByIDs returns account users matching the given IDs.
	BatchGetAccountUsersByIDs(ctx context.Context, ids []string) ([]*AccountUserDetail, *apierror.APIError)
}

type AddBatchInput struct {
	ID                string
	ItemID            string
	Quantity          CreateQuantityParams
	Seconds           *CreateQuantityParams
	Waste             *CreateQuantityParams
	ProductionStepID  *string
	ScanningStationID *string
}

type AddBatchesToProductionRunParams struct {
	ProductionRunID string
	AccountID       string
	Batches         []AddBatchInput
}

type AddItemAttributeParams struct {
	AccountID   string
	ItemID      string
	AttributeID string
}

type AddItemCategoryPropertyParams struct {
	AccountID      string
	ItemCategoryID string
	PropertyID     string
}

type Address struct {
	ID         string
	Name       string  `audit:"name"`
	Phone      *string `audit:"phone"`
	Email      *string `audit:"email"`
	IsDropShip bool    `audit:"is_drop_ship"`
	// ReceiveCalendarID names the days this dock accepts freight, overriding the customer's own calendar. Set when one of a customer's sites keeps different days from the rest.
	ReceiveCalendarID *string      `audit:"receive_calendar_id"`
	Geolocation       *Geolocation `audit:"geolocation"`
	CreatedAt         time.Time
	UpdatedAt         time.Time
}

type AddressComponents struct {
	AddressLine1 string
	AddressLine2 *string
	City         string
	State        string
	PostalCode   string
	Country      string
	CountryCode  string
}

type AddressDetailsResult struct {
	Address          *AddressComponents
	FormattedAddress string
}

type AddressRepo interface {
	List(ctx context.Context, params ListAddressesParams) (*ListAddressesResult, *apierror.APIError)
	Get(ctx context.Context, params GetAddressParams) (*Address, *apierror.APIError)
	GetByIDs(ctx context.Context, accountID string, ids []string) ([]*Address, *apierror.APIError)
	Create(ctx context.Context, addressID, geolocationID, accountAddressID string, params CreateAddressParams) (*Address, *apierror.APIError)
	Update(ctx context.Context, params UpdateAddressParams) (*Address, *apierror.APIError)
	Delete(ctx context.Context, params DeleteAddressParams) *apierror.APIError
	IsInAccount(ctx context.Context, accountID, addressID string) (bool, *apierror.APIError)
	GetGeolocationSharedCount(ctx context.Context, geolocationID string) (int64, *apierror.APIError)
	GetGeolocationIDByAddressID(ctx context.Context, addressID string) (string, *apierror.APIError)
	CreateGeolocation(ctx context.Context, id string, params CreateAddressParams) *apierror.APIError
	UpdateGeolocation(ctx context.Context, geolocationID string, params UpdateAddressParams) *apierror.APIError
	RelinkGeolocation(ctx context.Context, addressID, geolocationID string) *apierror.APIError
	CheckAddressNotInUse(ctx context.Context, addressID string) *apierror.APIError
	// SwitchAccountDefaultAddressToRelation realigns any account default billing/shipping pointer at
	// the given address to the account-relation default (owner→this account), falling back to NULL
	// when the relation has no usable default. It keeps a non-active account from being left with a
	// dangling default when the address is deleted (there are no FKs to cascade). Call inside the
	// delete transaction.
	SwitchAccountDefaultAddressToRelation(ctx context.Context, addressID string) *apierror.APIError
}

type AddressSuggestion struct {
	ID            string
	Description   string
	MainText      string
	SecondaryText string
}

type AddressSvc interface {
	// ListAddresses returns a paginated list of addresses for an account.
	ListAddresses(ctx context.Context, params ListAddressesParams) (*ListAddressesResult, *apierror.APIError)

	// GetAddress returns a single address by ID within an account.
	GetAddress(ctx context.Context, params GetAddressParams) (*Address, *apierror.APIError)

	// CreateAddress creates a new address linked to an account.
	CreateAddress(ctx context.Context, params CreateAddressParams) (*Address, *apierror.APIError)

	// UpdateAddress partially updates an address within an account.
	UpdateAddress(ctx context.Context, params UpdateAddressParams) (*Address, *apierror.APIError)

	// DeleteAddress deletes an address from an account.
	DeleteAddress(ctx context.Context, params DeleteAddressParams) *apierror.APIError

	// BatchGetAddressesByIDs returns addresses matching the input IDs that the caller's account is authorized to read. Used by the api-gateway resourcekit include resolver.
	BatchGetAddressesByIDs(ctx context.Context, ids []string) ([]*Address, *apierror.APIError)
}

type AddressValidationSvc interface {
	// Autocomplete returns address autocomplete suggestions.
	Autocomplete(ctx context.Context, input string, sessionToken *string) ([]AddressSuggestion, *apierror.APIError)

	// GetPlaceDetails returns parsed address components from a Google Places ID.
	GetPlaceDetails(ctx context.Context, placeID string, sessionToken *string) (*AddressDetailsResult, *apierror.APIError)

	// ValidateAddress validates an address using Google Address Validation API.
	ValidateAddress(ctx context.Context, addressLine1 string, addressLine2 *string, city, state, postalCode, country string) (*ValidatedAddress, *apierror.APIError)
}

type AdjustmentType struct {
	ID        string
	Name      string
	Code      string
	CreatedAt time.Time
	UpdatedAt time.Time
}

type AdjustmentTypeRepo interface {
	List(ctx context.Context, params ListAdjustmentTypesParams) (*ListAdjustmentTypesResult, *apierror.APIError)
	GetByIDs(ctx context.Context, ids []string) ([]*AdjustmentType, *apierror.APIError)
}

type AdjustmentTypeSvc interface {
	// ListAdjustmentTypes returns a paginated list of adjustment types.
	ListAdjustmentTypes(ctx context.Context, params ListAdjustmentTypesParams) (*ListAdjustmentTypesResult, *apierror.APIError)
	// BatchGetAdjustmentTypesByIDs returns adjustment types by ID for the api-gateway include resolver.
	BatchGetAdjustmentTypesByIDs(ctx context.Context, ids []string) ([]*AdjustmentType, *apierror.APIError)
}

type AdminUpdateShipmentTrackingParams struct {
	AccountID            string
	ShipmentID           string
	MasterTrackingNumber *string
	CarrierID            *string
	// Tri-state: unset keeps the current service level, null clears it.
	ServiceLevelID field.Clearable[string]
	Includes       []string
}

type AdminUpdateShippingCaseTrackingParams struct {
	AccountID      string
	ShippingCaseID string
	TrackingNumber *string
}

type AllocateOpenIssuesEvent struct {
	AccountID      string    `json:"account_id"`
	ItemID         string    `json:"item_id"`
	AfterCreatedAt time.Time `json:"after_created_at"`
	AfterID        string    `json:"after_id"`
}

type AllocationEntry struct {
	ID                string
	AmountValue       string
	AmountUnitAbbr    string
	CustomerName      string
	CustomerNumber    *string
	TransactionID     string
	TransactionType   string
	TransactionMethod *string
	AdjustmentType    *string
	InvoiceID         string
	InvoiceNumber     string
	Note              *string
	CreatedAt         time.Time
}

type AnalyticsRepo interface {
	GetSalesEntries(ctx context.Context, params AnalyzeSalesParams) ([]SalesEntry, *apierror.APIError)
	GetOpenBatchEntries(ctx context.Context, params AnalyzeOpenBatchesParams) ([]OpenBatchEntry, *apierror.APIError)
	GetProductionCostEntries(ctx context.Context, params AnalyzeProductionCostsParams) ([]ProductionCostEntry, *apierror.APIError)
	GetDeliveryAnalytics(ctx context.Context, params AnalyzeDeliveriesParams) (*DeliveryAnalyticsResult, *apierror.APIError)
	GetManufacturingMetric(ctx context.Context, params AnalyzeManufacturingParams) (float64, *apierror.APIError)
	GetManufacturingBatch(ctx context.Context, params AnalyzeManufacturingBatchParams) (*ManufacturingBatchResult, *apierror.APIError)
	GetOrderEntries(ctx context.Context, params AnalyzeOrdersParams) ([]OrderEntry, *apierror.APIError)
	GetQuarterlyOrders(ctx context.Context, params AnalyzeQuarterlyOrdersParams) ([]YearlyQuarterlyData, *apierror.APIError)
	GetMaterialAnalytics(ctx context.Context, params AnalyzeMaterialsParams) ([]MaterialAnalyticsEntry, *apierror.APIError)
	GetInventoryReceiptAnalytics(ctx context.Context, params AnalyzeInventoryReceiptsParams) ([]InventoryReceiptEntry, *apierror.APIError)
	GetNewCustomerEntries(ctx context.Context, params GetNewCustomersAnalyticsParams) ([]NewCustomerEntry, *apierror.APIError)
	GetDemandForecastMonthlyDemand(ctx context.Context, params GetDemandForecastWindowParams) ([]DemandForecastMonthlyDemandRow, *apierror.APIError)
	GetDemandForecastMonthlyRevenue(ctx context.Context, params GetDemandForecastWindowParams) ([]DemandForecastMonthlyRevenueRow, *apierror.APIError)
	GetOeeDepartmentData(ctx context.Context, params GetOeeWindowParams) ([]OeeDepartmentDataRow, *apierror.APIError)
	GetOeeEstimatedRuntime(ctx context.Context, params GetOeeWindowParams) ([]OeeEstimatedRuntimeRow, *apierror.APIError)
	GetOeeDowntimeByDepartment(ctx context.Context, params GetOeeWindowParams) ([]OeeDowntimeRow, *apierror.APIError)
	GetOeeTrendDepartmentDataByWeek(ctx context.Context, params GetOeeWindowParams) ([]OeeTrendDepartmentWeekRow, *apierror.APIError)
	GetOeeTrendDowntimeIntervals(ctx context.Context, params GetOeeWindowParams) ([]OeeDowntimeIntervalRow, *apierror.APIError)
	CountMachinesByDepartment(ctx context.Context, accountID string) ([]DepartmentMachineCountRow, *apierror.APIError)
	GetSaleProductItemIDs(ctx context.Context, accountID string) ([]SaleProductItemRow, *apierror.APIError)
	GetProductLineInfo(ctx context.Context, accountID string, productLineIDs []string) ([]ProductLineInfoRow, *apierror.APIError)
	GetOrderQuantityByProductLine(ctx context.Context, params GetOrderQuantityByProductLineParams) (*OrderQuantityByProductLineRow, *apierror.APIError)
}

type AnalyticsSvc interface {
	AnalyzeSales(ctx context.Context, params AnalyzeSalesParams) ([]SalesEntry, *apierror.APIError)

	// AnalyzeRealizedMargins rolls invoiced lines up to one row per customer and SKU and flags those priced below their peers or under target margin.
	AnalyzeRealizedMargins(ctx context.Context, params AnalyzeRealizedMarginsParams) (*RealizedMarginAnalysis, *apierror.APIError)

	// AnalyzeCustomerPricing sweeps every contracted price and flags those below their peers or under target margin.
	AnalyzeCustomerPricing(ctx context.Context, params AnalyzeCustomerPricingParams) (*CustomerPricingAnalysis, *apierror.APIError)
	AnalyzeOpenBatches(ctx context.Context, params AnalyzeOpenBatchesParams) ([]OpenBatchEntry, *apierror.APIError)
	AnalyzeProductionCosts(ctx context.Context, params AnalyzeProductionCostsParams) ([]ProductionCostEntry, *apierror.APIError)
	AnalyzeDeliveries(ctx context.Context, params AnalyzeDeliveriesParams) (*DeliveryAnalyticsResult, *apierror.APIError)
	AnalyzeManufacturing(ctx context.Context, params AnalyzeManufacturingParams) (float64, *apierror.APIError)
	AnalyzeManufacturingBatch(ctx context.Context, params AnalyzeManufacturingBatchParams) (*ManufacturingBatchResult, *apierror.APIError)
	AnalyzeOrders(ctx context.Context, params AnalyzeOrdersParams) ([]OrderEntry, *apierror.APIError)
	AnalyzeQuarterlyOrders(ctx context.Context, params AnalyzeQuarterlyOrdersParams) ([]YearlyQuarterlyData, *apierror.APIError)
	AnalyzeMaterials(ctx context.Context, params AnalyzeMaterialsParams) ([]MaterialAnalyticsEntry, *apierror.APIError)
	AnalyzeInventoryReceipts(ctx context.Context, params AnalyzeInventoryReceiptsParams) ([]InventoryReceiptEntry, *apierror.APIError)
	GetNewCustomersAnalytics(ctx context.Context, params GetNewCustomersAnalyticsParams) ([]NewCustomerEntry, *apierror.APIError)
	// GetDemandForecast returns per-item demand, revenue and sales history with seasonal-EMA forecasts and confidence bands.
	GetDemandForecast(ctx context.Context, params GetDemandForecastParams) (*DemandForecastResult, *apierror.APIError)
	// AnalyzeOee computes Availability x Performance x Quality per department from planned time, logged downtime and batch-ticket scan intervals.
	AnalyzeOee(ctx context.Context, params AnalyzeOeeParams) ([]OeeDepartment, *apierror.APIError)
	AnalyzeOeeTrend(ctx context.Context, params AnalyzeOeeTrendParams) ([]OeeTrendPeriod, *apierror.APIError)

	// AnalyzeScheduleAttainment measures actual production against the plan that was live at the time.
	AnalyzeScheduleAttainment(ctx context.Context, params AnalyzeScheduleAttainmentParams) (*ScheduleAttainmentResult, *apierror.APIError)

	// AnalyzeDeliveryPerformance measures what was promised against what was shipped.
	AnalyzeDeliveryPerformance(ctx context.Context, params AnalyzeDeliveryPerformanceParams) (*DeliveryPerformanceResult, *apierror.APIError)
	// AnalyzeWeeksOfSales returns on-hand inventory expressed as weeks of average sales per product line.
	AnalyzeWeeksOfSales(ctx context.Context, params AnalyzeWeeksOfSalesParams) (*WeeksOfSalesResult, *apierror.APIError)
}

type AnalyzeCustomerPricingParams struct {
	// CustomerIDs and CustomerGroupIDs narrow the reported findings, not the peer benchmark: a price must be compared against every comparable price, including those the caller did not ask about.
	CustomerIDs       []string
	CustomerGroupIDs  []string
	TargetGrossMargin *string
	OutlierTolerance  *string
}

type AnalyzeDeliveriesParams struct {
	AccountID              string
	StartDate              time.Time
	EndDate                time.Time
	ProductLineIDs         []string
	CustomerIDs            []string
	CustomerGroupIDs       []string
	SalesRepIDs            []string
	TargetDeliveryTimeDays *int32
	OverridePromisedDates  *bool
}

type AnalyzeDeliveryPerformanceParams struct {
	AccountID   string
	StartDate   time.Time
	EndDate     time.Time
	Granularity string

	DeliveryFilters
}

type AnalyzeInventoryReceiptsParams struct {
	AccountID   string
	ItemIDs     []string
	LocationIDs []string
	LotIDs      []string
}

type AnalyzeManufacturingBatchParams struct {
	AccountID           string
	StartDate           time.Time
	EndDate             time.Time
	ComparisonStartDate time.Time
	ComparisonEndDate   time.Time
	CustomerIDs         []string
	ProductLineIDs      []string
	CustomerGroupIDs    []string
	ItemIDs             []string
}

type AnalyzeManufacturingParams struct {
	AccountID string
	StartDate time.Time
	EndDate   time.Time
	Type      string
}

type AnalyzeMaterialsParams struct {
	AccountID     string
	SalesOrderIDs []string
	SupplierIDs   []string
}

type AnalyzeOeeParams struct {
	AccountID     string
	StartDate     time.Time
	EndDate       time.Time
	DepartmentIDs []string
	// PlannedTimeHours is the scheduled production time per department for the window. Without it Availability has no denominator, so the OEE ratios are returned nil rather than guessed. Keyed by department ID.
	PlannedTimeHours map[string]float64
}

type AnalyzeOeeTrendParams struct {
	AccountID     string
	StartDate     time.Time
	EndDate       time.Time
	DepartmentIDs []string
}

type AnalyzeOpenBatchesParams struct {
	AccountID      string
	ItemIDs        []string
	ProductLineIDs []string
}

type AnalyzeOrdersParams struct {
	AccountID        string
	SalesRepIDs      []string
	ProductLineIDs   []string
	CustomerIDs      []string
	CustomerGroupIDs []string
	IsSalesRep       bool
}

type AnalyzeProductionCostsParams struct {
	AccountID      string
	StartDate      *time.Time
	EndDate        *time.Time
	ItemIDs        []string
	ProductLineIDs []string
	DepartmentIDs  []string
	CategoryIDs    []string
}

type AnalyzeQuarterlyOrdersParams struct {
	AccountID        string
	SalesRepIDs      []string
	ItemIDs          []string
	ProductLineIDs   []string
	CustomerIDs      []string
	CustomerGroupIDs []string
}

type AnalyzeRealizedMarginsParams struct {
	StartDate time.Time
	EndDate   time.Time
	// CustomerIDs and CustomerGroupIDs narrow the reported findings, not the peer benchmark: a customer must be compared against everyone who bought the SKU, including those the caller did not ask about.
	CustomerIDs       []string
	CustomerGroupIDs  []string
	ProductLineIDs    []string
	TargetGrossMargin *string
	OutlierTolerance  *string
}

type AnalyzeSalesParams struct {
	AccountID        string
	StartDate        time.Time
	EndDate          time.Time
	ProductLineIDs   []string
	CustomerIDs      []string
	SalesRepIDs      []string
	CustomerGroupIDs []string
	Query            *string
	IsSalesRep       bool
}

type AnalyzeScheduleAttainmentParams struct {
	AccountID     string
	StartDate     time.Time
	EndDate       time.Time
	GroupBy       string
	MachineIDs    []string
	DepartmentIDs []string
}

type AnalyzeWeeksOfSalesParams struct {
	AccountID     string
	PeriodInWeeks int32
}

type AttainmentActualRow struct {
	WeekStartDate  time.Time
	MachineID      *string
	ItemID         string
	DepartmentID   *string
	ActualQuantity float64
	WasteQuantity  float64
	BatchCount     int64
}

type AttainmentBaselineRow struct {
	ScheduleID       string
	Version          int32
	HorizonStartDate time.Time
	HorizonEndDate   time.Time
	// PublishedAt is nil for a version that was never published — a draft was never a commitment.
	PublishedAt       *time.Time
	FrozenThroughDate *time.Time
	FrozenLineCount   int32
	// FrozenPlannedQuantity is the quantity captured at publish, pre-converted from its decimal column.
	FrozenPlannedQuantity float64
}

type AttainmentBucket struct {
	// Key identifies the bucket within the chosen grouping — an ISO week start, a machine id, a department id or an item id.
	Key   string
	Label string

	WeekStartDate *time.Time

	PlannedQuantity float64
	ActualQuantity  float64
	// MatchedQuantity is SUM(LEAST(actual, planned)) — the attainment numerator.
	MatchedQuantity float64
	WasteQuantity   float64
	// UnplannedQuantity is production with no matching planned line. It is surfaced rather than discarded: it is the schedule-breaker number.
	UnplannedQuantity float64

	PlannedRunHours float64
	PlannedLines    int64
	BatchCount      int64

	// Nil when the denominator is zero — a week nobody planned has no attainment, which is not the same as 0%.
	AttainmentPct  *float64
	OutputRatioPct *float64
}

type AttainmentDeviationRow struct {
	ProductionScheduleID string
	DeviationCount       int64
	AddedCount           float64
	AbsDeltaQuantity     float64
}

type AttainmentLabelRow struct {
	ID    string
	Label string
}

type AttainmentPlannedRow struct {
	WeekStartDate   time.Time
	MachineID       string
	ItemID          string
	DepartmentID    *string
	PlannedQuantity float64
	PlannedRunHours float64
	LineCount       int64
}

type Attribute struct {
	ID         string
	Value      string `audit:"value"`
	PropertyID string
	AccountID  string
	ColorCode  string `audit:"color_code"`
	SortOrder  int32  `audit:"sort_order"`
	IsPublic   bool   `audit:"is_public"`
	CreatedAt  time.Time
	UpdatedAt  time.Time
}

type AttributeRepo interface {
	List(ctx context.Context, params ListAttributesParams) (*ListAttributesResult, *apierror.APIError)
	ListByPropertyIDs(ctx context.Context, accountID string, propertyIDs []string) ([]*Attribute, *apierror.APIError)
	GetByIDs(ctx context.Context, accountID string, ids []string) ([]*Attribute, *apierror.APIError)
	Get(ctx context.Context, params GetAttributeParams) (*Attribute, *apierror.APIError)
	Create(ctx context.Context, id string, params CreateAttributeParams) (*Attribute, *apierror.APIError)
	Update(ctx context.Context, params UpdateAttributeParams) (*Attribute, *apierror.APIError)
	Delete(ctx context.Context, params DeleteAttributeParams) *apierror.APIError
	ExistsByValueInAccount(ctx context.Context, accountID, value string, excludeID *string) (bool, *apierror.APIError)
	FindByTextsInAccount(ctx context.Context, accountID string, texts []string) ([]*AttributeTextMatch, *apierror.APIError)
	CountByProperty(ctx context.Context, propertyID, accountID string) (int64, *apierror.APIError)
	ShiftOrdersUp(ctx context.Context, propertyID, accountID string, fromOrder int32) *apierror.APIError
	ShiftOrdersDown(ctx context.Context, propertyID, accountID string, afterOrder int32) *apierror.APIError
	ShiftOrdersUpBounded(ctx context.Context, propertyID, accountID string, fromOrder, toOrder int32) *apierror.APIError
	ShiftOrdersDownBounded(ctx context.Context, propertyID, accountID string, afterOrder, upToOrder int32) *apierror.APIError
}

type AttributeSvc interface {
	// ListAttributes returns a paginated list of attributes for a property.
	ListAttributes(ctx context.Context, params ListAttributesParams) (*ListAttributesResult, *apierror.APIError)

	// GetAttribute returns a single attribute by ID within a property.
	GetAttribute(ctx context.Context, propertyID, attributeID string) (*Attribute, *apierror.APIError)

	// BatchGetAttributesByIDs returns attributes matching the input IDs that belong to the caller's account.
	BatchGetAttributesByIDs(ctx context.Context, ids []string) ([]*Attribute, *apierror.APIError)

	// CreateAttribute creates a new attribute under a property.
	CreateAttribute(ctx context.Context, params CreateAttributeParams) (*Attribute, *apierror.APIError)

	// UpdateAttribute partially updates an attribute.
	UpdateAttribute(ctx context.Context, params UpdateAttributeParams) (*Attribute, *apierror.APIError)

	// DeleteAttribute deletes an attribute.
	DeleteAttribute(ctx context.Context, params DeleteAttributeParams) *apierror.APIError
}

type AttributeTextMatch struct {
	ID           string
	Text         string
	PropertyID   string
	PropertyName string
}

type BaseBatch struct {
	ID              string
	Item            LightItem             `audit:"item"`
	Quantity        BatchQuantity         `audit:"quantity"`
	Seconds         *BatchQuantity        `audit:"seconds"`
	Waste           *BatchQuantity        `audit:"waste"`
	ScanningStation *LightScanningStation `audit:"scanning_station"`
	DepartmentID    *string               `audit:"department_id"`
	DepartmentName  *string               `audit:"department_name"`
	ProductionStep  *LightProductionStep  `audit:"production_step"`
	ProductionRun   *LightProductionRun   `audit:"production_run"`
	ProductionRunID *string
	ClosedAt        *time.Time `audit:"closed_at"`
	ScannedAt       *time.Time `audit:"scanned_at"`
	CreatedAt       time.Time
	UpdatedAt       time.Time
}

type Batch struct {
	ID              string
	Item            LightItem             `audit:"item"`
	Quantity        BatchQuantity         `audit:"quantity"`
	Seconds         *BatchQuantity        `audit:"seconds"`
	Waste           *BatchQuantity        `audit:"waste"`
	ScanningStation *LightScanningStation `audit:"scanning_station"`
	DepartmentID    *string               `audit:"department_id"`
	DepartmentName  *string               `audit:"department_name"`
	ProductionStep  *LightProductionStep  `audit:"production_step"`
	ProductionRun   *LightProductionRun   `audit:"production_run"`
	Machines        []LightMachine
	Lots            []BatchLot
	InputBatchIDs   []string
	OutputBatchIDs  []string
	ClosedAt        *time.Time `audit:"closed_at"`
	ScannedAt       *time.Time `audit:"scanned_at"`
	CreatedAt       time.Time
	UpdatedAt       time.Time
}

type BatchFlowChildRow struct {
	ParentBatchID string
	BatchID       string
	ItemID        string
}

type BatchFlowNode struct {
	Batch          Batch
	InputBatchIDs  []string
	OutputBatchIDs []string
}

type BatchLot struct {
	LotNumber string
	Type      string // "material" or "productionRun"
}

type BatchQuantity struct {
	ID      string
	Measure decimal.Decimal
	Unit    LightUnit
}

type BatchRepo interface {
	Find(ctx context.Context, accountID, batchID string) (*Batch, *apierror.APIError)
	FindBatchFlow(ctx context.Context, accountID, batchID string) ([]BatchFlowNode, *apierror.APIError)
	FindByScanningStation(ctx context.Context, params ListBatchesByScanningStationParams) (*ListBatchesByScanningStationResult, *apierror.APIError)
	FindPossibleNextSteps(ctx context.Context, accountID, scanningStationID, batchID string) ([]ScanningProductionStepInfo, *apierror.APIError)
	FindOpenBatches(ctx context.Context, accountID string, itemIDs, productLineIDs []string) ([]OpenBatchSummary, *apierror.APIError)
	FindFurthestRightBatchInFlow(ctx context.Context, accountID, batchID string) (*BaseBatch, *apierror.APIError)
	FindNextAvailableBatchInFlow(ctx context.Context, accountID, batchID, productionStepID string) (*BaseBatch, *apierror.APIError)
	FindAvailableBatchesInFlow(ctx context.Context, accountID string, batchIDs []string, productionStepID string) ([]BaseBatch, *apierror.APIError)
	FindOutputBatches(ctx context.Context, accountID, batchID string) ([]BaseBatch, *apierror.APIError)
	Create(ctx context.Context, id string, params CreateBatchParams) (*BaseBatch, *apierror.APIError)
	MarkAsScanned(ctx context.Context, accountID, batchID string) *apierror.APIError
	ConnectProductionStep(ctx context.Context, accountID, batchID, productionStepID string) *apierror.APIError
	ConnectScanningStation(ctx context.Context, accountID, batchID, scanningStationID string) *apierror.APIError
	ConnectOneToOne(ctx context.Context, accountID, sourceBatchID, targetBatchID string, autoClose bool) *apierror.APIError
	ConnectManyToOne(ctx context.Context, accountID string, sourceBatchIDs []string, targetBatchID string, autoClose bool) *apierror.APIError
	Close(ctx context.Context, accountID, batchID string) (*BaseBatch, *apierror.APIError)
	CloseIfLastStep(ctx context.Context, accountID, batchID, productionStepID string) *apierror.APIError
	CloseIfFullyUsed(ctx context.Context, accountID string, batch BaseBatch, producedUnit LightUnit, productionStepID string) *apierror.APIError
	Delete(ctx context.Context, accountID, batchID string) (*BaseBatch, *apierror.APIError)
	DeleteMany(ctx context.Context, accountID string, batchIDs []string) *apierror.APIError
	// CountDownstreamBatches reports how many batches were fed by this one. A batch something downstream still feeds on cannot be undone.
	CountDownstreamBatches(ctx context.Context, batchID string) (int64, *apierror.APIError)
	// FindInputBatchIDs returns the batches that fed the given one.
	FindInputBatchIDs(ctx context.Context, batchID string) ([]string, *apierror.APIError)
	// FindLineageShortfall walks up a batch's lineage for the production run it belongs to and the seconds and waste accumulated along the way.
	FindLineageShortfall(ctx context.Context, batchID string) (*LineageShortfall, *apierror.APIError)
	// Unscan returns a batch to the state it was in before it was scanned, leaving the row in place so the production run that created it still holds that unit of work.
	Unscan(ctx context.Context, accountID, batchID string) (*BaseBatch, *apierror.APIError)
	// Reopen clears a batch's closed_at.
	Reopen(ctx context.Context, accountID, batchID string) *apierror.APIError
	// ReassignMachine points a batch at one machine and drops any other machine link it had, for a ticket moved to a campaign running somewhere else.
	ReassignMachine(ctx context.Context, accountID, batchID, machineID string) *apierror.APIError
	// ReopenIfNotFullyUsed reopens a batch that is no longer fully consumed — the mirror of CloseIfFullyUsed, run after a downstream batch is deleted and the quantity it was holding comes back.
	ReopenIfNotFullyUsed(ctx context.Context, accountID string, batch BaseBatch, producedUnit LightUnit, productionStepID string) *apierror.APIError
}

type BatchScannedEvent struct {
	// AccountID owns the batch. Carried on the payload as well as the identity so a subscriber that
	// re-publishes or replays the event does not depend on the envelope surviving intact.
	AccountID string `json:"account_id"`
	// BatchID is the batch the operator scanned, and the tag every ledger row written in reaction
	// carries, which is what lets an undo find them again.
	BatchID string `json:"batch_id"`

	ProductionStepID  string `json:"production_step_id"`
	ScanningStationID string `json:"scanning_station_id"`
	// ItemID is what the batch is of, used to confirm the step still produces what was scanned.
	ItemID string `json:"item_id"`

	// Measure and UnitID are what the operator recorded, in the unit they recorded it in. Conversion
	// into the step's production unit belongs to the subscriber, which knows the step.
	Measure string `json:"measure"`
	UnitID  string `json:"unit_id"`

	// SecondsMeasure and WasteMeasure are in the same unit as Measure. Empty means none.
	SecondsMeasure string `json:"seconds_measure,omitempty"`
	WasteMeasure   string `json:"waste_measure,omitempty"`

	ResponsibleUserID *string `json:"responsible_user_id,omitempty"`

	// ScannedAt is when the operator scanned, not when the event was published or handled. Receipts
	// are dated from it so a message that waits in the queue still lands on the day it happened.
	ScannedAt time.Time `json:"scanned_at"`
}

type BatchSvc interface {
	// GetBatchFlow returns the flow graph for a batch.
	GetBatchFlow(ctx context.Context, batchID string) ([]BatchFlowNode, *apierror.APIError)

	// ListBatchesByScanningStation returns a paginated list of batches for a scanning station.
	ListBatchesByScanningStation(ctx context.Context, params ListBatchesByScanningStationParams) (*ListBatchesByScanningStationResult, *apierror.APIError)

	// GetPossibleNextSteps returns the possible next production steps for a batch at a scanning station.
	GetPossibleNextSteps(ctx context.Context, scanningStationID, batchID string) ([]ScanningProductionStepInfo, *apierror.APIError)

	// AnalyzeOpenBatches returns aggregated open batch summaries for analytics.
	AnalyzeOpenBatches(ctx context.Context, itemIDs, productLineIDs []string) ([]OpenBatchSummary, *apierror.APIError)

	// InitializeBatch initializes a batch at a scanning station.
	InitializeBatch(ctx context.Context, batchID, scanningStationID string) (*BaseBatch, *apierror.APIError)

	// MoveBatches moves one or more batches to a new production step.
	MoveBatches(ctx context.Context, params MoveBatchesParams) (*BaseBatch, *apierror.APIError)

	// MergeBatches merges multiple batches into a single batch.
	MergeBatches(ctx context.Context, params MergeBatchesParams) (*BaseBatch, *apierror.APIError)

	// SplitBatch splits a batch into firsts, seconds, and waste.
	SplitBatch(ctx context.Context, params SplitBatchParams) (*BaseBatch, *apierror.APIError)

	// GetRemainingQuantityToSplit returns the remaining quantity available to split from a batch flow.
	GetRemainingQuantityToSplit(ctx context.Context, batchIDs []string, productionStepID string) (*BatchQuantity, *apierror.APIError)

	// GetScanningStationConsumption returns consumption demand for a scanning station.
	GetScanningStationConsumption(ctx context.Context, params GetConsumptionParams) ([]ScanningConsumption, *apierror.APIError)

	// CloseBatch closes a batch.
	CloseBatch(ctx context.Context, batchID string) (*BaseBatch, *apierror.APIError)

	// DeleteBatch deletes a single batch.
	DeleteBatch(ctx context.Context, batchID string) (*BaseBatch, *apierror.APIError)

	// DeleteManyBatches deletes multiple batches.
	DeleteManyBatches(ctx context.Context, batchIDs []string) *apierror.APIError
}

type BillingPublisher interface {
	// PublishSyncSeats writes a sync-seats command to the outbox for the given account.
	PublishSyncSeats(ctx context.Context, accountID string) *apierror.APIError
	// PublishReportSeatChange writes a report-seat-change command to the outbox for usage metering with the billing provider.
	PublishReportSeatChange(ctx context.Context, accountID string) *apierror.APIError
	// Writes a report-invoice-created command to the outbox for usage metering with the billing provider.
	PublishReportInvoiceCreated(ctx context.Context, accountID, invoiceID string) *apierror.APIError
}

type BulkCreateBatchParams struct {
	Item             ItemIdentifier
	QuantityValue    string
	QuantityUnit     UnitIdentifier
	SecondsValue     *string
	SecondsUnit      *UnitIdentifier
	WasteValue       *string
	WasteUnit        *UnitIdentifier
	ProductionStepID *string
	ScanningStation  *ObjectIdentifier
}

type BulkCreateConsumptionInput struct {
	SKU          string
	Measure      string
	Instructions *string
}

type BulkCreateItemInput struct {
	SKU            string
	Description    *string
	ItemCategoryID string
	ProductLineID  *string
	// AttributeIDs are connected to the new (or existing upserted) item in the same tx.
	AttributeIDs []string
}

type BulkCreateItemResult struct {
	SKU     string
	Success bool
	Error   *string
	ItemID  *string
}

type BulkCreateItemsParams struct {
	AccountID string
	Items     []BulkCreateItemInput
	Type      string
}

type BulkCreateProductionInput struct {
	SKU     string
	Measure string
}

type BulkCreateProductionRunEventBatch struct {
	BatchID           string
	ItemID            string
	QuantityValue     string
	QuantityUnitID    string
	SecondsValue      *string
	SecondsUnitID     *string
	WasteValue        *string
	WasteUnitID       *string
	ProductionStepID  *string
	ScanningStationID *string
}

type BulkCreateProductionRunEventRun struct {
	ProductionRunID   string
	ResponsibleUserID string
	Batches           []BulkCreateProductionRunEventBatch
}

type BulkCreateProductionRunParams struct {
	ResponsibleUserID string
	Batches           []BulkCreateBatchParams
}

type BulkCreateProductionRunsParams struct {
	ProductionRuns []BulkCreateProductionRunParams
}

type BulkCreateProductionStepInput struct {
	Name           string
	Consumptions   []BulkCreateConsumptionInput
	Productions    []BulkCreateProductionInput
	LaborRate      string
	LaborTime      string
	LaborTimeUnit  *string
	OverheadRate   string
	Allowances     *string
	LevelingFactor *string
	Station        *string
}

type BulkCreateProductionStepResult struct {
	Name             string
	Success          bool
	Error            *string
	ProductionStepID *string
	Action           string // "created", "updated", or "skipped"
}

type BulkCreateProductionStepsParams struct {
	AccountID string
	Steps     []BulkCreateProductionStepInput
}

type BulkDeleteCustomersParams struct {
	OwnerAccountID string
	CustomerIDs    []string
}

type BulkDeletePurchaseOrdersParams struct {
	PurchaseOrderIDs []string
	AccountID        string
}

type BulkDeleteSalesOrdersParams struct {
	SalesOrderIDs []string
	AccountID     string
}

type BulkDeleteSuppliersParams struct {
	OwnerAccountID string
	SupplierIDs    []string
}

type BulkOnHandInventory struct {
	ItemID           string
	OnHandQuantity   float64
	UnitID           string
	UnitAbbreviation string
	UnitType         string
}

type BulkOperationJobEvent struct {
	JobID string
}

type BulkReconcileItemInput struct {
	SKU     string
	Unit    string
	Measure decimal.Decimal
}

type BulkReconcileItemsParams struct {
	AccountID         string
	Data              []BulkReconcileItemInput
	ReconcileType     string // "addition" or "force"
	ResponsibleUserID *string
}

type BulkReconcileItemsResult struct {
	ReconciledItems []ReconciledItem
	SkippedItems    []SkippedItem
	Errors          []ReconcileError
}

type BulkResolveHubspotReviewsParams struct {
	JobID   string
	Reviews []ResolveHubspotReviewParams
}

type BulkUpsertDepartmentsParams struct {
	Departments []UpsertDepartmentParams
}

type BulkUpsertItemCategoriesParams struct {
	ItemCategories []UpsertItemCategoryParams
}

type BulkUpsertLocationsParams struct {
	Locations []UpsertLocationParams
}

type BulkUpsertMachinesParams struct {
	Machines []UpsertMachineParams
}

type BulkUpsertMaterialsParams struct {
	Materials []UpsertMaterialParams
}

type BulkUpsertPartsParams struct {
	Parts []UpsertPartParams
}

type BulkUpsertProductLinesParams struct {
	ProductLines []UpsertProductLineParams
}

type BulkUpsertProductionStepsParams struct {
	ProductionSteps []UpsertProductionStepParams
}

type BulkUpsertProductionStepsResult struct {
	CreatedIDs []string
	UpdatedIDs []string
}

type BulkUpsertProductsParams struct {
	Products []UpsertProductParams
}

type BulkUpsertPropertiesParams struct {
	Properties []UpsertPropertyParams
}

type BulkUpsertScanningStationsParams struct {
	ScanningStations []UpsertScanningStationParams
}

type BulkUpsertUnitGroupsParams struct {
	UnitGroups []UpsertUnitGroupParams
}

type BulkUpsertUnitsParams struct {
	Units []UpsertUnitParams
}

type BurnRateConsumptionLog struct {
	Value     string
	UnitID    string
	CreatedAt time.Time
}

type BurnRateMed interface {
	// RecalculateFromHistory updates the item's burn_rate from consumption change logs over the last 30 days. No-op when there is insufficient history.
	//
	//  1. Load the item and resolve its category's base unit.
	//  2. List the item's consumption change logs; no-op when fewer than two exist.
	//  3. Sum the absolute consumption quantities, converting each to the base unit.
	//  4. Divide the total by the days elapsed between the first and last log.
	//  5. Persist the resulting per-day rate to the item's burn rate.
	RecalculateFromHistory(ctx context.Context, accountID, itemID string) *apierror.APIError
}

type CancelJobParams struct {
	JobID string
}

type Carrier struct {
	ID                     string
	Name                   string  `audit:"name"`
	Code                   *string `audit:"code"`
	ShippoCarrierAccountID *string
	AccountNumber          *string `audit:"account_number"`
	IsPortalEnabled        bool    `audit:"is_portal_enabled"`
	AccountID              *string
	DeletedAt              *time.Time
	ServiceLevels          []*ServiceLevel
	CreatedAt              time.Time
	UpdatedAt              time.Time

	// Populated only by BatchGetCarriersByIDs when a positive service_levels_limit was requested. Not persisted; transient on the response path so the gRPC layer can mirror them into CarrierInfo's service_level_ids_preview / service_levels_has_more fields.
	ServiceLevelIDsPreview []string `audit:"-"`
	ServiceLevelsHasMore   bool     `audit:"-"`
}

type CarrierRepo interface {
	List(ctx context.Context, params ListCarriersParams) (*ListCarriersResult, *apierror.APIError)
	Get(ctx context.Context, params GetCarrierParams) (*Carrier, *apierror.APIError)
	GetByIDs(ctx context.Context, accountID string, ids []string) ([]*Carrier, *apierror.APIError)
	Create(ctx context.Context, id string, params CreateCarrierParams) (*Carrier, *apierror.APIError)
	Update(ctx context.Context, params UpdateCarrierParams) (*Carrier, *apierror.APIError)
	SoftDelete(ctx context.Context, accountID, carrierID string) *apierror.APIError
	DeleteOptionsByCarrierID(ctx context.Context, accountID, carrierID string) *apierror.APIError
	ExistsByName(ctx context.Context, accountID, name string, excludeID *string) (bool, *apierror.APIError)
	ListOptionsByCarrierID(ctx context.Context, accountID, carrierID string) ([]*ServiceLevel, *apierror.APIError)
	// ListOptionIDsForCarriers returns all carrier_option IDs grouped by carrier_id, ordered (carrier_id, created_at ASC, id ASC) — callers truncate to a per-carrier preview limit in Go.
	ListOptionIDsForCarriers(ctx context.Context, accountID string, carrierIDs []string) (map[string][]string, *apierror.APIError)
	// GetOptionsByIDs returns full ServiceLevel records by id with the same account-scoping rule as ListOptionsByCarrierID (the parent carrier must be the caller's own or a system carrier).
	GetOptionsByIDs(ctx context.Context, accountID string, ids []string) ([]*ServiceLevel, *apierror.APIError)
}

type CarrierSvc interface {
	// ListCarriers returns a paginated list of carriers visible to the caller's account.
	ListCarriers(ctx context.Context, params ListCarriersParams) (*ListCarriersResult, *apierror.APIError)

	// GetCarrier returns a single carrier by ID.
	GetCarrier(ctx context.Context, params GetCarrierParams) (*Carrier, *apierror.APIError)

	// BatchGetCarriersByIDs returns carriers by ID for the api-gateway include resolver. Authorization matches GetCarrier (caller's own account + system carriers). When serviceLevelsLimit > 0, each returned carrier carries a preview of up to N service_level IDs plus a has_more flag.
	BatchGetCarriersByIDs(ctx context.Context, ids []string, serviceLevelsLimit int32) ([]*Carrier, *apierror.APIError)

	// BatchGetServiceLevelsByIDs returns service levels by ID for the api-gateway include resolver. Authorization follows the parent carrier's account scope.
	BatchGetServiceLevelsByIDs(ctx context.Context, ids []string) ([]*ServiceLevel, *apierror.APIError)

	// CreateCarrier creates a new carrier, optionally registering with Shippo.
	CreateCarrier(ctx context.Context, params CreateCarrierParams) (*Carrier, *apierror.APIError)

	// UpdateCarrier partially updates a carrier.
	UpdateCarrier(ctx context.Context, params UpdateCarrierParams) (*Carrier, *apierror.APIError)

	// DeleteCarrier soft-deletes a carrier and cascades to options.
	DeleteCarrier(ctx context.Context, carrierID string) *apierror.APIError

	// InitiateOAuth starts the OAuth flow for a Shippo-managed carrier.
	InitiateOAuth(ctx context.Context, carrierID, redirectURI string, state *string) (string, *apierror.APIError)

	// GetOAuthStatus returns the OAuth connection status for a carrier.
	GetOAuthStatus(ctx context.Context, carrierID string) (string, *apierror.APIError)

	// SyncOptions syncs service levels from Shippo service levels.
	SyncOptions(ctx context.Context, carrierID string) (*Carrier, *apierror.APIError)
}

type CarrierTransitCandidates struct {
	// LaneDays is the cached carrier estimate for this exact lane, nil when it has never been warmed.
	LaneDays *int
	// LaneSourceCode says how the cached row was obtained, so a refresh knows whether it may overwrite it.
	LaneSourceCode string
	// LaneRefreshedAt is when the cached row was last written, used to judge staleness.
	LaneRefreshedAt *time.Time
	// ServiceLevelDefaultDays is the fallback configured on the service level, nil when none is set.
	ServiceLevelDefaultDays *int
}

type CarrierTransitEstimateRepo interface {
	// Resolve returns both transit candidates for a lane in one round trip. A lane whose service level does not exist (or belongs to another account) resolves to nil rather than an error: the caller's fallback is to stamp no transit at all.
	Resolve(ctx context.Context, accountID string, lane TransitLane) (*CarrierTransitCandidates, *apierror.APIError)
	// Upsert writes a harvested estimate, leaving an operator-entered row for the same lane untouched.
	Upsert(ctx context.Context, params UpsertTransitEstimateParams) *apierror.APIError
}

type CarryForwardBatch struct {
	BatchID             string
	ProductionRunID     string
	ProductionRunNumber string
	ProductionStepID    *string
	Quantity            float64
	UnitID              string
}

type CatalogAttribute struct {
	ID           string
	Name         string
	PropertyID   string
	PropertyName string
}

type CatalogCategory struct {
	ID         string
	Name       string
	Properties []*CatalogProperty
	Products   []*CatalogProduct
}

type CatalogProduct struct {
	ItemID      string
	SKU         string
	Description string
	Attributes  []*CatalogAttribute
}

type CatalogProductLine struct {
	ID   string
	Name string
}

type CatalogProperty struct {
	ID   string
	Name string
}