@stackbe/sdk 0.2.0 → 0.3.0

package/dist/index.d.mts

@@ -121,15 +121,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 +217,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;
@@ -598,19 +719,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 +748,8 @@ declare class AuthClient {
      * 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
@@ -627,9 +758,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 +914,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

@@ -121,15 +121,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 +217,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;
@@ -598,19 +719,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 +748,8 @@ declare class AuthClient {
      * 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
@@ -627,9 +758,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 +914,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 };