Prescriptoo Docs

Appearance

public ​

go
import "github.com/prescriptoo/prescriptoo-api/services/subscription/public"

Package public exposes subscription-owned billing contracts and curated capabilities.

Index ​

Variables ​

go
var (
    // ErrInvalidInput rejects invalid billing command data.
    ErrInvalidInput = errors.New("invalid billing input")
    // ErrNotFound hides absent or out-of-scope billing resources.
    ErrNotFound = errors.New("billing resource not found")
    // ErrConflict rejects conflicting lifecycle transitions or retry payloads.
    ErrConflict = errors.New("billing state conflict")
    // ErrForbidden rejects missing trusted administrative context.
    ErrForbidden = errors.New("billing access forbidden")
    // ErrUnavailable reports a required billing dependency failure.
    ErrUnavailable = errors.New("billing service unavailable")
    // ErrSubscriptionReadOnly denies organization business writes without eligible access.
    ErrSubscriptionReadOnly = errors.New("subscription_read_only")
    // ErrCapacityExceeded rejects active relationship usage beyond the agreed capacities.
    ErrCapacityExceeded = errors.New("subscription capacity exceeded")
)

ErrNotImplemented is retained for source compatibility. Deprecated: mounted billing operations are implemented and do not return it.

go
var ErrNotImplemented = errors.New("subscription operation is not implemented")

type ArchiveBillingPlanCapability ​

ArchiveBillingPlanCapability is the narrow provider interface for one billing operation.

go
type ArchiveBillingPlanCapability interface {
    ArchiveBillingPlan(context.Context, ArchiveBillingPlanInput) (*Empty, error)
}

type ArchiveBillingPlanInput ​

ArchiveBillingPlanInput supplies the archive billing plan operation.

go
type ArchiveBillingPlanInput struct {
    BillingAccess
    Authorization string
    Query         Query
    PlanID        string
}

type AuthInput ​

AuthInput carries bearer credentials to the owning use case.

go
type AuthInput struct {
    Authorization string `header:"Authorization" hidden:"true"`
}

type BillingAccess ​

BillingAccess is server-constructed following authentication and permission checks. It is never decoded from a request body.

go
type BillingAccess struct {
    Audit          audit.OperationContext
    IdempotencyKey string
}

type CatalogListInput ​

CatalogListInput lists public offerings without authentication.

go
type CatalogListInput struct{ PaginationInput }

type CreateBillingInvoiceCapability ​

CreateBillingInvoiceCapability is the narrow provider interface for one billing operation.

go
type CreateBillingInvoiceCapability interface {
    CreateBillingInvoice(context.Context, CreateBillingInvoiceInput) (*Invoice, error)
}

type CreateBillingInvoiceInput ​

CreateBillingInvoiceInput supplies the create billing invoice operation.

go
type CreateBillingInvoiceInput struct {
    BillingAccess
    Authorization  string
    Query          Query
    SubscriptionID string
    Params         CreateInvoiceParams
}

type CreateBillingPlanCapability ​

CreateBillingPlanCapability is the narrow provider interface for one billing operation.

go
type CreateBillingPlanCapability interface {
    CreateBillingPlan(context.Context, CreateBillingPlanInput) (*Plan, error)
}

type CreateBillingPlanInput ​

CreateBillingPlanInput supplies the create billing plan operation.

go
type CreateBillingPlanInput struct {
    BillingAccess
    Authorization string
    Query         Query
    Params        CreatePlanParams
}

type CreateBillingSubscriptionCapability ​

CreateBillingSubscriptionCapability is the narrow provider interface for one billing operation.

go
type CreateBillingSubscriptionCapability interface {
    CreateBillingSubscription(context.Context, CreateBillingSubscriptionInput) (*Subscription, error)
}

type CreateBillingSubscriptionInput ​

CreateBillingSubscriptionInput supplies the create billing subscription operation.

go
type CreateBillingSubscriptionInput struct {
    BillingAccess
    Authorization string
    Query         Query
    Params        CreateSubscriptionParams
}

type CreateInvoiceInput ​

CreateInvoiceInput describes a draft charge.

go
type CreateInvoiceInput struct {
    SubscriptionPathInput
    Body CreateInvoiceParams
}

func (*CreateInvoiceInput) Resolve ​

go
func (i *CreateInvoiceInput) Resolve(_ huma.Context) []error

Resolve validates the draft invoice's complete date pairs.

type CreateInvoiceParams ​

CreateInvoiceParams describes one draft charge; no line items, taxes or discounts are introduced.

go
type CreateInvoiceParams struct {
    Description        string    `json:"description" minLength:"1" maxLength:"2000" example:"Subscription charge" doc:"Human-readable offering or invoice charge description."`
    AmountMinor        int64     `json:"amount_minor" minimum:"1" example:"100000" doc:"Positive charge or payment amount in integer BDT minor units."`
    CoveredPeriodStart time.Time `json:"covered_period_start" example:"2030-01-01T00:00:00Z" doc:"Inclusive start of the period described by the charge."`
    CoveredPeriodEnd   time.Time `json:"covered_period_end" example:"2030-02-01T00:00:00Z" doc:"Exclusive end of the covered period; must follow its start."`
    InvoiceDate        time.Time `json:"invoice_date" example:"2030-01-01T00:00:00Z" doc:"Invoice date supplied for the charge."`
    DueDate            time.Time `json:"due_date" example:"2030-01-10T00:00:00Z" doc:"Payment due timestamp, on or after invoice date."`
    Notes              string    `json:"notes,omitempty" maxLength:"2000" doc:"Optional administrative notes."`
}

