pocketsflow 1.0.1 → 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

package/dist/index.d.mts

@@ -281,6 +281,273 @@ interface Subscription {
 interface ListSubscriptionsParams extends PaginationParams, DateRangeParams {
     status?: 'active' | 'canceled' | 'paused';
 }
+/** A subscription OFFER — a recurring product you sell. */
+interface SubscriptionOffer {
+    _id: string;
+    userId: string;
+    name: string;
+    description?: string;
+    price: number;
+    currency?: string;
+    frequency: 'weekly' | 'monthly' | 'yearly';
+    published?: boolean;
+    slug?: string;
+    thumbnail?: string;
+    testMode: boolean;
+    createdAt: string;
+    updatedAt?: string;
+}
+/** Whop-sourced live membership status. */
+type SubscriberStatus = 'incomplete' | 'incomplete_expired' | 'trialing' | 'active' | 'past_due' | 'canceled' | 'unpaid' | 'succeeded' | 'refunded' | 'paused';
+/** A subscriber — a buyer's membership in one of your subscription offers. */
+interface Subscriber {
+    _id: string;
+    buyerEmail: string;
+    /** Native portal link. The id pair is the capability — no login required. */
+    portalUrl?: string;
+    status: SubscriberStatus;
+    active: boolean;
+    /** The Whop PLAN id for this subscriber */
+    whopSubscriptionId?: string;
+    /** The Whop MEMBERSHIP id — drives the native portal cancel/resume actions */
+    whopMembershipId?: string;
+    cancelAtPeriodEnd?: boolean;
+    subscriptionId: string;
+    firstName?: string;
+    lastName?: string;
+    country?: string;
+    createdAt: string;
+    /** The joined subscription offer */
+    subscription?: {
+        _id: string;
+        name: string;
+        price: number;
+        frequency: 'weekly' | 'monthly' | 'yearly';
+    } | null;
+}
+interface ListSubscribersParams extends PaginationParams {
+    status?: SubscriberStatus;
+    buyerEmail?: string;
+    /** Alias for buyerEmail */
+    email?: string;
+    /** Filter by subscription offer id */
+    subscriptionId?: string;
+}
+interface SubscribersResponse {
+    subscribers: Subscriber[];
+    pagination: {
+        totalCount: number;
+        totalPages: number;
+        currentPage: number;
+        pageSize: number;
+        hasMore: boolean;
+    };
+}
+interface SubscriberDetail {
+    subscriber: Subscriber;
+    /** The subscription offer */
+    subscription: SubscriptionOffer | null;
+    /** The buyer's customer record */
+    customer: Customer | null;
+    status: SubscriberStatus;
+    /** Every subscription payment (initial + renewals) for this subscriber */
+    payments: Payment[];
+    /** Only present when `live: true` — null if the live lookup failed */
+    whopMembership?: Record<string, any> | null;
+}
+/** Native subscriber portal payload (no authentication required). */
+interface SubscriberPortalData {
+    subscription?: SubscriptionOffer | null;
+    subscriber?: Subscriber | null;
+    payments?: Payment[];
+    [key: string]: any;
+}
+/**
+ * A single payment (a `Sale`). Covers BOTH one-time product purchases
+ * (`isSubscription: false`) and subscription payments — the initial charge and
+ * every renewal (`isSubscription: true`).
+ */
+interface Payment {
+    _id: string;
+    isSubscription: boolean;
+    /** Subscription payments only: `initial` activates the membership, `renewal` after */
+    billingReason?: 'initial' | 'renewal';
+    /** Charged amount (after tax), in the payment currency */
+    amount: number;
+    grossAmount?: number;
+    amountBeforeTax?: number;
+    taxAmount?: number;
+    currency: string;
+    buyerEmail: string;
+    firstName?: string;
+    lastName?: string;
+    isRefunded: boolean;
+    isDisputed: boolean;
+    /** Empty on subscription payments — use `subscriptionId` instead */
+    productId?: string;
+    /** Empty on one-time product purchases */
+    subscriptionId?: string;
+    whopPaymentId?: string;
+    whopPlanId?: string;
+    whopMembershipId?: string;
+    createdAt: string;
+}
+interface ListPaymentsParams extends PaginationParams, DateRangeParams {
+    /** `one_time`, `subscription`, or `all` (default) */
+    type?: 'one_time' | 'subscription' | 'all';
+    productId?: string;
+    /** Filter by subscription offer id */
+    subscriptionId?: string;
+}
+interface PaymentsResponse {
+    payments: Payment[];
+    pagination: {
+        totalCount: number;
+        totalPages: number;
+        currentPage: number;
+        pageSize: number;
+        hasMore: boolean;
+    };
+}
+interface PaymentDetail {
+    payment: Payment & {
+        /** Net to the seller (amountBeforeTax − affiliateCut − stripeFee) */
+        net?: number;
+        /** Processor fee (Stripe or PayPal) */
+        fee?: number;
+        /** The raw stored Whop payment payload captured on the webhook */
+        metadata?: Record<string, any>;
+    };
+    /** One-time purchases only; null for subscription payments */
+    product: Product | null;
+    /** Subscription payments only; null for one-time purchases */
+    subscription: SubscriptionOffer | null;
+    customer: Customer | null;
+    whop?: Record<string, any>;
+    /** Only present when `live: true` — null if the live lookup failed */
+    whopLive?: Record<string, any> | null;
+}
+interface CreatorPageLink {
+    title?: string;
+    url?: string;
+    order?: number;
+    [key: string]: any;
+}
+interface CreatorPage {
+    _id: string;
+    userId: string;
+    creatorName?: string;
+    creatorBio?: string;
+    username?: string;
+    socialLinks?: CreatorPageLink[];
+    regularLinks?: CreatorPageLink[];
+    theme?: string;
+    themeV2?: Record<string, any>;
+    gaMeasurementId?: string;
+    subscriberForm?: Record<string, any>;
+    bookingEnabled?: boolean;
+    bookingButtonLabel?: string;
+    template?: string;
+    createdAt: string;
+    updatedAt?: string;
+}
+interface CreateCreatorPageParams {
+    creatorName?: string;
+    creatorBio?: string;
+    username?: string;
+    socialLinks?: CreatorPageLink[];
+    regularLinks?: CreatorPageLink[];
+    theme?: string;
+    themeV2?: Record<string, any>;
+    gaMeasurementId?: string;
+    subscriberForm?: Record<string, any>;
+    bookingEnabled?: boolean;
+    bookingButtonLabel?: string;
+    template?: string;
+}
+type UpdateCreatorPageParams = CreateCreatorPageParams;
+interface UploadImageResponse {
+    imageUrl: string;
+}
+type NewsletterPostStatus = 'draft' | 'scheduled' | 'sending' | 'sent' | 'failed' | 'automation';
+interface NewsletterPost {
+    _id: string;
+    creatorId: string;
+    name: string;
+    subject?: string;
+    preview?: string;
+    fromName?: string;
+    fromEmail: string;
+    replyToEmail?: string;
+    contentHtml?: string;
+    contentJson?: any;
+    status: NewsletterPostStatus;
+    scheduledAt?: string;
+    scheduledTimezone?: string;
+    sentAt?: string;
+    sendToAll?: boolean;
+    tags?: string[];
+    subscriberIds?: string[];
+    source?: 'dashboard' | 'api';
+    createdAt: string;
+    updatedAt: string;
+}
+interface CreateNewsletterPostParams {
+    /** Internal post name (required) */
+    name: string;
+    /** Required before the post can leave `draft` */
+    subject?: string;
+    /** Required before the post can leave `draft` */
+    preview?: string;
+    /** Required before the post can leave `draft` */
+    fromName?: string;
+    /** Defaults to your configured sender */
+    fromEmail?: string;
+    replyToEmail?: string;
+    /** Required before the post can leave `draft` */
+    contentHtml?: string;
+    contentJson?: any;
+    status?: NewsletterPostStatus;
+    scheduledAt?: string;
+    scheduledTimezone?: string;
+    sendToAll?: boolean;
+    tags?: string[];
+    subscriberIds?: string[];
+}
+type UpdateNewsletterPostParams = Partial<CreateNewsletterPostParams>;
+interface SendNewsletterPostResponse {
+    message: string;
+    post: NewsletterPost;
+}
+interface SendEmailParams {
+    /** Recipient(s) — 1 to 100 addresses */
+    to: string | string[];
+    subject: string;
+    /** Required unless `text` is provided */
+    html?: string;
+    /** Used to generate `html` when `html` is omitted */
+    text?: string;
+    fromName?: string;
+    replyTo?: string;
+    preview?: string;
+}
+interface SendEmailResponse {
+    /** The id of the post created for this send */
+    id: string;
+    /** Recipients the send was accepted for */
+    accepted: string[];
+    status: 'sent';
+}
+interface NewsletterSubscriber {
+    _id: string;
+    userId: string;
+    email: string;
+    name?: string;
+    status: 'active' | 'unsubscribed';
+    tags?: string[];
+    createdAt: string;
+    updatedAt: string;
+}
 interface Webhook {
     _id: string;
     userId: string;
@@ -380,6 +647,12 @@ declare class Pocketsflow {
     discounts: DiscountsResource;
     upsells: UpsellsResource;
     subscriptions: SubscriptionsResource;
+    subscriptionOffers: SubscriptionOffersResource;
+    subscribers: SubscribersResource;
+    payments: PaymentsResource;
+    creatorPages: CreatorPagesResource;
+    images: ImagesResource;
+    newsletters: NewslettersResource;
     webhooks: WebhooksResource;
     users: UsersResource;
     checkout: CheckoutResource;
@@ -453,6 +726,10 @@ declare class DiscountsResource {
     delete(id: string): Promise<{
         message: string;
     }>;
+    /** Validate a discount code against a product and get the resulting price */
+    apply(discountCode: string, productId: string): Promise<any>;
+    /** Check whether a product has any discounts */
+    checkProduct(productId: string): Promise<any>;
 }
 declare class UpsellsResource {
     private client;
@@ -470,6 +747,14 @@ declare class UpsellsResource {
         message: string;
     }>;
 }
+/**
+ * Legacy subscriber access via the Orders endpoints, kept for v1 compatibility.
+ *
+ * Prefer `subscribers` (buyers) and `subscriptionOffers` (the recurring
+ * products you sell) — they cover pause/resume and filtering, which these do
+ * not. Note `cancel`/`refund` here key off the Stripe subscription id, whereas
+ * `subscribers.cancel` accepts the subscriber `_id` or Whop membership id.
+ */
 declare class SubscriptionsResource {
     private client;
     constructor(client: Pocketsflow);
@@ -486,6 +771,156 @@ declare class SubscriptionsResource {
         message: string;
     }>;
 }
+/**
+ * Your subscription OFFERS — the recurring products you sell.
+ * To work with your buyers instead, use `subscribers`.
+ */
+declare class SubscriptionOffersResource {
+    private client;
+    constructor(client: Pocketsflow);
+    /** List all subscription offers */
+    list(): Promise<SubscriptionOffer[]>;
+    /** Get a subscription offer by ID */
+    get(id: string): Promise<SubscriptionOffer>;
+}
+/**
+ * Your subscribers — buyers with a membership in one of your subscription
+ * offers. `id` accepts either the subscriber's `_id` or its Whop membership id.
+ */
+declare class SubscribersResource {
+    private client;
+    constructor(client: Pocketsflow);
+    /** List subscribers */
+    list(params?: ListSubscribersParams): Promise<SubscribersResponse>;
+    /**
+     * Get a subscriber with its full payment history.
+     * Pass `live` to also fetch the authoritative membership from Whop; the
+     * lookup degrades gracefully and never fails the request.
+     */
+    get(id: string, options?: {
+        live?: boolean;
+    }): Promise<SubscriberDetail>;
+    /** Cancel a subscriber's subscription */
+    cancel(id: string): Promise<{
+        success: boolean;
+        message?: string;
+    }>;
+    /** Pause a subscriber's subscription */
+    pause(id: string): Promise<{
+        success: boolean;
+        message?: string;
+    }>;
+    /** Resume a paused subscription */
+    resume(id: string): Promise<{
+        success: boolean;
+        message?: string;
+    }>;
+    /**
+     * Read the native subscriber portal payload. The `subscriptionId` +
+     * `subscriberId` pair is itself the capability — these portal endpoints are
+     * unauthenticated, so the API key is not required to call them.
+     */
+    portal(subscriptionId: string, subscriberId: string): Promise<SubscriberPortalData>;
+    /** Cancel a membership through the native portal */
+    portalCancel(subscriberId: string): Promise<{
+        success?: boolean;
+        message?: string;
+    }>;
+    /** Resume a pending cancellation through the native portal */
+    portalResume(subscriberId: string): Promise<{
+        success?: boolean;
+        message?: string;
+    }>;
+}
+/**
+ * The unified payment ledger — one-time purchases AND subscription payments
+ * (the initial charge plus every renewal).
+ */
+declare class PaymentsResource {
+    private client;
+    constructor(client: Pocketsflow);
+    /** List payments */
+    list(params?: ListPaymentsParams): Promise<PaymentsResponse>;
+    /**
+     * Get a payment by ID. Pass `live` to also fetch the authoritative payment
+     * from Whop; the lookup degrades gracefully and never fails the request.
+     */
+    get(id: string, options?: {
+        live?: boolean;
+    }): Promise<PaymentDetail>;
+}
+/** Your Link in Bio page. */
+declare class CreatorPagesResource {
+    private client;
+    constructor(client: Pocketsflow);
+    /** Get your Link in Bio page */
+    get(): Promise<CreatorPage>;
+    /** Create your Link in Bio page. Fails if one already exists — use `update`. */
+    create(params: CreateCreatorPageParams): Promise<CreatorPage>;
+    /** Update your Link in Bio page (partial) */
+    update(params: UpdateCreatorPageParams): Promise<CreatorPage>;
+    /** Delete your Link in Bio page */
+    delete(): Promise<{
+        message: string;
+    }>;
+    /** Check whether a username is available */
+    checkUsername(username: string): Promise<any>;
+    /** Set your Link in Bio username */
+    updateUsername(username: string): Promise<CreatorPage>;
+}
+/** Image uploads. */
+declare class ImagesResource {
+    private client;
+    constructor(client: Pocketsflow);
+    /**
+     * Upload an image and get back its hosted URL.
+     *
+     * `file` accepts anything FormData can hold — a Blob/File, or a Buffer in
+     * Node 18+. `filename` is used when the value carries no name of its own.
+     */
+    upload(file: Blob | Uint8Array | ArrayBuffer, filename?: string): Promise<UploadImageResponse>;
+}
+/** Newsletter posts and subscribers. */
+declare class NewslettersResource {
+    private client;
+    posts: NewsletterPostsResource;
+    subscribers: NewsletterSubscribersResource;
+    constructor(client: Pocketsflow);
+    /**
+     * Send a one-off email to up to 100 recipients.
+     * Requires a verified sender email. Either `html` or `text` must be given.
+     */
+    send(params: SendEmailParams): Promise<SendEmailResponse>;
+}
+declare class NewsletterPostsResource {
+    private client;
+    constructor(client: Pocketsflow);
+    /** List all posts, newest first */
+    list(): Promise<NewsletterPost[]>;
+    /** Get a post by ID */
+    get(id: string): Promise<NewsletterPost>;
+    /**
+     * Create a post. Leaving `draft` requires `subject`, `preview`, `fromName`
+     * and `contentHtml` to be set.
+     */
+    create(params: CreateNewsletterPostParams): Promise<NewsletterPost>;
+    /** Update a post. Posts that have already been sent cannot be edited. */
+    update(id: string, params: UpdateNewsletterPostParams): Promise<NewsletterPost>;
+    /** Delete a post */
+    delete(id: string): Promise<NewsletterPost>;
+    /** Queue a post for sending to its subscribers */
+    send(id: string): Promise<SendNewsletterPostResponse>;
+}
+declare class NewsletterSubscribersResource {
+    private client;
+    constructor(client: Pocketsflow);
+    /** List all subscribers, newest first */
+    list(): Promise<NewsletterSubscriber[]>;
+    /** Get a subscriber by ID */
+    get(id: string): Promise<NewsletterSubscriber>;
+    /** Remove a subscriber */
+    delete(id: string): Promise<NewsletterSubscriber>;
+}
 declare class WebhooksResource {
     private client;
     constructor(client: Pocketsflow);
@@ -531,4 +966,4 @@ declare class RefundsResource {
     create(params: CreateRefundParams): Promise<Refund>;
 }
 
-export { type ApiError, type CheckoutSession, type CreateCheckoutParams, type CreateDiscountParams, type CreateProductParams, type CreateRefundParams, type CreateUpsellParams, type CreateVariantParams, type CreateWebhookParams, type Customer, type DateRangeParams, type Discount, type ListCustomersParams, type ListOrdersParams, type ListReviewsParams, type ListSubscriptionsParams, type Order, type OrdersResponse, type PaginatedResponse, type PaginationParams, Pocketsflow, type PocketsflowConfig, PocketsflowError, type Product, type ProductFile, type ProductVariant, type Refund, type Review, type Subscription, type UpdateDiscountParams, type UpdateProductParams, type UpdateUpsellParams, type UpdateUserParams, type UpdateWebhookParams, type Upsell, type UpsellsResponse, type User, type Webhook, type WebhookEvent };
+export { type ApiError, type CheckoutSession, type CreateCheckoutParams, type CreateCreatorPageParams, type CreateDiscountParams, type CreateNewsletterPostParams, type CreateProductParams, type CreateRefundParams, type CreateUpsellParams, type CreateVariantParams, type CreateWebhookParams, type CreatorPage, type CreatorPageLink, type Customer, type DateRangeParams, type Discount, type ListCustomersParams, type ListOrdersParams, type ListPaymentsParams, type ListReviewsParams, type ListSubscribersParams, type ListSubscriptionsParams, type NewsletterPost, type NewsletterPostStatus, type NewsletterSubscriber, type Order, type OrdersResponse, type PaginatedResponse, type PaginationParams, type Payment, type PaymentDetail, type PaymentsResponse, Pocketsflow, type PocketsflowConfig, PocketsflowError, type Product, type ProductFile, type ProductVariant, type Refund, type Review, type SendEmailParams, type SendEmailResponse, type SendNewsletterPostResponse, type Subscriber, type SubscriberDetail, type SubscriberPortalData, type SubscriberStatus, type SubscribersResponse, type Subscription, type SubscriptionOffer, type UpdateCreatorPageParams, type UpdateDiscountParams, type UpdateNewsletterPostParams, type UpdateProductParams, type UpdateUpsellParams, type UpdateUserParams, type UpdateWebhookParams, type UploadImageResponse, type Upsell, type UpsellsResponse, type User, type Webhook, type WebhookEvent };