pocketsflow 1.0.0 → 1.1.0

package/dist/index.d.ts

@@ -48,13 +48,42 @@ interface ProductFile {
     size?: number;
 }
 interface CreateProductParams {
+    /** Product name (required) */
     name: string;
+    /** Product description */
     description?: string;
+    /** Product price (required, defaults to 0) */
     price: number;
-    currency?: string;
-    type?: 'one-time' | 'subscription';
-    billingInterval?: 'month' | 'year';
-    active?: boolean;
+    /** Product subtitle */
+    subtitle?: string;
+    /** Whether customer can pay what they want */
+    payWant?: boolean;
+    /** Minimum price for pay-what-you-want */
+    minPrice?: number;
+    /** Maximum price for pay-what-you-want */
+    maxPrice?: number;
+    /** Whether product is published */
+    published?: boolean;
+    /** Product slug for URL */
+    slug?: string;
+    /** Thumbnail image URL */
+    thumbnail?: string;
+    /** Product images array */
+    images?: string[];
+    /** Call to action text */
+    ctaText?: string;
+    /** Show sales count */
+    showSales?: boolean;
+    /** Show reviews */
+    showReviews?: boolean;
+    /** Refund policy text */
+    refundPolicy?: string;
+    /** Callback URL for redirects */
+    callbackUrl?: string;
+    /** Collect first name */
+    hasFirstName?: boolean;
+    /** Collect last name */
+    hasLastName?: boolean;
 }
 interface UpdateProductParams {
     name?: string;
@@ -162,12 +191,19 @@ interface Discount {
     createdAt: string;
 }
 interface CreateDiscountParams {
+    /** Discount name (required) */
     name: string;
+    /** Discount code (required) - what customers enter at checkout */
     code: string;
+    /** Discount value (required) */
     value: number;
-    valueType: 'percentage' | 'fixed';
+    /** Value type: 'percentage' or 'fixed' (defaults to 'percentage') */
+    valueType?: 'percentage' | 'fixed';
+    /** Whether discount is active (defaults to true) */
     active?: boolean;
+    /** Product IDs this discount applies to (required) */
     mainProductIds: string[];
+    /** Expiration date (ISO 8601 string) */
     expiration?: string;
 }
 interface UpdateDiscountParams {
@@ -199,14 +235,23 @@ interface UpsellsResponse {
     salesWithUpsells: any[];
 }
 interface CreateUpsellParams {
-    name: string;
+    /** Upsell name */
+    name?: string;
+    /** Offer text/headline */
+    offer?: string;
+    /** Product IDs that trigger this upsell (required) */
     mainProductIds: string[];
+    /** Product ID to upsell (required) */
     upsellProductId: string;
+    /** Upsell price (required) */
     upsellPrice: number;
+    /** Upsell description shown to customer */
     upsellDescription?: string;
+    /** Primary button text (e.g., "Yes, add this!") */
     primaryButtonText?: string;
+    /** Secondary button text (e.g., "No thanks") */
     secondaryButtonText?: string;
-    offer?: string;
+    /** Whether upsell is active (defaults to true) */
     active?: boolean;
 }
 interface UpdateUpsellParams {
@@ -236,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;
@@ -248,11 +560,17 @@ interface Webhook {
     createdAt: string;
 }
 interface CreateWebhookParams {
+    /** Webhook endpoint URL (required) */
     url: string;
-    events: string[];
+    /** Events to subscribe to (required) */
+    events: WebhookEvent[];
+    /** Webhook description */
     description?: string;
+    /** Whether webhook is active (defaults to true) */
     active?: boolean;
 }
+/** Available webhook events */
+type WebhookEvent = 'order.completed' | 'order.refunded' | 'product.created' | 'product.updated' | 'product.deleted' | 'review.created' | 'customer.created' | 'customer.subscription.updated' | 'customer.subscription.deleted' | 'invoice.payment_succeeded' | 'invoice.payment_failed' | 'invoice.created' | 'invoice.upcoming' | 'payment_intent.succeeded' | 'payment_intent.payment_failed' | 'customer.subscription.trial_will_end' | 'customer.subscription.pause' | 'customer.subscription.resumed' | 'identity.verification_session.verified' | 'identity.verification_session.processing' | 'identity.verification_session.requires_input';
 interface UpdateWebhookParams {
     url?: string;
     events?: string[];
@@ -329,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;
@@ -402,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;
@@ -419,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);
@@ -435,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);
@@ -480,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 };
+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 };