@stackbe/sdk 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -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,31 +110,216 @@ 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;
 }
 interface VerifyTokenResponse {
+    success: boolean;
     valid: boolean;
-    customer?: Customer;
-    token?: string;
-    expiresAt?: string;
+    /** Customer ID */
+    customerId: string;
+    /** Customer email */
+    email: string;
+    /** Session JWT token - use this for subsequent authenticated requests */
+    sessionToken: string;
+    /** Tenant ID (your StackBE tenant) */
+    tenantId?: string;
+    /** Organization ID if in org context */
+    organizationId?: string;
+    /** Role in the organization */
+    orgRole?: 'owner' | 'admin' | 'member';
+    /** URL to redirect to after verification */
+    redirectUrl?: string;
 }
 interface SessionResponse {
-    customer: Customer;
+    valid: boolean;
+    /** Customer ID */
+    customerId: string;
+    /** Customer email */
+    email: string;
+    /** Session expiration time */
+    expiresAt?: string;
+    /** Tenant ID (your StackBE tenant) */
+    tenantId?: string;
+    /** Organization ID if in org context */
+    organizationId?: string;
+    /** Role in the organization */
+    orgRole?: 'owner' | 'admin' | 'member';
+    /** Customer details (if included) */
+    customer?: Customer;
+    /** Current subscription (if any) */
     subscription?: Subscription;
-    entitlements: Record<string, boolean | number | string>;
+    /** Feature entitlements */
+    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;
 }
+/**
+ * Error codes returned by StackBE API.
+ * Use these to handle specific error cases in your application.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await stackbe.auth.verifyToken(token);
+ * } catch (error) {
+ *   if (error instanceof StackBEError) {
+ *     switch (error.code) {
+ *       case 'TOKEN_EXPIRED':
+ *         return res.redirect('/login?error=expired');
+ *       case 'TOKEN_ALREADY_USED':
+ *         return res.redirect('/login?error=used');
+ *       case 'SESSION_EXPIRED':
+ *         return res.redirect('/login');
+ *       default:
+ *         return res.status(500).json({ error: 'Authentication failed' });
+ *     }
+ *   }
+ * }
+ * ```
+ */
+type StackBEErrorCode = 'TOKEN_EXPIRED' | 'TOKEN_ALREADY_USED' | 'TOKEN_INVALID' | 'SESSION_EXPIRED' | 'SESSION_INVALID' | 'UNAUTHORIZED' | 'NOT_FOUND' | 'CUSTOMER_NOT_FOUND' | 'SUBSCRIPTION_NOT_FOUND' | 'PLAN_NOT_FOUND' | 'APP_NOT_FOUND' | 'VALIDATION_ERROR' | 'MISSING_REQUIRED_FIELD' | 'INVALID_EMAIL' | 'USAGE_LIMIT_EXCEEDED' | 'METRIC_NOT_FOUND' | 'FEATURE_NOT_AVAILABLE' | 'NO_ACTIVE_SUBSCRIPTION' | 'TIMEOUT' | 'NETWORK_ERROR' | 'UNKNOWN_ERROR';
 interface StackBEErrorResponse {
     statusCode: number;
     message: string;
     error: string;
+    code?: StackBEErrorCode;
 }
 declare class StackBEError extends Error {
     readonly statusCode: number;
-    readonly code: string;
-    constructor(message: string, statusCode: number, code: string);
+    readonly code: StackBEErrorCode;
+    constructor(message: string, statusCode: number, code: StackBEErrorCode | string);
+    /** Check if this is a specific error type */
+    is(code: StackBEErrorCode): boolean;
+    /** Check if this is an auth-related error */
+    isAuthError(): boolean;
+    /** Check if this is a "not found" error */
+    isNotFoundError(): boolean;
 }
