facade4datatug

type AccountPlanEffect ¶ added in v0.5.0

type AccountPlanEffect struct {
	Fence                    PlanOwnerFence
	BuyerID                  string
	AccountKind              string
	PlanID                   string
	PlaceID                  string `json:",omitempty"`
	Tier                     string
	Period                   string
	Status                   string
	LastPaidEnd              time.Time
	ScheduledEnd             time.Time
	EffectiveEnd             time.Time
	PaidService              bool
	AppliedPercent           int
	LaunchGrant              bool
	Grants                   PlanEffectGrants
	Payments                 []PlanPayment
	CashBasisKnown           bool
	MoneyIngestEpoch         int64
	ObservedAt               time.Time
	CheckoutStartedAt        time.Time
	QuoteKey                 string
	PaidServiceProofID       string
	BasisOnly                bool
	SourceSubscriptionID     string
	SourceRevision           int64
	SourcePaidService        bool
	SourceQuoteKey           string
	SourcePaidServiceProofID string
	LastServiceRefund        *ServiceRefundProof
	TerminalFullRefund       bool `json:"terminalFullRefund,omitempty"`
}

AccountPlanEffect is a provider-neutral copy of the accepted payment fact. The host passes the *complete* source fact to VerifyCurrentEffect and ReconcileMoney; this type never substitutes for paymentus's accepted digest.

type AccountPlanWriter ¶ added in v0.5.0

type AccountPlanWriter struct {
	DB        dal.DB
	Owner     PlanEffectOwnerPort
	Personal  PersonalPlanOwnerPort
	Allocator PaidMonthAllocator
	Limits    ProLimitsResolver
	Clock     PlanClock
}

AccountPlanWriter is the DataTug domain writer. Its ports are bound by the host to one DAL database; no provider or cross-extension package is imported.

func (w AccountPlanWriter) Apply(ctx context.Context, effect AccountPlanEffect) (PlanApplyOutcome, error)

type AdmissionReader ¶ added in v0.4.0

type AdmissionReader interface {
	ReadAdmission(context.Context, string, time.Time) (AdmissionState, error)
}

type AdmissionState ¶ added in v0.4.0

type AdmissionState struct {
	TodayUsed int64
	Blocked   string
}

AdmissionState supplies guards that are authoritative outside this module. Blocked is empty, daily, free_budget, or unverified.

type BusinessActivityActorVerifier ¶ added in v0.23.0

type BusinessActivityActorVerifier interface {
	VerifyBusinessActivityActor(context.Context, dal.ReadTransaction, string) error
}

BusinessActivityActorVerifier must bind actorID to the authenticated server identity for this request. Implementations must use only the supplied transaction and must not trust an actor ID copied from a request body.

type BusinessActivityBinding ¶ added in v0.20.0

type BusinessActivityBinding struct {
	Period                                     contract4paymentus.UsagePeriodRef
	PeriodStartUTC, PeriodEndUTC, PaidUntilUTC time.Time
	PaidBindingProofID, QueryUseProofID        string
	QueryUseAllowed                            bool
}

BusinessActivityBinding is returned only by the host's transaction-bound financial and membership authority. It contains canonical paid-period facts, not caller claims. QueryUseAllowed includes current actor/project query-use access; publish/contributor permission is deliberately not required.

type BusinessActivityBindingReader ¶ added in v0.20.0

type BusinessActivityBindingReader interface {
	ReadCurrentBusinessActivityBinding(context.Context, dal.ReadTransaction, string, string, string, time.Time) (BusinessActivityBinding, error)
}

BusinessActivityBindingReader must validate current reciprocal membership, query-use permission and paid service binding using the supplied transaction. It must not start a transaction or call a provider.

type BusinessActivityBindingReaderOptions ¶ added in v0.23.0

type BusinessActivityBindingReaderOptions struct {
	Access        *BusinessProjectAccessVerifier
	InitialStarts contract4paymentus.InitialServiceStartReader
	Periods       contract4paymentus.UsagePeriodReader
	Contacts      CurrentProjectContactPort
	Actors        BusinessActivityActorVerifier
}

type BusinessProjectAccessPolicy ¶ added in v0.21.0

type BusinessProjectAccessPolicy struct {
	GrantVersion string
}

BusinessProjectAccessPolicy is server configuration. Unlimited project and contact grants come from this versioned product policy, never from a money field or the absence of Pro limits.

type BusinessProjectAccessVerifier ¶ added in v0.19.0

type BusinessProjectAccessVerifier struct {
	// contains filtered or unexported fields
}

BusinessProjectAccessVerifier contains no provider or mutation handle. The Paymentus reader can only inspect the caller's transaction; paid end and evidence expiry are both enforced before DataTug uses this result.

func NewBusinessProjectAccessVerifier(reader contract4paymentus.CurrentSpaceServiceReader, policy BusinessProjectAccessPolicy, now func() time.Time) (*BusinessProjectAccessVerifier, error)

func (v *BusinessProjectAccessVerifier) ReadCurrent(ctx context.Context, tx dal.ReadTransaction, spaceID string) (SpaceServiceAccess, error)

type BusinessSharedProjectOptions ¶ added in v0.21.0

type BusinessSharedProjectOptions struct {
	AccessPolicy  BusinessProjectAccessPolicy
	ServiceReader contract4paymentus.CurrentSpaceServiceReader
	ContactLinks  *PaidProjectOwnerLinksOptions
}

BusinessSharedProjectOptions are trusted host composition. The caller's existing Space authority remains required for each create command; current paid access is separately read from Paymentus in that same transaction.

type BusinessUsageCloseTerms ¶ added in v0.23.1

type BusinessUsageCloseTerms struct {
	Capacity           contract4paymentus.UsageCapacityEvidence
	BaseEvent          contract4paymentus.UsageBaseEvent
	BillMonthlyOverage bool
	DiscountPercent    int
}

