@stackbe/sdk 0.1.0

package/dist/index.mjs

@@ -0,0 +1,561 @@
+// src/types.ts
+var StackBEError = class extends Error {
+  constructor(message, statusCode, code) {
+    super(message);
+    this.name = "StackBEError";
+    this.statusCode = statusCode;
+    this.code = code;
+  }
+};
+
+// src/http.ts
+var HttpClient = class {
+  constructor(config) {
+    this.config = config;
+  }
+  async request(method, path, options = {}) {
+    const url = new URL(path, this.config.baseUrl);
+    if (options.params) {
+      Object.entries(options.params).forEach(([key, value]) => {
+        if (value !== void 0) {
+          url.searchParams.set(key, String(value));
+        }
+      });
+    }
+    if (!url.searchParams.has("appId")) {
+      url.searchParams.set("appId", this.config.appId);
+    }
+    const headers = {
+      "Authorization": `Bearer ${this.config.apiKey}`,
+      "Content-Type": "application/json",
+      ...options.headers
+    };
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
+    try {
+      const response = await fetch(url.toString(), {
+        method,
+        headers,
+        body: options.body ? JSON.stringify(options.body) : void 0,
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      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"
+        );
+      }
+      return data;
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error instanceof StackBEError) {
+        throw error;
+      }
+      if (error instanceof Error) {
+        if (error.name === "AbortError") {
+          throw new StackBEError("Request timeout", 408, "TIMEOUT");
+        }
+        throw new StackBEError(error.message, 0, "NETWORK_ERROR");
+      }
+      throw new StackBEError("Unknown error", 0, "UNKNOWN_ERROR");
+    }
+  }
+  async get(path, params) {
+    return this.request("GET", path, { params });
+  }
+  async post(path, body, params) {
+    return this.request("POST", path, { body, params });
+  }
+  async patch(path, body) {
+    return this.request("PATCH", path, { body });
+  }
+  async delete(path) {
+    return this.request("DELETE", path);
+  }
+};
+
+// src/usage.ts
+var UsageClient = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Track a usage event for a customer.
+   *
+   * @example
+   * ```typescript
+   * // Track 1 API call
+   * await stackbe.usage.track('cust_123', 'api_calls');
+   *
+   * // Track 5 API calls
+   * await stackbe.usage.track('cust_123', 'api_calls', { quantity: 5 });
+   *
+   * // Track with idempotency key
+   * await stackbe.usage.track('cust_123', 'api_calls', {
+   *   quantity: 1,
+   *   idempotencyKey: 'req_abc123'
+   * });
+   * ```
+   */
+  async track(customerId, metric, options = {}) {
+    const headers = {};
+    if (options.idempotencyKey) {
+      headers["Idempotency-Key"] = options.idempotencyKey;
+    }
+    return this.http.post("/v1/usage/track", {
+      customerId,
+      metric,
+      quantity: options.quantity ?? 1
+    });
+  }
+  /**
+   * Check if a customer is within their usage limits for a specific metric.
+   *
+   * @example
+   * ```typescript
+   * const { allowed, remaining } = await stackbe.usage.check('cust_123', 'api_calls');
+   *
+   * if (!allowed) {
+   *   throw new Error('Usage limit exceeded');
+   * }
+   * ```
+   */
+  async check(customerId, metric) {
+    return this.http.get(
+      `/v1/customers/${customerId}/usage/check`,
+      { metric }
+    );
+  }
+  /**
+   * Get complete usage summary for a customer across all metrics.
+   *
+   * @example
+   * ```typescript
+   * const usage = await stackbe.usage.get('cust_123');
+   *
+   * for (const metric of usage.metrics) {
+   *   console.log(`${metric.displayName}: ${metric.currentUsage}/${metric.limit}`);
+   * }
+   * ```
+   */
+  async get(customerId, billingPeriod) {
+    return this.http.get(
+      `/v1/customers/${customerId}/usage`,
+      { billingPeriod }
+    );
+  }
+  /**
+   * Track usage and check limits in one call.
+   * Returns whether the action is allowed after tracking.
+   *
+   * @example
+   * ```typescript
+   * const result = await stackbe.usage.trackAndCheck('cust_123', 'api_calls');
+   *
+   * if (!result.allowed) {
+   *   // Rollback or handle limit exceeded
+   * }
+   * ```
+   */
+  async trackAndCheck(customerId, metric, options = {}) {
+    const trackResult = await this.track(customerId, metric, options);
+    const allowed = trackResult.limit === null || trackResult.currentUsage <= trackResult.limit;
+    return {
+      ...trackResult,
+      allowed
+    };
+  }
+};
+
+// src/entitlements.ts
+var EntitlementsClient = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Check if a customer has access to a specific feature.
+   *
+   * @example
+   * ```typescript
+   * const { hasAccess } = await stackbe.entitlements.check('cust_123', 'premium_export');
+   *
+   * if (!hasAccess) {
+   *   return res.status(403).json({ error: 'Upgrade to access this feature' });
+   * }
+   * ```
+   */
+  async check(customerId, feature) {
+    return this.http.get(
+      `/v1/customers/${customerId}/entitlements/check`,
+      { feature }
+    );
+  }
+  /**
+   * Get all entitlements for a customer based on their current plan.
+   *
+   * @example
+   * ```typescript
+   * const { entitlements, planName } = await stackbe.entitlements.getAll('cust_123');
+   *
+   * console.log(`Customer is on ${planName} plan`);
+   * console.log('Features:', entitlements);
+   * // { premium_export: true, api_access: true, max_projects: 10 }
+   * ```
+   */
+  async getAll(customerId) {
+    return this.http.get(
+      `/v1/customers/${customerId}/entitlements`
+    );
+  }
+  /**
+   * Check multiple features at once.
+   *
+   * @example
+   * ```typescript
+   * const results = await stackbe.entitlements.checkMany('cust_123', [
+   *   'premium_export',
+   *   'api_access',
+   *   'advanced_analytics'
+   * ]);
+   *
+   * // { premium_export: true, api_access: true, advanced_analytics: false }
+   * ```
+   */
+  async checkMany(customerId, features) {
+    const results = {};
+    const checks = await Promise.all(
+      features.map(async (feature) => {
+        try {
+          const result = await this.check(customerId, feature);
+          return { feature, hasAccess: result.hasAccess };
+        } catch {
+          return { feature, hasAccess: false };
+        }
+      })
+    );
+    for (const { feature, hasAccess } of checks) {
+      results[feature] = hasAccess;
+    }
+    return results;
+  }
+  /**
+   * Require a feature - throws if customer doesn't have access.
+   *
+   * @example
+   * ```typescript
+   * // Throws StackBEError if customer doesn't have access
+   * await stackbe.entitlements.require('cust_123', 'premium_export');
+   *
+   * // If we get here, customer has access
+   * performPremiumExport();
+   * ```
+   */
+  async require(customerId, feature) {
+    const { hasAccess } = await this.check(customerId, feature);
+    if (!hasAccess) {
+      const error = new Error(`Customer does not have access to feature: ${feature}`);
+      error.name = "EntitlementError";
+      throw error;
+    }
+  }
+};
+
+// src/customers.ts
+var CustomersClient = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Get a customer by ID.
+   *
+   * @example
+   * ```typescript
+   * const customer = await stackbe.customers.get('cust_123');
+   * console.log(customer.email);
+   * ```
+   */
+  async get(customerId) {
+    return this.http.get(`/v1/customers/${customerId}`);
+  }
+  /**
+   * Get a customer by email.
+   *
+   * @example
+   * ```typescript
+   * const customer = await stackbe.customers.getByEmail('user@example.com');
+   * ```
+   */
+  async getByEmail(email) {
+    try {
+      return await this.http.get("/v1/customers/by-email", { email });
+    } catch (error) {
+      if (error instanceof Error && "statusCode" in error && error.statusCode === 404) {
+        return null;
+      }
+      throw error;
+    }
+  }
+  /**
+   * Create a new customer.
+   *
+   * @example
+   * ```typescript
+   * const customer = await stackbe.customers.create({
+   *   email: 'user@example.com',
+   *   name: 'John Doe',
+   *   metadata: { source: 'website' }
+   * });
+   * ```
+   */
+  async create(options) {
+    return this.http.post("/v1/customers", options);
+  }
+  /**
+   * Update a customer.
+   *
+   * @example
+   * ```typescript
+   * const customer = await stackbe.customers.update('cust_123', {
+   *   name: 'Jane Doe',
+   *   metadata: { plan: 'enterprise' }
+   * });
+   * ```
+   */
+  async update(customerId, options) {
+    return this.http.patch(`/v1/customers/${customerId}`, options);
+  }
+  /**
+   * Get or create a customer by email.
+   * Returns existing customer if found, creates new one if not.
+   *
+   * @example
+   * ```typescript
+   * const customer = await stackbe.customers.getOrCreate({
+   *   email: 'user@example.com',
+   *   name: 'John Doe'
+   * });
+   * ```
+   */
+  async getOrCreate(options) {
+    const existing = await this.getByEmail(options.email);
+    if (existing) {
+      return existing;
+    }
+    return this.create(options);
+  }
+  /**
+   * Send a magic link to a customer for passwordless authentication.
+   *
+   * @example
+   * ```typescript
+   * await stackbe.customers.sendMagicLink('user@example.com', {
+   *   redirectUrl: 'https://myapp.com/dashboard'
+   * });
+   * ```
+   */
+  async sendMagicLink(email, options) {
+    return this.http.post("/v1/auth/magic-link", {
+      email,
+      redirectUrl: options?.redirectUrl
+    });
+  }
+  /**
+   * Get the current session for a customer token.
+   * Use this to validate tokens and get customer data.
+   *
+   * @example
+   * ```typescript
+   * const session = await stackbe.customers.getSession(token);
+   * console.log(session.customer.email);
+   * console.log(session.entitlements);
+   * ```
+   */
+  async getSession(token) {
+    return this.http.get("/v1/auth/session", void 0);
+  }
+};
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://api.stackbe.io";
+var DEFAULT_TIMEOUT = 3e4;
+var StackBE = class {
+  /**
+   * Create a new StackBE client.
+   *
+   * @example
+   * ```typescript
+   * import { StackBE } from '@stackbe/sdk';
+   *
+   * const stackbe = new StackBE({
+   *   apiKey: process.env.STACKBE_API_KEY!,
+   *   appId: process.env.STACKBE_APP_ID!,
+   * });
+   *
+   * // Track usage
+   * await stackbe.usage.track('customer_123', 'api_calls');
+   *
+   * // Check entitlements
+   * const { hasAccess } = await stackbe.entitlements.check('customer_123', 'premium');
+   *
+   * // Get customer
+   * const customer = await stackbe.customers.get('customer_123');
+   * ```
+   */
+  constructor(config) {
+    if (!config.apiKey) {
+      throw new StackBEError("apiKey is required", 400, "INVALID_CONFIG");
+    }
+    if (!config.appId) {
+      throw new StackBEError("appId is required", 400, "INVALID_CONFIG");
+    }
+    this.http = new HttpClient({
+      baseUrl: config.baseUrl ?? DEFAULT_BASE_URL,
+      apiKey: config.apiKey,
+      appId: config.appId,
+      timeout: config.timeout ?? DEFAULT_TIMEOUT
+    });
+    this.usage = new UsageClient(this.http);
+    this.entitlements = new EntitlementsClient(this.http);
+    this.customers = new CustomersClient(this.http);
+  }
+  /**
+   * Create a middleware for Express that tracks usage automatically.
+   *
+   * @example
+   * ```typescript
+   * import express from 'express';
+   * import { StackBE } from '@stackbe/sdk';
+   *
+   * const app = express();
+   * const stackbe = new StackBE({ apiKey: '...', appId: '...' });
+   *
+   * // Track all API calls
+   * app.use(stackbe.middleware({
+   *   getCustomerId: (req) => req.user?.customerId,
+   *   metric: 'api_calls',
+   * }));
+   * ```
+   */
+  middleware(options) {
+    return async (req, res, next) => {
+      if (options.skip?.(req)) {
+        return next();
+      }
+      const customerId = options.getCustomerId(req);
+      if (!customerId) {
+        return next();
+      }
+      try {
+        this.usage.track(customerId, options.metric).catch((error) => {
+          console.error("[StackBE] Failed to track usage:", error.message);
+        });
+      } catch (error) {
+        console.error("[StackBE] Failed to track usage:", error);
+      }
+      next();
+    };
+  }
+  /**
+   * Create a middleware that requires a feature entitlement.
+   *
+   * @example
+   * ```typescript
+   * // Require premium feature
+   * app.get('/api/export',
+   *   stackbe.requireFeature({
+   *     getCustomerId: (req) => req.user?.customerId,
+   *     feature: 'premium_export',
+   *   }),
+   *   exportHandler
+   * );
+   * ```
+   */
+  requireFeature(options) {
+    return async (req, res, next) => {
+      const customerId = options.getCustomerId(req);
+      if (!customerId) {
+        if (options.onDenied) {
+          return options.onDenied(req, res);
+        }
+        return res.status(401).json({ error: "Unauthorized" });
+      }
+      try {
+        const { hasAccess } = await this.entitlements.check(customerId, options.feature);
+        if (!hasAccess) {
+          if (options.onDenied) {
+            return options.onDenied(req, res);
+          }
+          return res.status(403).json({
+            error: "Feature not available",
+            feature: options.feature,
+            upgradeRequired: true
+          });
+        }
+        next();
+      } catch (error) {
+        console.error("[StackBE] Failed to check entitlement:", error);
+        if (options.onDenied) {
+          return options.onDenied(req, res);
+        }
+        return res.status(500).json({ error: "Failed to verify access" });
+      }
+    };
+  }
+  /**
+   * Create a middleware that enforces usage limits.
+   *
+   * @example
+   * ```typescript
+   * // Enforce API call limits
+   * app.use('/api',
+   *   stackbe.enforceLimit({
+   *     getCustomerId: (req) => req.user?.customerId,
+   *     metric: 'api_calls',
+   *   })
+   * );
+   * ```
+   */
+  enforceLimit(options) {
+    return async (req, res, next) => {
+      const customerId = options.getCustomerId(req);
+      if (!customerId) {
+        return next();
+      }
+      try {
+        const { allowed, currentUsage, limit } = await this.usage.check(customerId, options.metric);
+        if (!allowed) {
+          if (options.onLimitExceeded) {
+            return options.onLimitExceeded(req, res, {
+              current: currentUsage,
+              limit: limit ?? 0
+            });
+          }
+          return res.status(429).json({
+            error: "Usage limit exceeded",
+            metric: options.metric,
+            current: currentUsage,
+            limit
+          });
+        }
+        this.usage.track(customerId, options.metric).catch((error) => {
+          console.error("[StackBE] Failed to track usage:", error.message);
+        });
+        next();
+      } catch (error) {
+        console.error("[StackBE] Failed to check usage limit:", error);
+        next();
+      }
+    };
+  }
+};
+export {
+  CustomersClient,
+  EntitlementsClient,
+  StackBE,
+  StackBEError,
+  UsageClient
+};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@stackbe/sdk",
+  "version": "0.1.0",
+  "description": "Official JavaScript/TypeScript SDK for StackBE - the billing backend for your side project",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "lint": "eslint src/",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "stackbe",
+    "billing",
+    "subscriptions",
+    "saas",
+    "usage-based-billing",
+    "entitlements",
+    "stripe"
+  ],
+  "author": "StackBE",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Epic-Design-Labs/app-stackbe-sdk.git"
+  },
+  "homepage": "https://stackbe.io",
+  "bugs": {
+    "url": "https://github.com/Epic-Design-Labs/app-stackbe-sdk/issues"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}