type CreatePlanInput ​

CreatePlanInput carries a complete shared offering.

go
type CreatePlanInput struct {
    AuthInput
    Body CreatePlanParams
}

type CreatePlanParams ​

CreatePlanParams defines an initial shared offering with both required capacities.

go
type CreatePlanParams struct {
    Name        string   `json:"name" minLength:"1" maxLength:"255" example:"Standard" doc:"Display name of the shared offering."`
    Slug        string   `json:"slug" minLength:"1" maxLength:"255" example:"standard" doc:"Unique immutable offering slug."`
    Description string   `json:"description,omitempty" maxLength:"2000" doc:"Human-readable offering or invoice charge description."`
    PriceMinor  int64    `json:"price_minor" minimum:"0" example:"100000" doc:"Agreed price in nonnegative integer BDT minor units."`
    Currency    string   `json:"currency,omitempty" enum:"BDT" default:"BDT" doc:"Currency is always BDT; no conversion is performed."`
    Interval    string   `json:"interval" enum:"monthly,yearly" example:"monthly" doc:"Offering billing interval; subscription periods are explicitly supplied by admins."`
    Features    Features `json:"features" doc:"Complete shared-plan feature map with required initial capacities."`
    IsPublic    bool     `json:"is_public" doc:"Whether an active offering appears in the public catalog."`
}

type CreateSubscriptionInput ​

CreateSubscriptionInput carries explicit subscription dates and optional customization.

go
type CreateSubscriptionInput struct {
    AuthInput
    Body CreateSubscriptionParams
}

func (*CreateSubscriptionInput) Resolve ​

go
func (i *CreateSubscriptionInput) Resolve(_ huma.Context) []error

Resolve validates the local subscription date/trial rules before application lifecycle validation.

type CreateSubscriptionParams ​

CreateSubscriptionParams specifies explicit dates; billing does not activate access.

go
type CreateSubscriptionParams struct {
    OrganizationID     string           `json:"organization_id" minLength:"1" example:"22222222-2222-4222-8222-222222222222" doc:"Organization billed by this subscription or charge."`
    PlanID             string           `json:"plan_id" minLength:"1" example:"11111111-1111-4111-8111-111111111111" doc:"Shared offering to snapshot; a different assignment resets price and overrides before explicit values apply."`
    CurrentPeriodStart time.Time        `json:"current_period_start" example:"2030-01-01T00:00:00Z" doc:"Inclusive subscription access start timestamp; immutable after creation."`
    CurrentPeriodEnd   time.Time        `json:"current_period_end" example:"2030-02-01T00:00:00Z" doc:"Exclusive subscription expiry; extend through the separate extension operation."`
    Status             string           `json:"status,omitempty" enum:"active,trialing" default:"active" doc:"Resource lifecycle state."`
    TrialEndsAt        *time.Time       `json:"trial_ends_at,omitempty" doc:"Exclusive trial access end; must follow start and fall within the subscription period."`
    PriceMinor         *int64           `json:"price_minor,omitempty" minimum:"0" doc:"Omit to use the assigned plan price."`
    FeatureOverrides   FeatureOverrides `json:"feature_overrides,omitempty" doc:"Per-subscription override map. Supplied objects replace the complete map; omitted keys revert to the snapshot and null values mean unlimited."`
}

type CurrentSubscription ​

CurrentSubscription marks the provenance of the supplied billing snapshot.

go
type CurrentSubscription struct {
    // A nil snapshot represents no current subscription. IsMock describes the
    // returned billing data only. Real relationship counts are read separately;
    // neither a mock snapshot nor this flag grants a financial entitlement.
    Subscription *Subscription
    IsMock       bool
}

type CurrentSubscriptions ​

CurrentSubscriptions is the batch read boundary for organization projections. A missing map entry means no current subscription; mocks are selected explicitly.

go
type CurrentSubscriptions interface {
    // CurrentSubscriptions batches snapshots for caller-validated organization IDs.
    // Implementations must propagate read failures instead of inventing a mock fallback.
    CurrentSubscriptions(context.Context, []string) (map[string]CurrentSubscription, error)
}

type DeleteBillingSubscriptionCapability ​

DeleteBillingSubscriptionCapability is the narrow provider interface for one billing operation.

go
type DeleteBillingSubscriptionCapability interface {
    DeleteBillingSubscription(context.Context, DeleteBillingSubscriptionInput) (*Empty, error)
}

type DeleteBillingSubscriptionInput ​

DeleteBillingSubscriptionInput supplies the delete billing subscription operation.

go
type DeleteBillingSubscriptionInput struct {
    BillingAccess
    Authorization  string
    Query          Query
    SubscriptionID string
}

type EditBillingInvoiceCapability ​

EditBillingInvoiceCapability is the narrow provider interface for one billing operation.

go
type EditBillingInvoiceCapability interface {
    EditBillingInvoice(context.Context, EditBillingInvoiceInput) (*Invoice, error)
}

type EditBillingInvoiceInput ​

EditBillingInvoiceInput supplies the edit billing invoice operation.

go
type EditBillingInvoiceInput struct {
    BillingAccess
    Authorization string
    Query         Query
    InvoiceID     string
    Params        EditInvoiceParams
}

type EditBillingPlanCapability ​

