tmp_docs.txt

import { NextRequest, NextResponse } from 'next/server';
import React from 'react';

interface CheckoutRouteInstance {
    apiKey: string;
    testMode?: boolean;
    defaultSuccessUrl?: string;
}
declare const Checkout: ({ apiKey, testMode, defaultSuccessUrl, }: CheckoutRouteInstance) => (req: NextRequest) => Promise<NextResponse<unknown>>;

interface PortalRouteInstance {
    apiKey: string;
    testMode?: boolean;
}
declare const Portal: ({ apiKey, testMode }: PortalRouteInstance) => (req: NextRequest) => Promise<NextResponse<unknown>>;

/**
 * Creem Webhook Types
 *
 * This file contains all the TypeScript types needed to work with Creem webhooks.
 * It's designed to be standalone and can be copied to external projects.
 *
 * No external dependencies required - just TypeScript!
 */
/**
 * Metadata type for storing arbitrary key-value pairs
 */
type Metadata = Record<string, string | number | null>;
/**
 * Base entity interface that all webhook objects extend
 */
interface BaseEntity {
    /** Unique identifier for the object */
    id: string;
    /** Environment mode: test, prod, or sandbox */
    mode: "test" | "prod" | "sandbox";
}
interface Text {
    /** Maximum character length constraint for the input */
    max_length?: number;
    /** Minimum character length requirement for the input */
    minimum_length?: number;
    /** The value of the input */
    value?: string;
}
interface Checkbox {
    /** The markdown text to display for the checkbox */
    label?: string;
    /** The value of the checkbox (checked or not) */
    value?: boolean;
}
interface CustomField {
    /** The type of the field */
    type: "text" | "checkbox";
    /** Unique key for custom field. Must be unique, alphanumeric, up to 200 characters */
    key: string;
    /** The label for the field, displayed to the customer, up to 50 characters */
    label: string;
    /** Whether the customer is required to complete the field. Defaults to false */
    optional?: boolean;
    /** Configuration for text field type */
    text?: Text;
    /** Configuration for checkbox field type */
    checkbox?: Checkbox;
}
interface CustomerEntity extends BaseEntity {
    /** String representing the object's type */
    object: "customer";
    /** Customer email address */
    email: string;
    /** Customer name */
    name?: string;
    /** The ISO alpha-2 country code for the customer */
    country: string;
    /** Creation date of the customer */
    created_at: Date;
    /** Last updated date of the customer */
    updated_at: Date;
}
interface FeatureEntity {
    /** Unique identifier for the feature */
    id: string;
    /** The feature type */
    type: "custom" | "github-repo" | "discord" | "file" | "link" | "licence-key";
    /** A brief description of the feature */
    description: string;
}
interface ProductEntity extends BaseEntity {
    /** String representing the object's type */
    object: "product";
    /** The name of the product */
    name: string;
    /** A brief description of the product */
    description: string;
    /** URL of the product image. Only png and jpg are supported */
    image_url?: string;
    /** Features of the product */
    features?: FeatureEntity[];
    /** The price of the product in cents. 1000 = $10.00 */
    price: number;
    /** Three-letter ISO currency code, in uppercase */
    currency: string;
    /** Billing method: recurring or one-time */
    billing_type: "recurring" | "one-time";
    /** Billing period */
    billing_period: "every-month" | "every-three-months" | "every-six-months" | "every-year" | "once";
    /** Status of the product */
    status: "active" | "archived";
    /** Tax calculation mode */
    tax_mode: "inclusive" | "exclusive";
    /** Tax category for the product */
    tax_category: "saas" | "digital-goods-service" | "ebooks";
    /** The product page URL for express checkout */
    product_url?: string;
    /** The URL to redirect after successful payment */
    default_success_url?: string;
    /** Creation date of the product */
    created_at: Date;
    /** Last updated date of the product */
    updated_at: Date;
}
interface TransactionEntity extends BaseEntity {
    /** String representing the object's type */
    object: "transaction";
    /** The transaction amount in cents. 1000 = $10.00 */
    amount: number;
    /** The amount the customer paid in cents. 1000 = $10.00 */
    amount_paid?: number;
    /** The discount amount in cents. 1000 = $10.00 */
    discount_amount?: number;
    /** Three-letter ISO currency code, in uppercase */
    currency: string;
    /** The type of transaction: payment (one time) or invoice (subscription) */
    type: "payment" | "invoice";
    /** The ISO alpha-2 country code where tax is collected */
    tax_country?: string;
    /** The sale tax amount in cents. 1000 = $10.00 */
    tax_amount?: number;
    /** Status of the transaction */
    status: "pending" | "paid" | "refunded" | "partialRefund" | "chargedBack" | "uncollectible" | "declined" | "void";
    /** The amount that has been refunded in cents. 1000 = $10.00 */
    refunded_amount?: number | null;
    /** The order ID associated with the transaction */
    order?: string;
    /** The subscription ID associated with the transaction */
    subscription?: string;
    /** The customer ID associated with the transaction */
    customer?: string;
    /** The description of the transaction */
    description: string;
    /** Start period for the invoice as timestamp */
    period_start?: number;
    /** End period for the invoice as timestamp */
    period_end?: number;
    /** Creation date of the transaction as timestamp */
    created_at: number;
}
interface OrderEntity extends BaseEntity {
    /** String representing the object's type */
    object: "order";
    /** The customer ID who placed the order */
    customer?: string;
    /** The product ID associated with the order */
    product: string;
    /** The transaction ID of the order */
    transaction?: string;
    /** The discount ID of the order */
    discount?: string;
    /** The total amount of the order in cents. 1000 = $10.00 */
    amount: number;
    /** The subtotal of the order in cents. 1000 = $10.00 */
    sub_total?: number;
    /** The tax amount of the order in cents. 1000 = $10.00 */
    tax_amount?: number;
    /** The discount amount of the order in cents. 1000 = $10.00 */
    discount_amount?: number;
    /** The amount due for the order in cents. 1000 = $10.00 */
    amount_due?: number;
    /** The amount paid for the order in cents. 1000 = $10.00 */
    amount_paid?: number;
    /** Three-letter ISO currency code, in uppercase */
    currency: string;
    /** The amount in the foreign currency, if applicable */
    fx_amount?: number;
    /** Three-letter ISO code of the foreign currency, if applicable */
    fx_currency?: string;
    /** The exchange rate used for converting between currencies */
    fx_rate?: number;
    /** Current status of the order */
    status: "pending" | "paid";
    /** The type of order */
    type: "recurring" | "onetime";
    /** The affiliate ID associated with the order, if applicable */
    affiliate?: string;
    /** Creation date of the order */
    created_at: Date;
    /** Last updated date of the order */
    updated_at: Date;
}
interface LicenseInstanceEntity extends BaseEntity {
    /** String representing the object's type */
    object: "license-instance";
    /** The name of the license instance */
    name: string;
    /** The status of the license instance */
    status: "active" | "deactivated";
    /** The creation date of the license instance */
    created_at: Date;
}
interface LicenseEntity extends BaseEntity {
    /** String representing the object's type */
    object: "license";
    /** The current status of the license key */
    status: "inactive" | "active" | "expired" | "disabled";
    /** The license key */
    key: string;
    /** The number of instances that this license key was activated */
    activation: number;
    /** The activation limit. Null if activations are unlimited */
    activation_limit: number | null;
    /** The date the license key expires. Null if no expiration */
    expires_at: Date | null;
    /** The creation date of the license key */
    created_at: Date;
    /** Associated license instance */
    instance?: LicenseInstanceEntity | null;
}
interface ProductFeatureEntity {
    /** License key issued for the order */
    license?: LicenseEntity;
}
interface SubscriptionItemEntity extends BaseEntity {
    /** String representing the object's type */
    object: "subscription_item";
    /** The product ID associated with the subscription item */
    product_id: string;
    /** The price ID associated with the subscription item */
    price_id: string;
    /** The number of units for the subscription item */
    units?: number;
    /** The creation date of the subscription item */
    created_at: Date;
    /** The last updated date of the subscription item */
    updated_at: Date;
}
type SubscriptionStatus = "active" | "canceled" | "unpaid" | "paused" | "trialing";
interface SubscriptionEntity extends BaseEntity {
    /** String representing the object's type */
    object: "subscription";
    /** The product associated with the subscription */
    product: ProductEntity | string;
    /** The customer who owns the subscription */
    customer: CustomerEntity | string;
    /** Subscription items */
    items?: SubscriptionItemEntity[];
    /** The method used for collecting payments */
    collection_method: "charge_automatically";
    /** The current status of the subscription */
    status: SubscriptionStatus;
    /** The ID of the last paid transaction */
    last_transaction_id?: string;
    /** The last paid transaction */
    last_transaction?: TransactionEntity;
    /** The date of the last paid transaction */
    last_transaction_date?: Date;
    /** The date when the next subscription transaction will be charged */
    next_transaction_date?: Date;
    /** The start date of the current subscription period */
    current_period_start_date: Date;
    /** The end date of the current subscription period */
    current_period_end_date: Date;
    /** The date when the subscription was canceled, if applicable */
    canceled_at: Date | null;
    /** The date when the subscription was created */
    created_at: Date;
    /** The date when the subscription was last updated */
    updated_at: Date;
    /** Optional metadata */
    metadata?: Metadata;
}
type CheckoutStatus = "pending" | "processing" | "completed" | "expired";
interface CheckoutEntity extends BaseEntity {
    /** String representing the object's type */
    object: "checkout";
    /** Status of the checkout */
    status: CheckoutStatus;
    /** Request ID to identify and track each checkout request */
    request_id: string;
    /** The product associated with the checkout session */
    product: ProductEntity | string;
    /** The number of units for the product */
    units: number;
    /** The order associated with the checkout session */
    order?: OrderEntity;
    /** The subscription associated with the checkout session */
    subscription?: SubscriptionEntity | string;
    /** The customer associated with the checkout session */
    customer?: CustomerEntity | string;
    /** Additional information collected during checkout */
    custom_fields?: CustomField[];
    /** The URL to complete the payment */
    checkout_url?: string;
    /** The URL to redirect after checkout is completed */
    success_url?: string;
    /** Features issued for the order */
    feature?: ProductFeatureEntity;
    /** Metadata for the checkout */
    metadata?: Metadata;
}
interface RefundEntity extends BaseEntity {
    /** String representing the object's type */
    object: "refund";
    /** Status of the refund */
    status: "pending" | "succeeded" | "canceled" | "failed";
    /** The refunded amount in cents. 1000 = $10.00 */
    refund_amount: number;
    /** Three-letter ISO currency code, in uppercase */
    refund_currency: string;
    /** Reason for the refund */
    reason: "duplicate" | "fraudulent" | "requested_by_customer" | "other";
    /** The transaction associated with the refund */
    transaction: TransactionEntity;
    /** The checkout associated with the refund */
    checkout?: CheckoutEntity | string;
    /** The order associated with the refund */
    order?: OrderEntity | string;
    /** The subscription associated with the refund */
    subscription?: SubscriptionEntity | string;
    /** The customer associated with the refund */
    customer?: CustomerEntity | string;
    /** Creation date as timestamp */
    created_at: number;
}
interface DisputeEntity extends BaseEntity {
    /** String representing the object's type */
    object: "dispute";
    /** The disputed amount in cents. 1000 = $10.00 */
    amount: number;
    /** Three-letter ISO currency code, in uppercase */
    currency: string;
    /** The transaction associated with the dispute */
    transaction: TransactionEntity;
    /** The checkout associated with the dispute */
    checkout?: CheckoutEntity | string;
    /** The order associated with the dispute */
    order?: OrderEntity | string;
    /** The subscription associated with the dispute */
    subscription?: SubscriptionEntity | string;
    /** The customer associated with the dispute */
    customer?: CustomerEntity | string;
    /** Creation date as timestamp */
    created_at: number;
}
/**
 * Subscription entity as returned in subscription webhook events.
 * The product and customer are always expanded (full objects, never just IDs).
 */
