@stackbe/sdk 0.1.0 → 0.2.0

package/dist/index.d.mts

@@ -7,6 +7,7 @@ interface HttpClientConfig {
 declare class HttpClient {
     private config;
     constructor(config: HttpClientConfig);
+    get baseUrl(): string;
     private request;
     get<T>(path: string, params?: Record<string, string | number | undefined>): Promise<T>;
     post<T>(path: string, body?: unknown, params?: Record<string, string | number | undefined>): Promise<T>;
@@ -109,6 +110,12 @@ interface UpdateCustomerOptions {
     name?: string;
     metadata?: Record<string, unknown>;
 }
+interface MagicLinkOptions {
+    /** URL to redirect to after authentication */
+    redirectUrl?: string;
+    /** Use development callback URL (for localhost testing) */
+    useDev?: boolean;
+}
 interface MagicLinkResponse {
     success: boolean;
     message: string;
@@ -124,6 +131,64 @@ interface SessionResponse {
     subscription?: Subscription;
     entitlements: Record<string, boolean | number | string>;
 }
+interface CreateCheckoutOptions {
+    /** Customer ID or email */
+    customer: string | {
+        email: string;
+        name?: string;
+    };
+    /** Plan ID to subscribe to */
+    planId: string;
+    /** URL to redirect after successful checkout */
+    successUrl: string;
+    /** URL to redirect if checkout is canceled */
+    cancelUrl?: string;
+    /** Allow promotion codes */
+    allowPromotionCodes?: boolean;
+    /** Trial period in days */
+    trialDays?: number;
+    /** Metadata to attach to the subscription */
+    metadata?: Record<string, string>;
+}
+interface CheckoutSessionResponse {
+    /** Checkout session ID */
+    id: string;
+    /** URL to redirect customer to for checkout */
+    url: string;
+    /** Session status */
+    status: 'open' | 'complete' | 'expired';
+    /** Customer ID */
+    customerId: string;
+    /** Expiration time */
+    expiresAt: string;
+}
+interface SubscriptionWithPlan extends Subscription {
+    plan: {
+        id: string;
+        name: string;
+        price: number;
+        interval: 'month' | 'year';
+        currency: string;
+    };
+}
+interface CancelSubscriptionOptions {
+    /** Cancel immediately or at end of billing period */
+    immediate?: boolean;
+    /** Reason for cancellation */
+    reason?: string;
+}
+interface CancelSubscriptionResponse {
+    success: boolean;
+    subscription: Subscription;
+    /** When the subscription will actually end */
+    endsAt: string;
+}
+interface UpdateSubscriptionOptions {
+    /** New plan ID to switch to */
+    planId?: string;
+    /** Proration behavior */
+    prorate?: boolean;
+}
 interface StackBEErrorResponse {
     statusCode: number;
     message: string;
@@ -347,14 +412,275 @@ declare class CustomersClient {
     getSession(token: string): Promise<SessionResponse>;
 }
 
+declare class CheckoutClient {
+    private http;
+    private appId;
+    constructor(http: HttpClient, appId: string);
+    /**
+     * Create a checkout session for a customer to subscribe to a plan.
+     * Returns a URL to redirect the customer to Stripe checkout.
+     *
+     * @example
+     * ```typescript
+     * // With existing customer ID
+     * const { url } = await stackbe.checkout.createSession({
+     *   customer: 'cust_123',
+     *   planId: 'plan_pro_monthly',
+     *   successUrl: 'https://myapp.com/success',
+     *   cancelUrl: 'https://myapp.com/pricing',
+     * });
+     *
+     * // Redirect to checkout
+     * res.redirect(url);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // With new customer (will be created)
+     * const { url } = await stackbe.checkout.createSession({
+     *   customer: { email: 'user@example.com', name: 'John' },
+     *   planId: 'plan_pro_monthly',
+     *   successUrl: 'https://myapp.com/success',
+     *   trialDays: 14,
+     * });
+     * ```
+     */
+    createSession(options: CreateCheckoutOptions): Promise<CheckoutSessionResponse>;
+    /**
+     * Get an existing checkout session by ID.
+     *
+     * @example
+     * ```typescript
+     * const session = await stackbe.checkout.getSession('cs_123');
+     * if (session.status === 'complete') {
+     *   // Payment successful
+     * }
+     * ```
+     */
+    getSession(sessionId: string): Promise<CheckoutSessionResponse>;
+    /**
+     * Generate a checkout URL for a plan.
+     * Convenience method that creates a session and returns just the URL.
+     *
+     * @example
+     * ```typescript
+     * const checkoutUrl = await stackbe.checkout.getCheckoutUrl({
+     *   customer: 'cust_123',
+     *   planId: 'plan_pro_monthly',
+     *   successUrl: 'https://myapp.com/success',
+     * });
+     *
+     * // Send to frontend
+     * res.json({ checkoutUrl });
+     * ```
+     */
+    getCheckoutUrl(options: CreateCheckoutOptions): Promise<string>;
+}
+
+declare class SubscriptionsClient {
+    private http;
+    constructor(http: HttpClient);
+    /**
+     * Get a customer's current active subscription.
+     *
+     * @example
+     * ```typescript
+     * const subscription = await stackbe.subscriptions.get('cust_123');
+     *
+     * if (subscription) {
+     *   console.log(`Plan: ${subscription.plan.name}`);
+     *   console.log(`Status: ${subscription.status}`);
+     *   console.log(`Renews: ${subscription.currentPeriodEnd}`);
+     * } else {
+     *   console.log('No active subscription');
+     * }
+     * ```
+     */
+    get(customerId: string): Promise<SubscriptionWithPlan | null>;
+    /**
+     * Get a subscription by ID.
+     *
+     * @example
+     * ```typescript
+     * const subscription = await stackbe.subscriptions.getById('sub_123');
+     * ```
+     */
+    getById(subscriptionId: string): Promise<SubscriptionWithPlan>;
+    /**
+     * List all subscriptions for a customer.
+     *
+     * @example
+     * ```typescript
+     * const subscriptions = await stackbe.subscriptions.list('cust_123');
+     * ```
+     */
+    list(customerId: string): Promise<Subscription[]>;
+    /**
+     * Cancel a subscription.
+     *
+     * @example
+     * ```typescript
+     * // Cancel at end of billing period (default)
+     * await stackbe.subscriptions.cancel('sub_123');
+     *
+     * // Cancel immediately
+     * await stackbe.subscriptions.cancel('sub_123', { immediate: true });
+     *
+     * // Cancel with reason
+     * await stackbe.subscriptions.cancel('sub_123', {
+     *   reason: 'Too expensive'
+     * });
+     * ```
+     */
+    cancel(subscriptionId: string, options?: CancelSubscriptionOptions): Promise<CancelSubscriptionResponse>;
+    /**
+     * Update a subscription (change plan).
+     *
+     * @example
+     * ```typescript
+     * // Upgrade/downgrade to a different plan
+     * await stackbe.subscriptions.update('sub_123', {
+     *   planId: 'plan_enterprise_monthly',
+     *   prorate: true,
+     * });
+     * ```
+     */
+    update(subscriptionId: string, options: UpdateSubscriptionOptions): Promise<Subscription>;
+    /**
+     * Reactivate a canceled subscription (before it ends).
+     *
+     * @example
+     * ```typescript
+     * // Customer changed their mind
+     * await stackbe.subscriptions.reactivate('sub_123');
+     * ```
+     */
+    reactivate(subscriptionId: string): Promise<Subscription>;
+    /**
+     * Check if a customer has an active subscription.
+     *
+     * @example
+     * ```typescript
+     * const isActive = await stackbe.subscriptions.isActive('cust_123');
+     * if (!isActive) {
+     *   return res.redirect('/pricing');
+     * }
+     * ```
+     */
+    isActive(customerId: string): Promise<boolean>;
+}
+
+declare class AuthClient {
+    private http;
+    private appId;
+    constructor(http: HttpClient, appId: string);
+    /**
+     * Send a magic link email to a customer for passwordless authentication.
+     *
+     * @example
+     * ```typescript
+     * // Send magic link
+     * await stackbe.auth.sendMagicLink('user@example.com');
+     *
+     * // With redirect URL
+     * await stackbe.auth.sendMagicLink('user@example.com', {
+     *   redirectUrl: 'https://myapp.com/dashboard',
+     * });
+     *
+     * // For localhost development
+     * await stackbe.auth.sendMagicLink('user@example.com', {
+     *   useDev: true,
+     * });
+     * ```
+     */
+    sendMagicLink(email: string, options?: MagicLinkOptions): Promise<MagicLinkResponse>;
+    /**
+     * Verify a magic link token and get a session token.
+     * Call this when the user clicks the magic link.
+     *
+     * @example
+     * ```typescript
+     * // In your /verify route handler
+     * const { token } = req.query;
+     *
+     * const result = await stackbe.auth.verifyToken(token);
+     *
+     * if (result.valid) {
+     *   // Set session cookie
+     *   res.cookie('session', result.token, { httpOnly: true });
+     *   res.redirect('/dashboard');
+     * } else {
+     *   res.redirect('/login?error=invalid_token');
+     * }
+     * ```
+     */
+    verifyToken(token: string): Promise<VerifyTokenResponse>;
+    /**
+     * Get the current session for an authenticated customer.
+     * Use this to validate session tokens and get customer data.
+     *
+     * @example
+     * ```typescript
+     * // Validate session on each request
+     * const sessionToken = req.cookies.session;
+     *
+     * const session = await stackbe.auth.getSession(sessionToken);
+     *
+     * if (session) {
+     *   req.customer = session.customer;
+     *   req.subscription = session.subscription;
+     *   req.entitlements = session.entitlements;
+     * }
+     * ```
+     */
+    getSession(sessionToken: string): Promise<SessionResponse | null>;
+    /**
+     * Create Express middleware that validates session tokens.
+     *
+     * @example
+     * ```typescript
+     * // Protect routes with authentication
+     * app.use('/dashboard', stackbe.auth.middleware({
+     *   getToken: (req) => req.cookies.session,
+     *   onUnauthenticated: (req, res) => res.redirect('/login'),
+     * }));
+     *
+     * app.get('/dashboard', (req, res) => {
+     *   // req.customer is available
+     *   res.json({ email: req.customer.email });
+     * });
+     * ```
+     */
+    middleware(options: {
+        getToken: (req: any) => string | undefined;
+        onUnauthenticated?: (req: any, res: any) => void;
+    }): (req: any, res: any, next: any) => Promise<any>;
+    /**
+     * Check if a session token is valid.
+     *
+     * @example
+     * ```typescript
+     * const isValid = await stackbe.auth.isAuthenticated(sessionToken);
+     * ```
+     */
+    isAuthenticated(sessionToken: string): Promise<boolean>;
+}
+
 declare class StackBE {
     private http;
+    private appId;
     /** Usage tracking and limits */
     readonly usage: UsageClient;
     /** Feature entitlements */
     readonly entitlements: EntitlementsClient;
     /** Customer management */
     readonly customers: CustomersClient;
+    /** Checkout sessions for Stripe */
+    readonly checkout: CheckoutClient;
+    /** Subscription management */
+    readonly subscriptions: SubscriptionsClient;
+    /** Customer authentication (magic links) */
+    readonly auth: AuthClient;
     /**
      * Create a new StackBE client.
      *
@@ -373,8 +699,18 @@ declare class StackBE {
      * // Check entitlements
      * const { hasAccess } = await stackbe.entitlements.check('customer_123', 'premium');
      *
-     * // Get customer
-     * const customer = await stackbe.customers.get('customer_123');
+     * // Create checkout session
+     * const { url } = await stackbe.checkout.createSession({
+     *   customer: 'cust_123',
+     *   planId: 'plan_pro',
+     *   successUrl: 'https://myapp.com/success',
+     * });
+     *
+     * // Get subscription
+     * const subscription = await stackbe.subscriptions.get('cust_123');
+     *
+     * // Send magic link
+     * await stackbe.auth.sendMagicLink('user@example.com');
      * ```
      */
     constructor(config: StackBEConfig);
@@ -445,4 +781,4 @@ declare class StackBE {
     }): (req: any, res: any, next: any) => Promise<any>;
 }
 
-export { type CheckEntitlementResponse, type CheckUsageResponse, type CreateCustomerOptions, type Customer, type CustomerUsageResponse, type CustomerWithSubscription, CustomersClient, EntitlementsClient, type EntitlementsResponse, type MagicLinkResponse, type SessionResponse, StackBE, type StackBEConfig, StackBEError, type StackBEErrorResponse, type Subscription, type TrackUsageOptions, type TrackUsageResponse, type UpdateCustomerOptions, UsageClient, type UsageMetric, type VerifyTokenResponse };
+export { AuthClient, type CancelSubscriptionOptions, type CancelSubscriptionResponse, type CheckEntitlementResponse, type CheckUsageResponse, CheckoutClient, type CheckoutSessionResponse, type CreateCheckoutOptions, type CreateCustomerOptions, type Customer, type CustomerUsageResponse, type CustomerWithSubscription, CustomersClient, EntitlementsClient, type EntitlementsResponse, type MagicLinkOptions, type MagicLinkResponse, type SessionResponse, StackBE, type StackBEConfig, StackBEError, type StackBEErrorResponse, type Subscription, type SubscriptionWithPlan, SubscriptionsClient, type TrackUsageOptions, type TrackUsageResponse, type UpdateCustomerOptions, type UpdateSubscriptionOptions, UsageClient, type UsageMetric, type VerifyTokenResponse };