EditBillingPlanCapability is the narrow provider interface for one billing operation.

go
type EditBillingPlanCapability interface {
    EditBillingPlan(context.Context, EditBillingPlanInput) (*Plan, error)
}

type EditBillingPlanInput ​

EditBillingPlanInput supplies the edit billing plan operation.

go
type EditBillingPlanInput struct {
    BillingAccess
    Authorization string
    Query         Query
    PlanID        string
    Params        EditPlanParams
}

type EditBillingSubscriptionCapability ​

EditBillingSubscriptionCapability is the narrow provider interface for one billing operation.

go
type EditBillingSubscriptionCapability interface {
    EditBillingSubscription(context.Context, EditBillingSubscriptionInput) (*Subscription, error)
}

type EditBillingSubscriptionInput ​

EditBillingSubscriptionInput supplies the edit billing subscription operation.

go
type EditBillingSubscriptionInput struct {
    BillingAccess
    Authorization  string
    Query          Query
    SubscriptionID string
    Params         EditSubscriptionParams
}

type EditInvoiceInput ​

EditInvoiceInput changes draft charge fields only.

go
type EditInvoiceInput struct {
    InvoicePathInput
    Body EditInvoiceParams
}

func (*EditInvoiceInput) Resolve ​

go
func (i *EditInvoiceInput) Resolve(_ huma.Context) []error

Resolve validates date pairs when both sides are present in a draft edit.

type EditInvoiceParams ​

EditInvoiceParams permits partial changes to drafts only; persisted date pairs are validated later.

go
type EditInvoiceParams struct {
    Description        *string    `json:"description,omitempty" minLength:"1" maxLength:"2000" doc:"Human-readable offering or invoice charge description."`
    AmountMinor        *int64     `json:"amount_minor,omitempty" minimum:"1" doc:"Positive charge or payment amount in integer BDT minor units."`
    CoveredPeriodStart *time.Time `json:"covered_period_start,omitempty" doc:"Inclusive start of the period described by the charge."`
    CoveredPeriodEnd   *time.Time `json:"covered_period_end,omitempty" doc:"Exclusive end of the covered period; must follow its start."`
    InvoiceDate        *time.Time `json:"invoice_date,omitempty" doc:"Invoice date supplied for the charge."`
    DueDate            *time.Time `json:"due_date,omitempty" doc:"Payment due timestamp, on or after invoice date."`
    Notes              *string    `json:"notes,omitempty" maxLength:"2000" doc:"Optional administrative notes."`
}

type EditPlanInput ​

EditPlanInput carries partial live-offering edits.

go
type EditPlanInput struct {
    PlanPathInput
    Body EditPlanParams
}

type EditPlanParams ​

EditPlanParams changes an offering without modifying historical subscription snapshots.

go
type EditPlanParams struct {
    Name        *string   `json:"name,omitempty" minLength:"1" maxLength:"255" doc:"Display name of the shared offering."`
    Description *string   `json:"description,omitempty" maxLength:"2000" doc:"Human-readable offering or invoice charge description."`
    PriceMinor  *int64    `json:"price_minor,omitempty" minimum:"0" doc:"Agreed price in nonnegative integer BDT minor units."`
    Interval    *string   `json:"interval,omitempty" enum:"monthly,yearly" doc:"Offering billing interval; subscription periods are explicitly supplied by admins."`
    Features    *Features `json:"features,omitempty" nullable:"false" doc:"Complete shared-plan feature map with required initial capacities."`
    IsPublic    *bool     `json:"is_public,omitempty" doc:"Whether an active offering appears in the public catalog."`
}

type EditSubscriptionInput ​

EditSubscriptionInput updates plan, price, status or overrides without changing expiry.

go
type EditSubscriptionInput struct {
    SubscriptionPathInput
    Body EditSubscriptionParams
}

func (*EditSubscriptionInput) Resolve ​

go
func (i *EditSubscriptionInput) Resolve(_ huma.Context) []error

Resolve requires a trial end when explicitly changing a subscription to trialing.

type EditSubscriptionParams ​

EditSubscriptionParams preserves omitted fields; a new plan resets price and overrides before explicit values apply.

go
type EditSubscriptionParams struct {
    TrialEndsAtSet   bool              `json:"-" hidden:"true"`
    PlanID           *string           `json:"plan_id,omitempty" minLength:"1" doc:"Shared offering to snapshot; a different assignment resets price and overrides before explicit values apply."`
    PriceMinor       *int64            `json:"price_minor,omitempty" minimum:"0" doc:"Agreed price in nonnegative integer BDT minor units."`
    Status           *string           `json:"status,omitempty" enum:"trialing,active,past_due,canceled,expired" doc:"Resource lifecycle state."`
    TrialEndsAt      *time.Time        `json:"trial_ends_at,omitempty" doc:"Used when changing status to trialing; must be within the existing subscription dates."`
    FeatureOverrides *FeatureOverrides `json:"feature_overrides,omitempty" nullable:"false" doc:"Replace the entire overrides map. Use {} to clear it; null values inside the map mean unlimited."`
}

func (*EditSubscriptionParams) UnmarshalJSON ​

go
func (p *EditSubscriptionParams) UnmarshalJSON(data []byte) error

UnmarshalJSON preserves exact numeric values and explicit PATCH field presence.

type Empty ​

Empty denotes an intended 204 response without a body.

go
type Empty struct{}

type Entitlements ​

Entitlements separates numeric capacities from eligibility and authorization.

