pennylane-api

Client TypeScript strict pour l'API Pennylane, construit avec Effect et publié en package privé sur GitHub Packages.

Installation

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}
Copy

Puis installez le package :

pnpm add @shopy-stock/pennylane-api effect @effect/platform @effect/platform-node
Copy

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.

Utilisation rapide

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);
Copy

Exemple products

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);
Copy

Développement local

pnpm install
pnpm check
pnpm typecheck
pnpm build
pnpm run docs
pnpm test --run
Copy

Versioning

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
Copy

Choisissez le type de version :

• patch pour une correction rétrocompatible
• minor pour une nouvelle fonctionnalité rétrocompatible
• major pour une rupture de compatibilité

Pipeline de release

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

GitHub Actions

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.

Contribution

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