feat: implement credential management and enhance error handling

vtkovapi · vtkovapi · commit b3c11fe44c84 · 2026-02-17T18:44:17.000-08:00
- Added credential management functionality to automatically resolve and map environment-specific credential UUIDs to human-readable names.
- Introduced a new `credentials.ts` module for credential resolution, including functions for building forward and reverse maps.
- Enhanced error handling in API requests by introducing a custom `VapiApiError` class for better error reporting.
- Updated the `pull` and `push` processes to incorporate credential resolution, ensuring seamless integration across environments.
- Improved logging for unresolved credentials and API errors to provide clearer feedback during operations.
- Revised the README to document the new credential management features and their usage.
diff --git a/README.md b/README.md
@@ -178,6 +178,7 @@ vapi-gitops/
 │   ├── state.ts                # State file management
 │   ├── resources.ts            # Resource loading (YAML, MD, TS)
 │   ├── resolver.ts             # Reference resolution
+│   ├── credentials.ts          # Credential resolution (name ↔ UUID)
 │   └── delete.ts               # Deletion & orphan checks
 ├── resources/
 │   ├── assistants/             # Assistant files (.md or .yml)
@@ -527,12 +528,53 @@ toolIds:
   - "uuid-1234-5678-abcd"
 ```
 
+### Credential Management
+
+Credentials (API keys, JWT secrets, etc.) are environment-specific and managed automatically through the state file. No secrets are stored in resource files or git.
+
+**How it works:**
+
+1. **Pull** fetches all credentials from `GET /credential` and stores `name-slug → UUID` in the state file
+2. **Pull** replaces credential UUIDs with human-readable names in resource files
+3. **Push** reverses the mapping — resolves credential names back to UUIDs before sending to the API
+
+```yaml
+# Resource file stores credential NAME (environment-agnostic)
+server:
+  url: https://my-api.com/endpoint
+  credentialId: my-server-credential    # ← human-readable name
+```
+
+```json
+// State file stores credential UUID (environment-specific)
+{
+  "credentials": {
+    "my-server-credential": "2f6db611-ad08-4099-8bd8-74db37b0a07e"
+  }
+}
+```
+
+**Cross-environment workflow:**
+
+Each environment has its own state file with its own credential UUIDs. The same resource file works across all environments — only the state file differs:
+
+```
+.vapi-state.dev.json  → "my-cred": "uuid-for-dev"
+.vapi-state.stg.json  → "my-cred": "uuid-for-stg"
+.vapi-state.prod.json → "my-cred": "uuid-for-prod"
+```
+
+> **Note:** Credentials are auto-discovered from the Vapi API by name. Create credentials with the same name in each environment's Vapi org, and pull will populate the mappings automatically.
+
 ### State File
 
 Tracks mapping between resource IDs and Vapi UUIDs:
 
 ```json
 {
+  "credentials": {
+    "my-server-credential": "uuid-0000"
+  },
   "tools": {
     "my-tool": "uuid-1234"
   },
@@ -593,6 +635,17 @@ Check the state file has correct UUID:
 2. Find the resource entry
 3. If incorrect, delete entry and re-run push
 
+### "Credential with ID not found" errors
+
+The credential UUID doesn't exist in the target environment. Fix:
+1. Run `npm run pull:{env}` to fetch credentials into the state file
+2. If the credential doesn't exist in the target org, create it in the Vapi dashboard with the same name
+3. Pull again — the mapping will be auto-populated
+
+### "Unresolved credential" warnings
+
+A resource file has a `credentialId` that couldn't be resolved to a UUID. This means the credential name isn't in the state file. Run `pull` to populate credential mappings.
+
 ### "property X should not exist" API errors
 
 Some properties can't be updated after creation. Add them to `UPDATE_EXCLUDED_KEYS` in `src/config.ts`.
diff --git a/src/api.ts b/src/api.ts
@@ -5,6 +5,28 @@ import type { VapiResponse } from "./types.ts";
 // HTTP Client for Vapi API
 // ─────────────────────────────────────────────────────────────────────────────
 
+export class VapiApiError extends Error {
+  constructor(
+    public readonly method: string,
+    public readonly endpoint: string,
+    public readonly statusCode: number,
+    public readonly apiMessage: string,
+    public readonly rawBody: string,
+  ) {
+    super(`API ${method} ${endpoint} failed (${statusCode}): ${apiMessage}`);
+    this.name = "VapiApiError";
+  }
+}
+
+function parseApiMessage(body: string): string {
+  try {
+    const parsed = JSON.parse(body);
+    if (typeof parsed.message === "string") return parsed.message;
+    if (Array.isArray(parsed.message)) return parsed.message.join("; ");
+  } catch { /* not JSON, use raw body */ }
+  return body;
+}
+
 const MAX_RETRIES = 5;
 const INITIAL_DELAY_MS = 2000;
 const REQUEST_DELAY_MS = 700; // Delay between requests to avoid rate limits
@@ -55,12 +77,10 @@ export async function vapiRequest<T = VapiResponse>(
     }
 
     const errorText = await response.text();
-    throw new Error(
-      `API ${method} ${endpoint} failed (${response.status}): ${errorText}`
-    );
+    throw new VapiApiError(method, endpoint, response.status, parseApiMessage(errorText), errorText);
   }
 
