postgresai 0.14.0-dev.70 → 0.14.0-dev.72

package/lib/init.ts

@@ -7,6 +7,32 @@ import * as path from "path";
 
 export const DEFAULT_MONITORING_USER = "postgres_ai_mon";
 
+/**
+ * Database provider type. Affects which prepare-db steps are executed.
+ * Known providers have specific behavior adjustments; unknown providers use default behavior.
+ * TODO: Consider auto-detecting provider from connection string or server version string.
+ * TODO: Consider making this more flexible via a config that specifies which steps/checks to skip.
+ */
+export type DbProvider = string;
+
+/** Known providers with special handling. Unknown providers are treated as self-managed. */
+export const KNOWN_PROVIDERS = ["self-managed", "supabase"] as const;
+
+/** Providers where we skip role creation (users managed externally). */
+const SKIP_ROLE_CREATION_PROVIDERS = ["supabase"];
+
+/** Providers where we skip ALTER USER statements (restricted by provider). */
+const SKIP_ALTER_USER_PROVIDERS = ["supabase"];
+
+/** Providers where we skip search_path verification (not set via ALTER USER). */
+const SKIP_SEARCH_PATH_CHECK_PROVIDERS = ["supabase"];
+
+/** Check if a provider is known and return a warning message if not. */
+export function validateProvider(provider: string | undefined): string | null {
+  if (!provider || KNOWN_PROVIDERS.includes(provider as any)) return null;
+  return `Unknown provider "${provider}". Known providers: ${KNOWN_PROVIDERS.join(", ")}. Treating as self-managed.`;
+}
+
 export type PgClientConfig = {
   connectionString?: string;
   host?: string;
@@ -458,10 +484,13 @@ export async function buildInitPlan(params: {
   monitoringUser?: string;
   monitoringPassword: string;
   includeOptionalPermissions: boolean;
+  /** Provider type. Affects which steps are included. Defaults to "self-managed". */
+  provider?: DbProvider;
 }): Promise<InitPlan> {
   // NOTE: kept async for API stability / potential future async template loading.
   const monitoringUser = params.monitoringUser || DEFAULT_MONITORING_USER;
   const database = params.database;
+  const provider = params.provider ?? "self-managed";
 
   const qRole = quoteIdent(monitoringUser);
   const qDb = quoteIdent(database);
@@ -475,12 +504,15 @@ export async function buildInitPlan(params: {
     DB_IDENT: qDb,
   };
 
-  // Role creation/update is done in one template file.
-  // Always use a single DO block to avoid race conditions between "role exists?" checks and CREATE USER.
-  // We:
-  // - create role if missing (and handle duplicate_object in case another session created it concurrently),
-  // - then ALTER ROLE to ensure the password is set to the desired value.
-  const roleStmt = `do $$ begin
+  // Some providers (e.g., Supabase) manage users externally - skip role creation.
+  // TODO: Make this more flexible by allowing users to specify which steps to skip via config.
+  if (!SKIP_ROLE_CREATION_PROVIDERS.includes(provider)) {
+    // Role creation/update is done in one template file.
+    // Always use a single DO block to avoid race conditions between "role exists?" checks and CREATE USER.
+    // We:
+    // - create role if missing (and handle duplicate_object in case another session created it concurrently),
+    // - then ALTER ROLE to ensure the password is set to the desired value.
+    const roleStmt = `do $$ begin
   if not exists (select 1 from pg_catalog.pg_roles where rolname = ${qRoleNameLit}) then
     begin
       create user ${qRole} with password ${qPw};
@@ -491,12 +523,30 @@ export async function buildInitPlan(params: {
   alter user ${qRole} with password ${qPw};
 end $$;`;
 
-  const roleSql = applyTemplate(loadSqlTemplate("01.role.sql"), { ...vars, ROLE_STMT: roleStmt });
-  steps.push({ name: "01.role", sql: roleSql });
+    const roleSql = applyTemplate(loadSqlTemplate("01.role.sql"), { ...vars, ROLE_STMT: roleStmt });
+    steps.push({ name: "01.role", sql: roleSql });
+  }
+
+  let permissionsSql = applyTemplate(loadSqlTemplate("02.permissions.sql"), vars);
+
+  // Some providers restrict ALTER USER - remove those statements.
+  // TODO: Make this more flexible by allowing users to specify which statements to skip via config.
+  if (SKIP_ALTER_USER_PROVIDERS.includes(provider)) {
+    permissionsSql = permissionsSql
+      .split("\n")
+      .filter((line) => {
+        const trimmed = line.trim();
+        // Keep comments and empty lines
+        if (trimmed.startsWith("--") || trimmed === "") return true;
+        // Filter out ALTER USER statements (case-insensitive, flexible whitespace)
+        return !/^\s*alter\s+user\s+/i.test(line);
+      })
+      .join("\n");
+  }
 
   steps.push({
     name: "02.permissions",
-    sql: applyTemplate(loadSqlTemplate("02.permissions.sql"), vars),
+    sql: permissionsSql,
   });
 
   // Helper functions (SECURITY DEFINER) for plan analysis and table info
@@ -612,6 +662,8 @@ export async function verifyInitSetup(params: {
   database: string;
   monitoringUser: string;
   includeOptionalPermissions: boolean;
+  /** Provider type. Affects which checks are performed. */
+  provider?: DbProvider;
 }): Promise<VerifyInitResult> {
   // Use a repeatable-read snapshot so all checks see a consistent view.
   await params.client.query("begin isolation level repeatable read;");
@@ -621,6 +673,7 @@ export async function verifyInitSetup(params: {
 
     const role = params.monitoringUser;
     const db = params.database;
+    const provider = params.provider ?? "self-managed";
 
     const roleRes = await params.client.query("select 1 from pg_catalog.pg_roles where rolname = $1", [role]);
     const roleExists = (roleRes.rowCount ?? 0) > 0;
@@ -684,16 +737,20 @@ export async function verifyInitSetup(params: {
       missingRequired.push("USAGE on schema public");
     }
 
-    const rolcfgRes = await params.client.query("select rolconfig from pg_catalog.pg_roles where rolname = $1", [role]);
-    const rolconfig = rolcfgRes.rows?.[0]?.rolconfig;
-    const spLine = Array.isArray(rolconfig) ? rolconfig.find((v: any) => String(v).startsWith("search_path=")) : undefined;
-    if (typeof spLine !== "string" || !spLine) {
-      missingRequired.push("role search_path is set");
-    } else {
-      // We accept any ordering as long as postgres_ai, public, and pg_catalog are included.
-      const sp = spLine.toLowerCase();
-      if (!sp.includes("postgres_ai") || !sp.includes("public") || !sp.includes("pg_catalog")) {
-        missingRequired.push("role search_path includes postgres_ai, public and pg_catalog");
+    // Some providers don't allow setting search_path via ALTER USER - skip this check.
+    // TODO: Make this more flexible by allowing users to specify which checks to skip via config.
+    if (!SKIP_SEARCH_PATH_CHECK_PROVIDERS.includes(provider)) {
+      const rolcfgRes = await params.client.query("select rolconfig from pg_catalog.pg_roles where rolname = $1", [role]);
+      const rolconfig = rolcfgRes.rows?.[0]?.rolconfig;
+      const spLine = Array.isArray(rolconfig) ? rolconfig.find((v: any) => String(v).startsWith("search_path=")) : undefined;
+      if (typeof spLine !== "string" || !spLine) {
+        missingRequired.push("role search_path is set");
+      } else {
+        // We accept any ordering as long as postgres_ai, public, and pg_catalog are included.
+        const sp = spLine.toLowerCase();
+        if (!sp.includes("postgres_ai") || !sp.includes("public") || !sp.includes("pg_catalog")) {
+          missingRequired.push("role search_path includes postgres_ai, public and pg_catalog");
+        }
       }
     }
 

package/lib/issues.ts

@@ -11,6 +11,17 @@ export const IssueStatus = {
   CLOSED: 1,
 } as const;
 
+/**
+ * Represents a PostgreSQL configuration parameter change recommendation.
+ * Used in action items to suggest config tuning.
+ */
+export interface ConfigChange {
+  /** PostgreSQL configuration parameter name (e.g., 'work_mem', 'shared_buffers') */
+  parameter: string;
+  /** Recommended value for the parameter (e.g., '256MB', '4GB') */
+  value: string;
+}
+
 export interface IssueActionItem {
   id: string;
   issue_id: string;
@@ -20,10 +31,27 @@ export interface IssueActionItem {
   is_done: boolean;
   done_by: number | null;
   done_at: string | null;
+  status: string;
+  status_reason: string | null;
+  status_changed_by: number | null;
+  status_changed_at: string | null;
+  sql_action: string | null;
+  configs: ConfigChange[];
   created_at: string;
   updated_at: string;
 }
 
+/**
+ * Summary of an action item (minimal fields for list views).
+ * Used in issue detail responses to provide quick overview of action items.
+ */
+export interface IssueActionItemSummary {
+  /** Action item ID (UUID) */
+  id: string;
+  /** Action item title */
+  title: string;
+}
+
 export interface Issue {
   id: string;
   title: string;
@@ -59,15 +87,21 @@ export interface IssueComment {
 
 export type IssueListItem = Pick<Issue, "id" | "title" | "status" | "created_at">;
 
-export type IssueDetail = Pick<Issue, "id" | "title" | "description" | "status" | "created_at" | "author_display_name">;
+export type IssueDetail = Pick<Issue, "id" | "title" | "description" | "status" | "created_at" | "author_display_name"> & {
+  action_items: IssueActionItemSummary[];
+};
 export interface FetchIssuesParams {
   apiKey: string;
   apiBaseUrl: string;
+  orgId?: number;
+  status?: "open" | "closed";
+  limit?: number;
+  offset?: number;
   debug?: boolean;
 }
 
 export async function fetchIssues(params: FetchIssuesParams): Promise<IssueListItem[]> {
-  const { apiKey, apiBaseUrl, debug } = params;
+  const { apiKey, apiBaseUrl, orgId, status, limit = 20, offset = 0, debug } = params;
   if (!apiKey) {
     throw new Error("API key is required");
   }
@@ -75,6 +109,17 @@ export async function fetchIssues(params: FetchIssuesParams): Promise<IssueListI
   const base = normalizeBaseUrl(apiBaseUrl);
   const url = new URL(`${base}/issues`);
   url.searchParams.set("select", "id,title,status,created_at");
+  url.searchParams.set("order", "id.desc");
+  url.searchParams.set("limit", String(limit));
+  url.searchParams.set("offset", String(offset));
+  if (typeof orgId === "number") {
+    url.searchParams.set("org_id", `eq.${orgId}`);
+  }
+  if (status === "open") {
+    url.searchParams.set("status", "eq.0");
+  } else if (status === "closed") {
+    url.searchParams.set("status", "eq.1");
+  }
 
   const headers: Record<string, string> = {
     "access-token": apiKey,
@@ -190,7 +235,7 @@ export async function fetchIssue(params: FetchIssueParams): Promise<IssueDetail
 
   const base = normalizeBaseUrl(apiBaseUrl);
   const url = new URL(`${base}/issues`);
-  url.searchParams.set("select", "id,title,description,status,created_at,author_display_name");
+  url.searchParams.set("select", "id,title,description,status,created_at,author_display_name,action_items");
   url.searchParams.set("id", `eq.${issueId}`);
   url.searchParams.set("limit", "1");
 
@@ -224,11 +269,23 @@ export async function fetchIssue(params: FetchIssueParams): Promise<IssueDetail
   if (response.ok) {
     try {
       const parsed = JSON.parse(data);
-      if (Array.isArray(parsed)) {
-        return (parsed[0] as IssueDetail) ?? null;
-      } else {
-        return parsed as IssueDetail;
+      const rawIssue = Array.isArray(parsed) ? parsed[0] : parsed;
+      if (!rawIssue) {
+        return null;
       }
+      // Map action_items to summary (id, title only)
+      const actionItemsSummary: IssueActionItemSummary[] = Array.isArray(rawIssue.action_items)
+        ? rawIssue.action_items.map((item: IssueActionItem) => ({ id: item.id, title: item.title }))
+        : [];
+      return {
+        id: rawIssue.id,
+        title: rawIssue.title,
+        description: rawIssue.description,
+        status: rawIssue.status,
+        created_at: rawIssue.created_at,
+        author_display_name: rawIssue.author_display_name,
+        action_items: actionItemsSummary,
+      } as IssueDetail;
     } catch {
       throw new Error(`Failed to parse issue response: ${data}`);
     }
@@ -612,3 +669,392 @@ export async function updateIssueComment(params: UpdateIssueCommentParams): Prom
     throw new Error(formatHttpError("Failed to update issue comment", response.status, data));
   }
 }
+
+// ============================================================================
+// Action Items API Functions
+// ============================================================================
+
+export interface FetchActionItemParams {
+  apiKey: string;
+  apiBaseUrl: string;
+  actionItemIds: string | string[];
+  debug?: boolean;
+}
+
+/**
+ * Fetch action item(s) by ID(s).
+ * Supports single ID or array of IDs.
+ *
+ * @param params - Fetch parameters
+ * @param params.apiKey - API authentication key
+ * @param params.apiBaseUrl - Base URL for the API
+ * @param params.actionItemIds - Single action item ID or array of IDs (UUIDs)
+ * @param params.debug - Enable debug logging
+ * @returns Array of action items matching the provided IDs
+ * @throws Error if API key is missing or no valid IDs provided
+ *
+ * @example
+ * // Fetch single action item
+ * const items = await fetchActionItem({ apiKey, apiBaseUrl, actionItemIds: "uuid-123" });
+ *
+ * @example
+ * // Fetch multiple action items
+ * const items = await fetchActionItem({ apiKey, apiBaseUrl, actionItemIds: ["uuid-1", "uuid-2"] });
+ */
+export async function fetchActionItem(params: FetchActionItemParams): Promise<IssueActionItem[]> {
+  const { apiKey, apiBaseUrl, actionItemIds, debug } = params;
+  if (!apiKey) {
+    throw new Error("API key is required");
+  }
+  // UUID format pattern for validation
+  const uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+  // Normalize to array, filter out null/undefined, trim, and validate UUID format
+  const rawIds = Array.isArray(actionItemIds) ? actionItemIds : [actionItemIds];
+  const validIds = rawIds
+    .filter((id): id is string => id != null && typeof id === "string")
+    .map(id => id.trim())
+    .filter(id => id.length > 0 && uuidPattern.test(id));
+  if (validIds.length === 0) {
+    throw new Error("actionItemId is required and must be a valid UUID");
+  }
+
+  const base = normalizeBaseUrl(apiBaseUrl);
+  const url = new URL(`${base}/issue_action_items`);
+  if (validIds.length === 1) {
+    url.searchParams.set("id", `eq.${validIds[0]}`);
+  } else {
+    // PostgREST IN syntax: id=in.(val1,val2,val3)
+    url.searchParams.set("id", `in.(${validIds.join(",")})`)
+  }
+
+  const headers: Record<string, string> = {
+    "access-token": apiKey,
+    "Prefer": "return=representation",
+    "Content-Type": "application/json",
+    "Connection": "close",
+  };
+
+  if (debug) {
+    const debugHeaders: Record<string, string> = { ...headers, "access-token": maskSecret(apiKey) };
+    console.log(`Debug: Resolved API base URL: ${base}`);
+    console.log(`Debug: GET URL: ${url.toString()}`);
+    console.log(`Debug: Auth scheme: access-token`);
+    console.log(`Debug: Request headers: ${JSON.stringify(debugHeaders)}`);
+  }
+
+  const response = await fetch(url.toString(), {
+    method: "GET",
+    headers,
+  });
+
+  if (debug) {
+    console.log(`Debug: Response status: ${response.status}`);
+    console.log(`Debug: Response headers: ${JSON.stringify(Object.fromEntries(response.headers.entries()))}`);
+  }
+
+  const data = await response.text();
+
+  if (response.ok) {
+    try {
+      const parsed = JSON.parse(data);
+      if (Array.isArray(parsed)) {
+        return parsed as IssueActionItem[];
+      }
+      return parsed ? [parsed as IssueActionItem] : [];
+    } catch {
+      throw new Error(`Failed to parse action item response: ${data}`);
+    }
+  } else {
+    throw new Error(formatHttpError("Failed to fetch action item", response.status, data));
+  }
+}
+
+export interface FetchActionItemsParams {
+  apiKey: string;
+  apiBaseUrl: string;
+  issueId: string;
+  debug?: boolean;
+}
+
+/**
+ * Fetch all action items for an issue.
+ *
+ * @param params - Fetch parameters
+ * @param params.apiKey - API authentication key
+ * @param params.apiBaseUrl - Base URL for the API
+ * @param params.issueId - Issue ID (UUID) to fetch action items for
+ * @param params.debug - Enable debug logging
+ * @returns Array of action items for the specified issue
+ * @throws Error if API key or issue ID is missing
+ */
+export async function fetchActionItems(params: FetchActionItemsParams): Promise<IssueActionItem[]> {
+  const { apiKey, apiBaseUrl, issueId, debug } = params;
+  if (!apiKey) {
+    throw new Error("API key is required");
+  }
+  if (!issueId) {
+    throw new Error("issueId is required");
+  }
+  // Validate UUID format to prevent PostgREST injection
+  const uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+  if (!uuidPattern.test(issueId.trim())) {
+    throw new Error("issueId must be a valid UUID");
+  }
+
+  const base = normalizeBaseUrl(apiBaseUrl);
+  const url = new URL(`${base}/issue_action_items`);
+  url.searchParams.set("issue_id", `eq.${issueId.trim()}`);
+
+  const headers: Record<string, string> = {
+    "access-token": apiKey,
+    "Prefer": "return=representation",
+    "Content-Type": "application/json",
+    "Connection": "close",
+  };
+
+  if (debug) {
+    const debugHeaders: Record<string, string> = { ...headers, "access-token": maskSecret(apiKey) };
+    console.log(`Debug: Resolved API base URL: ${base}`);
+    console.log(`Debug: GET URL: ${url.toString()}`);
+    console.log(`Debug: Auth scheme: access-token`);
+    console.log(`Debug: Request headers: ${JSON.stringify(debugHeaders)}`);
+  }
+
+  const response = await fetch(url.toString(), {
+    method: "GET",
+    headers,
+  });
+
+  if (debug) {
+    console.log(`Debug: Response status: ${response.status}`);
+    console.log(`Debug: Response headers: ${JSON.stringify(Object.fromEntries(response.headers.entries()))}`);
+  }
+
+  const data = await response.text();
+
+  if (response.ok) {
+    try {
+      return JSON.parse(data) as IssueActionItem[];
+    } catch {
+      throw new Error(`Failed to parse action items response: ${data}`);
+    }
+  } else {
+    throw new Error(formatHttpError("Failed to fetch action items", response.status, data));
+  }
+}
+
+export interface CreateActionItemParams {
+  apiKey: string;
+  apiBaseUrl: string;
+  issueId: string;
+  title: string;
+  description?: string;
+  sqlAction?: string;
+  configs?: ConfigChange[];
+  debug?: boolean;
+}
+
+/**
+ * Create a new action item for an issue.
+ *
+ * @param params - Creation parameters
+ * @param params.apiKey - API authentication key
+ * @param params.apiBaseUrl - Base URL for the API
+ * @param params.issueId - Issue ID (UUID) to create action item for
+ * @param params.title - Action item title
+ * @param params.description - Optional detailed description
+ * @param params.sqlAction - Optional SQL command to execute
+ * @param params.configs - Optional configuration parameter changes
+ * @param params.debug - Enable debug logging
+ * @returns Created action item ID
+ * @throws Error if required fields are missing or API call fails
+ */
+export async function createActionItem(params: CreateActionItemParams): Promise<string> {
+  const { apiKey, apiBaseUrl, issueId, title, description, sqlAction, configs, debug } = params;
+  if (!apiKey) {
+    throw new Error("API key is required");
+  }
+  if (!issueId) {
+    throw new Error("issueId is required");
+  }
+  // Validate UUID format
+  const uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+  if (!uuidPattern.test(issueId.trim())) {
+    throw new Error("issueId must be a valid UUID");
+  }
+  if (!title) {
+    throw new Error("title is required");
+  }
+
+  const base = normalizeBaseUrl(apiBaseUrl);
+  const url = new URL(`${base}/rpc/issue_action_item_create`);
+
+  const bodyObj: Record<string, unknown> = {
+    issue_id: issueId,
+    title: title,
+  };
+  if (description !== undefined) {
+    bodyObj.description = description;
+  }
+  if (sqlAction !== undefined) {
+    bodyObj.sql_action = sqlAction;
+  }
+  if (configs !== undefined) {
+    bodyObj.configs = configs;
+  }
+  const body = JSON.stringify(bodyObj);
+
+  const headers: Record<string, string> = {
+    "access-token": apiKey,
+    "Prefer": "return=representation",
+    "Content-Type": "application/json",
+    "Connection": "close",
+  };
+
+  if (debug) {
+    const debugHeaders: Record<string, string> = { ...headers, "access-token": maskSecret(apiKey) };
+    console.log(`Debug: Resolved API base URL: ${base}`);
+    console.log(`Debug: POST URL: ${url.toString()}`);
+    console.log(`Debug: Auth scheme: access-token`);
+    console.log(`Debug: Request headers: ${JSON.stringify(debugHeaders)}`);
+    console.log(`Debug: Request body: ${body}`);
+  }
+
+  const response = await fetch(url.toString(), {
+    method: "POST",
+    headers,
+    body,
+  });
+
+  if (debug) {
+    console.log(`Debug: Response status: ${response.status}`);
+    console.log(`Debug: Response headers: ${JSON.stringify(Object.fromEntries(response.headers.entries()))}`);
+  }
+
+  const data = await response.text();
+
+  if (response.ok) {
+    try {
+      return JSON.parse(data) as string;
+    } catch {
+      throw new Error(`Failed to parse create action item response: ${data}`);
+    }
+  } else {
+    throw new Error(formatHttpError("Failed to create action item", response.status, data));
+  }
+}
+
+export interface UpdateActionItemParams {
+  apiKey: string;
+  apiBaseUrl: string;
+  actionItemId: string;
+  title?: string;
+  description?: string;
+  isDone?: boolean;
+  status?: string;
+  statusReason?: string;
+  sqlAction?: string;
+  configs?: ConfigChange[];
+  debug?: boolean;
+}
+
+/**
+ * Update an existing action item.
+ *
+ * @param params - Update parameters
+ * @param params.apiKey - API authentication key
+ * @param params.apiBaseUrl - Base URL for the API
+ * @param params.actionItemId - Action item ID (UUID) to update
+ * @param params.title - New title
+ * @param params.description - New description
+ * @param params.isDone - Mark as done/not done
+ * @param params.status - Approval status: 'waiting_for_approval', 'approved', 'rejected'
+ * @param params.statusReason - Reason for status change
+ * @param params.sqlAction - SQL command to execute
+ * @param params.configs - Configuration parameter changes
+ * @param params.debug - Enable debug logging
+ * @throws Error if required fields missing or no update fields provided
+ */
+export async function updateActionItem(params: UpdateActionItemParams): Promise<void> {
+  const { apiKey, apiBaseUrl, actionItemId, title, description, isDone, status, statusReason, sqlAction, configs, debug } = params;
+  if (!apiKey) {
+    throw new Error("API key is required");
+  }
+  if (!actionItemId) {
+    throw new Error("actionItemId is required");
+  }
+  // Validate UUID format
+  const uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+  if (!uuidPattern.test(actionItemId.trim())) {
+    throw new Error("actionItemId must be a valid UUID");
+  }
+
+  // Check that at least one update field is provided
+  const hasUpdateField = title !== undefined || description !== undefined ||
+    isDone !== undefined || status !== undefined ||
+    statusReason !== undefined || sqlAction !== undefined || configs !== undefined;
+  if (!hasUpdateField) {
+    throw new Error("At least one field to update is required");
+  }
+
+  const base = normalizeBaseUrl(apiBaseUrl);
+  const url = new URL(`${base}/rpc/issue_action_item_update`);
+
+  const bodyObj: Record<string, unknown> = {
+    action_item_id: actionItemId,
+  };
+  if (title !== undefined) {
+    bodyObj.title = title;
+  }
+  if (description !== undefined) {
+    bodyObj.description = description;
+  }
+  if (isDone !== undefined) {
+    bodyObj.is_done = isDone;
+  }
+  if (status !== undefined) {
+    bodyObj.status = status;
+  }
+  if (statusReason !== undefined) {
+    bodyObj.status_reason = statusReason;
+  }
+  if (sqlAction !== undefined) {
+    bodyObj.sql_action = sqlAction;
+  }
+  if (configs !== undefined) {
+    bodyObj.configs = configs;
+  }
+  const body = JSON.stringify(bodyObj);
+
+  const headers: Record<string, string> = {
+    "access-token": apiKey,
+    "Prefer": "return=representation",
+    "Content-Type": "application/json",
+    "Connection": "close",
+  };
+
+  if (debug) {
+    const debugHeaders: Record<string, string> = { ...headers, "access-token": maskSecret(apiKey) };
+    console.log(`Debug: Resolved API base URL: ${base}`);
+    console.log(`Debug: POST URL: ${url.toString()}`);
+    console.log(`Debug: Auth scheme: access-token`);
+    console.log(`Debug: Request headers: ${JSON.stringify(debugHeaders)}`);
+    console.log(`Debug: Request body: ${body}`);
+  }
+
+  const response = await fetch(url.toString(), {
+    method: "POST",
+    headers,
+    body,
+  });
+
+  if (debug) {
+    console.log(`Debug: Response status: ${response.status}`);
+    console.log(`Debug: Response headers: ${JSON.stringify(Object.fromEntries(response.headers.entries()))}`);
+  }
+
+  if (!response.ok) {
+    const data = await response.text();
+    throw new Error(formatHttpError("Failed to update action item", response.status, data));
+  }
+}