BusinessUsageCloseTerms is server-derived close authority. A request's capacity digest and pricing choices are not accepted unless this port independently resolves the same frozen terms from the caller's transaction.

type BusinessUsageCloseTermsReader ¶ added in v0.23.1

type BusinessUsageCloseTermsReader interface {
	ReadBusinessUsageCloseTerms(context.Context, dal.ReadTransaction, contract4paymentus.UsagePeriodSnapshot) (BusinessUsageCloseTerms, error)
}

BusinessUsageCloseTermsReader must verify all capacity and pricing inputs from the supplied transaction. It must not use a provider or open a nested transaction. The native implementation refuses any non-empty prepaid basis until DataTug's partial-window coverage policy is approved.

type BusinessUsagePeriodAuthorityOptions ¶ added in v0.23.1

type BusinessUsagePeriodAuthorityOptions struct {
	Access        *BusinessProjectAccessVerifier
	InitialStarts contract4paymentus.InitialServiceStartReader
	Periods       contract4paymentus.UsagePeriodReader
	CloseTerms    BusinessUsageCloseTermsReader
	// Pricing resolves the current server-approved config for new periods. It
	// is a server-owned dependency, never request input. Existing periods keep
	// the config frozen in their native snapshot.
	Pricing func() contract4paymentus.UsagePricingConfig
	Now     func() time.Time
}

type BusinessUsagePeriodService ¶ added in v0.23.1

type BusinessUsagePeriodService struct {
	// contains filtered or unexported fields
}

BusinessUsagePeriodService makes the staged open/close sequence externally idempotent. A partial stage leaves a non-ready checkpoint that cannot admit reports or close; retry completes only after the native ledger confirms the exact stored period.

func NewBusinessUsagePeriodService(db dal.DB, authority *NativeBusinessUsagePeriodAuthority, ledger contract4paymentus.UsageLedger, now func() time.Time) (*BusinessUsagePeriodService, error)

func (s *BusinessUsagePeriodService) Close(ctx context.Context, request contract4paymentus.UsageCloseRequest) (contract4paymentus.UsagePeriodClose, error)

func (s *BusinessUsagePeriodService) OpenCurrent(ctx context.Context, spaceID string) (contract4paymentus.UsagePeriodSnapshot, error)

type CallerAdmissionReader ¶ added in v0.6.0

type CallerAdmissionReader interface {
	ReadAdmissionForCaller(context.Context, string, string, time.Time) (AdmissionState, error)
}

CallerAdmissionReader lets the host read admission for the authenticated caller and the personal account already proved by PersonalAccountDirectory. The implementation must supply the actual daily count, not a placeholder.

type ConfiguredProLimits ¶ added in v0.5.0

type ConfiguredProLimits struct {
	ByPlanID map[string]ProLimitsSnapshot
}

ConfiguredProLimits is a pure, versioned source of complete Pro grants. Production values are supplied by the host's reviewed configuration.

func (c ConfiguredProLimits) ResolveProLimits(planID string, grants PlanEffectGrants) (ProLimitsSnapshot, error)

type CurrentProjectContactPort ¶ added in v0.12.0

type CurrentProjectContactPort interface {
	ReadCurrentProjectContact(context.Context, dal.ReadTransaction, contract4linkage.RelationshipEntityRef) (ProjectContactState, error)
}

type DALProtectedProjectInventory ¶ added in v0.15.0

type DALProtectedProjectInventory struct {
	// contains filtered or unexported fields
}

DALProtectedProjectInventory uses collection-group scans but accepts records only under the exact spaces/{id}/ext/datatug/projects and spaces/{id}/ext/datatug/projectAdmissions ancestry. Group scans also find orphan subcollections whose parent Space document was deleted. The scan is intentionally unbounded by Firestore query limits; a hard local ceiling fails closed rather than returning a truncated count.

func NewDALProtectedProjectInventory(query dal.QueryExecutor) (*DALProtectedProjectInventory, error)

func (i *DALProtectedProjectInventory) CompleteProtectedProjectBasis(ctx context.Context, mode, product, payer string) (InitialProtectedProjectBasis, error)

type Facade ¶

type Facade struct {
	// contains filtered or unexported fields
}

Facade carries the injected database and ports for the DataTug extension's application commands. The host constructs one Facade at composition time (sneat-go/pkg/modules/datatug), wiring a real adapter per port; tests construct it over an in-memory database with fakes.

func NewFacade(db dal.DB, ids IDGenerator) Facade

func (f Facade) CreateProject(
	ctx context.Context, userID, storeID, title string,
) (projectID string, err error)

func (f Facade) RegisterGithubProject(
	ctx context.Context, userID string, request RegisterGithubProjectRequest,
) (projectID string, err error)

type FirstAdmittedMonthReader ¶ added in v0.4.0

type FirstAdmittedMonthReader interface {
	ReadFirstAdmittedMonth(context.Context, string, string, string) (string, error)
}

FirstAdmittedMonthReader reads the same immutable, server-only first-admission marker used by the AI meter. Empty means no question has been admitted yet. It is keyed by product and caller, with the proved personal account included so the host can reject a mismatched binding.

type GitHubCreateRepository ¶ added in v0.14.0

type GitHubCreateRepository interface {
	Scope() GitHubCreateRepositoryScope
	CurrentHead(context.Context, string) (string, error)
	EnsureFolderEmpty(context.Context, string, string) error
	CreateFilesCommit(context.Context, string, string, string, map[string][]byte) (string, error)
	FindCommitByMarker(context.Context, string, string, string, map[string][]byte) (string, error)
}

GitHubCreateRepository is implemented by a per-request, actor-bound adapter around githubauth4datatug.AuthorizedGitHubRepository. Its methods never expose OAuth or installation tokens to this module or to a caller.

