Pennylane API Client
    Preparing search index...

    Pennylane API Client

    pennylane-api

    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étrocompatible
    • minor pour une nouvelle fonctionnalité rétrocompatible
    • major pour une rupture de compatibilité

    Le workflow GitHub Actions fonctionne comme suit :

    1. Une PR fonctionnelle contient le code et un fichier .changeset/*.md.
    2. Le job validate s'exécute d'abord et vérifie aussi la génération TypeDoc (lint, typecheck, build, docs, tests).
    3. Le job release ne s'exécute qu'apres validate et uniquement sur main.
    4. Si validate echoue, release est automatiquement ignore.
    5. Sur main, release ouvre ou met a jour la PR chore(release): version package puis publie sur GitHub Packages apres fusion.
    6. Quand Changesets publie effectivement une nouvelle version, le job 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 :

    • lint/format check via Biome
    • typecheck TypeScript
    • build
    • génération TypeDoc
    • tests Vitest

    Un workflow est fourni :

    • .github/workflows/ci.yml pour la validation continue, la release et le déclenchement du build docs sur Cloudflare

    Le 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 :

    • les règles TypeScript/Effect du projet
    • les hooks Husky et Biome
    • l'ajout d'un changeset quand la publication du package doit évoluer