interface NormalizedSubscriptionEntity extends Omit<SubscriptionEntity, "product" | "customer"> {
    /** The product associated with the subscription (always expanded in webhooks) */
    product: ProductEntity;
    /** The customer who owns the subscription (always expanded in webhooks) */
    customer: CustomerEntity;
}
/**
 * Subscription entity as nested in checkout.completed events.
 * Note: In checkout events, the nested subscription has product/customer as ID strings.
 */
interface NestedSubscriptionInCheckout extends Omit<SubscriptionEntity, "product" | "customer"> {
    /** The product ID (string, not expanded in nested subscription) */
    product: string;
    /** The customer ID (string, not expanded in nested subscription) */
    customer: string;
}
/**
 * Checkout entity as returned in checkout.completed webhook events.
 * Product and customer are always expanded.
 * Subscription is also expanded but has product/customer as strings inside it.
 */
interface NormalizedCheckoutEntity extends Omit<CheckoutEntity, "product" | "customer" | "subscription"> {
    /** The product associated with the checkout (always expanded in webhooks) */
    product: ProductEntity;
    /** The customer associated with the checkout (always expanded in webhooks) */
    customer?: CustomerEntity;
    /** The subscription associated with the checkout (expanded, but nested fields are IDs) */
    subscription?: NestedSubscriptionInCheckout;
}
/**
 * Refund entity as returned in refund.created webhook events.
 */
