@happyvertical/smrt-affiliates 0.30.0

package/AGENTS.md

@@ -0,0 +1,62 @@
+# @happyvertical/smrt-affiliates
+
+Partner revenue sharing with multi-type partners, multi-tier commissions, and payout processing.
+
+## Models
+
+- **Partner**: `partnerTypes` JSON array (publisher/salesperson/referrer — multi-role). `parentPartnerId` for site-attached salespeople. `referredById` for referral attribution. `commissionRate`, `parentCommissionShare`.
+- **Commission**: 4 types per ad event — Display (publisher), Referral (referrer), Sales (salesperson), Parent (parent publisher's share). **Immutable** — no update/delete API.
+- **Payout**: batch aggregation. Status: `PENDING → APPROVED → PROCESSING → COMPLETED` (or FAILED).
+
+## Currency
+
+**All monetary fields are integer cents.** Helpers: `getTotalInDollars()`, `getAmountInDollars()`. `Commission.calculateAmount(grossRevenue, rate)` uses `Math.round()`.
+
+## Parent Commission Share
+
+```
+Salesperson.parentCommissionShare = 0.20 (20% to parent publisher)
+Effective sales rate = salesRate × (1 - parentCommissionShare)
+```
+
+## Cross-Package References (plain strings)
+
+`profileId` → smrt-profiles, `propertyId` → smrt-properties, `eventId` → smrt-ads, `invoiceId` → smrt-commerce
+
+## Tenancy
+
+Per `docs/content/standards.md §7`, tenant-aware models normally apply
+`@TenantScoped({ mode: 'optional' })` from `@happyvertical/smrt-tenancy`. The
+three models in this package deviate intentionally; each `@smrt(...)` block
+carries an inline comment pointing back to this section.
+
+`Partner`, `Commission`, and `Payout` are deliberately **NOT** tenant-scoped.
+The affiliate network is a cross-tenant graph by design:
+
+- A single `Partner` (e.g. a publisher operating multiple sites across
+  different tenants) needs a stable identity for revenue aggregation,
+  payout thresholds, and tax reporting. Slicing partner identity per
+  tenant would either duplicate the row or hide payouts owed across
+  tenants.
+- `Commission` rows attribute revenue to a partner across whichever tenant
+  generated the ad event; the cross-tenant attribution is the point of the
+  network.
+- `Payout` aggregates commissions for a partner regardless of which tenant
+  the underlying revenue came from. A tenant-scoped query would produce
+  systematically incorrect totals.
+
+This is the same reasoning that keeps `TenantKey` in `packages/secrets`
+out of the tenancy interceptor: rows that must be queried across tenants
+to fulfil their purpose should not be silently filtered.
+
+Operators that need tenant-attributed reporting should aggregate by
+joining `Commission` rows back to `eventId` (smrt-ads) and the originating
+ad's tenant — not by adding `@TenantScoped` here.
+
+## Gotchas
+
+- **No tenancy** (intentional): cross-tenant network visibility for affiliate tracking — see Tenancy section above for rationale
+- **partnerTypes is JSON string**: must parse with `getPartnerTypes()` helper
+- **Commission rate copied at event time**: immutable record, not a live reference to Partner.commissionRate
+- **Payout amounts in cents**: divide by 100 for display
+- **No ledger integration**: Payout → Invoice mapping is external

package/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright <2025> <Happy Vertical Corporation>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,118 @@
+# @happyvertical/smrt-affiliates
+
+Affiliate partner and commission tracking models for the SMRT framework. Manages multi-type partners (publisher/salesperson/referrer), multi-tier commission attribution, and payout batch processing.
+
+## Installation
+
+```bash
+pnpm add @happyvertical/smrt-affiliates
+```
+
+## Usage
+
+```typescript
+import {
+  Partner, PartnerCollection,
+  Commission, CommissionCollection,
+  Payout, PayoutCollection,
+  PartnerType, CommissionType, CommissionStatus, PayoutStatus
+} from '@happyvertical/smrt-affiliates';
+
+// Register a publisher partner (earns display commissions)
+const partners = new PartnerCollection(db);
+const publisher = await partners.create({
+  profileId: 'profile-uuid',
+  propertyId: 'property-uuid',
+  partnerTypes: JSON.stringify([PartnerType.PUBLISHER]),
+  displayCommissionRate: 0.50,
+  status: 'active',
+});
+
+// Attach a salesperson to the publisher
+// parentCommissionShare: 20% of sales commission goes to parent publisher
+const salesperson = await partners.create({
+  profileId: 'sales-profile-uuid',
+  parentPartnerId: publisher.id,
+  partnerTypes: JSON.stringify([PartnerType.SALESPERSON]),
+  salesCommissionRate: 0.10,
+  parentCommissionShare: 0.20,
+  status: 'active',
+});
+// Effective sales rate: 0.10 * (1 - 0.20) = 0.08
+salesperson.getEffectiveSalesRate(); // 0.08
+
+// Record a commission (all monetary values in integer cents)
+const commissions = new CommissionCollection(db);
+await commissions.create({
+  eventId: 'adevent-uuid',
+  partnerId: publisher.id,
+  commissionType: CommissionType.DISPLAY,
+  grossRevenue: 1000,       // $10.00
+  commissionRate: 0.50,
+  commissionAmount: Commission.calculateAmount(1000, 0.50), // 500 cents
+  currency: 'CAD',
+  status: CommissionStatus.PENDING,
+});
+
+// Create a payout batch for the publisher
+const payouts = new PayoutCollection(db);
+const payout = await payouts.create({
+  partnerId: publisher.id,
+  periodStart: new Date('2024-01-01'),
+  periodEnd: new Date('2024-01-31'),
+  displayEarnings: 25000,   // $250.00
+  referralEarnings: 500,    // $5.00
+  salesEarnings: 0,
+  parentEarnings: 0,
+  totalAmount: 25500,       // $255.00
+  currency: 'CAD',
+  status: PayoutStatus.PENDING,
+});
+
+// Payout lifecycle: PENDING -> APPROVED -> PROCESSING -> COMPLETED (or FAILED)
+payout.approve();
+payout.markProcessing();
+payout.complete('transfer-ref-123');
+await payout.save();
+```
+
+### Commission Types
+
+Each ad event can generate up to four commissions:
+
+| Type | Recipient | Description |
+|------|-----------|-------------|
+| `DISPLAY` | Publisher | Site owner earns share of impression revenue |
+| `REFERRAL` | Referrer | Partner who referred the publisher |
+| `SALES` | Salesperson | Partner who brought in the advertiser |
+| `PARENT` | Parent publisher | Share of salesperson's commission |
+
+## API
+
+### Models
+
+| Export | Description |
+|--------|------------|
+| `Partner` | Affiliate partner with multi-type roles, commission rates, payout threshold, and parent hierarchy |
+| `Commission` | Immutable revenue attribution record (no delete). `calculateAmount(grossRevenue, rate)` static helper |
+| `Payout` | Aggregated payment batch with status lifecycle and per-type earnings breakdown |
+
+### Collections
+
+`PartnerCollection`, `CommissionCollection`, `PayoutCollection`
+
+### Enums
+
+| Export | Values |
+|--------|--------|
+| `PartnerType` | `publisher`, `salesperson`, `referrer` |
+| `PartnerStatus` | `pending`, `active`, `suspended` |
+| `CommissionType` | `display`, `referral`, `sales`, `parent` |
+| `CommissionStatus` | `pending`, `included`, `paid` |
+| `PayoutStatus` | `pending`, `approved`, `processing`, `completed`, `failed` |
+| `PayoutMethod` | `bank_transfer`, `check`, `paypal`, `credit` |
+
+## Dependencies
+
+- `@happyvertical/smrt-core` -- ORM and code generation
+- Peer: `@happyvertical/smrt-ads`, `@happyvertical/smrt-commerce`, `@happyvertical/smrt-profiles`, `@happyvertical/smrt-properties`