# easyverein

> API Library for easyVerein®

Latest version **0.5.0** (published 2023-03-16) · MIT license · 0 weekly downloads

## Install

```sh
npm install easyverein
pnpm add easyverein
yarn add easyverein
bun add easyverein
```

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.5.0 |
| Published | 2023-03-16 |
| First published | 2021-01-02 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=10 |
| Dependencies | 2 |
| Unpacked size | 109.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 11 |
| Author | Frédéric Bolvin |
| Maintainers | frebo |
| Keywords | node, api, library, easyverein |

## Links

- npm: https://www.npmjs.com/package/easyverein
- Repository: https://github.com/Fensterbank/easyverein
- Homepage: https://github.com/Fensterbank/easyverein#readme
- Issues: https://github.com/Fensterbank/easyverein/issues
- npm.io page: https://npm.io/package/easyverein

## Dependencies (2)

- [node-fetch](https://npm.io/package/node-fetch.md) ^2.6.5
- [query-string](https://npm.io/package/query-string.md) ^7.0.1

## Alternatives

- [@expo/fingerprint](https://npm.io/package/@expo/fingerprint.md) — 6.2M weekly downloads
- [@azure/monitor-opentelemetry-exporter](https://npm.io/package/@azure/monitor-opentelemetry-exporter.md) — 850.0K weekly downloads
- [@azure/monitor-opentelemetry](https://npm.io/package/@azure/monitor-opentelemetry.md) — 624.0K weekly downloads
- [@posthog/ai](https://npm.io/package/@posthog/ai.md) — 423.3K weekly downloads
- [fakefilter](https://npm.io/package/fakefilter.md) — 63.9K weekly downloads

## Recent versions

- 0.5.0 (latest) — 2023-03-16
- 0.4.0 — 2022-08-21
- 0.3.0 — 2021-10-05
- 0.2.2 — 2021-04-13
- 0.2.1 — 2021-02-08
- 0.2.0 — 2021-02-01
- 0.1.1 — 2021-01-02
- 0.1.0 — 2021-01-02

## README

[<img src="https://img.shields.io/npm/v/easyverein">](https://www.npmjs.com/package/easyverein)

# Node API Library for easyVerein®  
 <img src="https://easyverein.com/static/logo.png" alt="easyVerein® Logo" height="100">

This is a typed Node.js API client for the **easyVerein® web service**.  
Since this client is in early development, only a few methods are implemented.  

This library is **inofficial** and therefore is **not developed or supported by** [easyVerein®](https://easyverein.com/) and [SD Software-Design GmbH](https://software-design.de/).

Official Library Documentation [easyverein.com/api/documentation](https://easyverein.com/api/documentation/)  
_You should be logged in to see anything useful there._

## Installation
```bash
yarn add easyverein
```
or
```bash
npm install easyverein
```

## Getting started

### Set global API token and - if necessary - API version
```typescript
  import { setApiToken, setApiVersion } from 'easyverein';

  setApiToken('token');

  // by default stable v1.4 is used. You can also define to use the deprecated v1.3 or the latest v1.5, which is under development and considered UNSTABLE! Usage on own risk!
  setApiVersion('v1.4'); // this line is optional, to always use the default version of this library
```
### Get the organization

```typescript
  import { getOrganization } from 'easyverein';

  const org = await getOrganization();

  console.log(`
    Our Organization is ${org.name}. Let's use the primary color ${org.primaryColor}
    and secondary color ${org.secondaryColor} to theme some things.`
  );
```

### Query Parameter
By default the API returns all fields, which is resulting in huge objects. (~ 23.5 KB per member item).  
The API supports a nestable query parameter containing all needed fields.

**A good sample for a get request with nested query:**

`GET https://easyverein.com/api/v1.1/member?query={id,contactDetails{id,name},org{id,name,short},email,membershipNumber}`

In most cases, you can pass that query string as a parameter to the client method.

```typescript
  import { getMembers } from 'easyverein';

  // Get all members with a small set of attributes
  const members = await getMembers(
    '{id,contactDetails{id,name},org{id,name,short},email,membershipNumber}'
  );
```

### Members
You can specify the parameter `query: string` to restrict the fields returned by the API.  
You can check the type `Member` to see which fields can be populated.

```typescript
  import { getMembers, getMember } from 'easyverein';

  // Get all members with a small set of attributes
  const members = await getMembers(
    '{id,contactDetails{name,dateOfBirth},membershipNumber,memberGroups,joinDate}'
  );

  members.forEach(m => console.log(m.contactDetails.name))


  // Get a specific member with two attributes
  const member = await getMember('123', 'contactDetails{name},membershipNumber');

  console.log(`Hello ${member.contactDetails.name}, your membership number is ${member.membershipNumber}.`);
```

### Contact Details
Contact details can be referenced to a member id, but don't have to.  
If you need all kind of contacts (e.g. Companies and Supplier), you can get them with this method.  
If you only want to get the details of your real members, it's better to use the `getMembers` method and include the contact details in the query.  
  
You can specify the parameter `query: string` to restrict the fields returned by the API.  
You can check the type `ContactDetail` to see which fields can be populated.

```typescript
  import { getContactDetails } from 'easyverein';

  // Get all members with a small set of attributes
  const contacts = await client.getContactDetails(
    '{salutation,firstName,familyName,mobilePhone,referencedMemberPK}'
  );

  // Get a specific contact with two attributes
  const contact = await client.getContactDetails('123', '{salutation,familyName}');
  console.log(`Hello ${contact.salutation} ${contact.familyName}!`);
```

## Developing and debugging this libary
To start working, run the `watch:build` task using [`npm`](https://docs.npmjs.com/getting-started/what-is-npm) or [`yarn`](https://yarnpkg.com/).

```sh
yarn watch:build
```

In another terminal tab/window, run the `watch:test` task while passing the api token as environment variable:

```sh
EASYVEREIN_TOKEN=123456acd43534dfe yarn watch:test
```

These watch tasks make development much faster and more interactive. 
  
To test your development directly, you can write unit tests in `index.spec.ts`.  

## Author & License
MIT License. Built with ❤️ by Frédéric Bolvin, [f-bit software](https://f-bit.software).

---
_Source: https://npm.io/package/easyverein · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._