pocketsflow 1.0.0 → 1.1.0

package/README.md

@@ -168,6 +168,10 @@ const updated = await pocketsflow.discounts.update('discount_id', {
 
 // Delete a discount
 await pocketsflow.discounts.delete('discount_id');
+
+// Validate a code against a product, and check whether a product has any
+const applied = await pocketsflow.discounts.apply('SAVE20', 'product_id');
+const has = await pocketsflow.discounts.checkProduct('product_id');
 ```
 
 ### Upsells
@@ -200,25 +204,151 @@ const updated = await pocketsflow.upsells.update('upsell_id', {
 await pocketsflow.upsells.delete('upsell_id');
 ```
 
-### Subscriptions
+### Subscription Offers
+
+Your subscription **offers** — the recurring products you sell.
+
+```typescript
+// List all subscription offers
+const offers = await pocketsflow.subscriptionOffers.list();
+
+// Get one offer
+const offer = await pocketsflow.subscriptionOffers.get('offer_id');
+```
+
+### Subscribers
+
+Your **buyers** — people with a membership in one of your offers. `id` accepts
+either the subscriber's `_id` or its Whop membership id.
 
 ```typescript
-// List subscription customers
-const subscriptions = await pocketsflow.subscriptions.list({
+// List subscribers
+const { subscribers, pagination } = await pocketsflow.subscribers.list({
+  status: 'active',
   page: 1,
   pageSize: 20,
 });
 
-// Get a subscription
-const subscription = await pocketsflow.subscriptions.get('subscription_id');
+// Get a subscriber with full payment history
+const detail = await pocketsflow.subscribers.get('subscriber_id');
+console.log(detail.payments); // initial charge + every renewal
 
-// Cancel a subscription
-await pocketsflow.subscriptions.cancel('stripe_subscription_id');
+// Pass `live` to also fetch the authoritative membership from Whop.
+// The lookup degrades gracefully and never fails the request.
+const live = await pocketsflow.subscribers.get('subscriber_id', { live: true });
+
+// Manage a membership
+await pocketsflow.subscribers.cancel('subscriber_id');
+await pocketsflow.subscribers.pause('subscriber_id');
+await pocketsflow.subscribers.resume('subscriber_id');
+```
+
+The native subscriber portal is driven by the `subscriptionId` + `subscriberId`
+pair, which is itself the capability — these endpoints need no API key:
+
+```typescript
+const data = await pocketsflow.subscribers.portal('offer_id', 'subscriber_id');
+await pocketsflow.subscribers.portalCancel('subscriber_id');
+await pocketsflow.subscribers.portalResume('subscriber_id');
+```
+
+### Payments
+
+The unified ledger — one-time purchases **and** subscription payments (the
+initial charge plus every renewal).
+
+```typescript
+// List payments
+const { payments, pagination } = await pocketsflow.payments.list({
+  type: 'subscription', // 'one_time' | 'subscription' | 'all' (default)
+  startDate: '2026-01-01',
+  pageSize: 50,
+});
+
+// Get one payment, with its product or offer, customer, and Whop payload
+const payment = await pocketsflow.payments.get('payment_id');
+```
+
+### Subscriptions (legacy)
 
-// Refund a subscription
+Kept for v1 compatibility. Prefer `subscribers` and `subscriptionOffers` above —
+they cover pause/resume and filtering, which these do not. Note `cancel` and
+`refund` here key off the **Stripe** subscription id.
+
+```typescript
+const subscriptions = await pocketsflow.subscriptions.list({ page: 1 });
+const subscription = await pocketsflow.subscriptions.get('subscription_id');
+await pocketsflow.subscriptions.cancel('stripe_subscription_id');
 await pocketsflow.subscriptions.refund('stripe_subscription_id');
 ```
 
+### Link in Bio
+
+```typescript
+// Get your page
+const page = await pocketsflow.creatorPages.get();
+
+// Create one (fails if you already have a page — use update)
+const created = await pocketsflow.creatorPages.create({
+  creatorName: 'Jane',
+  creatorBio: 'I make things',
+  regularLinks: [{ title: 'My site', url: 'https://example.com', order: 0 }],
+});
+
+// Partial update
+const updated = await pocketsflow.creatorPages.update({ creatorBio: 'Updated' });
+
+// Usernames
+await pocketsflow.creatorPages.checkUsername('jane');
+await pocketsflow.creatorPages.updateUsername('jane');
+
+await pocketsflow.creatorPages.delete();
+```
+
+### Images
+
+```typescript
+import { readFile } from 'node:fs/promises';
+
+const { imageUrl } = await pocketsflow.images.upload(
+  await readFile('./cover.png'),
+  'cover.png'
+);
+```
+
+### Newsletters
+
+```typescript
+// Send a one-off email to up to 100 recipients (requires a verified sender)
+const result = await pocketsflow.newsletters.send({
+  to: ['a@example.com', 'b@example.com'],
+  subject: 'Hello',
+  html: '<h1>Hi there</h1>',
+});
+console.log(result.id, result.accepted);
+
+// Posts
+const posts = await pocketsflow.newsletters.posts.list();
+const post = await pocketsflow.newsletters.posts.create({
+  name: 'March update',
+  subject: 'What shipped in March',
+  preview: 'New features inside',
+  fromName: 'Jane',
+  contentHtml: '<p>...</p>',
+});
+await pocketsflow.newsletters.posts.update(post._id, { subject: 'Revised' });
+await pocketsflow.newsletters.posts.send(post._id);
+await pocketsflow.newsletters.posts.delete(post._id);
+
+// Subscribers
+const subs = await pocketsflow.newsletters.subscribers.list();
+await pocketsflow.newsletters.subscribers.get('subscriber_id');
+await pocketsflow.newsletters.subscribers.delete('subscriber_id');
+```
+
+A post needs `subject`, `preview`, `fromName` and `contentHtml` before it can
+leave `draft`. Posts that have already been sent cannot be edited.
+
 ### Webhooks
 
 ```typescript