go
type Entitlements interface {
    CheckCapacity(context.Context, string, int, int) error
}

type ExtendBillingSubscriptionCapability ​

ExtendBillingSubscriptionCapability is the narrow provider interface for one billing operation.

go
type ExtendBillingSubscriptionCapability interface {
    ExtendBillingSubscription(context.Context, ExtendBillingSubscriptionInput) (*Subscription, error)
}

type ExtendBillingSubscriptionInput ​

ExtendBillingSubscriptionInput supplies the extend billing subscription operation.

go
type ExtendBillingSubscriptionInput struct {
    BillingAccess
    Authorization  string
    Query          Query
    SubscriptionID string
    Params         ExtendSubscriptionParams
}

type ExtendSubscriptionInput ​

ExtendSubscriptionInput carries a later explicit expiry.

go
type ExtendSubscriptionInput struct {
    SubscriptionPathInput
    Body ExtendSubscriptionParams
}

func (*ExtendSubscriptionInput) Resolve ​

go
func (i *ExtendSubscriptionInput) Resolve(_ huma.Context) []error

Resolve rejects a request-local extension date in the past; stored-date checks run in the use case.

type ExtendSubscriptionParams ​

ExtendSubscriptionParams sets a later end without activating an expired subscription.

go
type ExtendSubscriptionParams struct {
    CurrentPeriodEnd time.Time `json:"current_period_end" example:"2030-03-01T00:00:00Z" doc:"Exclusive subscription expiry; extend through the separate extension operation."`
}

type FeatureOverrides ​

FeatureOverrides replaces selected snapshot values; null is unlimited, not removal.

go
type FeatureOverrides map[string]any

func (FeatureOverrides) Schema ​

go
func (FeatureOverrides) Schema(_ huma.Registry) *huma.Schema

Schema defines optional overrides; supplying an object replaces the complete overrides map.

func (*FeatureOverrides) UnmarshalJSON ​

go
func (f *FeatureOverrides) UnmarshalJSON(data []byte) error

UnmarshalJSON preserves exact numeric values and explicit PATCH field presence.

type Features ​

Features contains plan flags and limits. Named capacities must be integers or null.

go
type Features map[string]any

func (Features) Schema ​

go
func (Features) Schema(_ huma.Registry) *huma.Schema

Schema defines required initial limits and extensible, typed feature values.

func (*Features) UnmarshalJSON ​

go
func (f *Features) UnmarshalJSON(data []byte) error

UnmarshalJSON preserves exact numeric values and explicit PATCH field presence.

type GetBillingInvoiceCapability ​

GetBillingInvoiceCapability is the narrow provider interface for one billing operation.

go
type GetBillingInvoiceCapability interface {
    GetBillingInvoice(context.Context, GetBillingInvoiceInput) (*Invoice, error)
}

type GetBillingInvoiceInput ​

GetBillingInvoiceInput supplies the get billing invoice operation.

go
type GetBillingInvoiceInput struct {
    BillingAccess
    Authorization string
    Query         Query
    InvoiceID     string
}

type GetBillingPaymentCapability ​

GetBillingPaymentCapability is the narrow provider interface for one billing operation.

go
type GetBillingPaymentCapability interface {
    GetBillingPayment(context.Context, GetBillingPaymentInput) (*Payment, error)
}

type GetBillingPaymentInput ​

GetBillingPaymentInput supplies the get billing payment operation.

go
type GetBillingPaymentInput struct {
    BillingAccess
    Authorization string
    Query         Query
    PaymentID     string
}

type GetBillingPlanCapability ​

GetBillingPlanCapability is the narrow provider interface for one billing operation.

go
type GetBillingPlanCapability interface {
    GetBillingPlan(context.Context, GetBillingPlanInput) (*Plan, error)
}

type GetBillingPlanInput ​

GetBillingPlanInput supplies the get billing plan operation.

go
type GetBillingPlanInput struct {
    BillingAccess
    Authorization string
    Query         Query
    PlanID        string
}

type GetBillingSubscriptionCapability ​

GetBillingSubscriptionCapability is the narrow provider interface for one billing operation.

go
type GetBillingSubscriptionCapability interface {
    GetBillingSubscription(context.Context, GetBillingSubscriptionInput) (*Subscription, error)
}

type GetBillingSubscriptionInput ​

GetBillingSubscriptionInput supplies the get billing subscription operation.

go
type GetBillingSubscriptionInput struct {
    BillingAccess
    Authorization  string
    Query          Query
    SubscriptionID string
}

type GetPublicPlanCapability ​

GetPublicPlanCapability is the narrow provider interface for one billing operation.

go
type GetPublicPlanCapability interface {
    GetPublicPlan(context.Context, GetPublicPlanInput) (*Plan, error)
}

type GetPublicPlanInput ​

GetPublicPlanInput supplies the get public plan operation.

go
type GetPublicPlanInput struct {
    Authorization string
    Query         Query
    PlanID        string
}

type Invoice ​

Invoice is a single charge with balances derived from non-voided manual payments.