+/**
+ * Webhook event types emitted by StackBE.
+ * Subscribe to these events to react to changes in your customers' subscriptions.
+ */
+type WebhookEventType = 'subscription_created' | 'subscription_updated' | 'subscription_cancelled' | 'subscription_renewed' | 'trial_started' | 'trial_ended' | 'payment_succeeded' | 'payment_failed' | 'customer_created' | 'customer_updated';
+/** Base webhook event structure */
+interface WebhookEvent<T extends WebhookEventType = WebhookEventType, P = unknown> {
+    /** Event ID */
+    id: string;
+    /** Event type */
+    type: T;
+    /** Tenant ID */
+    tenantId: string;
+    /** App ID */
+    appId: string;
+    /** Event payload */
+    data: P;
+    /** When the event was created */
+    createdAt: string;
+}
+/** Subscription webhook payload */
+interface SubscriptionWebhookPayload {
+    id: string;
+    customerId: string;
+    planId: string;
+    planName: string;
+    status: 'active' | 'canceled' | 'past_due' | 'trialing' | 'paused';
+    currentPeriodStart: string;
+    currentPeriodEnd: string;
+    cancelAtPeriodEnd: boolean;
+    trialEnd?: string;
+}
+/** Customer webhook payload */
+interface CustomerWebhookPayload {
+    id: string;
+    email: string;
+    name?: string;
+    metadata?: Record<string, unknown>;
+}
+/** Payment webhook payload */
+interface PaymentWebhookPayload {
+    id: string;
+    subscriptionId: string;
+    customerId: string;
+    amount: number;
+    currency: string;
+    status: 'succeeded' | 'failed';
+    failureReason?: string;
+}
+type SubscriptionCreatedEvent = WebhookEvent<'subscription_created', SubscriptionWebhookPayload>;
+type SubscriptionUpdatedEvent = WebhookEvent<'subscription_updated', SubscriptionWebhookPayload>;
+type SubscriptionCancelledEvent = WebhookEvent<'subscription_cancelled', SubscriptionWebhookPayload>;
+type SubscriptionRenewedEvent = WebhookEvent<'subscription_renewed', SubscriptionWebhookPayload>;
+type TrialStartedEvent = WebhookEvent<'trial_started', SubscriptionWebhookPayload>;
+type TrialEndedEvent = WebhookEvent<'trial_ended', SubscriptionWebhookPayload>;
+type PaymentSucceededEvent = WebhookEvent<'payment_succeeded', PaymentWebhookPayload>;
+type PaymentFailedEvent = WebhookEvent<'payment_failed', PaymentWebhookPayload>;
+type CustomerCreatedEvent = WebhookEvent<'customer_created', CustomerWebhookPayload>;
+type CustomerUpdatedEvent = WebhookEvent<'customer_updated', CustomerWebhookPayload>;
+/** Union of all webhook event types */
+type AnyWebhookEvent = SubscriptionCreatedEvent | SubscriptionUpdatedEvent | SubscriptionCancelledEvent | SubscriptionRenewedEvent | TrialStartedEvent | TrialEndedEvent | PaymentSucceededEvent | PaymentFailedEvent | CustomerCreatedEvent | CustomerUpdatedEvent;
 
 declare class UsageClient {
     private http;
@@ -347,14 +533,287 @@ 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.
+     *
+     * Returns the session token along with tenant and organization context.
+     *
+     * @example
+     * ```typescript
+     * // In your /verify route handler
+     * const { token } = req.query;
+     *
+     * try {
+     *   const result = await stackbe.auth.verifyToken(token);
+     *
+     *   // result includes: customerId, email, sessionToken, tenantId, organizationId
+     *   res.cookie('session', result.sessionToken, { httpOnly: true });
+     *   res.redirect('/dashboard');
+     * } catch (error) {
+     *   if (error instanceof StackBEError) {
+     *     if (error.code === 'TOKEN_EXPIRED') {
+     *       res.redirect('/login?error=expired');
+     *     } else if (error.code === 'TOKEN_ALREADY_USED') {
+     *       res.redirect('/login?error=used');
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    verifyToken(token: string): Promise<VerifyTokenResponse>;
+    /**
+     * Get the current session for an authenticated customer.
+     * Use this to validate session tokens and get customer data.
+     *
+     * Returns session info including tenant and organization context extracted from the JWT.
+     *
+     * @example
+     * ```typescript
+     * // Validate session on each request
+     * const sessionToken = req.cookies.session;
+     *
+     * const session = await stackbe.auth.getSession(sessionToken);
+     *
+     * if (session) {
+     *   console.log(session.customerId);
+     *   console.log(session.tenantId);       // Tenant context
+     *   console.log(session.organizationId); // Org context (if applicable)
+     *   console.log(session.subscription);
+     *   console.log(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 +832,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 +914,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 { type AnyWebhookEvent, AuthClient, type CancelSubscriptionOptions, type CancelSubscriptionResponse, type CheckEntitlementResponse, type CheckUsageResponse, CheckoutClient, type CheckoutSessionResponse, type CreateCheckoutOptions, type CreateCustomerOptions, type Customer, type CustomerCreatedEvent, type CustomerUpdatedEvent, type CustomerUsageResponse, type CustomerWebhookPayload, type CustomerWithSubscription, CustomersClient, EntitlementsClient, type EntitlementsResponse, type MagicLinkOptions, type MagicLinkResponse, type PaymentFailedEvent, type PaymentSucceededEvent, type PaymentWebhookPayload, type SessionResponse, StackBE, type StackBEConfig, StackBEError, type StackBEErrorCode, type StackBEErrorResponse, type Subscription, type SubscriptionCancelledEvent, type SubscriptionCreatedEvent, type SubscriptionRenewedEvent, type SubscriptionUpdatedEvent, type SubscriptionWebhookPayload, type SubscriptionWithPlan, SubscriptionsClient, type TrackUsageOptions, type TrackUsageResponse, type TrialEndedEvent, type TrialStartedEvent, type UpdateCustomerOptions, type UpdateSubscriptionOptions, UsageClient, type UsageMetric, type VerifyTokenResponse, type WebhookEvent, type WebhookEventType };