@stackbe/sdk 0.2.0 → 0.4.0

package/dist/index.d.mts

@@ -24,6 +24,30 @@ interface StackBEConfig {
     baseUrl?: string;
     /** Request timeout in milliseconds (default: 30000) */
     timeout?: number;
+    /**
+     * Session cache TTL in seconds (default: 0 = disabled).
+     * When set, getSession() results are cached to reduce API calls.
+     * @example
+     * ```typescript
+     * new StackBE({ apiKey, appId, sessionCacheTTL: 120 }) // Cache for 2 minutes
+     * ```
+     */
+    sessionCacheTTL?: number;
+    /**
+     * Development callback URL for magic link redirects.
+     * When set, this URL is used automatically when:
+     * - NODE_ENV !== 'production', or
+     * - useDev: true is passed to sendMagicLink()
+     * @example
+     * ```typescript
+     * new StackBE({
+     *   apiKey,
+     *   appId,
+     *   devCallbackUrl: 'http://localhost:3000/auth/callback'
+     * })
+     * ```
+     */
+    devCallbackUrl?: string;
 }
 interface TrackUsageOptions {
     /** Quantity to track (default: 1) */
@@ -121,15 +145,43 @@ interface MagicLinkResponse {
     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 */
@@ -189,16 +241,109 @@ interface UpdateSubscriptionOptions {
     /** 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;
@@ -570,13 +715,37 @@ declare class SubscriptionsClient {
     isActive(customerId: string): Promise<boolean>;
 }
 
+interface AuthClientOptions {
+    /** Session cache TTL in seconds (0 = disabled) */
+    sessionCacheTTL?: number;
+    /** Development callback URL for magic links */
+    devCallbackUrl?: string;
+}
 declare class AuthClient {
     private http;
     private appId;
-    constructor(http: HttpClient, appId: string);
+    private sessionCache;
+    private sessionCacheTTL;
+    private devCallbackUrl?;
+    constructor(http: HttpClient, appId: string, options?: AuthClientOptions);
+    /**
+     * Check if we're in a development environment.
+     */
+    private isDev;
+    /**
+     * Clear the session cache (useful for testing or logout).
+     */
+    clearCache(): void;
+    /**
+     * Remove a specific session from the cache.
+     */
+    invalidateSession(sessionToken: string): void;
     /**
      * Send a magic link email to a customer for passwordless authentication.
      *
+     * If `devCallbackUrl` is configured and we're in a dev environment (NODE_ENV !== 'production'),
+     * the dev callback URL will be used automatically.
+     *
      * @example
      * ```typescript
      * // Send magic link
@@ -587,7 +756,7 @@ declare class AuthClient {
      *   redirectUrl: 'https://myapp.com/dashboard',
      * });
      *
-     * // For localhost development
+     * // For localhost development (auto-detected if devCallbackUrl is configured)
      * await stackbe.auth.sendMagicLink('user@example.com', {
      *   useDev: true,
      * });
@@ -598,19 +767,27 @@ declare class AuthClient {
      * 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;
      *
-     * const result = await stackbe.auth.verifyToken(token);
+     * try {
+     *   const result = await stackbe.auth.verifyToken(token);
      *
-     * if (result.valid) {
-     *   // Set session cookie
-     *   res.cookie('session', result.token, { httpOnly: true });
+     *   // result includes: customerId, email, sessionToken, tenantId, organizationId
+     *   res.cookie('session', result.sessionToken, { httpOnly: true });
      *   res.redirect('/dashboard');
-     * } else {
-     *   res.redirect('/login?error=invalid_token');
+     * } 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');
+     *     }
+     *   }
      * }
      * ```
      */
@@ -619,6 +796,11 @@ declare class AuthClient {
      * Get the current session for an authenticated customer.
      * Use this to validate session tokens and get customer data.
      *
+     * If `sessionCacheTTL` is configured, results are cached to reduce API calls.
+     * Use `invalidateSession()` or `clearCache()` to manually clear cached sessions.
+     *
+     * Returns session info including tenant and organization context extracted from the JWT.
+     *
      * @example
      * ```typescript
      * // Validate session on each request
@@ -627,9 +809,11 @@ declare class AuthClient {
      * const session = await stackbe.auth.getSession(sessionToken);
      *
      * if (session) {
-     *   req.customer = session.customer;
-     *   req.subscription = session.subscription;
-     *   req.entitlements = session.entitlements;
+     *   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);
      * }
      * ```
      */
@@ -781,4 +965,4 @@ declare class StackBE {
     }): (req: any, res: any, next: any) => Promise<any>;
 }
 
-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 };
+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 };

