@etohq/types 1.5.1-alpha.3 → 1.5.1-alpha.5

package/dist/ambassador/common.d.ts

@@ -0,0 +1,699 @@
+import { BaseFilterable, OperatorMap } from "../dal";
+import { ActionType, AuthorityType, ContextType, RevenueRelationshipType, SourceType } from "./revenue-sharing";
+/**
+ * Ambassador source types
+ */
+export type AmbassadorSourceType = "user" | "community";
+/**
+ * Ambassador status types
+ */
+export type AmbassadorStatus = "default" | "verified" | "featured";
+/**
+ * Ambassador profile types
+ */
+export type AmbassadorProfileType = "individual" | "business";
+/**
+ * Program status types
+ */
+export type ProgramStatus = "active" | "inactive" | "suspended";
+/**
+ * Commission types - Enhanced for native revenue sharing
+ */
+export type CommissionType = "click" | "lead" | "sale" | "custom" | "revenue_share" | "community_bonus";
+/**
+ * Revenue sharing context - Makes revenue sharing conditions explicit
+ */
+export type RevenueShareContext = {
+    source_type: "direct" | "community" | "repost";
+    community_id?: string;
+    creator_id?: string;
+    share_percentage?: number;
+    sharing_rules?: {
+        ambassador_share: number;
+        creator_share: number;
+        community_share?: number;
+    };
+};
+/**
+ * Commission status types
+ */
+export type CommissionStatus = "pending" | "confirmed" | "processed" | "paid" | "refunded" | "duplicate" | "fraud" | "canceled";
+/**
+ * Enrollment status types
+ */
+export type ProgramEnrollmentStatus = "pending" | "approved" | "rejected" | "invited" | "declined" | "banned" | "archived";
+/**
+ * Banned reason types (Dub parity)
+ */
+export type BannedReasonType = "tos_violation" | "inappropriate_content" | "fake_traffic" | "fraud" | "spam" | "brand_abuse";
+/**
+ * Reward event types
+ */
+export type RewardEventType = "click" | "lead" | "sale" | "access_grant";
+/**
+ * Reward structure types
+ */
+export type RewardStructureType = "percentage" | "flat";
+/**
+ * Ambassador DTO
+ */
+export interface AmbassadorDTO {
+    id: string;
+    source_type: AmbassadorSourceType;
+    source_id: string;
+    name: string;
+    email: string | null;
+    profile_type: AmbassadorProfileType;
+    company_name: string | null;
+    status: AmbassadorStatus;
+    description: string | null;
+    total_earnings: number | null;
+    country: string | null;
+    image: string | null;
+    website: string | null;
+    website_txt_record: string | null;
+    website_verified_at: Date | null;
+    youtube: string | null;
+    youtube_channel_id: string | null;
+    youtube_verified_at: Date | null;
+    youtube_subscriber_count: number;
+    youtube_video_count: number;
+    youtube_view_count: number;
+    twitter: string | null;
+    twitter_verified_at: Date | null;
+    linkedin: string | null;
+    linkedin_verified_at: Date | null;
+    instagram: string | null;
+    instagram_verified_at: Date | null;
+    tiktok: string | null;
+    paypal_email: string | null;
+    stripe_connect_id: string | null;
+    min_withdrawal_amount: number;
+    payouts_enabled_at: Date | null;
+    connect_payouts_last_reminded_at: Date | null;
+    invoice_settings: Record<string, unknown> | null;
+    metadata: Record<string, unknown> | null;
+    created_at: Date;
+    updated_at: Date;
+}
+/**
+ * Reward DTO
+ */
+export interface RewardDTO {
+    /**
+     * The unique identifier for the reward.
+     */
+    id: string;
+    /**
+     * The associated program's ID for this reward.
+     */
+    program_id: string;
+    /**
+     * The event that triggers this reward (e.g., click, lead, sale).
+     */
+    event: RewardEventType;
+    /**
+     * The reward's structural type (e.g., fixed, percentage).
+     */
+    type: RewardStructureType;
+    /**
+     * The reward amount (could be a number or percent depending on structure).
+     */
+    amount: number;
+    /**
+     * The maximum allowed duration (if applicable) for the reward. Null if not set.
+     */
+    max_duration: number | null;
+    /**
+     * The maximum allowed amount for the reward. Null if not set.
+     */
+    max_amount: number | null;
+    /**
+     * Optional record for any additional modifiers for the reward.
+     * Null if not present.
+     */
+    modifiers: Record<string, unknown> | null;
+    /**
+     * Optional human-readable description for the reward. Null if not present.
+     */
+    description: string | null;
+    /**
+     * Timestamp when this reward was created.
+     */
+    created_at: Date;
+    /**
+     * Timestamp when this reward was last updated.
+     */
+    updated_at: Date;
+}
+/**
+ * Program DTO
+ *
+ * Includes all current program fields. All optional fields use `null`
+ * instead of being omitted or using `?`.
+ * Updated: Now contains additional Dub and platform discovery fields.
+ */
+export interface ProgramDTO {
+    /**
+     * Unique identifier of the program.
+     */
+    id: string;
+    /**
+     * Owner's unique ID.
+     */
+    owner_id: string;
+    /**
+     * The type of owner (e.g., user, brand, organization).
+     */
+    owner_type: string;
+    /**
+     * Program name.
+     */
+    name: string;
+    /**
+     * Program slug (unique string used in URLs).
+     */
+    slug: string;
+    /**
+     * Program description (null if not provided).
+     */
+    description: string | null;
+    /**
+     * Logo URL or null.
+     */
+    logo: string | null;
+    /**
+     * Brand color hex (null if not provided).
+     */
+    brand_color: string | null;
+    /**
+     * Domain associated with the program (null if not provided).
+     */
+    domain: string | null;
+    /**
+     * Public site URL for the program (null if not provided).
+     */
+    url: string | null;
+    /**
+     * Wordmark image or null.
+     */
+    wordmark: string | null;
+    /**
+     * Primary/category of the program (for discovery/search).
+     */
+    primary_category: string | null;
+    /**
+     * Commission type (either percentage or fixed).
+     */
+    commission_type: "percentage" | "fixed";
+    /**
+     * Commission rate (as percent or fixed value).
+     */
+    commission_rate: number;
+    /**
+     * Cookie length in days for tracking. (Attribution window)
+     */
+    cookie_length: number;
+    /**
+     * Number of days held before payout eligibility.
+     */
+    holding_period_days: number;
+    /**
+     * Minimum payout amount (base units, e.g., cents).
+     */
+    min_payout_amount: number;
+    /**
+     * Whether ambassadors are auto-approved (true or false).
+     */
+    auto_approve_ambassadors: boolean;
+    /**
+     * Timestamp when auto-approve was enabled (null if not set).
+     */
+    auto_approve_ambassadors_enabled_at: Date | null;
+    /**
+     * Maximum number of links allowed per ambassador.
+     */
+    max_ambassador_links: number;
+    /**
+     * URL validation mode.
+     */
+    url_validation_mode: "domain" | "exact";
+    /**
+     * Link structure pattern for access/ambassador links.
+     */
+    link_structure: "short" | "query" | "path";
+    /**
+     * Custom parameter for link construction (null if not used).
+     */
+    link_parameter: string | null;
+    /**
+     * Minimum age for ambassadors (null if no requirement).
+     */
+    age_verification: number | null;
+    /**
+     * Default folder ID for ambassadors (null if not set).
+     */
+    default_folder_id: string | null;
+    /**
+     * Default group ID for ambassadors (null if not set).
+     */
+    default_group_id: string | null;
+    /**
+     * Optional timestamp for published program landing page.
+     */
+    lander_published_at: Date | null;
+    /**
+     * Category for program discovery/marketplace (null if not set).
+     */
+    category: string | null;
+    /**
+     * List of tags or keywords (null if not set).
+     */
+    tags: string[] | null;
+    /**
+     * Target audience or audience description (null if not set).
+     */
+    target_audience: string | null;
+    /**
+     * Commission summary (human-readable, null if not set).
+     */
+    commission_summary: string | null;
+    /**
+     * Array of main program benefits (null if not set).
+     */
+    program_benefits: Record<string, unknown> | null;
+    /**
+     * Array of requirements for ambassadors (null if not set).
+     */
+    requirements: Record<string, unknown> | null;
+    /**
+     * Linked campaign ID (null if not integrated).
+     */
+    campaign_id: string | null;
+    /**
+     * List of active promotion IDs from campaign (null if none).
+     */
+    active_promotion_ids: string[] | null;
+    /**
+     * Whether promotion integration is enabled.
+     */
+    promotion_integration_enabled: boolean;
+    /**
+     * Array of all discounts (null if not present).
+     */
+    discounts: Record<string, unknown> | null;
+    /**
+     * List of all rewards for the program (null if no rewards).
+     */
+    rewards: RewardDTO[] | null;
+    /**
+     * Whether program discounting is enabled.
+     */
+    discount_enabled: boolean;
+    /**
+     * Discount type (percentage or flat).
+     */
+    discount_type: "percentage" | "flat";
+    /**
+     * Discount amount (number, either percent or flat, based on discount_type).
+     */
+    discount_amount: number;
+    /**
+     * Max duration for discount (null if not limited).
+     */
+    discount_max_duration: number | null;
+    /**
+     * Terms and conditions URL (null if not set).
+     */
+    terms_url: string | null;
+    /**
+     * Help/support URL (null if not set).
+     */
+    help_url: string | null;
+    /**
+     * Support email address (null if not set).
+     */
+    support_email: string | null;
+    /**
+     * Revenue sharing mode, affects how commissions or splits are managed.
+     */
+    revenue_sharing_mode: "default" | "custom" | "negotiated";
+    /**
+     * Current program status.
+     */
+    status: ProgramStatus;
+    /**
+     * Metadata for this program (null if not present).
+     */
+    metadata: Record<string, unknown> | null;
+    /**
+     * Timestamp when this program was created.
+     */
+    created_at: Date;
+    /**
+     * Timestamp when this program was last updated.
+     */
+    updated_at: Date;
+}
+/**
+ * Commission DTO
+ *
+ * Represents a single commission record within the ambassador program.
+ */
+export interface CommissionDTO {
+    /**
+     * Unique identifier of the commission.
+     */
+    id: string;
+    /**
+     * Program ID the commission is associated with.
+     */
+    program_id: string;
+    /**
+     * Ambassador/affiliate user ID who earned the commission.
+     */
+    ambassador_id: string;
+    /**
+     * Associated reward ID if applicable, otherwise null.
+     */
+    reward_id: string | null;
+    /**
+     * Associated access link/campaign link ID, or null if not applicable.
+     */
+    access_link_id: string | null;
+    /**
+     * Payout batch ID if commission has been assigned, otherwise null.
+     */
+    payout_id: string | null;
+    /**
+     * Invoice ID for accounting or external payouts, or null.
+     */
+    invoice_id: string | null;
+    /**
+     * Customer ID related to the commission event, or null.
+     */
+    customer_id: string | null;
+    /**
+     * Event ID that triggered the commission if applicable, or null.
+     */
+    event_id: string | null;
+    /**
+     * Human-readable description of the commission, if any.
+     */
+    description: string | null;
+    /**
+     * The commission type (sale, lead, custom, etc).
+     */
+    type: CommissionType;
+    /**
+     * The commission amount (un-multiplied by quantity).
+     */
+    amount: number;
+    /**
+     * Units sold/quantity tracked for this commission.
+     */
+    quantity: number;
+    /**
+     * The final earnings from the commission (amount * quantity, may be negative for clawbacks).
+     */
+    earnings: number;
+    /**
+     * Currency code (e.g., usd, eur).
+     */
+    currency: string;
+    /**
+     * The current status of this commission (e.g., pending, processing, paid).
+     */
+    status: CommissionStatus;
+    /**
+     * (Internal use) User ID that created or processed this commission. May be null.
+     */
+    user_id: string | null;
+    /**
+     * Timestamp the commission was created.
+     */
+    created_at: Date;
+    /**
+     * Timestamp the commission was last updated.
+     */
+    updated_at: Date;
+}
+/**
+ * Program Enrollment DTO
+ */
+export interface ProgramEnrollmentDTO {
+    /**
+     * The unique ID for this enrollment.
+     */
+    id: string;
+    /**
+     * The ambassador's ID who enrolled.
+     */
+    ambassador_id: string;
+    /**
+     * The program's ID in which ambassador is enrolled.
+     */
+    program_id: string;
+    /**
+     * (Optional) The group ID associated with enrollment. Null if not present.
+     */
+    group_id: string | null;
+    /**
+     * (Optional) The reward ID for clicks. Null if not present.
+     */
+    click_reward_id: string | null;
+    /**
+     * (Optional) The reward ID for leads. Null if not present.
+     */
+    lead_reward_id: string | null;
+    /**
+     * (Optional) The reward ID for sales. Null if not present.
+     */
+    sale_reward_id: string | null;
+    /**
+     * The current enrollment status (e.g., active, banned).
+     */
+    status: ProgramEnrollmentStatus;
+    /**
+     * Total commissions earned via this enrollment.
+     */
+    total_commissions: number;
+    /**
+     * (Optional) Date/time the ambassador was banned, or null if not banned.
+     */
+    banned_at: Date | null;
+    /**
+     * (Optional) The ban reason type, or null if not banned.
+     */
+    banned_reason: BannedReasonType | null;
+    /**
+     * Application message.
+     */
+    application_message: string | null;
+    /**
+     * Who invited this ambassador (ambassador ID or user ID).
+     */
+    invited_by: string | null;
+    source: string | null;
+    /**
+     * Metadata for this enrollment.
+     */
+    metadata: Record<string, any> | null;
+    /**
+     * Timestamp when this enrollment was created.
+     */
+    created_at: Date;
+    /**
+     * Timestamp when the enrollment was last updated.
+     */
+    updated_at: Date;
+}
+/**
+ * Filterable interfaces
+ */
+export interface FilterableAmbassadorProps extends BaseFilterable<FilterableAmbassadorProps> {
+    id?: string | string[];
+    source_type?: AmbassadorSourceType | AmbassadorSourceType[];
+    source_id?: string | string[];
+    status?: AmbassadorStatus | AmbassadorStatus[];
+    country?: string | string[];
+    email?: string | string[];
+}
+export interface FilterableProgramProps extends BaseFilterable<FilterableProgramProps> {
+    id?: string | string[];
+    space_id?: string | string[];
+    owner_id?: string | string[];
+    owner_type?: string | string[];
+    status?: ProgramStatus | ProgramStatus[];
+    slug?: string | string[];
+}
+export interface FilterableCommissionProps extends BaseFilterable<FilterableCommissionProps> {
+    id?: string | string[];
+    payout_id?: OperatorMap<string>;
+    program_id?: string | string[];
+    ambassador_id?: string | string[];
+    access_link_id?: string | string[];
+    type?: CommissionType | CommissionType[];
+    status?: CommissionStatus | CommissionStatus[];
+    created_at?: OperatorMap<Date>;
+}
+export interface FilterableRewardProps extends BaseFilterable<FilterableRewardProps> {
+    id?: string | string[];
+    program_id?: string | string[];
+    event?: RewardEventType | RewardEventType[];
+    type?: RewardStructureType | RewardStructureType[];
+}
+export interface FilterableProgramEnrollmentProps extends BaseFilterable<FilterableProgramEnrollmentProps> {
+    id?: string | string[];
+    ambassador_id?: string | string[];
+    program_id?: string | string[];
+    group_id?: string | string[];
+    status?: ProgramEnrollmentStatus | ProgramEnrollmentStatus[];
+}
+/**
+ * Filterable props for listing payouts.
+ */
+export interface FilterablePayoutProps extends BaseFilterable<FilterableProgramEnrollmentProps> {
+    id?: string | string[];
+    program_id?: string | string[];
+    ambassador_id?: string | string[];
+    status?: string | string[];
+    currency?: string;
+}
+/**
+ * Program URL validation mode
+ */
+export type ProgramUrlValidationMode = "domain" | "exact";
+/**
+ * Program link structure
+ */
+export type ProgramLinkStructure = "short" | "query" | "path";
+/**
+ * The payout status string union.
+ */
+export type PayoutStatus = "pending" | "processing" | "processed" | "sent" | "completed" | "failed" | "canceled";
+/**
+ * Payout DTO
+ */
+export interface PayoutDTO {
+    /**
+     * The unique payout ID.
+     */
+    id: string;
+    /**
+     * Program this payout is for.
+     */
+    program_id: string;
+    /**
+     * Ambassador (partner) ID this payout is assigned to.
+     */
+    ambassador_id: string;
+    /**
+     * The payout amount (in cents!).
+     */
+    amount: number;
+    /**
+     * The payout currency (ISO code).
+     */
+    currency: string;
+    /**
+     * The payout status (pending, processing, processed, etc).
+     */
+    status: PayoutStatus;
+    /**
+     * Optional description (nullable).
+     */
+    description: string | null;
+    /**
+     * The payout period start, if applicable.
+     */
+    period_start: Date | null;
+    /**
+     * The payout period end, if applicable.
+     */
+    period_end: Date | null;
+    /**
+     * Spay/PayPal/other payment processor fields (nullable).
+     */
+    spay_transfer_id: string | null;
+    spay_payout_id: string | null;
+    paypal_transfer_id: string | null;
+    failure_reason: string | null;
+    /**
+     * Audit trail.
+     */
+    created_by: string | null;
+    /**
+     * Paid at timestamp, if payout completed.
+     */
+    paid_at: Date | null;
+    /**
+     * Timestamps.
+     */
+    created_at: Date;
+    updated_at: Date;
+    deleted_at: Date | null;
+}
+/**
+ * Revenue sharing rule DTO - Materialized rules
+ *
+ */
+export type RevenueShareRuleDTO = {
+    id: string;
+    program_id: string;
+    current_source_type: SourceType;
+    current_source_id: string;
+    /**
+     * For cross-context scenarios (away). Null if not set.
+     */
+    original_source_type: SourceType | null;
+    /**
+     * For cross-context scenarios (away). Null if not set.
+     */
+    original_source_id: string | null;
+    action: ActionType;
+    context_type: ContextType;
+    /**
+     * Relationship for scope. Null if not set.
+     */
+    relationship: RevenueRelationshipType | null;
+    actor_share: number;
+    context_owner_share: number;
+    creator_share: number;
+    beneficiary_share: number;
+    platform_share: number;
+    name: string;
+    /**
+     * Human-readable description. Null if not set.
+     */
+    description: string | null;
+    /**
+     * How this rule was created (authoritative source).
+     */
+    rule_origin: AuthorityType;
+    /**
+     * E.g. agreement_id, etc. Null if not set.
+     */
+    rule_origin_id: string | null;
+    active: boolean;
+    /**
+     * Timestamp when this rule expires. Null if not set.
+     */
+    expires_at: Date | null;
+    created_at: Date;
+    updated_at: Date;
+};
+/**
+ * Revenue rule filters
+ */
+export interface RevenueShareRuleFilters extends BaseFilterable<FilterableProgramProps> {
+    program_id?: string | string[];
+    current_source_type?: SourceType | SourceType[];
+    current_source_id?: string | string[];
+    original_source_type?: SourceType | SourceType[];
+    action?: ActionType | ActionType[];
+    context_type?: ContextType | ContextType[];
+    active?: boolean;
+    expires_at?: OperatorMap<Date>;
+}
+//# sourceMappingURL=common.d.ts.map