npm package: @lecoq/helloasso-sdk
Description: A fully-typed Node.js SDK for the HelloAsso API.
Latest version: 0.2.0

# HelloAsso SDK

A fully-typed Node.js SDK for the HelloAsso API.

## Installation

```bash
# npm
npm install helloasso-sdk

# yarn
yarn add helloasso-sdk

# pnpm
pnpm add helloasso-sdk

# bun
bun add helloasso-sdk
```

## Usage

### Initialization

The required `clientId` and `clientSecret` keys are generated using the HelloAsso dashboard.

```ts
import { HelloAssoClient } from 'helloasso-sdk';

const client = new HelloAssoClient({
  clientId: "<YOUR_CLIENT_ID>",
  clientSecret: "<YOUR_CLIENT_SECRET>",
});
```

### Authentication

Access and refresh tokens are automatically handled by the client when querying the endpoints.

### Methods

#### Checkout

##### `getCheckoutIntent`
Retrieve a checkout intent.
```ts
client.getCheckoutIntent(params: { organizationSlug: string; checkoutIntentId: number; withFailedRefundOperation?: boolean; }): Promise<CheckoutIntentResponse>
```

##### `initCheckout`
Init a checkout.
```ts
client.initCheckout(params: { organizationSlug: string; }, body: InitCheckoutBody): Promise<InitCheckoutResponse>
```

#### Directory

##### `getDirectoryForms`
Get all forms by form filters and organization filters.
```ts
client.getDirectoryForms(params: { pageSize?: number; continuationToken?: string; }, body: ListFormsRequest): Promise<ResultsWithPaginationModel<SynchronizableFormModel>>
```

##### `getDirectoryOrganizations`
Get all organizations by organization filters.
```ts
client.getDirectoryOrganizations(params: { pageSize?: number; continuationToken?: string; }, body: ListOrganizationsRequest): Promise<ResultsWithPaginationModel<SynchronizableOrganizationModel>>
```

#### Forms

##### `quickCreateForm`
Create a simplified event for an Organism.
```ts
client.quickCreateForm(params: { organizationSlug: string; formType: FormType; }, body: FormQuickCreateRequest): Promise<FormQuickCreateModel>
```

##### `updateFormState`
Update a form state.
```ts
client.updateFormState(params: { organizationSlug: string; formType: FormType; formSlug: string; }, body: FormStateRequest): Promise<void>
```

##### `getFormPublic`
Get detailed public data about a specific form.
```ts
client.getFormPublic(params: { organizationSlug: string; formType: FormType; formSlug: string; }): Promise<FormPublicModel>
```

##### `getFormTypes`
Get a list of formTypes for an organization.
```ts
client.getFormTypes(params: { organizationSlug: string; states?: FormState[]; }): Promise<FormType[]>
```

##### `getOrganizationForms`
Get the forms of a specific organization.
```ts
client.getOrganizationForms(params: { organizationSlug: string; states?: FormState[]; formTypes?: FormType[]; pageIndex?: number; pageSize?: number; continuationToken?: string; }): Promise<ResultsWithPaginationModel<FormLightModel>>
```

#### Items

##### `getItem`
Get the detail of an item contained in an order.
```ts
client.getItem(params: { itemId: number; withDetails?: boolean; }): Promise<ItemDetail>
```

##### `getFormItems`
Get a list of items "sold" in a form.
```ts
client.getFormItems(params: { organizationSlug: string; formSlug: string; formType: FormType; from?: string; to?: string; userSearchKey?: string; pageIndex?: number; pageSize?: number; continuationToken?: string; tierTypes?: TierType[]; itemStates?: ItemState[]; tierName?: string; withDetails?: boolean; sortOrder?: SortOrder; sortField?: SortField; }): Promise<unknown>
```

##### `getOrganizationItems`
Get a list of items sold by an organization.
```ts
client.getOrganizationItems(params: { organizationSlug: string; from?: string; to?: string; userSearchKey?: string; pageIndex?: number; pageSize?: number; continuationToken?: string; tierTypes?: TierType[]; itemStates?: ItemState[]; tierName?: string; withDetails?: boolean; sortOrder?: SortOrder; sortField?: SortField; }): Promise<unknown>
```

#### Orders

##### `getOrder`
Get detailed information about a specific order.
```ts
client.getOrder(params: { orderId: number; withFormData?: boolean; }): Promise<OrderDetail>
```

##### `getFormOrders`
Get form orders.
```ts
client.getFormOrders(params: { organizationSlug: string; formSlug: string; formType: FormType; from?: string; to?: string; userSearchKey?: string; pageIndex?: number; pageSize?: number; continuationToken?: string; withDetails?: boolean; sortOrder?: SortOrder; }): Promise<ResultsWithPaginationModel<Order>>
```

