Documenso Local Dev LoopSAFE

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-local-dev-loop
description: 'Set up local development environment and testing workflow for Documenso.

  Use when configuring dev environment, setting up test workflows,

  or establishing rapid iteration patterns with Documenso.

  Trigger with phrases like "documenso local dev", "documenso development",

  "test documenso locally", "documenso dev environment".

  '
allowed-tools: Read, Write, Edit, Bash(npm:*), Bash(docker:*), Bash(node:*)
version: 1.14.0
license: MIT
author: Jeremy Longshore <[email protected]>
tags:
- saas
- documenso
- testing
- workflow
compatibility: Designed for Claude Code
---
# Documenso Local Dev Loop

## Output

- A small test-backed local change using synthetic documents/signers and a normal source-control rollback path.
- A redacted development verification receipt without document content, signing links, credentials, or signer PII.

## Examples

Use a development workspace with a synthetic template and signer, make one integration/config change, run its focused tests and a bounded lifecycle check, then inspect redacted status. Commit only reviewed changes; never use production documents, signing URLs, or credentials in local development.

## Overview

Configure a fast local development environment for Documenso integrations. Covers project structure, environment configs, self-hosted Documenso via Docker, test utilities, and cleanup scripts.

## Prerequisites

- Completed `documenso-install-auth` setup
- Node.js 18+ with TypeScript
- Docker (for self-hosted local Documenso)

## Instructions

### Step 1: Project Structure

```
my-signing-app/
├── src/
│   └── documenso/
│       ├── client.ts          # Configured SDK client
│       ├── documents.ts       # Document operations
│       ├── recipients.ts      # Recipient management
│       └── webhooks.ts        # Webhook handlers
├── scripts/
│   ├── verify-connection.ts   # Quick health check
│   ├── create-test-doc.ts     # Generate test documents
│   └── cleanup-test-docs.ts   # Remove test data
├── tests/
│   └── integration/
│       ├── document.test.ts
│       └── template.test.ts
├── .env.development
├── .env.test
└── .env.production
```

### Step 2: Environment Configuration

**.env.development:**

```bash
DOCUMENSO_API_KEY=api_dev_xxxxxxxxxxxx
DOCUMENSO_BASE_URL=https://stg-app.documenso.com/api/v2
DOCUMENSO_WEBHOOK_SECRET=whsec_dev_xxxxxxxxxxxx
LOG_LEVEL=debug
```

**.env.test:**

```bash
DOCUMENSO_API_KEY=api_test_xxxxxxxxxxxx
DOCUMENSO_BASE_URL=https://stg-app.documenso.com/api/v2
DOCUMENSO_WEBHOOK_SECRET=whsec_test_xxxxxxxxxxxx
LOG_LEVEL=warn
```

### Step 3: Client Wrapper with Dev Helpers

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

let _client: Documenso | null = null;

export function getClient(): Documenso {
  if (!_client) {
    _client = new Documenso({
      apiKey: process.env.DOCUMENSO_API_KEY!,
      ...(process.env.DOCUMENSO_BASE_URL && {
        serverURL: process.env.DOCUMENSO_BASE_URL,
      }),
    });
  }
  return _client;
}

// Dev helper: list recent documents for debugging
export async function listRecentDocs(limit = 5) {
  const client = getClient();
  const { documents } = await client.documents.findV0({
    page: 1,
    perPage: limit,
    orderByColumn: "createdAt",
    orderByDirection: "desc",
  });
  return documents;
}
```

### Step 4: Self-Hosted Local Documenso (Docker)

```bash
# Pull the official Documenso Docker image
docker pull documenso/documenso:latest

# Create docker-compose.local.yml
```

```yaml
# docker-compose.local.yml
services:
  documenso:
    image: documenso/documenso:latest
    ports:
      - "3000:3000"
    environment:
      - NEXTAUTH_URL=http://localhost:3000
      - NEXTAUTH_SECRET=local-dev-secret-change-me
      - NEXT_PRIVATE_ENCRYPTION_KEY=local-encryption-key
      - NEXT_PRIVATE_ENCRYPTION_SECONDARY_KEY=local-secondary-key
      - NEXT_PUBLIC_WEBAPP_URL=http://localhost:3000
      - NEXT_PRIVATE_DATABASE_URL=${DOCUMENSO_DATABASE_URL}
      - NEXT_PRIVATE_DIRECT_DATABASE_URL=${DOCUMENSO_DIRECT_DATABASE_URL}
      - NEXT_PRIVATE_SMTP_TRANSPORT=smtp-auth
      - NEXT_PRIVATE_SMTP_HOST=mailhog
      - NEXT_PRIVATE_SMTP_PORT=1025
    depends_on:
      - db
      - mailhog

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: documenso
      POSTGRES_PASSWORD: password
      POSTGRES_DB: documenso
    volumes:
      - pgdata:/var/lib/postgresql/data

  mailhog:
    image: mailhog/mailhog
    ports:
      - "8025:8025"  # Web UI for email inspection
      - "1025:1025"

volumes:
  pgdata:
```

```bash
docker compose -f docker-compose.local.yml up -d
# Documenso at http://localhost:3000
# MailHog at http://localhost:8025 (view sent emails)
```

**.env.local (for self-hosted dev):**

```bash
DOCUMENSO_API_KEY=api_local_xxxxxxxxxxxx
DOCUMENSO_BASE_URL=http://localhost:3000/api/v2
```

### Step 5: Quick Verification Script

```typescript
// scripts/verify-connection.ts
import { getClient } from "../src/documenso/client";

async function verify() {
  const client = getClient();
  try {
    const { documents } = await client.documents.findV0({ page: 1, perPage: 1 });
    console.log("Connection OK");
    console.log(`Documents accessible: ${documents.length >= 0 ? "yes" : "no"}`);
  } catch (err: any) {
    console.error(`Connection FAILED: ${err.message}`);
    if (err.statusCode === 401) console.error("Check DOCUMENSO_API_KEY");
    process.exit(1);
  }
}
verify();
```

### Step 6: Test Cleanup Script

```typescript
// scripts/cleanup-test-docs.ts
import { getClient } from "../src/documenso/client";

async function cleanup() {
  const client = getClient();
  const { documents } = await client.documents.findV0({ page: 1, perPage: 100 });

  const testDocs = documents.filter((d: any) =>
    d.title.startsWith("[TEST]") || d.title.startsWith("Hello World")
  );

  for (const doc of testDocs) {
    if (doc.status === "DRAFT") {
      await client.docume

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.