interface NormalizedRefundEntity extends RefundEntity {
    /** The transaction is always expanded */
    transaction: TransactionEntity;
}
/**
 * Dispute entity as returned in dispute.created webhook events.
 */
interface NormalizedDisputeEntity extends DisputeEntity {
    /** The transaction is always expanded */
    transaction: TransactionEntity;
}

interface CheckoutCustomer {
    /** Customer email address */
    email?: string;
    /** Customer name */
    name?: string;
}
interface CreateCheckoutInput {
    /**
     * The Creem product ID to checkout.
     * You can find this in your Creem dashboard under Products.
     *
     * @required
     * @example "prod_abc123"
     */
    productId: string;
    /**
     * Idempotency key to prevent duplicate checkouts.
     * If provided, subsequent requests with the same requestId will return the same checkout.
     *
     * @optional
     * @example "checkout-user123-20240101"
     */
    requestId?: string;
    /**
     * Number of units to purchase.
     * Must be a positive number. Defaults to 1 if not provided.
     *
     * @optional
     * @default 1
     * @example 3
     */
    units?: number;
    /**
     * Discount code to apply to the checkout.
     * The code must exist and be active in your Creem dashboard.
     *
     * @optional
     * @example "SUMMER2024"
     */
    discountCode?: string;
    /**
     * Customer information for the checkout.
     * If not provided, uses the authenticated user's email and name from the session.
     *
     * @optional
     * @example { email: "user@example.com", name: "John Doe" }
     */
    customer?: CheckoutCustomer;
    /**
     * Custom fields to include with the checkout.
     * Useful for storing additional information about the purchase.
     *
     * @optional
     * @example { custom_field_1: "value1", custom_field_2: "value2" }
     */
    customFields?: Record<string, unknown>;
    /**
     * URL to redirect to after successful checkout.
     * If not provided, uses the defaultSuccessUrl from plugin options.
     *
     * @optional
     * @example "/thank-you"
     * @example "https://example.com/success"
     */
    successUrl?: string;
    /**
     * Additional metadata to store with the checkout.
     * Automatically includes the authenticated user's ID as `referenceId` if available.
     *
     * @optional
     * @example { orderId: "12345", source: "web" }
     */
    metadata?: Record<string, unknown>;
    /**
     * User ID to associate with the checkout.
     * Automatically includes the authenticated user's ID as `referenceId` if available.
     *
     * @optional
     * @example "user123"
     */
    referenceId?: string;
}
/**
 * Flattened checkout.completed callback parameter.
 * All properties are at the top level for easy destructuring.
 */
