@checkoutpage/sdk 0.1.31 → 0.1.32

package/README.md

@@ -241,6 +241,67 @@ const pageBookings = await checkoutpage.bookings.list({
 });
 ```
 
+#### Create a booking
+
+`bookings.create` issues a real booking without collecting card payment: tickets
+are issued, the customer gets a confirmation email with the ticket PDF, and
+booking webhooks fire. Field values are addressed by `fieldId`, and every field
+the event marks as required must be supplied.
+
+```typescript
+const { data: booking } = await checkoutpage.bookings.create({
+  eventId: '67fcbdac6a91c25ef2d3534a',
+  tickets: { '65f4a1c2e4a9f3d2b1c0a9e8': 2 },
+  fields: [
+    { fieldId: '507f1f77bcf86cd799439030', value: 'ada@example.com' },
+    { fieldId: '507f1f77bcf86cd799439031', value: 'Ada Lovelace' },
+  ],
+  paymentOption: { manualType: 'invoice' },
+});
+
+console.log(booking.status); // 'unpaid'
+console.log(booking.amountDue); // 5000, settled outside checkout
+```
+
+#### Create a complimentary booking
+
+There are two ways to settle a booking, and exactly one of them is required.
+Pass `paymentOption`, as above, and the booking is recorded as `unpaid` with the
+amount as its balance due, settled outside checkout. Pass `complimentary: true`
+instead and the tickets are issued at no charge: the booking is recorded as
+`paid` with `amount`, `amountPaid` and `amountDue` of 0 and
+`isComplimentary: true`, while the ticket lines keep their face value and
+`complimentaryDiscountAmount` records what they would have cost. `complimentary`
+cannot be combined with `paymentOption` or `couponId`.
+
+```typescript
+const { data: booking } = await checkoutpage.bookings.create({
+  eventId: '67fcbdac6a91c25ef2d3534a',
+  tickets: { '65f4a1c2e4a9f3d2b1c0a9e8': 2 },
+  fields: [
+    { fieldId: '507f1f77bcf86cd799439030', value: 'ada@example.com' },
+    { fieldId: '507f1f77bcf86cd799439031', value: 'Ada Lovelace' },
+  ],
+  complimentary: true,
+});
+
+console.log(booking.status); // 'paid'
+console.log(booking.amount); // 0
+console.log(booking.complimentaryDiscountAmount); // 5000 (2 x 2500 face value)
+```
+
+#### Filter complimentary bookings
+
+```typescript
+const complimentary = await checkoutpage.bookings.list({
+  isComplimentary: 'true',
+});
+
+const paidFor = await checkoutpage.bookings.list({
+  isComplimentary: 'false',
+});
+```
+
 ### Products
 
 #### Get a product
@@ -249,6 +310,15 @@ const pageBookings = await checkoutpage.bookings.list({
 const product = await checkoutpage.products.get('product_id');
 ```
 
+#### List products
+
+```typescript
+const products = await checkoutpage.products.list({
+  search: 'shirt',
+  limit: 20,
+});
+```
+
 #### Update a product
 
 ```typescript
@@ -327,6 +397,69 @@ const result = await checkoutpage.files.upload({
 console.log('File uploaded:', result.data.id);
 ```
 
+### Themes
+
+A theme is a page design you can reuse across checkout pages, events and forms. `list()` returns
+your own themes (`scope: 'seller'`) and the built-in ones (`scope: 'global'`), which are read-only.
+
+#### List themes
+
+```typescript
+const { data: themes, has_more } = await checkoutpage.themes.list();
+
+const builtIn = await checkoutpage.themes.list({ scope: 'global' });
+```
+
+#### Create a theme
+
+```typescript
+const { data: theme } = await checkoutpage.themes.create({
+  name: 'Brand',
+  // Optional: start from a copy of a built-in theme or one of yours
+  baseThemeId: builtIn.data[0].id,
+  variables: { tokens: { colorPrimary: { light: '#4f46e5' } } },
+});
+```
+
+`variables` takes the same shape as a page's `themeOverrides`. A copy of a built-in theme does not
+follow your store's brand colour, so set `tokens.colorPrimary` if you want it. A name another of
+your themes already uses is rejected with a `ConflictError`.
+
+#### Get and update a theme
+
+```typescript
+const { data: theme } = await checkoutpage.themes.get(themeId);
+
+const { data: updated } = await checkoutpage.themes.update(themeId, {
+  name: 'Brand v2',
+  variables: { tokens: { colorPrimary: { light: '#0f766e' }, radius: null } },
+});
+```
+
+Every page that uses the theme changes too. Keys you leave out keep their value, and `null` resets a
+property, or everything under a key. Built-in themes can't be changed: copy one with `baseThemeId`.
+
+#### Use a theme on a page
+
+```typescript
+await checkoutpage.checkoutPages.update(pageId, { themeId: theme.id });
+```
+
+`events` and `forms` take `themeId` on `create` and `update` too, and page responses include it.
+Changing a page's theme replaces the page's own theme settings, including ones set in the
+dashboard such as custom CSS, so the page looks like the theme. `themeOverrides` sent in the same
+request apply on top, and the page's locale is kept.
+
+#### Delete a theme
+
+```typescript
+const { data: deleted } = await checkoutpage.themes.delete(themeId);
+```
+
+A theme that any of your pages uses, archived ones included, or that is your store's default theme,
+can't be deleted and throws a `ConflictError`. Move those pages to another theme with `themeId`
+first.
+
 ### Webhooks
 
 #### List webhook endpoints