type GitHubCreateRepositoryScope ¶ added in v0.14.0

type GitHubCreateRepositoryScope struct {
	ActorID, Owner, Name, Permission string
	RepositoryID                     int64
}

type GitHubProjectAccess ¶ added in v0.14.0

type GitHubProjectAccess struct {
	SpaceID         string
	SharedProjectID string
	Binding         models4datatug.GitHubProjectBinding
}

type GitHubProjectCreateCommand ¶ added in v0.14.0

type GitHubProjectCreateCommand struct {
	ActorID, SpaceID, OperationID, Title string
	BillingIntent                        SharedProjectBillingIntent
	Source                               models4datatug.GitHubCreateSource
}

func (c GitHubProjectCreateCommand) Validate() error

type GitHubProjectCreateResult ¶ added in v0.14.0

type GitHubProjectCreateResult struct {
	ID              string `json:"id"`
	Storage         string `json:"storage"`
	Project         string `json:"project"`
	SpaceID         string `json:"spaceID"`
	SharedProjectID string `json:"sharedProjectID"`
	Branch          string `json:"branch"`
	BranchHead      string `json:"branchHead"`
	Revision        string `json:"revision"`
	TemplateID      string `json:"templateID"`
	TemplateCommit  string `json:"templateCommit"`
}

type GitHubQueryExpectedFile ¶ added in v0.14.0

type GitHubQueryExpectedFile struct {
	OID  string
	Mode string
	Size int64
}

type GitHubQueryFileChange ¶ added in v0.14.0

type GitHubQueryFileChange struct {
	Path    string
	Content []byte
	Delete  bool
}

type GitHubQueryRepository ¶ added in v0.14.0

type GitHubQueryRepository interface {
	Scope() GitHubCreateRepositoryScope
	PrepareQuerySave(context.Context, string, string, string, dto.SaveQueryRequest) (*GitHubQuerySavePlan, error)
	CurrentHead(context.Context, string) (string, error)
	CreateQueryCommit(context.Context, string, string, string, *GitHubQuerySavePlan) (string, error)
	FindQueryCommit(context.Context, string, string, string, *GitHubQuerySavePlan) (string, error)
}

type GitHubQuerySavePlan ¶ added in v0.14.0

type GitHubQuerySavePlan struct {
	Changes      []GitHubQueryFileChange
	ExpectedTree map[string]GitHubQueryExpectedFile
	Response     dto.SaveQueryResponse
	BodyChanged  bool
}

type IDGenerator ¶

type IDGenerator interface {
	// NewID returns the id of a new record.
	NewID(ctx context.Context) (string, error)
}

IDGenerator is a PORT: extension implementation packages stay outside this module. Published contracts and their DTO aliases may be reused; behavior crosses a small interface defined here and is satisfied by an adapter in the host composition root (sneat-go/pkg/modules/datatug/adapters.go). Domain tests fake the port — see facade_test.go's fakeIDGenerator.

type InitialProtectedProjectBasis ¶ added in v0.11.0

type InitialProtectedProjectBasis struct {
	Digest    string
	Allocated int64
}

InitialProtectedProjectBasis must be issued by a trusted complete-inventory verifier. It includes existing allocations across ALL Spaces for this payer. It must also independently bind actor to the verified context and may only read. No runtime reset or missing-record zero inference is provided. An imported count requires the verifier to prove matching immutable allocation records.

type NativeBusinessActivityBindingReader ¶ added in v0.23.0

type NativeBusinessActivityBindingReader struct {
	// contains filtered or unexported fields
}

NativeBusinessActivityBindingReader composes DataTug project authorization with Paymentus' current paid-service and immutable original-start readers. Every authority read is confined to the caller's transaction.

func NewNativeBusinessActivityBindingReader(options BusinessActivityBindingReaderOptions) (*NativeBusinessActivityBindingReader, error)

func (r *NativeBusinessActivityBindingReader) ReadCurrentBusinessActivityBinding(
	ctx context.Context,
	tx dal.ReadTransaction,
	actorID, spaceID, projectID string,
	at time.Time,
) (BusinessActivityBinding, error)

type NativeBusinessUsageCloseTermsReader ¶ added in v0.23.1

type NativeBusinessUsageCloseTermsReader struct {
	// contains filtered or unexported fields
}

NativeBusinessUsageCloseTermsReader composes the existing native paid-lot reader with the immutable Business anchor and exact open usage period. Empty paid-capacity basis is the only supported close today; it does not choose an unapproved lot-window rule.

func NewNativeBusinessUsageCloseTermsReader(db dal.DB, initialStarts contract4paymentus.InitialServiceStartReader, periods contract4paymentus.UsagePeriodReader) (*NativeBusinessUsageCloseTermsReader, error)

func (r *NativeBusinessUsageCloseTermsReader) ReadBusinessUsageCloseTerms(ctx context.Context, tx dal.ReadTransaction, period contract4paymentus.UsagePeriodSnapshot) (BusinessUsageCloseTerms, error)

type NativeBusinessUsagePeriodAuthority ¶ added in v0.23.1

type NativeBusinessUsagePeriodAuthority struct {
	// contains filtered or unexported fields
}

NativeBusinessUsagePeriodAuthority combines current paid access for Open, the immutable original start for both Open and historical Close, and the accepted-receipt completeness checkpoint. It never grants new query access.

func NewNativeBusinessUsagePeriodAuthority(options BusinessUsagePeriodAuthorityOptions) (*NativeBusinessUsagePeriodAuthority, error)

func (a *NativeBusinessUsagePeriodAuthority) VerifyUsage(ctx context.Context, tx dal.ReadTransaction, operation contract4paymentus.UsageOperation) error

