documenso-upgrade-migration

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".

Zur Installation springen

Repository: jeremylongshore/tons-of-skills-marketplace
Letzte Quellaktivität: 19. August 2026 um 12:13
Erkannte Sprache von SKILL.md: Englisch
Sterne: 2.677
Forks: 392

Installationsoptionen

Standardmäßig ist der Prompt ausgewählt, der zuerst die Quelle prüft. Sie können zu einem direkten Befehl wechseln oder eine lokale Kopie herunterladen.

Quelldateien prüfen

Lesen Sie SKILL.md und alle von SkillsMP angezeigten Begleitdateien, bevor Sie sich für eine Installation entscheiden.

Zurück zur Suche Zurück zur Installation

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.13.0
license	MIT
author	Jeremy Longshore <jeremy@intentsolutions.io>
tags	["saas","documenso","api","migration"]
compatibility	Designed for Claude Code

Documenso Upgrade & Migration

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

# 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

// BEFORE: v1 REST API
const BASE = "https://app.documenso.com/api/v1";
const headers = { :  };


 res =  (, {
  : ,
  : { ...headers, :  },
  : .({ :  }),
});
 doc =  res.();


 listRes =  (, { headers });
 { documents } =  listRes.();


 {  }  ;
 client =  ({ : process..! });


 doc =  client..({ :  });


 { documents } =  client..({ : , :  });

// 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

# 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

// 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);
  });
});

Issue	Cause	Solution
ID format mismatch	v1 returns `id`, v2 returns `documentId`	Use adapter/mapping layer
Missing field	API change in new version	Update to new field names
Enum case sensitivity	v2 SDK uses uppercase enums	Use `"SIGNER"` not `"signer"`
Template API difference	v1 templates vs v2 envelopes	Check API version for template operations