@enactprotocol/api 2.0.0

package/src/auth.ts

@@ -0,0 +1,293 @@
+/**
+ * Authentication functionality (v2)
+ * Handles OAuth-based authentication for the Enact registry
+ */
+
+import type { EnactApiClient } from "./client";
+import type {
+  CurrentUser,
+  OAuthCallbackRequest,
+  OAuthLoginRequest,
+  OAuthLoginResponse,
+  OAuthProvider,
+  OAuthTokenResponse,
+  RefreshTokenRequest,
+  RefreshTokenResponse,
+} from "./types";
+
+/**
+ * Authentication result
+ */
+export interface AuthResult {
+  /** Whether authentication succeeded */
+  success: boolean;
+  /** Authentication token (if successful) */
+  token?: string | undefined;
+  /** Current user info (if successful) */
+  user?: AuthUser | undefined;
+  /** Error message (if failed) */
+  error?: string | undefined;
+}
+
+/**
+ * Authenticated user info
+ */
+export interface AuthUser {
+  /** Username */
+  username: string;
+  /** Email address */
+  email: string;
+  /** Namespaces owned */
+  namespaces: string[];
+}
+
+/**
+ * Authentication status
+ */
+export interface AuthStatus {
+  /** Whether currently authenticated */
+  authenticated: boolean;
+  /** Current user (if authenticated) */
+  user?: AuthUser | undefined;
+  /** Token expiration time (if available) */
+  expiresAt?: Date | undefined;
+}
+
+/**
+ * Initiate OAuth login (v2)
+ *
+ * @param client - API client instance
+ * @param provider - OAuth provider (github, google, microsoft)
+ * @param redirectUri - Callback URL (usually http://localhost:PORT/callback)
+ * @returns Authorization URL to redirect user to
+ *
+ * @example
+ * ```ts
+ * const result = await initiateLogin(client, "github", "http://localhost:9876/callback");
+ * console.log(`Visit: ${result.authUrl}`);
+ * ```
+ */
+export async function initiateLogin(
+  client: EnactApiClient,
+  provider: OAuthProvider,
+  redirectUri: string
+): Promise<OAuthLoginResponse> {
+  const response = await client.post<OAuthLoginResponse>("/auth/login", {
+    provider,
+    redirect_uri: redirectUri,
+  } as OAuthLoginRequest);
+
+  return response.data;
+}
+
+/**
+ * Exchange OAuth code for tokens (v2)
+ *
+ * @param client - API client instance
+ * @param provider - OAuth provider used
+ * @param code - Authorization code from OAuth callback
+ * @returns Token response with access token, refresh token, and user info
+ *
+ * @example
+ * ```ts
+ * const tokens = await exchangeCodeForToken(client, "github", "auth_code_123");
+ * client.setAuthToken(tokens.access_token);
+ * console.log(`Logged in as ${tokens.user.username}`);
+ * ```
+ */
+export async function exchangeCodeForToken(
+  client: EnactApiClient,
+  provider: OAuthProvider,
+  code: string
+): Promise<OAuthTokenResponse> {
+  const response = await client.post<OAuthTokenResponse>("/auth/callback", {
+    provider,
+    code,
+  } as OAuthCallbackRequest);
+
+  return response.data;
+}
+
+/**
+ * Refresh an expired access token (v2)
+ *
+ * @param client - API client instance
+ * @param refreshToken - Refresh token obtained during login
+ * @returns New access token and expiration
+ *
+ * @example
+ * ```ts
+ * const newToken = await refreshAccessToken(client, storedRefreshToken);
+ * client.setAuthToken(newToken.access_token);
+ * ```
+ */
+export async function refreshAccessToken(
+  client: EnactApiClient,
+  refreshToken: string
+): Promise<RefreshTokenResponse> {
+  const response = await client.post<RefreshTokenResponse>("/auth/refresh", {
+    refresh_token: refreshToken,
+  } as RefreshTokenRequest);
+
+  return response.data;
+}
+
+/**
+ * Authenticate with the Enact registry (v2 OAuth flow)
+ *
+ * This is a convenience wrapper that initiates an OAuth flow:
+ * 1. Opens a browser for authentication
+ * 2. User logs in via their provider (GitHub, Google, etc.)
+ * 3. Receives a token from the registry
+ *
+ * Note: The actual OAuth callback handling requires a local HTTP server,
+ * which should be implemented in the CLI package.
+ *
+ * @param client - API client instance
+ * @returns Authentication result
+ *
+ * @example
+ * ```ts
+ * const result = await authenticate(client);
+ * if (result.success) {
+ *   client.setAuthToken(result.token);
+ *   console.log(`Logged in as ${result.user.username}`);
+ * }
+ * ```
+ */
+export async function authenticate(_client: EnactApiClient): Promise<AuthResult> {
+  // This is a placeholder for the full OAuth flow
+  // The actual implementation should be in the CLI package
+  // which can start a local server and open a browser
+  //
+  // Typical flow:
+  // 1. const loginResponse = await initiateLogin(client, "github", redirectUri);
+  // 2. Open browser to loginResponse.auth_url
+  // 3. Start local server on redirectUri to receive callback
+  // 4. Extract code from callback
+  // 5. const tokens = await exchangeCodeForToken(client, "github", code);
+  // 6. Return { success: true, token: tokens.access_token, user: {...} }
+
+  throw new Error(
+    "authenticate() must be implemented in the CLI package. " +
+      "Use initiateLogin() and exchangeCodeForToken() for OAuth flow."
+  );
+}
+
+/**
+ * Log out by clearing the authentication token
+ *
+ * @param client - API client instance
+ */
+export function logout(client: EnactApiClient): void {
+  client.setAuthToken(undefined);
+}
+
+/**
+ * Get current user info (v2)
+ *
+ * @param client - API client instance (must be authenticated)
+ * @returns Current user info
+ *
+ * @example
+ * ```ts
+ * const user = await getCurrentUser(client);
+ * console.log(`Logged in as ${user.username}`);
+ * ```
+ */
+export async function getCurrentUser(client: EnactApiClient): Promise<CurrentUser> {
+  const response = await client.get<CurrentUser>("/auth/me");
+  return response.data;
+}
+
+/**
+ * Get current authentication status (v2)
+ *
+ * @param client - API client instance
+ * @returns Current auth status
+ *
+ * @example
+ * ```ts
+ * const status = await getAuthStatus(client);
+ * if (status.authenticated) {
+ *   console.log(`Logged in as ${status.user.username}`);
+ * }
+ * ```
+ */
+export async function getAuthStatus(client: EnactApiClient): Promise<AuthStatus> {
+  if (!client.isAuthenticated()) {
+    return { authenticated: false };
+  }
+
+  try {
+    const user = await getCurrentUser(client);
+    return {
+      authenticated: true,
+      user: {
+        username: user.username,
+        email: user.email,
+        namespaces: user.namespaces,
+      },
+    };
+  } catch {
+    // Token might be invalid/expired
+    return { authenticated: false };
+  }
+}
+
+/**
+ * Get user profile by username (v2)
+ *
+ * @param client - API client instance
+ * @param username - Username to look up
+ * @returns User profile info
+ */
+export async function getUserProfile(
+  client: EnactApiClient,
+  username: string
+): Promise<{
+  username: string;
+  displayName?: string | undefined;
+  avatarUrl?: string | undefined;
+  createdAt: Date;
+  toolsCount?: number | undefined;
+}> {
+  const response = await client.get<{
+    username: string;
+    display_name?: string | undefined;
+    avatar_url?: string | undefined;
+    created_at: string;
+    tools_count?: number | undefined;
+  }>(`/users/${username}`);
+
+  return {
+    username: response.data.username,
+    displayName: response.data.display_name,
+    avatarUrl: response.data.avatar_url,
+    createdAt: new Date(response.data.created_at),
+    toolsCount: response.data.tools_count,
+  };
+}
+
+/**
+ * Submit feedback for a tool
+ *
+ * @param client - API client instance (must be authenticated)
+ * @param name - Tool name
+ * @param rating - Rating (1-5)
+ * @param version - Version being rated
+ * @param comment - Optional comment
+ */
+export async function submitFeedback(
+  client: EnactApiClient,
+  name: string,
+  rating: number,
+  version: string,
+  comment?: string
+): Promise<void> {
+  await client.post(`/tools/${name}/feedback`, {
+    rating,
+    version,
+    comment,
+  });
+}

