https://github.com/inventor2007/finary-community
Finary Community Library
https://github.com/inventor2007/finary-community
community finance finary gestion
Last synced: 6 months ago
JSON representation
Finary Community Library
- Host: GitHub
- URL: https://github.com/inventor2007/finary-community
- Owner: inventor2007
- Created: 2025-12-28T13:34:19.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2025-12-28T21:04:36.000Z (6 months ago)
- Last Synced: 2025-12-31T12:58:24.056Z (6 months ago)
- Topics: community, finance, finary, gestion
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/finary-community
- Size: 32.2 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Finary Community Library
Une bibliothèque non-officielle et communautaire pour s'interfacer avec l'API Finary. Elle permet de récupérer vos données de patrimoine, transactions, insights et bien plus encore de manière programmatique.
## Installation
```bash
npm install finary-community
```
## Configuration & Authentification
L'authentification sur Finary étant complexe (protection anti-bot), cette librairie fonctionne en utilisant une session navigateur existante qu'elle capture pour vous.
Vous devez générer un fichier `credentials.json` qui permettra à votre code de se connecter.
### Méthode Recommandée (Assistant Interactif)
Si vous avez installé la librairie via NPM dans votre projet, executez simplement cette commande dans votre terminal (**à la racine où se trouve votre `node_modules`**) :
```bash
npx finary-community setup
```
Cela ouvrira une fenêtre de navigateur contrôlée. Connectez-vous simplement à Finary, et le script capturera automatiquement vos tokens et cookies pour générer le fichier `credentials.json`.
### Méthode Manuelle
Vous pouvez créer manuellement un fichier `credentials.json` à la racine de votre projet avec la structure suivante :
```json
{
"token": "VOTRE_JWT_TOKEN",
"clerkSession": "VOTRE_CLERK_SESSION_ID",
"headers": {
"user-agent": "Mozilla/5.0 ...",
"cookie": "..."
}
}
```
> **Important :** Le `clerkSession` (cookie `__session`) et les `headers` (notamment le `User-Agent` et `Cookie`) sont **obligatoires** pour permettre à la librairie de rafraîchir le token automatiquement lorsqu'il expire. Sans cela, le script cessera de fonctionner après 20 minutes.
## API Reference
Voici la documentation détaillée de chaque fonction disponible dans la librairie.
### Types et Enums Communs
Plusieurs fonctions utilisent les énumérations suivantes pour filtrer les données :
* **`FinaryPeriod`** : Période temporelle pour les graphiques et variations.
* `'1d'` (24h), `'1w'` (Semaine), `'1m'` (Mois), `'ytd'` (Depuis début d'année), `'1y'` (1 an), `'all'` (Tout).
* **`TimeseriesType`** : Type de série temporelle.
* `'sum'` (Valeur cumulée), `'all'` (Détail).
* **`DistributionType`** : Type de répartition.
* `'account'` (Par compte).
* **`InvestmentDistributionType`** : Type de répartition investissement.
* `'stock'` (Par action/actif).
---
### 1. Client Principal (`FinaryClient`)
Point d'entrée de la librairie.
#### `constructor(config)`
Initialise le client.
* **Paramètres** :
* `config` (`AuthConfig`) : Objet de configuration `{ credentialsPath: string }`.
#### `getUserProfile()`
Récupère les informations du profil utilisateur connecté.
* **Retourne** : `Promise` (Nom, email, paramètres, etc.)
#### `getOrganizations()`
Liste les organisations (souvent appelées "familles" dans l'UI) associées à l'utilisateur. Vous aurez besoin de l'ID de l'organisation et du membre pour la plupart des autres appels.
* **Retourne** : `Promise`
---
### 2. Investissements (`client.investments`)
Tous les appels nécessitent généralement `organizationId` et `membershipId`.
#### `getPortfolio(organizationId, membershipId, period)`
Vue d'ensemble du portefeuille d'investissements (Actions, Crypto, Immo, etc.).
* **Paramètres** :
* `organizationId` (`string`) : ID de l'organisation.
* `membershipId` (`string`) : ID du membre.
* `period` (`FinaryPeriod`, défaut: `YTD`) : Période de calcul des plus/moins-values.
* **Retourne** : `Promise`
#### `getTimeseries(organizationId, membershipId, period, type)`
Récupère l'historique de la valeur du portefeuille (graphique).
* **Paramètres** :
* `period` (`FinaryPeriod`, défaut: `YTD`).
* `type` (`TimeseriesType`, défaut: `SUM`).
* **Retourne** : `Promise`
#### `getDistribution(organizationId, membershipId, type, period)`
Répartition des actifs.
* **Paramètres** :
* `type` (`InvestmentDistributionType`, défaut: `STOCK`).
* **Retourne** : `Promise`
#### `getDividends(organizationId, membershipId, withRealEstate)`
Liste les dividendes perçus et à venir.
* **Paramètres** :
* `withRealEstate` (`boolean`, défaut: `true`) : Inclure les loyers/dividendes immobiliers (SCPI).
* **Retourne** : `Promise`
#### `getSectorAllocation(organizationId, membershipId)`
Répartition sectorielle du portefeuille (Technologie, Santé, Finance...).
* **Retourne** : `Promise`
#### `getGeographicalAllocation(organizationId, membershipId)`
Répartition géographique du portefeuille (USA, Europe, Asie...).
* **Retourne** : `Promise`
#### `getFees(organizationId, membershipId)`
Analyse des frais sur les enveloppes (PEA, CTO, AV...).
* **Retourne** : `Promise`
#### `getAccount(organizationId, membershipId, accountId, period)`
Détails d'un compte spécifique (ex: un PEA particulier).
* **Paramètres** :
* `accountId` (`string`) : ID du compte.
* **Retourne** : `Promise`
#### Méthodes "Account" Spécifiques
De la même manière que pour le portefeuille global, vous pouvez appeler ces méthodes pour un compte précis :
* `getAccountTimeseries(orgId, memId, accountId, period, type)`
* `getAccountDistribution(orgId, memId, accountId, type, period)`
* `getAccountDividends(orgId, memId, accountId, withRealEstate)`
* `getAccountSectorAllocation(orgId, memId, accountId)`
* `getAccountGeographicalAllocation(orgId, memId, accountId)`
* `getAccountFees(orgId, memId, accountId)`
---
### 3. Épargne (`client.savings`)
Concerne les livrets bancaires, fonds euros, etc.
#### `getPortfolio(organizationId, membershipId, period)`
Vue d'ensemble de l'épargne.
* **Retourne** : `Promise`
#### `getAccounts(organizationId, membershipId, period)`
Liste tous les comptes d'épargne.
* **Retourne** : `Promise`
#### `getAccount(organizationId, membershipId, accountId, period)`
Détails d'un compte épargne spécifique.
* **Retourne** : `Promise`
#### `getTransaction(organizationId, membershipId, page, perPage, query, accountId)`
Récupère les transactions (virements, intérêts).
* **Paramètres** :
* `page` (`number`, défaut: `1`) : Numéro de page.
* `perPage` (`number`, défaut: `50`) : Nombre d'éléments par page.
* `query` (`string`, optionnel) : Recherche textuelle.
* `accountId` (`string`, optionnel) : Filtrer par compte spécifique.
* **Retourne** : `Promise`
#### `getTimeseries(...)` et `getAccountTimeseries(...)`
Historique de valeur.
---
### 4. Comptes Courants (`client.checkings`)
#### `getPortfolio(organizationId, membershipId, period)`
Solde total des comptes courants.
* **Retourne** : `Promise`
#### `getAccounts(organizationId, membershipId, period)`
Liste des comptes bancaires.
* **Retourne** : `Promise`
#### `getTransactions(...)`
Récupère les transactions bancaires. Fonctionne identiquement à celle de l'épargne.
---
### 5. Benchmarks (`client.benchmarks`)
#### `getAvailableAssets(organizationId, membershipId, period)`
Récupère la liste des actifs disponibles pour faire des comparaisons de performance.
* **Retourne** : `Promise`
## Exemple Complet
```typescript
import { FinaryClient, FinaryPeriod } from 'finary-community';
const client = new FinaryClient({ credentialsPath: './credentials.json' });
async function main() {
// 1. Setup
const orgs = await client.getOrganizations();
const orgId = orgs[0].id;
const memberId = orgs[0].members[0].id;
console.log(`Utilisateur : ${orgs[0].name}`);
// 2. Investissements
const investments = await client.investments.getPortfolio(orgId, memberId, FinaryPeriod.YTD);
console.log(`--- Investissements ---`);
console.log(`Total : ${investments.total.amount} €`);
console.log(`Plus-value latente : ${investments.total.unrealized_pnl} €`);
// 3. Dividendes à venir
const dividends = await client.investments.getDividends(orgId, memberId);
if(dividends.upcoming_dividends.length > 0) {
console.log(`--- Prochains Dividendes ---`);
dividends.upcoming_dividends.forEach(div => {
console.log(`${div.date} : ${div.amount}€ (${div.asset.name})`);
});
}
// 4. Recherche de transactions Livret A
const savings = await client.savings.getAccounts(orgId, memberId);
const livretA = savings.find(s => s.name.includes("Livret A"));
if (livretA) {
console.log(`--- Transactions Livret A ---`);
const txs = await client.savings.getTransactions(orgId, memberId, 1, 5, '', livretA.id);
txs.forEach(t => console.log(`${t.date} : ${t.amount}€ - ${t.description}`));
}
}
main().catch(console.error);
```