type FlatCheckoutCompleted = {
    /** Webhook event type identifier */
    webhookEventType: "checkout.completed";
    /** Unique webhook event ID */
    webhookId: string;
    /** Webhook event creation timestamp */
    webhookCreatedAt: number;
} & NormalizedCheckoutEntity;
/**
 * Flattened refund.created callback parameter.
 */
type FlatRefundCreated = {
    /** Webhook event type identifier */
    webhookEventType: "refund.created";
    /** Unique webhook event ID */
    webhookId: string;
    /** Webhook event creation timestamp */
    webhookCreatedAt: number;
} & NormalizedRefundEntity;
/**
 * Flattened dispute.created callback parameter.
 */
type FlatDisputeCreated = {
    /** Webhook event type identifier */
    webhookEventType: "dispute.created";
    /** Unique webhook event ID */
    webhookId: string;
    /** Webhook event creation timestamp */
    webhookCreatedAt: number;
} & NormalizedDisputeEntity;
/**
 * Flattened subscription event callback parameter.
 */
type FlatSubscriptionEvent<T extends string> = {
    /** Webhook event type identifier */
    webhookEventType: T;
    /** Unique webhook event ID */
    webhookId: string;
    /** Webhook event creation timestamp */
    webhookCreatedAt: number;
} & NormalizedSubscriptionEntity;
/**
 * Reasons for granting access
 */
