@stackbe/sdk 0.1.0 → 0.3.0

package/dist/index.mjs

@@ -6,13 +6,69 @@ var StackBEError = class extends Error {
     this.statusCode = statusCode;
     this.code = code;
   }
+  /** Check if this is a specific error type */
+  is(code) {
+    return this.code === code;
+  }
+  /** Check if this is an auth-related error */
+  isAuthError() {
+    return [
+      "TOKEN_EXPIRED",
+      "TOKEN_ALREADY_USED",
+      "TOKEN_INVALID",
+      "SESSION_EXPIRED",
+      "SESSION_INVALID",
+      "UNAUTHORIZED"
+    ].includes(this.code);
+  }
+  /** Check if this is a "not found" error */
+  isNotFoundError() {
+    return [
+      "NOT_FOUND",
+      "CUSTOMER_NOT_FOUND",
+      "SUBSCRIPTION_NOT_FOUND",
+      "PLAN_NOT_FOUND",
+      "APP_NOT_FOUND"
+    ].includes(this.code);
+  }
 };
 
 // src/http.ts
+function mapErrorCode(status, message, errorType) {
+  if (errorType && errorType !== "Error") {
+    const codeFromError = errorType.toUpperCase().replace(/\s+/g, "_");
+    if (codeFromError.includes("NOT_FOUND")) return "NOT_FOUND";
+    if (codeFromError.includes("UNAUTHORIZED")) return "UNAUTHORIZED";
+  }
+  const lowerMessage = message.toLowerCase();
+  if (lowerMessage.includes("token") && lowerMessage.includes("expired")) return "TOKEN_EXPIRED";
+  if (lowerMessage.includes("already been used")) return "TOKEN_ALREADY_USED";
+  if (lowerMessage.includes("invalid") && lowerMessage.includes("token")) return "TOKEN_INVALID";
+  if (lowerMessage.includes("session") && lowerMessage.includes("expired")) return "SESSION_EXPIRED";
+  if (lowerMessage.includes("session") && lowerMessage.includes("invalid")) return "SESSION_INVALID";
+  if (lowerMessage.includes("customer") && lowerMessage.includes("not found")) return "CUSTOMER_NOT_FOUND";
+  if (lowerMessage.includes("subscription") && lowerMessage.includes("not found")) return "SUBSCRIPTION_NOT_FOUND";
+  if (lowerMessage.includes("plan") && lowerMessage.includes("not found")) return "PLAN_NOT_FOUND";
+  if (lowerMessage.includes("app") && lowerMessage.includes("not found")) return "APP_NOT_FOUND";
+  if (lowerMessage.includes("not found")) return "NOT_FOUND";
+  if (lowerMessage.includes("limit") && lowerMessage.includes("exceeded")) return "USAGE_LIMIT_EXCEEDED";
+  if (lowerMessage.includes("metric") && lowerMessage.includes("not found")) return "METRIC_NOT_FOUND";
+  if (lowerMessage.includes("feature") && lowerMessage.includes("not available")) return "FEATURE_NOT_AVAILABLE";
+  if (lowerMessage.includes("no active subscription")) return "NO_ACTIVE_SUBSCRIPTION";
+  if (lowerMessage.includes("required")) return "MISSING_REQUIRED_FIELD";
+  if (lowerMessage.includes("invalid") && lowerMessage.includes("email")) return "INVALID_EMAIL";
+  if (status === 400) return "VALIDATION_ERROR";
+  if (status === 401) return "UNAUTHORIZED";
+  if (status === 404) return "NOT_FOUND";
+  return "UNKNOWN_ERROR";
+}
 var HttpClient = class {
   constructor(config) {
     this.config = config;
   }
+  get baseUrl() {
+    return this.config.baseUrl;
+  }
   async request(method, path, options = {}) {
     const url = new URL(path, this.config.baseUrl);
     if (options.params) {
@@ -43,11 +99,9 @@ var HttpClient = class {
       const data = await response.json();
       if (!response.ok) {
         const errorData = data;
-        throw new StackBEError(
-          errorData.message || "Unknown error",
-          errorData.statusCode || response.status,
-          errorData.error || "UNKNOWN_ERROR"
-        );
+        const message = errorData.message || "Unknown error";
+        const code = errorData.code || mapErrorCode(response.status, message, errorData.error || "");
+        throw new StackBEError(message, errorData.statusCode || response.status, code);
       }
       return data;
     } catch (error) {
@@ -379,6 +433,463 @@ var CustomersClient = class {
   }
 };
 
+// src/checkout.ts
+var CheckoutClient = class {
+  constructor(http, appId) {
+    this.http = http;
+    this.appId = appId;
+  }
+  /**
+   * 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,
+   * });
+   * ```
+   */
+  async createSession(options) {
+    const body = {
+      planId: options.planId,
+      successUrl: options.successUrl,
+      cancelUrl: options.cancelUrl,
+      allowPromotionCodes: options.allowPromotionCodes,
+      trialDays: options.trialDays,
+      metadata: options.metadata
+    };
+    if (typeof options.customer === "string") {
+      body.customerId = options.customer;
+    } else {
+      body.customerEmail = options.customer.email;
+      body.customerName = options.customer.name;
+    }
+    return this.http.post("/v1/checkout/session", body);
+  }
+  /**
+   * Get an existing checkout session by ID.
+   *
+   * @example
+   * ```typescript
+   * const session = await stackbe.checkout.getSession('cs_123');
+   * if (session.status === 'complete') {
+   *   // Payment successful
+   * }
+   * ```
+   */
+  async getSession(sessionId) {
+    return this.http.get(`/v1/checkout/session/${sessionId}`);
+  }
+  /**
+   * 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 });
+   * ```
+   */
+  async getCheckoutUrl(options) {
+    const session = await this.createSession(options);
+    return session.url;
+  }
+};
+
+// src/subscriptions.ts
+var SubscriptionsClient = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * 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');
+   * }
+   * ```
+   */
+  async get(customerId) {
+    try {
+      return await this.http.get(
+        `/v1/subscriptions/current`,
+        { customerId }
+      );
+    } catch (error) {
+      if (error instanceof Error && "statusCode" in error && error.statusCode === 404) {
+        return null;
+      }
+      throw error;
+    }
+  }
+  /**
+   * Get a subscription by ID.
+   *
+   * @example
+   * ```typescript
+   * const subscription = await stackbe.subscriptions.getById('sub_123');
+   * ```
+   */
+  async getById(subscriptionId) {
+    return this.http.get(`/v1/subscriptions/${subscriptionId}`);
+  }
+  /**
+   * List all subscriptions for a customer.
+   *
+   * @example
+   * ```typescript
+   * const subscriptions = await stackbe.subscriptions.list('cust_123');
+   * ```
+   */
+  async list(customerId) {
+    return this.http.get("/v1/subscriptions", { customerId });
+  }
+  /**
+   * 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'
+   * });
+   * ```
+   */
+  async cancel(subscriptionId, options = {}) {
+    return this.http.post(
+      `/v1/subscriptions/${subscriptionId}/cancel`,
+      {
+        immediate: options.immediate ?? false,
+        reason: options.reason
+      }
+    );
+  }
+  /**
+   * 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,
+   * });
+   * ```
+   */
+  async update(subscriptionId, options) {
+    return this.http.patch(
+      `/v1/subscriptions/${subscriptionId}`,
+      options
+    );
+  }
+  /**
+   * Reactivate a canceled subscription (before it ends).
+   *
+   * @example
+   * ```typescript
+   * // Customer changed their mind
+   * await stackbe.subscriptions.reactivate('sub_123');
+   * ```
+   */
+  async reactivate(subscriptionId) {
+    return this.http.post(
+      `/v1/subscriptions/${subscriptionId}/reactivate`
+    );
+  }
+  /**
+   * Check if a customer has an active subscription.
+   *
+   * @example
+   * ```typescript
+   * const isActive = await stackbe.subscriptions.isActive('cust_123');
+   * if (!isActive) {
+   *   return res.redirect('/pricing');
+   * }
+   * ```
+   */
+  async isActive(customerId) {
+    const subscription = await this.get(customerId);
+    return subscription !== null && (subscription.status === "active" || subscription.status === "trialing");
+  }
+};
+
+// src/auth.ts
+function decodeJwt(token) {
+  try {
+    const parts = token.split(".");
+    if (parts.length !== 3) return null;
+    const payload = Buffer.from(parts[1], "base64").toString("utf-8");
+    return JSON.parse(payload);
+  } catch {
+    return null;
+  }
+}
+var AuthClient = class {
+  constructor(http, appId) {
+    this.http = http;
+    this.appId = appId;
+  }
+  /**
+   * 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,
+   * });
+   * ```
+   */
+  async sendMagicLink(email, options = {}) {
+    return this.http.post(
+      `/v1/apps/${this.appId}/auth/magic-link`,
+      {
+        email,
+        redirectUrl: options.redirectUrl,
+        useDev: options.useDev
+      }
+    );
+  }
+  /**
+   * 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');
+   *     }
+   *   }
+   * }
+   * ```
+   */
+  async verifyToken(token) {
+    const response = await fetch(
+      `${this.http.baseUrl}/v1/apps/${this.appId}/auth/verify?token=${encodeURIComponent(token)}`,
+      {
+        headers: {
+          "Content-Type": "application/json"
+        }
+      }
+    );
+    if (!response.ok) {
+      const errorData = await response.json().catch(() => ({}));
+      const message = errorData.message || "Token verification failed";
+      let code = "TOKEN_INVALID";
+      if (message.includes("expired")) {
+        code = "TOKEN_EXPIRED";
+      } else if (message.includes("already been used")) {
+        code = "TOKEN_ALREADY_USED";
+      }
+      throw new StackBEError(message, response.status, code);
+    }
+    const data = await response.json();
+    let tenantId;
+    let organizationId;
+    let orgRole;
+    if (data.sessionToken) {
+      const payload = decodeJwt(data.sessionToken);
+      if (payload) {
+        tenantId = payload.tenantId;
+        organizationId = payload.organizationId;
+        orgRole = payload.orgRole;
+      }
+    }
+    return {
+      success: data.success ?? true,
+      valid: true,
+      customerId: data.customerId,
+      email: data.email,
+      sessionToken: data.sessionToken,
+      tenantId,
+      organizationId,
+      orgRole,
+      redirectUrl: data.redirectUrl
+    };
+  }
+  /**
+   * 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);
+   * }
+   * ```
+   */
+  async getSession(sessionToken) {
+    try {
+      const response = await fetch(
+        `${this.http.baseUrl}/v1/apps/${this.appId}/auth/session`,
+        {
+          headers: {
+            "Authorization": `Bearer ${sessionToken}`,
+            "Content-Type": "application/json"
+          }
+        }
+      );
+      if (!response.ok) {
+        if (response.status === 401) {
+          return null;
+        }
+        throw new StackBEError("Failed to get session", response.status, "SESSION_INVALID");
+      }
+      const data = await response.json();
+      let tenantId;
+      let organizationId;
+      let orgRole;
+      const payload = decodeJwt(sessionToken);
+      if (payload) {
+        tenantId = payload.tenantId;
+        organizationId = payload.organizationId;
+        orgRole = payload.orgRole;
+      }
+      return {
+        valid: data.valid ?? true,
+        customerId: data.customerId,
+        email: data.email,
+        expiresAt: data.expiresAt,
+        tenantId: tenantId ?? data.tenantId,
+        organizationId: data.organizationId ?? organizationId,
+        orgRole: data.orgRole ?? orgRole,
+        customer: data.customer,
+        subscription: data.subscription,
+        entitlements: data.entitlements
+      };
+    } catch (error) {
+      if (error instanceof StackBEError) {
+        throw error;
+      }
+      return 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) {
+    return async (req, res, next) => {
+      const token = options.getToken(req);
+      if (!token) {
+        if (options.onUnauthenticated) {
+          return options.onUnauthenticated(req, res);
+        }
+        return res.status(401).json({ error: "Not authenticated" });
+      }
+      const session = await this.getSession(token);
+      if (!session) {
+        if (options.onUnauthenticated) {
+          return options.onUnauthenticated(req, res);
+        }
+        return res.status(401).json({ error: "Invalid session" });
+      }
+      req.customer = session.customer;
+      req.subscription = session.subscription;
+      req.entitlements = session.entitlements;
+      next();
+    };
+  }
+  /**
+   * Check if a session token is valid.
+   *
+   * @example
+   * ```typescript
+   * const isValid = await stackbe.auth.isAuthenticated(sessionToken);
+   * ```
+   */
+  async isAuthenticated(sessionToken) {
+    const session = await this.getSession(sessionToken);
+    return session !== null;
+  }
+};
+
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.stackbe.io";
 var DEFAULT_TIMEOUT = 3e4;
@@ -401,8 +912,18 @@ var StackBE = class {
    * // 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) {
@@ -412,6 +933,7 @@ var StackBE = class {
     if (!config.appId) {
       throw new StackBEError("appId is required", 400, "INVALID_CONFIG");
     }
+    this.appId = config.appId;
     this.http = new HttpClient({
       baseUrl: config.baseUrl ?? DEFAULT_BASE_URL,
       apiKey: config.apiKey,
@@ -421,6 +943,9 @@ var StackBE = class {
     this.usage = new UsageClient(this.http);
     this.entitlements = new EntitlementsClient(this.http);
     this.customers = new CustomersClient(this.http);
+    this.checkout = new CheckoutClient(this.http, config.appId);
+    this.subscriptions = new SubscriptionsClient(this.http);
+    this.auth = new AuthClient(this.http, config.appId);
   }
   /**
    * Create a middleware for Express that tracks usage automatically.
@@ -553,9 +1078,12 @@ var StackBE = class {
   }
 };
 export {
+  AuthClient,
+  CheckoutClient,
   CustomersClient,
   EntitlementsClient,
   StackBE,
   StackBEError,
+  SubscriptionsClient,
   UsageClient
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackbe/sdk",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Official JavaScript/TypeScript SDK for StackBE - the billing backend for your side project",
   "main": "dist/index.js",
   "module": "dist/index.mjs",