##### `getOrganizationOrders`
Get a list of orders within a specific organization.
```ts
client.getOrganizationOrders(params: { organizationSlug: string; from?: string; to?: string; userSearchKey?: string; pageIndex?: number; pageSize?: number; continuationToken?: string; formTypes?: FormType[]; withDetails?: boolean; sortOrder?: SortOrder; }): Promise<ResultsWithPaginationModel<Order>>
```

##### `cancelOrder`
Cancels future payments for an order, no refunds will be given.
```ts
client.cancelOrder(params: { orderId: number; }): Promise<void>
```

#### Payments

##### `exportCashOut`
Download the cash-out details as a CSV, Excel or Json.
```ts
client.exportCashOut(params: { organizationSlug: string; cashOutId: number; }): Promise<CashoutExportRowModel[]>
```

##### `getPayment`
Get detailed information about a specific payment.
```ts
client.getPayment(params: { paymentId: number; withFailedRefundOperation?: boolean; }): Promise<PaymentDetail>
```

##### `getFormPayments`
Get information about payments made in a specific form.
```ts
client.getFormPayments(params: { organizationSlug: string; formSlug: string; formType: FormType; from?: string; to?: string; userSearchKey?: string; pageIndex?: number; pageSize?: number; continuationToken?: string; states?: PaymentState[]; sortOrder?: SortOrder; sortField?: SortField; }): Promise<ResultsWithPaginationModel<Payment>>
```

##### `getOrganizationPayments`
Get information about payments made to a specific organization.
```ts
client.getOrganizationPayments(params: { organizationSlug: string; from?: string; to?: string; userSearchKey?: string; pageIndex?: number; pageSize?: number; continuationToken?: string; states?: PaymentState[]; sortOrder?: SortOrder; sortField?: SortField; }): Promise<ResultsWithPaginationModel<Payment>>
```

##### `refundPayment`
Refund a payment.
```ts
client.refundPayment(params: { paymentId: number; comment?: string; cancelOrder?: boolean; sendRefundMail?: boolean; amount?: number; "x-mfa-access-authorization"?: string; "x-mfa-sms-access-authorization"?: string; "x-mfa-password-authorization"?: string; }): Promise<RefundOperationModel>
```

#### Partners

##### `updatePartnerDomain`
A partner can update his domain.
```ts
client.updatePartnerDomain(body: PublicPutApiClientRequest): Promise<void>
```

##### `updatePartnerOrganizationNotificationUrl`
A partner can update a notification url linked to an organization.
```ts
client.updatePartnerOrganizationNotificationUrl(params: { organizationSlug: string; }, body: PostApiUrlNotificationBody): Promise<ApiUrlNotificationModel>
```

##### `deletePartnerOrganizationNotificationUrl`
A partner can delete a notification url linked to an organization.
```ts
client.deletePartnerOrganizationNotificationUrl(params: { organizationSlug: string; notificationType?: ApiNotificationType; }): Promise<void>
```

##### `updatePartnerNotificationUrl`
A partner can update his main notification url.
```ts
client.updatePartnerNotificationUrl(body: PostApiUrlNotificationBody): Promise<ApiUrlNotificationModel>
```

##### `deletePartnerNotificationUrl`
A partner can delete his main notification url.
```ts
client.deletePartnerNotificationUrl(params: { notificationType?: ApiNotificationType; }): Promise<void>
```

##### `getPartner`
A partner can retrieve his information.
```ts
client.getPartner(): Promise<PartnerPublicModel>
```

##### `getPartnerOrganizations`
Get all organization by partner.
```ts
client.getPartnerOrganizations(params: { pageSize?: number; continuationToken?: string; }): Promise<ResultsWithPaginationModel<PartnerOrganizationModel>>
```

#### Tags

##### `getTag`
Get Internal Tag Detail.
```ts
client.getTag(params: { tagName: string; withCount?: boolean; withAmount?: boolean; }): Promise<InternalTagModel>
```

#### Users

##### `getMyOrganizations`
Get my organizations.
```ts
client.getMyOrganizations(): Promise<OrganizationLightModel[]>
```

#### Values

##### `getOrganizationCategories`
Get list of organization categories.
```ts
client.getOrganizationCategories(): Promise<OrganismCategoryModel[]>
```

##### `getFormActivityTypes`
Get all activity types for a form type.
```ts
client.getFormActivityTypes(params: { formType: FormType; }): Promise<FormActivityModel[]>
```

##### `getPublicTags`
Get list of public tags.
```ts
client.getPublicTags(): Promise<PublicTagModel[]>
```

##### `getCompanyLegalStatus`
Get company legal status list.
```ts
client.getCompanyLegalStatus(): Promise<CompanyLegalStatusModel[]>
```