type GrantAccessReason = "subscription_active" | "subscription_trialing" | "subscription_paid";
/**
 * Reasons for revoking access
 */
type RevokeAccessReason = "subscription_paused" | "subscription_expired";
/**
 * Context passed to onGrantAccess callback.
 * All subscription properties are flattened for easy destructuring.
 */
type GrantAccessContext = {
    /** The reason for granting access */
    reason: GrantAccessReason;
} & NormalizedSubscriptionEntity;
/**
 * Context passed to onRevokeAccess callback.
 * All subscription properties are flattened for easy destructuring.
 */
type RevokeAccessContext = {
    /** The reason for revoking access */
    reason: RevokeAccessReason;
} & NormalizedSubscriptionEntity;
/**
 * Webhook configuration options
 */
interface WebhookOptions {
    /**
     * Creem Webhook Secret (for signature verification)
     * @required
     */
    webhookSecret: string;
    /**
     * Called when a checkout is completed.
     * All properties are flattened for easy destructuring.
     *
     * @example
     * onCheckoutCompleted: async ({ webhookEventType, product, customer, order, subscription }) => {
     *   console.log(`Checkout completed: ${customer?.email} purchased ${product.name}`);
     * }
     */
    onCheckoutCompleted?: (data: FlatCheckoutCompleted) => void | Promise<void>;
    /**
     * Called when a refund is created.
     */
    onRefundCreated?: (data: FlatRefundCreated) => void | Promise<void>;
    /**
     * Called when a dispute is created.
     */
    onDisputeCreated?: (data: FlatDisputeCreated) => void | Promise<void>;
    /**
     * Called when a subscription becomes active.
     *
     * @example
     * onSubscriptionActive: async ({ product, customer, status }) => {
     *   console.log(`${customer.email} subscribed to ${product.name}`);
     * }
     */
    onSubscriptionActive?: (data: FlatSubscriptionEvent<"subscription.active">) => void | Promise<void>;
    /**
     * Called when a subscription is in trialing state.
     */
    onSubscriptionTrialing?: (data: FlatSubscriptionEvent<"subscription.trialing">) => void | Promise<void>;
    /**
     * Called when a subscription is canceled.
     */
    onSubscriptionCanceled?: (data: FlatSubscriptionEvent<"subscription.canceled">) => void | Promise<void>;
    /**
     * Called when a subscription is paid.
     */
    onSubscriptionPaid?: (data: FlatSubscriptionEvent<"subscription.paid">) => void | Promise<void>;
    /**
     * Called when a subscription has expired.
     */
    onSubscriptionExpired?: (data: FlatSubscriptionEvent<"subscription.expired">) => void | Promise<void>;
    /**
     * Called when a subscription is unpaid.
     */
    onSubscriptionUnpaid?: (data: FlatSubscriptionEvent<"subscription.unpaid">) => void | Promise<void>;
    /**
     * Called when a subscription is updated.
     */
    onSubscriptionUpdate?: (data: FlatSubscriptionEvent<"subscription.update">) => void | Promise<void>;
    /**
     * Called when a subscription is past due.
     */
    onSubscriptionPastDue?: (data: FlatSubscriptionEvent<"subscription.past_due">) => void | Promise<void>;
    /**
     * Called when a subscription is paused.
     */
    onSubscriptionPaused?: (data: FlatSubscriptionEvent<"subscription.paused">) => void | Promise<void>;
    /**
     * Called when a user should be granted access to the platform.
     * This is triggered for: active, trialing, and paid subscriptions.
     *
     * NOTE: This may be called multiple times for the same user/subscription.
     * Implement this as an idempotent operation (safe to call repeatedly).
     *
     * @example
     * onGrantAccess: async ({ reason, product, customer, metadata }) => {
     *   const userId = metadata?.referenceId as string;
     *   console.log(`Granting ${reason} to ${customer.email} for ${product.name}`);
     *   // Your database logic here
     * }
     */
    onGrantAccess?: (context: GrantAccessContext) => void | Promise<void>;
    /**
     * Called when a user's access should be revoked.
     * This is triggered for: paused, expired, and canceled (after period ends) subscriptions.
     *
     * NOTE: This may be called multiple times for the same user/subscription.
     * Implement this as an idempotent operation (safe to call repeatedly).
     *
     * @example
     * onRevokeAccess: async ({ reason, product, customer, metadata }) => {
     *   const userId = metadata?.referenceId as string;
     *   console.log(`Revoking access (${reason}) from ${customer.email}`);
     *   // Your database logic here
     * }
     */
    onRevokeAccess?: (context: RevokeAccessContext) => void | Promise<void>;
}