type PaidMonthAllocator ¶ added in v0.5.0

type PaidMonthAllocator interface {
	AllocatePaidMonths(PlanPayment, string) (map[string]int64, error)
}

PaidMonthAllocator is a narrow host translation to core's existing AllocatePaidMonths. The writer owns deduplication and aggregation.

type PaidProjectLinkageOptions ¶ added in v0.12.0

type PaidProjectLinkageOptions struct {
	Paid     PaidSharedProjectOptions
	Business *BusinessProjectAccessVerifier
	Roles    ProjectRoleCatalog
	Contacts CurrentProjectContactPort
	Manager  ProjectRoleManagerPort
	Targets  ProjectContactRoleTargetPort
	Now      func() time.Time
}

type PaidProjectLinkagePolicy ¶ added in v0.12.0

type PaidProjectLinkagePolicy struct {
	// contains filtered or unexported fields
}

PaidProjectLinkagePolicy is the DataTug implementation of Core's generic transaction policy. Host activation MUST declare datatug/projects protected before binding generic routes or creating records, then bind this policy for BOTH linkage directions. A UI role list never supplies authority.

func NewPaidProjectLinkagePolicy(o PaidProjectLinkageOptions) (*PaidProjectLinkagePolicy, error)

func (p *PaidProjectLinkagePolicy) AuthorizeRelationshipMutation(ctx context.Context, tx dal.ReadTransaction, b contract4linkage.RelationshipMutationBatch) error

type PaidProjectOwnerLinksOptions ¶ added in v0.12.0

type PaidProjectOwnerLinksOptions struct {
	Roles    ProjectRoleCatalog
	Owner    ProjectOwnerContactPort
	Contacts CurrentProjectContactPort
}

type PaidSharedProjectOptions ¶ added in v0.11.0

type PaidSharedProjectOptions struct {
	Version, Mode, Product string
	// EnableQueryEditCandidates is an explicit host opt-in. Existing paid
	// project routes keep their current behavior until private rules and the
	// observe-only source journey are reviewed and wired by the host.
	EnableQueryEditCandidates bool
	ContactLinks              *PaidProjectOwnerLinksOptions
	Config                    PlanConfig
	Directory                 PersonalAccountDirectory
	Personal                  PersonalPlanOwnerPort
	Owner                     interface {
		ReadOwner(context.Context, dal.ReadTransaction, string, string, string) (PlanOwnerFence, error)
	}
}

PaidSharedProjectOptions are reviewed server configuration, never request fields. This slice supports current personal Pro only. Business grant/AI policy is not inferred from missing limits or historical tier fixtures. Product mutation is LIVE-only: TEST checkout projections never create real shared projects. Future TEST product isolation needs a separate ref namespace.

type PersonalAccount ¶ added in v0.4.0

type PersonalAccount struct{ ID, Title string }

PersonalAccount is an ownership assertion made by the host directory.

func ResolvePersonalPayer(ctx context.Context, callerID, accountHint string, directory PersonalAccountDirectory) (PersonalAccount, error)

type PersonalAccountDirectory ¶ added in v0.4.0

type PersonalAccountDirectory interface {
	PersonalAccount(context.Context, string) (PersonalAccount, error)
}

PersonalAccountDirectory must prove ownership and provision the personal account through the host. This domain never infers an account from a user ID.

type PersonalPlanOwnerPort ¶ added in v0.5.0

type PersonalPlanOwnerPort interface {
	VerifyPersonalOwner(context.Context, dal.ReadTransaction, string, string) error
}

type PersonalPlanService ¶ added in v0.4.0

type PersonalPlanService struct {
	Directory PersonalAccountDirectory
	Plans     PlanReader
	Usage     UsageReader
	Admission AdmissionReader
	// CallerAdmission takes precedence when bound. Admission remains supported
	// for existing consumers; a new host must bind this caller-aware port.
	CallerAdmission CallerAdmissionReader
	Config          PlanConfigReader
	Clock           PlanClock
	FirstMonth      FirstAdmittedMonthReader
}

PersonalPlanService composes ports without depending on transport or store.

func (s PersonalPlanService) Read(ctx context.Context, callerID, accountHint, _ string) (PlanResponse, error)

type PlanAI ¶ added in v0.4.0

type PlanAI struct {
	Unit     string      `json:"unit"`
	Enforced bool        `json:"enforced"`
	PeriodID string      `json:"periodId"`
	Used     int64       `json:"used"`
	Limit    int64       `json:"limit"`
	Left     int64       `json:"left"`
	ResetsAt time.Time   `json:"resetsAt"`
	Today    PlanToday   `json:"today"`
	Blocked  *string     `json:"blocked"`
	Models   []PlanModel `json:"models"`
}

type PlanAccount ¶ added in v0.4.0

type PlanAccount struct {
	AccountID string `json:"accountId"`
	Kind      string `json:"kind"`
	Title     string `json:"title"`
	Plan      string `json:"plan"`
	Role      string `json:"role"`
	Pays      bool   `json:"pays"`
}

type PlanApplyOutcome ¶ added in v0.5.0

type PlanApplyOutcome string

const (
	PlanApplied    PlanApplyOutcome = "applied"
	PlanIdempotent PlanApplyOutcome = "idempotent"
	PlanObsolete   PlanApplyOutcome = "obsolete"
)

type PlanClock ¶ added in v0.4.0

type PlanClock interface{ Now() time.Time }

type PlanConfig ¶ added in v0.4.0

type PlanConfig struct {
	FreeFirstMonthLimits models4datatug.PlanLimits
	FreeLaterMonthLimits models4datatug.PlanLimits
	ProLimits            models4datatug.PlanLimits
	FreeModels           []PlanModel
	ProModels            []PlanModel
	DailyLimit           int64
	// Zero grace stops paid access exactly at PaidUntil. Positive values are
	// explicit legacy policy; do not configure them for strict paid-through plans.
	ActiveGrace  time.Duration
	PastDueGrace time.Duration
	Enforced     bool
	UpgradeURL   string
	ManageURL    string
	SupportEmail string
}

