patchwork-os 0.2.0-alpha.33 → 0.2.0-alpha.35

package/dist/connectors/asana.d.ts

@@ -0,0 +1,198 @@
+/**
+ * Asana connector — read workspaces, projects, tasks, and current user, plus
+ * writes (createTask, updateTask, completeTask, addTaskComment).
+ *
+ * OAuth 2.0 Authorization Code Grant. Asana is a confidential client (bridge
+ * holds client secret), so PKCE is not used. Refresh tokens are issued; access
+ * tokens expire after 1 hour (3600s).
+ *
+ * Auth: standard OAuth 2.0 with `client_id` + `client_secret` + `redirect_uri`.
+ *   - Env vars: ASANA_CLIENT_ID, ASANA_CLIENT_SECRET (mirrors discord/slack)
+ *   - Stored: getSecretJsonSync("asana") → AsanaTokens
+ *   - Header: Authorization: Bearer <access_token>
+ *
+ * Scope note: Asana's only OAuth scope is `default`, which grants read+write
+ * combined — there is no read-only-only scope. Defense lives at the recipe-tool
+ * layer where each tool declares `isWrite: true|false`. Newer Asana accounts
+ * may also expose granular scopes; we set `default` for compatibility.
+ *
+ * Read tools: getCurrentUser, listWorkspaces, listProjects, listTasks, getTask.
+ * Write tools: createTask, updateTask, completeTask, addTaskComment.
+ *
+ * Idempotency: Asana doesn't honor an Idempotency-Key header. Writes simply
+ * throw on error — callers must dedupe via app-level checks if needed.
+ *
+ * HTTP routes (wired in src/server.ts):
+ *   GET    /connections/asana/auth     — redirect to Asana consent
+ *   GET    /connections/asana/callback — exchange code for tokens
+ *   POST   /connections/asana/test     — ping Asana API
+ *   DELETE /connections/asana          — clear stored tokens
+ *
+ * Asana wraps every API response in `{ data: ... }`. We unwrap consistently
+ * inside this class so recipe-tool wrappers see clean arrays/objects.
+ *
+ * Extends BaseConnector for unified auth, retry, rate-limit, error handling.
+ * Token refresh is delegated to BaseConnector.refreshToken() via apiCall.
+ */
+import { type AuthContext, BaseConnector, type ConnectorError, type ConnectorStatus, type OAuthConfig } from "./baseConnector.js";
+export interface AsanaTokens {
+    access_token: string;
+    refresh_token?: string;
+    /** ms since epoch; absolute, not relative */
+    expires_at?: number;
+    scope?: string;
+    token_type?: string;
+    /** stored at auth time so refresh works even if env vars are absent */
+    _client_id?: string;
+    _client_secret?: string;
+    username?: string;
+    user_gid?: string;
+    email?: string;
+    connected_at: string;
+}
+export interface AsanaUser {
+    gid: string;
+    name: string;
+    email?: string;
+    resource_type?: string;
+    photo?: {
+        image_60x60?: string;
+    } | null;
+}
+export interface AsanaWorkspace {
+    gid: string;
+    name: string;
+    resource_type?: string;
+    is_organization?: boolean;
+}
+export interface AsanaProject {
+    gid: string;
+    name: string;
+    resource_type?: string;
+    archived?: boolean;
+}
+export interface AsanaTask {
+    gid: string;
+    name: string;
+    resource_type?: string;
+    completed?: boolean;
+    assignee?: {
+        gid: string;
+        name?: string;
+    } | null;
+    due_on?: string | null;
+    notes?: string;
+}
+export interface AsanaStory {
+    gid: string;
+    resource_type?: string;
+    type?: string;
+    text?: string;
+    created_at?: string;
+    created_by?: {
+        gid: string;
+        name?: string;
+    } | null;
+}
+export interface CreateTaskParams {
+    workspaceGid: string;
+    name: string;
+    projectGid?: string;
+    notes?: string;
+    assigneeGid?: string;
+    /** ISO date YYYY-MM-DD */
+    dueOn?: string;
+    parentTaskGid?: string;
+}
+export interface UpdateTaskParams {
+    name?: string;
+    notes?: string;
+    completed?: boolean;
+    assigneeGid?: string;
+    /** ISO date YYYY-MM-DD */
+    dueOn?: string;
+}
+export declare function loadTokens(): AsanaTokens | null;
+export declare function saveTokens(tokens: AsanaTokens): void;
+export declare function clearTokens(): void;
+export declare function isConnected(): boolean;
+export declare class AsanaConnector extends BaseConnector {
+    readonly providerName = "asana";
+    protected getOAuthConfig(): OAuthConfig | null;
+    authenticate(): Promise<AuthContext>;
+    /**
+     * Persist refreshed tokens after BaseConnector.refreshToken() updates
+     * `this.auth`. BaseConnector calls `saveTokens()` (its own method on the
+     * tokenStorage StoredToken shape); we additionally mirror to our
+     * Asana-specific JSON so loadTokens() keeps working for HTTP probes.
+     */
+    saveTokens(): Promise<void>;
+    healthCheck(): Promise<{
+        ok: boolean;
+        error?: ConnectorError;
+    }>;
+    normalizeError(error: unknown): ConnectorError;
+    getStatus(): ConnectorStatus;
+    getCurrentUser(): Promise<AsanaUser>;
+    listWorkspaces(params?: {
+        limit?: number;
+    }): Promise<AsanaWorkspace[]>;
+    listProjects(params: {
+        workspaceGid: string;
+        limit?: number;
+    }): Promise<AsanaProject[]>;
+    listTasks(params?: {
+        projectGid?: string;
+        assignee?: string;
+        workspaceGid?: string;
+        limit?: number;
+    }): Promise<AsanaTask[]>;
+    getTask(taskGid: string): Promise<AsanaTask>;
+    createTask(params: CreateTaskParams): Promise<AsanaTask>;
+    updateTask(taskGid: string, updates: UpdateTaskParams): Promise<AsanaTask>;
+    /**
+     * Convenience wrapper around updateTask that flips `completed: true`. Lower
+     * risk than other updates since it's a single, well-known state transition.
+     */
+    completeTask(taskGid: string): Promise<AsanaTask>;
+    addTaskComment(taskGid: string, options: {
+        text: string;
+    }): Promise<AsanaStory>;
+    private buildHeaders;
+    private captureRateLimit;
+    /**
+     * Read the response body once and stash the first Asana `errors[].message`
+     * onto a sidecar property so normalizeError can include it without a second
+     * read. Returns the same Response for `throw` to consume.
+     */
+    private attachErrorDetail;
+}
+export declare function getAsanaConnector(): AsanaConnector;
+export { getAsanaConnector as asana };
+export interface ConnectorHandlerResult {
+    status: number;
+    body: string;
+    contentType?: string;
+    redirect?: string;
+}
+/**
+ * GET /connections/asana/auth — redirect to Asana consent screen.
+ */
+export declare function handleAsanaAuthorize(): ConnectorHandlerResult;
+/**
+ * GET /connections/asana/callback — exchange code for tokens.
+ */
+export declare function handleAsanaCallback(code: string | null, state: string | null, error: string | null): Promise<ConnectorHandlerResult>;
+/**
+ * POST /connections/asana/test — verify stored token works.
+ */
+export declare function handleAsanaTest(): Promise<ConnectorHandlerResult>;
+/**
+ * DELETE /connections/asana — clear stored tokens.
+ *
+ * Asana does not expose a public OAuth revocation endpoint, so we just drop
+ * local credentials. The token remains valid at Asana until it naturally
+ * expires (1h) or the user revokes the integration in their Asana account
+ * settings.
+ */
+export declare function handleAsanaDisconnect(): Promise<ConnectorHandlerResult>;