/**
 * Creates a webhook handler for Creem webhooks
 *
 * @param options - Webhook configuration options
 * @returns An async function that handles incoming webhook requests
 *
 * @example
 * ```typescript
 * import { Webhooks } from "@creem/nextjs/server";
 *
 * export const POST = Webhooks({
 *   webhookSecret: process.env.CREEM_WEBHOOK_SECRET!,
 *   onCheckoutCompleted: async ({ product, customer }) => {
 *     console.log(`${customer?.email} purchased ${product.name}`);
 *   },
 *   onGrantAccess: async ({ reason, customer, metadata }) => {
 *     // Grant access to your application
 *   },
 *   onRevokeAccess: async ({ reason, customer, metadata }) => {
 *     // Revoke access from your application
 *   },
 * });
 * ```
 */
declare const Webhook: (options: WebhookOptions) => (request: NextRequest) => Promise<NextResponse<{
    error: string;
}> | NextResponse<{
    message: string;
}>>;

interface CreemCheckoutProps extends CreateCheckoutInput {
    /**
     * Custom path for the checkout API route.
     * @default "/checkout"
     * @example "/api/creem/checkout"
     */
    checkoutPath?: string;
    children?: React.ReactNode;
}
declare const CreemCheckout: ({ productId, units, discountCode, customer, customFields, successUrl, metadata, referenceId, checkoutPath, children, }: CreemCheckoutProps) => React.JSX.Element;
interface CreemPortalProps {
    /**
     * The Creem customer ID to create a portal session for.
     * @required
     * @example "cust_abc123"
     */
    customerId: string;
    /**
     * Custom path for the portal API route.
     * @default "/portal"
     * @example "/api/creem/portal"
     */
    portalPath?: string;
    children?: React.ReactNode;
}
declare const CreemPortal: ({ customerId, portalPath, children, ...linkProps }: CreemPortalProps & Omit<React.ComponentProps<"a">, "href">) => React.JSX.Element;

export { Checkout, type CheckoutCustomer, type CreateCheckoutInput, CreemCheckout, type CreemCheckoutProps, CreemPortal, type CreemPortalProps, type FlatCheckoutCompleted, type FlatDisputeCreated, type FlatRefundCreated, type FlatSubscriptionEvent, type GrantAccessContext, type GrantAccessReason, Portal, type RevokeAccessContext, type RevokeAccessReason, Webhook, type WebhookOptions };