PlanConfig is supplied by the host, rather than encoded in plan policy. The two Free grants differ by the month of the first admitted question, which is independently read from the meter's server-only marker.

type PlanConfigReader ¶ added in v0.4.0

type PlanConfigReader interface {
	ReadPlanConfig(context.Context, string, time.Time) (PlanConfig, error)
}

PlanConfigReader receives the proved account and the one UTC instant sampled for this response; settings can change at runtime without implicit context.

type PlanEffectAuthority ¶ added in v0.5.0

type PlanEffectAuthority string

const (
	PlanEffectCurrent  PlanEffectAuthority = "current"
	PlanEffectObsolete PlanEffectAuthority = "obsolete"
	PlanEffectUnproved PlanEffectAuthority = "unproved"
)

type PlanEffectGrants ¶ added in v0.5.0

type PlanEffectGrants struct {
	Contributors, ProjectContributors, AIQuestions int64
	AIPaysFor                                      string
	ProtectedProjects                              *int64 `json:"protectedProjects,omitempty"`
	ProtectedProjectUsers                          *int64 `json:"protectedProjectUsers,omitempty"`
}

PlanEffectGrants mirrors the values frozen by the payment effect. The protected pair is optional only for accepted legacy effects; complete Pro limits still require a separately versioned server configuration.

type PlanEffectOwnerPort ¶ added in v0.5.0

type PlanEffectOwnerPort interface {
	ReadOwner(context.Context, dal.ReadTransaction, string, string, string) (PlanOwnerFence, error)
	ReadMoneyFence(context.Context, dal.ReadTransaction, string, string, string) (PlanMoneyFence, error)
	ClassifyEffect(context.Context, dal.ReadTransaction, PlanOwnerFence) (PlanEffectAuthority, error)
	VerifyCurrentEffect(context.Context, dal.ReadTransaction, AccountPlanEffect) error
	ReconcileMoney(context.Context, dal.ReadwriteTransaction, AccountPlanEffect) error
}

PlanEffectOwnerPort is bound to paymentus's transaction-aware owner reader. Every method receives the same DAL transaction as the product writer.

type PlanFacts ¶ added in v0.4.0

type PlanFacts struct {
	AccountKind               string                     `json:"accountKind"`
	Tier                      string                     `json:"tier"`
	Period                    string                     `json:"period"`
	ProviderStatus            string                     `json:"providerStatus"`
	PaidUntil                 *time.Time                 `json:"paidUntil,omitempty"`
	EndsAt                    *time.Time                 `json:"endsAt,omitempty"`
	LastInvoiceRefundedInFull bool                       `json:"lastInvoiceRefundedInFull"`
	TerminalFullRefund        bool                       `json:"terminalFullRefund,omitempty"`
	RefundedAt                *time.Time                 `json:"refundedAt,omitempty"`
	FirstPaidAt               *time.Time                 `json:"firstPaidAt,omitempty"`
	Founding                  bool                       `json:"founding"`
	Grants                    *models4datatug.PlanLimits `json:"grants,omitempty"`
}

PlanFacts are plain, provider-independent inputs to the plan-state mapping.

type PlanModel ¶ added in v0.4.0

type PlanModel struct {
	ID      string `json:"id"`
	Class   string `json:"class"`
	Weight  int64  `json:"weight"`
	Default bool   `json:"default"`
}

type PlanMoneyFence ¶ added in v0.5.0

type PlanMoneyFence struct {
	IngestEpoch, ReconciledEpoch int64
	Unresolved                   bool
}

type PlanOwnerFence ¶ added in v0.5.0

type PlanOwnerFence struct {
	Mode, Family, AccountID, OwnerSubscriptionID string
	OwnerGeneration, SubscriptionRevision        int64
}

PlanOwnerFence is copied from the private payment owner tuple by the host.

type PlanPayment ¶ added in v0.5.0

type PlanPayment struct {
	Mode, Provider, InvoiceID, PaymentID, SubscriptionID, AccountID string
	Currency                                                        string
	ReceivedCents                                                   int64
	CashConfirmed, RefundsKnown, DisputeResolved                    bool
	Lines                                                           []PlanPaymentLine
	Refunds                                                         []PlanRefund
}

type PlanPaymentLine ¶ added in v0.5.0

type PlanPaymentLine struct {
	ID, ProductFamily           string
	StartUTC, EndUTC            time.Time
	CashCents, RetainedTaxCents int64
	RetainedTaxKnown            bool
}

type PlanReader ¶ added in v0.4.0

type PlanReader interface {
	ReadCurrentPlan(context.Context, string) (*models4datatug.PlanRecord, error)
}

PlanReader reads only plan/current; an unreadable record falls toward Free.

type PlanRefund ¶ added in v0.5.0

type PlanRefund struct {
	ID               string
	GrossCents       int64
	LineGrossCents   map[string]int64
	AttributionKnown bool
}

type PlanResponse ¶ added in v0.4.0

type PlanResponse struct {
	V             int                       `json:"v"`
	Payer         string                    `json:"payer"`
	AccountID     string                    `json:"accountId"`
	AccountTitle  string                    `json:"accountTitle"`
	Role          string                    `json:"role"`
	Plan          string                    `json:"plan"`
	EffectivePlan string                    `json:"effectivePlan"`
	Status        string                    `json:"status"`
	Period        string                    `json:"period"`
	PaidUntil     *time.Time                `json:"paidUntil,omitempty"`
	Founding      bool                      `json:"founding"`
	Limits        models4datatug.PlanLimits `json:"limits"`
	AI            PlanAI                    `json:"ai"`
	OwnKeyWorks   bool                      `json:"ownKeyWorks"`
	CanUpgrade    bool                      `json:"canUpgrade"`
	UpgradeURL    string                    `json:"upgradeUrl"`
	ManageURL     string                    `json:"manageUrl,omitempty"`
	SupportEmail  string                    `json:"supportEmail,omitempty"`
	Accounts      []PlanAccount             `json:"accounts"`
}

