@plures/praxis 0.2.0

package/src/cloud/billing.ts

@@ -0,0 +1,336 @@
+/**
+ * GitHub Sponsors and Marketplace Billing
+ * 
+ * Types and utilities for GitHub-based monetization.
+ */
+
+/**
+ * Praxis Cloud subscription tiers
+ */
+export 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
+ */
+export enum BillingProvider {
+  /**
+   * GitHub Sponsors
+   */
+  SPONSORS = "sponsors",
+  
+  /**
+   * GitHub Marketplace (SaaS)
+   */
+  MARKETPLACE = "marketplace",
+  
+  /**
+   * Free tier (no billing)
+   */
+  NONE = "none",
+}
+
+/**
+ * Subscription status
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export const TIER_LIMITS: Record<SubscriptionTier, TierLimits> = {
+  [SubscriptionTier.FREE]: {
+    maxSyncsPerMonth: 1000,
+    maxStorageBytes: 10 * 1024 * 1024, // 10 MB
+    maxTeamMembers: 1,
+    maxApps: 1,
+    supportLevel: "community",
+  },
+  [SubscriptionTier.SOLO]: {
+    maxSyncsPerMonth: 50000,
+    maxStorageBytes: 1024 * 1024 * 1024, // 1 GB
+    maxTeamMembers: 1,
+    maxApps: 10,
+    supportLevel: "standard",
+  },
+  [SubscriptionTier.TEAM]: {
+    maxSyncsPerMonth: 500000,
+    maxStorageBytes: 10 * 1024 * 1024 * 1024, // 10 GB
+    maxTeamMembers: 10,
+    maxApps: 50,
+    supportLevel: "standard",
+  },
+  [SubscriptionTier.ENTERPRISE]: {
+    maxSyncsPerMonth: 5000000,
+    maxStorageBytes: 100 * 1024 * 1024 * 1024, // 100 GB
+    maxTeamMembers: null, // unlimited
+    maxApps: 1000,
+    supportLevel: "priority",
+  },
+};
+
+/**
+ * Check if a user has access to a specific tier
+ */
+export function hasAccessToTier(
+  subscription: Subscription,
+  requiredTier: SubscriptionTier
+): boolean {
+  if (subscription.status !== SubscriptionStatus.ACTIVE) {
+    return false;
+  }
+  
+  const tierOrder = [
+    SubscriptionTier.FREE,
+    SubscriptionTier.SOLO,
+    SubscriptionTier.TEAM,
+    SubscriptionTier.ENTERPRISE,
+  ];
+  
+  const currentTierIndex = tierOrder.indexOf(subscription.tier);
+  const requiredTierIndex = tierOrder.indexOf(requiredTier);
+  
+  return currentTierIndex >= requiredTierIndex;
+}
+
+/**
+ * Check if usage is within tier limits
+ */
+export function checkUsageLimits(
+  subscription: Subscription,
+  usage: {
+    syncCount: number;
+    storageBytes: number;
+    teamMembers: number;
+    appCount: number;
+  }
+): {
+  withinLimits: boolean;
+  violations: string[];
+} {
+  const violations: string[] = [];
+  
+  if (usage.syncCount > subscription.limits.maxSyncsPerMonth) {
+    violations.push(
+      `Sync limit exceeded: ${usage.syncCount}/${subscription.limits.maxSyncsPerMonth}`
+    );
+  }
+  
+  if (usage.storageBytes > subscription.limits.maxStorageBytes) {
+    violations.push(
+      `Storage limit exceeded: ${(usage.storageBytes / 1024 / 1024).toFixed(2)}MB/${(subscription.limits.maxStorageBytes / 1024 / 1024).toFixed(2)}MB`
+    );
+  }
+  
+  if (
+    subscription.limits.maxTeamMembers !== null &&
+    usage.teamMembers > subscription.limits.maxTeamMembers
+  ) {
+    violations.push(
+      `Team member limit exceeded: ${usage.teamMembers}/${subscription.limits.maxTeamMembers}`
+    );
+  }
+  
+  if (usage.appCount > subscription.limits.maxApps) {
+    violations.push(
+      `App limit exceeded: ${usage.appCount}/${subscription.limits.maxApps}`
+    );
+  }
+  
+  return {
+    withinLimits: violations.length === 0,
+    violations,
+  };
+}
+
+/**
+ * Create a free tier subscription
+ */
+export function createFreeSubscription(): Subscription {
+  return {
+    tier: SubscriptionTier.FREE,
+    status: SubscriptionStatus.ACTIVE,
+    provider: BillingProvider.NONE,
+    startDate: Date.now(),
+    autoRenew: true,
+    limits: TIER_LIMITS[SubscriptionTier.FREE],
+  };
+}
+
+/**
+ * Create a subscription from GitHub Sponsors tier
+ */
+export function createSponsorSubscription(
+  tierName: string,
+  monthlyPriceInCents: number
+): Subscription {
+  let tier = SubscriptionTier.FREE;
+  
+  // Map price to tier (example pricing)
+  if (monthlyPriceInCents >= 5000) { // $50/month
+    tier = SubscriptionTier.ENTERPRISE;
+  } else if (monthlyPriceInCents >= 2000) { // $20/month
+    tier = SubscriptionTier.TEAM;
+  } else if (monthlyPriceInCents >= 500) { // $5/month
+    tier = SubscriptionTier.SOLO;
+  }
+  
+  return {
+    tier,
+    status: SubscriptionStatus.ACTIVE,
+    provider: BillingProvider.SPONSORS,
+    sponsorTierId: tierName,
+    startDate: Date.now(),
+    autoRenew: true,
+    limits: TIER_LIMITS[tier],
+  };
+}

