Agent skill
documenso-debug-bundle
Comprehensive debugging toolkit for Documenso integrations. Use when troubleshooting complex issues, gathering diagnostic information, or creating support tickets for Documenso problems. Trigger with phrases like "debug documenso", "documenso diagnostics", "troubleshoot documenso", "documenso support ticket".
Install this agent skill to your Project
npx add-skill https://github.com/jeremylongshore/claude-code-plugins-plus-skills/tree/main/plugins/saas-packs/documenso-pack/skills/documenso-debug-bundle
SKILL.md
Documenso Debug Bundle
Current State
!node --version 2>/dev/null || echo 'N/A'
!python3 --version 2>/dev/null || echo 'N/A'
!uname -a
Overview
Comprehensive debugging tools for Documenso integration issues. Includes diagnostic scripts, curl debug commands, environment verification, and support ticket templates.
Prerequisites
- Documenso SDK installed
- Access to logs and configuration
curlandjqavailable
Instructions
Step 1: Quick Connectivity Test
#!/bin/bash
set -euo pipefail
echo "=== Documenso Connectivity Test ==="
# 1. Check API key is set
if [ -z "${DOCUMENSO_API_KEY:-}" ]; then
echo "FAIL: DOCUMENSO_API_KEY not set"
exit 1
fi
echo "OK: API key set (${#DOCUMENSO_API_KEY} chars)"
# 2. Test authentication
BASE="${DOCUMENSO_BASE_URL:-https://app.documenso.com/api/v1}"
STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
-H "Authorization: Bearer $DOCUMENSO_API_KEY" \
"$BASE/documents?page=1&perPage=1")
if [ "$STATUS" = "200" ]; then
echo "OK: API authentication successful"
elif [ "$STATUS" = "401" ]; then
echo "FAIL: Invalid API key (401)"
exit 1
elif [ "$STATUS" = "403" ]; then
echo "FAIL: Insufficient permissions (403) — try a team API key"
exit 1
else
echo "WARN: Unexpected status $STATUS"
fi
# 3. Check latency
LATENCY=$(curl -s -o /dev/null -w "%{time_total}" \
-H "Authorization: Bearer $DOCUMENSO_API_KEY" \
"$BASE/documents?page=1&perPage=1")
echo "Latency: ${LATENCY}s"
# 4. List recent documents
echo "=== Recent Documents ==="
curl -s -H "Authorization: Bearer $DOCUMENSO_API_KEY" \
"$BASE/documents?page=1&perPage=5" | jq '.documents[] | {id, title, status, createdAt}'
Step 2: TypeScript Diagnostic Script
// scripts/documenso-diagnose.ts
import { Documenso } from "@documenso/sdk-typescript";
async function diagnose() {
const results: Array<{ test: string; status: "PASS" | "FAIL"; detail: string }> = [];
// Test 1: API key
const apiKey = process.env.DOCUMENSO_API_KEY;
if (!apiKey) {
results.push({ test: "API Key", status: "FAIL", detail: "DOCUMENSO_API_KEY not set" });
return results;
}
results.push({ test: "API Key", status: "PASS", detail: `Set (${apiKey.length} chars)` });
// Test 2: Connection
const client = new Documenso({
apiKey,
...(process.env.DOCUMENSO_BASE_URL && { serverURL: process.env.DOCUMENSO_BASE_URL }),
});
try {
const start = Date.now();
const { documents } = await client.documents.findV0({ page: 1, perPage: 1 });
const latency = Date.now() - start;
results.push({
test: "Connection",
status: "PASS",
detail: `${latency}ms, ${documents.length} documents returned`,
});
} catch (err: any) {
results.push({
test: "Connection",
status: "FAIL",
detail: `${err.statusCode ?? "unknown"}: ${err.message}`,
});
}
// Test 3: Create + Delete (write access)
try {
const doc = await client.documents.createV0({ title: "[DIAG] Test Document" });
await client.documents.deleteV0(doc.documentId);
results.push({ test: "Write Access", status: "PASS", detail: "Create+delete OK" });
} catch (err: any) {
results.push({
test: "Write Access",
status: "FAIL",
detail: err.message,
});
}
// Print report
console.log("\n=== Documenso Diagnostic Report ===");
for (const r of results) {
console.log(` [${r.status}] ${r.test}: ${r.detail}`);
}
const failures = results.filter((r) => r.status === "FAIL").length;
console.log(`\n${results.length} tests, ${failures} failures\n`);
return results;
}
diagnose();
Run: npx tsx scripts/documenso-diagnose.ts
Step 3: Debug Logging Wrapper
// src/documenso/debug-client.ts
import { Documenso } from "@documenso/sdk-typescript";
export function createDebugClient(): Documenso {
const client = new Documenso({ apiKey: process.env.DOCUMENSO_API_KEY! });
// Proxy to log all method calls
return new Proxy(client, {
get(target, prop) {
const value = (target as any)[prop];
if (typeof value === "object" && value !== null) {
return new Proxy(value, {
get(innerTarget, innerProp) {
const method = (innerTarget as any)[innerProp];
if (typeof method === "function") {
return async (...args: any[]) => {
const start = Date.now();
console.log(`[DOCUMENSO] ${String(prop)}.${String(innerProp)}(`, JSON.stringify(args).slice(0, 200), ")");
try {
const result = await method.apply(innerTarget, args);
console.log(`[DOCUMENSO] OK in ${Date.now() - start}ms`);
return result;
} catch (err: any) {
console.error(`[DOCUMENSO] FAIL in ${Date.now() - start}ms: ${err.statusCode} ${err.message}`);
throw err;
}
};
}
return method;
},
});
}
return value;
},
});
}
Step 4: Support Ticket Template
When filing an issue on GitHub or Discord:
## Environment
- Documenso: Cloud / Self-hosted v[version]
- SDK: @documenso/sdk-typescript v[version]
- Node.js: [version]
- OS: [os]
## Issue Description
[What you expected vs what happened]
## Steps to Reproduce
1. [Step 1]
2. [Step 2]
## API Request (sanitized)
- Method: POST /api/v2/documents
- Status: [HTTP status]
- Response: [error body, no secrets]
## Diagnostic Output
[Paste output from documenso-diagnose.ts]
## Logs
[Relevant log lines, sanitized]
Error Handling
| Issue | Cause | Solution |
|---|---|---|
| Diagnostic timeout | Slow API or network | Check connectivity, increase timeout |
| Write test fails | Read-only key or no team access | Use team API key with write permissions |
| Self-hosted unreachable | Docker container down | docker ps, check container logs |
| Latency > 5s | Network or infrastructure issue | Check if self-hosted DB is overloaded |
Resources
Next Steps
For rate limit handling, see documenso-rate-limits.
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
dockerfile-generator
Dockerfile Generator - Auto-activating skill for DevOps Basics. Triggers on: dockerfile generator, dockerfile generator Part of the DevOps Basics skill category.
branch-naming-helper
Branch Naming Helper - Auto-activating skill for DevOps Basics. Triggers on: branch naming helper, branch naming helper Part of the DevOps Basics skill category.
readme-generator
Readme Generator - Auto-activating skill for DevOps Basics. Triggers on: readme generator, readme generator Part of the DevOps Basics skill category.
makefile-generator
Makefile Generator - Auto-activating skill for DevOps Basics. Triggers on: makefile generator, makefile generator Part of the DevOps Basics skill category.
gitignore-generator
Gitignore Generator - Auto-activating skill for DevOps Basics. Triggers on: gitignore generator, gitignore generator Part of the DevOps Basics skill category.
pre-commit-hook-setup
Pre Commit Hook Setup - Auto-activating skill for DevOps Basics. Triggers on: pre commit hook setup, pre commit hook setup Part of the DevOps Basics skill category.
Didn't find tool you were looking for?