type PlanStateResult ¶ added in v0.4.0

type PlanStateResult struct {
	Outcome string                     `json:"outcome"`
	Reason  string                     `json:"reason,omitempty"`
	Record  *models4datatug.PlanRecord `json:"record,omitempty"`
}

PlanStateResult names a write, leave, or refusal. The writer retains the previous aiExtraQuestions and stamps updatedAt outside this pure function.

func PlanStateFor(f PlanFacts) PlanStateResult

type PlanToday ¶ added in v0.4.0

type PlanToday struct {
	Used  int64 `json:"used"`
	Limit int64 `json:"limit"`
}

type PreparedSharedProjectCreate ¶ added in v0.10.0

type PreparedSharedProjectCreate struct {
	Binding   SharedProjectCreateBinding
	IssuedAt  time.Time
	Validator SharedProjectCreateTransactionAuthority
}

PreparedSharedProjectCreate is server-to-server only. Its validator privately owns the opaque Core reservation; that reservation never enters this DTO or a public response. The domain checks Binding and captures its validation clock AFTER preparation, before entering any retryable callback.

type ProBusinessSharedProjectOptions ¶ added in v0.21.0

type ProBusinessSharedProjectOptions struct {
	Pro      PaidSharedProjectOptions
	Business BusinessSharedProjectOptions
}

ProBusinessSharedProjectOptions configures both plans on one route service. Billing intent selects only which authority to prove; it never grants one.

type ProLimitsResolver ¶ added in v0.5.0

type ProLimitsResolver interface {
	ResolveProLimits(string, PlanEffectGrants) (ProLimitsSnapshot, error)
}

type ProLimitsSnapshot ¶ added in v0.5.0

type ProLimitsSnapshot struct {
	Version            string
	ProjectGuestsKnown bool
	Limits             models4datatug.PlanLimits
}

type ProjectAIEligibility ¶ added in v0.16.0

type ProjectAIEligibility struct {
	AIAllowed bool   `json:"aiAllowed"`
	Reason    string `json:"reason,omitempty"`
}

ProjectAIEligibility is a minimal, server-computed projection. Actor membership and sponsor entitlement are proved separately before it is returned; no payer or subscription identifiers leave this package.

type ProjectContactRoleChange ¶ added in v0.12.0

type ProjectContactRoleChange struct {
	Contact          ProjectContactState
	Before, Proposed []string
}

type ProjectContactRoleTargetPort ¶ added in v0.12.0

type ProjectContactRoleTargetPort interface {
	AuthorizeProjectContactRoleChange(context.Context, dal.ReadTransaction, ProjectRoleMutationAuthorization, ProjectContactRoleChange) error
}

Target authority decides eligibility of adds/removals, including deliberate stale-contact cleanup; counting a stale link does not approve assigning one.

type ProjectContactState ¶ added in v0.12.0

type ProjectContactState struct {
	Ref            contract4linkage.RelationshipEntityRef
	Exists, Active bool
	UserID         string
}

ProjectContactState comes from the current full contact record in the supplied transaction, never a cached active-contact brief. Missing/inactive contacts still count while linked. UserID is used for authentication only. Being a Space member is not a requirement for an assigned project contact.

type ProjectOwnerContactPort ¶ added in v0.12.0

type ProjectOwnerContactPort interface {
	ResolveProjectOwnerContact(context.Context, dal.ReadTransaction, SharedProjectCreateBinding) (contract4linkage.RelationshipEntityRef, error)
}

This port resolves an EXISTING contact in the original create transaction. It must independently bind the actor to the verified context, without writes, nested transactions, new contacts or automatic Space membership. The domain rechecks current status/UID and constructs only reciprocal linkage writes.

type ProjectRoleCatalog ¶ added in v0.12.0

type ProjectRoleCatalog struct {
	Version   string
	Roles     []string
	OwnerRole string
}

ProjectRoleCatalog is server configuration. This list approves role IDs only; it grants no operations or authority. The host's current role/permission ports separately authorize the operation. No public request may supply the list.

type ProjectRoleEvidence ¶ added in v0.12.0

type ProjectRoleEvidence struct {
	Contact ProjectContactState
	Roles   []string
}

type ProjectRoleManagerPort ¶ added in v0.12.0

type ProjectRoleManagerPort interface {
	AuthorizeProjectRoleMutation(context.Context, dal.ReadTransaction, ProjectRoleMutationAuthorization) error
}

Manager authority must independently bind ActorID to the authenticated context and authorize with CURRENT project roles and platform guards. Space role alone does not supply a project role. Multiple contacts for one UID are separate evidence: the port must not silently union their privileges.

type ProjectRoleMutationAuthorization ¶ added in v0.12.0

type ProjectRoleMutationAuthorization struct {
	ActorID       string
	Project       models4datatug.SharedProjectRef
	ActorContacts []ProjectRoleEvidence
	Changes       []ProjectContactRoleChange
}

type ProtectedProjectBasisAuthority ¶ added in v0.11.0

type ProtectedProjectBasisAuthority interface {
	VerifyInitialProtectedProjectBasisInTransaction(context.Context, dal.ReadwriteTransaction, string, string, string, string, InitialProtectedProjectBasis) error
}

type PurchaseReadiness ¶ added in v0.5.0