package/src/client.ts

@@ -0,0 +1,349 @@
+/**
+ * Enact Registry API Client
+ * Core HTTP client for interacting with the Enact registry
+ */
+
+import type { ApiError, RateLimitInfo } from "./types";
+
+/**
+ * Default registry URL
+ */
+export const DEFAULT_REGISTRY_URL = "https://siikwkfgsmouioodghho.supabase.co/functions/v1";
+
+/**
+ * API client configuration options
+ */
+export interface ApiClientOptions {
+  /** Registry base URL (default: https://siikwkfgsmouioodghho.supabase.co/functions/v1) */
+  baseUrl?: string | undefined;
+  /** Authentication token */
+  authToken?: string | undefined;
+  /** Request timeout in milliseconds (default: 30000) */
+  timeout?: number | undefined;
+  /** Number of retry attempts for failed requests (default: 3) */
+  retries?: number | undefined;
+  /** User agent string */
+  userAgent?: string | undefined;
+}
+
+/**
+ * API response wrapper
+ */
+export interface ApiResponse<T> {
+  /** Response data */
+  data: T;
+  /** HTTP status code */
+  status: number;
+  /** Rate limit information */
+  rateLimit?: RateLimitInfo | undefined;
+}
+
+/**
+ * API request error
+ */
+export class ApiRequestError extends Error {
+  /** HTTP status code */
+  readonly status: number;
+  /** API error code */
+  readonly code: string;
+  /** Original error response */
+  readonly response?: ApiError | undefined;
+
+  constructor(message: string, status: number, code: string, response?: ApiError) {
+    super(message);
+    this.name = "ApiRequestError";
+    this.status = status;
+    this.code = code;
+    this.response = response;
+  }
+}
+
+/**
+ * Parse rate limit headers from response
+ */
+function parseRateLimitHeaders(headers: Headers): RateLimitInfo | undefined {
+  const limit = headers.get("X-RateLimit-Limit");
+  const remaining = headers.get("X-RateLimit-Remaining");
+  const reset = headers.get("X-RateLimit-Reset");
+
+  if (limit && remaining && reset) {
+    return {
+      limit: Number.parseInt(limit, 10),
+      remaining: Number.parseInt(remaining, 10),
+      reset: Number.parseInt(reset, 10),
+    };
+  }
+
+  return undefined;
+}
+
+/**
+ * Enact Registry API Client
+ */
+export class EnactApiClient {
+  private readonly baseUrl: string;
+  private readonly timeout: number;
+  private readonly maxRetries: number;
+  private readonly userAgent: string;
+  private authToken: string | undefined;
+
+  constructor(options: ApiClientOptions = {}) {
+    this.baseUrl = options.baseUrl ?? DEFAULT_REGISTRY_URL;
+    this.timeout = options.timeout ?? 30000;
+    this.maxRetries = options.retries ?? 3;
+    this.userAgent = options.userAgent ?? "enact-cli/0.1.0";
+    this.authToken = options.authToken;
+  }
+
+  /**
+   * Set authentication token
+   */
+  setAuthToken(token: string | undefined): void {
+    this.authToken = token;
+  }
+
+  /**
+   * Get current authentication token
+   */
+  getAuthToken(): string | undefined {
+    return this.authToken;
+  }
+
+  /**
+   * Get the base URL for the registry
+   */
+  getBaseUrl(): string {
+    return this.baseUrl;
+  }
+
+  /**
+   * Get the user agent string
+   */
+  getUserAgent(): string {
+    return this.userAgent;
+  }
+
+  /**
+   * Check if client is authenticated
+   */
+  isAuthenticated(): boolean {
+    return this.authToken !== undefined;
+  }
+
+  /**
+   * Build headers for a request
+   */
+  private buildHeaders(contentType?: string): Headers {
+    const headers = new Headers();
+    headers.set("User-Agent", this.userAgent);
+    headers.set("Accept", "application/json");
+
+    if (contentType) {
+      headers.set("Content-Type", contentType);
+    }
+
+    if (this.authToken) {
+      headers.set("Authorization", `Bearer ${this.authToken}`);
+      // Supabase Edge Functions also need the apikey header
+      headers.set("apikey", this.authToken);
+    }
+
+    return headers;
+  }
+
+  /**
+   * Make an HTTP request with retry logic
+   */
+  private async request<T>(
+    method: string,
+    path: string,
+    options: {
+      body?: unknown;
+      contentType?: string;
+      retryCount?: number;
+    } = {}
+  ): Promise<ApiResponse<T>> {
+    const url = `${this.baseUrl}${path}`;
+    const retryCount = options.retryCount ?? 0;
+
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+
+    try {
+      const response = await fetch(url, {
+        method,
+        headers: this.buildHeaders(options.contentType),
+        body: options.body ? JSON.stringify(options.body) : undefined,
+        signal: controller.signal,
+      });
+
+      clearTimeout(timeoutId);
+
+      const rateLimit = parseRateLimitHeaders(response.headers);
+
+      // Handle rate limiting with retry
+      if (response.status === 429 && retryCount < this.maxRetries) {
+        const retryAfter = response.headers.get("Retry-After");
+        const delay = retryAfter ? Number.parseInt(retryAfter, 10) * 1000 : 1000 * (retryCount + 1);
+        await new Promise((resolve) => setTimeout(resolve, delay));
+        return this.request<T>(method, path, { ...options, retryCount: retryCount + 1 });
+      }
+
+      // Handle error responses
+      if (!response.ok) {
+        let errorData: ApiError | undefined;
+        try {
+          errorData = (await response.json()) as ApiError;
+        } catch {
+          // Response body might not be JSON
+        }
+
+        const code = errorData?.error?.code ?? "unknown";
+        const message = errorData?.error?.message ?? `HTTP ${response.status}`;
+
+        throw new ApiRequestError(message, response.status, code, errorData);
+      }
+
+      // Handle 204 No Content
+      if (response.status === 204) {
+        return {
+          data: undefined as T,
+          status: response.status,
+          rateLimit,
+        };
+      }
+
+      // Parse JSON response
+      let data: T;
+      try {
+        const text = await response.text();
+        if (!text || text.trim() === "") {
+          throw new ApiRequestError(
+            "Server returned empty response",
+            response.status,
+            "empty_response"
+          );
+        }
+        data = JSON.parse(text) as T;
+      } catch (parseError) {
+        if (parseError instanceof ApiRequestError) {
+          throw parseError;
+        }
+        throw new ApiRequestError(
+          "Server returned invalid JSON response",
+          response.status,
+          "invalid_json"
+        );
+      }
+
+      return { data, status: response.status, rateLimit };
+    } catch (error) {
+      clearTimeout(timeoutId);
+
+      // Handle network errors with retry
+      if (error instanceof Error && error.name === "AbortError") {
+        if (retryCount < this.maxRetries) {
+          const delay = 1000 * (retryCount + 1);
+          await new Promise((resolve) => setTimeout(resolve, delay));
+          return this.request<T>(method, path, { ...options, retryCount: retryCount + 1 });
+        }
+        throw new ApiRequestError("Request timeout", 0, "timeout");
+      }
+
+      // Re-throw ApiRequestErrors
+      if (error instanceof ApiRequestError) {
+        throw error;
+      }
+
+      // Wrap other errors
+      throw new ApiRequestError(
+        error instanceof Error ? error.message : "Unknown error",
+        0,
+        "network_error"
+      );
+    }
+  }
+
+  /**
+   * GET request
+   */
+  async get<T>(path: string): Promise<ApiResponse<T>> {
+    return this.request<T>("GET", path);
+  }
+
+  /**
+   * POST request
+   */
+  async post<T>(path: string, body?: unknown): Promise<ApiResponse<T>> {
+    return this.request<T>("POST", path, {
+      body,
+      contentType: "application/json",
+    });
+  }
+
+  /**
+   * PUT request
+   */
+  async put<T>(path: string, body?: unknown): Promise<ApiResponse<T>> {
+    return this.request<T>("PUT", path, {
+      body,
+      contentType: "application/json",
+    });
+  }
+
+  /**
+   * DELETE request
+   */
+  async delete<T>(path: string): Promise<ApiResponse<T>> {
+    return this.request<T>("DELETE", path);
+  }
+
+  /**
+   * Download a file (returns raw response for streaming)
+   */
+  async download(path: string): Promise<Response> {
+    const url = `${this.baseUrl}${path}`;
+
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout * 10); // Longer timeout for downloads
+
+    try {
+      const response = await fetch(url, {
+        method: "GET",
+        headers: this.buildHeaders(),
+        signal: controller.signal,
+      });
+
+      clearTimeout(timeoutId);
+
+      if (!response.ok) {
+        throw new ApiRequestError(
+          `Download failed: HTTP ${response.status}`,
+          response.status,
+          "download_error"
+        );
+      }
+
+      return response;
+    } catch (error) {
+      clearTimeout(timeoutId);
+
+      if (error instanceof ApiRequestError) {
+        throw error;
+      }
+
+      throw new ApiRequestError(
+        error instanceof Error ? error.message : "Download failed",
+        0,
+        "download_error"
+      );
+    }
+  }
+}
+
+/**
+ * Create a new API client instance
+ */
+export function createApiClient(options?: ApiClientOptions): EnactApiClient {
+  return new EnactApiClient(options);
+}