patchwork-os 0.2.0-alpha.2 → 0.2.0-alpha.22

package/dist/connectors/baseConnector.js

@@ -0,0 +1,213 @@
+/**
+ * BaseConnector — shared foundation for all Patchwork OS connectors.
+ *
+ * Provides:
+ *   - Unified authentication flow (token refresh, expiry handling)
+ *   - Secure token storage via OS keychain/DPAPI/Secret Service
+ *   - OAuth 2.0 refresh token flow
+ *   - Rate limiting with exponential backoff
+ *   - Error normalization to ConnectorError type
+ *   - Health check endpoint
+ *
+ * All new connectors (Jira, Notion, PagerDuty, Drive, etc.) extend this base.
+ * Extracted to prevent "each connector reinvents auth" anti-pattern.
+ */
+export class BaseConnector {
+    auth = null;
+    rateLimit = {
+        remaining: 100,
+        resetAt: new Date(Date.now() + 60000),
+        backoffMs: 0,
+    };
+    oauthConfig = null;
+    /**
+     * Load stored tokens from secure storage.
+     * Call this in subclass constructor or connect method.
+     */
+    async loadStoredTokens() {
+        const { getTokens } = await import("./tokenStorage.js");
+        const stored = await getTokens(this.providerName);
+        if (stored) {
+            this.auth = {
+                token: stored.accessToken,
+                refreshToken: stored.refreshToken,
+                expiresAt: stored.expiresAt ? new Date(stored.expiresAt) : undefined,
+                scopes: stored.scopes,
+            };
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Save current tokens to secure storage.
+     */
+    async saveTokens() {
+        if (!this.auth)
+            return;
+        const { storeTokens } = await import("./tokenStorage.js");
+        await storeTokens(this.providerName, {
+            accessToken: this.auth.token,
+            refreshToken: this.auth.refreshToken,
+            expiresAt: this.auth.expiresAt?.toISOString(),
+            scopes: this.auth.scopes,
+        });
+    }
+    /**
+     * Clear stored tokens (logout/disconnect).
+     */
+    async clearTokens() {
+        const { deleteTokens } = await import("./tokenStorage.js");
+        await deleteTokens(this.providerName);
+        this.auth = null;
+    }
+    /**
+     * Perform OAuth 2.0 token refresh.
+     * Subclasses can override for provider-specific refresh flows.
+     */
+    async refreshToken() {
+        if (!this.auth?.refreshToken)
+            return null;
+        const config = this.getOAuthConfig();
+        if (!config)
+            return null;
+        try {
+            const params = new URLSearchParams({
+                grant_type: "refresh_token",
+                refresh_token: this.auth.refreshToken,
+                client_id: config.clientId,
+                ...(config.clientSecret ? { client_secret: config.clientSecret } : {}),
+            });
+            const response = await fetch(config.tokenEndpoint, {
+                method: "POST",
+                headers: { "Content-Type": "application/x-www-form-urlencoded" },
+                body: params.toString(),
+            });
+            if (!response.ok) {
+                throw new Error(`Token refresh failed: ${response.status}`);
+            }
+            const data = (await response.json());
+            const newAuth = {
+                token: data.access_token,
+                refreshToken: data.refresh_token ?? this.auth.refreshToken,
+                expiresAt: data.expires_in
+                    ? new Date(Date.now() + data.expires_in * 1000)
+                    : undefined,
+                scopes: data.scope?.split(" ") ?? this.auth.scopes,
+            };
+            this.auth = newAuth;
+            await this.saveTokens();
+            return newAuth;
+        }
+        catch (err) {
+            // Refresh failed - clear tokens to force re-auth
+            await this.clearTokens();
+            return null;
+        }
+    }
+    /**
+     * Execute an authenticated API call with automatic token refresh
+     * and rate limit backoff.
+     */
+    async apiCall(fn, options = {}) {
+        const { retries = 2, retryDelayMs = 1000 } = options;
+        // Ensure auth - try refresh first, then fall back to full auth
+        if (!this.auth || this.isTokenExpired()) {
+            // Try OAuth refresh if we have a refresh token
+            if (this.auth?.refreshToken) {
+                const refreshed = await this.refreshToken();
+                if (refreshed) {
+                    this.auth = refreshed;
+                }
+                else {
+                    // Refresh failed, fall back to full auth
+                    try {
+                        this.auth = await this.authenticate();
+                    }
+                    catch (err) {
+                        return { error: this.normalizeError(err) };
+                    }
+                }
+            }
+            else {
+                // No refresh token, do full auth
+                try {
+                    this.auth = await this.authenticate();
+                }
+                catch (err) {
+                    return { error: this.normalizeError(err) };
+                }
+            }
+        }
+        // Apply rate limit backoff
+        if (this.rateLimit.backoffMs > 0) {
+            await sleep(this.rateLimit.backoffMs);
+        }
+        // Execute with retry
+        for (let attempt = 0; attempt <= retries; attempt++) {
+            try {
+                const result = await fn(this.auth?.token);
+                return { data: result };
+            }
+            catch (err) {
+                const normalized = this.normalizeError(err);
+                // Don't retry non-retryable errors
+                if (!normalized.retryable || attempt === retries) {
+                    return { error: normalized };
+                }
+                // Exponential backoff with jitter
+                const delay = retryDelayMs * 2 ** attempt + Math.random() * 500;
+                await sleep(delay);
+                // Token might have expired mid-call - try refresh first
+                if (normalized.code === "auth_expired") {
+                    if (this.auth?.refreshToken) {
+                        const refreshed = await this.refreshToken();
+                        if (refreshed) {
+                            this.auth = refreshed;
+                            continue; // Retry with new token
+                        }
+                    }
+                    // Refresh failed or no refresh token, try full auth
+                    try {
+                        this.auth = await this.authenticate();
+                    }
+                    catch {
+                        return { error: normalized };
+                    }
+                }
+            }
+        }
+        // Should not reach here, but TypeScript needs it
+        return {
+            error: {
+                code: "provider_error",
+                message: "Unexpected end of retry loop",
+                retryable: false,
+            },
+        };
+    }
+    /**
+     * Update rate limit state from HTTP response headers.
+     * Subclass should call this after each API response.
+     */
+    updateRateLimitFromHeaders(headers) {
+        if (headers["x-ratelimit-remaining"]) {
+            this.rateLimit.remaining = parseInt(headers["x-ratelimit-remaining"], 10);
+        }
+        if (headers["x-ratelimit-reset"]) {
+            this.rateLimit.resetAt = new Date(parseInt(headers["x-ratelimit-reset"], 10) * 1000);
+        }
+        if (headers["retry-after"]) {
+            this.rateLimit.backoffMs = parseInt(headers["retry-after"], 10) * 1000;
+        }
+    }
+    isTokenExpired() {
+        if (!this.auth?.expiresAt)
+            return false;
+        // Refresh 5 minutes before actual expiry
+        return new Date(Date.now() + 5 * 60000) >= this.auth.expiresAt;
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=baseConnector.js.map

package/dist/connectors/baseConnector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseConnector.js","sourceRoot":"","sources":["../../src/connectors/baseConnector.ts"],"names":[],"mappings":"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"}

package/dist/connectors/confluence.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Confluence connector — read/write Confluence pages via Atlassian REST API v2.
+ *
+ * Auth: API token + email + instance URL (same credential shape as Jira).
+ *   - Env vars: CONFLUENCE_API_TOKEN, CONFLUENCE_INSTANCE_URL, CONFLUENCE_EMAIL
+ *   - Stored: getSecretJsonSync("confluence") → ConfluenceTokens
+ *
+ * Tools: getPage, search, createPage, appendToPage, listSpaces
+ *
+ * Extends BaseConnector for unified auth, retry, rate-limit, error handling.
+ */
+import { type AuthContext, BaseConnector, type ConnectorError, type ConnectorStatus } from "./baseConnector.js";
+export interface ConfluenceTokens {
+    accessToken: string;
+    email: string;
+    instanceUrl: string;
+    connected_at: string;
+}
+export interface ConfluencePage {
+    id: string;
+    title: string;
+    status: string;
+    spaceId: string;
+    parentId?: string;
+    version: {
+        number: number;
+        createdAt: string;
+    };
+    body?: {
+        storage?: {
+            value: string;
+            representation: "storage";
+        };
+    };
+    _links: {
+        webui: string;
+    };
+}
+export interface ConfluenceSpace {
+    id: string;
+    key: string;
+    name: string;
+    type: string;
+    status: string;
+    _links: {
+        webui: string;
+    };
+}
+export interface ConfluenceSearchResult {
+    results: Array<{
+        content: {
+            id: string;
+            type: string;
+            title: string;
+            _links: {
+                webui: string;
+            };
+        };
+        excerpt: string;
+        url: string;
+        lastModified: string;
+    }>;
+    totalSize: number;
+    start: number;
+    limit: number;
+}
+export declare class ConfluenceConnector extends BaseConnector {
+    readonly providerName = "confluence";
+    private tokens;
+    protected getOAuthConfig(): null;
+    authenticate(): Promise<AuthContext>;
+    healthCheck(): Promise<{
+        ok: boolean;
+        error?: ConnectorError;
+    }>;
+    normalizeError(error: unknown): ConnectorError;
+    getStatus(): ConnectorStatus;
+    getPage(pageId: string, includeBody?: boolean): Promise<ConfluencePage | null>;
+    search(query: string, limit?: number): Promise<ConfluenceSearchResult>;
+    createPage(params: {
+        spaceId: string;
+        title: string;
+        body: string;
+        parentId?: string;
+    }): Promise<ConfluencePage>;
+    appendToPage(pageId: string, content: string): Promise<ConfluencePage>;
+    listSpaces(limit?: number): Promise<ConfluenceSpace[]>;
+    private buildHeaders;
+}
+export declare function loadTokens(): ConfluenceTokens | null;
+export declare function saveTokens(tokens: ConfluenceTokens): void;
+export declare function clearTokens(): void;
+export declare function getConfluenceConnector(): ConfluenceConnector;
+export { getConfluenceConnector as confluence };
+export interface ConnectorHandlerResult {
+    status: number;
+    body: string;
+    contentType?: string;
+}
+/**
+ * POST /connections/confluence/connect  { token, email, instanceUrl }
+ */
+export declare function handleConfluenceConnect(body: string): Promise<ConnectorHandlerResult>;
+/**
+ * POST /connections/confluence/test
+ */
+export declare function handleConfluenceTest(): Promise<ConnectorHandlerResult>;
+/**
+ * DELETE /connections/confluence
+ */
+export declare function handleConfluenceDisconnect(): ConnectorHandlerResult;