Documenso Upgrade MigrationSAFE

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-upgrade-migration
description: 'Manage Documenso API version upgrades and SDK migrations.

  Use when upgrading from v1 to v2 API, updating SDK versions,

  or migrating between Documenso versions.

  Trigger with phrases like "documenso upgrade", "documenso v2 migration",

  "update documenso SDK", "documenso API version".

  '
allowed-tools: Read, Write, Edit, Bash(npm:*)
version: 1.14.0
license: MIT
author: Jeremy Longshore <[email protected]>
tags:
- saas
- documenso
- api
- migration
compatibility: Designed for Claude Code
---
# Documenso Upgrade & Migration

## Output

- A versioned upgrade record with compatibility, access/audit checks, staged evidence, and a verified rollback revision.
- A paused/reversible release decision when any signing, authorization, or retention requirement regresses.

## Examples

Upgrade in a development workspace using synthetic documents and signers, test the previous and target versions for lifecycle, callback, access, and audit behavior, then stage a canary. Retain the prior release/configuration and roll back immediately if a control fails; do not validate upgrades by changing live signed documents.

## Current State

!`npm list @documenso/sdk-typescript 2>/dev/null || echo 'SDK not installed'`
!`npm list documenso-sdk-python 2>/dev/null || pip show documenso-sdk-python 2>/dev/null | head -3 || echo 'Python SDK not installed'`

## Overview

Guide for upgrading between Documenso API versions and SDK updates. Documenso has two API versions: **v1** (legacy, document-centric) and **v2** (recommended, envelope-based with multi-document support). The TypeScript and Python SDKs use the v2 API by default.

## Prerequisites

- Current Documenso integration working
- Test environment available
- Feature flag system (recommended for gradual rollout)

## API Version Comparison

| Feature | v1 (legacy) | v2 (recommended) |
|---------|-------------|-------------------|
| Base path | `/api/v1/` | `/api/v2/` |
| Document model | Documents | Envelopes (can contain multiple documents) |
| SDK support | REST only | TypeScript + Python SDK |
| Template API | `/templates/{id}/create-document` | Via envelope create |
| Authentication | `Authorization: Bearer` | `Authorization: Bearer` (same) |
| Status | Maintained, not deprecated | Actively developed |

## Instructions

### Step 1: Upgrade SDK to Latest

```bash
# Check current version
npm list @documenso/sdk-typescript

# Upgrade
npm install @documenso/sdk-typescript@latest

# Check for breaking changes
npm info @documenso/sdk-typescript changelog

# Python
pip install --upgrade documenso-sdk-python
```

### Step 2: v1 REST to v2 SDK Migration

```typescript
// BEFORE: v1 REST API
const BASE = "https://app.documenso.com/api/v1";
const headers = { Authorization: `Bearer ${process.env.DOCUMENSO_API_KEY}` };

// Create document
const res = await fetch(`${BASE}/documents`, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({ title: "Contract" }),
});
const doc = await res.json();

// List documents
const listRes = await fetch(`${BASE}/documents?page=1&perPage=20`, { headers });
const { documents } = await listRes.json();

// AFTER: v2 SDK
import { Documenso } from "@documenso/sdk-typescript";
const client = new Documenso({ apiKey: process.env.DOCUMENSO_API_KEY! });

// Create document
const doc = await client.documents.createV0({ title: "Contract" });

// List documents
const { documents } = await client.documents.findV0({ page: 1, perPage: 20 });
```

### Step 3: Gradual Migration with Feature Flags

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

const USE_V2 = process.env.DOCUMENSO_USE_V2 === "true";

export async function createDocument(title: string) {
  if (USE_V2) {
    const client = new Documenso({ apiKey: process.env.DOCUMENSO_API_KEY! });
    return client.documents.createV0({ title });
  }

  // Legacy v1
  const res = await fetch("https://app.documenso.com/api/v1/documents", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.DOCUMENSO_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ title }),
  });
  return res.json();
}

// Enable gradually:
// 1. DOCUMENSO_USE_V2=true in staging → test
// 2. DOCUMENSO_USE_V2=true for 10% of production traffic
// 3. Monitor error rates
// 4. Roll to 100%
// 5. Remove v1 code
```

### Step 4: Self-Hosted Version Upgrade

```bash
# Self-hosted Documenso upgrades are simple:
# 1. Pull new image
docker pull documenso/documenso:latest

# 2. Restart container (migrations run automatically on start)
docker compose -f docker-compose.prod.yml up -d documenso

# 3. Verify
docker logs documenso --tail 20 | grep "prisma migrate"
curl -s https://sign.yourcompany.com/api/health

# Rollback if needed:
docker compose -f docker-compose.prod.yml down documenso
docker pull documenso/documenso:previous-tag
docker compose -f docker-compose.prod.yml up -d documenso
```

### Step 5: Migration Testing

```typescript
// tests/migration/v1-v2-parity.test.ts
import { describe, it, expect } from "vitest";

describe("v1/v2 API Parity", () => {
  it("creates documents with same result shape", async () => {
    // Create via v1
    const v1Doc = await createDocumentV1("Parity Test");
    // Create via v2
    const v2Doc = await createDocumentV2("Parity Test");

    // Verify same essential fields
    expect(v1Doc.title).toBe(v2Doc.title);
    expect(typeof v1Doc.id).toBe("number");
    expect(typeof v2Doc.documentId).toBe("number");
  });

  it("lists documents consistently", async () => {
    const v1List = await listDocumentsV1();
    const v2List = await listDocumentsV2();

    // Same documents visible via both APIs
    expect(v1List.length).toBe(v2List.length);
  });
});
```

## Migration Checklist

- [ ] Current SDK version documented
- [ ] Changelog reviewed for breaking changes
- [ ] Feature branch c

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.