@mwam/sdk 0.0.0-stage → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,3 +1,190 @@
1
- # Temporary Holding Version
1
+ # @mwam/sdk
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ The client a monastery's own website uses to read its blog, events, series and galleries
4
+ from mwam-apps, and to book people in and take gifts through it.
5
+
6
+ Every answer is checked against the API's own schemas before you see it, so a change in the
7
+ API reaches you as one `MwamError` naming the field, not as `undefined` inside a template.
8
+
9
+ ```sh
10
+ npm install @mwam/sdk
11
+ ```
12
+
13
+ ## Use it from your server
14
+
15
+ Call it from server code: `getStaticProps`, `getServerSideProps`, an API route, a server
16
+ component. The API answers no browser but its own app's, and a website key must never reach a
17
+ browser.
18
+
19
+ ```js
20
+ import { createClient } from "@mwam/sdk";
21
+
22
+ const mwam = createClient({
23
+ apiKey: process.env.MWAM_SITE_KEY, // required, and the only setting a site needs
24
+ revalidate: 300, // Next.js: reuse answers for five minutes
25
+ });
26
+
27
+ const { posts } = await mwam.listPosts(); // the blog's newest 50, each with its cover and category
28
+ const post = await mwam.getPost("kathina"); // post.body.html is ready to render
29
+ const sessions = await mwam.listSessions(); // the dates still to come, soonest first
30
+ const event = await mwam.getEvent("monthly-sit");
31
+ const galleries = await mwam.listGalleries();
32
+ ```
33
+
34
+ The key says which monastery it is for — an Admin makes it for one — so the client asks the
35
+ API whose key it is on its first call (`GET /v1/site`) and remembers the answer. Two options
36
+ skip a default: `tenant`, the monastery's slug, to save that one question, and `baseUrl` to
37
+ talk to another copy of the API than `https://apps-api.meditatewithamonk.org` (a local one,
38
+ say). `mwam.site()` answers `{ slug, name }` if the site wants its monastery's name.
39
+
40
+ ## The blog
41
+
42
+ `getPost` answers with the body as HTML unless you ask for more. The API rendered it from a
43
+ closed set of elements, with every text escaped and every link checked, and every picture's
44
+ address is absolute, so it goes into your page as it is (`dangerouslySetInnerHTML` in React).
45
+ It is plain HTML for your own styles to dress; pictures are `<figure class="mwam-image">`,
46
+ and a pair of pictures is `mwam-before-after`. The author's choices arrive as classes, never
47
+ as inline styles, so your stylesheet decides what each one looks like — and one it does not
48
+ style simply shows at your text's width:
49
+
50
+ | Class | On | The author chose |
51
+ |---|---|---|
52
+ | `mwam-image--small` | `figure` | about a third of your text's width |
53
+ | `mwam-image--medium` | `figure` | about half of it |
54
+ | `mwam-image--wide` | `figure` | a little wider than your text |
55
+ | `mwam-image--full` | `figure` | as wide as your page allows |
56
+ | `mwam-align-center` | `p`, `h2`–`h4` | centred lines |
57
+ | `mwam-align-right` | `p`, `h2`–`h4` | lines set to the right |
58
+
59
+ A picture with none of the four is as wide as your text. Small and medium are caps, not
60
+ widths: a picture smaller than that is never enlarged. The CRM's own copy of these rules,
61
+ which you may borrow, is under "Rendered post bodies" in `apps/crm/app/globals.css`.
62
+
63
+ A post has a `cover` when one was chosen, and `null` when not: `{ url, alt, width, height }`,
64
+ with `url` absolute and `alt` the picture's description (`""` when it has none, which marks it
65
+ decorative). Give the `<img>` its `width` and `height` so the page does not jump as it loads.
66
+
67
+ The list comes a page at a time, by number, with `total` and `pageCount` for a pager. It
68
+ searches the title, summary and body with `q` (best match first; quotes for a phrase, a
69
+ leading minus to leave a word out), and filters by `category` and by date with `from` and
70
+ `to`. The counts are of what was asked for, so a search's pager is right too:
71
+
72
+ ```js
73
+ const page2 = await mwam.listPosts({ page: 2, limit: 12 }); // "Page 2 of 4"
74
+ const found = await mwam.listPosts({ q: "kathina robes" });
75
+ const talks = await mwam.listPosts({ category: "dhamma-talks" });
76
+ const november = await mwam.listPosts({
77
+ from: "2026-11-01T00:00:00-05:00", // give the offset, so the
78
+ to: "2026-12-01T00:00:00-05:00", // month starts where you are
79
+ });
80
+ const categories = await mwam.listCategories(); // [{ slug, name, postCount }]
81
+ ```
82
+
83
+ A post's `category` is `{ slug, name }` or `null`. A post shared from another monastery is in
84
+ none of yours, so it has none on your site.
85
+
86
+ Ask for `format: ["html", "text"]` when you also want the words alone, for a meta description
87
+ or a search index, or `["json"]` for the structured document if you render it yourself.
88
+
89
+ A post another monastery shared with yours carries your monastery's title, summary and
90
+ address for it. When its own monastery asked to be credited it also carries `source`,
91
+ `{ org, author }` (`author` can be null); show the credit when it is there. A draft, a
92
+ withdrawn post and an address that was never used all throw the same `not_found`.
93
+
94
+ ## An event's pictures
95
+
96
+ An event has a `cover` the same shape as a post's, `null` when none was chosen, on every
97
+ answer that describes it: `listSessions()` rows, `getEvent`, and a series' events. Chosen on
98
+ the event's Details tab in the CRM.
99
+
100
+ `getEvent` also carries `galleries`: the published galleries linked to that event in the
101
+ CRM, newest first, each with its `pictures` (`{ url, alt, caption, width, height }`), so a
102
+ page needs no second call. Empty when there are none.
103
+
104
+ ## The website key
105
+
106
+ An Admin makes one in **Monastery settings → Website keys**. It is shown once. Keep it in
107
+ your server's settings (`MWAM_SITE_KEY`) and nowhere else.
108
+
109
+ Every call needs it, reads included: a monastery's posts, events and galleries are read by its
110
+ own website and nobody else, and a key works for its own monastery only. Without one the API
111
+ answers 401 and the client throws.
112
+
113
+ To the API, all your visitors arrive from your server, so they share one rate limit. Pass each
114
+ visitor's own address when booking or giving and they are counted on their own:
115
+
116
+ ```js
117
+ const taken = await mwam.register(sessionId, { name, email }, { visitor: clientIp });
118
+ if (taken.status === "WAITLISTED") {
119
+ // Not an error: they are next in line. Say so.
120
+ }
121
+
122
+ const gift = await mwam.give({ amountCents, email, returnPath: "/give/thanks" }, { visitor: clientIp });
123
+ // Send the donor to gift.url, the payment provider's page.
124
+ ```
125
+
126
+ ### A gift on your own page
127
+
128
+ The donor need not leave your site. `giving()` answers with `card`, what Square's card box is
129
+ started with; the box turns the card into a one-use token in the browser, and your server
130
+ sends that token on. The card number never reaches your server or the API.
131
+
132
+ ```js
133
+ // In the page — Square's own script, from web.squarecdn.com
134
+ // (sandbox.web.squarecdn.com when card.environment is "sandbox"):
135
+ const payments = Square.payments(card.applicationId, card.locationId);
136
+ const box = await payments.card();
137
+ await box.attach("#card");
138
+ const { token } = await box.tokenize();
139
+ // Then post { amountCents, email, sourceId: token } to your own server.
140
+
141
+ // On your server:
142
+ try {
143
+ const gift = await mwam.giveByCard({ amountCents, email, name, sourceId }, { visitor: clientIp });
144
+ // gift.status is "PAID" (settled, receipt sent) or, rarely, "PENDING" (Square settles it).
145
+ } catch (e) {
146
+ if (e instanceof MwamError && e.code === "declined") {
147
+ // e.message is written for the donor: show it, and ask for the card again.
148
+ }
149
+ }
150
+ ```
151
+
152
+ Sending the same token twice, after a timeout say, never pays twice.
153
+
154
+ A **monthly gift** works the same way, when `giving().monthly` is true: ask the card box's
155
+ `verifyBuyer` with intent `STORE`, then `giveMonthly({ amountCents, name, email, sourceId,
156
+ verificationToken })` from your server. Square keeps the card in the monastery's own account
157
+ and charges it each month; each month is receipted. The donor is emailed a private link to
158
+ `/give/monthly/{token}` on your site — a page that shows `monthlyGift(token)` and offers
159
+ `stopMonthlyGift(token)`. Apple Pay shows only on
160
+ an address an Admin has turned it on for, in **Giving**; the address must serve Square's file
161
+ at `/.well-known/apple-developer-merchantid-domain-association`.
162
+
163
+ A missing, wrong or withdrawn key is refused on every call, so a broken key shows up at once. To replace one: make the new key, deploy it, then withdraw the old.
164
+
165
+ ## What it covers
166
+
167
+ | | |
168
+ |---|---|
169
+ | `site()` | The monastery the key belongs to, `{ slug, name }` |
170
+ | `listPosts({ page?, limit?, q?, category?, from?, to? })` | One page of the blog, with `total` and `pageCount` |
171
+ | `listCategories()` | The categories with something published in them, and how many |
172
+ | `getPost(slug, { format? })` | One post; `format` from `html` (the default), `text`, `json` |
173
+ | `listSessions({ from?, limit?, category? })` | The monastery's dates, soonest first |
174
+ | `getEvent(slug)` | One event and every date it has, with its `cover` and the `galleries` linked to it |
175
+ | `listSeries()` · `getSeries(slug)` | Programmes, and the events in each |
176
+ | `listGalleries({ limit? })` · `getGallery(slug)` | Published galleries; every picture has alt text |
177
+ | `register(sessionId, who, { visitor? })` | Takes a place, or a place on the waitlist |
178
+ | `booking(token)` · `cancelBooking(token)` | One booking, by the token from its email |
179
+ | `giving()` | Whether a gift can be taken now, in what currency, and what to start Square's card box with |
180
+ | `give(gift, { visitor? })` | Starts a gift; answers with the payment page |
181
+ | `giveByCard(gift, { visitor? })` | Takes a gift on your own page, with the card box's token |
182
+ | `giveMonthly(gift, { visitor? })` | Starts a monthly gift on your own page; the donor is emailed a link to stop it |
183
+ | `monthlyGift(token)` · `stopMonthlyGift(token)` | The donor's own page for their monthly gift, at `/give/monthly/{token}` on your site |
184
+ | `eventJsonLd(session, event, { url })` | `schema.org/Event` JSON-LD for one date |
185
+
186
+ Failures throw `MwamError`, with a `code` (`not_found`, `unreachable`, `unexpected_shape`,
187
+ or the API's own) and, where there was one, the HTTP `status`. A refusal the API wrote a
188
+ sentence for keeps that sentence as its `message`, ready to show the visitor.
189
+
190
+ Requires Node 18 or later, or any runtime with `fetch`.