go
type Invoice struct {
    IsOverdue            bool       `json:"is_overdue"`
    ID                   string     `json:"id" example:"44444444-4444-4444-8444-444444444444" doc:"Stable server-generated resource identifier."`
    InvoiceNumber        string     `json:"invoice_number" example:"INV-2026-001" doc:"Server-generated human-readable invoice number."`
    OrganizationID       string     `json:"organization_id" doc:"Organization billed by this subscription or charge."`
    SubscriptionID       string     `json:"subscription_id" doc:"Subscription associated with this invoice or payment."`
    Description          string     `json:"description" example:"Clinic subscription charge" doc:"Human-readable offering or invoice charge description."`
    AmountMinor          int64      `json:"amount_minor" minimum:"1" example:"100000" doc:"Positive charge or payment amount in integer BDT minor units."`
    Currency             string     `json:"currency" enum:"BDT" doc:"Currency is always BDT; no conversion is performed."`
    PaidMinor            int64      `json:"paid_minor" minimum:"0" doc:"Sum of non-voided payments against the invoice."`
    BalanceMinor         int64      `json:"balance_minor" minimum:"0" doc:"Invoice amount minus non-voided paid total; overpayment is rejected."`
    CoveredPeriodStart   time.Time  `json:"covered_period_start" doc:"Inclusive start of the period described by the charge."`
    CoveredPeriodEnd     time.Time  `json:"covered_period_end" doc:"Exclusive end of the covered period; must follow its start."`
    InvoiceDate          time.Time  `json:"invoice_date" doc:"Invoice date supplied for the charge."`
    DueDate              time.Time  `json:"due_date" doc:"Payment due timestamp, on or after invoice date."`
    Notes                string     `json:"notes,omitempty" doc:"Optional administrative notes."`
    Status               string     `json:"status" enum:"draft,open,paid,void,uncollectible" doc:"uncollectible is reserved; this API does not offer write-off."`
    IssuedAt             *time.Time `json:"issued_at,omitempty" doc:"Server-recorded timestamp when the draft invoice was issued."`
    PaidAt               *time.Time `json:"paid_at,omitempty" doc:"Timestamp payment was received, or when an invoice became fully paid."`
    VoidedAt             *time.Time `json:"voided_at,omitempty" doc:"Server-recorded correction timestamp; the original record remains visible."`
    VoidReason           string     `json:"void_reason,omitempty" doc:"Administrative explanation for voiding this record."`
    CreatedByAdminUserID string     `json:"created_by_admin_user_id" doc:"Trusted platform-admin record ID of the creator; never accepted from the client."`
    UpdatedByAdminUserID string     `json:"updated_by_admin_user_id" doc:"Trusted platform-admin record ID of the last editor."`
    VoidedByAdminUserID  string     `json:"voided_by_admin_user_id,omitempty" doc:"Trusted platform-admin record ID of the correction actor."`
    CreatedAt            time.Time  `json:"created_at" doc:"Server-recorded resource creation timestamp."`
    UpdatedAt            time.Time  `json:"updated_at" doc:"Server-recorded most recent resource update timestamp."`
}

type InvoiceListInput ​

InvoiceListInput filters administrative invoice history.

go
type InvoiceListInput struct {
    AuthInput
    PaginationInput
    OrganizationID string `query:"organization_id"`
    SubscriptionID string `query:"subscription_id"`
    Status         string `query:"status" enum:"draft,open,paid,void,uncollectible"`
}

type InvoicePathInput ​

InvoicePathInput identifies a single-charge invoice.

go
type InvoicePathInput struct {
    AuthInput
    InvoiceID string `path:"invoiceId" minLength:"1"`
}

type InvoicePaymentListInput ​

InvoicePaymentListInput includes recorded and voided payments for an invoice.

go
type InvoicePaymentListInput struct {
    InvoicePathInput
    PaginationInput
    Status string `query:"status" enum:"recorded,voided"`
}

type IssueBillingInvoiceCapability ​

IssueBillingInvoiceCapability is the narrow provider interface for one billing operation.

go
type IssueBillingInvoiceCapability interface {
    IssueBillingInvoice(context.Context, IssueBillingInvoiceInput) (*Invoice, error)
}

type IssueBillingInvoiceInput ​

IssueBillingInvoiceInput supplies the issue billing invoice operation.

go
type IssueBillingInvoiceInput struct {
    BillingAccess
    Authorization string
    Query         Query
    InvoiceID     string
}

type ListBillingInvoicesCapability ​

ListBillingInvoicesCapability is the narrow provider interface for one billing operation.

go
type ListBillingInvoicesCapability interface {
    ListBillingInvoices(context.Context, ListBillingInvoicesInput) (*Page[Invoice], error)
}

type ListBillingInvoicesInput ​

ListBillingInvoicesInput supplies the list billing invoices operation.

go
type ListBillingInvoicesInput struct {
    BillingAccess
    Authorization string
    Query         Query
}

type ListBillingPaymentsCapability ​

ListBillingPaymentsCapability is the narrow provider interface for one billing operation.

go
type ListBillingPaymentsCapability interface {
    ListBillingPayments(context.Context, ListBillingPaymentsInput) (*Page[Payment], error)
}

type ListBillingPaymentsInput ​

ListBillingPaymentsInput supplies the list billing payments operation.

go
type ListBillingPaymentsInput struct {
    BillingAccess
    Authorization string
    Query         Query
}

type ListBillingPlansCapability ​

ListBillingPlansCapability is the narrow provider interface for one billing operation.

go
type ListBillingPlansCapability interface {
    ListBillingPlans(context.Context, ListBillingPlansInput) (*Page[Plan], error)
}

type ListBillingPlansInput ​

ListBillingPlansInput supplies the list billing plans operation.

go
type ListBillingPlansInput struct {
    BillingAccess
    Authorization string
    Query         Query
}

