Documenso Performance TuningSAFE

Model-agnostic agent-skills platform with a harness-free canonical layer, verified adapters, and the ccpi package manager. Explore at tonsofskills.com.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: documenso-performance-tuning
description: 'Optimize Documenso integration performance with caching, batching, and
  efficient patterns.

  Use when improving response times, reducing API calls,

  or optimizing bulk document operations.

  Trigger with phrases like "documenso performance", "optimize documenso",

  "documenso caching", "documenso batch operations".

  '
allowed-tools: Read, Write, Edit
version: 1.14.0
license: MIT
author: Jeremy Longshore <[email protected]>
tags:
- saas
- documenso
- api
- performance
compatibility: Designed for Claude Code
---
# Documenso Performance Tuning

## Output

- A measured performance change with document/signing lifecycle, authorization, audit, and reliability guardrails.
- A reversible change record with aggregate metrics, owner, threshold, and rollback decision.

## Examples

Measure synthetic-document workflow latency, throughput, error rate, and callback completion in staging, change one approved capacity/cache/concurrency setting, and compare against baseline. Revert if signing state, authorization, audit, or error behavior regresses; do not use real documents or weaken controls to improve a benchmark.

## Overview

Optimize Documenso integrations for speed and efficiency. Key strategies: reduce API round-trips with templates, cache document metadata, batch operations with concurrency control, and use async processing for bulk signing workflows.

## Prerequisites

- Working Documenso integration
- Redis or in-memory cache (recommended)
- Completed `documenso-sdk-patterns` setup

## Instructions

### Step 1: Reduce API Calls with Templates

The biggest performance win: templates reduce a multi-step document creation (create + upload + add recipients + add fields + send = 5+ calls) to just 2 calls (create from template + send).

```typescript
// WITHOUT templates: 5+ API calls per document
async function createDocumentManual(signer: { email: string; name: string }) {
  const doc = await client.documents.createV0({ title: "Contract" });              // 1
  await client.documents.setFileV0(doc.documentId, { file: pdfBlob });             // 2
  const recip = await client.documentsRecipients.createV0(doc.documentId, {        // 3
    email: signer.email, name: signer.name, role: "SIGNER",
  });
  await client.documentsFields.createV0(doc.documentId, {                          // 4
    recipientId: recip.recipientId, type: "SIGNATURE",
    pageNumber: 1, pageX: 10, pageY: 80, pageWidth: 30, pageHeight: 5,
  });
  await client.documents.sendV0(doc.documentId);                                   // 5
}

// WITH templates: 2 API calls per document
async function createDocumentFromTemplate(templateId: number, signer: { email: string; name: string }) {
  const res = await fetch(                                                          // 1
    `${BASE}/templates/${templateId}/create-document`,
    {
      method: "POST",
      headers: { Authorization: `Bearer ${API_KEY}`, "Content-Type": "application/json" },
      body: JSON.stringify({
        title: `Contract — ${signer.name}`,
        recipients: [{ email: signer.email, name: signer.name, role: "SIGNER" }],
      }),
    }
  );
  const doc = await res.json();
  await fetch(`${BASE}/documents/${doc.documentId}/send`, {                         // 2
    method: "POST",
    headers: { Authorization: `Bearer ${API_KEY}` },
  });
}
```

### Step 2: Cache Document Metadata

```typescript
// src/cache/documenso-cache.ts
import NodeCache from "node-cache";

const cache = new NodeCache({ stdTTL: 300, checkperiod: 60 }); // 5 min TTL

export async function getCachedDocument(client: Documenso, documentId: number) {
  const key = `doc:${documentId}`;
  const cached = cache.get(key);
  if (cached) return cached;

  const doc = await client.documents.getV0(documentId);
  // Only cache completed documents (immutable)
  if (doc.status === "COMPLETED") {
    cache.set(key, doc, 3600); // 1 hour for completed
  } else {
    cache.set(key, doc, 30); // 30 seconds for in-progress
  }
  return doc;
}

// Invalidate on webhook events
export function invalidateDocument(documentId: number) {
  cache.del(`doc:${documentId}`);
}
```

### Step 3: Batch Operations with Concurrency Control

```typescript
// src/batch/documenso-batch.ts
import PQueue from "p-queue";

const queue = new PQueue({
  concurrency: 5,       // Max 5 concurrent API calls
  interval: 1000,       // Per second window
  intervalCap: 10,      // Max 10 per second
});

export async function batchCreateDocuments(
  client: Documenso,
  templateId: number,
  signers: Array<{ email: string; name: string; company: string }>
): Promise<Array<{ email: string; documentId?: number; error?: string }>> {
  const results = await Promise.allSettled(
    signers.map((signer) =>
      queue.add(async () => {
        const res = await fetch(
          `https://app.documenso.com/api/v1/templates/${templateId}/create-document`,
          {
            method: "POST",
            headers: {
              Authorization: `Bearer ${process.env.DOCUMENSO_API_KEY}`,
              "Content-Type": "application/json",
            },
            body: JSON.stringify({
              title: `Agreement — ${signer.company}`,
              recipients: [{ email: signer.email, name: signer.name, role: "SIGNER" }],
            }),
          }
        );
        if (!res.ok) throw new Error(`HTTP ${res.status}`);
        const doc = await res.json();

        // Send immediately
        await fetch(
          `https://app.documenso.com/api/v1/documents/${doc.documentId}/send`,
          {
            method: "POST",
            headers: { Authorization: `Bearer ${process.env.DOCUMENSO_API_KEY}` },
          }
        );

        return { email: signer.email, documentId: doc.documentId };
      })
    )
  );

  return results.map((r, i) => {
    if (r.status === "fulfilled") return r.value as any;
    return { email: signers[i].email, error: (r.reason as Error).message };
  

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.