@dream-api/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,520 @@
+/**
+ * Dream API SDK - Type Definitions
+ */
+interface DreamAPIConfig {
+    /** Your secret key (sk_test_xxx or sk_live_xxx) */
+    secretKey: string;
+    /** Your publishable key (pk_test_xxx or pk_live_xxx) - used for auth URL helpers */
+    publishableKey?: string;
+    /** Base URL override (for testing) */
+    baseUrl?: string;
+    /** Sign-up worker URL override */
+    signupUrl?: string;
+    /** Clerk base URL override (for production) */
+    clerkBaseUrl?: string;
+}
+interface Customer {
+    id: string;
+    email: string;
+    firstName?: string;
+    lastName?: string;
+    plan: string;
+    publishableKey: string;
+    createdAt: number;
+}
+interface CreateCustomerParams {
+    email: string;
+    password?: string;
+    firstName?: string;
+    lastName?: string;
+    plan?: string;
+}
+interface Usage {
+    userId: string;
+    plan: string;
+    usageCount: number;
+    limit: number | 'unlimited';
+    remaining: number | 'unlimited';
+    periodStart: string;
+    periodEnd: string;
+}
+interface UsageTrackResult {
+    success: boolean;
+    usage: Usage;
+}
+interface Tier {
+    name: string;
+    displayName: string;
+    price: number;
+    limit: number;
+    priceId: string;
+    productId: string;
+    features?: string;
+    popular?: boolean;
+}
+interface Product {
+    name: string;
+    price: number;
+    priceId: string;
+    productId: string;
+    description?: string;
+    imageUrl?: string;
+    inventory?: number;
+}
+interface CheckoutResult {
+    url: string;
+    sessionId?: string;
+}
+interface PortalResult {
+    url: string;
+}
+interface DashboardMetrics {
+    activeSubscriptions: number;
+    cancelingSubscriptions: number;
+    mrr: number;
+    totalRevenue?: number;
+    totalSales?: number;
+    avgOrderValue?: number;
+    usageThisPeriod: number;
+    customers: DashboardCustomer[];
+    tiers: Tier[];
+    products?: Product[];
+    orders?: Order[];
+    webhookStatus: WebhookStatus;
+}
+interface DashboardCustomer {
+    id: string;
+    email: string;
+    plan: string;
+    usage: number;
+    limit: number;
+    status: string;
+    renewsAt?: string;
+}
+interface Order {
+    customer: string;
+    email: string;
+    amount: number;
+    paymentId: string;
+    date: string;
+}
+interface WebhookStatus {
+    url: string;
+    lastEvent?: string;
+    recentEvents: Array<{
+        type: string;
+        timestamp: string;
+    }>;
+}
+interface DreamAPIError {
+    error: string;
+    message: string;
+    status?: number;
+}
+declare class DreamAPIException extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(error: DreamAPIError, status?: number);
+}
+
+/**
+ * Dream API SDK - HTTP Client
+ *
+ * Handles all HTTP communication with the Dream API.
+ * Automatically injects authentication headers.
+ */
+
+declare class DreamClient {
+    private secretKey;
+    private publishableKey;
+    private baseUrl;
+    private signupUrl;
+    private clerkUrl;
+    private userToken;
+    private tokenRefresher;
+    constructor(config: DreamAPIConfig);
+    /**
+     * Set the end-user JWT token for user-specific operations.
+     * Call this after the user signs in via Clerk.
+     */
+    setUserToken(token: string): void;
+    /**
+     * Clear the current user token (on sign out)
+     */
+    clearUserToken(): void;
+    /**
+     * Set a function to refresh the token before API calls
+     */
+    setTokenRefresher(refresher: () => Promise<string | null>): void;
+    /**
+     * Refresh token if we have a refresher set
+     */
+    private ensureFreshToken;
+    /**
+     * Get the publishable key
+     */
+    getPublishableKey(): string | undefined;
+    /**
+     * Get the sign-up URL base
+     */
+    getSignupBaseUrl(): string;
+    /**
+     * Get the Clerk base URL for hosted auth pages
+     */
+    getClerkBaseUrl(): string;
+    /**
+     * Make an authenticated request to the API
+     */
+    request<T>(method: 'GET' | 'POST' | 'PATCH' | 'DELETE', endpoint: string, options?: {
+        body?: unknown;
+        requiresUserToken?: boolean;
+    }): Promise<T>;
+    /**
+     * GET request
+     */
+    get<T>(endpoint: string, requiresUserToken?: boolean): Promise<T>;
+    /**
+     * POST request
+     */
+    post<T>(endpoint: string, body?: unknown, requiresUserToken?: boolean): Promise<T>;
+    /**
+     * PATCH request
+     */
+    patch<T>(endpoint: string, body?: unknown, requiresUserToken?: boolean): Promise<T>;
+    /**
+     * DELETE request
+     */
+    delete<T>(endpoint: string, requiresUserToken?: boolean): Promise<T>;
+}
+
+/**
+ * Dream API SDK - Clerk Integration
+ *
+ * Handles loading Clerk internally so devs never touch it.
+ * Uses the shared end-user-api Clerk app.
+ */
+interface ClerkUser {
+    id: string;
+    email: string;
+    plan: string;
+    publishableKey: string;
+}
+
+/**
+ * Dream API SDK - Auth Helpers
+ *
+ * URL builders for sign-up, sign-in, and account management flows.
+ * All URLs point to dream-api's shared Clerk app (end-user-api).
+ *
+ * Also handles loading Clerk internally so devs never touch it.
+ */
+
+interface AuthUrlOptions {
+    /** URL to redirect to after auth completes */
+    redirect: string;
+}
+declare class AuthHelpers {
+    private client;
+    private clerk;
+    private initialized;
+    constructor(client: DreamClient);
+    /**
+     * Initialize auth (loads Clerk internally).
+     * Call this on page load to detect existing sessions.
+     *
+     * @example
+     * ```typescript
+     * await api.auth.init();
+     * if (api.auth.isSignedIn()) {
+     *   // User is signed in, token already set
+     *   await api.usage.track();
+     * }
+     * ```
+     */
+    init(): Promise<void>;
+    /**
+     * Check if user is signed in
+     */
+    isSignedIn(): boolean;
+    /**
+     * Get current user info
+     */
+    getUser(): ClerkUser | null;
+    /**
+     * Sign out the current user
+     */
+    signOut(): Promise<void>;
+    /**
+     * Refresh the auth token (call before long sessions)
+     */
+    refreshToken(): Promise<void>;
+    /**
+     * Check if returning from auth redirect
+     */
+    static hasAuthParams(): boolean;
+    /**
+     * Get the sign-up URL for new users.
+     *
+     * Redirects to the sign-up worker which handles user creation
+     * and sets the required metadata (publishableKey, plan).
+     *
+     * @example
+     * ```typescript
+     * const signupUrl = api.auth.getSignUpUrl({ redirect: '/dashboard' });
+     * // Returns: https://sign-up.../signup?pk=pk_xxx&redirect=...
+     * window.location.href = signupUrl;
+     * ```
+     */
+    getSignUpUrl(options: AuthUrlOptions): string;
+    /**
+     * Get the sign-in URL for returning users.
+     *
+     * Redirects to Clerk's hosted sign-in page. After sign-in,
+     * users are redirected to your specified URL.
+     *
+     * @example
+     * ```typescript
+     * const signinUrl = api.auth.getSignInUrl({ redirect: '/dashboard' });
+     * window.location.href = signinUrl;
+     * ```
+     */
+    getSignInUrl(options: AuthUrlOptions): string;
+    /**
+     * Get the customer portal URL for account management.
+     *
+     * Redirects to Clerk's hosted account page where users can
+     * manage their profile, password, and security settings.
+     *
+     * Note: This is separate from billing management.
+     * For billing, use api.billing.openPortal().
+     *
+     * @example
+     * ```typescript
+     * const portalUrl = api.auth.getCustomerPortalUrl();
+     * window.location.href = portalUrl;
+     * ```
+     */
+    getCustomerPortalUrl(): string;
+}
+
+/**
+ * Dream API SDK
+ *
+ * Official SDK for Dream API - Auth, billing, and usage tracking in one API.
+ *
+ * @example
+ * ```typescript
+ * import { DreamAPI } from '@dream-api/sdk';
+ *
+ * const api = new DreamAPI({
+ *   secretKey: 'sk_test_xxx',
+ *   publishableKey: 'pk_test_xxx',
+ * });
+ *
+ * // Backend operations (SK only)
+ * await api.customers.create({ email: 'user@example.com' });
+ * const { tiers } = await api.products.listTiers();
+ * const dashboard = await api.dashboard.get();
+ *
+ * // Frontend operations (needs user token)
+ * api.setUserToken(clerkJWT);
+ * await api.usage.track();
+ * const usage = await api.usage.check();
+ * const { url } = await api.billing.createCheckout({ tier: 'pro' });
+ * ```
+ */
+
+/**
+ * Dream API SDK Client
+ */
+declare class DreamAPI {
+    private client;
+    /** Auth URL helpers */
+    readonly auth: AuthHelpers;
+    /** Customer management */
+    readonly customers: CustomerAPI;
+    /** Usage tracking */
+    readonly usage: UsageAPI;
+    /** Billing operations */
+    readonly billing: BillingAPI;
+    /** Product catalog */
+    readonly products: ProductAPI;
+    /** Dashboard metrics */
+    readonly dashboard: DashboardAPI;
+    constructor(config: DreamAPIConfig);
+    /**
+     * Set the end-user JWT token.
+     * Required for user-specific operations (usage, billing).
+     *
+     * @example
+     * ```typescript
+     * // After user signs in via Clerk
+     * const token = await clerk.session.getToken();
+     * api.setUserToken(token);
+     * ```
+     */
+    setUserToken(token: string): void;
+    /**
+     * Clear the user token (on sign out)
+     */
+    clearUserToken(): void;
+}
+declare class CustomerAPI {
+    private client;
+    constructor(client: DreamClient);
+    /**
+     * Create a new customer
+     *
+     * @example
+     * ```typescript
+     * const { customer } = await api.customers.create({
+     *   email: 'user@example.com',
+     *   firstName: 'John',
+     *   plan: 'free',
+     * });
+     * ```
+     */
+    create(params: CreateCustomerParams): Promise<{
+        customer: Customer;
+    }>;
+    /**
+     * Get a customer by ID
+     */
+    get(customerId: string): Promise<{
+        customer: Customer;
+    }>;
+    /**
+     * Update a customer's plan
+     */
+    update(customerId: string, params: {
+        plan: string;
+    }): Promise<{
+        customer: Customer;
+    }>;
+    /**
+     * Delete a customer
+     */
+    delete(customerId: string): Promise<{
+        success: boolean;
+        deleted: {
+            id: string;
+            email: string;
+        };
+    }>;
+}
+declare class UsageAPI {
+    private client;
+    constructor(client: DreamClient);
+    /**
+     * Track a usage event.
+     * Increments the user's usage counter for the current period.
+     *
+     * @example
+     * ```typescript
+     * const { usage } = await api.usage.track();
+     * console.log(`Used ${usage.usageCount} of ${usage.limit}`);
+     * ```
+     */
+    track(): Promise<UsageTrackResult>;
+    /**
+     * Check current usage without incrementing.
+     *
+     * @example
+     * ```typescript
+     * const usage = await api.usage.check();
+     * if (usage.remaining <= 0) {
+     *   // Show upgrade prompt
+     * }
+     * ```
+     */
+    check(): Promise<Usage>;
+}
+declare class BillingAPI {
+    private client;
+    constructor(client: DreamClient);
+    /**
+     * Create a checkout session for subscription upgrade.
+     *
+     * @example
+     * ```typescript
+     * const { url } = await api.billing.createCheckout({
+     *   tier: 'pro',
+     *   successUrl: '/success',
+     *   cancelUrl: '/pricing',
+     * });
+     * window.location.href = url;
+     * ```
+     */
+    createCheckout(params: {
+        tier?: string;
+        priceId?: string;
+        successUrl?: string;
+        cancelUrl?: string;
+    }): Promise<CheckoutResult>;
+    /**
+     * Open the Stripe customer portal for billing management.
+     *
+     * @example
+     * ```typescript
+     * const { url } = await api.billing.openPortal({ returnUrl: '/dashboard' });
+     * window.location.href = url;
+     * ```
+     */
+    openPortal(params?: {
+        returnUrl?: string;
+    }): Promise<PortalResult>;
+}
+declare class ProductAPI {
+    private client;
+    constructor(client: DreamClient);
+    /**
+     * List subscription tiers
+     */
+    listTiers(): Promise<{
+        tiers: Tier[];
+    }>;
+    /**
+     * List products (for store projects)
+     */
+    list(): Promise<{
+        products: Product[];
+    }>;
+    /**
+     * Create a cart checkout (guest checkout for store)
+     */
+    cartCheckout(params: {
+        items: Array<{
+            priceId: string;
+            quantity: number;
+        }>;
+        customerEmail: string;
+        customerName?: string;
+        successUrl?: string;
+        cancelUrl?: string;
+    }): Promise<CheckoutResult>;
+}
+declare class DashboardAPI {
+    private client;
+    constructor(client: DreamClient);
+    /**
+     * Get dashboard metrics
+     *
+     * @example
+     * ```typescript
+     * const dashboard = await api.dashboard.get();
+     * console.log(`MRR: $${dashboard.mrr}`);
+     * console.log(`Active subs: ${dashboard.activeSubscriptions}`);
+     * ```
+     */
+    get(): Promise<DashboardMetrics>;
+    /**
+     * Get aggregate totals across all projects
+     */
+    getTotals(): Promise<{
+        totalRevenue: number;
+        totalCustomers: number;
+        totalMRR: number;
+    }>;
+}
+
+export { type CheckoutResult, type ClerkUser, type CreateCustomerParams, type Customer, type DashboardCustomer, type DashboardMetrics, DreamAPI, type DreamAPIConfig, type DreamAPIError, DreamAPIException, type Order, type PortalResult, type Product, type Tier, type Usage, type UsageTrackResult, type WebhookStatus, DreamAPI as default };