package/dist/index.d.ts

@@ -24,6 +24,30 @@ interface StackBEConfig {
     baseUrl?: string;
     /** Request timeout in milliseconds (default: 30000) */
     timeout?: number;
+    /**
+     * Session cache TTL in seconds (default: 0 = disabled).
+     * When set, getSession() results are cached to reduce API calls.
+     * @example
+     * ```typescript
+     * new StackBE({ apiKey, appId, sessionCacheTTL: 120 }) // Cache for 2 minutes
+     * ```
+     */
+    sessionCacheTTL?: number;
+    /**
+     * Development callback URL for magic link redirects.
+     * When set, this URL is used automatically when:
+     * - NODE_ENV !== 'production', or
+     * - useDev: true is passed to sendMagicLink()
+     * @example
+     * ```typescript
+     * new StackBE({
+     *   apiKey,
+     *   appId,
+     *   devCallbackUrl: 'http://localhost:3000/auth/callback'
+     * })
+     * ```
+     */
+    devCallbackUrl?: string;
 }
 interface TrackUsageOptions {
     /** Quantity to track (default: 1) */
@@ -121,15 +145,43 @@ interface MagicLinkResponse {
     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 */
@@ -189,16 +241,109 @@ interface UpdateSubscriptionOptions {
     /** 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;
@@ -570,13 +715,37 @@ declare class SubscriptionsClient {
     isActive(customerId: string): Promise<boolean>;
 }
 
+interface AuthClientOptions {
+    /** Session cache TTL in seconds (0 = disabled) */
+    sessionCacheTTL?: number;
+    /** Development callback URL for magic links */
+    devCallbackUrl?: string;
+}
 declare class AuthClient {
     private http;
     private appId;
-    constructor(http: HttpClient, appId: string);
+    private sessionCache;
+    private sessionCacheTTL;
+    private devCallbackUrl?;
+    constructor(http: HttpClient, appId: string, options?: AuthClientOptions);
+    /**
+     * Check if we're in a development environment.
+     */
+    private isDev;
+    /**
+     * Clear the session cache (useful for testing or logout).
+     */
+    clearCache(): void;
+    /**
+     * Remove a specific session from the cache.
+     */
+    invalidateSession(sessionToken: string): void;
     /**
      * Send a magic link email to a customer for passwordless authentication.
      *
+     * If `devCallbackUrl` is configured and we're in a dev environment (NODE_ENV !== 'production'),
+     * the dev callback URL will be used automatically.
+     *
      * @example
      * ```typescript
      * // Send magic link
@@ -587,7 +756,7 @@ declare class AuthClient {
      *   redirectUrl: 'https://myapp.com/dashboard',
      * });
      *
-     * // For localhost development
+     * // For localhost development (auto-detected if devCallbackUrl is configured)
      * await stackbe.auth.sendMagicLink('user@example.com', {
      *   useDev: true,
      * });
@@ -598,19 +767,27 @@ declare class AuthClient {
      * 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;
      *
-     * const result = await stackbe.auth.verifyToken(token);
+     * try {
+     *   const result = await stackbe.auth.verifyToken(token);
      *
-     * if (result.valid) {
-     *   // Set session cookie
-     *   res.cookie('session', result.token, { httpOnly: true });
+     *   // result includes: customerId, email, sessionToken, tenantId, organizationId
+     *   res.cookie('session', result.sessionToken, { httpOnly: true });
      *   res.redirect('/dashboard');
-     * } else {
-     *   res.redirect('/login?error=invalid_token');
+     * } 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');
+     *     }
+     *   }
      * }
      * ```
      */
@@ -619,6 +796,11 @@ declare class AuthClient {
      * Get the current session for an authenticated customer.
      * Use this to validate session tokens and get customer data.
      *
+     * If `sessionCacheTTL` is configured, results are cached to reduce API calls.
+     * Use `invalidateSession()` or `clearCache()` to manually clear cached sessions.
+     *
+     * Returns session info including tenant and organization context extracted from the JWT.
+     *
      * @example
      * ```typescript
      * // Validate session on each request
@@ -627,9 +809,11 @@ declare class AuthClient {
      * const session = await stackbe.auth.getSession(sessionToken);
      *
      * if (session) {
-     *   req.customer = session.customer;
-     *   req.subscription = session.subscription;
-     *   req.entitlements = session.entitlements;
+     *   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);
      * }
      * ```
      */
@@ -781,4 +965,4 @@ declare class StackBE {
     }): (req: any, res: any, next: any) => Promise<any>;
 }
 
-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 };
+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 };