type ListBillingSubscriptionsCapability ​

ListBillingSubscriptionsCapability is the narrow provider interface for one billing operation.

go
type ListBillingSubscriptionsCapability interface {
    ListBillingSubscriptions(context.Context, ListBillingSubscriptionsInput) (*Page[Subscription], error)
}

type ListBillingSubscriptionsInput ​

ListBillingSubscriptionsInput supplies the list billing subscriptions operation.

go
type ListBillingSubscriptionsInput struct {
    BillingAccess
    Authorization string
    Query         Query
}

type ListInvoicePaymentsCapability ​

ListInvoicePaymentsCapability is the narrow provider interface for one billing operation.

go
type ListInvoicePaymentsCapability interface {
    ListInvoicePayments(context.Context, ListInvoicePaymentsInput) (*Page[Payment], error)
}

type ListInvoicePaymentsInput ​

ListInvoicePaymentsInput supplies the list invoice payments operation.

go
type ListInvoicePaymentsInput struct {
    BillingAccess
    Authorization string
    Query         Query
    InvoiceID     string
}

type ListPublicPlansCapability ​

ListPublicPlansCapability is the narrow provider interface for one billing operation.

go
type ListPublicPlansCapability interface {
    ListPublicPlans(context.Context, ListPublicPlansInput) (*Page[Plan], error)
}

type ListPublicPlansInput ​

ListPublicPlansInput supplies the list public plans operation.

go
type ListPublicPlansInput struct {
    Authorization string
    Query         Query
}

type ListSubscriptionInvoicesCapability ​

ListSubscriptionInvoicesCapability is the narrow provider interface for one billing operation.

go
type ListSubscriptionInvoicesCapability interface {
    ListSubscriptionInvoices(context.Context, ListSubscriptionInvoicesInput) (*Page[Invoice], error)
}

type ListSubscriptionInvoicesInput ​

ListSubscriptionInvoicesInput supplies the list subscription invoices operation.

go
type ListSubscriptionInvoicesInput struct {
    BillingAccess
    Authorization  string
    Query          Query
    SubscriptionID string
}

type OrganizationBillingReader ​

OrganizationBillingReader accepts a trusted scope established by Organization's use case.

go
type OrganizationBillingReader interface {
    OrganizationSubscription(context.Context, string) (*Subscription, error)
    OrganizationInvoices(context.Context, string, Query) (*Page[OrganizationInvoice], error)
}

type OrganizationInvoice ​

OrganizationInvoice includes only issued customer-facing charge and settlement fields.

go
type OrganizationInvoice struct {
    ID                 string     `json:"id"`
    InvoiceNumber      string     `json:"invoice_number"`
    OrganizationID     string     `json:"organization_id"`
    SubscriptionID     string     `json:"subscription_id"`
    Description        string     `json:"description"`
    AmountMinor        int64      `json:"amount_minor"`
    Currency           string     `json:"currency"`
    PaidMinor          int64      `json:"paid_minor"`
    BalanceMinor       int64      `json:"balance_minor"`
    CoveredPeriodStart time.Time  `json:"covered_period_start"`
    CoveredPeriodEnd   time.Time  `json:"covered_period_end"`
    InvoiceDate        time.Time  `json:"invoice_date"`
    DueDate            time.Time  `json:"due_date"`
    Status             string     `json:"status"`
    IsOverdue          bool       `json:"is_overdue"`
    IssuedAt           *time.Time `json:"issued_at,omitempty"`
    PaidAt             *time.Time `json:"paid_at,omitempty"`
    VoidedAt           *time.Time `json:"voided_at,omitempty"`
    CreatedAt          time.Time  `json:"created_at"`
    UpdatedAt          time.Time  `json:"updated_at"`
}

type Page ​

Page is a newest-first cursor-paginated result.

go
type Page[T any] struct {
    Items      []T    `json:"items"`
    NextCursor string `json:"next_cursor,omitempty"`
}

type PaginationInput ​

PaginationInput controls newest-first result pagination.

go
type PaginationInput struct {
    Limit  int    `query:"limit" minimum:"1" maximum:"100" default:"20"`
    Cursor string `query:"cursor"`
}

type Payment ​

Payment is an immutable manual entry; corrections void the original and record a replacement.

go
type Payment struct {
    ID                    string     `json:"id" example:"55555555-5555-4555-8555-555555555555" doc:"Stable server-generated resource identifier."`
    InvoiceID             string     `json:"invoice_id" doc:"Invoice whose balance is affected by the manual payment."`
    SubscriptionID        string     `json:"subscription_id" doc:"Subscription associated with this invoice or payment."`
    OrganizationID        string     `json:"organization_id" doc:"Organization billed by this subscription or charge."`
    AmountMinor           int64      `json:"amount_minor" minimum:"1" example:"50000" doc:"Positive charge or payment amount in integer BDT minor units."`
    Currency              string     `json:"currency" enum:"BDT" doc:"Currency is always BDT; no conversion is performed."`
    PaidAt                time.Time  `json:"paid_at" doc:"Timestamp payment was received, or when an invoice became fully paid."`
    Method                string     `json:"method" enum:"cash,bank_transfer,bkash,nagad,card,other" example:"bank_transfer" doc:"Manually entered method by which payment was received."`
    Reference             string     `json:"reference,omitempty" example:"BANK-TXN-123" doc:"Optional external transaction reference; no gateway verification occurs."`
    Notes                 string     `json:"notes,omitempty" doc:"Optional administrative notes."`
    Status                string     `json:"status" enum:"recorded,voided" doc:"Resource lifecycle state."`
    RecordedByAdminUserID string     `json:"recorded_by_admin_user_id" doc:"Trusted platform-admin record ID recording the received payment."`
    CreatedAt             time.Time  `json:"created_at" doc:"Server-recorded resource creation timestamp."`
    VoidedAt              *time.Time `json:"voided_at,omitempty" doc:"Server-recorded correction timestamp; the original record remains visible."`
    VoidedByAdminUserID   string     `json:"voided_by_admin_user_id,omitempty" doc:"Trusted platform-admin record ID of the correction actor."`
    VoidReason            string     `json:"void_reason,omitempty" doc:"Administrative explanation for voiding this record."`
}

