@ref247/affiliate-sdk/README.md

Ref247.io Affiliate SDK - integrate with us from you backend or build your custom UI

# Ref247AffiliateSDK

The `Ref247AffiliateSDK` is a TypeScript SDK for interacting with the [ref247.io](https://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/yarn/pnpm:

```bash
npm install @ref247/affiliate-sdk
```

## Initialization

Create a client instance:

```typescript
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:

```typescript
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