-  throw new Error(`API ${method} ${endpoint} failed: max retries exceeded`);
+  throw new VapiApiError(method, endpoint, 429, "max retries exceeded", "");
 }
 
 export async function vapiDelete(endpoint: string): Promise<void> {
@@ -88,11 +108,9 @@ export async function vapiDelete(endpoint: string): Promise<void> {
     }
 
     const errorText = await response.text();
-    throw new Error(
-      `API DELETE ${endpoint} failed (${response.status}): ${errorText}`
-    );
+    throw new VapiApiError("DELETE", endpoint, response.status, parseApiMessage(errorText), errorText);
   }
 
-  throw new Error(`API DELETE ${endpoint} failed: max retries exceeded`);
+  throw new VapiApiError("DELETE", endpoint, 429, "max retries exceeded", "");
 }
 
diff --git a/src/config.ts b/src/config.ts
@@ -127,7 +127,7 @@ function parseFlags(): { forceDelete: boolean; applyFilter: ApplyFilter } {
 
 function loadEnvFile(env: string, baseDir: string): void {
   const envFiles = [
-    join(baseDir, `.env.${env}`),       // .env.dev, .env.stg, .env.prod
+    join(baseDir, `.env.${env}`),       // .env.dev, .env.staging, .env.prod
     join(baseDir, `.env.${env}.local`), // .env.dev.local (for local overrides)
     join(baseDir, ".env.local"),        // .env.local (always loaded last)
   ];
diff --git a/src/credentials.ts b/src/credentials.ts
@@ -0,0 +1,57 @@
+import type { StateFile } from "./types.ts";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Credential Resolution — resolve org-specific credential UUIDs across environments
+//
+// Credentials are pulled from the API and stored in state (name-slug → UUID).
+// Resource files store credential NAMES (e.g., "roofr-server-credential").
+// Push resolves names → UUIDs. Pull resolves UUIDs → names.
+// ─────────────────────────────────────────────────────────────────────────────
+
+// Build UUID → name reverse map from state.credentials
+export function credentialReverseMap(state: StateFile): Map<string, string> {
+  const map = new Map<string, string>();
+  for (const [name, uuid] of Object.entries(state.credentials)) {
+    map.set(uuid, name);
+  }
+  return map;
+}
+
+// Build name → UUID forward map from state.credentials
+export function credentialForwardMap(state: StateFile): Map<string, string> {
+  const map = new Map<string, string>();
+  for (const [name, uuid] of Object.entries(state.credentials)) {
+    map.set(name, uuid);
+  }
+  return map;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Deep walk: replace string values matching the map keys
+// Works at any depth in any object/array structure
+// ─────────────────────────────────────────────────────────────────────────────
+
+export function deepReplaceValues<T>(obj: T, replacements: Map<string, string>): T {
+  if (replacements.size === 0) return obj;
+  return walk(obj, replacements) as T;
+}
+
+function walk(value: unknown, replacements: Map<string, string>): unknown {
+  if (typeof value === "string") {
+    return replacements.get(value) ?? value;
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((item) => walk(item, replacements));
+  }
+
+  if (value !== null && typeof value === "object") {
+    const result: Record<string, unknown> = {};
+    for (const [key, val] of Object.entries(value as Record<string, unknown>)) {
+      result[key] = walk(val, replacements);
+    }
+    return result;
+  }
+
+  return value;
+}
diff --git a/src/delete.ts b/src/delete.ts
@@ -1,4 +1,4 @@
-import { vapiDelete } from "./api.ts";
+import { vapiDelete, VapiApiError } from "./api.ts";
 import { FORCE_DELETE } from "./config.ts";
 import { extractReferencedIds } from "./resolver.ts";
 import type {
@@ -229,7 +229,8 @@ export async function deleteOrphanedResources(
       delete state[stateKey][resourceId];
       deleted++;
     } catch (error) {
-      console.error(`  ❌ Failed to delete ${type} ${resourceId}:`, error);
+      const msg = error instanceof VapiApiError ? error.apiMessage : (error instanceof Error ? error.message : String(error));
+      console.error(`  ❌ Failed to delete ${type} ${resourceId}: ${msg}`);
       throw error;
     }
   }
diff --git a/src/pull.ts b/src/pull.ts
@@ -1,9 +1,11 @@
 import { execSync } from "child_process";
+import { existsSync, readdirSync } from "fs";
 import { mkdir, writeFile } from "fs/promises";
 import { join, dirname, relative } from "path";
 import { stringify } from "yaml";
 import { VAPI_ENV, VAPI_BASE_URL, VAPI_TOKEN, RESOURCES_DIR, BASE_DIR, APPLY_FILTER } from "./config.ts";
 import { loadState, saveState } from "./state.ts";
+import { credentialReverseMap, deepReplaceValues } from "./credentials.ts";
 import type { StateFile, ResourceType } from "./types.ts";
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -108,7 +110,9 @@ export async function fetchAllResources(resourceType: ResourceType): Promise<Vap
 
   if (!response.ok) {
     const errorText = await response.text();
-    throw new Error(`API GET ${endpoint} failed (${response.status}): ${errorText}`);
+    let apiMessage = errorText;
+    try { const parsed = JSON.parse(errorText); if (typeof parsed.message === "string") apiMessage = parsed.message; } catch {}
+    throw new Error(`API GET ${endpoint} failed (${response.status}): ${apiMessage}`);
   }
 
   const data = await response.json();
@@ -121,6 +125,64 @@ export async function fetchAllResources(resourceType: ResourceType): Promise<Vap
   return data as VapiResource[];
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Credential Fetching
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface VapiCredential {
+  id: string;
+  name?: string;
+  provider: string;
+  [key: string]: unknown;
+}
+
+async function fetchCredentials(): Promise<VapiCredential[]> {
+  const url = `${VAPI_BASE_URL}/credential`;
+  const response = await fetch(url, {
+    method: "GET",
+    headers: { Authorization: `Bearer ${VAPI_TOKEN}` },
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    let apiMessage = errorText;
+    try { const parsed = JSON.parse(errorText); if (typeof parsed.message === "string") apiMessage = parsed.message; } catch {}
+    throw new Error(`API GET /credential failed (${response.status}): ${apiMessage}`);
+  }
+
+  return (await response.json()) as VapiCredential[];
+}
+
+function credentialSlug(cred: VapiCredential): string {
+  const base = cred.name || cred.provider || "credential";
+  return slugify(base);
+}
+
+async function pullCredentials(state: StateFile): Promise<void> {
+  console.log("\n🔑 Pulling credentials...");
+  const credentials = await fetchCredentials();
+  console.log(`   Found ${credentials.length} credentials in Vapi`);
+
+  const newSection: Record<string, string> = {};
+  // Build reverse map from existing state to preserve slug stability
+  const existingReverse = new Map<string, string>();
+  for (const [slug, uuid] of Object.entries(state.credentials)) {
+    existingReverse.set(uuid, slug);
+  }
+
+  for (const cred of credentials) {
+    // Reuse existing slug if available, otherwise generate a new one
+    let slug = existingReverse.get(cred.id);
+    if (!slug) {
+      slug = credentialSlug(cred);
+    }
+    newSection[slug] = cred.id;
+    console.log(`   🔑 ${slug} -> ${cred.id}`);
+  }
+
+  state.credentials = newSection;
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Naming & Slug Generation
 // ─────────────────────────────────────────────────────────────────────────────
@@ -147,6 +209,28 @@ function generateResourceId(resource: VapiResource): string {
   return name ? `${slugify(name)}-${shortId}` : `resource-${shortId}`;
 }
 
+// When pulling a new environment, a resource may already exist on disk under a
+// different UUID suffix (e.g., `end-call-tool-8102e715` from dev). Match by
+// name-slug so we reuse the existing file instead of creating a duplicate.
+function findExistingResourceId(
+  resourceType: ResourceType,
+  resource: VapiResource,
+): string | undefined {
+  const name = extractName(resource);
+  if (!name) return undefined;
+
+  const nameSlug = slugify(name);
+  const dir = join(RESOURCES_DIR, FOLDER_MAP[resourceType]);
+  if (!existsSync(dir)) return undefined;
+
+  const matches = readdirSync(dir)
+    .filter((f) => /\.(yml|yaml|md)$/.test(f))
+    .map((f) => f.replace(/\.(yml|yaml|md)$/, ""))
+    .filter((id) => id === nameSlug || id.startsWith(nameSlug + "-"));
+
+  return matches.length === 1 ? matches[0] : undefined;
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Resource Processing
 // ─────────────────────────────────────────────────────────────────────────────
@@ -395,6 +479,7 @@ export async function pullResourceType(
   console.log(`   Found ${resources.length} ${resourceType} in Vapi`);
 
   const reverseMap = buildReverseMap(state, resourceType);
+  const credReverse = credentialReverseMap(state);
   const newStateSection: Record<string, string> = {};
 
   let created = 0;
@@ -407,7 +492,9 @@ export async function pullResourceType(
     const isNew = !resourceId;
     
     if (!resourceId) {
-      resourceId = generateResourceId(resource);
+      // Reuse an existing file's resourceId if the name matches (cross-env pull)
+      resourceId = findExistingResourceId(resourceType, resource)
+        ?? generateResourceId(resource);
     }
 
     // Skip files that have been locally modified or deleted (default mode)
@@ -426,17 +513,18 @@ export async function pullResourceType(
     // Detect platform defaults (orgId is null/missing — read-only, immutable)
     const isPlatformDefault = resource.orgId === null || resource.orgId === undefined;
 
-    // Clean and resolve references
+    // Clean, resolve resource references, and replace credential UUIDs with names
     const cleaned = cleanResource(resource);
     const resolved = resolveReferencesToResourceIds(cleaned, state);
+    const withCredNames = deepReplaceValues(resolved, credReverse);
 
     // Mark platform defaults so apply skips them
     if (isPlatformDefault) {
-      resolved._platformDefault = true;
+      withCredNames._platformDefault = true;
     }
     
     // Write to file
-    const filePath = await writeResourceFile(resourceType, resourceId, resolved);
+    const filePath = await writeResourceFile(resourceType, resourceId, withCredNames);
     const icon = isPlatformDefault ? "🔒" : isNew ? "✨" : "📝";
     const relPath = relative(BASE_DIR, filePath);
     console.log(`   ${icon} ${resourceId} -> ${relPath}${isPlatformDefault ? " (platform default, read-only)" : ""}`);
@@ -492,6 +580,9 @@ async function main(): Promise<void> {
 
   const state = loadState();
 
+  // Credentials are always pulled first — they're needed to reverse-resolve UUIDs in resource files
+  await pullCredentials(state);
+
   const zero: PullStats = { created: 0, updated: 0, skipped: 0 };
   const stats: Record<string, PullStats> = {
     tools: { ...zero },
@@ -541,6 +632,6 @@ async function main(): Promise<void> {
 
 // Run the pull engine
 main().catch((error) => {
-  console.error("\n❌ Pull failed:", error);
+  console.error("\n❌ Pull failed:", error instanceof Error ? error.message : error);
   process.exit(1);
 });
diff --git a/src/push.ts b/src/push.ts
diff --git a/src/state.ts b/src/state.ts
diff --git a/src/types.ts b/src/types.ts