type PaymentListInput ​

PaymentListInput filters immutable manual payment records.

go
type PaymentListInput struct {
    AuthInput
    PaginationInput
    OrganizationID string `query:"organization_id"`
    SubscriptionID string `query:"subscription_id"`
    InvoiceID      string `query:"invoice_id"`
    Status         string `query:"status" enum:"recorded,voided"`
}

type PaymentPathInput ​

PaymentPathInput identifies a manual payment entry.

go
type PaymentPathInput struct {
    AuthInput
    PaymentID string `path:"paymentId" minLength:"1"`
}

type Plan ​

Plan is a shared offering; changes never rewrite assigned subscription snapshots.

go
type Plan struct {
    ID          string     `json:"id" example:"11111111-1111-4111-8111-111111111111" doc:"Stable server-generated resource identifier."`
    Name        string     `json:"name" example:"Standard" doc:"Display name of the shared offering."`
    Slug        string     `json:"slug" example:"standard" doc:"Unique immutable offering identifier."`
    Description string     `json:"description" doc:"Human-readable offering or invoice charge description."`
    PriceMinor  int64      `json:"price_minor" minimum:"0" example:"100000" doc:"BDT minor units; never floating-point money."`
    Currency    string     `json:"currency" enum:"BDT" example:"BDT" doc:"Currency is always BDT; no conversion is performed."`
    Interval    string     `json:"interval" enum:"monthly,yearly" example:"monthly" doc:"Offering billing interval; subscription periods are explicitly supplied by admins."`
    Features    Features   `json:"features" doc:"Complete shared-plan feature map with required initial capacities."`
    IsPublic    bool       `json:"is_public" doc:"Whether an active offering appears in the public catalog."`
    IsActive    bool       `json:"is_active" doc:"Whether the offering is assignable; archived offerings are inactive."`
    ArchivedAt  *time.Time `json:"archived_at,omitempty" doc:"Archive timestamp; historical subscription snapshots remain unchanged."`
    CreatedAt   time.Time  `json:"created_at" doc:"Server-recorded resource creation timestamp."`
    UpdatedAt   time.Time  `json:"updated_at" doc:"Server-recorded most recent resource update timestamp."`
}

type PlanListInput ​

PlanListInput includes private and archived plan filters for platform admins.

go
type PlanListInput struct {
    AuthInput
    PaginationInput
    IsPublic string `query:"is_public" enum:"true,false"`
    IsActive string `query:"is_active" enum:"true,false"`
}

type PlanPathInput ​

PlanPathInput identifies a plan; public operations do not declare bearer security.

go
type PlanPathInput struct {
    AuthInput
    PlanID string `path:"planId" minLength:"1"`
}

type Query ​

Query supplies pagination and resource-appropriate filters; newest-first ordering is fixed.

go
type Query struct {
    Limit          int
    Cursor         string
    OrganizationID string
    SubscriptionID string
    InvoiceID      string
    Status         string
    IsPublic       *bool
    IsActive       *bool
}

type RecordBillingPaymentCapability ​

RecordBillingPaymentCapability is the narrow provider interface for one billing operation.

go
type RecordBillingPaymentCapability interface {
    RecordBillingPayment(context.Context, RecordBillingPaymentInput) (*Payment, error)
}

type RecordBillingPaymentInput ​

RecordBillingPaymentInput supplies the record billing payment operation.

go
type RecordBillingPaymentInput struct {
    BillingAccess
    Authorization string
    Query         Query
    InvoiceID     string
    Params        RecordPaymentParams
}

type RecordPaymentInput ​

RecordPaymentInput records a received payment without granting subscription access.

go
type RecordPaymentInput struct {
    InvoicePathInput
    Body RecordPaymentParams
}

type RecordPaymentParams ​

RecordPaymentParams contains manual-entry data; audit actors and currency are server-owned.

go
type RecordPaymentParams struct {
    AmountMinor int64     `json:"amount_minor" minimum:"1" example:"50000" doc:"Positive charge or payment amount in integer BDT minor units."`
    PaidAt      time.Time `json:"paid_at" example:"2026-01-05T10:00:00Z" doc:"Timestamp payment was received, or when an invoice became fully paid."`
    Method      string    `json:"method" enum:"cash,bank_transfer,bkash,nagad,card,other" example:"bank_transfer" doc:"Manually entered method by which payment was received."`
    Reference   string    `json:"reference,omitempty" maxLength:"255" doc:"Optional external transaction reference; no gateway verification occurs."`
    Notes       string    `json:"notes,omitempty" maxLength:"2000" doc:"Optional administrative notes."`
}

type Subscription ​

Subscription retains agreed pricing and feature snapshots independently of plan edits.

