documenso-debug-bundle

name	documenso-debug-bundle
description	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".
allowed-tools	Read, Write, Edit, Bash(curl:*), Bash(node:*), Grep
version	1.0.0
license	MIT
author	Jeremy Longshore <[e-mail]>

Documenso Debug Bundle

Overview

Comprehensive debugging tools and diagnostic scripts for Documenso integration issues.

Prerequisites

• Documenso SDK installed
• Access to logs and configuration
• curl for API testing

Debug Scripts

Script 1: Connection Diagnostic

// scripts/documenso-diagnostic.ts
import { Documenso } from "@documenso/sdk-typescript";

interface DiagnosticResult {
  timestamp: string;
  environment: {
    nodeVersion: string;
    sdkVersion: string;
    apiKeyPresent: boolean;
    apiKeyPrefix: string;
    baseUrl: string;
  };
  connectivity: {
    canConnect: boolean;
    latencyMs: number;
    error?: string;
  };
  account: {
    documentsCount?: number;
    templatesCount?: number;
    error?: string;
  };
}

async function runDiagnostic(): Promise<DiagnosticResult> {
  const result: DiagnosticResult = {
    timestamp: new Date().toISOString(),
    environment: {
      nodeVersion: process.version,
      sdkVersion: "latest", // Get from package.json
      apiKeyPresent: !!process.env.DOCUMENSO_API_KEY,
      apiKeyPrefix: process.env.DOCUMENSO_API_KEY?.substring(0, 7) ?? "missing",
      baseUrl: process.env.DOCUMENSO_BASE_URL ?? "https://app.documenso.com/api/v2/",
    },
    connectivity: {
      canConnect: false,
      latencyMs: 0,
    },
    account: {},
  };

  if (!process.env.DOCUMENSO_API_KEY) {
    result.connectivity.error = "DOCUMENSO_API_KEY not set";
    return result;
  }

  const client = new Documenso({
    apiKey: process.env.DOCUMENSO_API_KEY,
    serverURL: process.env.DOCUMENSO_BASE_URL,
  });

  // Test connectivity
  const startTime = Date.now();
  try {
    const docs = await client.documents.findV0({ perPage: 1 });
    result.connectivity.canConnect = true;
    result.connectivity.latencyMs = Date.now() - startTime;
    result.account.documentsCount = docs.totalPages ?? 0;
  } catch (error: any) {
    result.connectivity.error = `${error.statusCode}: ${error.message}`;
    result.connectivity.latencyMs = Date.now() - startTime;
  }

  // Test templates access
  try {
    const templates = await client.templates.findV0({ perPage: 1 });
    result.account.templatesCount = templates.totalPages ?? 0;
  } catch (error: any) {
    result.account.error = error.message;
  }

  return result;
}

// Run and output
runDiagnostic().then(result => {
  console.log("\n=== Documenso Diagnostic Report ===\n");
  console.log(JSON.stringify(result, null, 2));

  // Summary
  console.log("\n=== Summary ===");
  if (result.connectivity.canConnect) {
    console.log("Connection: OK");
    console.log(`Latency: ${result.connectivity.latencyMs}ms`);
  } else {
    console.log("Connection: FAILED");
    console.log(`Error: ${result.connectivity.error}`);
  }
});

Script 2: Document Inspector

// scripts/inspect-document.ts
import { Documenso } from "@documenso/sdk-typescript";

async function inspectDocument(documentId: string) {
  const client = new Documenso({
    apiKey: process.env.DOCUMENSO_API_KEY ?? "",
  });

  console.log(`\n=== Inspecting Document: ${documentId} ===\n`);

  try {
    const doc = await client.documents.getV0({ documentId });

    console.log("Document Details:");
    console.log(`  ID: ${doc.id}`);
    console.log(`  Title: ${doc.title}`);
    console.log(`  Status: ${doc.status}`);
    console.log(`  Created: ${doc.createdAt}`);
    console.log(`  Updated: ${doc.updatedAt}`);

    console.();
     ( recipient  doc. ?? []) {
      .();
      .();
      .();
      .();
      .();
    }

    .();
     ( field  doc. ?? []) {
      .();
      .();
      .();
      .();
      .();
    }

     doc;
  }  (: ) {
    .();
    .();
     error;
  }
}


 documentId = process.[];
 (documentId) {
  (documentId);
}  {
  .();
}

Script 3: API Request Logger

// scripts/logged-client.ts
import { Documenso } from "@documenso/sdk-typescript";

// Create a logged wrapper
function createLoggedClient(): Documenso {
  const client = new Documenso({
    apiKey: process.env.DOCUMENSO_API_KEY ?? "",
    serverURL: process.env.DOCUMENSO_BASE_URL,
    debugLogger: {
      log: (...args) => {
        const timestamp = new Date().toISOString();
        console.log(`[${timestamp}] DEBUG:`, ...args);
      },
      warn: (...args) => {
        const timestamp = new Date().toISOString();
        console.warn(`[${timestamp}] WARN:`, ...args);
      },
      error: (...args) => {
        const timestamp = new Date().toISOString();
        console.(, ...args);
      },
    },
  });

   client;
}

 { createLoggedClient };

Script 4: Webhook Tester

// scripts/test-webhook.ts
import express from "express";
import crypto from "crypto";

const app = express();

