Ref247AffiliateSDK

The Ref247AffiliateSDK is a TypeScript SDK for interacting with the ref247.io Affiliate API (https://ref247.io/api).

This README includes a comprehensive, grouped list of available SDK methods (as implemented in src/index.ts) and short usage examples.

Installation

Install the SDK via npm:

npm install @ref247/affiliate-sdk

Initialization

Create a client instance:

import { Ref247AffiliateSDK } from '@ref247/affiliate-sdk';

// Optionally pass a custom API url and API credentials
const WHITELABEL_API_URL = 'https://ref247.io/api';
const affiliateApi = Ref247AffiliateSDK.init(WHITELABEL_API_URL, apiKey?, apiSecret?);

Available Methods (by category)

Auth

• init(apiUrl, apiKey, apiSecret): Used for system to system api requests
• setBearer('your-jwt-token'): Only needed when logging in with magic link
• getRoles(): Promise<Role[]>: List all roles.

User

• getMe(): Promise<User>: Get the current authenticated user.
• getUserAffiliationsByOrg(orgId: string): Promise<Affiliation>: Get affiliations for the current user within an organization.
• updateUser(userId: string, updateData: UpdateUser): Promise<User>: Update a user's profile.

Organization

• getOrganizations(): Promise<UserOrganization[]>: List organizations for the user.
• createOrganization(name: string, userId: string): Promise<Organization>: Create a new organization.
• updateOrganization(organizationId: string, updateData: Partial<UpdateOrganization>): Promise<Organization>: Update organization details.
• getOrganizationTheme(organizationId: string): Promise<OrgTheme>: Get theme settings.
• getOrganizationCurrency(organizationId: string): Promise<OrganizationCurrency[]>: List organization currencies.
• addOrganizationCurrency(organizationId: string, name: string): Promise<OrganizationCurrency>: Add a new currency.
• updateOrganizationCurrency(organizationId: string, id: string, name: string): Promise<OrganizationCurrency>: Update a currency.
• removeOrganizationCurrency(organizationId: string, id: string): Promise<string>: Remove a currency.
• getOrganizationPlan(orgId: string): Promise<OrganizationPlan>: Get an organization's plan.
• getPricingPlans(): Promise<OrganizationPlan[]>: List available pricing plans.
• getPricingPlan(planId: string): Promise<OrganizationPlan>: Get a specific pricing plan.
• getOrganizationEventTypes(organizationId: string): Promise<OrganizationEventType[]>: List event types.
• addOrganizationEventType(organizationId: string, name: string): Promise<OrganizationEventType>: Create an event type.
• updateOrganizationEventType(organizationId: string, id: string, name: string): Promise<OrganizationEventType>: Update an event type.
• removeOrganizationEventType(organizationId: string, id: string): Promise<string>: Delete an event type.
• addUserToOrganization(organizationId: string, email: string, roleId: string): Promise<Organization>: Invite/add a user to organization.
• updateUserRole(organizationId: string, userId: string, roleId: string): Promise<UserOrganization>: Change a user's role.
• deleteUserFromOrganization(organizationId: string, userId: string): Promise<void>: Remove a user.
• getUsersFromOrganization(organizationId: string, page?: number, take?: number, search?: string, orderBy?: string, order?: 'ASC'|'DESC', withDeleted?: boolean): Promise<Page<ListUser>>: Paginated organization users list.
• enterpriseRequest(orgId: string): Promise<void>: Submit an enterprise request for an org.

Affiliates & Affiliations

• getAffiliates(organizationId: string, page?: number, take?: number, search?: string, orderBy?: string, order?: 'ASC'|'DESC', withDeleted?: boolean): Promise<Page<AffiliationList>>: List affiliates for an organization.
• createAffiliate(affiliateData: CreateAffiliate): Promise<Affiliation>: Create an affiliate.
• getAffiliate(affiliationId: string): Promise<Affiliation>: Get affiliate details.
• getAffiliateReferrals(affiliationId: string, page?: number, take?: number, search?: string, orderBy?: string, order?: 'ASC'|'DESC', withDeleted?: boolean): Promise<Page<Affiliation>>: Get referrals for an affiliate.
• getAffiliatesByAffiliateId(affiliationId: string, page?: number, take?: number, search?: string, orderBy?: string, order?: 'ASC'|'DESC', withDeleted?: boolean): Promise<Page<AffiliationGenericList>>: Get referrals list by affiliate id.
• addCampaignToAffiliate(affiliateId: string, campaignId: string): Promise<Affiliation>: Assign a campaign to an affiliate.
• removeCampaignToAffiliate(affiliateId: string, campaignId: string): Promise<Affiliation>: Remove campaign assignment.
• updateAffiliate(affiliationId: string, updateData: UpdateAffiliate): Promise<Affiliation>: Update affiliate data.

Affiliate Links / Marketing

• getAffiliateLinkById(affiliateLinkId: string): Promise<AffiliateLink>: Get an affiliate link.
• getAffiliateLinkByUri(affiliateLinkUri: string): Promise<AffiliateLink>: Get link by URI.
• createAffiliateLink(affiliateData: CreateAffiliateLink): Promise<AffiliateLink>: Create an affiliate link.
• deleteAffiliateLink(affiliateLinkId: string): Promise<void>: Delete a link.
• getAllAffiliateLinksOfAffiliate(affiliateId: string, withDeleted?: boolean, page?: number, take?: number, search?: string, orderBy?: string, order?: 'ASC'|'DESC'): Promise<Page<AffiliateLink>>: Paginated affiliateLinks for affiliate.
• getAllAffiliateLinksOfOrganization(orgId: string, withDeleted?: boolean, page?: number, take?: number, search?: string, orderBy?: string, order?: 'ASC'|'DESC'): Promise<Page<AffiliateLink>>: Paginated affiliateLinks for organization.

Campaigns

• createCampaign(campaignData: CreateCampaign): Promise<Campaign>: Create a campaign.
• getAllCampaignsOfOrganization(orgId: string, withDeleted?: boolean): Promise<Campaign[]>: List org campaigns.
• getCampaignsByIds(orgId: string, campaignIds: string[]): Promise<Campaign[]>: Fetch campaigns by IDs.
• updateCampaign(id: string, campaignData: Partial<UpdateCampaign>): Promise<Campaign>: Update campaign.
• updateCampaignAssets(id: string, campaignData: UpdateCampaignAssets): Promise<Campaign>: Update campaign assets.
• deleteCampaign(id: string): Promise<void>: Delete campaign.

Commissions

• getCommissionStructuresOfOrganization(orgId: string, withDeleted?: boolean): Promise<CommissionStructure[]>: List commission structures.
• getCommissionStructure(commissionStructureId: string): Promise<CommissionStructure>: Get a structure.
• addCommissionStructureToCampaign(commissionStructureId: string, campaignId: string): Promise<Campaign>: Attach structure to campaign.
• removeCommissionStructureToCampaign(commissionStructureId: string, campaignId: string): Promise<Campaign>: Detach structure.
• addCommissionStructure(commissionStructureData: CreateCommissionStructure): Promise<CommissionStructure>: Create structure.
• deleteCommissionStructure(commissionStructureId: string): Promise<void>: Delete structure.
• updateCommissionStructure(id: string, updateData: UpdateCommissionStructure): Promise<CommissionStructure>: Update structure.
• getCommissionRule(commissionRuleId: string): Promise<CommissionRule>: Get rule.
• getCommissionRulesOfcommissionStructure(commissionStructureId: string, withDeleted?: boolean): Promise<CommissionRule[]>: List rules.
• addCommissionRule(commissionRuleData: CreateCommissionRule): Promise<CommissionRule>: Add rule (auto-casts numeric fields).
• updateCommissionRule(id: string, updateData: UpdateCommissionRule): Promise<CommissionRule>: Update rule (auto-casts numeric fields).
• deleteCommissionRule(commissionRuleId: string): Promise<void>: Delete a rule.
• getAffiliateCommissionsGenerated(affiliationId: string, page?: number, take?: number, search?: string, orderBy?: string, order?: 'ASC'|'DESC'): Promise<Page<Commission>>: Commissions generated by affiliate.
• getAffiliateCommissionsGained(affiliationId: string, page?: number, take?: number, search?: string, orderBy?: string, order?: 'ASC'|'DESC'): Promise<Page<Commission>>: Commissions gained by affiliate.
• getOrganizationCommissions(orgId: string, page?: number, take?: number, search?: string, orderBy?: string, order?: 'ASC'|'DESC', status?: CommissionStatusEnum): Promise<Page<Commission>>: Organization commissions.
• getOrganizationCommissionsByAffiliate(orgId: string, page?: number, take?: number, search?: string, orderBy?: string, order?: 'ASC'|'DESC', status?: CommissionStatusEnum): Promise<Page<CommissionGroup>>: Org commissions grouped by affiliate.
• updateCommissionsStatus(orgId: string, commissionIds: string[], status: CommissionStatusEnum): Promise<Commission[]>: Bulk update statuses.
• updatePendingCommissionsStatusOfAffiliate(affiliationId: string, status: CommissionStatusEnum, currencyId: string): Promise<Commission[]>: Update pending commissions for an affiliate.

Charts & Stats

• getAffiliateCommissionsChartData(affiliateId: string, startDate?: Date, endDate?: Date): Promise<CommissionChartData>: Commission chart for affiliate.
• getAffiliateReferralsChartData(affiliateId: string, startDate?: Date, endDate?: Date): Promise<LineData[]>: Referrals chart for affiliate.
• getOrgReferralsChartData(orgId: string, startDate?: Date, endDate?: Date): Promise<LineData[]>: Referrals chart for org.
• getOrgCommissionsChartData(orgId: string, startDate?: Date, endDate?: Date): Promise<OrgCommissionChartData>: Org commission chart.
• getAffiliateStats(affiliateId: string): Promise<AffiliateStats>: Stats for an affiliate.
• getOrganizationAffiliationStats(orgId: string): Promise<OrganizationAffiliateStats>: Organization affiliation stats.
• getOrganizationCommissionStats(orgId: string): Promise<CommissionSummary[]>: Organization commission summary.
• getOrganizationGenericStats(orgId: string): Promise<OrgGenericStats>: Generic org stats.
• getOrganizationPrivateStats(orgId: string): Promise<OrgPrivateStats>: Private org stats.

API Keys

• createApiKey(organizationId: string, data: CreateApiKey): Promise<ApiKey>: Create an API key.
• listApiKeysOfOrganization(organizationId: string): Promise<ApiKey[]>: List org API keys.
• listApiKeysOfUserAndOrganizationId(userId: string, organizationId: string): Promise<ApiKey[]>: List user+org API keys.
• revokeApiKey(organizationId: string, apiKeyId: string): Promise<void>: Revoke an API key.

File Uploads

• getOrganizationSignedUrl(orgId: string): Promise<SignedUrlResponse>: Get a signed URL for organization use.
• getPublicSignedUrl(orgId: string): Promise<SignedUrlResponse>: Get a public signed URL.
• getUploadUrlOrganization(uploadRequest: UploadRequestOrganization): Promise<UploadResponse>: Request organization upload URL.
• getUploadUrlUser(uploadRequest: UploadRequestUser): Promise<UploadResponse>: Request user upload URL.

Payments & Billing

• getPaymentsByOrganization(orgId: string): Promise<Payment[]>: List org payments.
• getPaymentsPendingByOrganization(orgId: string): Promise<Payment[]>: List pending payments.

Audit Logs

• getAuditLogsByOrganizationId(orgId: string, page?: number, take?: number, search?: string, orderBy?: string, order?: 'ASC'|'DESC', startDate?: Date, endDate?: Date): Promise<Page<AuditLog>>: Paginated audit logs.

Referral Actions

• getOrganizationReferralActions(orgId: string, page?: number, take?: number, search?: string, orderBy?: string, order?: 'ASC'|'DESC', isProcessed?: boolean): Promise<Page<ReferralAction>>: List referral actions.
• deleteReferralAction(id: string): Promise<void>: Delete a referral action.
• createReferralAction(referralActionDatas: CreateReferralAction[]): Promise<Message>: Bulk create referral actions.

Examples

Simple initialization and getting current user, creating an organization and a campaign:

const affiliateApi = Ref247AffiliateSDK.init();
const me = await affiliateApi.getMe();
const org = await affiliateApi.createOrganization('Acme Corp', 'user-id');
const campaign = await affiliateApi.createCampaign({ name: 'Launch Promo', budget: 5000 });

Reference

For exact DTO shapes and additional types see src/common/dtos and src/index.ts.

Contributing

Contributions welcome — open a PR or issue.

License

MIT