type PurchaseReadiness struct {
	DB       dal.DB
	Owner    PlanEffectOwnerPort
	Personal PersonalPlanOwnerPort
	Config   PlanConfigReader
	Clock    PlanClock
}

PurchaseReadiness verifies the current owner, the last actual Pro plan application, and its effective public plan in one read-only transaction.

func (r PurchaseReadiness) ReadyForPurchase(ctx context.Context, req PurchaseReadinessRequest) (bool, error)

type PurchaseReadinessRequest ¶ added in v0.5.0

type PurchaseReadinessRequest struct {
	BuyerID, Mode, SiteID, Family, AccountID    string
	SubscriptionID, QuoteKey, SessionID, PlanID string
}

PurchaseReadinessRequest contains only server-verified session and quote identity. The host translates the authenticated payment status request.

type QueryActivityContextResponse ¶ added in v0.20.0

type QueryActivityContextResponse struct {
	ContextID    string    `json:"contextID"`
	ExpiresAtUTC time.Time `json:"expiresAtUTC"`
}

type QueryActivityDrainRequest ¶ added in v0.20.0

type QueryActivityDrainRequest struct {
	Limit   int
	AfterID string
}

type QueryActivityDrainResult ¶ added in v0.20.0

type QueryActivityDrainResult struct {
	Scanned     int
	Delivered   int
	Failed      int
	NextAfterID string
	HasMore     bool
}

type QueryActivityReport ¶ added in v0.20.0

type QueryActivityReport struct {
	ContextID   string                           `json:"contextID"`
	OperationID string                           `json:"operationID"`
	Kind        models4datatug.QueryActivityKind `json:"kind"`
}

type QueryActivityReportResult ¶ added in v0.20.0

type QueryActivityReportResult struct {
	Accepted  bool   `json:"accepted"`
	Coalesced bool   `json:"coalesced"`
	ReceiptID string `json:"receiptID,omitempty"`
}

type QueryActivityService ¶ added in v0.20.0

type QueryActivityService struct {
	// contains filtered or unexported fields
}

QueryActivityService is an opt-in server intake and outbox. Its zero value and an unbound instance fail closed; browser attribution remains reported, first-party activity rather than proof of local execution.

func NewQueryActivityService(db dal.DB, binding BusinessActivityBindingReader, ledger contract4paymentus.UsageLedger, corrections contract4paymentus.UsageCorrectionInbox, now func() time.Time) (*QueryActivityService, error)

func (s *QueryActivityService) Deliver(ctx context.Context, spaceID, receiptID string) error

func (s *QueryActivityService) Drain(ctx context.Context, spaceID string, request QueryActivityDrainRequest) (QueryActivityDrainResult, error)

func (s *QueryActivityService) IssueContext(ctx context.Context, actorID, spaceID, projectID string) (QueryActivityContextResponse, error)

func (s *QueryActivityService) Report(ctx context.Context, actorID, spaceID string, report QueryActivityReport) (QueryActivityReportResult, error)

type QueryActivityUsageAuthority ¶ added in v0.20.0

type QueryActivityUsageAuthority struct{}

QueryActivityUsageAuthority proves that Paymentus is admitting or retaining the exact activity backed by DataTug's immutable accepted receipt. It reads through the ledger or inbox caller's transaction; it has no database or mutable authority dependency of its own.

func NewQueryActivityUsageAuthority() QueryActivityUsageAuthority

func (QueryActivityUsageAuthority) VerifyUsage(ctx context.Context, tx dal.ReadTransaction, operation contract4paymentus.UsageOperation) error

type RegisterGithubProjectRequest ¶ added in v0.2.0

type RegisterGithubProjectRequest struct {
	Org    string `json:"org"`
	Repo   string `json:"repo"`
	Folder string `json:"folder"`
	Title  string `json:"title"`
}

RegisterGithubProjectRequest describes a project that already exists in a GitHub repository.

func (v RegisterGithubProjectRequest) Validate() error

type ServiceRefundProof ¶ added in v0.5.0

type ServiceRefundProof struct {
	Known                 bool
	HasPaidServiceInvoice bool
	InvoiceID             string
	ServiceStartUTC       time.Time
	ServiceEndUTC         time.Time
	RefundedInFull        bool
}

ServiceRefundProof describes the current owner's service plan, even when a historical subscription caused this revision. It is never inferred from the account-wide A+C cash snapshot. Unknown and absence are distinct.

type SharedProjectActivationOptions ¶ added in v0.15.0

type SharedProjectActivationOptions struct {
	Activator      contract4spaceus.TransactionalRoleCapabilityActivator
	RequiredRoles  []string
	InventoryQuery dal.QueryExecutor
}

SharedProjectActivationOptions are trusted host composition. The Core activator never runs for passive reads or precommitted reservations.

type SharedProjectBillingIntent ¶ added in v0.21.0

type SharedProjectBillingIntent string

SharedProjectBillingIntent is only a user's plan choice. It grants no access: the service still verifies current Pro or Business authority.

const (
	BillingIntentPersonalPro   SharedProjectBillingIntent = "personal_pro"
	BillingIntentSpaceBusiness SharedProjectBillingIntent = "space_business"
)

func (i SharedProjectBillingIntent) Validate() error

type SharedProjectCreateAuthority ¶ added in v0.10.0

type SharedProjectCreateAuthority interface {
	PrepareSharedProjectCreate(context.Context, SharedProjectCreateBinding) (PreparedSharedProjectCreate, error)
}

SharedProjectCreateAuthority is supplied by the host using released Core Space contracts: existing DataTug capability, current ordinary active Space, and server-configured content-management roles. It must not enable a module. Core reservation labels have a narrower grammar than client command IDs: the adapter must derive a server-owned lowercase command digest (<=64 chars) and purpose/stage labels, not pass arbitrary client CommandID through Core.

