@mwam/sdk 0.0.0-stage → 0.4.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 +191 -2
- package/dist/index.d.ts +2351 -0
- package/dist/index.js +873 -0
- package/package.json +42 -3
package/README.md
CHANGED
|
@@ -1,3 +1,192 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @mwam/sdk
|
|
2
2
|
|
|
3
|
-
|
|
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 **Monastery settings → Payments**; 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. Answers `{ status, seats }` and no token (since 0.4.0): the person's link goes to them by email, and an address that had already booked is answered as a newcomer would be |
|
|
178
|
+
| `signUp(eventSlug, who, { visitor? })` | For an event whose `signUp` is `ALL_DATES` (a weekly class): one sign-up for every date it has and any added later. Answers `{ status }`, CONFIRMED or WAITLISTED, with the same rules as `register`; booking one of its dates with `register` is refused. The person leaves from their own page, which the email links to |
|
|
179
|
+
| `register(sessionId, { name, email, seats?, card, amountCents }, { visitor? })` | For a date whose event's `pricing` is `DONATION` (each place gives at least `priceCents`): `card` is the card box's `{ sourceId, verificationToken? }`, the box started with `giving().card`. The card is held, the place taken, then the money taken; a full date throws `conflict` with nothing taken, a refused card throws `declined` with a message for the person. The confirmation email is the receipt |
|
|
180
|
+
| `booking(token)` · `cancelBooking(token)` | One booking, by the token from its email |
|
|
181
|
+
| `giving()` | Whether a gift can be taken now, in what currency, and what to start Square's card box with |
|
|
182
|
+
| `give(gift, { visitor? })` | Starts a gift; answers with the payment page |
|
|
183
|
+
| `giveByCard(gift, { visitor? })` | Takes a gift on your own page, with the card box's token |
|
|
184
|
+
| `giveMonthly(gift, { visitor? })` | Starts a monthly gift on your own page; the donor is emailed a link to stop it |
|
|
185
|
+
| `monthlyGift(token)` · `stopMonthlyGift(token)` | The donor's own page for their monthly gift, at `/give/monthly/{token}` on your site |
|
|
186
|
+
| `eventJsonLd(session, event, { url })` | `schema.org/Event` JSON-LD for one date |
|
|
187
|
+
|
|
188
|
+
Failures throw `MwamError`, with a `code` (`not_found`, `unreachable`, `unexpected_shape`,
|
|
189
|
+
or the API's own) and, where there was one, the HTTP `status`. A refusal the API wrote a
|
|
190
|
+
sentence for keeps that sentence as its `message`, ready to show the visitor.
|
|
191
|
+
|
|
192
|
+
Requires Node 18 or later, or any runtime with `fetch`.
|