{"id":35178289,"url":"https://github.com/inventor2007/finary-community","last_synced_at":"2026-01-13T21:10:06.040Z","repository":{"id":330890726,"uuid":"1124167307","full_name":"inventor2007/finary-community","owner":"inventor2007","description":"Finary Community Library","archived":false,"fork":false,"pushed_at":"2025-12-28T21:04:36.000Z","size":33,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-31T12:58:24.056Z","etag":null,"topics":["community","finance","finary","gestion"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/finary-community","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/inventor2007.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-28T13:34:19.000Z","updated_at":"2025-12-29T10:22:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/inventor2007/finary-community","commit_stats":null,"previous_names":["inventor2007/finary-community"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/inventor2007/finary-community","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inventor2007%2Ffinary-community","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inventor2007%2Ffinary-community/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inventor2007%2Ffinary-community/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inventor2007%2Ffinary-community/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/inventor2007","download_url":"https://codeload.github.com/inventor2007/finary-community/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inventor2007%2Ffinary-community/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28400916,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-13T14:36:09.778Z","status":"ssl_error","status_checked_at":"2026-01-13T14:35:19.697Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["community","finance","finary","gestion"],"created_at":"2025-12-28T23:44:03.019Z","updated_at":"2026-01-13T21:10:06.033Z","avatar_url":"https://github.com/inventor2007.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Finary Community Library\n\nUne 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.\n\n## Installation\n\n```bash\nnpm install finary-community\n```\n\n## Configuration \u0026 Authentification\n\nL'authentification sur Finary étant complexe (protection anti-bot), cette librairie fonctionne en utilisant une session navigateur existante qu'elle capture pour vous.\n\nVous devez générer un fichier `credentials.json` qui permettra à votre code de se connecter.\n\n### Méthode Recommandée (Assistant Interactif)\n\nSi 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`**) :\n\n```bash\nnpx finary-community setup\n```\n\nCela 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`.\n\n### Méthode Manuelle\n\nVous pouvez créer manuellement un fichier `credentials.json` à la racine de votre projet avec la structure suivante :\n\n```json\n{\n    \"token\": \"VOTRE_JWT_TOKEN\",\n    \"clerkSession\": \"VOTRE_CLERK_SESSION_ID\",\n    \"headers\": {\n        \"user-agent\": \"Mozilla/5.0 ...\",\n        \"cookie\": \"...\"\n    }\n}\n```\n\n\u003e **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.\n\n## API Reference\n\nVoici la documentation détaillée de chaque fonction disponible dans la librairie.\n\n### Types et Enums Communs\n\nPlusieurs fonctions utilisent les énumérations suivantes pour filtrer les données :\n\n*   **`FinaryPeriod`** : Période temporelle pour les graphiques et variations.\n    *   `'1d'` (24h), `'1w'` (Semaine), `'1m'` (Mois), `'ytd'` (Depuis début d'année), `'1y'` (1 an), `'all'` (Tout).\n*   **`TimeseriesType`** : Type de série temporelle.\n    *   `'sum'` (Valeur cumulée), `'all'` (Détail).\n*   **`DistributionType`** : Type de répartition.\n    *   `'account'` (Par compte).\n*   **`InvestmentDistributionType`** : Type de répartition investissement.\n    *   `'stock'` (Par action/actif).\n\n---\n\n### 1. Client Principal (`FinaryClient`)\n\nPoint d'entrée de la librairie.\n\n#### `constructor(config)`\nInitialise le client.\n*   **Paramètres** :\n    *   `config` (`AuthConfig`) : Objet de configuration `{ credentialsPath: string }`.\n\n#### `getUserProfile()`\nRécupère les informations du profil utilisateur connecté.\n*   **Retourne** : `Promise\u003cUserProfile\u003e` (Nom, email, paramètres, etc.)\n\n#### `getOrganizations()`\nListe 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.\n*   **Retourne** : `Promise\u003cOrganization[]\u003e`\n\n---\n\n### 2. Investissements (`client.investments`)\n\nTous les appels nécessitent généralement `organizationId` et `membershipId`.\n\n#### `getPortfolio(organizationId, membershipId, period)`\nVue d'ensemble du portefeuille d'investissements (Actions, Crypto, Immo, etc.).\n*   **Paramètres** :\n    *   `organizationId` (`string`) : ID de l'organisation.\n    *   `membershipId` (`string`) : ID du membre.\n    *   `period` (`FinaryPeriod`, défaut: `YTD`) : Période de calcul des plus/moins-values.\n*   **Retourne** : `Promise\u003cInvestmentPortfolio\u003e`\n\n#### `getTimeseries(organizationId, membershipId, period, type)`\nRécupère l'historique de la valeur du portefeuille (graphique).\n*   **Paramètres** :\n    *   `period` (`FinaryPeriod`, défaut: `YTD`).\n    *   `type` (`TimeseriesType`, défaut: `SUM`).\n*   **Retourne** : `Promise\u003cTimeseries[]\u003e`\n\n#### `getDistribution(organizationId, membershipId, type, period)`\nRépartition des actifs.\n*   **Paramètres** :\n    *   `type` (`InvestmentDistributionType`, défaut: `STOCK`).\n*   **Retourne** : `Promise\u003cDistribution\u003e`\n\n#### `getDividends(organizationId, membershipId, withRealEstate)`\nListe les dividendes perçus et à venir.\n*   **Paramètres** :\n    *   `withRealEstate` (`boolean`, défaut: `true`) : Inclure les loyers/dividendes immobiliers (SCPI).\n*   **Retourne** : `Promise\u003cDividendsResponse\u003e`\n\n#### `getSectorAllocation(organizationId, membershipId)`\nRépartition sectorielle du portefeuille (Technologie, Santé, Finance...).\n*   **Retourne** : `Promise\u003cSectorAllocationResponse\u003e`\n\n#### `getGeographicalAllocation(organizationId, membershipId)`\nRépartition géographique du portefeuille (USA, Europe, Asie...).\n*   **Retourne** : `Promise\u003cGeographicalAllocationResponse\u003e`\n\n#### `getFees(organizationId, membershipId)`\nAnalyse des frais sur les enveloppes (PEA, CTO, AV...).\n*   **Retourne** : `Promise\u003cFeesResponse\u003e`\n\n#### `getAccount(organizationId, membershipId, accountId, period)`\nDétails d'un compte spécifique (ex: un PEA particulier).\n*   **Paramètres** :\n    *   `accountId` (`string`) : ID du compte.\n*   **Retourne** : `Promise\u003cInvestmentAccount\u003e`\n\n#### Méthodes \"Account\" Spécifiques\nDe la même manière que pour le portefeuille global, vous pouvez appeler ces méthodes pour un compte précis :\n*   `getAccountTimeseries(orgId, memId, accountId, period, type)`\n*   `getAccountDistribution(orgId, memId, accountId, type, period)`\n*   `getAccountDividends(orgId, memId, accountId, withRealEstate)`\n*   `getAccountSectorAllocation(orgId, memId, accountId)`\n*   `getAccountGeographicalAllocation(orgId, memId, accountId)`\n*   `getAccountFees(orgId, memId, accountId)`\n\n---\n\n### 3. Épargne (`client.savings`)\n\nConcerne les livrets bancaires, fonds euros, etc.\n\n#### `getPortfolio(organizationId, membershipId, period)`\nVue d'ensemble de l'épargne.\n*   **Retourne** : `Promise\u003cSavingsPortfolio\u003e`\n\n#### `getAccounts(organizationId, membershipId, period)`\nListe tous les comptes d'épargne.\n*   **Retourne** : `Promise\u003cSavingsAccount[]\u003e`\n\n#### `getAccount(organizationId, membershipId, accountId, period)`\nDétails d'un compte épargne spécifique.\n*   **Retourne** : `Promise\u003cSavingsAccount\u003e`\n\n#### `getTransaction(organizationId, membershipId, page, perPage, query, accountId)`\nRécupère les transactions (virements, intérêts).\n*   **Paramètres** :\n    *   `page` (`number`, défaut: `1`) : Numéro de page.\n    *   `perPage` (`number`, défaut: `50`) : Nombre d'éléments par page.\n    *   `query` (`string`, optionnel) : Recherche textuelle.\n    *   `accountId` (`string`, optionnel) : Filtrer par compte spécifique.\n*   **Retourne** : `Promise\u003cTransaction[]\u003e`\n\n#### `getTimeseries(...)` et `getAccountTimeseries(...)`\nHistorique de valeur.\n\n---\n\n### 4. Comptes Courants (`client.checkings`)\n\n#### `getPortfolio(organizationId, membershipId, period)`\nSolde total des comptes courants.\n*   **Retourne** : `Promise\u003cCheckingPortfolio\u003e`\n\n#### `getAccounts(organizationId, membershipId, period)`\nListe des comptes bancaires.\n*   **Retourne** : `Promise\u003cCheckingAccount[]\u003e`\n\n#### `getTransactions(...)`\nRécupère les transactions bancaires. Fonctionne identiquement à celle de l'épargne.\n\n---\n\n### 5. Benchmarks (`client.benchmarks`)\n\n#### `getAvailableAssets(organizationId, membershipId, period)`\nRécupère la liste des actifs disponibles pour faire des comparaisons de performance.\n*   **Retourne** : `Promise\u003cBenchmarkAsset[]\u003e`\n\n## Exemple Complet\n\n```typescript\nimport { FinaryClient, FinaryPeriod } from 'finary-community';\n\nconst client = new FinaryClient({ credentialsPath: './credentials.json' });\n\nasync function main() {\n    // 1. Setup\n    const orgs = await client.getOrganizations();\n    const orgId = orgs[0].id;\n    const memberId = orgs[0].members[0].id;\n\n    console.log(`Utilisateur : ${orgs[0].name}`);\n\n    // 2. Investissements\n    const investments = await client.investments.getPortfolio(orgId, memberId, FinaryPeriod.YTD);\n    console.log(`--- Investissements ---`);\n    console.log(`Total : ${investments.total.amount} €`);\n    console.log(`Plus-value latente : ${investments.total.unrealized_pnl} €`);\n\n    // 3. Dividendes à venir\n    const dividends = await client.investments.getDividends(orgId, memberId);\n    if(dividends.upcoming_dividends.length \u003e 0) {\n        console.log(`--- Prochains Dividendes ---`);\n        dividends.upcoming_dividends.forEach(div =\u003e {\n            console.log(`${div.date} : ${div.amount}€ (${div.asset.name})`);\n        });\n    }\n\n    // 4. Recherche de transactions Livret A\n    const savings = await client.savings.getAccounts(orgId, memberId);\n    const livretA = savings.find(s =\u003e s.name.includes(\"Livret A\"));\n    if (livretA) {\n        console.log(`--- Transactions Livret A ---`);\n        const txs = await client.savings.getTransactions(orgId, memberId, 1, 5, '', livretA.id);\n        txs.forEach(t =\u003e console.log(`${t.date} : ${t.amount}€ - ${t.description}`));\n    }\n}\n\nmain().catch(console.error);\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finventor2007%2Ffinary-community","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finventor2007%2Ffinary-community","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finventor2007%2Ffinary-community/lists"}