@plures/praxis 1.0.2 → 1.1.0

package/dist/node/cloud/index.d.cts

@@ -0,0 +1,864 @@
+import { b as PraxisFact, a as PraxisEvent } from '../protocol-Qek7ebBl.cjs';
+
+/**
+ * Cloud Relay Types
+ *
+ * Type definitions for Praxis Cloud Relay service.
+ */
+
+/**
+ * Cloud relay configuration
+ */
+interface CloudRelayConfig {
+    /**
+     * Azure Function App endpoint URL
+     */
+    endpoint: string;
+    /**
+     * GitHub OAuth token for authentication
+     */
+    authToken?: string;
+    /**
+     * Application identifier
+     */
+    appId: string;
+    /**
+     * Enable automatic sync
+     */
+    autoSync?: boolean;
+    /**
+     * Sync interval in milliseconds (default: 5000)
+     */
+    syncInterval?: number;
+    /**
+     * Enable encryption for blob storage
+     */
+    encryption?: boolean;
+}
+/**
+ * Relay connection status
+ */
+interface RelayStatus {
+    connected: boolean;
+    lastSync?: number;
+    endpoint: string;
+    appId: string;
+}
+/**
+ * CRDT sync message
+ */
+interface CRDTSyncMessage {
+    /**
+     * Message type
+     */
+    type: 'sync' | 'delta' | 'snapshot';
+    /**
+     * Application identifier
+     */
+    appId: string;
+    /**
+     * Vector clock for causality tracking
+     */
+    clock: Record<string, number>;
+    /**
+     * Facts to sync
+     */
+    facts?: PraxisFact[];
+    /**
+     * Events to forward
+     */
+    events?: PraxisEvent[];
+    /**
+     * Timestamp
+     */
+    timestamp: number;
+}
+/**
+ * Usage metrics
+ */
+interface UsageMetrics {
+    /**
+     * Application identifier
+     */
+    appId: string;
+    /**
+     * Number of sync operations
+     */
+    syncCount: number;
+    /**
+     * Number of events forwarded
+     */
+    eventCount: number;
+    /**
+     * Number of facts synced
+     */
+    factCount: number;
+    /**
+     * Storage used in bytes
+     */
+    storageBytes: number;
+    /**
+     * Period start timestamp
+     */
+    periodStart: number;
+    /**
+     * Period end timestamp
+     */
+    periodEnd: number;
+}
+/**
+ * Health check response
+ */
+interface HealthCheckResponse {
+    status: 'healthy' | 'degraded' | 'unhealthy';
+    timestamp: number;
+    version: string;
+    services: {
+        relay: boolean;
+        eventGrid: boolean;
+        storage: boolean;
+        auth: boolean;
+    };
+}
+/**
+ * Cloud relay client interface
+ */
+interface CloudRelayClient {
+    /**
+     * Connect to the relay
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from the relay
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Sync facts and events
+     */
+    sync(message: CRDTSyncMessage): Promise<void>;
+    /**
+     * Get usage metrics
+     */
+    getUsage(): Promise<UsageMetrics>;
+    /**
+     * Get health status
+     */
+    getHealth(): Promise<HealthCheckResponse>;
+    /**
+     * Get connection status
+     */
+    getStatus(): RelayStatus;
+}
+/**
+ * GitHub OAuth user info
+ */
+interface GitHubUser {
+    id: number;
+    login: string;
+    email?: string;
+    name?: string;
+    avatarUrl?: string;
+}
+/**
+ * Authentication result
+ */
+interface AuthResult {
+    success: boolean;
+    token?: string;
+    user?: GitHubUser;
+    expiresAt?: number;
+}
+
+/**
+ * Cloud Relay Client
+ *
+ * Client for connecting to Praxis Cloud Relay service (Azure-based).
+ */
+
+/**
+ * Create a cloud relay client
+ */
+declare function createCloudRelay(config: CloudRelayConfig): CloudRelayClient;
+/**
+ * Connect to Praxis Cloud Relay
+ *
+ * @param endpoint - Azure Function App endpoint URL
+ * @param options - Additional configuration options
+ * @returns Cloud relay client instance
+ *
+ * @example
+ * ```typescript
+ * import { connectRelay } from "@plures/praxis/cloud";
+ *
+ * const relay = await connectRelay("https://my-app.azurewebsites.net", {
+ *   appId: "my-app",
+ *   authToken: "github-token",
+ *   autoSync: true
+ * });
+ *
+ * // Sync data
+ * await relay.sync({
+ *   type: "delta",
+ *   appId: "my-app",
+ *   clock: {},
+ *   facts: [...],
+ *   timestamp: Date.now()
+ * });
+ * ```
+ */
+declare function connectRelay(endpoint: string, options?: Omit<CloudRelayConfig, 'endpoint'>): Promise<CloudRelayClient>;
+
+/**
+ * GitHub OAuth Authentication
+ *
+ * GitHub OAuth integration for Praxis Cloud Relay identity.
+ */
+
+/**
+ * GitHub OAuth configuration
+ */
+interface GitHubOAuthConfig {
+    clientId: string;
+    clientSecret?: string;
+    redirectUri?: string;
+    scope?: string;
+}
+/**
+ * GitHub OAuth client
+ */
+declare class GitHubOAuth {
+    private config;
+    constructor(config: GitHubOAuthConfig);
+    /**
+     * Get the OAuth authorization URL
+     */
+    getAuthorizationUrl(state?: string): string;
+    /**
+     * Exchange authorization code for access token
+     */
+    exchangeCode(code: string): Promise<AuthResult>;
+    /**
+     * Get user information from GitHub
+     */
+    getUserInfo(token: string): Promise<GitHubUser>;
+    /**
+     * Verify a token is valid
+     */
+    verifyToken(token: string): Promise<boolean>;
+    /**
+     * Generate a random state parameter for CSRF protection
+     */
+    private generateState;
+}
+/**
+ * Create a GitHub OAuth client
+ */
+declare function createGitHubOAuth(config: GitHubOAuthConfig): GitHubOAuth;
+/**
+ * Authenticate with GitHub OAuth device flow (for CLI)
+ */
+declare function authenticateWithDeviceFlow(clientId: string): Promise<AuthResult>;
+
+/**
+ * GitHub Sponsors and Marketplace Billing
+ *
+ * Types and utilities for GitHub-based monetization.
+ */
+/**
+ * Praxis Cloud subscription tiers
+ */
+declare enum SubscriptionTier {
+    /**
+     * Free tier - limited usage
+     */
+    FREE = "free",
+    /**
+     * Solo tier - individual developers via GitHub Sponsors
+     */
+    SOLO = "solo",
+    /**
+     * Team tier - small teams via GitHub Sponsors
+     */
+    TEAM = "team",
+    /**
+     * Enterprise tier - self-service enterprise via GitHub Sponsors/Marketplace
+     */
+    ENTERPRISE = "enterprise"
+}
+/**
+ * Billing provider type
+ */
+declare enum BillingProvider {
+    /**
+     * GitHub Sponsors
+     */
+    SPONSORS = "sponsors",
+    /**
+     * GitHub Marketplace (SaaS)
+     */
+    MARKETPLACE = "marketplace",
+    /**
+     * Free tier (no billing)
+     */
+    NONE = "none"
+}
+/**
+ * Subscription status
+ */
+declare enum SubscriptionStatus {
+    /**
+     * Active subscription
+     */
+    ACTIVE = "active",
+    /**
+     * Subscription cancelled, but still valid until period end
+     */
+    CANCELLED = "cancelled",
+    /**
+     * Subscription expired or payment failed
+     */
+    EXPIRED = "expired",
+    /**
+     * No subscription
+     */
+    NONE = "none"
+}
+/**
+ * Tier limits for different subscription levels
+ */
+interface TierLimits {
+    /**
+     * Maximum sync operations per month
+     */
+    maxSyncsPerMonth: number;
+    /**
+     * Maximum storage in bytes
+     */
+    maxStorageBytes: number;
+    /**
+     * Maximum number of team members (null = unlimited)
+     */
+    maxTeamMembers: number | null;
+    /**
+     * Maximum number of apps/projects
+     */
+    maxApps: number;
+    /**
+     * Support level
+     */
+    supportLevel: 'community' | 'standard' | 'priority';
+}
+/**
+ * Subscription information
+ */
+interface Subscription {
+    /**
+     * Subscription tier
+     */
+    tier: SubscriptionTier;
+    /**
+     * Subscription status
+     */
+    status: SubscriptionStatus;
+    /**
+     * Billing provider
+     */
+    provider: BillingProvider;
+    /**
+     * GitHub sponsor tier ID (if applicable)
+     */
+    sponsorTierId?: string;
+    /**
+     * GitHub Marketplace plan ID (if applicable)
+     */
+    marketplacePlanId?: number;
+    /**
+     * Subscription start date
+     */
+    startDate: number;
+    /**
+     * Current period end date
+     */
+    periodEnd?: number;
+    /**
+     * Whether subscription auto-renews
+     */
+    autoRenew: boolean;
+    /**
+     * Usage limits for this tier
+     */
+    limits: TierLimits;
+}
+/**
+ * Billing event type
+ */
+interface BillingEvent {
+    /**
+     * Event type
+     */
+    type: 'subscription_created' | 'subscription_cancelled' | 'subscription_renewed' | 'tier_changed';
+    /**
+     * Timestamp
+     */
+    timestamp: number;
+    /**
+     * User/organization ID
+     */
+    userId: number;
+    /**
+     * Old subscription (for changes)
+     */
+    oldSubscription?: Subscription;
+    /**
+     * New subscription
+     */
+    newSubscription: Subscription;
+}
+/**
+ * Default tier limits
+ */
+declare const TIER_LIMITS: Record<SubscriptionTier, TierLimits>;
+/**
+ * Check if a user has access to a specific tier
+ */
+declare function hasAccessToTier(subscription: Subscription, requiredTier: SubscriptionTier): boolean;
+/**
+ * Check if usage is within tier limits
+ */
+declare function checkUsageLimits(subscription: Subscription, usage: {
+    syncCount: number;
+    storageBytes: number;
+    teamMembers: number;
+    appCount: number;
+}): {
+    withinLimits: boolean;
+    violations: string[];
+};
+/**
+ * Create a free tier subscription
+ */
+declare function createFreeSubscription(): Subscription;
+/**
+ * Create a subscription from GitHub Sponsors tier
+ */
+declare function createSponsorSubscription(tierName: string, monthlyPriceInCents: number): Subscription;
+
+/**
+ * GitHub Sponsors API Client
+ *
+ * Client for checking GitHub Sponsors subscription status.
+ */
+
+/**
+ * GitHub Sponsors tier information
+ */
+interface SponsorTier {
+    /**
+     * Tier ID
+     */
+    id: string;
+    /**
+     * Tier name
+     */
+    name: string;
+    /**
+     * Monthly price in cents
+     */
+    monthlyPriceInCents: number;
+    /**
+     * Tier description
+     */
+    description?: string;
+    /**
+     * Whether this is a one-time sponsorship
+     */
+    isOneTime: boolean;
+}
+/**
+ * Sponsorship information
+ */
+interface Sponsorship {
+    /**
+     * Sponsor login
+     */
+    sponsorLogin: string;
+    /**
+     * Sponsor ID
+     */
+    sponsorId: number;
+    /**
+     * Tier information
+     */
+    tier: SponsorTier;
+    /**
+     * Creation date
+     */
+    createdAt: string;
+    /**
+     * Whether sponsorship is active
+     */
+    isActive: boolean;
+}
+/**
+ * GitHub Sponsors API client
+ */
+declare class GitHubSponsorsClient {
+    private token;
+    private accountLogin;
+    constructor(token: string, accountLogin: string);
+    /**
+     * Get current user's sponsorship of the Praxis account
+     */
+    getSponsorship(userLogin: string): Promise<Sponsorship | null>;
+    /**
+     * Get subscription from sponsorship
+     */
+    getSubscription(userLogin: string): Promise<Subscription>;
+    /**
+     * Check if user is a sponsor
+     */
+    isSponsor(userLogin: string): Promise<boolean>;
+}
+/**
+ * Create a GitHub Sponsors client
+ */
+declare function createSponsorsClient(token: string, accountLogin?: string): GitHubSponsorsClient;
+
+/**
+ * GitHub Marketplace API Client
+ *
+ * Client for GitHub Marketplace SaaS integration (preparatory).
+ */
+
+/**
+ * GitHub Marketplace plan
+ */
+interface MarketplacePlan {
+    /**
+     * Plan ID
+     */
+    id: number;
+    /**
+     * Plan name
+     */
+    name: string;
+    /**
+     * Plan description
+     */
+    description: string;
+    /**
+     * Monthly price in cents
+     */
+    monthlyPriceInCents: number;
+    /**
+     * Yearly price in cents
+     */
+    yearlyPriceInCents: number;
+    /**
+     * Price model
+     */
+    priceModel: 'FLAT_RATE' | 'PER_UNIT';
+    /**
+     * Whether this plan has a free trial
+     */
+    hasFreeTrial: boolean;
+    /**
+     * Unit name (for per-unit pricing)
+     */
+    unitName?: string;
+    /**
+     * Bullets (features list)
+     */
+    bullets: string[];
+}
+/**
+ * Marketplace account
+ */
+interface MarketplaceAccount {
+    /**
+     * Account ID
+     */
+    id: number;
+    /**
+     * Account login
+     */
+    login: string;
+    /**
+     * Account type
+     */
+    type: 'User' | 'Organization';
+    /**
+     * Plan
+     */
+    plan: MarketplacePlan;
+    /**
+     * Whether account is on free trial
+     */
+    onFreeTrial: boolean;
+    /**
+     * Free trial ends on (if applicable)
+     */
+    freeTrialEndsOn?: string;
+    /**
+     * Next billing date
+     */
+    nextBillingDate?: string;
+}
+/**
+ * Marketplace webhook event
+ */
+interface MarketplaceWebhookEvent {
+    /**
+     * Action type
+     */
+    action: 'purchased' | 'cancelled' | 'changed' | 'pending_change' | 'pending_change_cancelled';
+    /**
+     * Effective date
+     */
+    effectiveDate?: string;
+    /**
+     * Marketplace purchase
+     */
+    marketplacePurchase: {
+        account: MarketplaceAccount;
+        billingCycle: 'monthly' | 'yearly';
+        unitCount?: number;
+        onFreeTrial: boolean;
+        freeTrialEndsOn?: string;
+        nextBillingDate?: string;
+    };
+    /**
+     * Previous plan (for changes)
+     */
+    previousMarketplacePurchase?: {
+        account: MarketplaceAccount;
+        billingCycle: 'monthly' | 'yearly';
+        unitCount?: number;
+    };
+}
+/**
+ * Praxis Cloud Marketplace plans configuration
+ */
+declare const MARKETPLACE_PLANS: {
+    solo: {
+        name: string;
+        description: string;
+        monthlyPriceInCents: number;
+        yearlyPriceInCents: number;
+        features: string[];
+    };
+    team: {
+        name: string;
+        description: string;
+        monthlyPriceInCents: number;
+        yearlyPriceInCents: number;
+        features: string[];
+    };
+    enterprise: {
+        name: string;
+        description: string;
+        monthlyPriceInCents: number;
+        yearlyPriceInCents: number;
+        features: string[];
+    };
+};
+/**
+ * GitHub Marketplace API client
+ */
+declare class GitHubMarketplaceClient {
+    private token;
+    constructor(token: string);
+    /**
+     * Get accounts for the authenticated user
+     */
+    getAccounts(): Promise<MarketplaceAccount[]>;
+    /**
+     * Get subscription from marketplace account
+     */
+    getSubscription(accountId: number): Promise<Subscription | null>;
+    /**
+     * Handle marketplace webhook event
+     */
+    handleWebhookEvent(event: MarketplaceWebhookEvent): {
+        userId: number;
+        userLogin: string;
+        subscription: Subscription;
+    } | null;
+}
+/**
+ * Create a GitHub Marketplace client
+ */
+declare function createMarketplaceClient(token: string): GitHubMarketplaceClient;
+
+/**
+ * Auto-Provisioning
+ *
+ * Automatic tenant/storage provisioning based on GitHub identity.
+ */
+
+/**
+ * Tenant information
+ */
+interface Tenant {
+    /**
+     * Tenant ID (derived from GitHub user/org)
+     */
+    id: string;
+    /**
+     * GitHub user ID
+     */
+    githubUserId: number;
+    /**
+     * GitHub login (username or org name)
+     */
+    githubLogin: string;
+    /**
+     * Tenant type
+     */
+    type: 'user' | 'organization';
+    /**
+     * Subscription
+     */
+    subscription: Subscription;
+    /**
+     * Storage namespace
+     */
+    storageNamespace: string;
+    /**
+     * Creation timestamp
+     */
+    createdAt: number;
+    /**
+     * Last accessed timestamp
+     */
+    lastAccessedAt: number;
+}
+/**
+ * Generate a storage namespace from GitHub login
+ *
+ * Namespace format: gh-{login}-{hash}
+ * This ensures uniqueness and follows Azure Blob Storage naming rules.
+ */
+declare function generateStorageNamespace(githubLogin: string, userId: number): string;
+/**
+ * Generate tenant ID from GitHub user
+ */
+declare function generateTenantId(githubUser: GitHubUser): string;
+/**
+ * Create a tenant from GitHub user
+ */
+declare function createTenant(githubUser: GitHubUser, subscription: Subscription): Tenant;
+/**
+ * Validate storage namespace
+ *
+ * Ensures namespace follows Azure Blob Storage naming rules:
+ * - 3-63 characters
+ * - lowercase letters, numbers, and hyphens only
+ * - must start with letter or number
+ * - no consecutive hyphens
+ */
+declare function validateStorageNamespace(namespace: string): {
+    valid: boolean;
+    error?: string;
+};
+/**
+ * Get storage container name for an app
+ */
+declare function getAppStorageContainer(tenantNamespace: string, appId: string): string;
+/**
+ * Provisioning result
+ */
+interface ProvisioningResult {
+    /**
+     * Whether provisioning was successful
+     */
+    success: boolean;
+    /**
+     * Tenant (if successful)
+     */
+    tenant?: Tenant;
+    /**
+     * Error message (if failed)
+     */
+    error?: string;
+}
+/**
+ * Provision a new tenant
+ *
+ * This would typically:
+ * 1. Create storage containers
+ * 2. Set up access policies
+ * 3. Initialize tenant metadata
+ * 4. Register with billing system
+ */
+declare function provisionTenant(githubUser: GitHubUser, subscription: Subscription): Promise<ProvisioningResult>;
+/**
+ * Get or create tenant
+ *
+ * Checks if tenant exists, creates if not.
+ */
+declare function getOrCreateTenant(githubUser: GitHubUser, subscription: Subscription, tenantLookup: (id: string) => Promise<Tenant | null>): Promise<Tenant>;
+
+/**
+ * Azure Functions Relay Endpoints
+ *
+ * HTTP-triggered Azure Functions for Praxis Cloud Relay.
+ */
+/**
+ * Azure Function context (simplified interface)
+ */
+interface AzureContext {
+    log: (message: string) => void;
+    done: (err?: Error, result?: unknown) => void;
+}
+/**
+ * Azure HTTP request
+ */
+interface AzureHttpRequest {
+    method: string;
+    url: string;
+    headers: Record<string, string>;
+    query: Record<string, string>;
+    body?: unknown;
+}
+/**
+ * Azure HTTP response
+ */
+interface AzureHttpResponse {
+    status: number;
+    headers?: Record<string, string>;
+    body?: unknown;
+}
+/**
+ * Health check endpoint
+ * GET /health
+ */
+declare function healthEndpoint(context: AzureContext, _req: AzureHttpRequest): Promise<AzureHttpResponse>;
+/**
+ * CRDT sync endpoint
+ * POST /sync
+ */
+declare function syncEndpoint(context: AzureContext, req: AzureHttpRequest): Promise<AzureHttpResponse>;
+/**
+ * Usage metrics endpoint
+ * GET /usage?appId=<appId>
+ */
+declare function usageEndpoint(context: AzureContext, req: AzureHttpRequest): Promise<AzureHttpResponse>;
+/**
+ * Stats endpoint for aggregated metrics
+ * GET /stats?appId=<appId>
+ */
+declare function statsEndpoint(context: AzureContext, req: AzureHttpRequest): Promise<AzureHttpResponse>;
+/**
+ * Event forwarding endpoint
+ * POST /events
+ */
+declare function eventsEndpoint(context: AzureContext, req: AzureHttpRequest): Promise<AzureHttpResponse>;
+/**
+ * Schema registry endpoint
+ * GET /schema?appId=<appId>
+ * POST /schema (to register a schema)
+ */
+declare function schemaEndpoint(context: AzureContext, req: AzureHttpRequest): Promise<AzureHttpResponse>;
+
+export { type AuthResult, type AzureContext, type AzureHttpRequest, type AzureHttpResponse, type BillingEvent, BillingProvider, type CRDTSyncMessage, type CloudRelayClient, type CloudRelayConfig, GitHubMarketplaceClient, GitHubOAuth, type GitHubOAuthConfig, GitHubSponsorsClient, type GitHubUser, type HealthCheckResponse, MARKETPLACE_PLANS, type MarketplaceAccount, type MarketplacePlan, type MarketplaceWebhookEvent, type ProvisioningResult, type RelayStatus, type SponsorTier, type Sponsorship, type Subscription, SubscriptionStatus, SubscriptionTier, TIER_LIMITS, type Tenant, type TierLimits, type UsageMetrics, authenticateWithDeviceFlow, checkUsageLimits, connectRelay, createCloudRelay, createFreeSubscription, createGitHubOAuth, createMarketplaceClient, createSponsorSubscription, createSponsorsClient, createTenant, eventsEndpoint, generateStorageNamespace, generateTenantId, getAppStorageContainer, getOrCreateTenant, hasAccessToTier, healthEndpoint, provisionTenant, schemaEndpoint, statsEndpoint, syncEndpoint, usageEndpoint, validateStorageNamespace };