@paykit-sdk/core/dist/index.d.ts

The Payment Toolkit for Typescript

type WithPaymentProviderConfig<T extends object> = T & {
    apiKey: string;
    environment?: 'test' | 'live';
};
type OverrideProps<T, V> = V & Omit<T, keyof V>;
type LooseAutoComplete<T extends string> = T | Omit<string, T>;
type StringMetadata = {
    [key: string]: string;
};

type CreateCheckoutParams = {
    /**
     * The ID of the customer.
     */
    customer_id: string;
    /**
     * The metadata of the checkout.
     */
    metadata: StringMetadata;
    /**
     * The mode of the checkout.
     */
    mode: 'payment' | 'subscription';
    /**
     * The success URL of the checkout.
     */
    success_url: string;
    /**
     * The cancel URL of the checkout.
     */
    cancel_url: string;
    /**
     * The price ID of the checkout.
     */
    price_id: string;
    /**
     * The quantity of the checkout.
     */
    quantity: number;
};
type RetrieveCheckoutParams = {
    /**
     * The ID of the customer.
     */
    customer_id: string;
};
type Checkout = {
    /**
     * The ID of the checkout.
     */
    id: string;
    /**
     * The ID of the customer.
     */
    customer_id: string;
    /**
     * The metadata of the checkout.
     */
    metadata?: StringMetadata;
    /**
     * The mode of the checkout.
     */
    mode: 'payment' | 'subscription';
    /**
     * The success URL of the checkout.
     */
    success_url: string;
    /**
     * The cancel URL of the checkout.
     */
    cancel_url: string | undefined;
    /**
     * The products of the checkout.
     */
    products: Array<{
        id: string;
        quantity: number;
    }>;
    /**
     * The URL of the checkout.
     */
    url: string;
};

interface Customer {
    /**
     * The ID of the customer.
     */
    id: string;
    /**
     * The email of the customer.
     */
    email?: string;
    /**
     * The name of the customer.
     */
    name?: string;
    /**
     * The metadata of the customer.
     */
    metadata?: StringMetadata;
}
interface CreateCustomerParams {
    /**
     * The email of the customer.
     */
    email: string;
    /**
     * The name of the customer.
     */
    name?: string;
    /**
     * The metadata of the customer.
     */
    metadata?: StringMetadata;
}
interface UpdateCustomerParams {
    /**
     * The email of the customer.
     */
    email: string;
    /**
     * The name of the customer.
     */
    name?: string;
    /**
     * The metadata of the customer.
     */
    metadata?: StringMetadata;
}

type SubscriptionStatus = 'active' | 'past_due' | 'canceled' | 'expired';
interface Subscription {
    /**
     * The ID of the subscription.
     */
    id: string;
    /**
     * The ID of the customer.
     */
    customer_id: string;
    /**
     * The status of the subscription.
     */
    status: SubscriptionStatus;
    /**
     * The current period start of the subscription.
     */
    current_period_start: Date;
    /**
     * The current period end of the subscription.
     */
    current_period_end: Date;
    /**
     * The metadata of the subscription.
     */
    metadata?: StringMetadata;
}
type UpdateSubscriptionParams = {
    /**
     * The metadata of the subscription.
     */
    metadata: StringMetadata;
};
declare const toPaykitSubscriptionStatus: <T extends string>(status: T) => SubscriptionStatus;

type WebhookEventLiteral = 'customer.created' | 'customer.updated' | 'customer.deleted' | 'subscription.created' | 'subscription.updated' | 'subscription.canceled' | 'checkout.created';
interface WebhookEvent<T extends any> {
    /**
     * The ID of the webhook event.
     */
    id: string;
    /**
     * The type of the webhook event.
     */
    type: string;
    /**
     * The created timestamp of the webhook event.
     */
    created: number;
    /**
     * The data of the webhook event.
     */
    data: T;
}
type WebhookHandler<T extends any> = (event: WebhookEvent<T>) => Promise<void>;
type WebhookEventPayload = WebhookEvent<Checkout> | WebhookEvent<Customer | null> | WebhookEvent<Subscription>;
/**
 * todo: accept the request object instead of the payload and signature
 */
interface InternalWebhookHandlerParams {
    payload: string;
    signature: string;
    secret: string;
}
declare const toPaykitEvent: <T extends any>(event: {
    id: string;
    type: WebhookEventLiteral;
    created: number;
    data: T;
}) => WebhookEvent<T>;

interface PayKitProvider {
    /**
     * Checkout sessions
     */
    createCheckout(params: CreateCheckoutParams): Promise<Checkout>;
    retrieveCheckout(id: string): Promise<Checkout>;
    /**
     * Customer management
     */
    createCustomer(params: CreateCustomerParams): Promise<Customer>;
    updateCustomer(id: string, params: UpdateCustomerParams): Promise<Customer>;
    retrieveCustomer(id: string): Promise<Customer | null>;
    /**
     * Subscription management
     */
    updateSubscription(id: string, params: UpdateSubscriptionParams): Promise<Subscription>;
    cancelSubscription(id: string): Promise<Subscription>;
    retrieveSubscription(id: string): Promise<Subscription>;
    /**
     * Webhook management
     */
    handleWebhook(params: InternalWebhookHandlerParams): Promise<WebhookEventPayload>;
}

interface WebhookConfig {
    provider: PayKitProvider;
    webhookSecret: string;
    /**
     * Customer events
     */
    onCustomerCreated?: WebhookHandler<Customer>;
    onCustomerUpdated?: WebhookHandler<Customer>;
    onCustomerDeleted?: WebhookHandler<Customer>;
    /**
     * Subscription events
     */
    onSubscriptionCreated?: WebhookHandler<Subscription>;
    onSubscriptionUpdated?: WebhookHandler<Subscription>;
    onSubscriptionCanceled?: WebhookHandler<Subscription>;
    /**
     * Checkout events
     */
    onCheckoutCreated?: WebhookHandler<Checkout>;
}
declare class Webhook {
    private config;
    constructor(config: WebhookConfig);
    handleWebhook: (payload: string, signature: string) => Promise<void>;
}

declare class PayKit {
    private provider;
    constructor(provider: PayKitProvider);
    checkouts: {
        create: (params: CreateCheckoutParams) => Promise<Checkout>;
        retrieve: (id: string) => Promise<Checkout>;
    };
    customers: {
        create: (params: CreateCustomerParams) => Promise<Customer>;
        update: (id: string, params: UpdateCustomerParams) => Promise<Customer>;
        retrieve: (id: string) => Promise<Customer | null>;
    };
    subscriptions: {
        update: (id: string, params: UpdateSubscriptionParams) => Promise<Subscription>;
        cancel: (id: string) => Promise<Subscription>;
    };
}

export { type Checkout, type CreateCheckoutParams, type CreateCustomerParams, type Customer, type InternalWebhookHandlerParams, type LooseAutoComplete, type OverrideProps, PayKit, type PayKitProvider, type RetrieveCheckoutParams, type StringMetadata, type Subscription, type SubscriptionStatus, type UpdateCustomerParams, type UpdateSubscriptionParams, Webhook, type WebhookEvent, type WebhookEventLiteral, type WebhookEventPayload, type WebhookHandler, type WithPaymentProviderConfig, toPaykitEvent, toPaykitSubscriptionStatus };