package/src/cloud/client.ts

@@ -0,0 +1,221 @@
+/**
+ * Cloud Relay Client
+ * 
+ * Client for connecting to Praxis Cloud Relay service (Azure-based).
+ */
+
+import type {
+  CloudRelayConfig,
+  CloudRelayClient,
+  RelayStatus,
+  CRDTSyncMessage,
+  UsageMetrics,
+  HealthCheckResponse,
+} from "./types.js";
+
+/**
+ * Create a cloud relay client
+ */
+export function createCloudRelay(config: CloudRelayConfig): CloudRelayClient {
+  let status: RelayStatus = {
+    connected: false,
+    endpoint: config.endpoint,
+    appId: config.appId,
+  };
+
+  let syncTimer: NodeJS.Timeout | null = null;
+  const vectorClock: Record<string, number> = {};
+
+  return {
+    async connect(): Promise<void> {
+      // Validate endpoint
+      if (!config.endpoint) {
+        throw new Error("Cloud relay endpoint is required");
+      }
+
+      // Test connection
+      try {
+        const response = await fetch(`${config.endpoint}/health`, {
+          method: "GET",
+          headers: {
+            "Content-Type": "application/json",
+            ...(config.authToken && {
+              Authorization: `Bearer ${config.authToken}`,
+            }),
+          },
+        });
+
+        if (!response.ok) {
+          throw new Error(`Health check failed: ${response.statusText}`);
+        }
+
+        status.connected = true;
+        status.lastSync = Date.now();
+
+        // Start auto-sync if enabled
+        if (config.autoSync) {
+          const interval = config.syncInterval || 5000;
+          syncTimer = setInterval(() => {
+            // Auto-sync logic would go here
+            // For now, just update lastSync
+            status.lastSync = Date.now();
+          }, interval);
+        }
+      } catch (error) {
+        status.connected = false;
+        throw new Error(
+          `Failed to connect to cloud relay: ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
+    },
+
+    async disconnect(): Promise<void> {
+      if (syncTimer) {
+        clearInterval(syncTimer);
+        syncTimer = null;
+      }
+      status.connected = false;
+    },
+
+    async sync(message: CRDTSyncMessage): Promise<void> {
+      if (!status.connected) {
+        throw new Error("Not connected to cloud relay");
+      }
+
+      // Update vector clock
+      vectorClock[config.appId] = (vectorClock[config.appId] || 0) + 1;
+      message.clock = { ...vectorClock };
+
+      try {
+        const response = await fetch(`${config.endpoint}/sync`, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            ...(config.authToken && {
+              Authorization: `Bearer ${config.authToken}`,
+            }),
+          },
+          body: JSON.stringify(message),
+        });
+
+        if (!response.ok) {
+          throw new Error(`Sync failed: ${response.statusText}`);
+        }
+
+        status.lastSync = Date.now();
+
+        // Merge received vector clock
+        const result = await response.json() as any;
+        if (result.clock) {
+          Object.entries(result.clock).forEach(([key, value]) => {
+            vectorClock[key] = Math.max(
+              vectorClock[key] || 0,
+              value as number
+            );
+          });
+        }
+      } catch (error) {
+        throw new Error(
+          `Failed to sync: ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
+    },
+
+    async getUsage(): Promise<UsageMetrics> {
+      if (!status.connected) {
+        throw new Error("Not connected to cloud relay");
+      }
+
+      try {
+        const response = await fetch(
+          `${config.endpoint}/usage?appId=${config.appId}`,
+          {
+            method: "GET",
+            headers: {
+              "Content-Type": "application/json",
+              ...(config.authToken && {
+                Authorization: `Bearer ${config.authToken}`,
+              }),
+            },
+          }
+        );
+
+        if (!response.ok) {
+          throw new Error(`Failed to get usage: ${response.statusText}`);
+        }
+
+        return await response.json() as UsageMetrics;
+      } catch (error) {
+        throw new Error(
+          `Failed to get usage metrics: ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
+    },
+
+    async getHealth(): Promise<HealthCheckResponse> {
+      try {
+        const response = await fetch(`${config.endpoint}/health`, {
+          method: "GET",
+          headers: {
+            "Content-Type": "application/json",
+          },
+        });
+
+        if (!response.ok) {
+          throw new Error(`Health check failed: ${response.statusText}`);
+        }
+
+        return await response.json() as HealthCheckResponse;
+      } catch (error) {
+        throw new Error(
+          `Failed to get health status: ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
+    },
+
+    getStatus(): RelayStatus {
+      return { ...status };
+    },
+  };
+}
+
+/**
+ * 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()
+ * });
+ * ```
+ */
+export async function connectRelay(
+  endpoint: string,
+  options: Omit<CloudRelayConfig, "endpoint"> = { appId: "default" }
+): Promise<CloudRelayClient> {
+  const config: CloudRelayConfig = {
+    endpoint,
+    ...options,
+  };
+
+  const client = createCloudRelay(config);
+  await client.connect();
+  return client;
+}

package/src/cloud/index.ts

@@ -0,0 +1,121 @@
+/**
+ * Praxis Cloud
+ * 
+ * Cloud relay and synchronization for Praxis applications.
+ * 
+ * @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()
+ * });
+ * 
+ * // Get usage metrics
+ * const usage = await relay.getUsage();
+ * console.log(`Syncs: ${usage.syncCount}, Events: ${usage.eventCount}`);
+ * ```
+ */
+
+// Client
+export { createCloudRelay, connectRelay } from "./client.js";
+
+// Types
+export type {
+  CloudRelayConfig,
+  CloudRelayClient,
+  RelayStatus,
+  CRDTSyncMessage,
+  UsageMetrics,
+  HealthCheckResponse,
+  GitHubUser,
+  AuthResult,
+} from "./types.js";
+
+// Authentication
+export {
+  GitHubOAuth,
+  createGitHubOAuth,
+  authenticateWithDeviceFlow,
+} from "./auth.js";
+export type { GitHubOAuthConfig } from "./auth.js";
+
+// Billing and Subscriptions
+export {
+  SubscriptionTier,
+  BillingProvider,
+  SubscriptionStatus,
+  TIER_LIMITS,
+  hasAccessToTier,
+  checkUsageLimits,
+  createFreeSubscription,
+  createSponsorSubscription,
+} from "./billing.js";
+export type {
+  TierLimits,
+  Subscription,
+  BillingEvent,
+} from "./billing.js";
+
+// GitHub Sponsors
+export {
+  GitHubSponsorsClient,
+  createSponsorsClient,
+} from "./sponsors.js";
+export type {
+  SponsorTier,
+  Sponsorship,
+} from "./sponsors.js";
+
+// GitHub Marketplace
+export {
+  GitHubMarketplaceClient,
+  createMarketplaceClient,
+  MARKETPLACE_PLANS,
+} from "./marketplace.js";
+export type {
+  MarketplacePlan,
+  MarketplaceAccount,
+  MarketplaceWebhookEvent,
+} from "./marketplace.js";
+
+// Auto-Provisioning
+export {
+  generateStorageNamespace,
+  generateTenantId,
+  createTenant,
+  validateStorageNamespace,
+  getAppStorageContainer,
+  provisionTenant,
+  getOrCreateTenant,
+} from "./provisioning.js";
+export type {
+  Tenant,
+  ProvisioningResult,
+} from "./provisioning.js";
+
+// Relay endpoints (for Azure Functions deployment)
+export {
+  healthEndpoint,
+  syncEndpoint,
+  usageEndpoint,
+  statsEndpoint,
+  eventsEndpoint,
+  schemaEndpoint,
+} from "./relay/endpoints.js";
+export type {
+  AzureContext,
+  AzureHttpRequest,
+  AzureHttpResponse,
+} from "./relay/endpoints.js";