@stackbe/sdk 0.6.4 → 0.7.1

package/README.md

@@ -200,6 +200,64 @@ if (session) {
 const isAuthenticated = await stackbe.auth.isAuthenticated(sessionToken);
 ```
 
+### Plans & Products
+
+List available pricing plans for your pricing page:
+
+```typescript
+// List all plans
+const plans = await stackbe.plans.list();
+
+// List active plans sorted by price
+const plans = await stackbe.plans.listByPrice();
+// [Free ($0), Starter ($9), Pro ($29), Enterprise ($99)]
+
+// Filter by product
+const plans = await stackbe.plans.list({ productId: 'prod_123' });
+
+// Get a specific plan
+const plan = await stackbe.plans.get('plan_123');
+console.log(plan.name, plan.priceCents, plan.entitlements);
+
+// List products
+const products = await stackbe.products.list();
+
+// Get product details
+const product = await stackbe.products.get('prod_123');
+```
+
+#### Dynamic Pricing Page Example
+
+```typescript
+// Next.js pricing page
+export default async function PricingPage() {
+  const plans = await stackbe.plans.listByPrice();
+
+  return (
+    <div className="grid grid-cols-3 gap-4">
+      {plans.map((plan) => (
+        <div key={plan.id} className="border p-4 rounded">
+          <h3>{plan.name}</h3>
+          <p className="text-2xl">
+            ${plan.priceCents / 100}/{plan.interval}
+          </p>
+          <ul>
+            {Object.entries(plan.entitlements).map(([key, value]) => (
+              <li key={key}>
+                {key}: {value === true ? '✓' : value}
+              </li>
+            ))}
+          </ul>
+          <a href={`/checkout?plan=${plan.id}`}>
+            {plan.priceCents === 0 ? 'Start Free' : 'Subscribe'}
+          </a>
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
 ### Customer Management
 
 ```typescript
@@ -226,6 +284,76 @@ const customer = await stackbe.customers.getOrCreate({
 await stackbe.customers.update('cust_123', { name: 'Jane Doe' });
 ```
 
+### Organizations (B2B Multi-User)
+
+Manage customer organizations for B2B apps:
+
+```typescript
+// Create organization with customer as owner
+const org = await stackbe.organizations.create({
+  name: 'Acme Corp',
+  ownerId: customer.id,
+});
+
+// List all organizations
+const orgs = await stackbe.organizations.list();
+
+// Get organization by ID
+const org = await stackbe.organizations.get('org_123');
+
+// Update organization
+await stackbe.organizations.update('org_123', { name: 'New Name' });
+
+// Delete organization (must have no active subscriptions)
+await stackbe.organizations.delete('org_123');
+
+// Add member to organization
+await stackbe.organizations.addMember('org_123', {
+  customerId: 'cust_456',
+  role: 'member', // 'admin' | 'member'
+});
+
+// Remove member
+await stackbe.organizations.removeMember('org_123', 'member_456');
+
+// Update member role
+await stackbe.organizations.updateMember('org_123', 'member_456', {
+  role: 'admin',
+});
+
+// Invite by email
+await stackbe.organizations.invite('org_123', {
+  email: 'newuser@company.com',
+  role: 'member',
+});
+
+// List pending invites
+const invites = await stackbe.organizations.listInvites('org_123');
+
+// Cancel invite
+await stackbe.organizations.cancelInvite('org_123', 'invite_456');
+```
+
+#### B2B Signup Flow
+
+```typescript
+async function signup(email: string, orgName: string) {
+  // 1. Get or create customer
+  const customer = await stackbe.customers.getOrCreate({ email });
+
+  // 2. Create organization with customer as owner
+  const org = await stackbe.organizations.create({
+    name: orgName,
+    ownerId: customer.id,
+  });
+
+  // 3. Send magic link
+  await stackbe.auth.sendMagicLink(email);
+
+  return { customer, org };
+}
+```
+
 ## Express Middleware
 
 ### Track Usage Automatically
@@ -421,9 +549,22 @@ stackbe.auth.invalidateSession(token);
 stackbe.auth.clearCache(); // Clear all
 ```
 
-### Environment-Aware Redirects
+### Magic Link Callback URLs
 
-Auto-detect development environment for magic link redirects:
+**Recommended approach**: Pass the callback URL explicitly for maximum reliability:
+
+```typescript
+// Determine callback URL based on your environment
+const callbackUrl = process.env.NODE_ENV === 'production'
+  ? 'https://myapp.com/auth/callback'
+  : 'http://localhost:3000/auth/callback';
+
+await stackbe.auth.sendMagicLink('user@example.com', {
+  redirectUrl: callbackUrl,
+});
+```
+
+**Alternative**: Use `devCallbackUrl` for automatic detection (uses `devCallbackUrl` when `NODE_ENV !== 'production'`):
 
 ```typescript
 const stackbe = new StackBE({
@@ -432,17 +573,18 @@ const stackbe = new StackBE({
   devCallbackUrl: 'http://localhost:3000/auth/callback',
 });
 
-// In development (NODE_ENV !== 'production'), uses devCallbackUrl automatically
+// In development, uses devCallbackUrl automatically
 await stackbe.auth.sendMagicLink('user@example.com');
-// Redirects to: http://localhost:3000/auth/callback
 
-// In production, uses your configured auth callback URL
-// Or pass explicit redirectUrl to override
-await stackbe.auth.sendMagicLink('user@example.com', {
-  redirectUrl: 'https://myapp.com/custom-callback',
-});
+// In production, falls back to app settings callback URL
+// Explicit redirectUrl always takes priority if provided
 ```
 
+**Notes:**
+- `devCallbackUrl` only activates when `NODE_ENV !== 'production'`
+- Explicit `redirectUrl` parameter always takes priority
+- For predictable behavior, use the explicit approach above
+
 ## Webhooks
 
 Typed webhook payloads for handling StackBE events:

package/dist/index.d.mts

@@ -304,8 +304,43 @@ interface OrganizationInvite {
     status: 'pending' | 'accepted' | 'cancelled';
     sentAt: string;
 }
+interface Plan {
+    id: string;
+    name: string;
+    slug: string;
+    description?: string;
+    priceCents: number;
+    currency: string;
+    interval: 'month' | 'year';
+    trialDays?: number;
+    entitlements: Record<string, boolean | number | string>;
+    status: 'active' | 'archived';
+    requirePaymentMethod: boolean;
+    productId: string;
+    product?: Product;
+    createdAt: string;
+    updatedAt: string;
+}
+interface Product {
+    id: string;
+    name: string;
+    slug: string;
+    description?: string;
+    appId: string;
+    plans?: Plan[];
+    createdAt: string;
+    updatedAt: string;
+}
+interface ListPlansOptions {
+    /** Filter by product ID */
+    productId?: string;
+}
+interface ListProductsOptions {
+    /** Filter by app ID (defaults to SDK appId) */
+    appId?: string;
+}
 interface CreateCheckoutOptions {
-    /** Customer ID or email */
+    /** Customer ID or object with email. Use string for existing customer ID, object for email-based lookup/creation */
     customer: string | {
         email: string;
         name?: string;
@@ -316,6 +351,8 @@ interface CreateCheckoutOptions {
     successUrl: string;
     /** URL to redirect if checkout is canceled */
     cancelUrl?: string;
+    /** Organization ID for org-level subscriptions. Customer must be owner/admin of the org. */
+    organizationId?: string;
     /** Allow promotion codes */
     allowPromotionCodes?: boolean;
     /** Trial period in days */
@@ -790,7 +827,7 @@ declare class CheckoutClient {
      *
      * @example
      * ```typescript
-     * // With new customer (will be created)
+     * // With customer email (looks up or creates customer)
      * const { url } = await stackbe.checkout.createSession({
      *   customer: { email: 'user@example.com', name: 'John' },
      *   planId: 'plan_pro_monthly',
@@ -798,6 +835,18 @@ declare class CheckoutClient {
      *   trialDays: 14,
      * });
      * ```
+     *
+     * @example
+     * ```typescript
+     * // Organization-level subscription (B2B)
+     * const { url } = await stackbe.checkout.createSession({
+     *   customer: 'cust_123',
+     *   organizationId: 'org_456',  // Customer must be owner/admin
+     *   planId: 'plan_team',
+     *   successUrl: 'https://myapp.com/success',
+     *   cancelUrl: 'https://myapp.com/pricing',
+     * });
+     * ```
      */
     createSession(options: CreateCheckoutOptions): Promise<CheckoutSessionResponse>;
     /**
@@ -1230,6 +1279,342 @@ declare class OrganizationsClient {
     cancelInvite(orgId: string, inviteId: string): Promise<void>;
 }
 
+/**
+ * Client for managing plans and products.
+ * Use this to list available pricing plans for display in your pricing page.
+ *
+ * @example
+ * ```typescript
+ * // List all plans
+ * const plans = await stackbe.plans.list();
+ *
+ * // List plans for a specific product
+ * const plans = await stackbe.plans.list({ productId: 'prod_123' });
+ *
+ * // Get a specific plan
+ * const plan = await stackbe.plans.get('plan_123');
+ *
+ * // List products
+ * const products = await stackbe.products.list();
+ * ```
+ */
+declare class PlansClient {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * List all plans for the app.
+     *
+     * @example
+     * ```typescript
+     * // List all plans
+     * const plans = await stackbe.plans.list();
+     *
+     * // Filter by product
+     * const plans = await stackbe.plans.list({ productId: 'prod_123' });
+     *
+     * // Display in pricing page
+     * plans.forEach(plan => {
+     *   console.log(`${plan.name}: $${plan.priceCents / 100}/${plan.interval}`);
+     * });
+     * ```
+     */
+    list(options?: ListPlansOptions): Promise<Plan[]>;
+    /**
+     * Get a plan by ID.
+     *
+     * @example
+     * ```typescript
+     * const plan = await stackbe.plans.get('plan_123');
+     * console.log(plan.name, plan.priceCents, plan.entitlements);
+     * ```
+     */
+    get(planId: string): Promise<Plan>;
+    /**
+     * Get active plans only (excludes archived plans).
+     *
+     * @example
+     * ```typescript
+     * const activePlans = await stackbe.plans.getActive();
+     * ```
+     */
+    getActive(options?: ListPlansOptions): Promise<Plan[]>;
+    /**
+     * Get plans sorted by price (ascending).
+     *
+     * @example
+     * ```typescript
+     * const plans = await stackbe.plans.listByPrice();
+     * // [Free, Starter, Pro, Enterprise]
+     * ```
+     */
+    listByPrice(options?: ListPlansOptions): Promise<Plan[]>;
+}
+/**
+ * Client for managing products.
+ *
+ * @example
+ * ```typescript
+ * // List all products
+ * const products = await stackbe.products.list();
+ *
+ * // Get a specific product
+ * const product = await stackbe.products.get('prod_123');
+ * ```
+ */
+declare class ProductsClient {
+    private readonly http;
+    private readonly appId;
+    constructor(http: HttpClient, appId: string);
+    /**
+     * List all products for the app.
+     *
+     * @example
+     * ```typescript
+     * const products = await stackbe.products.list();
+     * products.forEach(product => {
+     *   console.log(product.name, product.plans?.length, 'plans');
+     * });
+     * ```
+     */
+    list(options?: ListProductsOptions): Promise<Product[]>;
+    /**
+     * Get a product by ID.
+     *
+     * @example
+     * ```typescript
+     * const product = await stackbe.products.get('prod_123');
+     * console.log(product.name, product.description);
+     * ```
+     */
+    get(productId: string): Promise<Product>;
+}
+
+interface FeatureRequest {
+    id: string;
+    title: string;
+    description?: string;
+    status: 'new' | 'under_review' | 'planned' | 'in_progress' | 'completed' | 'declined';
+    category?: string;
+    authorId: string;
+    authorEmail: string;
+    voteCount: number;
+    hasVoted?: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+interface FeatureRequestComment {
+    id: string;
+    customerEmail: string;
+    content: string;
+    isAdminReply: boolean;
+    createdAt: string;
+}
+interface CreateFeatureRequestOptions {
+    title: string;
+    description?: string;
+    category?: string;
+}
+interface ListFeatureRequestsOptions {
+    status?: 'new' | 'under_review' | 'planned' | 'in_progress' | 'completed' | 'declined';
+    category?: string;
+    sortBy?: 'newest' | 'votes' | 'recent_activity';
+    limit?: number;
+    offset?: number;
+}
+interface FeatureRequestListResponse {
+    data: FeatureRequest[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+interface InterestedCustomer {
+    customerId: string;
+    email: string;
+    votedAt?: string;
+    submittedAt?: string;
+}
+interface InterestedCustomersResponse {
+    featureRequestId: string;
+    title: string;
+    status: string;
+    author: {
+        customerId: string;
+        email: string;
+        submittedAt: string;
+    };
+    voters: InterestedCustomer[];
+    totalInterested: number;
+}
+interface CustomerFeatureActivity {
+    customerId: string;
+    submitted: Array<{
+        id: string;
+        title: string;
+        status: string;
+        voteCount: number;
+        submittedAt: string;
+    }>;
+    votedOn: Array<{
+        id: string;
+        title: string;
+        status: string;
+        voteCount: number;
+        votedAt: string;
+    }>;
+    totalSubmitted: number;
+    totalVotes: number;
+}
+declare class FeatureRequestsClient {
+    private http;
+    private appId;
+    constructor(http: HttpClient, appId: string);
+    /**
+     * List feature requests for the app.
+     *
+     * @example
+     * ```typescript
+     * // Get all feature requests
+     * const { data, total } = await stackbe.featureRequests.list();
+     *
+     * // Filter by status
+     * const planned = await stackbe.featureRequests.list({ status: 'planned' });
+     *
+     * // Sort by votes
+     * const popular = await stackbe.featureRequests.list({ sortBy: 'votes' });
+     * ```
+     */
+    list(options?: ListFeatureRequestsOptions): Promise<FeatureRequestListResponse>;
+    /**
+     * Submit a new feature request.
+     * Requires customer session token.
+     *
+     * @example
+     * ```typescript
+     * const request = await stackbe.featureRequests.create({
+     *   title: 'Dark mode support',
+     *   description: 'Would love to have a dark theme option',
+     *   category: 'UI',
+     * });
+     * ```
+     */
+    create(options: CreateFeatureRequestOptions): Promise<FeatureRequest>;
+    /**
+     * Get a specific feature request by ID.
+     *
+     * @example
+     * ```typescript
+     * const request = await stackbe.featureRequests.get('req_123');
+     * console.log(`${request.title} has ${request.voteCount} votes`);
+     * ```
+     */
+    get(requestId: string): Promise<FeatureRequest & {
+        comments: FeatureRequestComment[];
+    }>;
+    /**
+     * Upvote a feature request.
+     * Requires customer session token. Idempotent.
+     *
+     * @example
+     * ```typescript
+     * await stackbe.featureRequests.vote('req_123');
+     * ```
+     */
+    vote(requestId: string): Promise<{
+        success?: boolean;
+        alreadyVoted?: boolean;
+        voteCount: number;
+    }>;
+    /**
+     * Remove your vote from a feature request.
+     * Requires customer session token.
+     *
+     * @example
+     * ```typescript
+     * await stackbe.featureRequests.removeVote('req_123');
+     * ```
+     */
+    removeVote(requestId: string): Promise<{
+        success: boolean;
+        voteCount: number;
+    }>;
+    /**
+     * Add a comment to a feature request.
+     * Requires customer session token.
+     *
+     * @example
+     * ```typescript
+     * await stackbe.featureRequests.addComment('req_123', {
+     *   content: 'This would be really helpful for my workflow!',
+     * });
+     * ```
+     */
+    addComment(requestId: string, options: {
+        content: string;
+    }): Promise<FeatureRequestComment>;
+    /**
+     * Update a feature request status or category.
+     * Requires API key (admin).
+     *
+     * @example
+     * ```typescript
+     * await stackbe.featureRequests.update('req_123', {
+     *   status: 'planned',
+     *   category: 'Core Features',
+     * });
+     * ```
+     */
+    update(requestId: string, options: {
+        status?: string;
+        category?: string;
+    }): Promise<FeatureRequest>;
+    /**
+     * Delete a feature request.
+     * Requires API key (admin).
+     *
+     * @example
+     * ```typescript
+     * await stackbe.featureRequests.delete('req_123');
+     * ```
+     */
+    delete(requestId: string): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Get all customers interested in a feature request (author + voters).
+     * Useful for user research or notifying users when the feature ships.
+     * Requires API key (admin).
+     *
+     * @example
+     * ```typescript
+     * const { author, voters, totalInterested } = await stackbe.featureRequests.getInterestedCustomers('req_123');
+     *
+     * // Notify all interested users
+     * const emails = [author.email, ...voters.map(v => v.email)];
+     * await sendNotification(emails, 'Your requested feature is now live!');
+     * ```
+     */
+    getInterestedCustomers(requestId: string): Promise<InterestedCustomersResponse>;
+    /**
+     * Get a customer's feature request activity (requests submitted + votes).
+     * Useful for displaying on customer profile.
+     * Requires API key (admin).
+     *
+     * @example
+     * ```typescript
+     * const activity = await stackbe.featureRequests.getCustomerActivity('cust_123');
+     *
+     * console.log(`Submitted ${activity.totalSubmitted} requests`);
+     * console.log(`Voted on ${activity.totalVotes} requests`);
+     *
+     * // Show their most wanted features
+     * activity.votedOn.forEach(r => {
+     *   console.log(`- ${r.title} (${r.status})`);
+     * });
+     * ```
+     */
+    getCustomerActivity(customerId: string): Promise<CustomerFeatureActivity>;
+}
+
 declare class StackBE {
     private http;
     private appId;
@@ -1247,6 +1632,12 @@ declare class StackBE {
     readonly auth: AuthClient;
     /** Organization management (B2B multi-user) */
     readonly organizations: OrganizationsClient;
+    /** Pricing plans */
+    readonly plans: PlansClient;
+    /** Products */
+    readonly products: ProductsClient;
+    /** Feature requests and voting */
+    readonly featureRequests: FeatureRequestsClient;
     /**
      * Create a new StackBE client.
      *
@@ -1347,4 +1738,4 @@ declare class StackBE {
     }): (req: any, res: any, next: any) => Promise<any>;
 }
 
-export { type AddMemberOptions, type AnyWebhookEvent, AuthClient, type CancelSubscriptionOptions, type CancelSubscriptionResponse, type CheckEntitlementResponse, type CheckUsageResponse, CheckoutClient, type CheckoutSessionResponse, type CreateCheckoutOptions, type CreateCustomerOptions, type CreateOrganizationOptions, type Customer, type CustomerCreatedEvent, type CustomerUpdatedEvent, type CustomerUsageResponse, type CustomerWebhookPayload, type CustomerWithSubscription, CustomersClient, EntitlementsClient, type EntitlementsResponse, type InviteMemberOptions, type MagicLinkOptions, type MagicLinkResponse, type Organization, type OrganizationInvite, type OrganizationMember, OrganizationsClient, 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 UpdateOrganizationOptions, type UpdateSubscriptionOptions, UsageClient, type UsageMetric, type VerifyTokenResponse, type WebhookEvent, type WebhookEventType };
+export { type AddMemberOptions, type AnyWebhookEvent, AuthClient, type CancelSubscriptionOptions, type CancelSubscriptionResponse, type CheckEntitlementResponse, type CheckUsageResponse, CheckoutClient, type CheckoutSessionResponse, type CreateCheckoutOptions, type CreateCustomerOptions, type CreateFeatureRequestOptions, type CreateOrganizationOptions, type Customer, type CustomerCreatedEvent, type CustomerFeatureActivity, type CustomerUpdatedEvent, type CustomerUsageResponse, type CustomerWebhookPayload, type CustomerWithSubscription, CustomersClient, EntitlementsClient, type EntitlementsResponse, type FeatureRequest, type FeatureRequestComment, type FeatureRequestListResponse, FeatureRequestsClient, type InterestedCustomer, type InterestedCustomersResponse, type InviteMemberOptions, type ListFeatureRequestsOptions, type ListPlansOptions, type ListProductsOptions, type MagicLinkOptions, type MagicLinkResponse, type Organization, type OrganizationInvite, type OrganizationMember, OrganizationsClient, type PaymentFailedEvent, type PaymentSucceededEvent, type PaymentWebhookPayload, type Plan, PlansClient, type Product, ProductsClient, 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 UpdateOrganizationOptions, type UpdateSubscriptionOptions, UsageClient, type UsageMetric, type VerifyTokenResponse, type WebhookEvent, type WebhookEventType };