type SharedProjectCreateBinding ¶ added in v0.10.0

type SharedProjectCreateBinding struct {
	ActorID, SpaceID, CommandID, RequestDigest string
	// Paid binding is server-resolved. Legacy ownership-only commands leave it empty.
	PayerID, Mode, Product string
}

SharedProjectCreateBinding contains only immutable values. ActorID must come from the verified request context, never an HTTP body. A trusted adapter must independently bind it to that context when preparing Space authority.

type SharedProjectCreateCommand ¶ added in v0.10.0

type SharedProjectCreateCommand struct {
	ActorID, SpaceID, CommandID, Title string
	BillingIntent                      SharedProjectBillingIntent
}

func (c SharedProjectCreateCommand) Validate() error

type SharedProjectCreateTransactionAuthority ¶ added in v0.10.0

type SharedProjectCreateTransactionAuthority interface {
	// ValidateSharedProjectCreateInTransaction must re-read current Space,
	// membership/role, enabled module and durable reservation evidence in this
	// exact transaction on EVERY invocation, including command replay. It may
	// only read: no nested transaction, writes, provider call or clock read.
	ValidateSharedProjectCreateInTransaction(context.Context, dal.ReadwriteTransaction, SharedProjectCreateBinding, time.Time) error
}

type SharedProjectService ¶ added in v0.10.0

type SharedProjectService struct {
	// contains filtered or unexported fields
}

SharedProjectService is deliberately separate from the private-project Facade, so existing callers do not acquire shared creation implicitly.

func NewActivatingBusinessSharedProjectService(
	db dal.DB,
	ids IDGenerator,
	now func() time.Time,
	options BusinessSharedProjectOptions,
	activation SharedProjectActivationOptions,
) (*SharedProjectService, error)

func NewActivatingPaidSharedProjectService(
	db dal.DB,
	ids IDGenerator,
	now func() time.Time,
	paid PaidSharedProjectOptions,
	activation SharedProjectActivationOptions,
) (*SharedProjectService, error)

func NewActivatingProBusinessSharedProjectService(db dal.DB, ids IDGenerator, now func() time.Time, options ProBusinessSharedProjectOptions, activationOptions SharedProjectActivationOptions) (*SharedProjectService, error)

func NewBusinessSharedProjectService(
	db dal.DB,
	ids IDGenerator,
	authority SharedProjectCreateAuthority,
	now func() time.Time,
	options BusinessSharedProjectOptions,
) (*SharedProjectService, error)

func NewPaidSharedProjectService(db dal.DB, ids IDGenerator, authority SharedProjectCreateAuthority, now func() time.Time, options PaidSharedProjectOptions) (*SharedProjectService, error)

func NewProBusinessSharedProjectService(db dal.DB, ids IDGenerator, authority SharedProjectCreateAuthority, now func() time.Time, options ProBusinessSharedProjectOptions) (*SharedProjectService, error)

func NewSharedProjectService(db dal.DB, ids IDGenerator, authority SharedProjectCreateAuthority, now func() time.Time) (*SharedProjectService, error)

func (s *SharedProjectService) AuthorizeGitHubProjectWrite(ctx context.Context, actorID string, repositoryID int64, owner, name, folder string) (GitHubProjectAccess, error)

func (s *SharedProjectService) Create(ctx context.Context, command SharedProjectCreateCommand) (models4datatug.SharedProjectRef, error)

func (s *SharedProjectService) CreateGitHubProject(ctx context.Context, command GitHubProjectCreateCommand, repo GitHubCreateRepository) (GitHubProjectCreateResult, error)

func (s *SharedProjectService) EnsureProtectedProjectQuotaForCreate(ctx facade.ContextWithUser, binding SharedProjectCreateBinding) error

func (s *SharedProjectService) PlanExplicitProjectCreateActivationInTransaction(
	ctx facade.ContextWithUser,
	tx dal.ReadwriteTransaction,
	binding SharedProjectCreateBinding,
	observedAt time.Time,
) (contract4spaceus.PreparedRoleCapabilityActivation, error)

func (s *SharedProjectService) ReadGitHubProjectAIEligibility(ctx context.Context, actorID string, repositoryID int64, owner, name, folder string) (ProjectAIEligibility, error)

func (s *SharedProjectService) ReadSharedProjectAIEligibility(ctx context.Context, actorID, spaceID, projectID string) (ProjectAIEligibility, error)

func (s *SharedProjectService) ResolveGitHubProject(ctx context.Context, actorID string, repositoryID int64, owner, name, folder string) (GitHubProjectAccess, error)

func (s *SharedProjectService) SaveGitHubQuery(ctx context.Context, actorID string, repositoryID int64, owner, name, folder string, request dto.SaveQueryRequest, repo GitHubQueryRepository) (*dto.SaveQueryResponse, error)

type SpaceServiceAccess ¶ added in v0.19.0

type SpaceServiceAccess struct {
	Mode, ServiceID, PayerSpaceID, OwnerFamily, AccountKind, ProductID, PlanID string
	OwnerSubscriptionID, PaidServiceProofID, GrantVersion                      string
	OwnerGeneration, OwnerRevision                                             int64
	PaidUntilUTC                                                               time.Time
	State                                                                      string // active or ended, after complete source reconciliation
	UnlimitedProjects, UnlimitedContacts                                       bool
	// contains filtered or unexported fields
}

SpaceServiceAccess is the product-authorized current service projection. It is derived from Paymentus' read-only financial projection plus this versioned DataTug entitlement policy. The client cannot supply any field.

type UsageReader ¶ added in v0.4.0

type UsageReader interface {
	ReadUsage(context.Context, string, string) (*models4datatug.AIUsageRecord, error)
}

UsageReader reads the requested UTC month; nil means no count document.