@btst/plugin-affiliate 0.0.0-stage → 1.0.0-beta.0

package/dist/types.d.mts

@@ -0,0 +1,176 @@
+/** Application review and referral eligibility state. */
+type AffiliateStatus = "pending" | "approved" | "suspended";
+/** Percentage points or a fixed amount in currency minor units. */
+type CommissionType = "percent" | "flat";
+/** Review and settlement state; payouts alone move commissions to paid. */
+type CommissionStatus = "pending" | "approved" | "paid" | "voided";
+/** Manual payment outcome; failed batches release their reserved commissions. */
+type PayoutStatus = "pending" | "sent" | "failed";
+/** Partner profile with ISO timestamp strings and optional administrative notes. */
+interface Affiliate {
+    id: string;
+    /** Authenticated account that exclusively owns this profile's portal. */
+    userId: string;
+    name: string;
+    email: string;
+    code: string;
+    status: AffiliateStatus;
+    /** Payment instructions stored as text, without processor-specific validation. */
+    payoutDetails?: string | null;
+    /** Administrative notes, omitted from portal responses. */
+    notes?: string | null;
+    commissionType?: CommissionType | null;
+    commissionValue?: number | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Recorded visit; its stored ISO timestamp determines cookie attribution eligibility. */
+interface ReferralClick {
+    id: string;
+    affiliateId: string;
+    code: string;
+    landingPath?: string | null;
+    referrer?: string | null;
+    /** Optional hash supplied by a trusted integration; HTTP tracking does not collect IPs. */
+    ipHash?: string | null;
+    userAgent?: string | null;
+    createdAt: string;
+}
+/** Attributed order/event with a safe integer amount in currency minor units. */
+interface Conversion {
+    id: string;
+    affiliateId: string;
+    clickId?: string | null;
+    /** Stable order/event identifier used to deduplicate conversion retries. */
+    externalRef?: string | null;
+    amount: number;
+    currency: string;
+    status: "pending" | "approved" | "rejected";
+    createdAt: string;
+}
+/** Earnings from one conversion, expressed in currency minor units with ISO timestamps. */
+interface Commission {
+    id: string;
+    affiliateId: string;
+    conversionId: string;
+    /** Pending or settled payout reservation; empty when available for a new batch. */
+    payoutId?: string | null;
+    amount: number;
+    currency: string;
+    status: CommissionStatus;
+    createdAt: string;
+    updatedAt: string;
+}
+/** One affiliate's manual payment batch in one currency; dates are ISO strings. */
+interface Payout {
+    id: string;
+    affiliateId: string;
+    amount: number;
+    currency: string;
+    status: PayoutStatus;
+    reference?: string | null;
+    paidAt?: string | null;
+    createdAt: string;
+}
+/** Offset pagination and filters for affiliate administration lists. */
+interface ListParams {
+    limit?: number;
+    offset?: number;
+    affiliateId?: string;
+    status?: string;
+    currency?: string;
+}
+/** A page of records and the total count before pagination. */
+interface ListResult<T> {
+    items: T[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+/** Referral counts and commission minor-unit totals, grouped separately per currency. */
+interface AffiliateStats {
+    clicks: number;
+    conversions: number;
+    totals: {
+        currency: string;
+        pending: number;
+        approved: number;
+        paid: number;
+        voided: number;
+    }[];
+}
+/** HTTP(S) landing-page template and optional banner link shown to partners. */
+interface MarketingAsset {
+    name: string;
+    url: string;
+    description?: string;
+    bannerUrl?: string;
+}
+/** One account's profile, totals, recent financial history, and program marketing assets. */
+interface AffiliatePortal {
+    affiliate: Affiliate | null;
+    stats: AffiliateStats;
+    commissions: Commission[];
+    payouts: Payout[];
+    assets: MarketingAsset[];
+}
+/** Pending-profile input; administrators supply ownership, applications use request identity. */
+interface CreateAffiliateInput {
+    userId: string;
+    name: string;
+    email: string;
+    code?: string;
+    payoutDetails?: string;
+}
+/** Administrative profile edits; commission override type and value must be set or cleared together. */
+interface UpdateAffiliateInput {
+    name?: string;
+    email?: string;
+    code?: string;
+    status?: AffiliateStatus;
+    payoutDetails?: string | null;
+    notes?: string | null;
+    commissionType?: CommissionType | null;
+    commissionValue?: number | null;
+}
+/** A referral visit and optional metadata supplied by the tracking transport or trusted caller. */
+interface TrackClickInput {
+    code: string;
+    landingPath?: string;
+    referrer?: string;
+    ipHash?: string;
+    userAgent?: string;
+}
+/** Verified order/event amount and attribution; omitted attribution returns null without a request fallback. */
+interface CreateConversionInput {
+    externalRef?: string;
+    amount: number;
+    currency?: string;
+    attribution?: {
+        code?: string;
+        clickId?: string;
+    };
+}
+/** Reserve selected or all available approved commissions for one affiliate and currency. */
+interface CreatePayoutInput {
+    affiliateId: string;
+    currency: string;
+    commissionIds?: string[];
+}
+/** Attribution window, default commission rule, and optional partner marketing assets. */
+interface AffiliateOptions {
+    /** Trusted HTTP(S) site origin for tracking redirects when the API uses a separate origin. */
+    siteOrigin?: string;
+    /** Number of days a stored referral click remains eligible. Defaults to 30. */
+    attributionWindowDays?: number;
+    /** Whether a new tracked referral replaces the existing cookie. Defaults to last_touch. */
+    attributionMode?: "first_touch" | "last_touch";
+    /** Default commission rule, unless the affiliate has an override. Defaults to percent. */
+    defaultCommissionType?: CommissionType;
+    /** Percentage (up to two decimals) or integer minor units for flat rules. Defaults to 20. */
+    defaultCommissionValue?: number;
+    /** Optional landing page templates and banner metadata displayed in the portal. */
+    marketingAssets?: MarketingAsset[];
+}
+
+export type { Affiliate, AffiliateOptions, AffiliatePortal, AffiliateStats, AffiliateStatus, Commission, CommissionStatus, CommissionType, Conversion, CreateAffiliateInput, CreateConversionInput, CreatePayoutInput, ListParams, ListResult, MarketingAsset, Payout, PayoutStatus, ReferralClick, TrackClickInput, UpdateAffiliateInput };

package/dist/types.d.ts

@@ -0,0 +1,176 @@
+/** Application review and referral eligibility state. */
+type AffiliateStatus = "pending" | "approved" | "suspended";
+/** Percentage points or a fixed amount in currency minor units. */
+type CommissionType = "percent" | "flat";
+/** Review and settlement state; payouts alone move commissions to paid. */
+type CommissionStatus = "pending" | "approved" | "paid" | "voided";
+/** Manual payment outcome; failed batches release their reserved commissions. */
+type PayoutStatus = "pending" | "sent" | "failed";
+/** Partner profile with ISO timestamp strings and optional administrative notes. */
+interface Affiliate {
+    id: string;
+    /** Authenticated account that exclusively owns this profile's portal. */
+    userId: string;
+    name: string;
+    email: string;
+    code: string;
+    status: AffiliateStatus;
+    /** Payment instructions stored as text, without processor-specific validation. */
+    payoutDetails?: string | null;
+    /** Administrative notes, omitted from portal responses. */
+    notes?: string | null;
+    commissionType?: CommissionType | null;
+    commissionValue?: number | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Recorded visit; its stored ISO timestamp determines cookie attribution eligibility. */
+interface ReferralClick {
+    id: string;
+    affiliateId: string;
+    code: string;
+    landingPath?: string | null;
+    referrer?: string | null;
+    /** Optional hash supplied by a trusted integration; HTTP tracking does not collect IPs. */
+    ipHash?: string | null;
+    userAgent?: string | null;
+    createdAt: string;
+}
+/** Attributed order/event with a safe integer amount in currency minor units. */
+interface Conversion {
+    id: string;
+    affiliateId: string;
+    clickId?: string | null;
+    /** Stable order/event identifier used to deduplicate conversion retries. */
+    externalRef?: string | null;
+    amount: number;
+    currency: string;
+    status: "pending" | "approved" | "rejected";
+    createdAt: string;
+}
+/** Earnings from one conversion, expressed in currency minor units with ISO timestamps. */
+interface Commission {
+    id: string;
+    affiliateId: string;
+    conversionId: string;
+    /** Pending or settled payout reservation; empty when available for a new batch. */
+    payoutId?: string | null;
+    amount: number;
+    currency: string;
+    status: CommissionStatus;
+    createdAt: string;
+    updatedAt: string;
+}
+/** One affiliate's manual payment batch in one currency; dates are ISO strings. */
+interface Payout {
+    id: string;
+    affiliateId: string;
+    amount: number;
+    currency: string;
+    status: PayoutStatus;
+    reference?: string | null;
+    paidAt?: string | null;
+    createdAt: string;
+}
+/** Offset pagination and filters for affiliate administration lists. */
+interface ListParams {
+    limit?: number;
+    offset?: number;
+    affiliateId?: string;
+    status?: string;
+    currency?: string;
+}
+/** A page of records and the total count before pagination. */
+interface ListResult<T> {
+    items: T[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+/** Referral counts and commission minor-unit totals, grouped separately per currency. */
+interface AffiliateStats {
+    clicks: number;
+    conversions: number;
+    totals: {
+        currency: string;
+        pending: number;
+        approved: number;
+        paid: number;
+        voided: number;
+    }[];
+}
+/** HTTP(S) landing-page template and optional banner link shown to partners. */
+interface MarketingAsset {
+    name: string;
+    url: string;
+    description?: string;
+    bannerUrl?: string;
+}
+/** One account's profile, totals, recent financial history, and program marketing assets. */
+interface AffiliatePortal {
+    affiliate: Affiliate | null;
+    stats: AffiliateStats;
+    commissions: Commission[];
+    payouts: Payout[];
+    assets: MarketingAsset[];
+}
+/** Pending-profile input; administrators supply ownership, applications use request identity. */
+interface CreateAffiliateInput {
+    userId: string;
+    name: string;
+    email: string;
+    code?: string;
+    payoutDetails?: string;
+}
+/** Administrative profile edits; commission override type and value must be set or cleared together. */
+interface UpdateAffiliateInput {
+    name?: string;
+    email?: string;
+    code?: string;
+    status?: AffiliateStatus;
+    payoutDetails?: string | null;
+    notes?: string | null;
+    commissionType?: CommissionType | null;
+    commissionValue?: number | null;
+}
+/** A referral visit and optional metadata supplied by the tracking transport or trusted caller. */
+interface TrackClickInput {
+    code: string;
+    landingPath?: string;
+    referrer?: string;
+    ipHash?: string;
+    userAgent?: string;
+}
+/** Verified order/event amount and attribution; omitted attribution returns null without a request fallback. */
+interface CreateConversionInput {
+    externalRef?: string;
+    amount: number;
+    currency?: string;
+    attribution?: {
+        code?: string;
+        clickId?: string;
+    };
+}
+/** Reserve selected or all available approved commissions for one affiliate and currency. */
+interface CreatePayoutInput {
+    affiliateId: string;
+    currency: string;
+    commissionIds?: string[];
+}
+/** Attribution window, default commission rule, and optional partner marketing assets. */
+interface AffiliateOptions {
+    /** Trusted HTTP(S) site origin for tracking redirects when the API uses a separate origin. */
+    siteOrigin?: string;
+    /** Number of days a stored referral click remains eligible. Defaults to 30. */
+    attributionWindowDays?: number;
+    /** Whether a new tracked referral replaces the existing cookie. Defaults to last_touch. */
+    attributionMode?: "first_touch" | "last_touch";
+    /** Default commission rule, unless the affiliate has an override. Defaults to percent. */
+    defaultCommissionType?: CommissionType;
+    /** Percentage (up to two decimals) or integer minor units for flat rules. Defaults to 20. */
+    defaultCommissionValue?: number;
+    /** Optional landing page templates and banner metadata displayed in the portal. */
+    marketingAssets?: MarketingAsset[];
+}
+
+export type { Affiliate, AffiliateOptions, AffiliatePortal, AffiliateStats, AffiliateStatus, Commission, CommissionStatus, CommissionType, Conversion, CreateAffiliateInput, CreateConversionInput, CreatePayoutInput, ListParams, ListResult, MarketingAsset, Payout, PayoutStatus, ReferralClick, TrackClickInput, UpdateAffiliateInput };

package/dist/types.mjs

@@ -0,0 +1 @@
+

package/package.json

@@ -1,6 +1,162 @@
 {
   "name": "@btst/plugin-affiliate",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0-beta.0",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/better-stack-ai/better-stack.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "description": "Affiliate plugin for the BTST core runtime.",
+  "exports": {
+    "./api": {
+      "import": {
+        "types": "./dist/api/index.d.ts",
+        "default": "./dist/api/index.mjs"
+      },
+      "require": {
+        "types": "./dist/api/index.d.cts",
+        "default": "./dist/api/index.cjs"
+      }
+    },
+    "./client": {
+      "import": {
+        "types": "./dist/client/index.d.ts",
+        "default": "./dist/client/index.mjs"
+      },
+      "require": {
+        "types": "./dist/client/index.d.cts",
+        "default": "./dist/client/index.cjs"
+      }
+    },
+    "./client/hooks": {
+      "import": {
+        "types": "./dist/client/hooks/index.d.ts",
+        "default": "./dist/client/hooks/index.mjs"
+      },
+      "require": {
+        "types": "./dist/client/hooks/index.d.cts",
+        "default": "./dist/client/hooks/index.cjs"
+      }
+    },
+    "./client/components": {
+      "import": {
+        "types": "./dist/client/components/index.d.ts",
+        "default": "./dist/client/components/index.mjs"
+      },
+      "require": {
+        "types": "./dist/client/components/index.d.cts",
+        "default": "./dist/client/components/index.cjs"
+      }
+    },
+    "./query-keys": {
+      "import": {
+        "types": "./dist/query-keys.d.ts",
+        "default": "./dist/query-keys.mjs"
+      },
+      "require": {
+        "types": "./dist/query-keys.d.cts",
+        "default": "./dist/query-keys.cjs"
+      }
+    },
+    "./permissions": {
+      "import": {
+        "types": "./dist/permissions.d.ts",
+        "default": "./dist/permissions.mjs"
+      },
+      "require": {
+        "types": "./dist/permissions.d.cts",
+        "default": "./dist/permissions.cjs"
+      }
+    },
+    "./attribution": {
+      "import": {
+        "types": "./dist/attribution.d.ts",
+        "default": "./dist/attribution.mjs"
+      },
+      "require": {
+        "types": "./dist/attribution.d.cts",
+        "default": "./dist/attribution.cjs"
+      }
+    },
+    "./types": {
+      "import": {
+        "types": "./dist/types.d.ts",
+        "default": "./dist/types.mjs"
+      },
+      "require": {
+        "types": "./dist/types.d.cts",
+        "default": "./dist/types.cjs"
+      }
+    },
+    "./css": "./dist/style.css"
+  },
+  "typesVersions": {
+    "*": {
+      "api": [
+        "./dist/api/index.d.ts"
+      ],
+      "client": [
+        "./dist/client/index.d.ts"
+      ],
+      "client/hooks": [
+        "./dist/client/hooks/index.d.ts"
+      ],
+      "client/components": [
+        "./dist/client/components/index.d.ts"
+      ],
+      "query-keys": [
+        "./dist/query-keys.d.ts"
+      ],
+      "permissions": [
+        "./dist/permissions.d.ts"
+      ],
+      "attribution": [
+        "./dist/attribution.d.ts"
+      ],
+      "types": [
+        "./dist/types.d.ts"
+      ]
+    }
+  },
+  "dependencies": {
+    "@btst/db": "3.0.1",
+    "better-call": "1.4.4",
+    "zod": "^4.2.1"
+  },
+  "peerDependencies": {
+    "@btst/stack": ">=6.0.0-beta.0 <7.0.0",
+    "@btst/yar": ">=1.3.2",
+    "@tanstack/react-query": "^5.0.0",
+    "react": ">=19.2.6",
+    "react-dom": ">=19.2.6"
+  },
+  "devDependencies": {
+    "@btst/yar": "1.3.2",
+    "@tanstack/react-query": "5.105.0",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1",
+    "typescript": "^5.6.3",
+    "unbuild": "3.6.1",
+    "vitest": "^4.1.12",
+    "@btst/adapter-memory": "3.0.1",
+    "@btst/stack": "6.0.0-beta.0"
+  },
+  "gitHead": "ac7a6206d81e36262baf4392255575b4dc9bf6b5",
+  "scripts": {
+    "build": "unbuild --clean",
+    "typecheck": "tsc --project tsconfig.json",
+    "test": "vitest run"
+  }
 }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.