// Log all incoming requests
app.use((req, res, next) => {
  console.log(`\n=== Incoming Request ===`);
  console.log(`Time: ${new Date().toISOString()}`);
  console.log(`Method: ${req.method}`);
  console.log(`Path: ${req.path}`);
  console.log(`Headers:`, JSON.stringify(req.headers, null, 2));
  next();
});

// Parse raw body for signature verification
app.use(express.raw({ type: "application/json" }));

app.post("/webhook/documenso", (req, res) => {
  const secret = req.headers["x-documenso-secret"];
   expectedSecret = process..;

  .();
  .();
  .();

   {
     payload = .(req..());
    .();
    .();
    .();
    .(, .(payload, , ));

    res.().({ :  });
  }  (error) {
    .(, error);
    res.().({ :  });
  }
});

  = process.. || ;
app.(,  {
  .();
  .();
  .();
});

Script 5: Bulk Document Status Check

// scripts/check-document-status.ts
import { Documenso } from "@documenso/sdk-typescript";

async function checkAllDocuments() {
  const client = new Documenso({
    apiKey: process.env.DOCUMENSO_API_KEY ?? "",
  });

  console.log("Fetching all documents...\n");

  const statusCounts: Record<string, number> = {};
  const pendingDocs: Array<{ id: string; title: string; age: string }> = [];

  let page = 1;
  let hasMore = true;

  while (hasMore) {
    const result = await client.documents.findV0({
      page,
      perPage: 100,
    });

    for (const doc of result.documents ?? []) {
      const status = doc.status ?? "UNKNOWN";
      statusCounts[status] = (statusCounts[status] ?? ) + ;

      
       (status === ) {
         createdAt =  (doc.!);
         age = (createdAt);
        pendingDocs.({
          : doc.!,
          : doc. ?? ,
          age,
        });
      }
    }

    hasMore = (result.?. ?? ) === ;
    page++;
  }

  .();
   ( [status, count]  .(statusCounts)) {
    .();
  }

   (pendingDocs. > ) {
    .();
     ( doc  pendingDocs.(, )) {
      .();
    }
     (pendingDocs. > ) {
      .();
    }
  }
}

 ():  {
   now =  ();
   diffMs = now.() - date.();
   diffDays = .(diffMs / ( *  *  * ));

   (diffDays === )  ;
   (diffDays === )  ;
   (diffDays < )  ;
   (diffDays < )  ;
   ;
}

().(.);

curl Debug Commands

# Test API connectivity
curl -v -H "Authorization: Bearer $DOCUMENSO_API_KEY" \
  https://app.documenso.com/api/v2/documents

# Get specific document
curl -H "Authorization: Bearer $DOCUMENSO_API_KEY" \
  https://app.documenso.com/api/v2/documents/{documentId}

# List templates
curl -H "Authorization: Bearer $DOCUMENSO_API_KEY" \
  https://app.documenso.com/api/v2/templates

# Test webhook endpoint
curl -X POST http://localhost:3000/webhook/documenso \
  -H "Content-Type: application/json" \
  -H "X-Documenso-Secret: your-secret" \
  -d '{"event":"document.completed","payload":{"id":"test"}}'

Environment Checklist

#!/bin/bash
# scripts/check-env.sh

echo "=== Documenso Environment Check ==="

# Check API key
if [ -z "$DOCUMENSO_API_KEY" ]; then
  echo "DOCUMENSO_API_KEY: NOT SET"
else
  echo "DOCUMENSO_API_KEY: SET (${DOCUMENSO_API_KEY:0:7}...)"
fi

# Check base URL
if [ -z "$DOCUMENSO_BASE_URL" ]; then
  echo "DOCUMENSO_BASE_URL: NOT SET (using default)"
else
  echo "DOCUMENSO_BASE_URL: $DOCUMENSO_BASE_URL"
fi

# Check webhook secret
if [ -z "$DOCUMENSO_WEBHOOK_SECRET" ]; then
  echo "DOCUMENSO_WEBHOOK_SECRET: NOT SET"
else
  echo "DOCUMENSO_WEBHOOK_SECRET: SET"
fi

# Test connectivity
echo ""
echo "Testing connectivity..."
response=$(curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer $DOCUMENSO_API_KEY" \
  ${DOCUMENSO_BASE_URL:-https://app.documenso.com/api/v2/}documents?perPage=1)

if [ "" =  ]; 
   
 [  =  ]; 
   

   

Support Ticket Template

When creating a support ticket, include:

## Documenso Support Request

### Environment
- SDK Version: @documenso/sdk-typescript@x.x.x
- Node.js Version: v20.x.x
- Environment: Production / Staging
- API Base URL: https://app.documenso.com/api/v2/

### Issue Description
[Describe what you expected vs what happened]

### Steps to Reproduce
1. [Step 1]
2. [Step 2]
3. [Step 3]

### Error Details

[Paste error message and stack trace]

### Diagnostic Output
```json
[Paste output from documenso-diagnostic.ts]

Document IDs (if applicable)

• Document ID: doc_xxx
• Template ID: tmpl_xxx

Request/Response (if applicable)

[Paste relevant API request and response]

## Output
- Diagnostic scripts ready
- Environment validated
- Debug logging enabled
- Support ticket template prepared

## Resources
- [Documenso GitHub Issues](https://github.com/documenso/documenso/issues)
- [Documenso Discord](https://documenso.com/discord)
- [API Status](https://status.documenso.com)

## Next Steps
For rate limit handling, see `documenso-rate-limits`.