@stackbe/sdk 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,448 @@
+interface HttpClientConfig {
+    baseUrl: string;
+    apiKey: string;
+    appId: string;
+    timeout: number;
+}
+declare class HttpClient {
+    private config;
+    constructor(config: HttpClientConfig);
+    private request;
+    get<T>(path: string, params?: Record<string, string | number | undefined>): Promise<T>;
+    post<T>(path: string, body?: unknown, params?: Record<string, string | number | undefined>): Promise<T>;
+    patch<T>(path: string, body?: unknown): Promise<T>;
+    delete<T>(path: string): Promise<T>;
+}
+
+interface StackBEConfig {
+    /** Your StackBE API key (starts with sk_) */
+    apiKey: string;
+    /** Your App ID from the StackBE dashboard */
+    appId: string;
+    /** Base URL for the API (default: https://api.stackbe.io) */
+    baseUrl?: string;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+}
+interface TrackUsageOptions {
+    /** Quantity to track (default: 1) */
+    quantity?: number;
+    /** Idempotency key to prevent duplicate tracking */
+    idempotencyKey?: string;
+}
+interface TrackUsageResponse {
+    success: boolean;
+    currentUsage: number;
+    limit: number | null;
+    remaining: number | null;
+}
+interface CheckUsageResponse {
+    /** Whether the customer is within their usage limits */
+    allowed: boolean;
+    /** Current usage for this billing period */
+    currentUsage: number;
+    /** The limit (null if unlimited) */
+    limit: number | null;
+    /** Remaining quota (null if unlimited) */
+    remaining: number | null;
+    /** When the usage counter resets */
+    resetAt?: string;
+}
+interface UsageMetric {
+    metric: string;
+    displayName: string;
+    unit: string;
+    currentUsage: number;
+    limit: number | null;
+    included: number;
+    remaining: number | null;
+    overageQuantity: number;
+    overageCost: number;
+}
+interface CustomerUsageResponse {
+    customerId: string;
+    billingPeriod: string;
+    metrics: UsageMetric[];
+}
+interface CheckEntitlementResponse {
+    /** Whether the customer has access to this feature */
+    hasAccess: boolean;
+    /** The customer's current plan name */
+    planName?: string;
+    /** Additional entitlement metadata */
+    metadata?: Record<string, unknown>;
+}
+interface EntitlementsResponse {
+    customerId: string;
+    planId: string;
+    planName: string;
+    entitlements: Record<string, boolean | number | string>;
+}
+interface Customer {
+    id: string;
+    email: string;
+    name?: string;
+    metadata?: Record<string, unknown>;
+    createdAt: string;
+    updatedAt: string;
+}
+interface Subscription {
+    id: string;
+    customerId: string;
+    planId: string;
+    planName: string;
+    status: 'active' | 'canceled' | 'past_due' | 'trialing' | 'paused';
+    currentPeriodStart: string;
+    currentPeriodEnd: string;
+    cancelAtPeriodEnd: boolean;
+    createdAt: string;
+}
+interface CustomerWithSubscription extends Customer {
+    subscription?: Subscription;
+}
+interface CreateCustomerOptions {
+    email: string;
+    name?: string;
+    metadata?: Record<string, unknown>;
+}
+interface UpdateCustomerOptions {
+    name?: string;
+    metadata?: Record<string, unknown>;
+}
+interface MagicLinkResponse {
+    success: boolean;
+    message: string;
+}
+interface VerifyTokenResponse {
+    valid: boolean;
+    customer?: Customer;
+    token?: string;
+    expiresAt?: string;
+}
+interface SessionResponse {
+    customer: Customer;
+    subscription?: Subscription;
+    entitlements: Record<string, boolean | number | string>;
+}
+interface StackBEErrorResponse {
+    statusCode: number;
+    message: string;
+    error: string;
+}
+declare class StackBEError extends Error {
+    readonly statusCode: number;
+    readonly code: string;
+    constructor(message: string, statusCode: number, code: string);
+}
+
+declare class UsageClient {
+    private http;
+    constructor(http: HttpClient);
+    /**
+     * 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'
+     * });
+     * ```
+     */
+    track(customerId: string, metric: string, options?: TrackUsageOptions): Promise<TrackUsageResponse>;
+    /**
+     * 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');
+     * }
+     * ```
+     */
+    check(customerId: string, metric: string): Promise<CheckUsageResponse>;
+    /**
+     * 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}`);
+     * }
+     * ```
+     */
+    get(customerId: string, billingPeriod?: string): Promise<CustomerUsageResponse>;
+    /**
+     * 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
+     * }
+     * ```
+     */
+    trackAndCheck(customerId: string, metric: string, options?: TrackUsageOptions): Promise<TrackUsageResponse & {
+        allowed: boolean;
+    }>;
+}
+
+declare class EntitlementsClient {
+    private http;
+    constructor(http: HttpClient);
+    /**
+     * 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' });
+     * }
+     * ```
+     */
+    check(customerId: string, feature: string): Promise<CheckEntitlementResponse>;
+    /**
+     * 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 }
+     * ```
+     */
+    getAll(customerId: string): Promise<EntitlementsResponse>;
+    /**
+     * 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 }
+     * ```
+     */
+    checkMany(customerId: string, features: string[]): Promise<Record<string, boolean>>;
+    /**
+     * 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();
+     * ```
+     */
+    require(customerId: string, feature: string): Promise<void>;
+}
+
+declare class CustomersClient {
+    private http;
+    constructor(http: HttpClient);
+    /**
+     * Get a customer by ID.
+     *
+     * @example
+     * ```typescript
+     * const customer = await stackbe.customers.get('cust_123');
+     * console.log(customer.email);
+     * ```
+     */
+    get(customerId: string): Promise<CustomerWithSubscription>;
+    /**
+     * Get a customer by email.
+     *
+     * @example
+     * ```typescript
+     * const customer = await stackbe.customers.getByEmail('user@example.com');
+     * ```
+     */
+    getByEmail(email: string): Promise<CustomerWithSubscription | null>;
+    /**
+     * Create a new customer.
+     *
+     * @example
+     * ```typescript
+     * const customer = await stackbe.customers.create({
+     *   email: 'user@example.com',
+     *   name: 'John Doe',
+     *   metadata: { source: 'website' }
+     * });
+     * ```
+     */
+    create(options: CreateCustomerOptions): Promise<Customer>;
+    /**
+     * Update a customer.
+     *
+     * @example
+     * ```typescript
+     * const customer = await stackbe.customers.update('cust_123', {
+     *   name: 'Jane Doe',
+     *   metadata: { plan: 'enterprise' }
+     * });
+     * ```
+     */
+    update(customerId: string, options: UpdateCustomerOptions): Promise<Customer>;
+    /**
+     * 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'
+     * });
+     * ```
+     */
+    getOrCreate(options: CreateCustomerOptions): Promise<Customer>;
+    /**
+     * Send a magic link to a customer for passwordless authentication.
+     *
+     * @example
+     * ```typescript
+     * await stackbe.customers.sendMagicLink('user@example.com', {
+     *   redirectUrl: 'https://myapp.com/dashboard'
+     * });
+     * ```
+     */
+    sendMagicLink(email: string, options?: {
+        redirectUrl?: string;
+    }): Promise<MagicLinkResponse>;
+    /**
+     * 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);
+     * ```
+     */
+    getSession(token: string): Promise<SessionResponse>;
+}
+
+declare class StackBE {
+    private http;
+    /** Usage tracking and limits */
+    readonly usage: UsageClient;
+    /** Feature entitlements */
+    readonly entitlements: EntitlementsClient;
+    /** Customer management */
+    readonly customers: CustomersClient;
+    /**
+     * 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: StackBEConfig);
+    /**
+     * 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: {
+        getCustomerId: (req: any) => string | undefined;
+        metric: string;
+        skip?: (req: any) => boolean;
+    }): (req: any, res: any, next: any) => Promise<any>;
+    /**
+     * 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: {
+        getCustomerId: (req: any) => string | undefined;
+        feature: string;
+        onDenied?: (req: any, res: any) => void;
+    }): (req: any, res: any, next: any) => Promise<any>;
+    /**
+     * 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: {
+        getCustomerId: (req: any) => string | undefined;
+        metric: string;
+        onLimitExceeded?: (req: any, res: any, usage: {
+            current: number;
+            limit: number;
+        }) => void;
+    }): (req: any, res: any, next: any) => Promise<any>;
+}
+
+export { type CheckEntitlementResponse, type CheckUsageResponse, type CreateCustomerOptions, type Customer, type CustomerUsageResponse, type CustomerWithSubscription, CustomersClient, EntitlementsClient, type EntitlementsResponse, type MagicLinkResponse, type SessionResponse, StackBE, type StackBEConfig, StackBEError, type StackBEErrorResponse, type Subscription, type TrackUsageOptions, type TrackUsageResponse, type UpdateCustomerOptions, UsageClient, type UsageMetric, type VerifyTokenResponse };