@lacagnottedesproches/lcdp-js-lite 1.12.0 → 1.13.0-beta.0

package/README.md

@@ -1,9 +1,69 @@
 [![Test with coverage afina-js-lite 🎉](https://github.com/lacagnottedesproches/afina-js-lite/actions/workflows/test.js.yml/badge.svg)](https://github.com/lacagnottedesproches/afina-js-lite/actions/workflows/test.js.yml)
-
-[![Build and test with coverage afina-js-lite 🎉](https://github.com/lacagnottedesproches/afina-js-lite/actions/workflows/node.js.yml/badge.svg)](https://github.com/lacagnottedesproches/afina-js-lite/actions/workflows/node.js.yml)
+[![npm](https://img.shields.io/npm/v/@lacagnottedesproches/lcdp-js-lite)](https://www.npmjs.com/package/@lacagnottedesproches/lcdp-js-lite)
 
 <div align="center">
-  <h1>La Cagnotte des Proches - Afina JS Lite</h1>
+  <h1>La Cagnotte des Proches — JS SDK</h1>
+  <p>Typed loader for the La Cagnotte des Proches SDK, in the browser and on the server.</p>
+  <p>
+    <a href="https://docs.lacagnottedesproches.fr/lcdpjs/"><strong>Documentation</strong></a> ·
+    <a href="https://docs.lacagnottedesproches.fr/">API reference</a>
+  </p>
 </div>
 
-The SDK JS, that is a wrapper around **afina-sdk**.
+## Install
+
+```bash
+npm install @lacagnottedesproches/lcdp-js-lite @stripe/stripe-js
+```
+
+`@stripe/stripe-js` (>= 3) is a peer dependency.
+
+## Browser: `loadLCDP`
+
+```ts
+import { loadLCDP } from "@lacagnottedesproches/lcdp-js-lite";
+
+const lcdp = await loadLCDP("pk_your_public_key");
+// lcdp is null during server-side rendering
+```
+
+Options:
+
+| Option        | Default                               | Description                                                    |
+| ------------- | ------------------------------------- | -------------------------------------------------------------- |
+| `api_url`     | `https://api.lacagnottedesproches.fr` | API base URL. Never take it from user input.                   |
+| `sdk_version` | —                                     | Pin a specific SDK bundle version.                             |
+| `stripe`      | `true`                                | Set `false` on read-only pages to skip loading Stripe.js.      |
+
+The SDK is loaded once. Calling `loadLCDP` again returns the same instance.
+
+## Server: `requestLCDP`
+
+```ts
+import { requestLCDP } from "@lacagnottedesproches/lcdp-js-lite";
+
+const api = requestLCDP(process.env.LCDP_SECRET_KEY!);
+const account = await api.getAccount(accountId);
+```
+
+- **Server only.** It throws if `window` exists, so your secret key never reaches the browser.
+- Every request has a 30 s timeout.
+- On HTTP errors, the promise rejects with the API error `detail`.
+
+Available methods: `createAccount`, `createPot`, `createAccountAndPot`, `updatePot`, `createPayout`, `getAccount`, `updateAccount`, `updateAccountIdentity`, `updateAccountBank`.
+
+## TypeScript
+
+All types are exported from the package:
+
+```ts
+import type { LCDP, LCDPApi } from "@lacagnottedesproches/lcdp-js-lite";
+```
+
+## Documentation
+
+Full guides and the API reference: **https://docs.lacagnottedesproches.fr/lcdpjs/**
+
+## License
+
+[GPL-3.0-only](./LICENSE)

package/dist/types.d.ts

@@ -177,6 +177,34 @@ export interface PayloadDonation extends DataDonation {
     amount_donation: number;
     amount_tip: number;
 }
+/**
+ * Donor edit of a donation, sent to `updateDonation`. `token` is the edit
+ * token from the link v4 puts in the donation email. Only the fields you set
+ * are changed; `message: null` clears the message.
+ */
+export interface PayloadDonationUpdate {
+    token: string;
+    first_name?: string | undefined;
+    message?: string | null | undefined;
+    stay_anonymous_checked?: boolean | undefined;
+    hide_amount_donation_checked?: boolean | undefined;
+    private_message_checked?: boolean | undefined;
+}
+/**
+ * Current values of a donation for the donor edit form, from `getDonationForEdit`.
+ * `first_name` and `message` are the real values, even for an anonymous
+ * donation or a private message.
+ */
+export interface DonationForEdit {
+    id: UUID;
+    first_name: string | null;
+    message: string | null;
+    stay_anonymous_checked: boolean;
+    hide_amount_donation_checked: boolean;
+    private_message_checked: boolean;
+    pot_id: UUID;
+    pot_name: string;
+}
 export interface DonationResult {
     error?: string;
     status: string | "requires_action";
@@ -246,6 +274,25 @@ export interface StatsPot {
     amount_tips?: number;
     amount_real_tips?: number;
 }
+/**
+ * Public view of a donation in a pot donations list. The API already hides
+ * what the donor chose to hide: names are null when anonymous, the amount
+ * is null when hidden, the message is null when private.
+ */
+export interface PotDonation {
+    id: UUID;
+    date_created_ts: number;
+    amount_donation: number | null;
+    stay_anonymous_checked: boolean;
+    hide_amount_donation_checked: boolean;
+    private_message_checked: boolean;
+    message: string | null;
+    first_name: string | null;
+    last_name: string | null;
+}
+export interface PotDonationsPagination extends Pagination {
+    items: PotDonation[];
+}
 export interface StatsPotsPagination extends Pagination {
     items: StatsPot[];
 }
@@ -303,10 +350,14 @@ export interface LCDP {
     createTokenPersonVerification: (payload: PayloadVerification) => Promise<ExternalTokenObject>;
     createTokenAccountBank(payload: PayloadAccountBank): Promise<ExternalTokenObject>;
     createDonation: (payload: PayloadDonation) => Promise<DonationResult>;
+    /** `getDonationForEdit` and `updateDonation` need SDK 1.7.0 or later. */
+    getDonationForEdit: (token: string) => Promise<DonationForEdit>;
+    updateDonation: (donationId: string, payload: PayloadDonationUpdate) => Promise<void>;
     getAvailableCountries: () => Promise<Country[]>;
     getCategories: () => Promise<Category[]>;
     getPots: (params?: ParamsPagination) => Promise<PotsPagination>;
     getPot: (potId: string) => Promise<Pot>;
+    getPotDonations: (potId: string, params?: ParamsPagination) => Promise<PotDonationsPagination>;
     getStatsDashboard: (ts_start?: number, ts_end?: number) => Promise<StatDashboard>;
     getStatsPots: (ts_start?: number, ts_end?: number, page?: number, per_page?: number) => Promise<StatsPotsPagination>;
     retrieveAssociations: (payload?: PayloadQueryAssociations) => Promise<Associations>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lacagnottedesproches/lcdp-js-lite",
-  "version": "1.12.0",
+  "version": "1.13.0-beta.0",
   "description": "LCDP JS Lite",
   "scripts": {
     "build": "rm -rf dist/ && rollup -c",
@@ -15,7 +15,8 @@
     "test:types": "tsd --files __tests__/types.test-d.ts",
     "test:debug": "node --inspect-brk node_modules/.bin/jest --runInBand",
     "test:update-snapshots": "jest --updateSnapshot",
-    "test:clear-cache": "jest --clearCache"
+    "test:clear-cache": "jest --clearCache",
+    "docs": "typedoc"
   },
   "main": "dist/index.js",
   "module": "dist/index.mjs",