@parsrun/service-adapters 0.1.0

package/dist/payments/index.d.ts

@@ -0,0 +1,782 @@
+import * as _parsrun_service from '@parsrun/service';
+import { createMemoryEventTransport, RpcServer, EventEmitter, ServiceClientOptions } from '@parsrun/service';
+import { Logger } from '@parsrun/core';
+
+/**
+ * @parsrun/service-adapters - Payments Service Definition
+ */
+/**
+ * Payments Service Definition
+ *
+ * Provides payment processing, billing, usage tracking,
+ * and dunning capabilities as a microservice.
+ */
+declare const paymentsServiceDefinition: _parsrun_service.ServiceDefinition<{
+    /**
+     * Get subscription details
+     */
+    getSubscription: {
+        input: {
+            subscriptionId?: string;
+            customerId?: string;
+        };
+        output: {
+            id: string;
+            customerId: string;
+            status: "active" | "canceled" | "past_due" | "trialing" | "paused";
+            planId: string;
+            planName: string;
+            currentPeriodStart: string;
+            currentPeriodEnd: string;
+            cancelAtPeriodEnd: boolean;
+            provider: string;
+        } | null;
+        description: string;
+    };
+    /**
+     * Get customer details
+     */
+    getCustomer: {
+        input: {
+            customerId: string;
+        };
+        output: {
+            id: string;
+            email: string;
+            name?: string;
+            metadata?: Record<string, unknown>;
+            provider: string;
+        } | null;
+        description: string;
+    };
+    /**
+     * Check quota status
+     */
+    checkQuota: {
+        input: {
+            customerId: string;
+            featureKey: string;
+        };
+        output: {
+            allowed: boolean;
+            remaining: number | null;
+            limit: number | null;
+            resetAt?: string;
+            percentage: number;
+        };
+        description: string;
+    };
+    /**
+     * Get usage summary
+     */
+    getUsage: {
+        input: {
+            customerId: string;
+            featureKey?: string;
+            period?: "hour" | "day" | "month";
+        };
+        output: {
+            features: Array<{
+                featureKey: string;
+                used: number;
+                limit: number | null;
+                percentage: number;
+            }>;
+            period: {
+                start: string;
+                end: string;
+            };
+        };
+        description: string;
+    };
+    /**
+     * Get available plans
+     */
+    getPlans: {
+        input: undefined;
+        output: {
+            plans: Array<{
+                id: string;
+                name: string;
+                displayName: string;
+                tier: number;
+                basePrice: number;
+                currency: string;
+                billingInterval: "month" | "year";
+                features: Array<{
+                    featureKey: string;
+                    limitValue: number | null;
+                    limitPeriod: string | null;
+                }>;
+            }>;
+        };
+        description: string;
+    };
+    /**
+     * Get dunning status
+     */
+    getDunningStatus: {
+        input: {
+            customerId: string;
+        };
+        output: {
+            inDunning: boolean;
+            status?: "active" | "resolved" | "abandoned" | "recovered";
+            currentStep?: number;
+            totalSteps?: number;
+            nextActionAt?: string;
+            daysSinceFailure?: number;
+        };
+        description: string;
+    };
+}, {
+    /**
+     * Create a checkout session
+     */
+    createCheckout: {
+        input: {
+            email: string;
+            planId: string;
+            successUrl: string;
+            cancelUrl: string;
+            countryCode?: string;
+            metadata?: Record<string, unknown>;
+        };
+        output: {
+            checkoutUrl: string;
+            sessionId: string;
+            customerId?: string;
+            provider: string;
+        };
+        description: string;
+    };
+    /**
+     * Cancel a subscription
+     */
+    cancelSubscription: {
+        input: {
+            subscriptionId: string;
+            cancelAtPeriodEnd?: boolean;
+            reason?: string;
+        };
+        output: {
+            success: boolean;
+            canceledAt?: string;
+            effectiveAt?: string;
+        };
+        description: string;
+    };
+    /**
+     * Update subscription
+     */
+    updateSubscription: {
+        input: {
+            subscriptionId: string;
+            planId?: string;
+            metadata?: Record<string, unknown>;
+        };
+        output: {
+            success: boolean;
+            subscription: {
+                id: string;
+                planId: string;
+                status: string;
+            };
+        };
+        description: string;
+    };
+    /**
+     * Create customer portal session
+     */
+    createPortalSession: {
+        input: {
+            customerId: string;
+            returnUrl: string;
+        };
+        output: {
+            portalUrl: string;
+            expiresAt?: string;
+        };
+        description: string;
+    };
+    /**
+     * Track usage
+     */
+    trackUsage: {
+        input: {
+            customerId: string;
+            featureKey: string;
+            quantity: number;
+            metadata?: Record<string, unknown>;
+        };
+        output: {
+            success: boolean;
+            newTotal: number;
+            remaining: number | null;
+        };
+        description: string;
+    };
+    /**
+     * Assign plan to customer
+     */
+    assignPlan: {
+        input: {
+            customerId: string;
+            planId: string;
+            expiresAt?: string;
+        };
+        output: {
+            success: boolean;
+            previousPlanId?: string;
+            newPlanId: string;
+        };
+        description: string;
+    };
+    /**
+     * Handle webhook
+     */
+    handleWebhook: {
+        input: {
+            provider: "stripe" | "paddle" | "iyzico";
+            payload: string;
+            signature: string;
+        };
+        output: {
+            success: boolean;
+            eventType?: string;
+            eventId?: string;
+        };
+        description: string;
+    };
+}, {
+    /**
+     * Subscription was created
+     */
+    "subscription.created": {
+        data: {
+            subscriptionId: string;
+            customerId: string;
+            planId: string;
+            provider: string;
+            timestamp: string;
+        };
+        delivery: "at-least-once";
+        description: string;
+    };
+    /**
+     * Subscription was renewed
+     */
+    "subscription.renewed": {
+        data: {
+            subscriptionId: string;
+            customerId: string;
+            planId: string;
+            periodStart: string;
+            periodEnd: string;
+            timestamp: string;
+        };
+        delivery: "at-least-once";
+        description: string;
+    };
+    /**
+     * Subscription was canceled
+     */
+    "subscription.canceled": {
+        data: {
+            subscriptionId: string;
+            customerId: string;
+            reason?: string;
+            effectiveAt: string;
+            timestamp: string;
+        };
+        delivery: "at-least-once";
+        description: string;
+    };
+    /**
+     * Subscription plan changed
+     */
+    "subscription.plan_changed": {
+        data: {
+            subscriptionId: string;
+            customerId: string;
+            previousPlanId: string;
+            newPlanId: string;
+            timestamp: string;
+        };
+        delivery: "at-least-once";
+        description: string;
+    };
+    /**
+     * Payment succeeded
+     */
+    "payment.succeeded": {
+        data: {
+            paymentId: string;
+            customerId: string;
+            amount: number;
+            currency: string;
+            invoiceId?: string;
+            timestamp: string;
+        };
+        delivery: "at-least-once";
+        description: string;
+    };
+    /**
+     * Payment failed
+     */
+    "payment.failed": {
+        data: {
+            customerId: string;
+            subscriptionId?: string;
+            amount: number;
+            currency: string;
+            errorCode?: string;
+            errorMessage?: string;
+            timestamp: string;
+        };
+        delivery: "at-least-once";
+        description: string;
+    };
+    /**
+     * Quota exceeded
+     */
+    "quota.exceeded": {
+        data: {
+            customerId: string;
+            featureKey: string;
+            used: number;
+            limit: number;
+            timestamp: string;
+        };
+        delivery: "at-least-once";
+        description: string;
+    };
+    /**
+     * Quota threshold reached
+     */
+    "quota.threshold_reached": {
+        data: {
+            customerId: string;
+            featureKey: string;
+            percentage: number;
+            used: number;
+            limit: number;
+            timestamp: string;
+        };
+        delivery: "at-least-once";
+        description: string;
+    };
+    /**
+     * Dunning started
+     */
+    "dunning.started": {
+        data: {
+            customerId: string;
+            subscriptionId: string;
+            amount: number;
+            currency: string;
+            timestamp: string;
+        };
+        delivery: "at-least-once";
+        description: string;
+    };
+    /**
+     * Dunning resolved
+     */
+    "dunning.resolved": {
+        data: {
+            customerId: string;
+            resolution: "recovered" | "canceled" | "manual";
+            timestamp: string;
+        };
+        delivery: "at-least-once";
+        description: string;
+    };
+}, string[]>;
+/**
+ * Type export for the payments service definition
+ */
+type PaymentsServiceDefinition = typeof paymentsServiceDefinition;
+
+/**
+ * @parsrun/service-adapters - Payments Service Server
+ * Server-side implementation of the Payments microservice
+ */
+
+interface PaymentsServiceServerOptions {
+    /** Payment provider configurations */
+    providers: {
+        default: PaymentProviderConfig;
+        regions?: Record<string, PaymentProviderConfig>;
+    };
+    /** Database/storage for usage tracking */
+    storage?: PaymentsStorage;
+    /** Logger */
+    logger?: Logger;
+    /** Event transport (for emitting events) */
+    eventTransport?: ReturnType<typeof createMemoryEventTransport>;
+}
+interface PaymentProviderConfig {
+    type: "stripe" | "paddle" | "iyzico" | "mock";
+    secretKey?: string;
+    webhookSecret?: string;
+}
+interface PaymentsStorage {
+    getUsage(customerId: string, featureKey: string): Promise<number>;
+    trackUsage(customerId: string, featureKey: string, quantity: number): Promise<number>;
+    resetUsage(customerId: string, featureKey?: string): Promise<void>;
+    getPlan(planId: string): Promise<Plan$1 | null>;
+    getPlans(): Promise<Plan$1[]>;
+    getCustomerPlan(customerId: string): Promise<string | null>;
+    setCustomerPlan(customerId: string, planId: string): Promise<void>;
+}
+interface Plan$1 {
+    id: string;
+    name: string;
+    displayName: string;
+    tier: number;
+    basePrice: number;
+    currency: string;
+    billingInterval: "month" | "year";
+    features: Array<{
+        featureKey: string;
+        limitValue: number | null;
+        limitPeriod: string | null;
+    }>;
+}
+/**
+ * Create Payments Service Server
+ */
+declare function createPaymentsServiceServer(options: PaymentsServiceServerOptions): {
+    rpcServer: RpcServer;
+    eventEmitter: EventEmitter;
+    register: () => void;
+};
+
+/**
+ * @parsrun/service-adapters - Payments Service Client
+ * Type-safe client for the Payments microservice
+ */
+
+/**
+ * Type-safe Payments Service Client
+ */
+interface PaymentsServiceClient {
+    /**
+     * Get subscription details
+     */
+    getSubscription(options: {
+        subscriptionId?: string;
+        customerId?: string;
+    }): Promise<Subscription | null>;
+    /**
+     * Get customer details
+     */
+    getCustomer(customerId: string): Promise<Customer | null>;
+    /**
+     * Check quota for a feature
+     */
+    checkQuota(customerId: string, featureKey: string): Promise<QuotaStatus>;
+    /**
+     * Get usage summary
+     */
+    getUsage(options: {
+        customerId: string;
+        featureKey?: string;
+        period?: "hour" | "day" | "month";
+    }): Promise<UsageSummary>;
+    /**
+     * Get available plans
+     */
+    getPlans(): Promise<{
+        plans: Plan[];
+    }>;
+    /**
+     * Get dunning status
+     */
+    getDunningStatus(customerId: string): Promise<DunningStatus>;
+    /**
+     * Create checkout session
+     */
+    createCheckout(options: CreateCheckoutOptions): Promise<CheckoutSession>;
+    /**
+     * Cancel subscription
+     */
+    cancelSubscription(options: CancelSubscriptionOptions): Promise<CancelResult>;
+    /**
+     * Update subscription
+     */
+    updateSubscription(options: UpdateSubscriptionOptions): Promise<UpdateResult>;
+    /**
+     * Create customer portal session
+     */
+    createPortalSession(customerId: string, returnUrl: string): Promise<PortalSession>;
+    /**
+     * Track usage
+     */
+    trackUsage(options: TrackUsageOptions): Promise<TrackUsageResult>;
+    /**
+     * Assign plan to customer
+     */
+    assignPlan(customerId: string, planId: string, expiresAt?: string): Promise<AssignPlanResult>;
+    /**
+     * Handle webhook
+     */
+    handleWebhook(options: WebhookOptions): Promise<WebhookResult>;
+    /**
+     * Subscribe to subscription events
+     */
+    onSubscriptionCreated(handler: (event: SubscriptionCreatedEvent) => Promise<void>): () => void;
+    onSubscriptionRenewed(handler: (event: SubscriptionRenewedEvent) => Promise<void>): () => void;
+    onSubscriptionCanceled(handler: (event: SubscriptionCanceledEvent) => Promise<void>): () => void;
+    onSubscriptionPlanChanged(handler: (event: PlanChangedEvent) => Promise<void>): () => void;
+    /**
+     * Subscribe to payment events
+     */
+    onPaymentSucceeded(handler: (event: PaymentSucceededEvent) => Promise<void>): () => void;
+    onPaymentFailed(handler: (event: PaymentFailedEvent) => Promise<void>): () => void;
+    /**
+     * Subscribe to quota events
+     */
+    onQuotaExceeded(handler: (event: QuotaExceededEvent) => Promise<void>): () => void;
+    onQuotaThresholdReached(handler: (event: QuotaThresholdEvent) => Promise<void>): () => void;
+    /**
+     * Subscribe to dunning events
+     */
+    onDunningStarted(handler: (event: DunningStartedEvent) => Promise<void>): () => void;
+    onDunningResolved(handler: (event: DunningResolvedEvent) => Promise<void>): () => void;
+    /**
+     * Close the client
+     */
+    close(): Promise<void>;
+}
+interface Subscription {
+    id: string;
+    customerId: string;
+    status: "active" | "canceled" | "past_due" | "trialing" | "paused";
+    planId: string;
+    planName: string;
+    currentPeriodStart: string;
+    currentPeriodEnd: string;
+    cancelAtPeriodEnd: boolean;
+    provider: string;
+}
+interface Customer {
+    id: string;
+    email: string;
+    name?: string;
+    metadata?: Record<string, unknown>;
+    provider: string;
+}
+interface QuotaStatus {
+    allowed: boolean;
+    remaining: number | null;
+    limit: number | null;
+    resetAt?: string;
+    percentage: number;
+}
+interface UsageSummary {
+    features: Array<{
+        featureKey: string;
+        used: number;
+        limit: number | null;
+        percentage: number;
+    }>;
+    period: {
+        start: string;
+        end: string;
+    };
+}
+interface Plan {
+    id: string;
+    name: string;
+    displayName: string;
+    tier: number;
+    basePrice: number;
+    currency: string;
+    billingInterval: "month" | "year";
+    features: Array<{
+        featureKey: string;
+        limitValue: number | null;
+        limitPeriod: string | null;
+    }>;
+}
+interface DunningStatus {
+    inDunning: boolean;
+    status?: "active" | "resolved" | "abandoned" | "recovered";
+    currentStep?: number;
+    totalSteps?: number;
+    nextActionAt?: string;
+    daysSinceFailure?: number;
+}
+interface CreateCheckoutOptions {
+    email: string;
+    planId: string;
+    successUrl: string;
+    cancelUrl: string;
+    countryCode?: string;
+    metadata?: Record<string, unknown>;
+}
+interface CheckoutSession {
+    checkoutUrl: string;
+    sessionId: string;
+    customerId?: string;
+    provider: string;
+}
+interface CancelSubscriptionOptions {
+    subscriptionId: string;
+    cancelAtPeriodEnd?: boolean;
+    reason?: string;
+}
+interface CancelResult {
+    success: boolean;
+    canceledAt?: string;
+    effectiveAt?: string;
+}
+interface UpdateSubscriptionOptions {
+    subscriptionId: string;
+    planId?: string;
+    metadata?: Record<string, unknown>;
+}
+interface UpdateResult {
+    success: boolean;
+    subscription: {
+        id: string;
+        planId: string;
+        status: string;
+    };
+}
+interface PortalSession {
+    portalUrl: string;
+    expiresAt?: string;
+}
+interface TrackUsageOptions {
+    customerId: string;
+    featureKey: string;
+    quantity: number;
+    metadata?: Record<string, unknown>;
+}
+interface TrackUsageResult {
+    success: boolean;
+    newTotal: number;
+    remaining: number | null;
+}
+interface AssignPlanResult {
+    success: boolean;
+    previousPlanId?: string;
+    newPlanId: string;
+}
+interface WebhookOptions {
+    provider: "stripe" | "paddle" | "iyzico";
+    payload: string;
+    signature: string;
+}
+interface WebhookResult {
+    success: boolean;
+    eventType?: string;
+    eventId?: string;
+}
+interface SubscriptionCreatedEvent {
+    subscriptionId: string;
+    customerId: string;
+    planId: string;
+    provider: string;
+    timestamp: string;
+}
+interface SubscriptionRenewedEvent {
+    subscriptionId: string;
+    customerId: string;
+    planId: string;
+    periodStart: string;
+    periodEnd: string;
+    timestamp: string;
+}
+interface SubscriptionCanceledEvent {
+    subscriptionId: string;
+    customerId: string;
+    reason?: string;
+    effectiveAt: string;
+    timestamp: string;
+}
+interface PlanChangedEvent {
+    subscriptionId: string;
+    customerId: string;
+    previousPlanId: string;
+    newPlanId: string;
+    timestamp: string;
+}
+interface PaymentSucceededEvent {
+    paymentId: string;
+    customerId: string;
+    amount: number;
+    currency: string;
+    invoiceId?: string;
+    timestamp: string;
+}
+interface PaymentFailedEvent {
+    customerId: string;
+    subscriptionId?: string;
+    amount: number;
+    currency: string;
+    errorCode?: string;
+    errorMessage?: string;
+    timestamp: string;
+}
+interface QuotaExceededEvent {
+    customerId: string;
+    featureKey: string;
+    used: number;
+    limit: number;
+    timestamp: string;
+}
+interface QuotaThresholdEvent {
+    customerId: string;
+    featureKey: string;
+    percentage: number;
+    used: number;
+    limit: number;
+    timestamp: string;
+}
+interface DunningStartedEvent {
+    customerId: string;
+    subscriptionId: string;
+    amount: number;
+    currency: string;
+    timestamp: string;
+}
+interface DunningResolvedEvent {
+    customerId: string;
+    resolution: "recovered" | "canceled" | "manual";
+    timestamp: string;
+}
+/**
+ * Create Payments Service Client
+ *
+ * @example
+ * ```typescript
+ * // Embedded mode
+ * const payments = createPaymentsServiceClient();
+ *
+ * // HTTP mode
+ * const payments = createPaymentsServiceClient({
+ *   mode: 'http',
+ *   baseUrl: 'https://payments.example.com',
+ * });
+ *
+ * // Check quota before API call
+ * const quota = await payments.checkQuota(customerId, 'api_calls');
+ * if (!quota.allowed) {
+ *   throw new Error('Quota exceeded');
+ * }
+ *
+ * // Track usage after API call
+ * await payments.trackUsage({
+ *   customerId,
+ *   featureKey: 'api_calls',
+ *   quantity: 1,
+ * });
+ * ```
+ */
+declare function createPaymentsServiceClient(options?: ServiceClientOptions): PaymentsServiceClient;
+
+export { type PaymentsServiceClient, type PaymentsServiceDefinition, type PaymentsServiceServerOptions, createPaymentsServiceClient, createPaymentsServiceServer, paymentsServiceDefinition };