go
type Subscription struct {
    IsWritable         bool             `json:"is_writable"`
    ReadOnlyReason     string           `json:"read_only_reason,omitempty"`
    ID                 string           `json:"id" example:"33333333-3333-4333-8333-333333333333" doc:"Stable server-generated resource identifier."`
    OrganizationID     string           `json:"organization_id" example:"22222222-2222-4222-8222-222222222222" doc:"Organization billed by this subscription or charge."`
    Plan               Plan             `json:"plan" doc:"Snapshot of the assigned plan, not the current live offering."`
    PriceMinor         int64            `json:"price_minor" minimum:"0" example:"90000" doc:"Agreed price in nonnegative integer BDT minor units."`
    Currency           string           `json:"currency" enum:"BDT" doc:"Currency is always BDT; no conversion is performed."`
    FeatureOverrides   FeatureOverrides `json:"feature_overrides" doc:"Per-subscription override map. Supplied objects replace the complete map; omitted keys revert to the snapshot and null values mean unlimited."`
    EffectiveFeatures  Features         `json:"effective_features" doc:"Assigned plan features merged with per-subscription overrides."`
    Status             string           `json:"status" enum:"trialing,active,past_due,canceled,expired" doc:"Resource lifecycle state."`
    CurrentPeriodStart time.Time        `json:"current_period_start" doc:"Inclusive subscription access start timestamp; immutable after creation."`
    CurrentPeriodEnd   time.Time        `json:"current_period_end" doc:"Exclusive subscription expiry; extend through the separate extension operation."`
    TrialEndsAt        *time.Time       `json:"trial_ends_at,omitempty" doc:"Exclusive trial access end; must follow start and fall within the subscription period."`
    CanceledAt         *time.Time       `json:"canceled_at,omitempty" doc:"Timestamp access was canceled."`
    DeletedAt          *time.Time       `json:"deleted_at,omitempty" doc:"Soft-deletion timestamp; financial records remain retained."`
    CreatedAt          time.Time        `json:"created_at" doc:"Server-recorded resource creation timestamp."`
    UpdatedAt          time.Time        `json:"updated_at" doc:"Server-recorded most recent resource update timestamp."`
}

type SubscriptionInvoiceListInput ​

SubscriptionInvoiceListInput lists an individual subscription's invoices.

go
type SubscriptionInvoiceListInput struct {
    SubscriptionPathInput
    PaginationInput
    Status string `query:"status" enum:"draft,open,paid,void,uncollectible"`
}

type SubscriptionListInput ​

SubscriptionListInput filters current and historical subscriptions.

go
type SubscriptionListInput struct {
    AuthInput
    PaginationInput
    OrganizationID string `query:"organization_id"`
    Status         string `query:"status" enum:"trialing,active,past_due,canceled,expired"`
}

type SubscriptionPathInput ​

SubscriptionPathInput identifies an organization subscription.

go
type SubscriptionPathInput struct {
    AuthInput
    SubscriptionID string `path:"subscriptionId" minLength:"1"`
}

type SubscriptionService ​

SubscriptionService is the shared request-time eligibility predicate. Invoke only from use cases.

go
type SubscriptionService interface {
    IsActiveSubscription(context.Context, string) (bool, error)
}

type TransactionServices ​

TransactionServices binds reads to a caller-owned transaction after its organization lock. This is an infrastructure boundary; access decisions remain in the calling use case.

go
type TransactionServices interface {
    CurrentInTransaction(pgx.Tx) CurrentSubscriptions
    InTransaction(pgx.Tx) SubscriptionService
    EntitlementsInTransaction(pgx.Tx) Entitlements
}

type VoidBillingInvoiceCapability ​

VoidBillingInvoiceCapability is the narrow provider interface for one billing operation.

go
type VoidBillingInvoiceCapability interface {
    VoidBillingInvoice(context.Context, VoidBillingInvoiceInput) (*Invoice, error)
}

type VoidBillingInvoiceInput ​

VoidBillingInvoiceInput supplies the void billing invoice operation.

go
type VoidBillingInvoiceInput struct {
    BillingAccess
    Authorization string
    Query         Query
    InvoiceID     string
    Params        VoidParams
}

type VoidBillingPaymentCapability ​

VoidBillingPaymentCapability is the narrow provider interface for one billing operation.

go
type VoidBillingPaymentCapability interface {
    VoidBillingPayment(context.Context, VoidBillingPaymentInput) (*Payment, error)
}

type VoidBillingPaymentInput ​

VoidBillingPaymentInput supplies the void billing payment operation.

go
type VoidBillingPaymentInput struct {
    BillingAccess
    Authorization string
    Query         Query
    PaymentID     string
    Params        VoidParams
}

type VoidInvoiceInput ​

VoidInvoiceInput requires an invoice correction reason.

go
type VoidInvoiceInput struct {
    InvoicePathInput
    Body VoidParams
}

type VoidParams ​

VoidParams requires an auditable explanation for a billing correction.

go
type VoidParams struct {
    Reason string `json:"reason" minLength:"1" maxLength:"2000" example:"Incorrect manual entry; replacement follows." doc:"Required nonempty explanation for a billing correction."`
}

type VoidPaymentInput ​

VoidPaymentInput requires a payment correction reason.

go
type VoidPaymentInput struct {
    PaymentPathInput
    Body VoidParams
}

Generated by gomarkdoc

Documentation follows the source. Planned contracts are marked explicitly.