@@ -362,8 +495,36 @@ saveSecret(webhook.secret);
 > and a URL already registered on the account is rejected with a `ConflictError`.
 
 > The create response is the **only** place the signing `secret` is ever returned.
-> It is not included in `list()` responses and cannot be retrieved later — store it
-> when you create the endpoint. Omit `secret` to have one generated for you.
+> It is not included in `list()` or `get()` responses and cannot be retrieved later, so store
+> it when you create the endpoint. Omit `secret` to have one generated for you.
+
+#### Get a webhook endpoint
+
+```typescript
+const { data: webhook } = await checkoutpage.webhooks.get(webhookId);
+
+console.log(webhook.status, webhook.deliveryCount, webhook.lastFailureAt);
+```
+
+The signing `secret` is not included.
+
+#### Update a webhook endpoint
+
+```typescript
+const { data: updated } = await checkoutpage.webhooks.update(webhookId, {
+  url: 'https://example.com/hooks/checkoutpage-v2',
+  events: ['payment.paid', 'checkout_page.updated', 'product.updated'],
+});
+
+// Pause deliveries without deleting the endpoint, then resume them
+await checkoutpage.webhooks.update(webhookId, { status: 'inactive' });
+await checkoutpage.webhooks.update(webhookId, { status: 'active' });
+```
+
+Only the fields you send change. `events` and `customHeaders` replace the existing values rather
+than merging with them. A new `url` must use https and must not already be registered on another of
+your webhooks (`ValidationError` / `ConflictError`). The signing secret cannot be changed through
+the API.
 
 #### Delete a webhook endpoint
 
@@ -373,6 +534,39 @@ const { data: deleted } = await checkoutpage.webhooks.delete(webhook.id);
 
 Deliveries stop immediately and the endpoint no longer appears in `list()`.
 
+### Test mode
+
+Switch a checkout page, event or form into test mode with `testmode: true`. While it is on, every
+purchase on that page is a test purchase: no money is taken, the buyer gets the product for free,
+and the records are created with `livemode: false`.
+
+```typescript
+await checkoutpage.checkoutPages.update(pageId, { testmode: true });
+
+const { data: pagesInTestMode } = await checkoutpage.checkoutPages.list({ testmode: true });
+
+// Turn it off to take real payments again
+await checkoutpage.checkoutPages.update(pageId, { testmode: false });
+```
+
+`events` and `forms` take the same field on `create`, `update` and `list`. Page responses carry
+`testmode` and `testmodeEnabledAt` (when test mode was switched on, `null` while it is off).
+
+#### Read test records
+
+Pass `livemode: false` to read test records from payments, bookings, subscriptions, subscription
+payments, invoices, submissions and tickets:
+
+```typescript
+const { data: testPayments } = await checkoutpage.payments.list({ pageId, livemode: false });
+const { data: testPayment } = await checkoutpage.payments.get(paymentId, { livemode: false });
+const pdf = await checkoutpage.bookings.downloadTicketPdf(bookingId, { livemode: false });
+```
+
+Without `livemode`, reads return records in the mode of your API key. A live key (`sk_live_`)
+reads live data by default and test data with `livemode: false`. A test key (`sk_test_`) only
+reads test data: `livemode: true` with a test key throws an `AuthenticationError` (403).
+
 ## Error Handling
 
 The SDK provides typed error classes for different error scenarios: