Client TypeScript strict pour l'API Pennylane, construit avec Effect et publié en package privé sur GitHub Packages.
Le package est publié sur GitHub Packages sous le scope de l'organisation.
Ajoutez un .npmrc dans le projet consommateur :
@shopy-stock:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
Puis installez le package :
pnpm add @shopy-stock/pennylane-api effect @effect/platform @effect/platform-node
En local, utilisez un token GitHub ayant accès en lecture aux packages privés de l'organisation.
Pour les autres repositories privés de l'organisation, pensez aussi à autoriser l'accès au package dans les paramètres GitHub Packages du dépôt package si vous voulez consommer le package via GITHUB_TOKEN en CI.
import { NodeHttpClient } from "@effect/platform-node";
import { Effect } from "effect";
import { makeLayer, PennylaneApi } from "@shopy-stock/pennylane-api";
const pennylaneLayer = makeLayer({
apiKey: "VOTRE_CLE_API_PENNYLANE",
});
const program = Effect.gen(function* () {
const response = yield* PennylaneApi.journals.getJournals();
console.log("Journaux récupérés:", response.items);
});
Effect.runPromise(
program.pipe(Effect.provide(pennylaneLayer), Effect.provide(NodeHttpClient.layer)),
).catch(console.error);
import { NodeHttpClient } from "@effect/platform-node";
import { Effect } from "effect";
import { makeLayer, PennylaneApi } from "@shopy-stock/pennylane-api";
const pennylaneLayer = makeLayer({
apiKey: "VOTRE_CLE_API_PENNYLANE",
});
const program = Effect.gen(function* () {
const products = yield* PennylaneApi.products.getProducts({
limit: 20,
sort: "-id",
});
console.log("Produits récupérés:", products.items);
const createdProduct = yield* PennylaneApi.products.createProduct({
label: "Abonnement Premium",
description: "Abonnement mensuel",
price_before_tax: "29.90",
vat_rate: "FR_200",
unit: "month",
currency: "EUR",
reference: "PREMIUM-MONTHLY",
});
const updatedProduct = yield* PennylaneApi.products.updateProduct(createdProduct.id, {
label: "Abonnement Premium Plus",
price_before_tax: "39.90",
});
const product = yield* PennylaneApi.products.getProduct(updatedProduct.id);
console.log("Produit final:", product);
});
Effect.runPromise(
program.pipe(Effect.provide(pennylaneLayer), Effect.provide(NodeHttpClient.layer)),
).catch(console.error);
Dans Pennylane, une transaction est justifiée lorsqu'elle est rapprochée d'une facture. Flux complet : lister les transactions à justifier, envoyer le PDF, importer la facture fournisseur avec ce fichier, puis la rapprocher de la transaction.
import { NodeHttpClient } from "@effect/platform-node";
import { Effect } from "effect";
import { makeLayer, PennylaneApi } from "@shopy-stock/pennylane-api";
import { readFile } from "node:fs/promises";
const pennylaneLayer = makeLayer({
apiKey: "VOTRE_CLE_API_PENNYLANE",
});
const program = Effect.gen(function* () {
// 1. Lister les transactions d'un compte bancaire depuis le 1er septembre
const { items } = yield* PennylaneApi.transactions.getTransactions({
filter: [
{ field: "bank_account_id", operator: "eq", value: "9" },
{ field: "date", operator: "gteq", value: "2026-09-01" },
],
limit: 100,
});
const transaction = items.find((item) => item.attachment_required);
if (transaction === undefined) {
return;
}
// 2. Envoyer le justificatif
const pdf = yield* Effect.promise(() => readFile("./facture.pdf"));
const attachment = yield* PennylaneApi.fileAttachments.uploadFileAttachment({
file: new Blob([pdf], { type: "application/pdf" }),
filename: "facture.pdf",
});
// 3. Trouver le fournisseur (ou le créer avec `suppliers.createSupplier`)
const suppliers = yield* PennylaneApi.suppliers.getSuppliers({
filter: [{ field: "name", operator: "start_with", value: "MY SUPPLIER" }],
});
const supplierId = transaction.supplier?.id ?? suppliers.items[0]?.id;
if (supplierId === undefined) {
return;
}
// 4. Importer la facture fournisseur avec le fichier
// (409 = fichier pas encore prêt : réessayer quelques secondes plus tard)
const invoice = yield* PennylaneApi.supplierInvoices.importSupplierInvoice({
file_attachment_id: attachment.id,
supplier_id: supplierId,
date: "2026-09-28",
deadline: "2026-10-28",
currency_amount_before_tax: "100.00",
currency_amount: "120.00",
currency_tax: "20.00",
invoice_lines: [{ currency_amount: "120.00", currency_tax: "20.00", vat_rate: "FR_200" }],
});
// 5. Rapprocher la facture de la transaction
yield* PennylaneApi.supplierInvoices.matchSupplierInvoiceTransaction(invoice.id, transaction.id);
});
Effect.runPromise(
program.pipe(Effect.provide(pennylaneLayer), Effect.provide(NodeHttpClient.layer)),
).catch(console.error);
Pour un encaissement client, utiliser PennylaneApi.customerInvoices.matchCustomerInvoiceTransaction.
Scopes API requis : transactions:readonly (ou transactions:all), suppliers:readonly
(ou suppliers:all), supplier_invoices:all, customer_invoices:all selon le cas.
pnpm install
pnpm check
pnpm typecheck
pnpm build
pnpm run docs
pnpm test --run
Le projet utilise Changesets pour gérer les versions SemVer du package.
Quand une PR modifie le package publié, il faut créer un changeset :
pnpm changeset
Choisissez le type de version :
patch pour une correction rétrocompatibleminor pour une nouvelle fonctionnalité rétrocompatiblemajor pour une rupture de compatibilitéLe workflow GitHub Actions fonctionne comme suit :
.changeset/*.md.validate s'exécute d'abord et vérifie aussi la génération TypeDoc (lint, typecheck, build, docs, tests).release ne s'exécute qu'apres validate et uniquement sur main.validate echoue, release est automatiquement ignore.main, release ouvre ou met a jour la PR chore(release): version package puis publie sur GitHub Packages apres fusion.trigger-cloudflare-docs déclenche le build Cloudflare Pages via un deploy hook.Le dossier docs/ n'est pas versionné dans Git : la documentation est générée au moment du déploiement Cloudflare.
Le workflow CI exécute systématiquement :
Un workflow est fourni :
.github/workflows/ci.yml pour la validation continue, la release et le déclenchement du build docs sur CloudflareLe workflow de release utilise GITHUB_TOKEN avec les permissions contents: write, pull-requests: write et packages: write.
Le workflow utilise aussi le secret CLOUDFLARE_DOCS_DEPLOY_HOOK pour déclencher le build de la documentation sur Cloudflare Pages après publication.
Les conventions de code et d'architecture sont documentées dans AGENTS.md.
Toute modification destinée à être livrée aux autres projets doit respecter à la fois :