@checkoutpage/sdk 0.1.14 → 0.1.30

package/README.md

@@ -55,6 +55,18 @@ const checkoutpage = createCheckoutPageClient({
 
 ## Usage
 
+### Account
+
+#### Get the account your API key belongs to
+
+```typescript
+const account = await checkoutpage.accounts.get();
+
+console.log(account.name); // 'mystore' — store slug, the default checkout subdomain
+console.log(account.displayName); // 'My Store' — shown to customers
+console.log(account.logo?.url); // store logo, or null when none is set
+```
+
 ### Customers
 
 #### Get a customer
@@ -150,6 +162,36 @@ const previousPage = await checkoutpage.subscriptions.list({
 });
 ```
 
+### Subscription Payments
+
+Per-payment records for subscriptions — one record per Stripe invoice charge. Use this for billing history, refund inspection, and "when was I charged?" questions.
+
+#### List subscription payments
+
+```typescript
+const result = await checkoutpage.subscriptionPayments.list({
+  limit: 10,
+});
+console.log(`Total: ${result.total}, has more: ${result.has_more}`);
+```
+
+#### List payments for a single subscription
+
+```typescript
+const result = await checkoutpage.subscriptionPayments.list({
+  subscriptionId: 'sub_id',
+});
+```
+
+#### Filter failed/unpaid payments
+
+```typescript
+const failed = await checkoutpage.subscriptionPayments.list({
+  paymentStatus: 'failed',
+});
+const unpaid = await checkoutpage.subscriptionPayments.list({ paid: 'false' });
+```
+
 ### Payments
 
 #### List payments
@@ -199,6 +241,138 @@ const pageBookings = await checkoutpage.bookings.list({
 });
 ```
 
+### Products
+
+#### Get a product
+
+```typescript
+const product = await checkoutpage.products.get('product_id');
+```
+
+#### Update a product
+
+```typescript
+const updated = await checkoutpage.products.update('product_id', {
+  title: 'Updated Product Title',
+  description: 'Updated description',
+  price: 5900, // $59.00 in cents
+  stock: 100,
+  hasUnlimitedStock: false,
+});
+```
+
+#### Subscription limits and file access
+
+These settings live on the product, so a product reused across several checkout
+pages behaves consistently everywhere.
+
+```typescript
+await checkoutpage.products.update('product_id', {
+  // Cap each customer to one active subscription for this product
+  limitSubscriptions: {
+    enabled: true,
+    // Also check active subscriptions in Stripe
+    limitSubscriptionsStripe: { enabled: true },
+  },
+  // Let customers keep downloading files after their subscription lapses
+  enableFileAccessForInactiveSubscriptions: true,
+});
+```
+
+Both are also accepted when creating a page, under `productData`:
+
+```typescript
+await checkoutpage.checkoutPages.create({
+  name: 'Membership',
+  productData: {
+    title: 'Membership',
+    price: { amount: 4900, currency: 'usd', recurring: { interval: 'month' } },
+    limitSubscriptions: { enabled: true },
+    enableFileAccessForInactiveSubscriptions: true,
+  },
+});
+```
+
+> The page-level `limitSubscriptions`, `limitSubscriptionsStripe`, and
+> `enableFileAccessForInactiveSubscriptions` fields are **deprecated**. They are
+> still accepted and are applied to the page's product, and page responses still
+> report them by mirroring the product — but new integrations should set them
+> under `productData` or via `products.update()`.
+
+### Files
+
+#### Upload an image
+
+```typescript
+const imageFile = new File([blob], 'product-image.jpg', { type: 'image/jpeg' });
+
+const result = await checkoutpage.files.upload({
+  file: imageFile,
+  purpose: 'image',
+});
+
+console.log('Image uploaded:', result.data.id, result.data.location);
+```
+
+#### Upload a file
+
+```typescript
+const pdfFile = new File([blob], 'ebook.pdf', { type: 'application/pdf' });
+
+const result = await checkoutpage.files.upload({
+  file: pdfFile,
+  purpose: 'file',
+});
+
+console.log('File uploaded:', result.data.id);
+```
+
+### Webhooks
+
+#### List webhook endpoints
+
+```typescript
+const { data: webhooks, has_more } = await checkoutpage.webhooks.list();
+```
+
+#### Filter by event and status
+
+```typescript
+const active = await checkoutpage.webhooks.list({
+  event: 'payment.paid',
+  status: 'active',
+  limit: 25,
+});
+```
+
+#### Create a webhook endpoint
+
+```typescript
+const { data: webhook } = await checkoutpage.webhooks.create({
+  name: 'CRM sync',
+  url: 'https://example.com/hooks/checkoutpage',
+  events: ['payment.paid', 'subscription.created'],
+  customHeaders: { Authorization: 'Bearer receiver-token' },
+});
+
+saveSecret(webhook.secret);
+```
+
+> The `url` must use **https** — an `http` URL is rejected with a `ValidationError`,
+> 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.
+
+#### Delete a webhook endpoint
+
+```typescript
+const { data: deleted } = await checkoutpage.webhooks.delete(webhook.id);
+```
+
+Deliveries stop immediately and the endpoint no longer appears in `list()`.
+
 ## Error Handling
 
 The SDK provides typed error classes for different error scenarios: